comfyui-mcp 0.48.21 → 0.48.23

package/dist/orchestrator/panel-tools.js

@@ -23,22 +23,24 @@
 // gating for panel_clear/panel_restart_comfyui) is IDENTICAL across providers,
 // so parity is automatic — neither path reimplements a tool.
 import { z } from "zod";
+import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { extname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { comfyuiFetch } from "../comfyui/fetch.js";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { parse as parseYaml } from "yaml";
+import { dispatchOutcomeOf } from "../services/ui-bridge.js";
 import { withWorkflowTarget, } from "../services/workflow-target-store.js";
 import { addUserMcpServer, readUserMcpServers, removeUserMcpServer, setUserMcpServerSecret, } from "../services/user-mcp-config.js";
 import { setComfyuiSecret, setAgentSecret, isAllowedAgentSecretKey } from "../services/panel-secrets.js";
 import { flattenUiWorkflow } from "../services/flatten-workflow.js";
 import { getNsfwConsent, setNsfwConsent } from "../services/panel-settings.js";
 import { QueueMonitor } from "../services/queue-monitor.js";
-import { getObjectInfo, backfillObjectInfo, resetClient, resetObjectInfoCache, } from "../comfyui/client.js";
+import { getClient, getObjectInfo, backfillObjectInfo, resetClient, resetObjectInfoCache, } from "../comfyui/client.js";
 import { convertUiToApi, collectNodeTypes } from "../services/workflow-converter.js";
 import { restartComfyUI } from "../services/process-control.js";
-import { isRemoteMode } from "../config.js";
+import { isRemoteMode, isCloudMode, getBootLocalComfyUIBaseUrl, getComfyUIBaseUrl, } from "../config.js";
 import { sliceWorkflow } from "../services/workflow-slicer.js";
 import { validateA2UISpecServer } from "../services/a2ui-spec.js";
 /** Treat these as an affirmative answer to the adult-content consent card. */
@@ -81,29 +83,31 @@ export function rebootConfirmed(res) {
     }
 }
 /**
- * True when a comfy_reboot ToolResult is an ERROR whose text is the EXPECTED
- * connection drop of a server going down (the reboot handler exits the instant it
- * accepts the request, so the browser tab's socket dies before it can ack). This
- * is the SUCCESS signal of a reboot, NOT a failure — the bridge surfaces it as a
- * mid-command "OUTCOME UNKNOWN" / "disconnected" / "not open" / "did not reply"
- * error. Distinguished from a genuine refusal, which comes back as a NON-error
- * ToolResult carrying `rebooting:false` (handled by rebootConfirmed instead).
+ * True when a comfy_reboot ToolResult is the bridge's canonical POST-WRITE mid-command
+ * drop — the command was ACTUALLY WRITTEN to the panel socket and the connection then
+ * died before a reply (the reboot handler exits the instant it accepts, so the socket
+ * dies mid-flight). The bridge emits this for a MUTATING command as
+ * "disconnected mid-command … OUTCOME UNKNOWN" (ui-bridge.ts handleMidCommandDisconnect).
+ *
+ * Deliberately NOT matched (coordinator P0): a raw PRE-WRITE `sock.send()` failure
+ * (ECONNRESET / socket hang up / EPIPE / "was NOT dispatched") — that means the command
+ * was NEVER written, so NOTHING was dispatched. Treating a pre-write send failure as an
+ * accepted/ambiguous "dropped reboot" would let readiness certify a cycle that was never
+ * even requested. Also NOT matched: pre-dispatch "is not open" / "did not reply within N
+ * ms" (a live-but-frozen tab) / idempotent-read grace expiry — those return verbatim.
+ * A genuine refusal comes back as a NON-error `rebooting:false` (rebootConfirmed handles).
  */
 export function rebootDropped(res) {
     if (!res?.isError)
         return false;
     const text = res?.content?.find((c) => c.type === "text")?.text ?? "";
-    // Match ONLY signals that the command we JUST sent (comfy_reboot) died IN
-    // FLIGHT — i.e. the reboot was accepted and the origin went down before it
-    // could ack. The bridge's mutating-command mid-flight drop is the canonical
-    // one ("disconnected mid-command … OUTCOME UNKNOWN", ui-bridge.ts), plus raw
-    // socket resets. Deliberately NOT matched: pre-dispatch / generic errors like
-    // "is not open" (socket already closed BEFORE we sent — no reboot happened),
-    // "did not reply within N ms" (a live-but-frozen/backgrounded tab), and the
-    // idempotent-read "genuinely gone" grace expiry. Treating those as a reboot
-    // would risk a FALSE success (claiming a restart that never fired) once an
-    // unrelated tab reconnection makes readiness pass. Those return verbatim.
-    return /disconnected mid-command|OUTCOME UNKNOWN|ECONNRESET|socket hang up|premature close|other side closed|ECONNABORTED|EPIPE/i.test(text);
+    // The AUTHORITATIVE signal is the bridge's TYPED dispatch flag (dispatchOutcomeOf),
+    // checked by the caller BEFORE this. This text match is a defense-in-depth fallback:
+    // the pre-write wrapper ("the command was NOT dispatched") must WIN even if its quoted
+    // detail contains a post-write phrase, so a pre-write send failure is never a "drop".
+    if (/NOT dispatched/i.test(text))
+        return false;
+    return /disconnected mid-command|OUTCOME UNKNOWN/i.test(text);
 }
 /**
  * True when a comfy_reboot ToolResult is a NON-error, NON-fired refusal whose
@@ -130,6 +134,12 @@ export function rebootNoEndpoint(res) {
     return /reboot endpoint|reboot route|was NOT restarted|no reachable .*reboot/i.test(text);
 }
 let panelRebootTimingOverride = null;
+// The whole readiness wait (settle + poll budget) MUST finish comfortably below the
+// client's outer ~300s tools/call timeout, so a FAILING wait always returns a clean
+// ready:false in time instead of being killed as a bare 300s timeout — even if the
+// COMFYUI_PANEL_REBOOT_* env overrides are set absurdly high (coordinator codex P2).
+const MAX_REBOOT_SETTLE_MS = 10_000; // 10s
+const MAX_REBOOT_BUDGET_MS = 240_000; // 240s  → settle+budget ≤ 250s < 300s outer
 function parsePositiveNumberEnv(name, fallback) {
     const raw = process.env[name];
     if (raw == null || raw === "")
@@ -137,16 +147,23 @@ function parsePositiveNumberEnv(name, fallback) {
     const n = Number(raw);
     return Number.isFinite(n) && n > 0 ? n : fallback;
 }
-function getPanelRebootTiming() {
-    if (panelRebootTimingOverride)
-        return panelRebootTimingOverride;
+/** Reboot-readiness timing from env, with each value HARD-CAPPED so no override can
+ *  push the total wait past the outer tools/call budget (coordinator codex P2).
+ *  The probe interval defaults to a TIGHT 500ms: the observer runs CONCURRENTLY with
+ *  the reboot dispatch and must catch a BRIEF down window (a fast restart can be down
+ *  for well under 2s), needing >=2 down probes inside it (coordinator HIGH). settleMs
+ *  is retained only for the env cap; the observer no longer settles before probing. */
+function computeRebootTimingFromEnv() {
     return {
-        settleMs: Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_REBOOT_SETTLE_S", 3) * 1000),
-        budgetMs: Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_REBOOT_BUDGET_S", 120) * 1000),
-        intervalMs: Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_REBOOT_INTERVAL_S", 2) * 1000),
-        probeTimeoutMs: Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_REBOOT_PROBE_S", 5) * 1000),
+        settleMs: Math.min(MAX_REBOOT_SETTLE_MS, Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_REBOOT_SETTLE_S", 3) * 1000)),
+        budgetMs: Math.min(MAX_REBOOT_BUDGET_MS, Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_REBOOT_BUDGET_S", 120) * 1000)),
+        intervalMs: Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_REBOOT_INTERVAL_S", 0.2) * 1000),
+        probeTimeoutMs: Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_REBOOT_PROBE_S", 2) * 1000),
     };
 }
+function getPanelRebootTiming() {
+    return panelRebootTimingOverride ?? computeRebootTimingFromEnv();
+}
 /** The default generous readiness budget, in seconds — reported to callers. */
 export function panelRebootBudgetSeconds() {
     return Math.round(getPanelRebootTiming().budgetMs / 1000);
@@ -156,12 +173,31 @@ export const __panelToolsTestHooks = {
     setPanelRebootTiming(timing) {
         panelRebootTimingOverride = timing;
     },
+    /** Inject a fake boot-endpoint probe so readiness tests drive the real proof loop
+     *  without real HTTP. Returns a ProbeStatus, or a boolean (true→healthy/false→down)
+     *  so DOWN→UP can be scripted with plain booleans. null restores the live probe. */
+    setHealthProbe(fn) {
+        healthProbeOverride = fn;
+    },
+    looksLikeSystemStats,
+    probeComfyHealth,
+    probeComfyEndpoint,
+    captureRebootHealthBase,
+    sameHttpOrigin,
+    sameHttpBase,
+    isLoopbackOrigin,
+    loopbackProbeUrl,
+    /** Compute reboot timing from env WITH the P2 hard caps (bypasses any override). */
+    computeRebootTimingFromEnv,
     /** Zero out the post-drop retry settle so retry-once tests don't sleep. */
     setRetrySettleMs(ms) {
         retrySettleMsOverride = ms;
     },
     isRetrySafeCmd,
     isTransientReconnectError,
+    // #384 live-canvas capture fallback (defined later in the module).
+    reconstructUiFromState: (reply) => reconstructUiFromState(reply),
+    resolveWorkflowInput: (args, ctx, allowStateFallback = true) => resolveWorkflowInput(args, ctx, allowStateFallback),
 };
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
@@ -221,43 +257,379 @@ function retrySettleMs() {
         return retrySettleMsOverride;
     return Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_RETRY_SETTLE_S", 0.4) * 1000);
 }
+/** True when a decoded /system_stats body has the recognizable ComfyUI shape (a
+ *  `system` object and/or a `devices` array) — the same fields health_check /
+ *  get_environment read. A bare 2xx from a reverse-proxy login page, an SPA
+ *  catch-all, or a proxy error page is NOT ComfyUI and must NOT certify recovery
+ *  (codex #509 P1). */
+function looksLikeSystemStats(body) {
+    if (!body || typeof body !== "object")
+        return false;
+    const b = body;
+    const hasSystem = b.system != null && typeof b.system === "object";
+    const hasDevices = Array.isArray(b.devices);
+    return hasSystem || hasDevices;
+}
+/** The CONCRETE loopback FAMILY of a hostname, or null when it isn't an unambiguous
+ *  loopback literal. IPv4 loopback (127.0.0.1 / the 0.0.0.0 wildcard) → "127.0.0.1";
+ *  IPv6 loopback (::1 / the :: wildcard) → "::1". The families are kept DISTINCT so a
+ *  v4 tab and a v6 instance at the same port are NOT wrongly matched (coordinator
+ *  finding 4: v6 A on [::1]:8188 + v4 B on 127.0.0.1:8188 are DIFFERENT instances).
+ *
+ *  `localhost` returns null ON PURPOSE (coordinator P0): a URL preserves the literal
+ *  "localhost" and does NOT reveal whether the browser actually reached 127.0.0.1 or
+ *  ::1 — so PINNING it to a family we can't verify could send the auth-bearing probe to
+ *  a DIFFERENT-family instance than the reboot went to (v6 A rebooted, v4 B probed →
+ *  false cert + auth leak). We therefore refuse the ambiguity: a `localhost` boot/tab
+ *  origin is NOT directly-probeable and routes to the honest dispatched-unconfirmed
+ *  result instead of the direct-probe certification path. */
+function loopbackFamily(host) {
+    const h = host.toLowerCase().replace(/^\[|\]$/g, "");
+    if (h === "127.0.0.1" || h === "0.0.0.0")
+        return "127.0.0.1";
+    if (h === "::1" || h === "::" || h === "0000:0000:0000:0000:0000:0000:0000:0000")
+        return "::1";
+    return null;
+}
+/** True when a hostname is loopback-equivalent (either family, incl. the wildcard
+ *  binds 0.0.0.0/:: which are reachable on loopback). */
+function isLoopbackHostName(host) {
+    return loopbackFamily(host) !== null;
+}
+/** The scheme://host:port origin of a URL (default ports made explicit), or null if
+ *  unparseable. Loopback hosts canonicalize to their FAMILY loopback (v4 → 127.0.0.1,
+ *  v6 → ::1) — so localhost/127.0.0.1/0.0.0.0 compare equal, and ::1/:: compare equal,
+ *  but a v4 host and a v6 host DIFFER (they may be different instances). Ports differ. */
+function httpOriginOf(rawUrl) {
+    try {
+        const u = new URL(rawUrl);
+        const port = u.port || (u.protocol === "https:" ? "443" : "80");
+        const host = u.hostname.toLowerCase();
+        const canonHost = loopbackFamily(host) ?? host;
+        return `${u.protocol}//${canonHost}:${port}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** Rewrite a CONCRETE loopback-literal base URL to one that is actually CONNECTABLE and
+ *  that AGREES with loopbackFamily's identity canonicalization — so the probe (and the
+ *  auth headers it carries) can never hit a DIFFERENT-family instance than the one
+ *  identity matched (coordinator P1). Every IPv4-family loopback literal (127.0.0.1 /
+ *  0.0.0.0) → the literal 127.0.0.1; every IPv6-family loopback literal (::1 / ::) → the
+ *  bracketed literal [::1]. A DNS-ambiguous `localhost` has no concrete family and is
+ *  left UNCHANGED (callers gate it out via loopbackFamily before probing). Non-loopback
+ *  hosts are returned unchanged. */
+function loopbackProbeUrl(rawUrl) {
+    try {
+        const u = new URL(rawUrl);
+        const fam = loopbackFamily(u.hostname);
+        if (fam === "127.0.0.1")
+            u.hostname = "127.0.0.1";
+        else if (fam === "::1")
+            u.hostname = "[::1]";
+        return u.toString().replace(/\/+$/, "");
+    }
+    catch {
+        return rawUrl;
+    }
+}
+/** True when two URLs share the exact same scheme + host + port (path ignored).
+ *  Used ONLY for the redirect host-escape check — a same-host redirect isn't a
+ *  host escape. Instance IDENTITY uses sameHttpBase (path-aware) instead. */
+function sameHttpOrigin(a, b) {
+    const oa = a ? httpOriginOf(a) : null;
+    const ob = b ? httpOriginOf(b) : null;
+    return oa != null && oa === ob;
+}
+/** The canonical scheme://host:port/path form of a URL (loopback host normalized,
+ *  trailing slashes stripped, path case-sensitive), or null if unparseable. Two
+ *  ComfyUI instances reverse-proxied under the SAME host:port but DIFFERENT path
+ *  prefixes (/a vs /b) are DISTINCT — so instance identity must include the path. */
+function canonicalHttpBase(rawUrl) {
+    const origin = httpOriginOf(rawUrl);
+    if (origin == null)
+        return null;
+    try {
+        const path = new URL(rawUrl).pathname.replace(/\/+$/, "");
+        return `${origin}${path}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when two URLs identify the SAME instance: same scheme+host+port AND the
+ *  same path prefix (a reverse-proxied mount point is part of its identity). */
+function sameHttpBase(a, b) {
+    const ca = a ? canonicalHttpBase(a) : null;
+    const cb = b ? canonicalHttpBase(b) : null;
+    return ca != null && ca === cb;
+}
+/** True when a URL's host is loopback-EQUIVALENT (incl. the wildcard binds 0.0.0.0/::,
+ *  which are reachable on loopback) — the only hosts the orchestrator can reach on its
+ *  OWN machine to health-probe (the #509 local case). */
+function isLoopbackOrigin(rawUrl) {
+    try {
+        return isLoopbackHostName(new URL(rawUrl).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** Connection error codes that DEFINITIVELY mean the endpoint's PORT is not accepting —
+ *  the listener is gone (a restarting process closed it). This is the ONLY connection
+ *  failure that proves a process-down for the cycle proof, and for a LOOPBACK probe the
+ *  ONLY sound one: ECONNREFUSED = the host actively refused the connection because nothing
+ *  is listening on that port. Everything else is (correctly) NOT a listener-down:
+ *   - ECONNRESET / EPIPE / EPROTO / ETIMEDOUT / "socket hang up" — a still-LISTENING server
+ *     can reset a connection or transiently fail TLS without going down;
+ *   - ENETUNREACH / EHOSTUNREACH / ENETDOWN / EHOSTDOWN — a local network/routing failure;
+ *     the ComfyUI process can still be listening while the stack is momentarily unavailable
+ *     (codex High);
+ *   - ENOTFOUND / EAI_AGAIN — DNS (inapplicable to a loopback literal), not a listener-down.
+ *  A genuine restart CLOSES the loopback port, so repeated polling observes ECONNREFUSED
+ *  during the down window; the ambiguous codes above stay "unknown" so a transient glitch
+ *  + a later 200 can never fake a restart cycle. */
+const PORT_NOT_LISTENING_CODES = new Set([
+    "ECONNREFUSED", // host refused — nothing listening on the port (the restarting-process signal)
+]);
+/** Extract a connection error's OS code (undici wraps the real error under `.cause`). */
+function connErrorCode(err) {
+    const e = err;
+    if (typeof e?.code === "string")
+        return e.code;
+    if (typeof e?.cause?.code === "string")
+        return e.cause.code;
+    return undefined;
+}
+/**
+ * Probe the boot endpoint and CLASSIFY it. Because the down→up transition is the SOLE
+ * proof a process actually CYCLED, "down" must mean the endpoint STOPPED SERVING at the
+ * CONNECTION level — the port isn't accepting (a restarting process closes its listener).
+ * The boot endpoint in the certify path is a DIRECT loopback ComfyUI (no reverse proxy —
+ * captureRebootHealthBase probes 127.0.0.1/[::1] directly), so:
+ *   - "down" = a CONNECTION failure whose code DEFINITIVELY means the port isn't accepting
+ *     (ECONNREFUSED — the process is not listening, a genuine restart). Ambiguous
+ *     mid-connection errors (ECONNRESET / EPIPE / EPROTO / hang up) and network/DNS
+ *     reachability failures (ENETUNREACH / EHOSTUNREACH / ENOTFOUND …) do NOT count — the
+ *     server can still be listening — so they are "unknown". ECONNREFUSED is the ONLY
+ *     signal that proves a cycle.
+ *   - "healthy" = a same-origin 2xx carrying a real /system_stats body.
+ *   - "unknown" = the server RESPONDED (so its HTTP listener is UP — NOT a process-down),
+ *     just not as ComfyUI-up-and-serving-stats: ANY 5xx (a transient 500 is an app error,
+ *     NOT a restart — codex false-success fix), a 3xx (redirect:"manual", so a login/SPA
+ *     redirect can't certify and no auth is sent onward), a 4xx (401/403/404/429), a
+ *     wrong-origin URL, or a 2xx with a non-ComfyUI / malformed body; AND our own request
+ *     TIMEOUT (the port accepted the connection but was slow to answer → listening, not
+ *     down). "unknown" is NOT a down and NEVER contributes to the cycle proof — so a
+ *     transient 5xx / slow response can never masquerade as a restart.
+ * Never throws.
+ */
+async function probeComfyEndpoint(base, timeoutMs) {
+    if (!base)
+        return "unknown";
+    const url = `${base}/system_stats`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.max(1, timeoutMs));
+    timer.unref?.();
+    try {
+        const res = await comfyuiFetch(url, { signal: controller.signal, redirect: "manual" });
+        const status = res.status;
+        // A 5xx means the HTTP server ANSWERED — its listener is UP — so it is NOT proof the
+        // process went down; treat it as "unknown", never "down" (a transient 500 must not
+        // fake a restart cycle). Same for 3xx/4xx.
+        if (status < 200 || status >= 300)
+            return "unknown"; // 3xx/4xx/5xx = responded, not stats
+        if (res.url && !sameHttpOrigin(res.url, url))
+            return "unknown"; // wrong origin
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            return "unknown"; // 2xx but not JSON — up, but not a /system_stats we trust
+        }
+        return looksLikeSystemStats(body) ? "healthy" : "unknown";
+    }
+    catch (err) {
+        // OUR abort = a TIMEOUT: the port accepted the connection but was slow to answer, so
+        // its listener is UP (not a process-down) → "unknown", never part of a cycle proof (a
+        // transiently-slow no-op server must not fake a restart).
+        if (controller.signal.aborted)
+            return "unknown";
+        // A connection failure is "down" ONLY when its code DEFINITIVELY means the port isn't
+        // accepting (ECONNREFUSED &c). An AMBIGUOUS mid-connection error (ECONNRESET / EPIPE /
+        // EPROTO / hang up) can come from a STILL-listening server, so it is "unknown" — never
+        // a down that a later 200 could turn into a phantom cycle (codex High).
+        const code = connErrorCode(err);
+        return code != null && PORT_NOT_LISTENING_CODES.has(code) ? "down" : "unknown";
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Boolean healthy? wrapper over probeComfyEndpoint (redirect-safe). */
+async function probeComfyHealth(base, timeoutMs) {
+    return (await probeComfyEndpoint(base, timeoutMs)) === "healthy";
+}
+/** Coerce a health-probe override's boolean (true→healthy / false→down) or an explicit
+ *  ProbeStatus, so tests can script recovery sequences with plain booleans. */
+function normalizeProbe(v) {
+    if (v === true)
+        return "healthy";
+    if (v === false)
+        return "down";
+    return v;
+}
+/**
+ * The FIXED ComfyUI base URL to health-probe during a reboot readiness wait, or
+ * null when we must fall back to the panel round-trip (as before #509). Captured by
+ * the handler BEFORE it dispatches comfy_reboot and held for the whole wait.
+ *
+ * SECURITY (coordinator codex P1): the probe TARGET is the orchestrator's own
+ * PROCESS-START local ComfyUI endpoint (getBootLocalComfyUIBaseUrl) — captured at
+ * boot and IMMUTABLE. It is deliberately NOT getComfyUIBaseUrl(): that reflects the
+ * mutable runtime config a panel `hello` can retarget (applyComfyuiUrl →
+ * setComfyuiTarget), so a client could steer it. And it is NEVER the client-advertised
+ * `hello.comfyui_url` (spoofable; comfyuiFetch would leak the configured ComfyUI auth
+ * headers to an attacker-chosen origin). The tab origin is used ONLY as a gate, and the
+ * gate reads the SERVER-OBSERVED handshake Origin (tabServerOrigin) — which the browser
+ * sets and blocks page JS from forging — NOT the spoofable hello.comfyui_url: we
+ * self-probe our OWN boot endpoint solely when the rebooted tab PROVABLY (by its
+ * handshake) fronts THAT SAME instance, so a socket that merely CLAIMS the boot URL can't
+ * ride an unrelated boot-instance cycle to a false certification (codex High). Null
+ * (→ honest dispatched-unconfirmed) when:
+ *   - cloud OR remote mode; or
+ *   - the orchestrator didn't boot against a LOCAL loopback ComfyUI; or
+ *   - the tab isn't SERVER-TRUSTED-local (tabIsLocal — arrived on the token-less
+ *     loopback primary listener; relay/tunnel/LAN/pairing → false); or
+ *   - the tab's HANDSHAKE origin is absent, ambiguous (`localhost`), or does NOT match our
+ *     boot endpoint by scheme+host+port (concrete-family loopback-canonicalized) — i.e. it
+ *     drives a DIFFERENT instance / family, or one we can't verify; AND, because a handshake
+ *     Origin carries NO path, a boot target mounted under a basePath fails path-aware
+ *     identity and is (soundly) fail-closed to dispatched-unconfirmed.
+ */
+function captureRebootHealthBase(ctx) {
+    if (isCloudMode() || isRemoteMode())
+        return null;
+    const bootBase = getBootLocalComfyUIBaseUrl(); // server-authorized, hello-immutable
+    if (!bootBase || !isLoopbackOrigin(bootBase))
+        return null;
+    const base = bootBase.replace(/\/+$/, "");
+    // Server-trusted provenance: the tab arrived on the token-less loopback listener.
+    if (ctx.bridge?.tabIsLocal?.(ctx.tabId) !== true)
+        return null;
+    // And the rebooted tab must provably front THAT SAME boot instance. Use the SERVER-
+    // OBSERVED handshake Origin (tabServerOrigin) — the browser sets it on the WS upgrade
+    // and blocks page JS from forging it — NOT the spoofable client hello.comfyui_url
+    // (tabOrigin): a non-Comfy socket on the host could otherwise CLAIM the boot URL, ack
+    // comfy_reboot without rebooting, and ride an unrelated boot-instance cycle to a false
+    // ready:true (codex High). A handshake Origin proves only scheme+host+port (it carries
+    // NO path), so we compare it path-AWARE (sameHttpBase) against the boot base: when the
+    // boot target is mounted under a basePath (e.g. …:8188/comfy) the pathless Origin cannot
+    // prove the tab fronts THAT mount vs another instance at the same host:port, so we FAIL
+    // CLOSED to the honest dispatched-unconfirmed result rather than certify unsoundly (codex
+    // P1). The common pathless boot base matches an equal Origin and certifies. Loopback
+    // identity canonicalizes only CONCRETE literals by family (127.0.0.1 ≡ a 0.0.0.0 bind;
+    // ::1 ≡ a :: bind) — a DNS-ambiguous `localhost` on EITHER side yields no family
+    // (loopbackFamily → null), so it never matches a concrete literal and this returns null
+    // (coordinator P0). A different instance / family / path / absent Origin → null too.
+    const origin = ctx.bridge?.tabServerOrigin?.(ctx.tabId);
+    if (!sameHttpBase(origin, base))
+        return null;
+    // Return a CONNECTABLE probe URL bound to the SAME concrete family identity matched
+    // above: a wildcard-bound (0.0.0.0/::) local ComfyUI is reachable on loopback, so probe
+    // the family literal at that port (127.0.0.1 / [::1]). The probe (and the auth headers
+    // it carries) can therefore never cross to a different-family instance.
+    return loopbackProbeUrl(base);
+}
+let healthProbeOverride = null;
 /**
- * Poll the panel bridge until ComfyUI is reachable again after a reboot. Each probe
- * is a lightweight `nodes_queue_status` round-trip (via ctx.call, which never
- * throws — it returns an isError ToolResult while the tab/backend is down and
- * auto-heals onto the reconnected tab once it returns). Resolves ready:true on the
- * first successful probe (with how long recovery took), or ready:false when the
- * server never comes back within the bounded budget.
+ * Observe the boot endpoint's recovery AFTER a reboot was dispatched, and certify ONLY on
+ * an OBSERVED DOWN→UP cycle. Acceptance (dispatch confirmed/dropped) is the guard against
+ * a NO-OP, but we deliberately do NOT certify a lone healthy endpoint after a settle:
+ * the panel emits rebooting:true even when it merely INFERS a reboot from a dropped fetch
+ * (its comfy_reboot handler's catch branch), so a confirmed ack is NOT a guarantee that a
+ * real Manager reboot was accepted — treat it like the ambiguous DROP and require the
+ * endpoint to actually go DOWN then come back (coordinator: panel invariant unverifiable).
+ *   - ANY single "down" (an ECONNREFUSED — the port stopped listening) marks it going down;
+ *     the next "healthy" → observed-cycle.
+ *   - Never healthy after an observed down, OR never a down at all → couldn't-confirm.
+ *
+ * CONCURRENT mode (a `gate` is supplied): the caller starts this BEFORE awaiting the full
+ * dispatch, so probes are already sampling the endpoint DURING the ack/drop/timeout window
+ * — catching a FAST reboot whose down→up completes before the ack returns (the #509 fast-
+ * reboot false-timeout). PROBE-FIRST-THEN-SLEEP: the observer AWAITS the post-write
+ * notification (gate.waitDispatched — no timer poll, so no leading window in which a
+ * sub-millisecond cycle could be missed), then takes its FIRST probe IMMEDIATELY at the
+ * post-write dispatch instant (no leading interval sleep), sleeping intervalMs only BETWEEN
+ * subsequent probes. COUNTING stays post-write: a sample
+ * marks the cycle only if taken at/after gate.dispatchedAt, so a pre-dispatch down never
+ * contributes. gate.deadline is the live deadline (tightened to ack-completion + budget so a
+ * slow ack doesn't eat it); gate.cancelled aborts.
+ * LEGACY mode (no gate): started AFTER the restart's synchronous work; probe immediately
+ * against the fixed `deadline`.
  */
-async function waitForPanelReady(ctx, timing) {
-    if (timing.settleMs > 0)
-        await sleep(timing.settleMs);
+async function observeRecovery(timing, deadline, opts) {
     const start = Date.now();
-    // Enforce an ABSOLUTE wall-clock deadline so the total wait honours budgetMs —
-    // NOT budgetMs/intervalMs iterations that each also burn a probe timeout + a
-    // sleep (which would overrun the advertised bound several-fold). Each probe and
-    // each inter-probe sleep is capped by the time remaining.
-    const deadline = start + timing.budgetMs;
-    // Clamp interval to a floor so a 0/tiny env value can't hot-loop unbounded —
-    // UNLESS a test override is active (tests inject small deterministic values).
+    const gate = opts.gate;
     const intervalMs = panelRebootTimingOverride
         ? Math.max(1, timing.intervalMs)
-        : Math.max(250, timing.intervalMs);
+        : Math.max(50, timing.intervalMs);
+    const probe = healthProbeOverride ?? probeComfyEndpoint;
+    const currentDeadline = () => gate?.deadline ?? deadline;
+    let sawDown = false;
     let attempts = 0;
     for (;;) {
-        const remaining = deadline - Date.now();
-        const probeTimeoutMs = Math.max(1, Math.min(timing.probeTimeoutMs, remaining));
-        const probe = await ctx.call({ cmd: "nodes_queue_status" }, probeTimeoutMs);
+        if (gate?.cancelled)
+            break;
+        if (currentDeadline() - Date.now() <= 0)
+            break;
+        if (gate && !gate.dispatched) {
+            // CONCURRENT mode, not yet dispatched: AWAIT the post-write NOTIFICATION (resolves the
+            // microtask after the socket write) WITHOUT probing — no timer poll, so there is NO
+            // leading window in which a sub-millisecond down→up could be missed (codex). The very
+            // first probe then fires the instant the command is dispatched (probe-first).
+            await gate.waitDispatched;
+            if (gate.cancelled)
+                break;
+            // Fall through and probe immediately (a fast non-accepted outcome that resolves before
+            // this observer wakes will already have set gate.cancelled above; otherwise a single
+            // read of our OWN boot endpoint during the sub-ack window is the accepted benign
+            // residual — see the handler's INHERENT TRADEOFF note — and is discarded on refusal).
+        }
+        // PROBE NOW (no leading interval sleep) — the first sample lands at the post-write
+        // dispatch instant so a sub-interval down→up is caught (coordinator: probe-first).
+        const sampleAt = Date.now();
         attempts++;
-        if (!probe.isError) {
-            return { ready: true, waited_ms: Date.now() - start, attempts };
+        const t = Math.max(1, Math.min(timing.probeTimeoutMs, currentDeadline() - Date.now()));
+        let status = "unknown";
+        try {
+            status = normalizeProbe(await probe(opts.healthBase, t));
         }
-        const left = deadline - Date.now();
+        catch {
+            status = "unknown";
+        }
+        if (gate?.cancelled)
+            break;
+        // COUNTING gate: a sample contributes to the cycle only if taken at/after the post-write
+        // dispatched instant (defensive — the observer also defers its first probe to dispatch).
+        if (gate == null || sampleAt >= gate.dispatchedAt) {
+            if (status === "down") {
+                sawDown = true;
+            }
+            else if (status === "healthy" && sawDown) {
+                return { ready: true, waited_ms: Date.now() - start, attempts, via: "observed-cycle", sawDown };
+            }
+            // "healthy" without a prior down, and "unknown", are ignored — keep looking.
+        }
+        // Sleep BETWEEN probes (both modes).
+        const left = currentDeadline() - Date.now();
         if (left <= 0)
             break;
         await sleep(Math.min(intervalMs, left));
     }
-    return { ready: false, waited_ms: Date.now() - start, attempts };
+    return { ready: false, waited_ms: Date.now() - start, attempts, sawDown };
 }
 // ---- workflow_open verify-after-timeout (#215/#319/#496) --------------------
 // `panel_open_workflow` forwards `workflow_open` over the UI bridge and waits for
@@ -267,7 +639,7 @@ async function waitForPanelReady(ctx, timing) {
 // genuinely happened (the executor ran; the ack just didn't make it back in the
 // window). Reporting that as a failure is a FALSE FAILURE: a follow-up
 // `workflow_list` shows the target IS the active tab, and it invites unsafe
-// retries. Mirroring the reboot-readiness pattern (waitForPanelReady / #497), on
+// retries. Mirroring the reboot-readiness pattern (observeRecovery / #497), on
 // an ack-timeout we do NOT immediately fail — we VERIFY the AUTHORITATIVE active
 // workflow by polling `workflow_list` (a fresh bridge round-trip, never a stale
 // cache) and return SUCCESS with a `recovered` note if the target became active,
@@ -505,9 +877,11 @@ async function openWorkflowWithVerify(path, ctx) {
 /**
  * Resolve a caller-supplied pin `path` (path / filename / key, any form) to the
  * AUTHORITATIVE open-workflow record from a fresh `workflow_list` — the single
- * source of truth for which tabs exist and their canonical `key` (#259). Returns:
- *  - the matched record when the workflow IS open (so the pin can be canonicalized
- *    to its stable key and bound to the exact frontend tab identity);
+ * source of truth for which tabs exist, their canonical `key`, and which one is
+ * ACTIVE (#259). Returns:
+ *  - a {record, isActive} pair when the workflow IS open (so the caller can
+ *    canonicalize the pin to its stable key AND reject a background target that the
+ *    panel could never route to — #556/#571);
  *  - `null` when workflow_list is unreachable/empty or carries no `workflows`
  *    array (indeterminate — caller should fall back to the raw path, NOT fail);
  *  - the sentinel `NOT_OPEN` when the list IS known but the target is absent, so
@@ -530,16 +904,141 @@ async function resolveOpenWorkflow(ctx, path) {
         // No enumerable tab list (older panel / stub) — can't verify, don't fail closed.
         return null;
     }
-    for (const wf of rawList) {
-        if (activeMatchesTarget(wf, path))
-            return wf;
+    const activeObj = parsed.active;
+    const activeLabel = workflowRecordLabel(activeObj);
+    // A caller token (path / filename / key) can match MORE THAN ONE open record —
+    // e.g. two tabs share the filename "A.json" from different dirs, or two never-saved
+    // tabs. Selecting the wrong same-token record and then reading its `active` flag would
+    // misjudge active-ness (codex P1). So gather ALL matches and disambiguate toward the
+    // one that is actually the live canvas before deciding.
+    const matches = rawList.filter((wf) => activeMatchesTarget(wf, path));
+    let rec;
+    if (matches.length === 1) {
+        rec = matches[0];
+    }
+    else if (matches.length > 1) {
+        // Prefer an EXACT stable-identity (key/path) match to the caller token; then prefer
+        // the record that is the active canvas; otherwise leave it unresolved and let the
+        // active-object branch / NOT_OPEN handle it (never guess among ambiguous tabs).
+        const exact = matches.filter((m) => m.key === path || m.path === path);
+        const activePreferred = matches.filter((m) => m.active === true || recMatchesActive(m, activeObj));
+        rec = exact.length === 1 ? exact[0] : activePreferred.length === 1 ? activePreferred[0] : undefined;
+    }
+    if (rec) {
+        return { record: rec, isActive: computeIsActive(rec, activeObj), activeLabel };
     }
     // The active object is authoritative too, in case it isn't mirrored in the array.
-    if (activeMatchesTarget(parsed.active, path)) {
-        return parsed.active;
+    if (activeMatchesTarget(activeObj, path)) {
+        return { record: activeObj, isActive: true, activeLabel };
     }
     return NOT_OPEN;
 }
+/**
+ * Is `rec` the active canvas? TRI-STATE (#556/#571):
+ *  - the record's OWN `active` boolean is authoritative and immune to filename aliasing;
+ *  - else compare `rec` to the `active` object by STABLE identity (key/path/routing_key —
+ *    never filename alone, which can collide across tabs). This yields `true`/`false`
+ *    ONLY when the two share a COMPARABLE identity dimension;
+ *  - else (no per-record flag AND nothing comparable) → `undefined` (indeterminate): the
+ *    caller must stay lenient rather than fail a valid pin on an older/partial panel.
+ */
+function computeIsActive(rec, activeObj) {
+    if (typeof rec.active === "boolean")
+        return rec.active;
+    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).
+ */
+function identityVerdict(rec, activeObj) {
+    if (!activeObj || typeof activeObj !== "object")
+        return undefined;
+    const a = activeObj;
+    const r = rec;
+    const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+    const pairs = [
+        [r.key, a.key],
+        [r.path, a.path],
+        [r.routing_key, a.routing_key],
+        [r.key, a.routing_key],
+        [r.routing_key, a.key],
+    ];
+    let comparable = false;
+    for (const [x, y] of pairs) {
+        if (nonEmpty(x) && nonEmpty(y)) {
+            comparable = true;
+            if (x === y)
+                return true;
+        }
+    }
+    return comparable ? false : undefined;
+}
+/** Stable-identity match (positive only) — used to prefer the active record among matches. */
+function recMatchesActive(rec, activeObj) {
+    return identityVerdict(rec, activeObj) === true;
+}
+/** Best-effort human label for a workflow_list record/active object. */
+function workflowRecordLabel(rec) {
+    if (!rec || typeof rec !== "object")
+        return undefined;
+    const r = rec;
+    for (const v of [r.filename, r.title, r.path, r.key]) {
+        if (typeof v === "string" && v.trim())
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Validate and canonicalize a pin `path` to a routable target, SHARED by every entry
+ * point that writes a pinned workflow target (the MCP tool AND the panel-driven
+ * set_workflow_target event) so none can bypass the guarantees:
+ *  - FAIL CLOSED when the workflow isn't open (#259) — never route the pin to another tab;
+ *  - FAIL AT PIN TIME when it is open but NOT the active canvas (#556/#571) — the panel can
+ *    only read/edit the in-view workflow (panel #349/#186), so a background pin would only
+ *    defer a "workflow mismatch"; reject it honestly and immediately;
+ *  - otherwise canonicalize to the stable `key` (survives rename/reconnect);
+ *  - INDETERMINATE lists (older/partial panel — no `workflows` array, or no comparable
+ *    active identity) stay LENIENT: pin the raw path rather than fail a valid pin.
+ */
+export async function resolvePinTarget(ctx, path, filename) {
+    const resolved = await resolveOpenWorkflow(ctx, path);
+    if (resolved === NOT_OPEN) {
+        return {
+            ok: false,
+            error: `Cannot pin to "${path}" — it is not open in ComfyUI. Open it first ` +
+                `(panel_open_workflow) or pick an open workflow from panel_list_workflows, ` +
+                `then pin. (Refusing to pin to a workflow that isn't open so graph edits ` +
+                `never land on the wrong tab.)`,
+        };
+    }
+    if (resolved && resolved.isActive === false) {
+        const activeName = resolved.activeLabel ? ` (currently "${resolved.activeLabel}")` : "";
+        return {
+            ok: false,
+            error: `Cannot pin to "${filename ?? path}" — it is open but not the active canvas${activeName}. ` +
+                `The panel can only read or edit the workflow that is currently in view, so a background ` +
+                `pin would fail on your next panel_* graph call. To work on it, switch to it first with ` +
+                `panel_open_workflow (that makes it the active canvas), then pin — or, if you meant to ` +
+                `edit the workflow already in view, pin that one instead. (Pinning does not switch the ` +
+                `user's view and cannot route edits to a background tab.)`,
+        };
+    }
+    if (resolved) {
+        // Canonicalize to the stable key so routing survives rename/reconnect.
+        const rec = resolved.record;
+        return {
+            ok: true,
+            pinPath: rec.key ?? rec.path ?? path,
+            pinFilename: filename ?? rec.filename ?? rec.path,
+        };
+    }
+    // Indeterminate list — stay lenient (older/partial panel).
+    return { ok: true, pinPath: path, pinFilename: filename };
+}
 export const __openWorkflowTestHooks = {
     /** Inject fast open-verify timing so tests don't wait the real ~6s budget. */
     setOpenVerifyTiming(timing) {
@@ -671,51 +1170,116 @@ function comfyWorkflowsDirs() {
         join(base, "user", "workflows"),
     ];
 }
-/** Read + parse a UI workflow JSON from disk by path. Resolves an absolute path,
- *  OR a path relative to a ComfyUI workflows dir (COMFYUI_PATH/user/default/workflows,
- *  then user/workflows). Guards: must be .json, must exist/be readable, and must
- *  parse to a UI workflow (a top-level `nodes` array). */
-function readWorkflowFromPath(rawPath) {
+/** Validate a parsed value is a UI/litegraph workflow (a top-level `nodes`
+ *  array), throwing a source-labelled error otherwise. */
+function assertUiWorkflow(parsed, sourceLabel) {
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error(`${sourceLabel} did not parse to a workflow object.`);
+    }
+    if (!Array.isArray(parsed.nodes)) {
+        throw new Error(`${sourceLabel} is not a UI workflow (missing a top-level \`nodes\` array). ` +
+            `Provide a UI/litegraph workflow JSON, not API/prompt format.`);
+    }
+    return parsed;
+}
+/** Read + parse a UI workflow JSON by path. Resolves an ABSOLUTE path off the
+ *  orchestrator's disk, or a RELATIVE name authoritatively through the CONNECTED
+ *  ComfyUI's userdata API — which resolves under the server's RUNTIME
+ *  `--user-directory` (custom or default), so the RIGHT file always wins and a
+ *  stale same-named file under the guessed default dir can never shadow it
+ *  (#202). Only when the server can't serve the name (404 / unreachable) does it
+ *  fall back to the orchestrator's guessed local workflows dirs, so a
+ *  disk-staged file still opens. Guards: must be .json and must parse to a UI
+ *  workflow (a top-level `nodes` array). Fails loudly (never loads the wrong
+ *  file) when the name resolves nowhere. */
+async function readWorkflowFromPath(rawPath) {
     const p = (rawPath ?? "").trim();
     if (!p)
         throw new Error("Provide a non-empty `path` to a workflow .json file.");
     if (!/\.json$/i.test(p)) {
         throw new Error(`"${p}" is not a .json file — pass the path to a ComfyUI workflow JSON.`);
     }
-    // Build the candidate absolute paths to try, in order.
-    const candidates = [];
+    const readLocal = (resolved) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(resolved, "utf8"));
+        }
+        catch (err) {
+            throw new Error(`"${resolved}" is not valid JSON: ${err.message}`);
+        }
+        return assertUiWorkflow(parsed, `"${resolved}"`);
+    };
+    // ABSOLUTE path → the orchestrator's own disk, unchanged.
     if (isAbsolute(p)) {
-        candidates.push(resolve(p));
-    }
-    else {
-        // Relative to each ComfyUI workflows dir (the common case — a just-staged file).
-        for (const dir of comfyWorkflowsDirs())
-            candidates.push(resolve(dir, p));
-        // Also relative to the orchestrator's CWD as a last resort.
-        candidates.push(resolve(process.cwd(), p));
+        const resolved = resolve(p);
+        if (existsSync(resolved) && statSync(resolved).isFile())
+            return readLocal(resolved);
+        throw new Error(`No workflow file at "${p}". Looked under ${resolved}. ` +
+            `Pass an absolute path, or a name relative to the ComfyUI workflows folder.`);
     }
-    const resolved = candidates.find((c) => existsSync(c) && statSync(c).isFile());
-    if (!resolved) {
-        const where = isAbsolute(p)
-            ? candidates[0]
-            : `the ComfyUI workflows dir (${comfyWorkflowsDirs().join(" or ") || "COMFYUI_PATH not set"}) or an absolute path`;
-        throw new Error(`No workflow file at "${p}". Looked under ${where}. Pass an absolute path, or a name relative to the ComfyUI workflows folder.`);
-    }
-    let parsed;
+    let outcome;
     try {
-        parsed = JSON.parse(readFileSync(resolved, "utf8"));
+        const client = getClient();
+        const encoded = encodeURIComponent(`workflows/${p.replace(/^[\\/]+/, "")}`);
+        const res = await client.fetchApi(`/api/userdata/${encoded}`);
+        if (res.ok) {
+            // Read the body as TEXT and classify HERE so a malformed 2xx surfaces its
+            // OWN error (no fallback), while ComfyUI's "200 + EMPTY body = file does
+            // not exist" convention (some builds; see parseWorkflowLock) is treated as
+            // an ABSENCE that DOES allow the local fallback — not a malformed error.
+            const body = (await res.text()).trim();
+            if (body === "") {
+                outcome = { kind: "absent", detail: "was not in the ComfyUI userdata library (empty 200 response)" };
+            }
+            else {
+                try {
+                    outcome = { kind: "found", parsed: JSON.parse(body) };
+                }
+                catch (err) {
+                    outcome = { kind: "malformed", detail: err instanceof Error ? err.message : String(err) };
+                }
+            }
+        }
+        else if (res.status === 404) {
+            outcome = { kind: "absent", detail: "was not in the ComfyUI userdata library (HTTP 404)" };
+        }
+        else {
+            outcome = { kind: "refused", detail: `ComfyUI userdata library returned HTTP ${res.status}` };
+        }
     }
     catch (err) {
-        throw new Error(`"${resolved}" is not valid JSON: ${err.message}`);
+        outcome = {
+            kind: "unreachable",
+            detail: `ComfyUI userdata library was unreachable (${err instanceof Error ? err.message : String(err)})`,
+        };
     }
-    if (!parsed || typeof parsed !== "object") {
-        throw new Error(`"${resolved}" did not parse to a workflow object.`);
+    if (outcome.kind === "found") {
+        // A found-but-non-UI file must surface its own honest error, not silence.
+        return assertUiWorkflow(outcome.parsed, `The workflow "${p}" from the ComfyUI userdata library`);
     }
-    if (!Array.isArray(parsed.nodes)) {
-        throw new Error(`"${resolved}" is not a UI workflow (missing a top-level \`nodes\` array). ` +
-            `Provide a UI/litegraph workflow JSON, not API/prompt format.`);
+    if (outcome.kind === "malformed") {
+        throw new Error(`The workflow "${p}" in the ComfyUI userdata library is not valid JSON: ${outcome.detail}`);
     }
-    return parsed;
+    if (outcome.kind === "refused") {
+        // Server is reachable but did not serve the file — do NOT fall back to a
+        // possibly-stale local file; report the status honestly.
+        throw new Error(`Could not read "${p}" from the connected ComfyUI: ${outcome.detail}. ` +
+            `Pass an absolute path, or a name shown by panel_list_workflows.`);
+    }
+    // outcome.kind is "absent" (404) or "unreachable" — fall back to the
+    // orchestrator's guessed local workflows dirs (best-effort; only meaningful on
+    // a same-machine ComfyUI whose user-dir matches the default layout, or a file
+    // staged straight to disk).
+    const localCandidates = [
+        ...comfyWorkflowsDirs().map((dir) => resolve(dir, p)),
+        resolve(process.cwd(), p), // orchestrator CWD as a last local resort
+    ];
+    const local = localCandidates.find((c) => existsSync(c) && statSync(c).isFile());
+    if (local)
+        return readLocal(local);
+    throw new Error(`No workflow file at "${p}". It ${outcome.detail}, and it is not under the orchestrator's workflows ` +
+        `dir (${comfyWorkflowsDirs().join(" or ") || "COMFYUI_PATH not set"}). ` +
+        `Pass an absolute path, or a name shown by panel_list_workflows.`);
 }
 // IMPORTANT (Codex parity): use `z.array(z.number())` — NOT `z.tuple([...])` — for
 // fixed-length coordinate vectors. zod's `.tuple()` emits JSON-Schema draft-04
@@ -829,22 +1393,53 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
     // (We gate inside the tool because the SDK's canUseTool is bypassed under
     // bypassPermissions, which the panel agent runs in; the Codex HTTP path runs
     // approvalPolicy "never", so the same in-tool gate is the only safeguard.)
-    const confirm = async (question, header) => {
+    const confirm = async (question, header, timeoutMs) => {
+        // #360: the enclosing MCP `tools/call` is killed at ~300s. A hardcoded 300s
+        // card wait had ZERO margin below that budget — so an unanswered confirm blew
+        // the whole tool call (a transport timeout) instead of returning cleanly, and
+        // any late answer was lost. CLAMP the card deadline under the budget (the same
+        // getAskTiming() ceiling panel_ask uses for #486) and, on a reply-timeout,
+        // poll the bridge's late-reply buffer for a bounded grace so a slow-but-valid
+        // yes/no is still HONORED. A genuine no-answer returns "timeout" (reported
+        // honestly by the caller), never a silent decline.
+        const base = getAskTiming();
+        // A caller may pass a tighter WHOLE-confirm budget (#536: panel_restart bounds
+        // confirm+dispatch+readiness under the outer limit). Treat timeoutMs as the HARD
+        // ceiling on deadline+grace so we never overrun the caller's budget, while still
+        // never exceeding the ask clamp. Absent → the full clamp (deadline+grace).
+        const total = typeof timeoutMs === "number"
+            ? Math.max(1, Math.min(timeoutMs, base.deadlineMs + base.graceMs))
+            : base.deadlineMs + base.graceMs;
+        const deadlineMs = Math.max(1, Math.min(base.deadlineMs, total));
+        const graceMs = Math.max(0, total - deadlineMs);
+        const timing = { deadlineMs, graceMs, pollMs: base.pollMs };
+        const askId = randomUUID();
         try {
             ensureReachable();
             const reply = await bridge.send({
                 cmd: "ask_user",
+                ask_id: askId,
                 question,
                 header,
                 options: [
                     { label: "Yes, go ahead", description: "" },
                     { label: "No, cancel", description: "" },
                 ],
-            }, { tabId: ctx.tabId, timeoutMs: 300000 });
-            return isAffirmative(reply);
+            }, { tabId: ctx.tabId, timeoutMs: timing.deadlineMs });
+            return isAffirmative(reply) ? "yes" : "no";
         }
-        catch {
-            return false;
+        catch (err) {
+            // Only a card-reply TIMEOUT is recoverable/honest-as-timeout: poll the late
+            // buffer, then report "timeout" if still unanswered. Any other error (no
+            // panel, transport failure) → "no" so the destructive op is SKIPPED, exactly
+            // as the previous catch-all did.
+            if (isReplyTimeoutError(err)) {
+                const late = await pollLateAskReply(bridge, askId, timing);
+                if (late !== undefined)
+                    return isAffirmative(late) ? "yes" : "no";
+                return "timeout";
+            }
+            return "no";
         }
     };
     // EXPLICIT self-heal — see PanelToolCtx.rebindToActiveTab. Only rebinds when
@@ -880,11 +1475,90 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
  * what I have open" is the common ask, and requiring a save-to-disk round trip
  * first derailed real sessions (deleted placeholder files, 404 tabs).
  */
-async function resolveWorkflowInput(args, ctx) {
+/**
+ * Rebuild a UI-format workflow ({ nodes, links }) from the panel's back-compat
+ * `graph_get_state` reply (the #384 fallback). Each summarized node carries its
+ * widget values keyed BY NAME (`widgets`) and its inputs' upstream source
+ * (`connected_from`), so we materialize:
+ *   - nodes with `widgets_values` as the name→value OBJECT — convertUiToApi maps
+ *     those by name, which also sidesteps the positional widget-order pitfalls,
+ *   - a synthetic links array + per-input `link` ids from `connected_from`.
+ * Returns null when the reply has no usable nodes.
+ */
+function reconstructUiFromState(reply) {
+    const r = reply;
+    const nodesIn = r?.nodes;
+    if (!Array.isArray(nodesIn) || nodesIn.length === 0)
+        return null;
+    // graph_get_state caps at MAX_STATE_NODES (100) and flags the overflow. A
+    // truncated capture would silently yield an INCOMPLETE executable graph, so
+    // refuse it — the caller then surfaces the actionable "pass pack/path/graph"
+    // error rather than stripping a partial workflow.
+    if (r?.truncated === true)
+        return null;
+    if (typeof r?.node_count === "number" && r.node_count > nodesIn.length)
+        return null;
+    const uiNodes = nodesIn.map((raw) => {
+        const n = raw;
+        const mode = n.mode === "mute" ? 2 : n.mode === "bypass" ? 4 : 0;
+        return {
+            id: n.id,
+            type: n.type,
+            mode,
+            pos: [0, 0],
+            inputs: (n.inputs ?? []).map((inp) => ({
+                name: inp.name,
+                type: inp.type ?? "*",
+                link: null,
+            })),
+            outputs: (n.outputs ?? []).map((o) => ({
+                name: o.name,
+                type: o.type ?? "*",
+                links: [],
+            })),
+            widgets_values: n.widgets && typeof n.widgets === "object"
+                ? n.widgets
+                : [],
+            properties: {},
+            ...(n.title ? { title: n.title } : {}),
+        };
+    });
+    const byId = new Map(uiNodes.map((n) => [n.id, n]));
+    const links = [];
+    let linkId = 0;
+    nodesIn.forEach((raw, idx) => {
+        const inputs = raw.inputs ?? [];
+        const tgt = uiNodes[idx];
+        inputs.forEach((inp, slot) => {
+            const from = inp.connected_from;
+            if (!from || from.node_id == null || !byId.has(from.node_id))
+                return;
+            const id = ++linkId;
+            tgt.inputs[slot].link = id;
+            const srcNode = byId.get(from.node_id);
+            const srcSlot = from.output_slot ?? 0;
+            while (srcNode.outputs.length <= srcSlot) {
+                srcNode.outputs.push({ name: `out_${srcNode.outputs.length}`, type: "*", links: [] });
+            }
+            srcNode.outputs[srcSlot].links.push(id);
+            links.push([id, from.node_id, srcSlot, tgt.id, slot, inp.type ?? "*"]);
+        });
+    });
+    return { nodes: uiNodes, links };
+}
+async function resolveWorkflowInput(args, ctx, 
+// The live-canvas graph_get_state fallback (#384) is LOSSY: it reconstructs
+// only nodes/links/widgets (name-keyed) — no layout, groups, properties, or
+// subgraph definitions. That's fine for panel_strip_workflow (API/prompt output
+// for inspection/execution), but panel_flatten_workflow LOADS its result back
+// ONTO the canvas and panel_slice_workflow needs groups to find its seeds, so
+// they must NOT take this fallback — they keep the actionable "update your
+// panel" error instead. Only strip opts in.
+allowStateFallback = false) {
     if (args.pack)
         return readPackWorkflow(args.pack);
     if (args.path)
-        return readWorkflowFromPath(args.path);
+        return await readWorkflowFromPath(args.path);
     if (args.graph != null) {
         return (typeof args.graph === "string"
             ? JSON.parse(args.graph)
@@ -907,7 +1581,31 @@ async function resolveWorkflowInput(args, ctx) {
         });
     }
     catch (err) {
-        throw new Error(`Couldn't capture the live canvas (${err instanceof Error ? err.message : String(err)}). ` +
+        // #384: a panel too old to register graph_serialize (added at 0.11.4) still
+        // answers the back-compat `graph_get_state`. On an "Unknown command" rejection
+        // ONLY (a genuine transport/timeout error must surface as-is), fall back to it
+        // and reconstruct the graph so "strip the live canvas" works without a
+        // save-to-disk round trip.
+        const msg = err instanceof Error ? err.message : String(err);
+        if (allowStateFallback && /unknown command/i.test(msg)) {
+            try {
+                const target = ctx.workflowTarget?.get(ctx.tabId);
+                const stateCmd = target
+                    ? withWorkflowTarget({ cmd: "graph_get_state" }, target)
+                    : { cmd: "graph_get_state" };
+                const stateReply = await ctx.bridge.send(stateCmd, {
+                    tabId: ctx.tabId,
+                    timeoutMs: 30000,
+                });
+                const rebuilt = reconstructUiFromState(stateReply);
+                if (rebuilt)
+                    return rebuilt;
+            }
+            catch {
+                /* fall through to the actionable error below */
+            }
+        }
+        throw new Error(`Couldn't capture the live canvas (${msg}). ` +
             `An older panel version may not support graph_serialize — pass pack, path, or graph instead.`);
     }
     const wf = reply?.workflow;
@@ -916,6 +1614,133 @@ async function resolveWorkflowInput(args, ctx) {
     }
     return wf;
 }
+let askTimingOverride = null;
+// The enclosing MCP `tools/call` is killed at ~300s. The card deadline PLUS the
+// late-answer grace poll must finish UNDER that, or a slow-but-valid pick is lost
+// to the framework before we can honor it (#486). This is the HARD ceiling on the
+// total ask budget — applied even when env overrides ask for more, so a
+// misconfigured COMFYUI_PANEL_ASK_DEADLINE_S/GRACE_S can never recreate #486.
+const ASK_TOTAL_BUDGET_CAP_MS = 285_000;
+function getAskTiming() {
+    if (askTimingOverride)
+        return askTimingOverride;
+    const pollMs = Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_ASK_POLL_S", 0.5) * 1000);
+    // Defaults keep deadline + grace comfortably under the budget (240 + up to 45 =
+    // 285s). Env overrides are HARD-clamped: the deadline is capped first (leaving at
+    // least a 1s slice), then the grace gets only whatever budget remains, so
+    // deadline + grace is guaranteed ≤ ASK_TOTAL_BUDGET_CAP_MS regardless of input.
+    let deadlineMs = Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_ASK_DEADLINE_S", 240) * 1000);
+    let graceMs = Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_ASK_GRACE_S", 45) * 1000);
+    deadlineMs = Math.min(deadlineMs, ASK_TOTAL_BUDGET_CAP_MS - 1000);
+    graceMs = Math.min(graceMs, Math.max(0, ASK_TOTAL_BUDGET_CAP_MS - deadlineMs));
+    return { deadlineMs, graceMs, pollMs };
+}
+/** True when an error is the bridge's reply-TIMEOUT for a card (the tab never
+ *  replied within the window), NOT a genuine transport/command error. Only a
+ *  timeout warrants polling the late-reply buffer for a slow-but-valid answer. */
+function isReplyTimeoutError(err) {
+    const msg = err instanceof Error ? err.message : String(err ?? "");
+    return /did not reply to .* within \d+\s*ms|backgrounded or frozen/i.test(msg);
+}
+/**
+ * Actionable error string when THIS session has no interactive surface able to
+ * render an ask card (so the ask would block with no way to answer), or `null`
+ * when a card can render. Uses the bridge's `isHeadless` on the tab the ask would
+ * target (the current tab if reachable, else the resolved active tab). Defensive:
+ * an unknown/lightweight bridge, or an ambiguous active-tab resolution, returns
+ * null so the normal send path surfaces its own clear error instead.
+ */
+function askSurfaceError(ctx) {
+    const b = ctx.bridge;
+    if (typeof b.isHeadless !== "function")
+        return null; // lightweight/unknown bridge
+    let targetId = ctx.tabId;
+    if (typeof b.canReach === "function" && !b.canReach(targetId)) {
+        if (typeof b.resolveActiveTabId !== "function")
+            return null;
+        try {
+            targetId = b.resolveActiveTabId();
+        }
+        catch {
+            return null; // no single active tab — let the send path report it clearly
+        }
+    }
+    if (!b.isHeadless(targetId))
+        return null;
+    return ("No interactive panel surface can render a choice card in this session — the " +
+        "connected client is canvas-less (a mobile mirror, a remote/headless viewer, or " +
+        "an exec/headless run), so panel_ask can't be answered here and would block. Ask " +
+        "the user directly in plain chat text, or invoke panel_ask from an interactive " +
+        "ComfyUI browser tab (not nested inside an exec/headless call).");
+}
+/** Poll the bridge's late-reply buffer for a validated ask answer that arrived
+ *  after the card-reply timeout, up to the grace budget. undefined if none. */
+async function pollLateAskReply(bridge, askId, timing) {
+    const take = bridge
+        .takeLateAskReply;
+    if (typeof take !== "function")
+        return undefined;
+    const deadline = Date.now() + timing.graceMs;
+    for (;;) {
+        const late = take.call(bridge, askId);
+        if (late !== undefined)
+            return late;
+        const left = deadline - Date.now();
+        if (left <= 0)
+            return undefined;
+        await sleep(Math.max(1, Math.min(timing.pollMs, left)));
+    }
+}
+/**
+ * Run a panel_ask: render the choice card and return the user's pick. Clamps the
+ * card deadline under the MCP tools/call budget and, on a reply-timeout, honors a
+ * late-but-valid answer from the bridge's late-reply buffer before failing (#486).
+ * Sent DIRECTLY over the bridge (like the confirm/consent cards) so a stable
+ * `ask_id` can key the late-reply buffer.
+ */
+async function askUserWithGrace(ctx, ask) {
+    const timing = getAskTiming();
+    const askId = randomUUID();
+    const cmd = {
+        cmd: "ask_user",
+        ask_id: askId,
+        question: ask.question,
+        options: ask.options,
+        header: ask.header,
+        multi_select: ask.multi_select,
+    };
+    try {
+        ctx.ensureReachable?.();
+        const reply = await ctx.bridge.send(cmd, {
+            tabId: ctx.tabId,
+            timeoutMs: timing.deadlineMs,
+        });
+        return ok(reply);
+    }
+    catch (err) {
+        if (isReplyTimeoutError(err)) {
+            const late = await pollLateAskReply(ctx.bridge, askId, timing);
+            if (late !== undefined)
+                return ok(late);
+            return fail("The question card was not answered in time (or no interactive panel surface " +
+                "rendered it — e.g. an exec/headless run), so nothing was selected. If you " +
+                "still need the decision, ask the user directly in plain chat text, or " +
+                "re-invoke panel_ask from an interactive ComfyUI tab.");
+        }
+        return fail(err);
+    }
+}
+export const __panelAskTestHooks = {
+    /** Inject fast ask timing so tests don't wait the real deadline/grace. */
+    setAskTiming(timing) {
+        askTimingOverride = timing;
+    },
+    /** The env-derived (hard-clamped) ask timing, for the budget-cap test. */
+    getAskTiming,
+    ASK_TOTAL_BUDGET_CAP_MS,
+    askSurfaceError,
+    isReplyTimeoutError,
+};
 /**
  * The SINGLE source of truth for the panel_* tool surface. Both transports
  * register these exact definitions, so the Claude (in-process) and Codex (HTTP)
@@ -925,7 +1750,7 @@ export function buildPanelToolDefs() {
     // Local helper so each def reads like the original `tool(...)` call.
     const def = (name, description, schema, handler) => ({ name, description, schema, handler });
     return [
-        def("panel_query_graph", "QUERY the workflow the user is CURRENTLY VIEWING — filter, traverse, project, and aggregate over the live canvas WITHOUT dumping the whole graph (replaces the old panel_get_graph full-JSON dump; output is TOKEN-BOUNDED with an explicit truncation marker, so a big graph can never flood your context). Combine: `types` (node type contains any), `title` (contains), `where` widget predicates ANDed ('cfg>7', 'steps<=20', 'sampler_name=euler', 'text~sunset' — ops = != >= <= > < ~contains), `ids` (exact nodes — THE way to read ONE node's exact slot/widget detail: {ids:[42], fields:'detail'}), `upstream_of`/`downstream_of` + `depth` (dependency traversal: upstream = what FEEDS that node, downstream = what CONSUMES it; seed at depth 0), `fields` ('compact' one line per node [default], 'ids', 'detail' = the full node summary with slots + connections + mode), `group_by:'type'` (counts only), `limit` (default 40). detail rows include each node's MODE — a 'bypass' node is skipped and a 'mute' node kills everything downstream, so check modes on the path you care about before running (fix with panel_set_node_mode). Every result also carries `groups` (id, title, member node_ids — groups are geometric, trust this list) and, when viewing a SUBGRAPH (after panel_enter_subgraph), `rails` (boundary rail ids/slots). Typical flow: panel_graph_outline to orient → panel_query_graph to pinpoint/inspect → edit. Read-only.", {
+        def("panel_query_graph", "FILTER/traverse a SUBSET of the live graph once you already know what you're looking for — NOT the tool for 'show me the canvas' / a full overview (use panel_graph_outline FIRST for that). QUERY the workflow the user is CURRENTLY VIEWING — filter, traverse, project, and aggregate over the live canvas WITHOUT dumping the whole graph (replaces the old panel_get_graph full-JSON dump; output is TOKEN-BOUNDED with an explicit truncation marker, so a big graph can never flood your context). Combine: `types` (node type contains any), `title` (contains), `where` widget predicates ANDed ('cfg>7', 'steps<=20', 'sampler_name=euler', 'text~sunset' — ops = != >= <= > < ~contains), `ids` (exact nodes — THE way to read ONE node's exact slot/widget detail: {ids:[42], fields:'detail'}), `upstream_of`/`downstream_of` + `depth` (dependency traversal: upstream = what FEEDS that node, downstream = what CONSUMES it; seed at depth 0), `fields` ('compact' one line per node [default], 'ids', 'detail' = the full node summary with slots + connections + mode), `group_by:'type'` (counts only), `limit` (default 40). detail rows include each node's MODE — a 'bypass' node is skipped and a 'mute' node kills everything downstream, so check modes on the path you care about before running (fix with panel_set_node_mode). Every result also carries `groups` (id, title, member node_ids — groups are geometric, trust this list) and, when viewing a SUBGRAPH (after panel_enter_subgraph), `rails` (boundary rail ids/slots). Typical flow: panel_graph_outline to orient → panel_query_graph to pinpoint/inspect → edit. Read-only.", {
             types: z.array(z.string()).optional().describe("Node type contains ANY of these (case-insensitive)."),
             title: z.string().optional().describe("Node title contains this."),
             where: z
@@ -977,7 +1802,7 @@ export function buildPanelToolDefs() {
             limit: args.limit,
             max_chars: args.max_chars,
         })),
-        def("panel_graph_outline", "Read a COMPACT, dependency-ordered TEXT MAP of the workflow the user is viewing — the FASTEST way to UNDERSTAND a graph (especially a big loaded pack/template) before you touch it. Returns one `outline` string built for you to read top→down: nodes are topologically sorted (sources first, sinks last), each shown on its own block as `id Type \"title\" [bypass/mute] [OUTPUT] · group:X  widget=value …` with `← inputs` (as source_node.output_name) and `→ outputs` (as target_node.input_name), preceded by a GROUPS index (title → member node ids). It shows the WIRING you'd otherwise have to reconstruct. Use this FIRST to get oriented; then panel_query_graph to filter/traverse/inspect (e.g. {ids:[42], fields:'detail'} for one node's exact slot/widget detail), or panel_find_nodes for free-text search. Read-only.", {}, async (_args, ctx) => ctx.call({ cmd: "graph_outline" })),
+        def("panel_graph_outline", "'Show me what's on the canvas' / 'what's on the graph right now' / 'read the current workflow' / 'describe the open graph' -> THIS TOOL. It reads the LIVE canvas the user is looking at. NOT visualize_workflow (that renders a workflow you PASS IN — a saved file/JSON — into a Mermaid diagram, and does NOT read the live canvas) and NOT panel_query_graph (use that only to FILTER/traverse a SUBSET once you already know what you're looking for). Returns a COMPACT, dependency-ordered TEXT MAP of the whole open graph — the FASTEST way to UNDERSTAND it (especially a big loaded pack/template) before you touch it. One `outline` string, read top→down: nodes topologically sorted (sources first, sinks last), each on its own block as `id Type \"title\" [bypass/mute] [OUTPUT] · group:X  widget=value …` with `← inputs` (as source_node.output_name) and `→ outputs` (as target_node.input_name), preceded by a GROUPS index (title → member node ids). It shows the WIRING you'd otherwise have to reconstruct. Use this FIRST to get oriented; then panel_query_graph to filter/traverse/inspect (e.g. {ids:[42], fields:'detail'} for one node's exact slot/widget detail), or panel_find_nodes for free-text search. Read-only.", {}, async (_args, ctx) => ctx.call({ cmd: "graph_outline" })),
         def("panel_view_selected", "What the user has SELECTED on the canvas right now. Call this FIRST whenever they say \"this node\", \"the selected one\", \"the highlighted node\", \"where did I get this from\", or otherwise point at something without giving an id — the selection IS the answer, and reading it costs one call instead of scanning the graph. Returns the full detail summary (id, type, title, widgets, inputs with sources, outputs, mode) for each selected node, plus `selected_count` and any selected groups/reroutes. If `selected_count` is 0, nothing is selected — ask the user to click the node rather than guessing. NEVER dump the whole graph to work out which node they mean. Read-only.", {}, async (_args, ctx) => ctx.call({ cmd: "graph_view_selected" })),
         def("panel_view_nodes_in_viewport", "The nodes the user can actually SEE — everything intersecting the current viewport (pan+zoom) of the canvas they're looking at. Use this to SCOPE your work to what's on their screen instead of reading a whole graph: when they say \"these nodes\", \"the ones here\", \"what am I looking at\", or when a graph is large and you only need the region in front of them. Returns the viewport rect in graph coordinates (x, y, width, height, zoom), `node_count` (whole graph) vs `in_view_count`, and the detail summary of each visible node. A node counts as visible if any part of it overlaps the viewport. On a big canvas this is dramatically cheaper than panel_graph_outline / panel_query_graph — prefer it when the user's framing is visual. Read-only.", {}, async (_args, ctx) => ctx.call({ cmd: "graph_view_nodes_in_viewport" })),
         def("panel_audit_prompt_director", "Audit Prompt Director on the LIVE canvas without changing it. Correlates Prompt Director/Producer/Auto/Context/Reference/Critic widget values and wiring with detected model-loader filenames, every LoRA loader's actual model/CLIP strengths, and Prompt Director's latest sanitized runtime edit plan, resolved Model Explorer metadata, warnings, exact final prompt, and critic verdict. Returns observations plus proposed panel_set_widget changes with requires_confirmation=true. Call this when Prompt Director nodes are present, before saying the model/LoRA setup is correct, or when an edit prompt is ignored. READ-ONLY: present useful findings to the user and ask before applying any recommendation unless they already explicitly asked you to fix it.", {}, async (_args, ctx) => ctx.call({ cmd: "graph_prompt_director_audit" })),
@@ -1047,7 +1872,12 @@ export function buildPanelToolDefs() {
         }, async (args, ctx) => ctx.call({ cmd: "graph_add_node", class_type: args.class_type, pos: args.pos, title: args.title })),
         def("panel_remove_node", "Remove a node (and its connections) from the user's open graph by id. Undoable with Ctrl+Z.", { node_id: z.number().int().describe("Node id from panel_graph_outline / panel_query_graph.") }, async (args, ctx) => ctx.call({ cmd: "graph_remove_node", node_id: args.node_id })),
         def("panel_clear", "Remove EVERY node from the user's open graph — only for an explicit 'clear/reset the canvas'. Just CALL THIS DIRECTLY when they ask to clear: the tool itself pops a confirm card and only wipes on a yes (don't ask separately first). The wipe is a single Ctrl+Z undo. NEVER use this for a 'new workflow' — that's panel_new_workflow (a new tab, leaves this graph intact).", {}, async (_args, ctx) => {
-            if (!(await ctx.confirm("Clear the canvas? This removes every node from the open workflow. (One Ctrl+Z undoes it.)", "Clear canvas"))) {
+            const decision = await ctx.confirm("Clear the canvas? This removes every node from the open workflow. (One Ctrl+Z undoes it.)", "Clear canvas");
+            if (decision === "timeout") {
+                return ok("Timed out waiting for your confirmation, so I left the canvas as-is. " +
+                    "Tell me to clear it again when you're ready.");
+            }
+            if (decision !== "yes") {
                 return ok("Cancelled — the canvas was left as-is.");
             }
             return ctx.call({ cmd: "graph_clear" });
@@ -1074,7 +1904,9 @@ export function buildPanelToolDefs() {
                 .optional()
                 .describe("Inline UI workflow (object or JSON string) to strip instead of a pack/path."),
         }, async (args, ctx) => {
-            const raw = await resolveWorkflowInput(args, ctx);
+            // strip opts into the lossy live-canvas fallback (#384) — its API/prompt
+            // output is for inspection/execution, never reloaded onto the canvas.
+            const raw = await resolveWorkflowInput(args, ctx, true);
             const ui = raw;
             const bulk = await getObjectInfo();
             const objectInfo = await backfillObjectInfo(bulk, collectNodeTypes(ui));
@@ -1195,9 +2027,10 @@ export function buildPanelToolDefs() {
                     data = readPackWorkflow(args.pack);
                 }
                 else if (args.path) {
-                    // Read an arbitrary workflow JSON off the orchestrator's local disk —
-                    // same server-side-read pattern as `pack`, keeping the big JSON out of chat.
-                    data = readWorkflowFromPath(args.path);
+                    // Read an arbitrary workflow JSON server-side — a local disk path, or
+                    // (for a relative name under a custom --user-directory) the connected
+                    // ComfyUI's userdata API — keeping the big JSON out of chat (#202).
+                    data = await readWorkflowFromPath(args.path);
                 }
                 else if (args.graph != null) {
                     data = typeof args.graph === "string" ? JSON.parse(args.graph) : args.graph;
@@ -1247,13 +2080,27 @@ export function buildPanelToolDefs() {
             node_id: z.number().int().describe("Node id whose input to disconnect."),
             input: slotRef.optional().describe("Input slot name or index (default 0)."),
         }, async (args, ctx) => ctx.call({ cmd: "graph_disconnect", node_id: args.node_id, input: args.input })),
-        def("panel_set_widget", "Set a widget value on a node in the user's open graph (steps, cfg, seed, ckpt_name, text prompts, …). Returns the previous and new value. Undoable with Ctrl+Z.", {
+        def("panel_set_widget", "Set a widget value on a node in the user's open graph (steps, cfg, seed, ckpt_name, text prompts, …). Returns the previous and new value. Undoable with Ctrl+Z. To CLEAR a text widget to an empty string, pass `clear: true` (some MCP clients drop an empty-string `value` from the serialized payload, so `value: \"\"` may not arrive — `clear: true` always works).", {
             node_id: z.number().int().describe("Node id from panel_graph_outline / panel_query_graph."),
             widget: z.string().describe("Widget name (e.g. 'steps', 'cfg', 'text')."),
             value: z
                 .union([z.string(), z.number(), z.boolean()])
-                .describe("New value. Must match the widget's expected type."),
-        }, async (args, ctx) => ctx.call({ cmd: "graph_set_widget", node_id: args.node_id, widget: args.widget, value: args.value })),
+                .optional()
+                .describe("New value. Must match the widget's expected type. Optional only when `clear: true` is set (which forces an empty string)."),
+            clear: z
+                .boolean()
+                .optional()
+                .describe("Set true to clear the widget to an empty string (\"\"). Escape hatch for when a client cannot carry an empty-string `value` through tool-arg JSON. Overrides `value`."),
+        }, async (args, ctx) => {
+            // Distinguish "value present but empty" from "value absent" by key
+            // presence, NOT a truthiness check — an empty string is a legitimate
+            // value. `clear: true` is the transport-independent way to set "".
+            const value = args.clear === true ? "" : args.value;
+            if (value === undefined) {
+                return fail("panel_set_widget needs a `value`. To set an empty string, pass `clear: true` (some clients drop an empty-string `value`).");
+            }
+            return ctx.call({ cmd: "graph_set_widget", node_id: args.node_id, widget: args.widget, value });
+        }),
         def("panel_move_node", "Move a node to a new canvas position [x, y] in the user's open graph. Undoable.", {
             node_id: z.number().int().describe("Node id from panel_graph_outline / panel_query_graph."),
             pos: xy().describe("New canvas [x, y] (two numbers)."),
@@ -1474,7 +2321,15 @@ export function buildPanelToolDefs() {
                     if (args.target_kind !== "env") {
                         return ok("The built-in comfyui server takes secrets as env vars — use target_kind 'env' (e.g. key 'CIVITAI_API_TOKEN').");
                     }
-                    setComfyuiSecret(args.key, `${args.value_prefix ?? ""}${secret}`);
+                    setComfyuiSecret(args.key, `${args.value_prefix ?? ""}${secret}`, {
+                        // This save ANSWERS an outstanding agent secret request — mark it so
+                        // the orchestrator injects the "retry the action" nudge, and carry
+                        // the requesting tab so ONLY that tab's agent is nudged (never a
+                        // broadcast to unrelated tabs). A Settings-panel slot save omits
+                        // both and never nudges (#164).
+                        requested: true,
+                        tabId: ctx.tabId,
+                    });
                     // Redacted ack ONLY — the secret never enters the agent's context. The
                     // respawn is deferred to this turn's end, so this is accurate.
                     return ok(`🔒 Token saved for the built-in comfyui tools (env "${args.key}"). It's being applied now — the comfyui tools respawn with it as soon as this turn ends, then I'll retry. No reload needed.`);
@@ -1558,7 +2413,12 @@ export function buildPanelToolDefs() {
                     .describe("Step state (default 'pending'). Mark the one you're on 'active'."),
             }))
                 .describe("The full ordered checklist (replaces the current one). Empty array clears the tray."),
-        }, async (args, ctx) => ctx.call({ cmd: "set_todo", items: args.items }, 5000)),
+        }, 
+        // #322: a 5s ack deadline false-timed-out a responsive session whose tab was
+        // momentarily backgrounded. set_todo is a non-destructive, idempotent full-
+        // replace UI write (already in RETRY_SAFE_CMDS), so give it the same sane 15s
+        // bound as the other UI-state writes (workflow_save) instead of a tight 5s.
+        async (args, ctx) => ctx.call({ cmd: "set_todo", items: args.items }, 15000)),
         def("panel_open_civitai", "Open the in-panel CivitAI browser for the user, pre-seeded with a search term and suggested filters, so they can VISUALLY browse and pick a model / LoRA / checkpoint / workflow / image. When the user asks about — or you're recommending — specific CivitAI models/LoRAs/checkpoints (e.g. 'what's a good relight LoRA?'), PREFER opening this docked browser and highlighting your picks over a text-only answer: it docks beside the chat (dock defaults true) so chat and results stay visible together, and it lets the user SEE the actual cards instead of reading a table. Typical show-don't-tell flow: panel_open_civitai (docked) → panel_civitai_search to refine → panel_civitai_results to READ the metadata + URLs → panel_civitai_highlight the one(s) you recommend, with a brief text summary of why. Set a helpful query + filters matched to their goal (including the browsing level). Their selection comes back to you as a normal chat message — UNLESS the panel is muted, in which case they download it directly themselves. Prefer this over guessing a specific model or asking them to paste a URL.", {
             query: z
                 .string()
@@ -1737,24 +2597,31 @@ export function buildPanelToolDefs() {
                 .describe("The choices (at least 2). An 'Other' free-text field is added automatically."),
             header: z.string().optional().describe("Very short label/chip for the card (e.g. 'Sampler')."),
             multi_select: z.boolean().optional().describe("Allow selecting multiple options (default false)."),
-        }, async (args, ctx) => ctx.call({
-            cmd: "ask_user",
-            question: args.question,
-            options: args.options,
-            header: args.header,
-            multi_select: args.multi_select,
-        }, 
-        // Human-in-the-loop: wait up to 10 minutes for a pick.
-        600000)),
-        def("panel_save_workflow", "Save the user's open workflow PROGRAMMATICALLY — no Save/Rename dialog ever pops. A never-saved workflow is auto-named and persisted; pass `name` to give it (or rename it to) a specific name. Use this freely (e.g. after building a graph) — it won't interrupt the user.", { name: z.string().optional().describe("Name to save/rename to (no .json needed). Omit to save in place / auto-name an unsaved workflow.") }, async (args, ctx) => args.name
+        }, async (args, ctx) => {
+            // #300: fail FAST with an actionable error when there is no interactive
+            // surface to render the card (a canvas-less/headless client, or an exec/
+            // headless run), rather than blocking with no way to answer.
+            const surfaceErr = askSurfaceError(ctx);
+            if (surfaceErr)
+                return fail(surfaceErr);
+            // #486: clamp the card deadline under the MCP tools/call budget and honor a
+            // late-but-valid answer via the bridge's late-reply buffer.
+            return askUserWithGrace(ctx, {
+                question: args.question,
+                options: args.options,
+                header: args.header,
+                multi_select: args.multi_select,
+            });
+        }),
+        def("panel_save_workflow", "Save the user's open workflow PROGRAMMATICALLY — no Save/Rename dialog ever pops. With no `name`: saves in place (or auto-names + persists a never-saved workflow). With `name`: if the workflow is ALREADY saved under a different name this is a SAVE-AS — it writes a NEW file and leaves the original untouched on disk (it NEVER renames/moves/destroys the original); for a never-saved workflow it is simply the first save. The result reports what happened: `saved_as`+`copied_from`+`original_on_disk` (a disk-verified check that the original file still exists) for a Save-As copy, or `first_save` for a brand-new workflow. Use this freely (e.g. after building a graph) — it won't interrupt the user.", { name: z.string().optional().describe("Name for the workflow (no .json needed). If the workflow is already saved under a different name, this writes a NEW file (Save-As COPY) and leaves the original in place — it never renames/moves/destroys it. Omit to save in place / auto-name an unsaved workflow.") }, async (args, ctx) => args.name
             ? ctx.call({ cmd: "workflow_save_as", name: args.name }, 15000)
             : ctx.call({ cmd: "workflow_save" }, 15000)),
         def("panel_list_workflows", "List the user's OPEN workflow tabs and which one is active (path, filename, modified, persisted). Use this to know what's open before switching/renaming/closing. Read-only.", {}, async (_args, ctx) => ctx.call({ cmd: "workflow_list" })),
-        def("panel_get_workflow_target", "Read which workflow this agent is bound to edit. mode 'current' means graph tools follow whatever tab the user is viewing; mode 'pinned' means edits go to the pinned workflow even if the user switched to another tab. Call this when unsure which workflow your panel_* edits will affect.", {}, async (_args, ctx) => {
+        def("panel_get_workflow_target", "Read which workflow this agent is bound to edit. mode 'current' means graph tools follow whatever tab the user is viewing; mode 'pinned' means edits are bound to the pinned workflow (which was the active canvas at pin time) — if the user later switches to another tab, your next graph call FAILS LOUDLY rather than silently editing the wrong graph. Call this when unsure which workflow your panel_* edits will affect.", {}, async (_args, ctx) => {
             const target = ctx.workflowTarget?.get(ctx.tabId) ?? { mode: "current" };
             return ok(target);
         }),
-        def("panel_set_workflow_target", "Pin the agent to a specific open workflow tab, or release the pin to follow the user's current tab. Use pinned when the user asks you to work on workflow A while they browse workflow B — set mode:'pinned' and path from panel_list_workflows. Set mode:'current' (or omit path) to follow the active tab again. Does NOT switch what the user sees; it only routes your panel_* graph edits. mode:'current' is ALSO the explicit RECOVERY signal: if your panel_* calls started failing with `no connected tab` after ComfyUI reconnected, the panel reloaded, or the user switched to a different workflow FILE, call this with mode:'current' to rebind this session onto the tab that's live now.", {
+        def("panel_set_workflow_target", "Pin the agent to a specific open workflow tab (it must be the ACTIVE/in-view workflow at pin time), or release the pin to follow the user's current tab. The panel can only read or edit the workflow currently in view, so pinning to a background tab is REJECTED at pin time — to work on a different open workflow, switch to it first with panel_open_workflow (that makes it active), then pin. Pinning does NOT change the user's view; it binds your panel_* graph edits to that workflow and makes a later mismatch (e.g. the user switches away) fail loudly instead of silently editing the wrong graph. Set mode:'pinned' with path from panel_list_workflows; set mode:'current' (or omit path) to follow the active tab again. mode:'current' is ALSO the explicit RECOVERY signal: if your panel_* calls started failing with `no connected tab` after ComfyUI reconnected, the panel reloaded, or the user switched to a different workflow FILE, call this with mode:'current' to rebind this session onto the tab that's live now.", {
             mode: z
                 .enum(["current", "pinned"])
                 .describe("'current' = follow the user's active workflow tab; 'pinned' = always edit the given path."),
@@ -1791,25 +2658,18 @@ export function buildPanelToolDefs() {
                 }
             }
             // PIN: bind to the EXACT open-workflow identity from the authoritative
-            // workflow_list, canonicalizing to its stable `key` and FAILING CLOSED when
-            // the requested workflow isn't actually open — instead of letting the panel
-            // silently route the pin to another tab (#259). Indeterminate lists (older
-            // panel / no `workflows` array) fall back to the raw path (unchanged).
+            // workflow_list, canonicalizing to its stable `key`, FAILING CLOSED when the
+            // requested workflow isn't open (#259), and FAILING AT PIN TIME when it is open
+            // but not the active canvas (#556/#571). Shared with the panel-driven event path
+            // so both entry points validate identically.
             let pinPath = path;
             let pinFilename = filename;
             if (mode === "pinned" && path) {
-                const resolved = await resolveOpenWorkflow(ctx, path);
-                if (resolved === NOT_OPEN) {
-                    return fail(`Cannot pin to "${path}" — it is not open in ComfyUI. Open it first ` +
-                        `(panel_open_workflow) or pick an open workflow from panel_list_workflows, ` +
-                        `then pin. (Refusing to pin to a workflow that isn't open so graph edits ` +
-                        `never land on the wrong tab.)`);
-                }
-                if (resolved) {
-                    // Canonicalize to the stable key so routing survives rename/reconnect.
-                    pinPath = resolved.key ?? resolved.path ?? path;
-                    pinFilename = filename ?? resolved.filename ?? resolved.path;
-                }
+                const res = await resolvePinTarget(ctx, path, filename);
+                if (!res.ok)
+                    return fail(res.error);
+                pinPath = res.pinPath;
+                pinFilename = res.pinFilename;
             }
             const target = ctx.workflowTarget.set(ctx.tabId, {
                 mode,
@@ -2010,100 +2870,290 @@ export function buildPanelToolDefs() {
         }, async (args, ctx) => ctx.call({ cmd: "graph_update_node", id: args.id, version: args.version, channel: args.channel, mode: args.mode }, 30000)),
         def("panel_node_queue_status", "Check the built-in Manager's install/update queue status (to see if a queued install finished). Read-only.", {}, async (_args, ctx) => ctx.call({ cmd: "nodes_queue_status" }, 20000)),
         def("panel_restart_comfyui", "Restart the user's ComfyUI server via the built-in Manager — needed to load newly installed/updated custom nodes. CALL THIS DIRECTLY when a restart is needed: it pops a confirm card and only restarts on a yes (don't ask separately first). ComfyUI and this agent go down briefly, then the panel auto-reconnects and you resume. ⚠️ BUSY GUARD: a restart ABORTS any in-progress or queued generation — if ComfyUI is generating, this tool REFUSES and tells you (it does NOT restart). When that happens, tell the user a render is running and WAIT for it (poll panel_node_queue_status), or pass force:true ONLY if the user explicitly confirms they want to kill the running generation. Best practice: before restarting after an install, check the queue is idle first. Only call when a restart is actually needed.", { force: z.boolean().optional() }, async ({ force }, ctx) => {
-            if (!(await ctx.confirm("Restart ComfyUI now? It (and this agent) will go down briefly, then reconnect and resume automatically.", "Restart ComfyUI"))) {
+            // 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
+            // (kill+relaunch starts only with >=130s left, its ~40s of sync work FRONT-LOADED)
+            // means the handler PROVABLY returns well under 300s. The confirm wait is bound
+            // to the remaining budget (its deadline+grace can't overrun it — see confirm).
+            const OVERALL_MAX_MS = 255_000;
+            const overallDeadline = Date.now() + OVERALL_MAX_MS;
+            const decision = await ctx.confirm("Restart ComfyUI now? It (and this agent) will go down briefly, then reconnect and resume automatically.", "Restart ComfyUI", Math.max(1, overallDeadline - Date.now()));
+            if (decision === "timeout") {
+                return ok("Timed out waiting for your confirmation, so I did NOT restart ComfyUI. " +
+                    "Tell me to restart it and I'll go ahead.");
+            }
+            if (decision !== "yes") {
                 return ok("Cancelled — ComfyUI was not restarted.");
             }
-            const res = await ctx.call({ cmd: "comfy_reboot", force: force === true }, 15000);
+            // 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-
+            // completion prevents any rebind in between). The boot-endpoint probe target is
+            // 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?.();
+            const boundTabId = ctx.tabId;
+            const healthBase = captureRebootHealthBase(ctx);
+            const timing = getPanelRebootTiming();
+            const dispatchTimeout = Math.max(1, Math.min(15000, overallDeadline - Date.now()));
+            // CONCURRENT OBSERVATION (coordinator): start probing the fixed boot endpoint NOW,
+            // in parallel with the dispatch, so a FAST reboot whose down→up completes entirely
+            // inside the ack/drop/timeout window is still captured (the reopened #509 fast-reboot
+            // false-timeout). COUNTING stays post-write via the gate: the observer neither probes
+            // nor counts until gate.dispatched flips (the instant AFTER the socket write), so a
+            // pre-dispatch down never contributes. gate.deadline starts at the whole-handler cap
+            // (probing spans the ack window) and is tightened to ack-completion + budget below.
+            //
+            // INHERENT TRADEOFF (coordinator, verified: no early-accept signal exists — the bridge
+            // resolves send() only with the single rid-correlated {rebooting} reply, so accept vs
+            // REFUSE is known only IN that reply). To catch a fast reboot we MUST probe DURING the
+            // ack window, i.e. before we know accept/refuse. The residual is BENIGN and bounded:
+            //   • the probe targets ONLY the orchestrator's OWN immutable, server-authorized boot
+            //     ComfyUI (captureRebootHealthBase → getBootLocalComfyUIBaseUrl) with the correct
+            //     configured auth — never a client-advertised, cross-family, or wrong instance, so
+            //     it is NOT an auth leak or a wrong-instance probe (handshake-Origin gated above);
+            //   • a genuinely REFUSED reboot does NOT restart ComfyUI, so no REAL ECONNREFUSED→
+            //     healthy cycle occurs to certify; and even a CONTRIVED one is explicitly discarded
+            //     (the refusal branch below returns the refusal verbatim and never reads the
+            //     observer — a refusal can NEVER certify).
+            // Eliminating even this harmless own-endpoint read would require probing only AFTER the
+            // reply, which reopens the #509 fast-reboot false-timeout — an unacceptable regression.
+            let signalDispatched;
+            const gate = {
+                dispatched: false,
+                dispatchedAt: Number.POSITIVE_INFINITY,
+                cancelled: false,
+                deadline: overallDeadline,
+                waitDispatched: new Promise((r) => {
+                    signalDispatched = r;
+                }),
+            };
+            const recoveryPromise = healthBase != null
+                ? observeRecovery(timing, gate.deadline, { healthBase, gate })
+                : null;
+            // The AUTHORITATIVE, TYPED dispatch outcome from the bridge rejection (if any):
+            // false = a PRE-write send failure (nothing transmitted), true = a POST-write
+            // mid-command OUTCOME-UNKNOWN drop / reply-timeout. Captured from the RAW error —
+            // text can't defeat it — so a pre-write failure whose detail happens to quote
+            // "OUTCOME UNKNOWN" is still categorically NOT-dispatched (coordinator P1).
+            let res;
+            let dispatchOutcome;
+            // ctx.bridge.send()'s Promise executor writes to the socket SYNCHRONOUSLY, so by the
+            // time it returns the promise the command has been written (or synchronously pre-write
+            // failed). Open the counting gate right here — this is the POST-write instant — then
+            // await the ack. Probing (already running) begins the moment this flips.
+            const sendPromise = ctx.bridge.send({ cmd: "comfy_reboot", force: force === true }, { tabId: boundTabId, timeoutMs: dispatchTimeout });
+            gate.dispatched = true;
+            gate.dispatchedAt = Date.now();
+            // Wake the observer's FIRST probe IMMEDIATELY (microtask — no timer window) now that
+            // the command has been written. Resolved on EVERY path (accept / drop / refuse /
+            // pre-write failure), so the observer never hangs on gate.waitDispatched.
+            signalDispatched();
+            try {
+                res = ok(await sendPromise);
+            }
+            catch (err) {
+                res = fail(err);
+                dispatchOutcome = dispatchOutcomeOf(err);
+            }
+            // A PRE-write send failure means nothing was transmitted — the reboot never happened,
+            // so NOTHING may certify: abort the concurrent observer immediately (coordinator P1).
+            if (dispatchOutcome === false)
+                gate.cancelled = true;
             // Classify the reboot dispatch:
             //  - CONFIRMED (rebooting:true): the panel acked before it went down.
-            //  - EXPECTED DROP: the reboot handler exits the instant it accepts the
-            //    request, so ComfyUI (and the tab it serves) goes down before it can
-            //    ack — the bridge surfaces that as a mid-command "OUTCOME UNKNOWN" /
-            //    disconnected error. That dropped connection IS the success signal of a
-            //    reboot, NOT a failure (#493, panel #222/#263/#266/#306/#307).
-            //  - REFUSAL: a busy-guard / Manager-forbidden / no-endpoint refusal comes
-            //    back as a NON-error ToolResult with `rebooting:false` — the server is
-            //    still up and was NOT restarted; return it verbatim and touch nothing.
+            //  - EXPECTED DROP: the reboot handler exits the instant it accepts the request,
+            //    so ComfyUI (and the tab it serves) goes down before it can ack — a bridge
+            //    mid-command "OUTCOME UNKNOWN"/disconnect. That drop IS the accept + went-down
+            //    signal (#493, panel #222/#263/#266/#306/#307).
+            //  - REFUSAL: a busy-guard / Manager-forbidden / no-endpoint refusal — the server
+            //    is still up and was NOT restarted; return it verbatim and touch nothing.
             const fired = rebootConfirmed(res);
-            const dropped = !fired && rebootDropped(res);
+            // A pre-write send failure (typed dispatchOutcome === false) is categorically NOT an
+            // accepted drop — never enter the probing path for a command that never left. The
+            // text check (rebootDropped) is a defense-in-depth fallback for older bridges that
+            // don't carry the typed flag.
+            const dropped = !fired && dispatchOutcome !== false && (dispatchOutcome === true || rebootDropped(res));
             if (!fired && !dropped) {
-                // The panel could not fire a Manager reboot. If the SOLE reason is that
-                // NO Manager reboot endpoint answered (legacy Manager 3.x: v2 route 405s,
-                // legacy route 404s — #425, panel #253/#266) AND the target is a LOCAL,
-                // process-controllable ComfyUI, fall back to the headless managed restart
-                // (kill + relaunch) — the same mechanism as the `restart_comfyui` tool.
-                // A busy-guard or security refusal is deliberately NOT eligible
-                // (rebootNoEndpoint excludes those), so this never aborts a running
-                // render or bypasses Manager's security gate.
-                if (!isRemoteMode() && rebootNoEndpoint(res)) {
+                // NOT accepted (e.g. a rebooting:false busy-guard/security REFUSAL). BELT-AND-
+                // SUSPENDERS (coordinator): EXPLICITLY DISCARD any cycle the concurrent observer may
+                // have sampled during the sub-ack window — a refusal must NEVER certify. We cancel
+                // the observer and, crucially, never read recoveryPromise on this path: whatever it
+                // resolved to (even a contrived ready:true) is dropped, and we return the refusal
+                // verbatim. (The legacy no-endpoint fallback below starts its OWN fresh observation
+                // after the restart's synchronous work; it does not reuse this observer.)
+                gate.cancelled = true;
+                void recoveryPromise; // discarded — a refused reboot can never yield ready:true
+                // If the SOLE reason is NO Manager reboot endpoint (legacy Manager
+                // 3.x — #425, panel #253/#266) AND the target is a LOCAL, process-controllable
+                // ComfyUI, fall back to the headless managed restart (kill + relaunch). A
+                // busy-guard / security refusal is NOT eligible (rebootNoEndpoint excludes them).
+                if (!isRemoteMode() &&
+                    rebootNoEndpoint(res) &&
+                    // INSTANCE BINDING: restartComfyUI() acts on the orchestrator's GLOBAL config
+                    // target (a hello can retarget it). Only run it when the bound tab provably
+                    // fronts our OWN boot instance AND that boot instance is the CURRENT global
+                    // target — so the relaunch cycles the SAME instance this tab rebooted.
+                    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();
+                    // 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 restartComfyUI();
+                        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.");
                     }
-                    if (!restart.started) {
+                    clearTimeout(restartTimer);
+                    // 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) as a fallback, but it " +
-                            `could not restart ComfyUI: ${restart.message} ` +
+                            "Tried the headless managed restart (kill + relaunch), but it did not restart " +
+                            `ComfyUI: ${restart?.message ?? "unknown error"} ` +
                             "Restart ComfyUI on the host, then reconnect.");
                     }
-                    // A managed kill+relaunch restarts ComfyUI out-of-band from the WS
-                    // client, so drop the memoized caches exactly as the Manager-reboot
-                    // path does before waiting for the panel to reconnect.
-                    resetClient();
-                    resetObjectInfoCache();
-                    const timing = getPanelRebootTiming();
-                    const recovery = await waitForPanelReady(ctx, timing);
+                    // 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;
+                    const observed = recovery.via === "observed-cycle";
                     return ok({
                         rebooting: true,
                         ready: recovery.ready,
+                        confirmed_cycle: observed, // true = we directly observed the down→up cycle
                         recovered_ms: recovery.waited_ms,
                         probes: recovery.attempts,
-                        via: "headless-managed-restart",
-                        note: "ComfyUI-Manager (legacy 3.x) had no reboot endpoint; restarted ComfyUI " +
-                            `via the headless managed restart (kill + relaunch)${recovery.ready
-                                ? ` and it came back ready in ${(recovery.waited_ms / 1000).toFixed(1)}s.`
-                                : " but the panel did not reconnect within the readiness budget — verify with panel_node_queue_status."}`,
+                        saw_down: recovery.sawDown,
+                        via: recovery.ready ? recovery.via : undefined,
+                        note: "ComfyUI-Manager (legacy 3.x) had no reboot endpoint; ran the headless managed " +
+                            "restart (kill + relaunch) " +
+                            (recovery.ready
+                                ? `and it came back healthy in ${(recovery.waited_ms / 1000).toFixed(1)}s` +
+                                    (observed ? " (observed it go down then come back)." : " (cycle not directly observed).")
+                                : `but it did NOT become healthy within ${Math.round(recovery.waited_ms / 1000)}s — verify with health_check / panel_node_queue_status before assuming it restarted.`),
                     });
                 }
-                // Genuine refusal (or an unrelated error) — do NOT poll or reset caches.
-                // Resetting on a refusal would close the shared client mid-generation
-                // (codex WS-3 finding #2).
+                // Genuine refusal (busy guard / security / no eligible fallback) — return
+                // verbatim; do NOT reset caches (that would close the shared client mid-render).
                 return res;
             }
-            // A panel/Manager reboot restarts ComfyUI out-of-band from the MCP
-            // process-control path, so the orchestrator's WebSocket client and its
-            // memoized /object_info survive the restart and go stale: get_node_info
-            // then returns pre-restart schemas, model dropdowns, and required/optional
-            // placement (#353/#378/#394), and newly installed nodes stay invisible
-            // (#357). The reboot is the triggering event — drop both caches so the
-            // next call refetches against the fresh server.
+            // ACCEPTED. A reboot restarts ComfyUI out-of-band, so the orchestrator's cached WS
+            // client + /object_info go stale (#353/#357/#378/#394) — drop both caches.
             resetClient();
             resetObjectInfoCache();
-            // The reboot has FIRED. The connection drop is EXPECTED, not an error — do
-            // not surface it as a false timeout/failure. Instead poll readiness (a
-            // lightweight nodes_queue_status round-trip that auto-heals onto the
-            // reconnected tab) up to a generous bound and report SUCCESS once ComfyUI
-            // is reachable again, with how long recovery took. Only report FAILURE if
-            // it genuinely never comes back within the budget — a truly-dead server
-            // still fails honestly.
-            const timing = getPanelRebootTiming();
-            const recovery = await waitForPanelReady(ctx, timing);
+            // Observe recovery. There is exactly ONE sound proof that THIS ComfyUI instance
+            // actually cycled: a directly OBSERVED down→up on the server-authorized, immutable,
+            // family-bound boot endpoint (observeRecovery). We do NOT fabricate a second proof
+            // from a weaker proxy. In particular a panel tab disconnecting→reconnecting proves
+            // only that a panel↔orchestrator socket churned — NOT that the (possibly remote)
+            // ComfyUI cycled; `tab_id` is client-supplied and a different same-kind socket can
+            // take that id over with a fresh nonce, so a tab reconnect can never certify a
+            // same-instance restart (codex gate). So when there is NO probeable boot endpoint
+            // (remote / cloud / older / untrusted-locality panel), we HONESTLY report the reboot
+            // as dispatched-and-accepted but NOT server-confirmable — a non-error result that
+            // tells the caller to verify, NOT the #509 false-TIMEOUT *error* (the real #509 local
+            // case is a probeable boot endpoint and is certified by observeRecovery below).
+            if (healthBase == null) {
+                // No probeable boot endpoint — the concurrent observer was never started.
+                return ok({
+                    rebooting: true,
+                    ready: false,
+                    confirmed_cycle: false,
+                    dispatched: true,
+                    note: "ComfyUI restart was dispatched and accepted; it is restarting out-of-band. " +
+                        "There is no local boot endpoint I can safely probe from here, so I can't " +
+                        "confirm it finished coming back — a panel reconnect wouldn't prove this " +
+                        "instance actually cycled. Check health_check / panel_node_queue_status in a " +
+                        "few seconds to confirm it's back.",
+                });
+            }
+            // The concurrent observer has been probing since dispatch (catching a fast down→up
+            // inside the ack window). Now measure the readiness budget from ACK COMPLETION — so a
+            // slow ack doesn't eat it — by tightening the live deadline, then await the verdict.
+            // Both fired and dropped are AMBIGUOUS (the panel emits rebooting:true even when it
+            // only INFERS a reboot from a dropped fetch), so certification requires an OBSERVED
+            // down→up, which the observer has been (and continues) watching for.
+            gate.deadline = Math.min(Date.now() + timing.budgetMs, overallDeadline);
+            const recovery = await recoveryPromise;
             if (!recovery.ready) {
-                return fail(`Reboot was triggered but ComfyUI did not come back within ${Math.round(timing.budgetMs / 1000)}s (${recovery.attempts} probes). Check the host — is ComfyUI-Manager restarting it? ` +
-                    "Verify with panel_node_queue_status once a tab reconnects before retrying.");
+                const waited = Math.round(recovery.waited_ms / 1000);
+                return ok({
+                    rebooting: true,
+                    ready: false,
+                    confirmed_cycle: false,
+                    recovered_ms: recovery.waited_ms,
+                    probes: recovery.attempts,
+                    saw_down: recovery.sawDown,
+                    note: recovery.sawDown
+                        ? `Reboot was dispatched and ComfyUI went down, but it has not become healthy within ${waited}s — it may still be starting or the restart failed. Verify with health_check / panel_node_queue_status before retrying; do NOT assume it is back.`
+                        : `The reboot command was sent but I could NOT confirm ComfyUI actually cycled within ${waited}s (it never went down — the panel may have merely disconnected/inferred a reboot without one). Verify with health_check / panel_node_queue_status; do NOT assume it restarted.`,
+                });
             }
             return ok({
                 rebooting: true,
                 ready: true,
+                confirmed_cycle: true, // we directly observed the down→up cycle on the boot endpoint
                 recovered_ms: recovery.waited_ms,
                 probes: recovery.attempts,
-                note: `ComfyUI rebooted and came back ready in ${(recovery.waited_ms / 1000).toFixed(1)}s${dropped ? " (connection dropped as expected while it went down)" : ""}.`,
+                saw_down: recovery.sawDown,
+                via: recovery.via,
+                note: `ComfyUI restart accepted and it is healthy again in ${(recovery.waited_ms / 1000).toFixed(1)}s` +
+                    " (observed it go down then come back)" +
+                    (dropped ? "; connection dropped as expected while it went down" : "") +
+                    ".",
             });
         }),
         def("panel_free_vram", "Unload all loaded models and free VRAM (ComfyUI /free). Use to unwedge a stuck/OOM ComfyUI when a cancel didn't free memory — before retrying or, last resort, restarting (panel_restart_comfyui). Does NOT restart ComfyUI; it just drops resident models and frees cached memory.", {}, async (_args, ctx) => ctx.call({ cmd: "free_vram" }, 15000)),
@@ -2246,11 +3296,19 @@ export function createPanelMcpServer(bridge, tabId, workflowTargets) {
     const ctx = makePanelToolCtx(bridge, tabId, workflowTargets);
     const defs = buildPanelToolDefs();
     const tools = defs.map((d) => tool(d.name, d.description, d.schema, (args) => d.handler(args, ctx)));
-    return createSdkMcpServer({
+    const server = createSdkMcpServer({
         name: "comfyui-panel",
         version: "1.0.0",
         tools,
     });
+    // Re-point this server's bound tab after a panel tab-id migration (#568 Defect
+    // 1). ctx.tabId is read LIVE by every handler (and by call/confirm), so updating
+    // it in place moves ALL panel_* routing onto the migrated tab — no stale id that
+    // makes the tools throw `no connected tab`. PanelAgent.rebindTabId() calls this.
+    server.rebindTab = (newTabId) => {
+        ctx.tabId = newTabId;
+    };
+    return server;
 }
 /**
  * Register the SHARED panel_* tools onto a `@modelcontextprotocol/sdk` McpServer