comfyui-mcp 0.49.0 → 0.49.2

package/dist/orchestrator/index.js

@@ -15,17 +15,20 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 import readline from "node:readline";
-import { startUiBridge, isLoopbackBindHost } from "../services/ui-bridge.js";
+import { startUiBridge, isLoopbackBindHost, SESSION_EPOCH } from "../services/ui-bridge.js";
 import { setupSecureBridge, resolveComfyuiPathForTarget } from "../services/secure-bridge.js";
 import { startQuickTunnel } from "../services/tunnel.js";
 import { detectInstallMode } from "../services/self-update.js";
+import { performPanelSync } from "../services/panel-sync.js";
+import { isPanelAutoInstallDisabled } from "../services/panel-installer.js";
 import { SelfRestarter } from "../services/self-restart.js";
-import { SessionStore, armableResume, deriveStableKey, destinationHasCollisionState, keepsBackendState, siblingOwnsStableKey, workflowIdentityParts, } from "./session-store.js";
+import { SessionStore, armableResume, carryWorkflowCommandStamp, deriveStableKey, destinationHasCollisionState, keepsBackendState, siblingOwnsStableKey, workflowIdentityParts, } from "./session-store.js";
 import { listSessions, loadTranscript } from "./history.js";
 import { uploadImageHttp, resetClient } from "../comfyui/client.js";
 import { logger } from "../utils/logger.js";
 import { PanelAgentManager, fetchSupportedModels, fetchSupportedCommands, isEffort, } from "./panel-agent.js";
 import { promptText } from "./error-text.js";
+import { callToolAdmission } from "./call-tool-admission.js";
 import { createPanelMcpServer, makePanelToolCtx, resolvePinTarget } from "./panel-tools.js";
 import { optionsAckFrame, optionsErrorAckFrame, optionsRequestMeta, } from "./options-ack.js";
 import { readUserMcpServers } from "../services/user-mcp-config.js";
@@ -89,7 +92,7 @@ WEDGED RENDER / OOM / VRAM PINNED — when a generation is stuck or hits CUDA ou
 
 WORKFLOW TARGETING — by default your panel_* graph edits follow whichever workflow tab the user is currently viewing. The panel can only read or edit the workflow currently IN VIEW, so to work on a specific open workflow, make it the active canvas first with panel_open_workflow, then call panel_set_workflow_target(mode:"pinned", path:<from panel_list_workflows>) to bind your edits to it; panel_get_workflow_target shows the current binding. Pinning to a background (open but not active) workflow is REJECTED at pin time — it cannot route edits to a tab that isn't in view. A pin does NOT switch what the user sees; it binds your edits to that workflow so that if the user later switches away, your next graph call fails loudly instead of silently editing the wrong graph. Set mode:"current" to follow the user's active tab again.
 
-CRITICAL — never destroy the user's work. When they ask for a "new workflow", a "fresh canvas", or to "start over for a new project", call panel_new_workflow (it opens a NEW TAB and leaves their current workflow intact). NEVER use panel_clear for that — panel_clear wipes the CURRENTLY OPEN graph and is ONLY for an explicit "clear/reset this canvas". You can manage tabs with panel_list_workflows / panel_open_workflow / panel_rename_workflow / panel_close_workflow, and group nodes with panel_select_nodes / panel_create_subgraph. To label a node by its purpose, use panel_set_node_title. To read or edit nodes INSIDE a subgraph, call panel_enter_subgraph(node_id) first — then panel_query_graph / panel_graph_outline and the panel_* edit tools operate on the subgraph's inner nodes — and panel_exit_subgraph when you're done.
+CRITICAL — never destroy the user's work. When they ask for a "new workflow", a "fresh canvas", or to "start over for a new project", call panel_new_workflow (it opens a NEW TAB and leaves their current workflow intact). NEVER use panel_clear for that — panel_clear wipes the CURRENTLY OPEN graph and is ONLY for an explicit "clear/reset this canvas". You can manage tabs with panel_list_workflows / panel_open_workflow / panel_rename_workflow / panel_close_workflow, and group nodes with panel_select_nodes / panel_create_subgraph. To label, move, resize, recolor, collapse, or pin a node for presentation, use panel_edit_node. To read or edit nodes INSIDE a subgraph, call panel_enter_subgraph(node_id) first — then panel_query_graph / panel_graph_outline and the panel_* edit tools operate on the subgraph's inner nodes — and panel_exit_subgraph when you're done.
 
 SUBGRAPH I/O — exposing interior nodes to the boundary. To wire an interior node to the subgraph's boundary from INSIDE a subgraph, do NOT panel_connect to a guessed rail node id — that's the rail and you'll get it wrong. Use panel_expose_subgraph_output(from_node_id, from_output) to expose an interior OUTPUT on the output rail (so the parent graph can wire the subgraph node's new output), and panel_expose_subgraph_input(to_node_id, to_input) to expose an interior INPUT on the input rail. Read panel_query_graph's \`rails\` field (present when viewing a subgraph) to see the current boundary slots — what's already exposed and what still needs it. To EXPAND/DISSOLVE a subgraph back into the parent graph (inline its inner nodes and rewire external links, removing the wrapper — the inverse of panel_create_subgraph), use panel_unpack_subgraph(node_id). All three are undoable with Ctrl+Z.
 
