comfyui-mcp 0.52.3 → 0.52.4

package/dist/orchestrator/panel-tools.js

@@ -34,12 +34,17 @@ import { fileURLToPath } from "node:url";
 import { comfyuiFetch } from "../comfyui/fetch.js";
 import { assertPanelNotTargetedUnverifiable } from "../services/panel-pin-guard.js";
 import { nodesInstallCommandArgs } from "../services/node-management.js";
+import { searchPanelNodes } from "../services/manager-node-search.js";
 import { isPanelAnsweredError } from "../services/panel-answered.js";
 import { isPreExecutorRefusal } from "../services/panel-refusal.js";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { parse as parseYaml } from "yaml";
+import { SEMVER_RE } from "../services/ui-bridge.js";
+import { compareSemver } from "../services/self-update.js";
+import { primePanelBase, verifiedPanelDiskVersion, } from "../services/panel-workspace.js";
 import { conversationOfScopeAddress, isScopeAddress, shortTabId } from "../services/session-scope.js";
 import { NODE_ID_MESSAGE, NODE_ID_PATTERN, normalizeNodeId } from "./node-id.js";
+import { parseContradictoryPromotedWidgetRefusal, resolveInnerPromotedTarget, } from "./promoted-widget.js";
 import { clearSwitchHold, describeSwitchHold, recordSwitchHold, successProvesSwitchCleared, } from "./switch-hold.js";
 import { NO_ORIGIN_REMEDY } from "./fence-refusal.js";
 /** #884 — journal TICKETS (run completions #468, ask answers #486) must be
@@ -80,7 +85,7 @@ import { getNsfwConsent, setNsfwConsent } from "../services/panel-settings.js";
 import { QueueMonitor } from "../services/queue-monitor.js";
 import { RunCompletions } from "./run-completion-journal.js";
 import { AskAnswers, askFingerprint, PANEL_ASK_ID_PREFIX, } from "./ask-answer-journal.js";
-import { getObjectInfo, backfillObjectInfo, resetClient, resetObjectInfoCache, } from "../comfyui/client.js";
+import { getObjectInfo, backfillObjectInfo, getQueueVerified, resetClient, resetObjectInfoCache, } from "../comfyui/client.js";
 import { convertUiToApi, collectNodeTypes } from "../services/workflow-converter.js";
 import { restartComfyUI, preflightLocalRestart, readServingArgv, describeArgvDrift, 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";
@@ -159,6 +164,14 @@ function fail(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
 }
+/** A refusal that also carries {@link FenceRepairDiagnosis}. The text is unchanged by
+ *  this wrapper: the field is ADDITIVE, so a client that ignores structuredContent
+ *  reads exactly what it read before. */
+function failWithFenceDiagnosis(text, diagnosis) {
+    const res = fail(text);
+    res.structuredContent = { panel_fence: diagnosis };
+    return res;
+}
 /**
  * #971 — the AMBIGUOUS-rebind refusal, worded so it can be acted on.
  *
@@ -630,6 +643,43 @@ function sleep(ms) {
 // is not mistaken for a dead tab — still capped (never Infinity) so a genuinely
 // frozen/backgrounded tab fails in bounded time instead of hanging forever.
 const OBJECT_INFO_REFRESH_ACK_TIMEOUT_MS = 30_000;
+// #1639 — while a ComfyUI prompt is running the frontend main thread often
+// cannot service graph_* at all (reads included). Waiting out the 20/30 s ack
+// bound only surfaces "tab may be backgrounded or frozen" with an unknown
+// mutation outcome. Fail closed BEFORE dispatch for canvas-touching graph
+// commands so the agent gets an explicit QUEUE BUSY instead. `graph_run` is
+// excluded: queuing behind an in-flight job is the documented sweep path, and
+// panel_run already has its own duplicate fence.
+function queueBusySnapshotNote() {
+    const snap = QueueMonitor.snapshot();
+    if (!snap.running)
+        return "";
+    const prompt = snap.runningPromptId ? ` (running prompt ${snap.runningPromptId}` : "";
+    const node = snap.currentNode ? `, currently at node ${snap.currentNode}` : "";
+    const close = snap.runningPromptId ? ")" : "";
+    return `${prompt}${node}${close}`;
+}
+function graphCmdBlockedByRunningPrompt(cmd) {
+    const name = typeof cmd.cmd === "string" ? cmd.cmd : "";
+    if (!name.startsWith("graph_") || name === "graph_run")
+        return null;
+    const snap = QueueMonitor.snapshot();
+    if (!snap.running)
+        return null;
+    return (`${name} was NOT sent — nothing was applied. QUEUE BUSY: a ComfyUI prompt is running` +
+        `${queueBusySnapshotNote()}. The panel tab typically cannot answer graph_* commands ` +
+        `(including read-only graph_query / graph_outline) while a prompt is executing — ` +
+        `waiting out the ack timeout would only surface a generic "tab may be backgrounded ` +
+        `or frozen" with an unknown outcome. Retry after queue (action:"list") shows running: 0.`);
+}
+function queueBusyTimeoutNote() {
+    if (!QueueMonitor.snapshot().running)
+        return "";
+    return (`\n\nQUEUE BUSY: a ComfyUI prompt is still running${queueBusySnapshotNote()}. ` +
+        `The panel tab typically cannot answer graph_* (including read-only queries) while a ` +
+        `prompt is executing — this is not a backgrounded or frozen tab. Retry after queue ` +
+        `(action:"list") shows running: 0.`);
+}
 const RETRY_SAFE_CMDS = new Set([
     // Idempotent reads (mirror UiBridge.READONLY_CMDS + list/status probes).
     "graph_serialize",
@@ -712,6 +762,26 @@ function isMutatingGraphCmd(cmd) {
     const name = typeof cmd.cmd === "string" ? cmd.cmd : "";
     return MUTATING_GRAPH_EDIT_CMDS.has(name);
 }
+/**
+ * #1519 — a graph command the panel FENCES that does not mutate the canvas.
+ *
+ * The panel's `activeWorkflowFenceApplies` fences every `graph_*` command, reads
+ * included, and exempts the recovery probe `workflow_list`
+ * (`commandIsCanvasTargetless`, panel #759). So "fenced, and not a mutation" is
+ * exactly the `graph_*` names that are not in MUTATING_GRAPH_EDIT_CMDS — derived
+ * from that one allowlist rather than kept as a second one, so a newly added edit
+ * command cannot drift into being classified as a read.
+ *
+ * The `graph_` prefix is load-bearing for a second reason: the diagnosis this
+ * gates runs `workflow_list`, which flows back through this same catch. Keying on
+ * the prefix keeps the probe OUT of the branch that launched it, so a panel that
+ * fences the probe too (a build predating the #759 exemption) surfaces its own
+ * refusal instead of recursing.
+ */
+function isFencedGraphRead(cmd) {
+    const name = typeof cmd.cmd === "string" ? cmd.cmd : "";
+    return name.startsWith("graph_") && !MUTATING_GRAPH_EDIT_CMDS.has(name);
+}
 /** True when an error is a TRANSIENT transport/reconnect drop (the tab went away
  *  or was replaced), NOT a genuine command error or a live-but-frozen reply
  *  timeout. Deliberately EXCLUDES "did not reply within N ms" (a backgrounded/
@@ -1547,6 +1617,49 @@ function captureRebootHealthBase(ctx) {
     // it carries) can therefore never cross to a different-family instance.
     return loopbackProbeUrl(base);
 }
+/**
+ * #1671 — the configured LOCAL boot instance, when that is a known loopback
+ * process this orchestrator can account for without a live panel tab.
+ *
+ * `captureRebootHealthBase` requires a live tab handshake. After a crash that
+ * takes the panel bridge offline that proof is gone — the tab is the component
+ * that disappeared. The configured boot URL is still known, and it is the same
+ * target `restart_comfyui` would act on. Returning it is NOT a claim that the
+ * vanished tab fronted this instance; callers must still refuse a proven
+ * mismatch (see offlineRestartHealthBase).
+ */
+function configuredBootRestartBase() {
+    if (isCloudMode() || isRemoteMode())
+        return null;
+    const bootBase = getBootLocalComfyUIBaseUrl();
+    if (!bootBase || !isLoopbackOrigin(bootBase))
+        return null;
+    const base = bootBase.replace(/\/+$/, "");
+    if (!sameHttpBase(getComfyUIBaseUrl(), base))
+        return null;
+    return loopbackProbeUrl(base);
+}
+/**
+ * #1671 — which base, if any, a panel-offline crash recovery may restart.
+ *
+ * Prefer a still-provable tab binding. If the tab is gone, fall back to the
+ * configured boot instance UNLESS the last-known handshake Origin proves the
+ * panel was on a DIFFERENT server (#851/#1593: never restart the wrong one).
+ */
+function offlineRestartHealthBase(ctx) {
+    const bound = captureRebootHealthBase(ctx);
+    if (bound != null && sameHttpBase(getComfyUIBaseUrl(), bound))
+        return bound;
+    const observed = ctx.bridge?.tabServerOrigin?.(ctx.tabId) ?? null;
+    const verdict = classifyRestartFallbackTarget({
+        headlessBase: getComfyUIBaseUrl(),
+        panelBase: bound,
+        observedOrigin: observed,
+    });
+    if (verdict.kind === "different")
+        return null;
+    return configuredBootRestartBase();
+}
 let healthProbeOverride = null;
 /** Test injection for the #742 refuse-safe restart preflight (the real one is
  *  preflightLocalRestart in process-control). null → the live preflight. */
@@ -3440,49 +3553,53 @@ export function readOpenActiveAgainstTarget(active, path, activeConfirmed) {
         (typeof a.key === "string" && a.key !== "");
     return identified ? "different" : "indeterminate";
 }
