comfyui-mcp 0.48.21 → 0.48.22

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;
+}
 /**
- * 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.
+ * 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.
  */
-async function waitForPanelReady(ctx, timing) {
-    if (timing.settleMs > 0)
-        await sleep(timing.settleMs);
+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;
+/**
+ * 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 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,
@@ -671,51 +1043,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));
+        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.`);
     }
-    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 = 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 +1266,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 +1348,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 +1454,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 +1487,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)
@@ -1047,7 +1745,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 +1777,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 +1900,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 +1953,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 +2194,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 +2286,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,15 +2470,22 @@ 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)),
+        }, 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. 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
             ? ctx.call({ cmd: "workflow_save_as", name: args.name }, 15000)
             : ctx.call({ cmd: "workflow_save" }, 15000)),
@@ -2010,100 +2750,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)),