@@ -129,11 +132,11 @@ INSPECT NODE MODES BEFORE YOU RUN. After loading a pack/template/workflow — an
 
 VERIFY THE OUTPUT MATCHES THE REQUEST. After a render completes, actually LOOK at the image/video the panel delivers and confirm it matches what was asked BEFORE you declare success or move to the next step. If it doesn't match, do NOT report progress — diagnose (wrong prompt path? a bypassed/muted builder or switch? wrong widget value?), fix it (often panel_set_node_mode or panel_set_widget), and rerun. Only claim something works once you've SEEN that it does — never report progress you haven't verified.
 
-AFTER PANEL_RUN — once you call panel_run to queue a render, you will be notified automatically with the output image(s)/video when it finishes. Do not poll get_queue, get_history, or list_output_images waiting for the result — just end your turn and the finished render will be delivered to you.
+AFTER PANEL_RUN — once you call panel_run to queue a render, you will be notified automatically with the output image(s)/video when it finishes. Do not poll queue (action:"list"), get_history, or list_output_images waiting for the result — just end your turn and the finished render will be delivered to you.
 
 DEBUG WRONG RENDERS BY INSPECTING INTERMEDIATE STEPS (run-to-node). When a final asset comes out WRONG — artifacts, wrong subject/pose/composition/color, blur, a ControlNet/IPAdapter/mask/LoRA not taking, a refiner or upscale stage degrading it — do NOT just re-roll the whole graph. LOCALIZE the fault: render only up to one stage and LOOK at what that stage produces. panel_run takes to_node_id to run ONE output branch (ComfyUI partial execution) — only that output node plus everything upstream of it renders, the rest is skipped, so it's fast and cheap, and the result is delivered to you automatically like any run. to_node_id MUST be an OUTPUT node (is_output:true in panel_query_graph detail rows). To inspect a point that ISN'T an output — a latent, a preprocessor/depth/pose map, a mask, an intermediate image — TAP it: add a PreviewImage on an IMAGE wire (or VAEDecode→PreviewImage on a LATENT, MaskToImage→PreviewImage on a MASK), panel_run(to_node_id=that preview), read the delivered image, then panel_remove_node the tap when done. Bisect upstream→downstream until you find the FIRST stage whose output is bad — that node (or its inputs/widgets) is what to fix, then run-to-node there again to confirm before a full run. For the full method (probe recipes, symptom→probe map) read the debug-render skill via read_skill. This is for renders that COMPLETE but look wrong; for runs that fail with an error/OOM/missing node, use the troubleshooting skill instead.
 