-/**
- * #887 — observe what is active after an open, WITHOUT adopting anything.
- *
- * Split out of `refreshOpenWorkflowUuid` because the two questions have different
- * preconditions. Adoption is gated on the open reply corroborating the requested
- * identity — a reply that cannot prove which workflow it opened must never
- * authorize a fence refresh. Pure observation needs none of that: "what does the
- * panel say is active right now" is answerable regardless of what the open replied,
- * and on the path that matters most the open reply is an ERROR carrying no JSON at
- * all. Requiring corroboration there is what kept the reporter's own case
- * unexamined.
- */
-/**
- * #1337 — CLEAR THE FENCE ON THE VERDICT THAT PROVED IDENTITY.
- *
- * A reporter's session lost the canvas permanently: every graph call refused with
- * `workflow instance mismatch`, and the one fence-EXEMPT recovery could not clear it.
- *
- * `workflow_open` re-derives the fence only on its success branch. The verdict
- *
- *   "workflow_open RAN and the canvas IS bound to X — that much was proven — but the
- *    graph on it does not match the state that was loaded … You are NOT on the wrong
- *    workflow: X IS the active one."
- *
- * is delivered as an ERROR, so control never reaches the re-derivation. That mismatches
- * two different levels: the verdict asserts IDENTITY was proven, and what it withholds
- * is CONTENT (frontend normalisation vs a partial load). Applying content-level
- * uncertainty to an identity-level fence is what leaves the session with no in-band
- * recovery — the only remaining move is a browser reload, which destroys unsaved work.
- *
- * MEASURED, because the comment that justified the old behaviour asserts otherwise:
- *   • the panel really does publish NO workflow_uuid on this reply (its own
- *     FENCE_NOT_REFRESHED text), so there is nothing to adopt FROM THE REPLY — true;
- *   • but `workflow_list` IS fence-exempt (commandIsCanvasTargetless in the panel's
- *     workflow-chat-identity.js), and the panel's own recovery text names
- *     panel_list_workflows as "exempt from the fence" and says it "republishes the
- *     active identity". So the fence CAN be re-derived here; nothing tried.
- *
- * This runs that exempt re-derivation and reports what it achieved. The open still
- * FAILS — the content warning is preserved verbatim, because "re-read before editing"
- * is still the right instruction — and nothing is adopted on the UNPROVEN verdict,
- * where identity itself is in doubt.
- */
+async function probeLiveGraphUnderCurrentFence(ctx) {
+    // `fields:"ids", limit:1` is the cheapest shape that still has to pass the
+    // instance fence — we only need whether the canvas STILL ACCEPTS this session's
+    // stamp, not the graph itself.
+    let res;
+    try {
+        res = await ctx.call({ cmd: "graph_query", fields: "ids", limit: 1 }, 8000);
+    }
+    catch (err) {
+        if (isWorkflowInstanceMismatch(err))
+            return { status: "mismatch_refused" };
+        return { status: "unanswered", detail: err instanceof Error ? err.message : String(err) };
+    }
+    if (!res?.isError)
+        return { status: "answered" };
+    const text = toolResultText(res);
+    if (isWorkflowInstanceMismatch(text))
+        return { status: "mismatch_refused" };
+    // An acked executor error still means the fence passed — the canvas is the
+    // one this session was already bound to.
+    if (isPanelAnsweredResult(res))
+        return { status: "answered" };
+    return { status: "unanswered", detail: text };
+}
+function identityClaimedContentUnverifiedNote(detail) {
+    const busy = queueBusyTimeoutNote();
+    return (`\n\nFENCE: NOT cleared (live graph unread). The panel asserted the canvas IS bound to the ` +
+        `requested workflow, but a live graph read did not come back (${detail || "no reason was reported"}), ` +
+        `so content is UNVERIFIED. Identity-matched is not content-matched: do NOT trust ` +
+        `"you are on the right workflow" / "You are NOT on the wrong workflow". Do NOT edit or save ` +
+        `expecting the opened file. Retry the graph read (panel_graph_outline) once the tab answers.` +
+        busy);
+}
+function identityClaimedButLiveGraphUnchangedNote(ctx) {
+    const fence = currentWorkflowFence(ctx);
+    const fenceTxt = fence.known && fence.uuid
+        ? `under this session's existing fence (${fence.uuid})`
+        : `without being refused by a workflow-instance fence`;
+    return (`\n\nFENCE: NOT cleared (live graph still answers). CONTENT MISMATCH: the panel asserted the ` +
+        `canvas IS bound to the requested workflow, but a live graph read still answers ${fenceTxt} — ` +
+        `the graph on screen is the PREVIOUS workflow, not the one just opened. That is the failure ` +
+        `the fence exists to prevent: clearing it here would let later reads of this graph succeed ` +
+        `as if they were the opened file. Do NOT trust "you are on the right workflow" / ` +
+        `"You are NOT on the wrong workflow". Do NOT edit or save expecting the opened file. ` +
+        `Read the graph (panel_graph_outline) to see what is actually open, then retry ` +
+        `panel_open_workflow or panel_load_workflow if the canvas did not switch.`);
+}
 async function clearFenceOnIdentityProvenOpen(ctx, res) {
     const text = toolResultText(res);
     // ONLY the class that states identity was proven. The UNPROVEN verdict ("could not
@@ -3490,6 +3607,13 @@ async function clearFenceOnIdentityProvenOpen(ctx, res) {
     // fence onto a canvas we cannot identify is how an edit lands on the wrong graph.
     if (!/the canvas IS bound to/i.test(text))
         return { res, repaired: false };
+    const canvas = await probeLiveGraphUnderCurrentFence(ctx);
+    if (canvas.status === "answered") {
+        return { res: appendToolResultText(res, identityClaimedButLiveGraphUnchangedNote(ctx)), repaired: false };
+    }
+    if (canvas.status === "unanswered") {
+        return { res: appendToolResultText(res, identityClaimedContentUnverifiedNote(canvas.detail)), repaired: false };
+    }
     let note;
     // #1560 — reported STRUCTURALLY, never re-read out of the sentence below. The caller
     // uses this to decide whether a "the channel is not answering" note would contradict
@@ -3838,7 +3962,8 @@ function corroborateActiveForFence(parsed) {
     // Same tri-state primitive the pin path uses. `false` = they name DIFFERENT
     // canvases (the stale/mixed case). `undefined` = they share no comparable
     // identity field, so agreement was never established — which is not agreement.
-    const verdict = identityVerdict(flaggedActive[0], active);
+    const flagged = flaggedActive[0];
+    const verdict = identityVerdict(flagged, active);
     if (verdict === false) {
         return {
             ok: false,
@@ -3849,6 +3974,20 @@ function corroborateActiveForFence(parsed) {
         };
     }
     if (verdict !== true) {
+        // #1650 — unsaved (`tmp:`) tabs never have path/filename. After a reconnect
+        // the top-level `active` record historically omitted `key`/`routing_key`
+        // whenever the panel had not yet established a workflow identity, while the
+        // unique flagged-active list entry still carried the per-tab `tmp:` handle
+        // from `workflowTabId()`. Those two records describe the same canvas; they
+        // just do not share a field that `identityVerdict` can pair. The reverse
+        // (handle on `active`, omitted on the list row) is the same gap.
+        //
+        // Restricted to BOTH sides being unsaved and exactly one flagged-active
+        // (already checked above). A saved path on either side is a different
+        // canvas, not a missing field.
+        if (unsavedTmpHandleCorroborates(flagged, active)) {
+            return { ok: true, active: fenceRecordForAdoption(flagged, active) };
+        }
         return {
             ok: false,
             seenUuid,
@@ -3858,7 +3997,7 @@ function corroborateActiveForFence(parsed) {
             settles: false,
         };
     }
-    return { ok: true, active: active };
+    return { ok: true, active: fenceRecordForAdoption(flagged, active) };
 }
 /**
  * Re-derive this session's command fence from the panel's live active canvas.
@@ -3939,6 +4078,46 @@ WORTH CHECKING — THE PANEL'S VERSION IS UNKNOWN HERE: this session's panel has
         }
         if (!v?.tooOld)
             return "";
+        // #1229 — IS THE INSTALL EVEN BEHIND, OR ONLY WHAT COMFYUI IS SERVING?
+        //
+        // This branch compares the RUNNING panel against the minimum and concludes
+        // "pack is out of date" — but the reporter's pack on disk was 0.14.37 while
+        // the session ran 0.11.38: ComfyUI-Manager had updated the pack IN PLACE
+        // after ComfyUI started, and ComfyUI keeps serving the web assets it
+        // registered at startup. Prescribing `sync` there is a no-op remedy — the
+        // disk already clears the floor — and it cost the reporter a full
+        // pack-version investigation to discover that. The actual fix is a RESTART
+        // plus a hard-refresh, and a hard-refresh ALONE provably does not work,
+        // because the new assets are registered server-side at startup, not re-read
+        // from disk on reload.
+        //
+        // Same proof discipline as resolveStaleBundleSkew (#774): only a disk
+        // version re-read NOW from the observed install dir may override the update
+        // advice. Anything unproven — no observation, an unparseable version, or a
+        // disk version genuinely below the floor — falls through to the sync remedy
+        // unchanged, which is correct for a pack that really is behind.
+        const disk = verifiedPanelDiskVersion()?.trim();
+        if (!disk) {
+            // The observation is missing or stale (most often the live-base
+            // resolution lapsed and this refusal is the first thing to ask in a
+            // while). Refresh it in the background — never awaited, since building
+            // an error message must not block on I/O — so a retry can answer.
+            void primePanelBase().catch(() => { });
+        }
+        if (disk && SEMVER_RE.test(disk) && compareSemver(disk, v.needed) >= 0) {
+            return (`
+
+WHY THIS READ WAS NEEDED AT ALL: this session's RUNNING panel is ${v.version}, ` +
+                `and a panel only reports the new workflow's identity ON THE REPLY from ` +
+                `${v.needed} onwards — but DO NOT SYNC THE PANEL: the pack ON DISK is ` +
+                `${disk}, which already meets ${v.needed}, so a sync would change nothing. ` +
+                `What is stale is what ComfyUI is SERVING: the pack was updated after ` +
+                `ComfyUI started, and ComfyUI keeps serving the web assets it registered ` +
+                `at startup. Restart ComfyUI so it serves ${disk}, then HARD-REFRESH the ` +
+                `browser tab (Ctrl+Shift+R) — a hard refresh ALONE does not fix this, ` +
+                `because the assets are registered server-side at startup, not re-read ` +
+                `from disk on reload.`);
+        }
         return (`
 
 WHY THIS READ WAS NEEDED AT ALL: this session's panel is ${v.version}, and a ` +
@@ -5052,11 +5231,67 @@ function computeIsActive(rec, activeObj) {
     return identityVerdict(rec, activeObj);
 }
 /**
- * Stable-identity (key/path/routing_key) verdict between a record and the active object.
- * Returns `true` on a positive match, `false` only when the two expose a COMPARABLE field
- * (both non-empty) that DISAGREES, and `undefined` when they share no comparable field at
- * all (so the caller cannot conclude "background" — stay lenient). Filename is never used
- * (it collides across tabs).
+ * Per-tab unsaved handle (`tmp:<id>`). Unsaved tabs have no path/filename; this
+ * is the only unique identity they publish. Accepts any non-empty `tmp:` token
+ * (not only RFC-uuid suffixes) so a panel that mints a shorter handle still
+ * corroborates — `canonicalUnsavedWorkflowIdentity` stays strict for OPEN,
+ * which is a caller-supplied selector.
+ */
+function recordTmpHandle(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const rec = value;
+    for (const v of [rec.routing_key, rec.key]) {
+        if (typeof v === "string" && /^tmp:\S+$/.test(v))
+            return v;
+    }
+    return null;
+}
+/** Canonical saved path, or null when the record is unsaved / has no path. */
+function recordSavedPath(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    return canonicalSavedWorkflowPath(value.path);
+}
+/**
+ * #1650 — the unique flagged-active list entry and the top-level `active`
+ * record describe the same UNSAVED canvas even when they do not share a
+ * pairable field. True only when BOTH sides lack a saved path and at least
+ * one carries a `tmp:` handle. A saved path on either side is a different
+ * canvas (or a mixed reply), not a missing field.
+ */
+function unsavedTmpHandleCorroborates(listRec, activeObj) {
+    if (recordSavedPath(listRec) || recordSavedPath(activeObj))
+        return false;
+    if (!(recordTmpHandle(listRec) || recordTmpHandle(activeObj)))
+        return false;
+    const listUuid = responseWorkflowUuid(listRec);
+    const activeUuid = responseWorkflowUuid(activeObj);
+    // Two published uuids that disagree are a mixed reply, not a missing field.
+    if (listUuid && activeUuid && listUuid !== activeUuid)
+        return false;
+    return true;
+}
+/**
+ * Record to adopt a fence uuid from. Prefer the top-level `active` object
+ * (it is the one that historically carries `workflow_uuid`); fall back to
+ * the flagged list row when only that row published one.
+ */
+function fenceRecordForAdoption(listRec, activeObj) {
+    const active = activeObj;
+    if (responseWorkflowUuid(active))
+        return active;
+    const list = listRec;
+    if (responseWorkflowUuid(list))
+        return list;
+    return active;
+}
+/**
+ * Stable-identity (key/path/routing_key/tmp: handle) verdict between a record and the
+ * active object. Returns `true` on a positive match, `false` only when the two expose a
+ * COMPARABLE field (both non-empty) that DISAGREES, and `undefined` when they share no
+ * comparable field at all (so the caller cannot conclude "background" — stay lenient).
+ * Filename is never used (it collides across tabs).
  */
 function identityVerdict(rec, activeObj) {
     if (!activeObj || typeof activeObj !== "object")
@@ -5070,6 +5305,12 @@ function identityVerdict(rec, activeObj) {
         [r.routing_key, a.routing_key],
         [r.key, a.routing_key],
         [r.routing_key, a.key],
+        // #1650 — a tmp: handle is a per-tab identity, not a saved path. Pair it
+        // the same way key↔routing_key is paired so an unsaved canvas is not
+        // treated as "no comparable field" when one side published `key` and the
+        // other published `routing_key` (or vice versa).
+        [recordTmpHandle(r), recordTmpHandle(a)],
+        [r.workflow_uuid, a.workflow_uuid],
     ];
     // A CONTRADICTION OUTRANKS AN AGREEMENT (codex gate P0). Returning `true` on
     // the first equal pair meant a mixed reply — matching `key`, conflicting
@@ -5100,6 +5341,12 @@ function identityVerdict(rec, activeObj) {
         [r.key, a.key, (v) => (nonEmpty(v) ? v : null)],
         [r.path, a.path, canonicalSavedWorkflowPath],
         [r.routing_key, a.routing_key, canonicalSavedWorkflowRoutingIdentity],
+        [recordTmpHandle(r), recordTmpHandle(a), (v) => (nonEmpty(v) ? v : null)],
+        [
+            r.workflow_uuid,
+            a.workflow_uuid,
+            (v) => (typeof v === "string" && WORKFLOW_UUID_RE.test(v) ? v : null),
+        ],
     ];
     for (const [x, y, canon] of sameField) {
         if (!nonEmpty(x) || !nonEmpty(y))
@@ -6156,6 +6403,12 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
                 await awaitReachable();
             }
             ensureReachable();
+            // #1639 — a running prompt freezes the tab's graph_* channel. Refuse
+            // BEFORE dispatch so a mutation is known-not-applied rather than
+            // delivered-into-a-frozen-tab with a 20/30s unknown-outcome timeout.
+            const blocked = graphCmdBlockedByRunningPrompt(cmd);
+            if (blocked)
+                return fail(blocked);
             const firstTry = ok(await sendRouted(cmd, timeoutMs, observeRid));
             // panel#1097 — a guard-domain command that SUCCEEDS is the evidence that the
             // switch is over, whichever attempt lands it. Without this an ordinary
@@ -6255,7 +6508,7 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
                     // Leaving it unmarked fails closed (nothing is settled, no false success)
                     // but silently switches the settle off for a real sequence, which is the
                     // kind of gap that reads as "the fix does not work" much later.
-                    return carryReplyTimeoutMark(err2, fail(err2));
+                    return carryReplyTimeoutMark(err2, fail(`${err2 instanceof Error ? err2.message : String(err2)}${queueBusyTimeoutNote()}`));
                 }
             }
             // #442 defect 4: a MUTATING command (deliberately excluded from RETRY_SAFE_CMDS)
@@ -6299,35 +6552,198 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
             // The bridge cannot tell them apart — from its side both are "no identity". The
             // orchestrator can, with the same read-only re-derivation the documented recovery
             // performs. So it is measured, once, and the answer names the remedy that fits.
+            // panel#1339 — `refreshed` AND `already_current` ARE NOT THE SAME ANSWER.
+            //
+            // The branch below used to return ONE sentence for both: "the live canvas DOES
+            // carry an identity (<uuid>) and this session's fence has been re-derived onto
+            // it. RETRY THIS EXACT CALL ONCE". The reporter read that as a contradiction —
+            // told the identity had *already* been re-derived, yet refused anyway — and the
+            // two states it covers want opposite next moves:
+            //
+            //   refreshed        the tab had NO fence and THIS CALL installed one, derived
+            //                    from the live canvas. The refusal you are holding is the
+            //                    repair. A bare retry is the right move and works because
+            //                    of it — which is why it looked "transient": the first call
+            //                    did the work and reported failure.
+            //   already_current  the fence read back as ALREADY PRESENT AND EQUAL. It cannot
+            //                    have been that at dispatch — the refusal is proof the stamp
+            //                    was empty, and currentWorkflowFence reads the same resolver
+            //                    the bridge consulted — so a fence appeared between the two
+            //                    reads, and NOT because of this call: `already_current`
+            //                    returns BEFORE any adoption. Two things produce it and this
+            //                    code cannot tell them apart, which is why it asserts
+            //                    neither: the session was moved onto a DIFFERENT tab while
+            //                    the check ran (rebindWorkflowFence's workflow_list round
+            //                    trip is retry-safe, its retry runs ensureReachable, and
+            //                    `before` is then re-read for the new tab), or a fence for
+            //                    THIS tab was installed in that window by something else (a
+            //                    concurrent rebind, or the panel's own mismatch re-hello,
+            //                    #1043/#932). Either way NOTHING WAS REPAIRED for the caller
+            //                    and the uuid quoted may not be the one they were refused
+            //                    against — so the remedy is to confirm the target, not to
+            //                    name a mechanism nobody measured.
+            //
+            // Splitting the sentence is half the fix. The other half is that the answer must
+            // be readable WITHOUT parsing the sentence: an agent deciding to re-run a
+            // mutation off matched error prose is how a write gets double-applied. See
+            // FenceRepairDiagnosis — the verdict, and the bridge-owned dispatch flag the
+            // "nothing was applied" claim rests on, ride in structuredContent.
+            //
+            // What does NOT change: every branch still REFUSES. The call really did not
+            // perform the widget write — it performed the repair — and a refusal that
+            // repairs and REPORTS is a different risk from one that repairs and PROCEEDS
+            // (#1646 removed exactly that from the neighbouring branch). Nothing here
+            // auto-continues the mutation.
             if (isNoTrustedIdentityRefusal(err) && isMutatingGraphCmd(cmd)) {
                 const raw = err instanceof Error ? err.message : String(err);
+                // The TYPED flag, not the text predicate above: `isNoTrustedIdentityRefusal`
+                // is a phrase match and would fire on anything that merely quotes the phrase.
+                // Only the bridge can say whether the frame reached the socket.
+                const dispatchFlag = dispatchOutcomeOf(err);
+                const dispatched = dispatchFlag === false ? "no" : dispatchFlag === true ? "yes" : "unknown";
+                const retrySafe = dispatched === "no" ? "yes" : dispatched === "yes" ? "no" : "unknown";
+                // THREE-WAY, because the flag is three-way. A two-way ternary here printed
+                // "this refusal carries no dispatch flag" for a refusal whose flag was
+                // present and said `true` — the same collapse this whole branch exists to
+                // remove, reintroduced one level up (review of this PR). Each arm states the
+                // observation it actually has.
+                const nothingApplied = dispatched === "no"
+                    ? ` Nothing was applied (the bridge reports this frame was never written to the ` +
+                        `socket), so re-issuing cannot double-apply.`
+                    : dispatched === "yes"
+                        ? ` CAUTION — the bridge reports this frame WAS written to the socket, so the ` +
+                            `mutation may ALREADY have been applied. Do not re-issue it blindly; establish ` +
+                            `what landed first (read the node back with panel_query_graph).`
+                        : ` Whether anything was applied is NOT established here — this refusal carries no ` +
+                            `dispatch flag — so do not re-issue on the strength of this message alone.`;
+                // A retry may only be ORDERED when the bridge proved nothing was written.
+                // Otherwise the instruction contradicts `retry_safe`, which is exactly what a
+                // caller keys on: "RETRY THIS EXACT CALL ONCE" beside `retry_safe:"no"` is a
+                // self-contradictory verdict, and the prose is the half an agent obeys.
+                const mayOrderRetry = dispatched === "no";
+                const retryOrder = mayOrderRetry
+                    ? `RETRY THIS EXACT CALL ONCE.`
+                    : `The fence is repaired, so the same call should now pass it — but re-issue only ` +
+                        `after settling the question below.`;
+                // …and the machine-readable step follows the same rule.
+                const retryAction = (fallback) => mayOrderRetry ? fallback : "verify_applied_then_decide";
+                const tabBefore = ctx.tabId;
                 try {
                     const rebind = await rebindWorkflowFence(ctx);
+                    // WHAT WAS THERE BEFORE, reported as the tri-state it is rather than folded
+                    // into an absence. `refreshed` is returned for every `before` that is not a
+                    // known-equal fence, which is THREE different priors: definitively none, a
+                    // read that FAILED, and a fence naming a DIFFERENT workflow that was then
+                    // replaced. FenceRead's own contract forbids collapsing the second into the
+                    // first ("an absence nobody observed"), and a first draft of this message did
+                    // exactly that by saying "this session had NO fence for it" on all three.
+                    const priorFence = !rebind.before.known
+                        ? "unreadable"
+                        : rebind.before.uuid
+                            ? "present"
+                            : "absent";
+                    const base = {
+                        dispatched,
+                        retry_safe: retrySafe,
+                        rebind_status: rebind.status,
+                        prior_fence: priorFence,
+                        ...(rebind.before.known && rebind.before.uuid
+                            ? { prior_fence_uuid: rebind.before.uuid }
+                            : {}),
+                        tab_before: tabBefore,
+                        tab_after: ctx.tabId,
+                    };
                     if (rebind.status === "no_identity") {
-                        return fail(`${raw}\n\nCHECKED, so this is not a guess: the live canvas was re-read and it ` +
+                        return failWithFenceDiagnosis(`${raw}\n\nCHECKED, so this is not a guess: the live canvas was re-read and it ` +
                             `carries no workflow identity either (${rebind.why}). ` +
                             `panel_set_workflow_target({mode:"current"}) will NOT clear this — it chooses ` +
                             `WHICH workflow to fence against and cannot mint an identity for one that has ` +
                             `none, so it reports success while every mutation keeps failing. RECOVERY: ` +
                             `panel_open_workflow(<path>) on this same workflow; re-opening it is what gives ` +
                             `it an identity. If it has never been saved there is no path to re-open — save ` +
-                            `it first with panel_save_workflow, which also gives it a stable identity.`);
+                            `it first with panel_save_workflow, which also gives it a stable identity.`, {
+                            ...base,
+                            fence_repaired_by_this_call: "no",
+                            retry_clears_refusal: "no",
+                            next_action: "open_or_save_workflow",
+                        });
                     }
-                    if (rebind.status === "refreshed" || rebind.status === "already_current") {
-                        return fail(`${raw}\n\nCHECKED: the live canvas DOES carry an identity (${rebind.uuid}) and ` +
-                            `this session's fence has been re-derived onto it. RETRY THIS EXACT CALL ONCE — ` +
-                            `nothing was applied, so a retry cannot double-apply.`);
+                    if (rebind.status === "refreshed") {
+                        // Only what was OBSERVED about the prior fence. Each arm is a different
+                        // fact with a different implication, and "no fence" is true for exactly
+                        // one of them.
+                        const wasBefore = priorFence === "absent"
+                            ? `this session had NO fence for it`
+                            : priorFence === "present"
+                                ? `this session's fence named a DIFFERENT workflow (${rebind.before.known ? rebind.before.uuid : ""}), which has been REPLACED`
+                                : `this session's prior fence could not be read, so whether there was one is ` +
+                                    `not claimed here`;
+                        return failWithFenceDiagnosis(`${raw}\n\nCHECKED: the live canvas DOES carry an identity (${rebind.uuid}), ` +
+                            `${wasBefore}, and THIS CALL installed one derived from that canvas — the ` +
+                            `refusal you are reading is what repaired it, which is why the same call ` +
+                            `refused now and passes the fence next. ${retryOrder}${nothingApplied}`, {
+                            ...base,
+                            workflow_uuid: rebind.uuid,
+                            fence_repaired_by_this_call: "yes",
+                            retry_clears_refusal: "yes",
+                            next_action: retryAction("retry_same_call"),
+                        });
+                    }
+                    if (rebind.status === "already_current") {
+                        return failWithFenceDiagnosis(`${raw}\n\nCHECKED, and THIS CALL REPAIRED NOTHING: the re-read found a fence that ` +
+                            `was ALREADY present and already named the live canvas (${rebind.uuid}). That ` +
+                            `cannot be the fence your command was refused against — the refusal is proof ` +
+                            `that one was missing — so a fence appeared between the two reads, and not ` +
+                            `through this call. It is EITHER a fence for a different tab this session was ` +
+                            `moved onto while the check ran, OR one installed for this tab by something ` +
+                            `else in that window; nothing here can tell which, so ${rebind.uuid} is not ` +
+                            `claimed to be the identity you asked for. CONFIRM THE TARGET BEFORE RETRYING: ` +
+                            `panel_set_workflow_target({mode:"current"}) if you mean the canvas that is live ` +
+                            `now, or panel_open_workflow(<path>) for the workflow you actually meant; then ` +
+                            `re-issue.${nothingApplied} A bare retry is not refused by this message — it is ` +
+                            `simply not aimed at anything this check verified.`, {
+                            ...base,
+                            workflow_uuid: rebind.uuid,
+                            fence_repaired_by_this_call: "no",
+                            // NOT "yes". A retry would carry the fence this read saw, but nothing
+                            // here establishes that it belongs to the tab the caller addressed.
+                            retry_clears_refusal: "unknown",
+                            next_action: retryAction("confirm_target_then_retry"),
+                        });
                     }
                     // unreadable / uncorroborated — say so rather than picking a remedy.
-                    return fail(`${raw}\n\nCHECKED, and the answer is UNKNOWN: the live canvas could not be re-read ` +
+                    return failWithFenceDiagnosis(`${raw}\n\nCHECKED, and the answer is UNKNOWN: the live canvas could not be re-read ` +
                         `well enough to say whether it has an identity. Try ` +
                         `panel_open_workflow(<path>) on the workflow you mean — it is the only recovery ` +
                         `that works in BOTH states, because it gives the workflow an identity rather than ` +
-                        `adopting one that may not exist.`);
+                        `adopting one that may not exist.`, {
+                        ...base,
+                        ...(("uuid" in rebind) ? { workflow_uuid: rebind.uuid } : {}),
+                        // `adopt_error` is the one status that cannot say which side of the write
+                        // it threw on, so it is the one that may not claim "nothing was repaired".
+                        fence_repaired_by_this_call: rebind.status === "adopt_error" ? "unknown" : "no",
+                        retry_clears_refusal: "unknown",
+                        next_action: "open_workflow",
+                    });
                 }
                 catch {
-                    // The diagnosis must never change how the call failed.
-                    return fail(raw);
+                    // The diagnosis must never change how the call failed — so the TEXT is the
+                    // bare cause, exactly as before. The field is still emitted, saying unknown:
+                    // a caller that has to distinguish "no field" from "field says unknown" is
+                    // back to inferring, which is the defect this fix is about.
+                    return failWithFenceDiagnosis(raw, {
+                        dispatched,
+                        retry_safe: retrySafe,
+                        rebind_status: "check_threw",
+                        // The check threw, so it never reported a `before` — that is not an
+                        // absence, it is an unmade observation.
+                        prior_fence: "unreadable",
+                        tab_before: tabBefore,
+                        tab_after: ctx.tabId,
+                        fence_repaired_by_this_call: "unknown",
+                        retry_clears_refusal: "unknown",
+                        next_action: "unknown",
+                    });
                 }
             }
             // #1330 — CORROBORATE A FENCE MISMATCH INSTEAD OF LETTING IT REPEAT.
@@ -6409,6 +6825,165 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
                 }
                 return fail(`${name} was NOT applied — nothing changed. ${raw}${verdict}`);
             }
+            // #1519 — THE SAME REFUSAL ON A READ, AND AN ABSENT STAMP IS NOT A WRONG ONE.
+            //
+            // The reporter's session resumed onto a different workflow and the very first
+            // live-canvas read came back
+            //
+            //   workflow instance mismatch: this command carries no workflow-instance
+            //   stamp, and the active canvas reports 2b3f4684-…. Nothing was applied.
+            //
+            // Measured on current main before this branch existed: the panel's refusal IS
+            // the entire tool result. The corroboration above is gated on
+            // `isMutatingGraphCmd`, so a READ refused by the very same fence fell through
+            // every branch here and this side added nothing at all. #1480's guard already
+            // extends its diagnosis to reads "on purpose: `panel_graph_outline` refusing
+            // was half of the reported dead end"; this is the same reasoning for the stamp
+            // fence.
+            //
+            // What the panel says on its own is NOT nothing, and the difference is the
+            // point. Since panel 0.11.83 its refusal ends "Re-target with
+            // panel_set_workflow_target({mode:"current"}), or re-select the intended
+            // workflow with panel_open_workflow, then retry" — both exits, offered as
+            // interchangeable, with nothing said about which one this refusal calls for.
+            // That is right for the panel, which by design "observed only that the two
+            // identities differ" and refuses to infer a cause; it is not enough for the
+            // caller, and in the #1331 state the first of the two cannot work at all — it
+            // reports success while the read keeps failing. Only this side can take the
+            // read that decides, so this side takes it.
+            //
+            // TWO REFUSALS, NOT ONE. `isWorkflowInstanceMismatch` matches both of the
+            // panel's states, and they are different facts with OPPOSITE remedies:
+            //
+            //   "carries no workflow-instance stamp"  → this session has NO workflow
+            //       identity. Nothing was compared; the command was refused for arriving
+            //       bare. Deriving a fence from the live canvas is what fixes it.
+            //   "issued for workflow instance <uuid>" → this session HAS an identity and
+            //       the canvas disagrees with it. Deriving a fence from the live canvas
+            //       ABANDONS the workflow the caller named — the right move only if that
+            //       is what they meant.
+            //
+            // Collapsing them would hand the second case the first case's remedy, which is
+            // the retarget #1646 removed for cause. So the shape is read from the panel's
+            // own words and, when it matches NEITHER wording, the answer is UNKNOWN and is
+            // said to be — never guessed into one of the two.
+            //
+            // Read from the REFUSAL, never from `cmd.workflow_uuid`: the stamp is applied
+            // downstream of here, so that field is undefined at this point for BOTH states
+            // (the trap that silently disabled #1330's transient branch one block up).
+            //
+            // NOTHING IS ADOPTED. The probe is the same read-only one (`adopt:false`), so
+            // this reports which state it found and the fence moves only on an explicit
+            // rebind. The refusal itself is preserved verbatim and the call still fails.
+            if (isWorkflowInstanceMismatch(err) && isFencedGraphRead(cmd)) {
+                const name = typeof cmd.cmd === "string" ? cmd.cmd : "panel command";
+                const raw = err instanceof Error ? err.message : String(err);
+                const stamped = /issued for workflow instance ([0-9a-f-]{36})/i.exec(raw)?.[1] ?? null;
+                const unstamped = /carries no workflow-instance stamp/i.test(raw);
+                // Three-valued on purpose. A panel whose wording matches neither is not
+                // evidence for either state, and this branch must not manufacture one.
+                const shape = unstamped
+                    ? "unstamped"
+                    : stamped
+                        ? "stamped"
+                        : "unstated";
+                // Naming `mode:"current"` to a PINNED session is naming something that also
+                // RELEASES the pin. Say so where it applies rather than letting the caller
+                // discover it by losing their target.
+                const pin = ctx.workflowTarget?.get(ctx.tabId);
+                const pinNote = pin?.mode === "pinned" && pin.path
+                    ? ` NOTE: this session is PINNED to ${pin.filename ?? pin.path}, and mode:"current" ` +
+                        `RELEASES that pin. To keep it, bring that workflow back to the canvas with ` +
+                        `panel_open_workflow(${JSON.stringify(pin.path)}) and retry instead.`
+                    : "";
+                const RETRY_IS_FREE = `RETRY THIS EXACT CALL ONCE — this is a read, so re-issuing it cannot double-apply ` +
+                    `anything.`;
+                let verdict;
+                try {
+                    const probe = await rebindWorkflowFence(ctx, { adopt: false });
+                    const live = "uuid" in probe ? probe.uuid : null;
+                    verdict =
+                        probe.status === "no_identity"
+                            // Worded without reference to the session's own side, because this
+                            // state is reachable from BOTH shapes: an unstamped session and a
+                            // stamped one can each face a canvas with no readable identity, and
+                            // "no identity EITHER" would be false for the second.
+                            ? `\n\nCHECKED, so this is not a guess: the live canvas was re-read and it carries ` +
+                                `no workflow identity of its own (${probe.why}). ` +
+                                `panel_set_workflow_target({mode:"current"}) will NOT clear this — it chooses ` +
+                                `WHICH workflow to fence against and cannot mint an identity for one that has ` +
+                                `none, so it reports success while this read keeps being refused. RECOVERY: ` +
+                                `panel_open_workflow(<path>) on this same workflow; re-opening it is what gives ` +
+                                `it an identity. If it has never been saved there is no path to re-open — save ` +
+                                `it first with panel_save_workflow, which also gives it a stable identity.`
+                            : probe.status === "healed_by_panel"
+                                ? `\n\nCHECKED, and the answer CHANGED while it was being read: the panel ` +
+                                    `re-advertised its identity and this session's fence moved to the live canvas ` +
+                                    `(${live}) — through the panel's own repair, not this check. ${RETRY_IS_FREE}`
+                                : probe.status === "already_current"
+                                    ? shape === "unstamped"
+                                        ? // The COMPARISON, not a cause — the panel's own discipline. An
+                                            // identity established between dispatch and this read explains
+                                            // it, and so does this session having been re-bound onto another
+                                            // tab in between; neither was witnessed, so neither is asserted.
+                                            `\n\nCHECKED, and the two readings disagree: this session's fence NOW ` +
+                                                `names the live canvas (${live}), yet this command reached the panel ` +
+                                                `carrying no stamp at all. What produced that gap was not observed from ` +
+                                                `here. ${RETRY_IS_FREE}`
+                                        : `\n\nCHECKED: this session's fence already names the live canvas ` +
+                                            `(${live}), so it was not the stale side and the disagreement is gone by ` +
+                                            `the time it was looked at. ${RETRY_IS_FREE} If it refuses again with the ` +
+                                            `same pair, the two identities are genuinely disagreeing and ` +
+                                            `panel_open_workflow is the way to settle which one you mean.`
+                                    : probe.status === "diverged"
+                                        ? shape === "unstamped"
+                                            ? // Says only what the panel reported and what the probe read. It
+                                                // does NOT assert that this session holds no fence right now:
+                                                // `diverged` is also reached with a fence naming some third
+                                                // workflow, and that reading was never taken.
+                                                `\n\nCHECKED, and this is a MISSING stamp rather than a wrong one: the ` +
+                                                    `panel refused it for arriving with NO stamp, so no two identities were ` +
+                                                    `compared — this is not the case where you are pointed at another ` +
+                                                    `workflow. The live canvas DOES have an identity ` +
+                                                    `(${live}). Nothing was adopted here; this check is read-only and the ` +
+                                                    `fence is unchanged. RECOVERY: ` +
+                                                    `panel_set_workflow_target({mode:"current"}) derives this session's ` +
+                                                    `fence from the live canvas, after which this read carries a stamp and ` +
+                                                    `runs.${pinNote}`
+                                            : shape === "stamped"
+                                                ? // "was issued for", not "is fenced to": the uuid comes from the
+                                                    // panel's account of what the COMMAND carried, and the session's
+                                                    // fence may have moved since. The mutation branch above words
+                                                    // it the same way for the same reason.
+                                                    `\n\nCHECKED, and this session was NOT re-pointed: this command was ` +
+                                                        `issued for ${stamped} and the live canvas is a DIFFERENT workflow ` +
+                                                        `(${live}). ` +
+                                                        `This is a WRONG stamp, not a missing one, so the two exits are not ` +
+                                                        `interchangeable: to read the workflow you issued for, bring it back ` +
+                                                        `with panel_open_workflow; to read the live canvas instead, re-target ` +
+                                                        `deliberately with panel_set_workflow_target({mode:"current"}) — that ` +
+                                                        `also re-points every later EDIT in this session, which is why it is ` +
+                                                        `never done for you off a refusal.${pinNote}`
+                                                : `\n\nCHECKED, and the live canvas reports ${live}. Which side is ` +
+                                                    `stale is NOT known from here: this panel's refusal states neither ` +
+                                                    `that the command was unstamped nor which instance it was issued ` +
+                                                    `for, so no remedy is named for it — read panel_list_workflows (the ` +
+                                                    `panel exempts it from this fence) and decide which workflow you mean.`
+                                        : `\n\nCHECKED, but the live canvas could not be established ` +
+                                            `(${probe.status}), so the answer is UNKNOWN and the fence is unchanged. ` +
+                                            `Try panel_list_workflows — the panel exempts that read from this fence ` +
+                                            `(it is the recovery probe) — and re-select the workflow you mean with ` +
+                                            `panel_open_workflow.`;
+                }
+                catch (probeErr) {
+                    // A diagnosis must never change how the call failed.
+                    verdict =
+                        `\n\nCHECKED, and the check itself threw, so the live canvas is UNKNOWN — this ` +
+                            `refusal stands on its own terms and the fence is unchanged. ` +
+                            `(${probeErr instanceof Error ? probeErr.message : String(probeErr)})`;
+                }
+                return fail(`${name} was refused before it ran — no graph data was read. ${raw}${verdict}`);
+            }
             // #1480 — NAME A REMEDY THE TAB CAN ACTUALLY ACCEPT.
             //
             // The panel's own remedy for this verdict is `panel_open_workflow(<path>)`, which
@@ -6508,9 +7083,11 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
                 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 carryReplyTimeoutMark(err, fail(`${cause}\n\nTo retry this exact mutation, re-issue identical args plus retry_of:"${dispatchedRid}"; otherwise call normally.`));
+                return carryReplyTimeoutMark(err, fail(`${cause}\n\nTo retry this exact mutation, re-issue identical args plus retry_of:"${dispatchedRid}"; otherwise call normally.` +
+                    queueBusyTimeoutNote()));
             }
-            return carryReplyTimeoutMark(err, fail(err));
+            const timeoutCause = err instanceof Error ? err.message : String(err);
+            return carryReplyTimeoutMark(err, fail(`${timeoutCause}${queueBusyTimeoutNote()}`));
         }
     };
     /**
@@ -8674,7 +9251,65 @@ export function buildPanelToolDefs() {
             // a single revalidation, #338/#458) — that authoritative fetch can outlast
             // the 6000 ms default ack on a large install and return a FALSE timeout.
             // Give the guarded write the bounded refresh ack budget.
-            return ctx.call({ cmd: "graph_set_widget", node_id: args.node_id, widget: args.widget, value }, OBJECT_INFO_REFRESH_ACK_TIMEOUT_MS);
+            const write = (nodeId, widget) => ctx.call({ cmd: "graph_set_widget", node_id: nodeId, widget, value }, OBJECT_INFO_REFRESH_ACK_TIMEOUT_MS);
+            const first = await write(args.node_id, args.widget);
+            if (!first.isError)
+                return first;
+            // #1655 — the panel listed this widget as promoted while refusing it as
+            // not promoted. The listing is node.widgets; the write looks up host
+            // inputs. When those disagree, resolve the displayed name to the unique
+            // inner mapping and set it there (the issue's own workaround), then
+            // leave the subgraph so the caller's scope is unchanged.
+            const refusal = parseContradictoryPromotedWidgetRefusal(textOfToolResult(first), args.widget);
+            if (!refusal || String(refusal.nodeId) !== String(args.node_id))
+                return first;
+            if (refusal.widget !== args.widget) {
+                const remapped = await write(args.node_id, refusal.widget);
+                if (!remapped.isError)
+                    return remapped;
+                if (!parseContradictoryPromotedWidgetRefusal(textOfToolResult(remapped), refusal.widget)) {
+                    return remapped;
+                }
+            }
+            const sub = await ctx.call({ cmd: "graph_get_subgraph", node_id: args.node_id });
+            if (sub.isError) {
+                return appendToolResultText(first, `\n\n(The panel listed "${refusal.widget}" as promoted while refusing it. ` +
+                    `Tried to resolve that name to the inner widget and graph_get_subgraph FAILED: ` +
+                    `${textOfToolResult(sub)})`);
+            }
+            const inner = resolveInnerPromotedTarget(parseToolResultJson(sub), refusal.widget);
+            if (!inner) {
+                return appendToolResultText(first, `\n\n(The panel listed "${refusal.widget}" as promoted while refusing it. ` +
+                    `graph_get_subgraph did not uniquely identify an inner node that owns that widget, ` +
+                    `so the write was not retried — guessing among several inners, or acting on a ` +
+                    `truncated inner list, would target the wrong node.)`);
+            }
+            const entered = await ctx.call({ cmd: "graph_enter_subgraph", node_id: args.node_id }, 15000);
+            if (entered.isError) {
+                return appendToolResultText(first, `\n\n(The panel listed "${refusal.widget}" as promoted while refusing it. ` +
+                    `Resolved it to inner node ${inner.innerNodeId} but panel_enter_subgraph FAILED: ` +
+                    `${textOfToolResult(entered)})`);
+            }
+            const written = await write(inner.innerNodeId, inner.widget);
+            const exited = await ctx.call({ cmd: "graph_exit_subgraph" }, 15000);
+            if (!written.isError) {
+                const via = `\n\n(Applied via the inner widget this promotion lists: node ${inner.innerNodeId} ` +
+                    `"${inner.widget}". The panel listed "${refusal.widget}" as promoted while refusing ` +
+                    `it as not promoted; the displayed name was resolved to that inner mapping.)`;
+                if (exited.isError) {
+                    return appendToolResultText(written, `${via} panel_exit_subgraph then FAILED — the canvas may still be inside the ` +
+                        `subgraph. Call panel_exit_subgraph. (${textOfToolResult(exited)})`);
+                }
+                return appendToolResultText(written, via);
+            }
+            if (exited.isError) {
+                return appendToolResultText(first, `\n\n(Tried the inner mapping node ${inner.innerNodeId} "${inner.widget}" and it ` +
+                    `FAILED: ${textOfToolResult(written)} panel_exit_subgraph also FAILED — the ` +
+                    `canvas may still be inside the subgraph. Call panel_exit_subgraph. ` +
+                    `(${textOfToolResult(exited)}))`);
+            }
+            return appendToolResultText(first, `\n\n(Tried the inner mapping node ${inner.innerNodeId} "${inner.widget}" and it ` +
+                `FAILED: ${textOfToolResult(written)})`);
         }),
         def("panel_remove_widget", "Remove ONE dynamic widget row from a node — the rows custom nodes add themselves, like the rgthree Power Lora Loader's `lora_1`, `lora_2`, … or an Impact/Inspire list node's entries. Their add/remove affordance is a canvas-drawn button you cannot click, so this is the only way to delete a row; panel_set_widget can only overwrite a row's value, and panel_remove_node deletes the whole node. REFUSES, with the reason, when the widget is an input the BACKEND declares (removing it would change what is sent at queue time — set it with panel_set_widget instead), when it is a frontend-generated control widget (control_after_generate, which the frontend re-creates), when its input slot currently has a link (disconnect it first), and when the node definitions cannot be read at all — an unreadable definition is reported as unknown, never treated as 'not declared'. The remaining rows are deliberately NOT renumbered: `lora_N` is a monotonic id, not a position, and the backend matches rows by name prefix, so gaps are harmless — the reply lists the remaining widget names, and those are the names to use next. Undoable with Ctrl+Z.", {
             node_id: nodeId().describe("Node id from panel_graph_outline / panel_query_graph."),
@@ -10048,66 +10683,97 @@ export function buildPanelToolDefs() {
             let rebindNote = "";
             let deferredBind = false;
             let fenceRebind;
+            // panel#1292 — a scope ctx stays scope-bound, so ctx.tabId never changes
+            // on a successful turn-pin recovery. Track that separately from the
+            // real-tab rebind note below.
+            let currentModeTurnRepinned = false;
             if (mode === "current" && ctx.rebindToActiveTab) {
                 const before = ctx.tabId;
-                // Give an in-flight reconnect (a ComfyUI restart / panel reload still
-                // settling) a brief chance to bind immediately, since this IS the recovery
-                // signal the agent reaches for in exactly that window (#474). awaitReachable
-                // rebinds via ensureReachable when a tab is (re)connected.
-                if (ctx.awaitReachable)
-                    await ctx.awaitReachable();
-                try {
-                    // completes the rebind if awaitReachable didn't. mode:"current" is
-                    // THE explicit scope-recovery consent (#884 gate 3) — the only
-                    // caller that may escape a DEAD scope pin (a healthy pin still
-                    // stays put; see rebindToActiveTab's double gate).
-                    const rebind = ctx.rebindToActiveTab({ scopeRecoveryConsent: true });
-                    // #1077 Finding 2 — a scope repin that declined now says WHY, and
-                    // this is where the user reads it. The refusal used to be a bare
-                    // boolean, so a session stuck in the one state that repeats forever
-                    // (the active tab belongs to another backend's conversation while
-                    // this one has several eligible tabs) saw no difference from a
-                    // healthy pin being correctly left alone.
-                    if (rebind?.repinRefusal) {
-                        rebindNote += ` The session pin was NOT moved: ${rebind.repinRefusal}.`;
+                const recoveringScope = isScopeAddress(before);
+                // Hold the send() wait BEFORE the first await so a same-batch sibling
+                // that already hit the null pin waits instead of minting #884.
+                if (recoveringScope)
+                    ctx.bridge.beginScopeRecovery?.(before);
+                const tryRebind = (deferIfNoTabs) => {
+                    try {
+                        // mode:"current" is THE explicit scope-recovery consent (#884 gate 3)
+                        // — the only caller that may escape a DEAD scope pin (a healthy pin
+                        // still stays put; see rebindToActiveTab's double gate).
+                        const rebind = ctx.rebindToActiveTab({ scopeRecoveryConsent: true });
+                        // #1077 Finding 2 — a scope repin that declined now says WHY.
+                        if (rebind?.repinRefusal && !/pin was NOT moved/.test(rebindNote)) {
+                            rebindNote += ` The session pin was NOT moved: ${rebind.repinRefusal}.`;
+                        }
+                        if (rebind?.rebound)
+                            currentModeTurnRepinned = true;
                     }
-                }
-                catch (err) {
-                    // #474: with 2+ live tabs the rebind is AMBIGUOUS — fail so the user picks.
-                    // But with ZERO tabs connected (the "Connected: none" window right after a
-                    // restart/reload where the old tmp: tab is gone) the recovery call must NOT
-                    // hard-fail: clear the stale binding and record the current-mode intent so
-                    // the session binds onto the tab the moment one reconnects, instead of
-                    // stranding the agent with no way to recover.
-                    const live = typeof ctx.bridge.tabs === "function" ? ctx.bridge.tabs() : undefined;
-                    let noTabsConnected;
-                    if (Array.isArray(live)) {
-                        // Count only INTERACTIVE (canvas-owning) tabs: a headless-only reconnect is
-                        // NOT a usable graph binding, so it defers (binds once a real canvas tab
-                        // connects) rather than failing as if a tab were pickable. Call isHeadless
-                        // THROUGH the bridge (it reads `this.conns`) — a detached reference would
-                        // lose `this` and throw "reading 'conns'" (the same #478 unbound-method bug).
-                        const isHeadlessTab = (id) => typeof ctx.bridge.isHeadless === "function" && ctx.bridge.isHeadless(id);
-                        const interactive = live.filter((t) => !isHeadlessTab(t.tab_id));
-                        noTabsConnected = interactive.length === 0;
+                    catch (err) {
+                        // #474: with 2+ live tabs the rebind is AMBIGUOUS — fail so the user picks.
+                        // But with ZERO tabs connected (the "Connected: none" window right after a
+                        // restart/reload where the old tmp: tab is gone) the recovery call must NOT
+                        // hard-fail: clear the stale binding and record the current-mode intent so
+                        // the session binds onto the tab the moment one reconnects, instead of
+                        // stranding the agent with no way to recover.
+                        const live = typeof ctx.bridge.tabs === "function" ? ctx.bridge.tabs() : undefined;
+                        let noTabsConnected;
+                        if (Array.isArray(live)) {
+                            // Count only INTERACTIVE (canvas-owning) tabs: a headless-only reconnect is
+                            // NOT a usable graph binding, so it defers (binds once a real canvas tab
+                            // connects) rather than failing as if a tab were pickable. Call isHeadless
+                            // THROUGH the bridge (it reads `this.conns`) — a detached reference would
+                            // lose `this` and throw "reading 'conns'" (the same #478 unbound-method bug).
+                            const isHeadlessTab = (id) => typeof ctx.bridge.isHeadless === "function" && ctx.bridge.isHeadless(id);
+                            const interactive = live.filter((t) => !isHeadlessTab(t.tab_id));
+                            noTabsConnected = interactive.length === 0;
+                        }
+                        else {
+                            // No tab enumeration — classify by the resolve error: only "nothing
+                            // connected" defers; an AMBIGUOUS multi-tab error must still fail so the
+                            // user picks (never silently defer a routable-but-ambiguous session).
+                            const msg = err instanceof Error ? err.message : String(err ?? "");
+                            noTabsConnected =
+                                /no panel connected|not reachable|connected:\s*none|no connected tab/i.test(msg) &&
+                                    !/multiple|last active|pass tab_id/i.test(msg);
+                        }
+                        if (!noTabsConnected)
+                            return fail(ambiguousRebindGuidance(ctx, err));
+                        // The first pass is BEFORE awaitReachable. Deferring here skipped the
+                        // wait, so a tab that reconnects mid-call (#474) was never adopted.
+                        if (!deferIfNoTabs)
+                            return undefined;
+                        deferredBind = true;
+                        rebindNote =
+                            " No panel tab is connected yet — cleared the stale binding; this session will " +
+                                "follow (bind onto) the tab as soon as one reconnects. Retry your graph tool in a " +
+                                "moment; if nothing reconnects shortly, ask the user to refresh (reload) the ComfyUI " +
+                                "browser tab, which reconnects the Agent panel after a restart (not an install issue).";
                     }
-                    else {
-                        // No tab enumeration — classify by the resolve error: only "nothing
-                        // connected" defers; an AMBIGUOUS multi-tab error must still fail so the
-                        // user picks (never silently defer a routable-but-ambiguous session).
-                        const msg = err instanceof Error ? err.message : String(err ?? "");
-                        noTabsConnected =
-                            /no panel connected|not reachable|connected:\s*none|no connected tab/i.test(msg) &&
-                                !/multiple|last active|pass tab_id/i.test(msg);
+                    return undefined;
+                };
+                try {
+                    // panel#1292 hole 1 — recover the turn pin SYNCHRONOUSLY, before
+                    // awaitReachable yields to same-batch siblings.
+                    const failed = tryRebind(false);
+                    if (failed)
+                        return failed;
+                    // Give an in-flight reconnect (a ComfyUI restart / panel reload still
+                    // settling) a brief chance to bind immediately, since this IS the recovery
+                    // signal the agent reaches for in exactly that window (#474). awaitReachable
+                    // rebinds via ensureReachable when a tab is (re)connected.
+                    if (ctx.awaitReachable)
+                        await ctx.awaitReachable();
+                    // A first attempt that found no canvas (or a dead pin that is still
+                    // dead after the wait) gets one more recovery now that a tab may exist.
+                    const pinStillDead = typeof ctx.bridge.canReach === "function" && !ctx.bridge.canReach(ctx.tabId);
+                    if (!currentModeTurnRepinned && pinStillDead) {
+                        const failed2 = tryRebind(true);
+                        if (failed2)
+                            return failed2;
                     }
-                    if (!noTabsConnected)
-                        return fail(ambiguousRebindGuidance(ctx, err));
-                    deferredBind = true;
-                    rebindNote =
-                        " No panel tab is connected yet — cleared the stale binding; this session will " +
-                            "follow (bind onto) the tab as soon as one reconnects. Retry your graph tool in a " +
-                            "moment; if nothing reconnects shortly, ask the user to refresh (reload) the ComfyUI " +
-                            "browser tab, which reconnects the Agent panel after a restart (not an install issue).";
+                }
+                finally {
+                    if (recoveringScope)
+                        ctx.bridge.endScopeRecovery?.(before);
                 }
                 // Detect the rebind regardless of whether awaitReachable or rebindToActiveTab
                 // performed it (either mutates ctx.tabId), so the note is never swallowed.
@@ -10119,6 +10785,12 @@ export function buildPanelToolDefs() {
                     // was whether the retarget did anything, it read as a no-op.
                     rebindNote = ` Rebound this session from tab ${shortTabId(before)} onto the active tab ${shortTabId(ctx.tabId)}.`;
                 }
+                if (currentModeTurnRepinned) {
+                    rebindNote +=
+                        ` This session's turn routing was AMBIGUOUS (a reconnect delivered messages from ` +
+                            `several workflows at once) and is now pinned to the active tab, so graph tools ` +
+                            `will resolve deterministically.`;
+                }
             }
             // PIN: bind to the EXACT open-workflow identity from the authoritative
             // workflow_list, canonicalizing to its stable `key`, FAILING CLOSED when the
@@ -10316,6 +10988,20 @@ export function buildPanelToolDefs() {
             const fence = fenceRebind
                 ? describeFenceRebind(fenceRebind, canMutateNow, refusalCause)
                 : undefined;
+            // panel#1292 hole 2 — `graph_binding:"bound"` is a fence verdict, not a
+            // statement that the turn-origin pin was recovered. A null pin still
+            // mints the #884 refusal on the next scope-addressed graph call.
+            const turnPinStillAmbiguous = () => isScopeAddress(ctx.tabId) &&
+                typeof ctx.bridge.resolveFailure === "function" &&
+                ctx.bridge.resolveFailure(ctx.tabId) === "ambiguous";
+            const refuseBoundWhileAmbiguous = () => fail(`panel_set_workflow_target({mode:"current"}) did NOT restore this session's turn ` +
+                `routing.\n\nAPPLIED (do not repeat this part): the workflow target is now ` +
+                `mode:"current"${rebindNote ? `.${rebindNote}` : "."}\n\nNOT APPLIED: the ` +
+                `workflow-instance fence could be described as bound, but the turn-origin pin ` +
+                `is still ambiguous, so the next graph call would fail with "issued from ` +
+                `multiple workflows at once". Name a workflow with ` +
+                `panel_set_workflow_target({mode:"pinned", path:...}) or wait for the next ` +
+                `single-origin message.`);
             // #1473 — TAKE THE ADVICE THIS MESSAGE GIVES, instead of assigning it as homework.
             //
             // The reporter restarted ComfyUI, called this, was told the binding was NOT
@@ -10420,10 +11106,13 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
                     const heldUuid = fenceRebind && fenceRebind.status === "no_identity" && fenceRebind.before.known
                         ? fenceRebind.before.uuid
                         : undefined;
+                    if (turnPinStillAmbiguous())
+                        return refuseBoundWhileAmbiguous();
                     return ok({
                         ...target,
                         graph_binding: "bound",
                         ...(fenceRebind ? { graph_binding_status: fenceRebind.status } : {}),
+                        ...(currentModeTurnRepinned ? { turn_routing: "repinned" } : {}),
                         note: hint +
                             rebindNote +
                             ` The graph binding was NOT re-derived (the panel's active reply could ` +
@@ -10454,12 +11143,17 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
                 : scopeRepin && typeof scopeRepin === "object" && scopeRepin.reason
                     ? ` NOTE — the workflow target was set, but this session's turn routing was NOT re-pinned: ${scopeRepin.reason}.`
                     : "";
+            if (fence?.binding === "bound" && turnPinStillAmbiguous()) {
+                return refuseBoundWhileAmbiguous();
+            }
             return ok({
                 ...target,
                 ...(deferredBind ? { deferred: true } : {}),
                 ...(fence ? { graph_binding: fence.binding } : {}),
                 ...(fenceRebind ? { graph_binding_status: fenceRebind.status } : {}),
-                ...(typeof scopeRepin === "string" ? { turn_routing: "repinned" } : {}),
+                ...(typeof scopeRepin === "string" || currentModeTurnRepinned
+                    ? { turn_routing: "repinned" }
+                    : {}),
                 note: hint + rebindNote + (fence?.note ?? "") + scopeRepinNote,
             });
         }),
@@ -10705,7 +11399,19 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
             name: args.name,
         }, 15000)),
         def("panel_unpack_subgraph", "EXPAND / DISSOLVE a subgraph node on the user's open graph — inline its interior nodes back into the PARENT graph, rewire all external links to those now-inlined nodes, and remove the subgraph wrapper. This is the frontend's \"Unpack Subgraph\" (litegraph LGraph.unpackSubgraph) and the exact INVERSE of panel_create_subgraph. Use it to flatten a stage that was over-nested, or to edit interior nodes directly at the parent level. The interior nodes reappear on the parent canvas with their connections preserved. Undoable with Ctrl+Z.", { node_id: nodeId().describe("Subgraph node id to unpack/dissolve (is_subgraph=true, from panel_graph_outline / panel_query_graph).") }, async (args, ctx) => ctx.call({ cmd: "graph_unpack_subgraph", node_id: args.node_id }, 15000)),
-        def("panel_search_nodes", "Search installable custom-node packs via the user's BUILT-IN ComfyUI Manager (the same source the Manager UI uses). Returns matching packs {id, title, description}. Use the `id` with panel_install_node. Prefer this over the headless search_custom_nodes tool — it works against the user's actual (Desktop) Manager.", { query: z.string().describe("Search text, e.g. 'kjnodes', 'controlnet', 'ipadapter'."), limit: z.number().int().min(1).max(40).optional().describe("Max results to return, 1-40 (default 15). Requests above 40 are refused; the panel also clamps to 40 and discloses limit_cap.") }, async (args, ctx) => ctx.call({ cmd: "nodes_search", query: args.query, limit: args.limit }, 20000)),
+        def("panel_search_nodes", "Search installable custom-node packs via the user's BUILT-IN ComfyUI Manager (the same source the Manager UI uses). Returns matching packs {id, title, description}. Use the `id` with panel_install_node. Prefer this over the headless search_custom_nodes tool — it works against the user's actual (Desktop) Manager. If Manager's cache mappings endpoint returns HTTP 5xx, this retries remote/local and still searches; a remaining 5xx is a Manager outage, not proof the pack is missing.", { query: z.string().describe("Search text, e.g. 'kjnodes', 'controlnet', 'ipadapter'."), limit: z.number().int().min(1).max(40).optional().describe("Max results to return, 1-40 (default 15). Requests above 40 are refused; the panel also clamps to 40 and discloses limit_cap.") }, async (args, ctx) => {
+            // #1669 — the panel asks getmappings?mode=cache and used to fail the
+            // whole search on HTTP 500. Degrade: retry remote/local, or name the
+            // 500 as a Manager outage (not a missing pack).
+            const query = String(args.query ?? "");
+            const limit = typeof args.limit === "number" ? args.limit : undefined;
+            const out = await searchPanelNodes({
+                panelSearch: () => ctx.call({ cmd: "nodes_search", query, limit }, 20000),
+                query,
+                limit,
+            });
+            return out.via === "panel" ? out.value : ok(out.value);
+        }),
         def("panel_list_nodes", "List the custom-node packs currently installed in the user's ComfyUI (via the built-in Manager). Read-only.", {}, async (_args, ctx) => ctx.call({ cmd: "nodes_list" }, 20000)),
         def("panel_install_node", "Install a custom-node pack into the user's ComfyUI via the BUILT-IN Manager (queues the install). Pass `id` (registry id like 'comfyui-kjnodes' or 'author/repo') from panel_search_nodes, or `repository` (git URL) to request a nightly/from-source install — see the v4 limit below before relying on it. A search result whose `id` IS a git URL (legacy/repository-style entries) is auto-routed to a from-source 'nightly' install — 'latest' cannot resolve for those. " +
             "⚠️ ON MANAGER v4, `repository` IS NOT THE URL THAT GETS CLONED (#1539). Read out of ComfyUI-Manager V4.2.2's own source and confirmed on a live V4.2.2: a 'nightly' install resolves the pack by its BARE REPO NAME against the CHANNEL's custom-node-list, then clones the URL recorded in THAT entry; the `repository` you pass is stored in the task params and never read. So what decides success is whether the repo is listed in the channel this call asks for — and a miss does NOT simply stop: on 'nightly' v4 falls back to the COMFY REGISTRY entry whose id is that same bare name and clones whatever repository it is registered to, so an unlisted name can still install someone else's code. Only when the registry lacks the id too do you get \"Node '<name>@nightly' not found in [ManagerChannel.<channel>, ManagerDatabaseSource.<mode>]\", naming that channel. " +
@@ -10771,7 +11477,7 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
             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. 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) => {
+        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. If a crash takes the panel bridge offline so the confirmation card cannot be shown, this tool falls back to a headless restart of the configured local process (or COMFYUI_RESTART_COMMAND) instead of depending on the dead bridge — it still refuses a readable busy queue without force:true, and still refuses when a relaunch cannot be proven. 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, or set COMFYUI_RESTART_COMMAND to the exact command that restarts the instance (e.g. `docker restart <container>`): the restart then runs through that command (the busy guard above still applies) instead of needing the launch path.", { 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
@@ -10824,6 +11530,12 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
                     "previous restart, so the confirmation card wasn't answered. Tell me to restart it " +
                     `and I'll re-ask. ${fallback}`);
             }
+            // #1671 — set when the confirmation card was UNREACHABLE and ComfyUI is
+            // not healthy: the crash took the panel bridge offline, so recovery
+            // must not depend on asking that bridge. The headless path below runs
+            // instead. An explicit decline, a still-healthy server, and remote/
+            // cloud keep the existing reports (confirmation + busy-queue stay).
+            let recoverWithoutPanel = false;
             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
@@ -10883,7 +11595,20 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
                         clearSessionRestartDispatchIfSame(ctx, declineHeldToken);
                     }
                 }
-                if (outcome.status === "down") {
+                // #1671: the recovery command must not depend on the component a crash
+                // takes offline. UNREACHABLE + not-healthy (down, or ambiguous — the
+                // reporter's empty-body HTTP 502) on a LOCAL target falls through to
+                // the headless restart. An explicit decline still reports and does
+                // NOT restart (confirmation). A still-healthy server still does not
+                // auto-restart (#1332). Remote/cloud have no local process to cycle.
+                const crashTookBridgeOffline = decision === "unreachable" &&
+                    (outcome.status === "down" || outcome.status === "ambiguous") &&
+                    !isRemoteMode() &&
+                    !isCloudMode();
+                if (crashTookBridgeOffline) {
+                    recoverWithoutPanel = true;
+                }
+                else 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
@@ -10924,7 +11649,12 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
                         "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) {
+                if (recoverWithoutPanel) {
+                    // Fall through to the headless path once runHeadlessManagedRestart
+                    // is defined. Do not claim the server is reachable, and do not ask
+                    // the dead panel to reboot it.
+                }
+                else 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
@@ -10943,26 +11673,37 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
                         : "Cancelled — no new restart was dispatched. ComfyUI was briefly " +
                             "unreachable but is healthy again.");
                 }
-                // #1332 — the reporter's exact string, and it was FALSE. They accepted the
-                // restart, ComfyUI restarted (a fresh startup in the server log), and this
-                // said it had not — because the restart dropped the socket the answer had to
-                // travel back on, and a transport failure used to arrive here as "no".
-                //
-                // The probes above already refuse to claim "not restarted" while the server
-                // is DOWN. This is the remaining case: the server is HEALTHY, which is
-                // equally true of "nothing happened" and of "it restarted and came back".
-                // With an explicit decline we know which; without one we do not, and the
-                // sentence must stop asserting it.
-                return ok(decision === "unreachable"
-                    ? "This call did NOT dispatch a restart. Whether ComfyUI restarted for some " +
-                        "other reason cannot be told from here: the panel could not be reached to " +
-                        "ask for confirmation — the question never appeared — so no decision was " +
-                        "made either way, and the server is reachable now, which looks the same " +
-                        "whether it never went down or went down and came back. If you asked for a " +
-                        "restart and one has already happened, this is that transport loss, not a " +
-                        "cancellation. Check the ComfyUI log for a fresh startup line before " +
-                        "restarting again."
-                    : "Cancelled — ComfyUI was not restarted.");
+                else {
+                    // #1332 — the reporter's exact string, and it was FALSE. They accepted the
+                    // restart, ComfyUI restarted (a fresh startup in the server log), and this
+                    // said it had not — because the restart dropped the socket the answer had to
+                    // travel back on, and a transport failure used to arrive here as "no".
+                    //
+                    // The probes above already refuse to claim "not restarted" while the server
+                    // is DOWN. This is the remaining case: the server is HEALTHY, which is
+                    // equally true of "nothing happened" and of "it restarted and came back".
+                    // With an explicit decline we know which; without one we do not, and the
+                    // sentence must stop asserting it.
+                    const fallback = decision === "unreachable"
+                        ? " " +
+                            restartTimeoutFallbackAdvice({
+                                headlessBase: getComfyUIBaseUrl(),
+                                panelBase: declineBootBase,
+                                observedOrigin: ctx.bridge?.tabServerOrigin?.(ctx.tabId) ?? null,
+                            })
+                        : "";
+                    return ok(decision === "unreachable"
+                        ? "This call did NOT dispatch a restart. Whether ComfyUI restarted for some " +
+                            "other reason cannot be told from here: the panel could not be reached to " +
+                            "ask for confirmation — the question never appeared — so no decision was " +
+                            "made either way, and the server is reachable now, which looks the same " +
+                            "whether it never went down or went down and came back. If you asked for a " +
+                            "restart and one has already happened, this is that transport loss, not a " +
+                            "cancellation. Check the ComfyUI log for a fresh startup line before " +
+                            "restarting again." +
+                            fallback
+                        : "Cancelled — ComfyUI was not restarted.");
+                }
             }
             // Heal an orphaned session onto the live tab FIRST, then bind the reboot dispatch
             // to that ONE tab id (no await between capture and dispatch, so JS run-to-
@@ -10970,6 +11711,366 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
             // 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?.();
+            // Run the HEADLESS managed restart (restartComfyUI) from inside this tool and
+            // report its outcome against OUR OWN independent boot-endpoint observation
+            // (never restartComfyUI's self-reported readiness, which a first-healthy
+            // no-op would flunk). Shared by three call sites that must not dispatch the
+            // tab reboot: the legacy no-endpoint fallback below (#425), a configured
+            // COMFYUI_RESTART_COMMAND (panel#1262), and #1671 crash recovery when the
+            // panel bridge is already gone. restartComfyUI acts on the orchestrator's
+            // GLOBAL config target, so the first two require a BOUND-CONFIRMED local
+            // tab; #1671 may also use the configured boot instance when the tab is gone.
+            const runHeadlessManagedRestart = async (args) => {
+                const { healthBase, preRestartPanelIdentity, why, mechanism, noteHealthyLead, noteRanLead } = args;
+                // The managed kill+relaunch does UNPREEMPTIBLE synchronous execSync work — PID
+                // discovery (~5+8s) + termination (~10s) + first port-free lookup (~13s) ≈ 40s
+                // worst case (Windows) — that a Promise.race CANNOT interrupt, and it BLOCKS the
+                // observer during that window. Admit it ONLY with enough budget for that sync
+                // work AND a full cold-start observation AFTER it, and give the observer a
+                // deadline that spans BOTH (coordinator P1: the proof deadline must start after,
+                // not before, the restart's synchronous work — otherwise a genuine cold start
+                // that finishes at sync+coldStart false-times-out).
+                const LEGACY_SYNC_WORST_CASE_MS = 40_000; // execSync PID lookup + kill + port-free
+                const LEGACY_COLD_START_OBS_MS = 100_000; // cold-start observation AFTER the sync
+                const LEGACY_RESTART_MIN_BUDGET_MS = LEGACY_SYNC_WORST_CASE_MS + LEGACY_COLD_START_OBS_MS;
+                if (overallDeadline - Date.now() < LEGACY_RESTART_MIN_BUDGET_MS) {
+                    return ok({
+                        rebooting: false,
+                        ready: false,
+                        confirmed_cycle: false,
+                        note: `${why}, and there isn't enough remaining time to safely run ${mechanism}. ` +
+                            "ComfyUI was NOT restarted — retry panel_restart_comfyui " +
+                            "(a fresh call gets the full budget).",
+                    });
+                }
+                // A managed kill+relaunch restarts ComfyUI out-of-band, so drop the memoized
+                // caches. The observer watches the boot endpoint itself with a deadline spanning
+                // the ~40s blocking sync + a full cold-start window, and certifies ONLY on an
+                // OBSERVED down→up — a never-restarted healthy endpoint (a Desktop first-healthy
+                // Manager-reboot / preflight no-op) is honestly couldn't-confirm (coordinator P1).
+                resetClient();
+                resetObjectInfoCache();
+                resetManagerApiCache("panel managed restart");
+                const headlessTiming = getPanelRebootTiming();
+                // The observation window spans the ~40s blocking sync + a full cold-start
+                // window. (Under a test timing override, use the injected budget instead so the
+                // never-certify cases don't wait the real ~140s.)
+                const legacyProofWindow = panelRebootTimingOverride
+                    ? headlessTiming.settleMs + headlessTiming.budgetMs
+                    : LEGACY_RESTART_MIN_BUDGET_MS;
+                const proofDeadline = Math.min(Date.now() + legacyProofWindow, overallDeadline);
+                const proofPromise = observeRecovery(headlessTiming, proofDeadline, { healthBase });
+                const restartBudget = Math.max(1, overallDeadline - Date.now());
+                let restart;
+                let restartTimer;
+                try {
+                    restart = await Promise.race([
+                        restartComfyUI(),
+                        new Promise((resolve) => {
+                            restartTimer = setTimeout(() => resolve(undefined), restartBudget);
+                            restartTimer.unref?.();
+                        }),
+                    ]);
+                }
+                catch (err) {
+                    clearTimeout(restartTimer);
+                    void proofPromise.catch(() => { }); // self-terminates at proofDeadline
+                    return fail(`${why}, and ${mechanism} also failed: ` +
+                        (err instanceof Error ? err.message : String(err)) +
+                        " — 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 path 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 headlessDispatchToken;
+                if (restart?.stopped === true) {
+                    headlessDispatchToken = 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
+                // the OLD one — fail clearly rather than certify a no-op (coordinator P1).
+                if (restart?.spawn_error ||
+                    (restart != null && restart.stopped !== true && restart.started !== true)) {
+                    void proofPromise.catch(() => { });
+                    return fail(`${why}. Tried ${mechanism}, but it did not restart ` +
+                        `ComfyUI: ${restart?.message ?? "unknown error"} ` +
+                        "Restart ComfyUI on the host, then reconnect.");
+                }
+                // 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 && headlessDispatchToken != null) {
+                    clearSessionRestartDispatchIfSame(ctx, headlessDispatchToken);
+                }
+                const observed = recovery.via === "observed-cycle";
+                // The headless 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 headless 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);
+                // #654 — `ready`/`graph_tools_ready` still come from the BOOLEAN, so an
+                // undetermined reconnect withholds graph tools exactly as before. Only
+                // the reported observation changes.
+                const tabReconnect = classifyTabReconnect({
+                    serverReady: recovery.ready,
+                    baselineCaptured: preRestartPanelIdentity != null,
+                    tabBack,
+                });
+                return ok({
+                    rebooting: true,
+                    ready: graphToolsReady,
+                    graph_tools_ready: graphToolsReady,
+                    server_ready: recovery.ready,
+                    panel_tab_reconnected: tabReconnect,
+                    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: recovery.ready && !graphToolsReady
+                        ? `${noteHealthyLead} came back healthy in ${(recovery.waited_ms / 1000).toFixed(1)}s, but ` +
+                            (!tabBack
+                                ? tabReconnect === "unknown"
+                                    ? "whether the panel tab reconnected could NOT be determined — no pre-restart " +
+                                        "baseline was captured for it, so nothing was watched. WHY is not established " +
+                                        "here, and it is one of: the tab's socket was not open at the instant the " +
+                                        "restart was dispatched; the panel advertised no tab session id (an older " +
+                                        "build, or its browser-tab lease was refused because a duplicate tab holds " +
+                                        "it); or the tab did not resolve at all. The tab may well be back. Graph " +
+                                        "tools are withheld (ready:false) because that is unproven, NOT because the " +
+                                        'tab is known to be gone: call panel_list_workflows or panel_set_workflow_target({mode:"current"}) ' +
+                                        "to find out, and only refresh the browser if those also fail. If this " +
+                                        "repeats on every restart, the panel is probably too old to advertise a tab " +
+                                        "session id — update it."
+                                    : "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.")
+                        : `${noteRanLead} ` +
+                            (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 get_system_stats (action:"health") / panel_node_queue_status before assuming it restarted.`),
+                });
+            };
+            // #1671: panel-offline crash recovery. The confirmation card could not
+            // be shown because the bridge is gone, and ComfyUI is not healthy
+            // (down, or an empty-body 502). Restart the configured local process
+            // through the same headless path the Manager-missing and
+            // COMFYUI_RESTART_COMMAND cases already use. Do NOT send comfy_reboot
+            // — that is the dead bridge. A readable busy queue still refuses
+            // without force:true; an unreadable queue on an already-unhealthy
+            // server is the crash, not "idle", and is not a reason to refuse.
+            // A proven-different panel origin, or a process we cannot relaunch,
+            // fails with the true cause instead of claiming success.
+            if (recoverWithoutPanel) {
+                const healthBase = offlineRestartHealthBase(ctx);
+                if (healthBase == null || !sameHttpBase(getComfyUIBaseUrl(), healthBase)) {
+                    return ok({
+                        rebooting: false,
+                        ready: false,
+                        confirmed_cycle: false,
+                        refused: true,
+                        note: "This call did NOT dispatch a restart. The panel could not be reached to " +
+                            "ask for confirmation (the crash took the panel bridge offline) and I " +
+                            "cannot identify a local ComfyUI process I can account for, so I will " +
+                            "not stop a server I cannot prove I can bring back. Nothing was " +
+                            "stopped. " +
+                            restartRefusalHandoffAdvice({
+                                headlessBase: getComfyUIBaseUrl(),
+                                panelBase: captureRebootHealthBase(ctx),
+                                observedOrigin: ctx.bridge?.tabServerOrigin?.(ctx.tabId) ?? null,
+                            }),
+                    });
+                }
+                if (force !== true) {
+                    let busyCount = null;
+                    try {
+                        const queue = await getQueueVerified();
+                        busyCount = queue.queue_running.length + queue.queue_pending.length;
+                    }
+                    catch {
+                        // Unreadable queue + already-unhealthy server is the crash itself.
+                        // Unlike the configured-command YES path, "cannot check" is not a
+                        // reason to refuse: the generation that might have been running
+                        // is the one that took the bridge down.
+                        busyCount = null;
+                    }
+                    if (busyCount != null && busyCount !== 0) {
+                        return ok({
+                            rebooting: false,
+                            ready: false,
+                            confirmed_cycle: false,
+                            refused: true,
+                            note: `Refusing to restart ComfyUI: ${busyCount} generation(s) are in progress ` +
+                                "or queued, and a restart ABORTS them. The panel could not be reached " +
+                                "to ask, so nothing was stopped. Wait for the queue to drain, or retry " +
+                                "with force:true ONLY if the user explicitly confirms they want to kill " +
+                                "the running generation.",
+                        });
+                    }
+                }
+                const configuredCmd = config.comfyuiRestartCommand;
+                if (!configuredCmd) {
+                    const preflight = await (localRestartPreflightOverride ?? preflightLocalRestart)();
+                    if (!preflight.ok) {
+                        return ok({
+                            rebooting: false,
+                            ready: false,
+                            confirmed_cycle: false,
+                            refused: true,
+                            note: "The panel could not be reached to ask for confirmation (the crash " +
+                                "took the panel bridge offline). Refusing to restart ComfyUI: " +
+                                `${preflight.reason} A restart from here would STOP ComfyUI and ` +
+                                "nothing would bring it back automatically, so it was refused " +
+                                "BEFORE anything was stopped. Restart it from whatever launches it, " +
+                                "or set COMFYUI_RESTART_COMMAND to the exact command that restarts " +
+                                "the instance.",
+                        });
+                    }
+                }
+                const postHealthBase = offlineRestartHealthBase(ctx);
+                if (postHealthBase == null || !sameHttpBase(healthBase, postHealthBase)) {
+                    return ok({
+                        rebooting: false,
+                        ready: false,
+                        confirmed_cycle: false,
+                        refused: true,
+                        note: "Refusing to restart ComfyUI: the ComfyUI target changed while the " +
+                            "offline recovery was being prepared, so I can no longer confirm the " +
+                            "headless restart would act on the instance this session accounts for. " +
+                            "Nothing was stopped.",
+                    });
+                }
+                return runHeadlessManagedRestart({
+                    healthBase,
+                    preRestartPanelIdentity: ctx.panelConnectionIdentity?.(),
+                    why: "The panel could not be reached to ask for confirmation (the crash took " +
+                        "the panel bridge offline)",
+                    mechanism: configuredCmd
+                        ? "the configured restart command"
+                        : "the headless managed restart (kill + relaunch)",
+                    noteHealthyLead: configuredCmd
+                        ? "The panel bridge was offline after the crash, so the restart ran " +
+                            "through COMFYUI_RESTART_COMMAND; ComfyUI"
+                        : "The panel bridge was offline after the crash, so the restart ran " +
+                            "through the headless managed restart; ComfyUI",
+                    noteRanLead: configuredCmd
+                        ? "The panel bridge was offline after the crash, so the restart ran " +
+                            "through COMFYUI_RESTART_COMMAND (not a panel confirmation card)"
+                        : "The panel bridge was offline after the crash, so the restart ran " +
+                            "through the headless managed restart (not a panel confirmation card)",
+                });
+            }
+            // panel#1262: A CONFIGURED RESTART COMMAND REPLACES THE TAB REBOOT.
+            //
+            // On an externally-managed local install (a container, a systemd unit, a
+            // launcher) the tab reboot is the WRONG mechanism twice over: the
+            // refuse-safe preflight below cannot prove a relaunch from a bare
+            // `main.py` argv that anchors only inside the instance's own namespace
+            // (so it refuses and the wedge wins), and a wedged server answers no
+            // Manager reboot anyway. COMFYUI_RESTART_COMMAND is the user's explicit
+            // statement of what cycles the instance, so when it is set the restart
+            // runs through it (headless restartComfyUI honors it) instead of the
+            // tab dispatch. The BUSY GUARD the server-side reboot would have
+            // enforced is re-implemented here against a VERIFIED queue read, with
+            // the same force:true contract; a queue that cannot be read at all (the
+            // wedge itself) refuses without force, because "cannot check" is not
+            // "idle" and a restart aborts whatever is running.
+            const configuredRestartCommand = config.comfyuiRestartCommand;
+            if (configuredRestartCommand && !isRemoteMode() && !isCloudMode()) {
+                const commandHealthBase = captureRebootHealthBase(ctx);
+                if (commandHealthBase != null && sameHttpBase(getComfyUIBaseUrl(), commandHealthBase)) {
+                    if (force !== true) {
+                        let busyCount = null;
+                        try {
+                            const queue = await getQueueVerified();
+                            busyCount = queue.queue_running.length + queue.queue_pending.length;
+                        }
+                        catch {
+                            // unknown-ok: an UNREADABLE queue is the wedge case itself — null
+                            // below refuses without force (fail closed), it never reads as idle.
+                            busyCount = null;
+                        }
+                        if (busyCount !== 0) {
+                            return ok({
+                                rebooting: false,
+                                ready: false,
+                                confirmed_cycle: false,
+                                refused: true,
+                                note: busyCount === null
+                                    ? "Refusing to restart ComfyUI: COMFYUI_RESTART_COMMAND is set, so the " +
+                                        "restart runs the configured command — which ABORTS any in-progress or " +
+                                        "queued generation — and the queue could not be read to confirm it is " +
+                                        "idle (the server is not answering, which may be the very wedge you are " +
+                                        "restarting to escape). Nothing was stopped. If the user confirms any " +
+                                        "running render may be killed, retry with force:true."
+                                    : `Refusing to restart ComfyUI: ${busyCount} generation(s) are in progress ` +
+                                        "or queued, and the configured restart command ABORTS them. Nothing was " +
+                                        "stopped. Wait for the queue to drain (poll panel_node_queue_status), or " +
+                                        "retry with force:true ONLY if the user explicitly confirms they want to " +
+                                        "kill the running generation.",
+                            });
+                        }
+                    }
+                    // The busy-check AWAIT makes the pre-await binding capture stale (r7's
+                    // own rule): a retarget or tab rebind landing during it would run the
+                    // command against an instance this tab no longer provably fronts.
+                    // Re-heal and re-verify at the point of action, exactly as the
+                    // dispatch path below does.
+                    ctx.ensureReachable?.();
+                    const postCheckHealthBase = captureRebootHealthBase(ctx);
+                    if (postCheckHealthBase == null ||
+                        !sameHttpBase(commandHealthBase, postCheckHealthBase)) {
+                        return ok({
+                            rebooting: false,
+                            ready: false,
+                            confirmed_cycle: false,
+                            refused: true,
+                            note: "Refusing to restart ComfyUI: the panel connection or target changed " +
+                                "while the queue was being checked, so I can no longer confirm the " +
+                                "configured restart command would act on the instance this tab fronts. " +
+                                "Nothing was stopped. Retry once the panel has settled.",
+                        });
+                    }
+                    return runHeadlessManagedRestart({
+                        healthBase: commandHealthBase,
+                        preRestartPanelIdentity: ctx.panelConnectionIdentity?.(),
+                        why: "COMFYUI_RESTART_COMMAND is set",
+                        mechanism: "the configured restart command",
+                        noteHealthyLead: "COMFYUI_RESTART_COMMAND is set, so the restart ran through the configured " +
+                            "command; ComfyUI",
+                        noteRanLead: "COMFYUI_RESTART_COMMAND is set, so the restart ran through the configured " +
+                            "command (not the Manager reboot)",
+                    });
+                }
+                // UNBOUND local target: the configured command acts on the orchestrator's
+                // CONFIGURED target, which is not provably the instance this tab fronts —
+                // fall through to the normal preflight/refusal machinery below (its refusal
+                // names restart_comfyui, the non-tab-scoped entry point that CAN use it).
+            }
             // #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
@@ -11169,7 +12270,10 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
                             "from whatever launches it (its own launcher — e.g. Pinokio's own controls — " +
                             "the Desktop app, or your terminal); for an externally-managed install you " +
                             "can also point COMFYUI_PATH " +
-                            "at the live install so a relaunch can be proven and use restart_comfyui.",
+                            "at the live install so a relaunch can be proven and use restart_comfyui, " +
+                            "or set COMFYUI_RESTART_COMMAND to the exact command that restarts the " +
+                            "instance (e.g. `docker restart <container>`) — both restart tools then run " +
+                            "that command instead of needing the launch path resolvable from here.",
                     });
                 }
                 // Otherwise: a PASS with a stable config (proven safe for THE
@@ -11390,161 +12494,14 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
                     // and tracked in #871; this gate narrows the window, it does not close it.
                     healthBase != null &&
                     sameHttpBase(getComfyUIBaseUrl(), healthBase)) {
-                    // The managed kill+relaunch does UNPREEMPTIBLE synchronous execSync work — PID
-                    // discovery (~5+8s) + termination (~10s) + first port-free lookup (~13s) ≈ 40s
-                    // worst case (Windows) — that a Promise.race CANNOT interrupt, and it BLOCKS the
-                    // observer during that window. Admit it ONLY with enough budget for that sync
-                    // work AND a full cold-start observation AFTER it, and give the observer a
-                    // deadline that spans BOTH (coordinator P1: the proof deadline must start after,
-                    // not before, the restart's synchronous work — otherwise a genuine cold start
-                    // that finishes at sync+coldStart false-times-out).
-                    const LEGACY_SYNC_WORST_CASE_MS = 40_000; // execSync PID lookup + kill + port-free
-                    const LEGACY_COLD_START_OBS_MS = 100_000; // cold-start observation AFTER the sync
-                    const LEGACY_RESTART_MIN_BUDGET_MS = LEGACY_SYNC_WORST_CASE_MS + LEGACY_COLD_START_OBS_MS;
-                    if (overallDeadline - Date.now() < LEGACY_RESTART_MIN_BUDGET_MS) {
-                        return ok({
-                            rebooting: false,
-                            ready: false,
-                            confirmed_cycle: false,
-                            note: "The built-in Manager exposed no reboot endpoint (legacy Manager 3.x), and " +
-                                "there isn't enough remaining time to safely run the headless managed restart " +
-                                "(kill + relaunch). ComfyUI was NOT restarted — retry panel_restart_comfyui " +
-                                "(a fresh call gets the full budget).",
-                        });
-                    }
-                    // A managed kill+relaunch restarts ComfyUI out-of-band, so drop the memoized
-                    // caches. The observer watches the boot endpoint itself with a deadline spanning
-                    // the ~40s blocking sync + a full cold-start window, and certifies ONLY on an
-                    // OBSERVED down→up — a never-restarted healthy endpoint (a Desktop first-healthy
-                    // Manager-reboot / preflight no-op) is honestly couldn't-confirm (coordinator P1).
-                    resetClient();
-                    resetObjectInfoCache();
-                    resetManagerApiCache("panel managed restart");
-                    // The observation window spans the ~40s blocking sync + a full cold-start
-                    // window. (Under a test timing override, use the injected budget instead so the
-                    // never-certify cases don't wait the real ~140s.)
-                    const legacyProofWindow = panelRebootTimingOverride
-                        ? timing.settleMs + timing.budgetMs
-                        : LEGACY_RESTART_MIN_BUDGET_MS;
-                    const proofDeadline = Math.min(Date.now() + legacyProofWindow, overallDeadline);
-                    const proofPromise = observeRecovery(timing, proofDeadline, { healthBase });
-                    const restartBudget = Math.max(1, overallDeadline - Date.now());
-                    let restart;
-                    let restartTimer;
-                    try {
-                        restart = await Promise.race([
-                            restartComfyUI(),
-                            new Promise((resolve) => {
-                                restartTimer = setTimeout(() => resolve(undefined), restartBudget);
-                                restartTimer.unref?.();
-                            }),
-                        ]);
-                    }
-                    catch (err) {
-                        clearTimeout(restartTimer);
-                        void proofPromise.catch(() => { }); // self-terminates at proofDeadline
-                        return fail("The built-in Manager exposed no reboot endpoint (legacy Manager 3.x), " +
-                            "and the headless managed restart also failed: " +
-                            (err instanceof Error ? err.message : String(err)) +
-                            " — restart ComfyUI on the host, then reconnect.");
-                    }
-                    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
-                    // the OLD one — fail clearly rather than certify a no-op (coordinator P1).
-                    if (restart?.spawn_error ||
-                        (restart != null && restart.stopped !== true && restart.started !== true)) {
-                        void proofPromise.catch(() => { });
-                        return fail("The built-in Manager exposed no reboot endpoint (legacy Manager 3.x). " +
-                            "Tried the headless managed restart (kill + relaunch), but it did not restart " +
-                            `ComfyUI: ${restart?.message ?? "unknown error"} ` +
-                            "Restart ComfyUI on the host, then reconnect.");
-                    }
-                    // 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);
-                    // #654 — `ready`/`graph_tools_ready` still come from the BOOLEAN, so an
-                    // undetermined reconnect withholds graph tools exactly as before. Only
-                    // the reported observation changes.
-                    const tabReconnect = classifyTabReconnect({
-                        serverReady: recovery.ready,
-                        baselineCaptured: preRestartPanelIdentity != null,
-                        tabBack,
-                    });
-                    return ok({
-                        rebooting: true,
-                        ready: graphToolsReady,
-                        graph_tools_ready: graphToolsReady,
-                        server_ready: recovery.ready,
-                        panel_tab_reconnected: tabReconnect,
-                        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: 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
-                                    ? tabReconnect === "unknown"
-                                        ? "whether the panel tab reconnected could NOT be determined — no pre-restart " +
-                                            "baseline was captured for it, so nothing was watched. WHY is not established " +
-                                            "here, and it is one of: the tab's socket was not open at the instant the " +
-                                            "restart was dispatched; the panel advertised no tab session id (an older " +
-                                            "build, or its browser-tab lease was refused because a duplicate tab holds " +
-                                            "it); or the tab did not resolve at all. The tab may well be back. Graph " +
-                                            "tools are withheld (ready:false) because that is unproven, NOT because the " +
-                                            'tab is known to be gone: call panel_list_workflows or panel_set_workflow_target({mode:"current"}) ' +
-                                            "to find out, and only refresh the browser if those also fail. If this " +
-                                            "repeats on every restart, the panel is probably too old to advertise a tab " +
-                                            "session id — update it."
-                                        : "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 get_system_stats (action:"health") / panel_node_queue_status before assuming it restarted.`),
+                    return runHeadlessManagedRestart({
+                        healthBase,
+                        preRestartPanelIdentity,
+                        why: "The built-in Manager exposed no reboot endpoint (legacy Manager 3.x)",
+                        mechanism: "the headless managed restart (kill + relaunch)",
+                        noteHealthyLead: "ComfyUI-Manager (legacy 3.x) had no reboot endpoint; the headless managed restart",
+                        noteRanLead: "ComfyUI-Manager (legacy 3.x) had no reboot endpoint; ran the headless managed " +
+                            "restart (kill + relaunch)",
                     });
                 }
                 // Genuine refusal (busy guard / security / no eligible fallback) — return