-CHAIN A STAGE'S OUTPUT INTO THE NEXT STAGE'S LOADER — when a multi-stage pipeline (e.g. Krea2 image → LTX video → WAN extend) needs one stage's OUTPUT fed into the next stage's loader (LoadImage / VHS_LoadVideo / LoadAudio), call stage_output_as_input with the output's { filename, subfolder?, type? } and drop the returned input filename into the loader's image/video/audio widget. (Or, for a file already on disk, upload_image / upload_video / upload_audio.) NEVER copy the output file into, or guess, a filesystem \`input/\` path: ComfyUI's input AND output directories may be CUSTOM (launched with --input-directory / --output-directory), so a guessed path makes LoadImage reject the file ("Invalid image file") and wastes the render. stage_output_as_input goes through the server API (/view → /upload/image), which resolves the real dirs correctly every time. VERIFY A VIDEO RENDER VIA THE FILESYSTEM, NOT /history — VHS_VideoCombine and similar video nodes write the .mp4 but frequently do NOT register an output in ComfyUI's /history (the prompt shows done with no output and no error), so do NOT conclude a clip "silently dropped" from get_history/get_job_status; confirm it with list_output_images (which now lists videos, each tagged kind:"video") by filename/prefix + fresh mtime, then chain it forward with stage_output_as_input.
+CHAIN A STAGE'S OUTPUT INTO THE NEXT STAGE'S LOADER — when a multi-stage pipeline (e.g. Krea2 image → LTX video → WAN extend) needs one stage's OUTPUT fed into the next stage's loader (LoadImage / VHS_LoadVideo / LoadAudio), call stage_output_as_input with the output's { filename, subfolder?, type? } and drop the returned input filename into the loader's image/video/audio widget. (Or, for a file already on disk, upload_image / upload_video / upload_audio.) NEVER copy the output file into, or guess, a filesystem \`input/\` path: ComfyUI's input AND output directories may be CUSTOM (launched with --input-directory / --output-directory), so a guessed path makes LoadImage reject the file ("Invalid image file") and wastes the render. stage_output_as_input goes through the server API (/view → /upload/image), which resolves the real dirs correctly every time. VERIFY A VIDEO RENDER VIA THE FILESYSTEM, NOT /history — VHS_VideoCombine and similar video nodes write the .mp4 but frequently do NOT register an output in ComfyUI's /history (the prompt shows done with no output and no error), so do NOT conclude a clip "silently dropped" from get_history or queue (action:"status"); confirm it with list_output_images (which now lists videos, each tagged kind:"video") by filename/prefix + fresh mtime, then chain it forward with stage_output_as_input.
 
 BYPASS COMPLETED STAGES BEFORE QUEUING THE NEXT ONE. When you build a multi-stage pipeline on one canvas (e.g. Krea2 → LTX → WAN), once a stage has RUN and you've captured/staged its output, BYPASS that stage's nodes with panel_set_node_mode(mode:"bypass") BEFORE you queue the next stage — so panel_run doesn't re-execute (and make the user pay for / wait on) work that's already done. Re-running the whole graph because an earlier stage was left active is a real, costly failure mode: explicitly bypass each finished stage and keep only the ACTIVE stage live. (This complements stage_output_as_input, which feeds the prior stage's output forward into the next stage's loader — bypass the producer, feed its captured output to the consumer.)
 
@@ -192,7 +195,7 @@ const HEADLESS_DIRECTIVE = "[HEADLESS SESSION — no ComfyUI panel/canvas is con
     "(panel_run, panel_query_graph, panel_set_widget, panel_add_node, …) are UNAVAILABLE here and will fail — " +
     "do everything through the comfyui MCP tools (generate_image, or create_workflow + enqueue_workflow). " +
     "There is NO panel to auto-deliver a finished render, so you MUST deliver the result YOURSELF IN THIS SAME TURN: " +
-    "enqueuing returns a prompt_id immediately, so wait for it with get_job_status(prompt_id) — poll it briefly until " +
+    "enqueuing returns a prompt_id immediately, so wait for it with queue (action:\"status\", prompt_id) — poll it briefly until " +
     "it reports completion (this is the ONE case where polling IS correct) — then fetch the output with get_history and " +
     "show it with panel_show_media. Do NOT end your turn expecting an automatic notification; none will arrive. " +
     "If the run FAILED — or the user asks why a render failed / what's missing — call diagnose_run FIRST, and do NOT use " +
@@ -225,7 +228,7 @@ function formatQueueNote(rep) {
         return (`⚠️ The current ComfyUI render appears STALLED: ` +
             `${rep.currentNode ? `node ${rep.currentNode} ` : ""}${rep.progress ? `(progress ${rep.progress}) ` : ""}` +
             `on prompt ${rep.runningPromptId ?? "?"} has not advanced for ~${secs}s. ComfyUI only checks interrupts ` +
-            `BETWEEN steps, so a stuck step can ignore cancel_job. If it's wedged: call cancel_job with ` +
+            `BETWEEN steps, so a stuck step can ignore a cancel. If it's wedged: call queue (action:"cancel") with ` +
             `clear_pending:true; if it reports the job still wedged, restart_comfyui / panel_restart_comfyui. ` +
             `Do NOT queue another run on top.`);
     }
@@ -237,8 +240,8 @@ function formatQueueNote(rep) {
     if (rep.backlog && !rep.selfAttributed) {
         const pending = Math.max(0, rep.queueDepth - 1);
         return (`ℹ️ ComfyUI queue: ${rep.queueDepth} tasks in flight (1 running + ${pending} pending) that this session ` +
-            `didn't queue. This is only a problem if the running one is stuck — inspect with get_queue. ` +
-            `cancel_queued_job drops a single pending item; cancel_job with clear_pending:true resets everything.`);
+            `didn't queue. This is only a problem if the running one is stuck — inspect with queue (action:"list"). ` +
+            `queue (action:"cancel_queued") drops a single pending item; queue (action:"cancel") with clear_pending:true resets everything.`);
     }
     return null;
 }
@@ -579,109 +582,6 @@ function isRemoteHttpsUrl(u) {
         return false;
     }
 }
-/** The direct tool channel: a mobile client can invoke these READ/DOWNLOAD backend
- *  tools without an agent turn (structured nav data + rig-side downloads). The
- *  bridge is already token-gated; this whitelist keeps call_tool to non-destructive
- *  tools (no restart/remove/clear/install). */
-const CALL_TOOL_WHITELIST = new Set([
-    "list_workflows",
-    "get_workflow",
-    "analyze_workflow",
-    "query_workflow",
-    "workflow_from_image",
-    "list_output_images",
-    "get_image",
-    "list_local_models",
-    // Read-only CivitAI lookups (creator-search feature): let a client browse
-    // models/creators through the rig without an agent turn.
-    "search_civitai_models",
-    "search_civitai_creators",
-    "download_civitai_model",
-    "download_model",
-    "enqueue_workflow",
-    // Persist a workflow to the ComfyUI library (mobile "pull workflow from a
-    // CivitAI example" → save_workflow). Writes a workflow file (auto-converts
-    // API-format graphs to canvas-openable UI format); overwrites same-filename,
-    // so the client generates a unique name. No model/system mutation.
-    "save_workflow",
-    // One-tap cancel of the RUNNING render (the mobile queue monitor's stop
-    // button). User-initiated and narrowly scoped: the client passes the
-    // prompt_id it saw in `queue_status`, and cancel_job only interrupts when the
-    // running job still matches — it can never kill a job that started after the
-    // tap, and (without clear_pending, which the mobile client never sends) it
-    // never touches other pending jobs in a shared queue.
-    "cancel_job",
-    // "Why did my render fail?" for canvas-less clients. The panel answers this from
-    // live canvas state (panel_get_errors); a phone has no canvas, so it reads
-    // the same story server-side from history + re-validating the graph that ran.
-    // Read-only.
-    "diagnose_run",
-    // Read-only training surface: flow/model discovery + progress polling +
-    // docker/GPU/image preflight for the panel/mobile Training tab, and the
-    // dataset/job-config/file readers behind its Jobs/Datasets views.
-    "train_list_flows",
-    "train_status",
-    "train_doctor",
-    "train_list_datasets",
-    "train_dataset_detail",
-    "train_job_config",
-    "train_file",
-    "train_preview_config",
-    "train_dataset_update",
-    "train_dataset_delete",
-    "train_caption_image",
-    "train_caption_dataset",
-    "train_delete_job",
-    // User-initiated training ops (panel/mobile Training wizard): stage a dataset,
-    // launch a GPU-container training run, cancel one. All validation lives in the
-    // tools themselves (dataset checks, docker/image preflight, liveness-verified
-    // cancel); the whitelist only gates reachability.
-    "train_prepare_dataset",
-    "train_start",
-    "train_cancel",
-    // RunPod control panel (desktop + mobile): the one-tap pod lifecycle + the
-    // local⇄pod host switch. Read-only status/list/troubleshoot, the COST-SAVING
-    // actions (stop/use_local), connect (retarget only — a pod must already be
-    // RUNNING, so it neither spins nor keeps one billing), watch/unwatch, and the
-    // referral deploy link. Each tool validates its own pod state; the whitelist
-    // only gates reachability from a canvas-less client.
-    // NOTE: runpod_pod_create AND runpod_pod_start are deliberately EXCLUDED
-    // (#269/#278) — both put a pod into a BILLING state (create deploys; start
-    // RESUMES billing on a stopped pod). A confirmation-less mirrored/foreign tab
-    // must not be able to spend money, so both go through an agent turn / explicit
-    // UI action. stop is kept (it SAVES money).
-    "runpod_pod_status",
-    "runpod_list_pods",
-    "runpod_pod_stop",
-    "runpod_pod_connect",
-    "runpod_pod_troubleshoot",
-    "runpod_use_local",
-    "runpod_watch",
-    "runpod_unwatch",
-    "runpod_deploy_link",
-    // Micro-Apps (panel "Apps" feature): the canvas-less client's list/run/poll
-    // surface, plus registry install. One tool since 0.49.0 slice 2, so the
-    // whitelist can no longer distinguish the actions — the risk posture is judged
-    // over the whole tool. Run queues a job the user explicitly tapped (same as
-    // enqueue_workflow, already whitelisted); list/get/run_status are read-only;
-    // import (mobile Explore) has the rig fetch a bundle from the public registry
-    // and write it locally, the same risk as save_workflow + download_model
-    // (already whitelisted) — no model/system mutation, and deps install stays a
-    // separate consented action.
-    "apps",
-    // App dependency side-panel (Explore/detail): the ✓/download panel reads what
-    // an app needs vs what's installed and offers per-item fetches. Reads are safe
-    // (missing-model detection + candidate resolution, node-pack presence); model
-    // downloads reuse the already-whitelisted download_civitai_model/download_model.
-    // install_custom_node is a MUTATION that runs the pack's code on install —
-    // reachable for the panel's "install missing node" button, gated behind an
-    // explicit themed confirm client-side. (Revisit if a canvas-less/foreign tab
-    // must not be able to trigger a node install.)
-    "resolve_missing_models",
-    "extract_workflow_dependencies",
-    "list_installed_nodes",
-    "install_custom_node",
-]);
 /** Lazily build ONE in-process MCP client wired to the full comfyui tool surface,
  *  reused across call_tool requests. Reuses the exact tool implementations (same
  *  getClient()/COMFYUI_URL as the agents) — no logic duplication. */
@@ -703,6 +603,55 @@ function getCallToolClient() {
     }
     return callToolClientPromise;
 }
+/**
+ * #694 — the `models` push frame is the ONE frame stamped with the bridge's
+ * per-process SESSION_EPOCH (no per-command stamping): the panel scopes its
+ * retry_of dedupe cache to the process that minted the rids, so a restarted
+ * orchestrator's tokens never collide with a prior process's. Exported (pure)
+ * so the epoch-stability test can build two frames without booting the
+ * orchestrator.
+ */
+export function buildModelsPushFrame(models, current, backend) {
+    return { type: "models", epoch: SESSION_EPOCH, models, current, backend };
+}
+/** #694 (epoch-first) — the tiny immediate frame a hello gets before any async
+ *  work: advances the session epoch without waiting for model discovery, so a
+ *  command arriving in the gap can never resolve retry_of against the prior
+ *  process's epoch. Exported (pure) for the shape test. Type is "session_epoch"
+ *  — NEVER "session": that frame name is taken (session_id lifecycle). */
+export function buildSessionEpochFrame() {
+    return { type: "session_epoch", epoch: SESSION_EPOCH };
+}
+/**
+ * Send the model handshake even when discovery returned no choices. The models
+ * frame is also the process-epoch handshake that scopes panel retry tokens, so
+ * suppressing an empty catalog would leave a reconnecting panel on the prior
+ * process's epoch and allow stale tokens to resolve there.
+ */
+export function pushModelsFrame(bridge, panelTabId, models, current, backend) {
+    return bridge.push(buildModelsPushFrame(models, current, backend), panelTabId);
+}
+/**
+ * Keeps download-tray reconciliation state separate from the progress-file
+ * lifecycle. `record` only decides whether a changed snapshot needs a global
+ * broadcast; `forPanel` is the current (possibly empty) state sent to every
+ * hello/re-hello so a reconnect cannot retain rows from an old process.
+ */
+export class DownloadProgressSnapshots {
+    lastSnapshot = null;
+    rows = [];
+    record(rows) {
+        const snapshot = JSON.stringify(rows);
+        if (snapshot === this.lastSnapshot)
+            return false;
+        this.lastSnapshot = snapshot;
+        this.rows = rows;
+        return true;
+    }
+    forPanel() {
+        return this.rows;
+    }
+}
 export async function runPanelOrchestrator() {
     // Crash guard: the orchestrator is a long-lived background process the user
     // can't see. A stray rejection (e.g. a fire-and-forget push to a tab that
@@ -802,6 +751,9 @@ export async function runPanelOrchestrator() {
     const lockPort = Number(process.env.COMFYUI_MCP_BRIDGE_PORT) || 9180;
     const lockPath = orchLockPath(lockPort);
     const bridge = startUiBridge(lockPort, bridgeToken, bridgeHost);
+    // Starts empty intentionally: a newly connected panel must be able to clear
+    // rows left by an older process before this process sees any progress files.
+    const downloadSnapshots = new DownloadProgressSnapshots();
     // The LISTENER'S auth was fixed at construction: a null boot token means a
     // tokenless listener FOREVER — lazily provisioning a token later would
     // advertise a tunnel whose token is not enforced (codex finding). The lazy
@@ -1282,6 +1234,12 @@ export async function runPanelOrchestrator() {
     // new provider's onSession would persist under the old backend's key. Tracked for every
     // tab with a valid identity; cleared when the identity is absent/untrusted.
     const tabStableIdentity = new Map();
+    // The UUID stamped on the NEXT panel command. Normally this exactly mirrors
+    // tabStableIdentity from hello. #716 intentionally lets a successful explicit
+    // open/re-pin refresh only this command fence before the next hello arrives;
+    // session ownership remains hello-bound so a command reply can never silently
+    // retarget durable conversation state.
+    const tabCommandWorkflowUuid = new Map();
     const workflowTargets = new WorkflowTargetStore();
     // Monotonic per-tab sequence for set_workflow_target events. A pinned target is
     // validated asynchronously (resolvePinTarget queries workflow_list), so a later event
@@ -1919,7 +1877,28 @@ export async function runPanelOrchestrator() {
     // (the generation-bound-command leak). Resolved from the CALLER's tab id: during the switch
     // race the retiring tab still maps to its own uuid, so a late command stamps the ORIGIN
     // workflow's uuid and the panel (now showing the new one) fails it closed.
-    bridge.setTabWorkflowUuidResolver((tabId) => tabStableIdentity.get(panelTabOf(tabId))?.uuid);
+    bridge.setTabWorkflowUuidResolver((tabId) => tabCommandWorkflowUuid.get(panelTabOf(tabId)), (tabId, workflowUuid) => {
+        // A command reply is useful only while its routed tab still exists, and
+        // only when its UUID has the same strict shape/origin binding as hello.
+        // Invalid/missing panel data leaves the old stamp in place, causing the
+        // existing fail-closed fence to reject a subsequent mutation.
+        try {
+            if (!bridge.canReach(tabId))
+                return false;
+        }
+        catch {
+            return false;
+        }
+        const panelTab = panelTabOf(tabId);
+        const identity = workflowIdentityParts({
+            workflowUuid,
+            origin: bridge.tabServerOrigin(tabId),
+        });
+        if (!identity)
+            return false;
+        tabCommandWorkflowUuid.set(panelTab, identity.uuid);
+        return true;
+    });
     // ── Local-agent VRAM pause during generation ────────────────────────────
     // On a single-GPU box the local Ollama chat model and ComfyUI fight for VRAM:
     // a resident model can OOM a render, and a chat sent mid-render reloads the
@@ -2254,21 +2233,15 @@ export async function runPanelOrchestrator() {
         const backend = backendForTab(panelTabId);
         void ensureModels(backend)
             .then((models) => {
-            if (models.length) {
-                // `backend` rides on the models frame so the panel's picker reflects the
-                // provider THIS tab selected (single-port multi-provider). `current`
-                // reports the model this tab will ACTUALLY spawn with: the picker's
-                // per-tab override when one is set (set_options survives reconnects
-                // of the same tab id), else the backend's configured default —
-                // previously the default was always reported, so a reconnecting
-                // client's picker showed the wrong current model after a switch.
-                bridge.push({
-                    type: "models",
-                    models,
-                    current: manager.modelOverrideFor(agentKeyFor(panelTabId)) ?? currentModelFor(backend),
-                    backend,
-                }, panelTabId);
-            }
+            // `backend` rides on the models frame so the panel's picker reflects the
+            // provider THIS tab selected (single-port multi-provider). `current`
+            // reports the model this tab will ACTUALLY spawn with: the picker's
+            // per-tab override when one is set (set_options survives reconnects
+            // of the same tab id), else the backend's configured default —
+            // previously the default was always reported, so a reconnecting
+            // client's picker showed the wrong current model after a switch. Send
+            // even an empty list: the frame advances the #694 session epoch.
+            pushModelsFrame(bridge, panelTabId, models, manager.modelOverrideFor(agentKeyFor(panelTabId)) ?? currentModelFor(backend), backend);
         })
             .catch(() => {
             /* probe already logged; panel keeps its fallback list */
@@ -2346,6 +2319,14 @@ export async function runPanelOrchestrator() {
         // tell the difference (and warn if no ack arrives).
         if (event.type === "hello" && event.tab_id) {
             const panelTab = event.tab_id;
+            // #694 (epoch-first) — restamp the session epoch IMMEDIATELY on hello,
+            // before any async work (model discovery, panel sync, retarget probe).
+            // The models frame carries the epoch too, but it awaits async discovery,
+            // so a command arriving in the gap could resolve retry_of against the
+            // PRIOR process's epoch/journal. This tiny "session_epoch" frame (NEVER
+            // "session" — that name is the session_id lifecycle frame) advances the
+            // epoch first thing; the panel stamps on any epoch-carrying frame.
+            bridge.push(buildSessionEpochFrame(), panelTab);
             // Learn the sidebar panel's version from its hello and, the first time we
             // see it (or when it changes on a panel update), refresh the env block so
             // the agent's ENVIRONMENT line carries the panel version — bug reports get
@@ -2355,6 +2336,40 @@ export async function runPanelOrchestrator() {
                 latestPanelVersion = helloPanelVer;
                 void refreshEnvCapabilities();
             }
+            // #706 — an npm-orchestrator update can require a newer Registry panel.
+            // The panel-sync service owns the ENTIRE safety decision: it re-reads the
+            // local install under the panel-op lock, refuses pins/dev installs/shadows
+            // and unverifiable scans, and only reports a version it verified on disk.
+            // A desktop hello is the first point at which we can both repair an
+            // unpinned skew and tell the affected user that ComfyUI must restart. The
+            // bridge pins each CURRENT socket's kind on its FIRST hello, so query that
+            // trusted session state rather than this raw (and replayable) hello's
+            // `headless`. A headless mirror cannot load the desktop extension.
+            if (!bridge.isCurrentHeadless(panelTab) &&
+                !isPanelAutoInstallDisabled()) {
+                void performPanelSync()
+                    .then((sync) => {
+                    // An already-current local panel needs no chat noise. Every other
+                    // outcome is actionable: synced => restart, pinned => unpin first,
+                    // blocked/unknown/dev => its truthful recovery guidance.
+                    if (sync.decision === "up-to-date" || sync.decision === "not-applicable")
+                        return;
+                    bridge.push({ type: "say", text: `⚠️ ${sync.message}` }, panelTab);
+                    logger.info(`[panel-orchestrator] panel sync on hello for ${panelTab.slice(0, 8)}: ` +
+                        `${sync.decision}${sync.synced ? ` (verified ${sync.verifiedVersion ?? "unknown"})` : ""}`);
+                })
+                    .catch((err) => {
+                    // Never translate a Manager queue/verification failure into success.
+                    // The explicit tool remains available for diagnosis and retry.
+                    const detail = err instanceof Error ? err.message : String(err);
+                    logger.warn(`[panel-orchestrator] panel auto-sync on hello failed: ${detail}`);
+                    bridge.push({
+                        type: "say",
+                        text: `⚠️ Could not automatically sync the ComfyUI-MCP panel; no update was claimed. ` +
+                            `Run install_panel(action:'status') to inspect it, then retry install_panel(action:'sync') if appropriate. (${detail})`,
+                    }, panelTab);
+                });
+            }
             // Retarget ComfyUI to the URL the browser was served from (window.location),
             // BEFORE the readiness probe so the "ready" ack reflects the right instance —
             // but a hello can arrive from a STALE browser tab on a DEAD instance (E2E
@@ -2492,6 +2507,7 @@ export async function runPanelOrchestrator() {
                     workflowTargetSeq.delete(migratedFrom);
                     tabStableKey.delete(migratedFrom);
                     tabStableIdentity.delete(migratedFrom);
+                    tabCommandWorkflowUuid.delete(migratedFrom);
                 }
                 else {
                     // #570 — migrate per-backend state for EVERY provider, not only the currently-selected
@@ -2591,6 +2607,11 @@ export async function runPanelOrchestrator() {
                     const carriedStable = tabStableKey.get(migratedFrom);
                     tabStableKey.delete(migratedFrom);
                     tabStableIdentity.delete(migratedFrom);
+                    // #436 — the command stamp is the ONE per-tab map that must NOT be retired
+                    // here: carry it onto the old id (same uuid — sameWorkflow proved it). See
+                    // carryWorkflowCommandStamp for why deleting it flapped sessions still
+                    // bound to the pre-migration id into read-ok / write-refused.
+                    carryWorkflowCommandStamp(tabCommandWorkflowUuid, migratedFrom, newIdentity);
                     if (carriedStable !== undefined) {
                         if (panelTab.startsWith("tmp:"))
                             tabStableKey.set(panelTab, carriedStable);
@@ -2602,10 +2623,14 @@ export async function runPanelOrchestrator() {
             // #570: record this tab's TRUSTED identity (every tab) for the migration
             // discriminator above and the set_backend recompute below. Absent/untrusted →
             // cleared (fail closed: no proof of continuity → a future migration won't rebind).
-            if (newIdentity)
+            if (newIdentity) {
                 tabStableIdentity.set(panelTab, newIdentity);
-            else
+                tabCommandWorkflowUuid.set(panelTab, newIdentity.uuid);
+            }
+            else {
                 tabStableIdentity.delete(panelTab);
+                tabCommandWorkflowUuid.delete(panelTab);
+            }
             // Blind content mode rides the hello (issue #90) so the FIRST agent spawn
             // already carries the right tool-server env. A CHANGE against a live
             // agent also respawns it (codex-review F2: the set_content_mode frame is
@@ -2855,6 +2880,7 @@ export async function runPanelOrchestrator() {
                         sessionStore.clearStable(prior);
                     tabStableKey.delete(panelTab);
                     tabStableIdentity.delete(panelTab);
+                    tabCommandWorkflowUuid.delete(panelTab);
                 }
             }
             // Live model list for the picker; SDK slash commands are Claude-only.
@@ -2865,6 +2891,12 @@ export async function runPanelOrchestrator() {
             if (backend === "claude")
                 pushCommands(panelTab);
             bridge.push({ type: "workflow_target", target: workflowTargets.get(panelTab) }, panelTab);
+            // #717: panel tray rows belong to the bridge session, while progress files
+            // are process-private. Reconcile THIS hello/re-hello directly, including
+            // an empty snapshot, rather than waiting for an unrelated future change.
+            // This frame is state only: it does not create terminal rows or signal any
+            // download outcome.
+            bridge.push({ type: "download_progress", downloads: downloadSnapshots.forPanel() }, panelTab);
             // Seed this tab's live queue monitor right away: queue_status broadcasts
             // are change-only, so a tab connecting MID-render would otherwise wait for
             // the next state transition to learn a job is already running.
@@ -3423,9 +3455,12 @@ export async function runPanelOrchestrator() {
             const tool = typeof ev.tool === "string" ? ev.tool : "";
             const toolArgs = ev.args && typeof ev.args === "object" ? ev.args : {};
             void (async () => {
-                if (!CALL_TOOL_WHITELIST.has(tool)) {
-                    bridge.push({ type: "tool_result", cid, tool, ok: false, error: `tool "${tool}" is not permitted` }, tabId);
-                    logger.warn(`[panel-orchestrator] call_tool rejected non-whitelisted "${tool}" (tab ${tabId.slice(0, 8)})`);
+                // Name-level whitelist plus, for consolidated tools, action-level scope
+                // (see call-tool-admission.ts). The name-refusal string is unchanged.
+                const denied = callToolAdmission(tool, toolArgs);
+                if (denied !== null) {
+                    bridge.push({ type: "tool_result", cid, tool, ok: false, error: denied }, tabId);
+                    logger.warn(`[panel-orchestrator] call_tool rejected: ${denied} (tab ${tabId.slice(0, 8)})`);
                     return;
                 }
                 const client = await getCallToolClient();
@@ -4003,7 +4038,6 @@ export async function runPanelOrchestrator() {
     catch {
         // no saved state
     }
-    let lastDownloadSnapshot = "[]";
     const pollDownloads = () => {
         let files = [];
         try {
@@ -4135,9 +4169,7 @@ export async function runPanelOrchestrator() {
         // must not count as idle. Self-healing: a crashed writer's row ages out.
         downloadingRows = downloads.filter((d) => d.status === "downloading");
         downloads.sort((a, b) => String(a.name ?? "").localeCompare(String(b.name ?? "")));
-        const snapshot = JSON.stringify(downloads);
-        if (snapshot !== lastDownloadSnapshot) {
-            lastDownloadSnapshot = snapshot;
+        if (downloadSnapshots.record(downloads)) {
             bridge.push({ type: "download_progress", downloads }); // broadcast to all tabs
         }
         // Flush any download-completion buckets whose debounce window has elapsed —