comfyui-mcp 0.43.0 → 0.44.0

package/dist/orchestrator/index.js

@@ -32,26 +32,29 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { registerAllTools } from "../tools/index.js";
-import { isForceRemoteFlagSet, isLoopbackHost, detectLocalComfyUIPath, setComfyuiTarget } from "../config.js";
+import { isForceRemoteFlagSet, isLoopbackHost, detectLocalComfyUIPath, setComfyuiTarget, onComfyuiTargetChanged, isTargetingLocal, getComfyUIBaseUrl } from "../config.js";
 import { buildComfyuiMcpEnv, comfyuiSecretKeys, onComfyuiSecretsChanged, hydrateAgentSecretsIntoEnv, onAgentSecretsChanged, setAgentSecret, setComfyuiSecret, isAllowedComfyuiSecretKey, } from "../services/panel-secrets.js";
 import { CodexBackend } from "./codex-backend.js";
 import { GeminiBackend, GEMINI_DEFAULT_MODEL } from "./gemini-backend.js";
+import { AntigravityBackend } from "./antigravity-backend.js";
 import { GrokBackend, GROK_DEFAULT_MODEL } from "./grok-backend.js";
 import { OllamaBackend, OLLAMA_SYSTEM_PROMPT } from "./ollama-backend.js";
 import { ChatGptOAuthBackend, CHATGPT_DEFAULT_MODEL } from "./chatgpt-oauth-backend.js";
-import { GlmBackend, GLM_DEFAULT_MODEL } from "./glm-backend.js";
-import { KimiBackend, KIMI_DEFAULT_MODEL } from "./kimi-backend.js";
-import { MoonshotBackend, MOONSHOT_DEFAULT_MODEL } from "./moonshot-backend.js";
+import { KimiBackend } from "./kimi-backend.js";
+import { OPENAI_KEY_PROVIDER_IDS, openAiKeyProvider, simpleKeyProvider, openAiKeyProviderModel, } from "../services/openai-provider-registry.js";
+import { resolveOpenAiKeyCredentials } from "../services/code-provider-auth.js";
 import { CopilotBackend, COPILOT_DEFAULT_MODEL } from "./copilot-backend.js";
 import { SYSTEM as MODEL_CARD_SYSTEM } from "./ai-proposer.js";
 import { resolvePrompt, registerPrompt, onPromptsChanged } from "../services/prompt-overrides.js";
 import { allBackendReadiness } from "./backend-readiness.js";
 import { handleOAuthBegin, handleOAuthStatus, handleOAuthSignout } from "./oauth-bridge.js";
+import { buildStartFailureNotice } from "./start-failure-notice.js";
 import { OAUTH_PROVIDERS } from "../services/oauth-flow.js";
 import { startPanelMcpHttpServer } from "./panel-mcp-http.js";
 import { startPanelConsoleHttpServer } from "./panel-console-http.js";
 import { readComfyuiCrashLog, formatCrashNote } from "../services/crash-log.js";
 import { QueueMonitor } from "../services/queue-monitor.js";
+import { initRunpodWatcher, getRunpodWatcher } from "../services/runpod-watch.js";
 import { buildQueueStatusFrame, createQueueStatusBroadcaster, } from "../services/queue-status-broadcast.js";
 import { unloadAllOllama, warmOllama, resolveOllamaHost } from "../services/ollama-vram.js";
 import { isLocalLmstudio, startLmstudioServer, unloadAllLmstudio, warmLmstudio, } from "../services/lmstudio-lifecycle.js";
@@ -170,9 +173,10 @@ const HEADLESS_DIRECTIVE = "[HEADLESS SESSION — no ComfyUI panel/canvas is con
     "enqueuing returns a prompt_id immediately, so wait for it with get_job_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: it names the failed " +
-    "node with its exception, plus any missing models (exact file + the widget holding it) and missing node types, in one " +
-    "call. It is the canvas-less equivalent of the panel's \"why is this red?\", so do NOT try panel_view_errored_nodes here.";
+    "If the run FAILED — or the user asks why a render failed / what's missing — call diagnose_run FIRST, and do NOT use " +
+    "get_history for that: diagnose_run returns everything get_history would (failed node + exception + traceback) PLUS the " +
+    "missing models (exact file + the widget holding it) and missing node types that get_history omits, in one call. It is " +
+    "the canvas-less equivalent of the panel's \"why is this red?\", so also do NOT try panel_view_errored_nodes here.";
 /** Live stall threshold (seconds) pushed from the panel setting via a `set_config`
  *  frame — applies WITHOUT a reconnect. null = not set, fall back to env then the
  *  built-in default. Process-global: one ComfyUI per orchestrator. */
@@ -597,6 +601,22 @@ const CALL_TOOL_WHITELIST = new Set([
     "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 plus the
+    // user-initiated lifecycle actions (create/start/stop/connect/use_local/
+    // watch/unwatch) and the referral deploy link. Each tool validates its own
+    // pod state; the whitelist only gates reachability from a canvas-less client.
+    "runpod_pod_status",
+    "runpod_list_pods",
+    "runpod_pod_start",
+    "runpod_pod_stop",
+    "runpod_pod_create",
+    "runpod_pod_connect",
+    "runpod_pod_troubleshoot",
+    "runpod_use_local",
+    "runpod_watch",
+    "runpod_unwatch",
+    "runpod_deploy_link",
 ]);
 /** 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
@@ -974,6 +994,9 @@ export async function runPanelOrchestrator() {
     // COMFYUI_MCP_GEMINI_MODEL (default gemini-2.5-pro). The model is applied at spawn
     // via the CLI `--model` flag (ACP exposes no per-session model setter).
     const geminiModel = process.env.COMFYUI_MCP_GEMINI_MODEL ?? GEMINI_DEFAULT_MODEL;
+    // Antigravity (`agy`, issue #262): no default on purpose — unset means the
+    // account's own default model; the live catalog comes from `agy models`.
+    const antigravityModel = process.env.COMFYUI_MCP_ANTIGRAVITY_MODEL;
     const grokModel = process.env.COMFYUI_MCP_GROK_MODEL ?? GROK_DEFAULT_MODEL;
     // Ollama (local LLMs, issue #97): the model is a local tag applied PER
     // REQUEST — switching live is free. Default = OUR FINE-TUNE,
@@ -1001,14 +1024,18 @@ export async function runPanelOrchestrator() {
     {
         const hydrated = new Set(hydratedSecrets);
         const src = (k) => (process.env[k] ? (hydrated.has(k) ? "store" : "env") : "none");
-        logger.info(`[panel-orchestrator] keyed providers: openrouter=${src("OPENROUTER_API_KEY")}, glm=${src("GLM_API_KEY")}, kimi=${src("KIMI_API_KEY")}, moonshot=${src("MOONSHOT_API_KEY")}`);
+        const registryKeyed = OPENAI_KEY_PROVIDER_IDS.map((id) => `${id}=${src(openAiKeyProvider(id).envKeys[0])}`).join(", ");
+        logger.info(`[panel-orchestrator] keyed providers: openrouter=${src("OPENROUTER_API_KEY")}, ${registryKeyed}`);
     }
     const persistedAgent = getAgentSettings();
     let ollamaModel = process.env.COMFYUI_MCP_OLLAMA_MODEL ?? persistedAgent.ollama?.model ?? "artokun/gemma4-comfyui-mcp:e4b";
     const chatgptModel = process.env.COMFYUI_MCP_CHATGPT_MODEL ?? CHATGPT_DEFAULT_MODEL;
-    const glmModel = process.env.COMFYUI_MCP_GLM_MODEL ?? GLM_DEFAULT_MODEL;
-    const kimiModel = process.env.COMFYUI_MCP_KIMI_MODEL ?? KIMI_DEFAULT_MODEL;
-    const moonshotModel = process.env.COMFYUI_MCP_MOONSHOT_MODEL ?? MOONSHOT_DEFAULT_MODEL;
+    // kimi keeps a local model var (its bespoke KimiBackend takes it). glm/moonshot
+    // read their model straight from the registry via the shared factory, so no
+    // per-provider model var is needed for them anymore. All three still resolve to
+    // the exact value the old <provider>Model consts held
+    // (process.env.COMFYUI_MCP_<X>_MODEL ?? <X>_DEFAULT_MODEL).
+    const kimiModel = openAiKeyProviderModel(openAiKeyProvider("kimi"));
     // EXPERIMENTAL (ToS risk) — off by default, only reachable once the user has
     // signed in via the panel's experimental row (oauth-bridge.ts's
     // allow_experimental gate); never the defaultBackend/auto-pick.
@@ -1096,10 +1123,10 @@ export async function runPanelOrchestrator() {
         "codex",
         "chatgpt",
         "gemini",
+        "antigravity",
         "grok",
-        "glm",
-        "kimi",
-        "moonshot",
+        // Simple api-key providers (glm/kimi/moonshot) come from the registry.
+        ...OPENAI_KEY_PROVIDER_IDS,
         "ollama",
         "openrouter",
         "lmstudio",
@@ -1283,6 +1310,23 @@ export async function runPanelOrchestrator() {
         },
         close: async () => { },
     });
+    // ONE code path for the simple OpenAI-compatible api-key providers (glm,
+    // moonshot, …): resolve the provider's key + base URL (throws if absent), then
+    // build the shared OllamaBackend openai driver pinned to that host/key/model.
+    // Collapses the near-identical GlmBackend/MoonshotBackend classes. `kimi` is
+    // excluded (simpleKeyProvider filters it) — its OAuth prepare() keeps KimiBackend.
+    const makeOpenAiKeyBackend = (reg, extra = {}) => {
+        const creds = resolveOpenAiKeyCredentials(reg.id);
+        return new OllamaBackend({
+            ...extra,
+            cwd: comfyuiPath ?? process.cwd(),
+            backendId: reg.id,
+            model: openAiKeyProviderModel(reg),
+            api: "openai",
+            host: creds.baseUrl,
+            apiKey: creds.apiKey,
+        });
+    };
     const makeBackend = (key) => {
         const backend = backendOf(key);
         const panelTabId = panelTabOf(key);
@@ -1305,6 +1349,14 @@ export async function runPanelOrchestrator() {
                     mcpServers: makeHttpBackendMcpServers(panelTabId),
                 });
             }
+            if (backend === "antigravity") {
+                return new AntigravityBackend({
+                    cwd: comfyuiPath ?? process.cwd(),
+                    ...(antigravityModel ? { model: antigravityModel } : {}),
+                    systemAppend: panelSystemAppend,
+                    mcpServers: makeHttpBackendMcpServers(panelTabId),
+                });
+            }
             if (backend === "grok") {
                 return new GrokBackend({
                     cwd: comfyuiPath ?? process.cwd(),
@@ -1373,10 +1425,10 @@ export async function runPanelOrchestrator() {
                     mcpServers: makeHttpBackendMcpServers(panelTabId),
                 });
             }
-            if (backend === "glm") {
-                return new GlmBackend({
-                    cwd: comfyuiPath ?? process.cwd(),
-                    model: glmModel,
+            const simpleKeyReg = simpleKeyProvider(backend);
+            if (simpleKeyReg) {
+                // glm/moonshot (and any future simple api-key provider) share one factory.
+                return makeOpenAiKeyBackend(simpleKeyReg, {
                     systemAppend: panelSystemAppend,
                     comfyuiUrl,
                     mcpServers: makeHttpBackendMcpServers(panelTabId),
@@ -1391,15 +1443,6 @@ export async function runPanelOrchestrator() {
                     mcpServers: makeHttpBackendMcpServers(panelTabId),
                 });
             }
-            if (backend === "moonshot") {
-                return new MoonshotBackend({
-                    cwd: comfyuiPath ?? process.cwd(),
-                    model: moonshotModel,
-                    systemAppend: panelSystemAppend,
-                    comfyuiUrl,
-                    mcpServers: makeHttpBackendMcpServers(panelTabId),
-                });
-            }
             if (backend === "copilot") {
                 // EXPERIMENTAL (ToS risk) — prepare() throws a clear re-sign-in error if
                 // no ~/.comfyui-mcp/copilot-auth.json exists yet (resolveCopilotOAuth),
@@ -1435,32 +1478,35 @@ export async function runPanelOrchestrator() {
         let pb = probeBackends.get(backend);
         if (!pb) {
             try {
-                pb =
-                    backend === "codex"
+                const simpleKeyReg = simpleKeyProvider(backend);
+                pb = simpleKeyReg
+                    ? makeOpenAiKeyBackend(simpleKeyReg)
+                    : backend === "codex"
                         ? new CodexBackend({ cwd: comfyuiPath ?? process.cwd(), model: codexModel })
                         : backend === "chatgpt"
                             ? new ChatGptOAuthBackend({ cwd: comfyuiPath ?? process.cwd(), model: chatgptModel })
-                            : backend === "glm"
-                                ? new GlmBackend({ cwd: comfyuiPath ?? process.cwd(), model: glmModel })
-                                : backend === "kimi"
-                                    ? new KimiBackend({ cwd: comfyuiPath ?? process.cwd(), model: kimiModel })
-                                    : backend === "moonshot"
-                                        ? new MoonshotBackend({ cwd: comfyuiPath ?? process.cwd(), model: moonshotModel })
-                                        : backend === "ollama"
-                                            ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: ollamaModel, ...ollamaDeps() })
-                                            : backend === "grok"
-                                                ? new GrokBackend({ cwd: comfyuiPath ?? process.cwd(), model: grokModel })
-                                                : backend === "openrouter"
-                                                    ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: openrouterModel, ...openrouterDeps() })
-                                                    : backend === "lmstudio"
-                                                        ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: lmstudioModel, ...lmstudioDeps() })
-                                                        : backend === "llamacpp"
-                                                            ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: llamacppModel, ...llamacppDeps() })
-                                                            : backend === "custom"
-                                                                ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: customModel, ...customDeps() })
-                                                                : backend === "copilot"
-                                                                    ? new CopilotBackend({ cwd: comfyuiPath ?? process.cwd(), model: copilotModel })
-                                                                    : new GeminiBackend({ cwd: comfyuiPath ?? process.cwd(), model: geminiModel });
+                            : backend === "kimi"
+                                ? new KimiBackend({ cwd: comfyuiPath ?? process.cwd(), model: kimiModel })
+                                : backend === "ollama"
+                                    ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: ollamaModel, ...ollamaDeps() })
+                                    : backend === "antigravity"
+                                        ? new AntigravityBackend({
+                                            cwd: comfyuiPath ?? process.cwd(),
+                                            ...(antigravityModel ? { model: antigravityModel } : {}),
+                                        })
+                                        : backend === "grok"
+                                            ? new GrokBackend({ cwd: comfyuiPath ?? process.cwd(), model: grokModel })
+                                            : backend === "openrouter"
+                                                ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: openrouterModel, ...openrouterDeps() })
+                                                : backend === "lmstudio"
+                                                    ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: lmstudioModel, ...lmstudioDeps() })
+                                                    : backend === "llamacpp"
+                                                        ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: llamacppModel, ...llamacppDeps() })
+                                                        : backend === "custom"
+                                                            ? new OllamaBackend({ cwd: comfyuiPath ?? process.cwd(), model: customModel, ...customDeps() })
+                                                            : backend === "copilot"
+                                                                ? new CopilotBackend({ cwd: comfyuiPath ?? process.cwd(), model: copilotModel })
+                                                                : new GeminiBackend({ cwd: comfyuiPath ?? process.cwd(), model: geminiModel });
                 probeBackends.set(backend, pb);
             }
             catch (err) {
@@ -1562,13 +1608,34 @@ export async function runPanelOrchestrator() {
         onSeen: (key, mid) => {
             bridge.push({ type: "ack", ok: true, kind: "seen", mid }, panelTabOf(key));
         },
+        // PER-TAB start failure (issue #250): a backend that rejects at
+        // prepare()/first-connect — an invalid API key 401ing on an OpenAI-dialect
+        // provider (moonshot/glm/custom/openrouter), an unreachable endpoint — is a
+        // tab-local configuration error, the same class as the keyless ctor path
+        // (#209), one step later. Degrade THAT tab only: an honest say naming the
+        // provider with check-your-key guidance, plus a degraded ack so the panel
+        // shows the real state. The manager already dropped the dead agent, so
+        // fixing the key and Disconnect → Connect (or just re-sending) retries
+        // cleanly. This must NOT self-exit — a bad moonshot key on one tab was
+        // killing healthy sessions on every other tab.
+        onStartFailure: (key, message) => {
+            // Frame construction (hint selection via the key-provider registry,
+            // composite-key → panel-tab split, say + degraded ack + turn:done) lives
+            // in start-failure-notice.ts so it is unit-testable (issue #255).
+            const { panelTab, backend, frames } = buildStartFailureNotice(key, message, defaultBackend);
+            for (const frame of frames)
+                bridge.push(frame, panelTab);
+            logger.warn(`[panel-orchestrator] tab ${panelTab.slice(0, 8)} (${backend}) agent failed to start — degraded THIS tab only, other tabs unaffected (${message})`);
+        },
         // ROOT-CAUSE self-exit (the "bridge open but no panel agent responded" wedge):
-        // a tab's agent died fatally (couldn't start, or its bounded self-restart gave
-        // up). The orchestrator is alive and the bridge is up, but no agent will ever
-        // handshake — exactly the wedge. Exit cleanly so the panel pack's bridge-death
-        // → reclaim + sticky-reconnect respawns a FRESH orchestrator, instead of
-        // leaving the user staring at the manual "fully restart ComfyUI" warning.
-        // Mirrors the uncaughtException exit above (Node's own default on a fatal).
+        // a tab's agent died fatally — its bounded self-restart loop gave up (the
+        // session kept dropping immediately). The orchestrator is alive and the
+        // bridge is up, but no agent will ever handshake — exactly the wedge. Exit
+        // cleanly so the panel pack's bridge-death → reclaim + sticky-reconnect
+        // respawns a FRESH orchestrator, instead of leaving the user staring at the
+        // manual "fully restart ComfyUI" warning. Mirrors the uncaughtException exit
+        // above (Node's own default on a fatal). Start failures no longer route here
+        // (issue #250) — they degrade per-tab via onStartFailure above.
         onAgentFatal: (tabId, reason) => {
             requestSelfExit(`tab ${tabId.slice(0, 8)} ${reason}`);
         },
@@ -1822,6 +1889,8 @@ export async function runPanelOrchestrator() {
             return codexModel;
         if (backend === "gemini")
             return geminiModel;
+        if (backend === "antigravity")
+            return antigravityModel;
         if (backend === "grok")
             return grokModel;
         if (backend === "ollama")
@@ -1836,12 +1905,9 @@ export async function runPanelOrchestrator() {
             return customModel || undefined;
         if (backend === "chatgpt")
             return chatgptModel;
-        if (backend === "glm")
-            return glmModel;
-        if (backend === "kimi")
-            return kimiModel;
-        if (backend === "moonshot")
-            return moonshotModel;
+        const reg = openAiKeyProvider(backend);
+        if (reg)
+            return openAiKeyProviderModel(reg); // glm / kimi / moonshot
         if (backend === "copilot")
             return copilotModel;
         return model;
@@ -2061,6 +2127,13 @@ export async function runPanelOrchestrator() {
             // are change-only, so a tab connecting MID-render would otherwise wait for
             // the next state transition to learn a job is already running.
             bridge.push(buildQueueStatusFrame(QueueMonitor.snapshot()), panelTab);
+            // Seed the RunPod control panel too — a tab that just connected gets the
+            // current pod-status frame (or a cleared one when nothing is watched).
+            const rpFrame = getRunpodWatcher()?.current();
+            if (rpFrame)
+                bridge.push(rpFrame, panelTab);
+            // Seed the honest host indicator: tell this tab where renders run now.
+            bridge.push({ type: "comfyui_target", url: getComfyUIBaseUrl(), is_local: isTargetingLocal() }, panelTab);
             // Re-push the last usage so the context meter isn't blank after a reload.
             const lastStatus = manager.lastStatusFor(key);
             if (lastStatus)
@@ -2072,10 +2145,10 @@ export async function runPanelOrchestrator() {
             const isCx = backend === "codex";
             const isCg = backend === "chatgpt";
             const isGm = backend === "gemini";
+            const isAg = backend === "antigravity";
             const isGk = backend === "grok";
-            const isGl = backend === "glm";
-            const isKm = backend === "kimi";
-            const isMs = backend === "moonshot";
+            // glm/kimi/moonshot share one registry-driven ack (label + ready + degraded).
+            const reg = openAiKeyProvider(backend);
             const isOl = backend === "ollama";
             const isOr = backend === "openrouter";
             const isLs = backend === "lmstudio";
@@ -2116,33 +2189,31 @@ export async function runPanelOrchestrator() {
                 : ensureModels(backend))
                 .then((models) => {
                 if (models.length) {
-                    const agentLabel = isCx
-                        ? (codexModel ?? models[0].value ?? "Codex")
-                        : isCg
-                            ? (chatgptModel ?? models[0].value ?? "ChatGPT")
-                            : isGm
-                                ? (geminiModel ?? models[0].value ?? "Gemini")
-                                : isGk
-                                    ? (grokModel ?? models[0].value ?? "Grok")
-                                    : isGl
-                                        ? (glmModel ?? models[0].value ?? "GLM")
-                                        : isKm
-                                            ? (kimiModel ?? models[0].value ?? "Kimi")
-                                            : isMs
-                                                ? (moonshotModel ?? models[0].value ?? "Kimi K3")
-                                                : isOl
-                                                    ? (ollamaModel ?? models[0].value ?? "Ollama")
-                                                    : isLs
-                                                        ? (lmstudioModel || (models[0].value ?? "LM Studio"))
-                                                        : isLc
-                                                            ? (llamacppModel || (models[0].value ?? "llama.cpp"))
-                                                            : isCu
-                                                                ? (customModel || (models[0].value ?? "Custom endpoint"))
-                                                                : isOr
-                                                                    ? (openrouterModel ?? models[0].value ?? "OpenRouter")
-                                                                    : isCp
-                                                                        ? (copilotModel ?? models[0].value ?? "Copilot")
-                                                                        : model;
+                    const agentLabel = reg
+                        ? (openAiKeyProviderModel(reg) ?? models[0].value ?? reg.ackFallbackLabel)
+                        : isCx
+                            ? (codexModel ?? models[0].value ?? "Codex")
+                            : isCg
+                                ? (chatgptModel ?? models[0].value ?? "ChatGPT")
+                                : isGm
+                                    ? (geminiModel ?? models[0].value ?? "Gemini")
+                                    : isAg
+                                        ? (antigravityModel ?? models[0].value ?? "Antigravity")
+                                        : isGk
+                                            ? (grokModel ?? models[0].value ?? "Grok")
+                                            : isOl
+                                                ? (ollamaModel ?? models[0].value ?? "Ollama")
+                                                : isLs
+                                                    ? (lmstudioModel || (models[0].value ?? "LM Studio"))
+                                                    : isLc
+                                                        ? (llamacppModel || (models[0].value ?? "llama.cpp"))
+                                                        : isCu
+                                                            ? (customModel || (models[0].value ?? "Custom endpoint"))
+                                                            : isOr
+                                                                ? (openrouterModel ?? models[0].value ?? "OpenRouter")
+                                                                : isCp
+                                                                    ? (copilotModel ?? models[0].value ?? "Copilot")
+                                                                    : model;
                     // llama.cpp launch gotchas (issue #161): a reachable server can still
                     // be useless for us — tool calling needs --jinja (rejected requests),
                     // and a launch-time -c under ~16K silently truncates the tool payload.
@@ -2172,64 +2243,60 @@ export async function runPanelOrchestrator() {
                     }
                     // Greet only on a FRESH session (a resume/reconnect already has the thread).
                     if (!resume) {
-                        const readyText = isCx
-                            ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your Codex (ChatGPT) account. Ask away.`
-                            : isCg
-                                ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your ChatGPT subscription (direct OAuth). Ask away.`
-                                : isGm
-                                    ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your Google account (Gemini Code Assist). Ask away.`
-                                    : isGk
-                                        ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your Grok (xAI) account. Ask away.`
-                                        : isGl
-                                            ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your Z.AI GLM Coding Plan. Ask away.`
-                                            : isKm
-                                                ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your Kimi Code subscription. Ask away.`
-                                                : isMs
-                                                    ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your Moonshot platform (Kimi K3) API key. Ask away.`
-                                                    : isOl
-                                                        ? `🟢 comfyui-mcp agent ready — ${agentLabel} running locally via Ollama (no account, no API key). Small local models are slower and simpler than frontier ones — expect fewer frills. Ask away.`
-                                                        : isLs
-                                                            ? `🟢 comfyui-mcp agent ready — ${agentLabel} running locally via LM Studio (no account, no API key). Small local models are slower and simpler than frontier ones — expect fewer frills. Ask away.`
-                                                            : isLc
-                                                                ? `🟢 comfyui-mcp agent ready — ${agentLabel} running locally via llama.cpp (no account, no API key). Small local models are slower and simpler than frontier ones — expect fewer frills. Ask away.`
-                                                                : isCu
-                                                                    ? `🟢 comfyui-mcp agent ready — ${agentLabel} via your custom endpoint (${customBaseUrl}). Ask away.`
-                                                                    : isOr
-                                                                        ? `🟢 comfyui-mcp agent ready — ${agentLabel} via OpenRouter (hosted API, your OPENROUTER_API_KEY). Ask away.`
-                                                                        : isCp
-                                                                            ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your GitHub Copilot subscription (⚠️ experimental, ToS risk — you opted in). Ask away.`
-                                                                            : `🟢 comfyui-mcp agent ready — ${agentLabel} on your Claude subscription. Ask away.`;
+                        const readyText = reg
+                            ? reg.readyMessage(agentLabel)
+                            : isCx
+                                ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your Codex (ChatGPT) account. Ask away.`
+                                : isCg
+                                    ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your ChatGPT subscription (direct OAuth). Ask away.`
+                                    : isGm
+                                        ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your Google account (Gemini Code Assist). Ask away.`
+                                        : isAg
+                                            ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your Google AI subscription via Antigravity CLI. Note: agy turns show final answers only (no live tool progress). Ask away.`
+                                            : isGk
+                                                ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your Grok (xAI) account. Ask away.`
+                                                : isOl
+                                                    ? `🟢 comfyui-mcp agent ready — ${agentLabel} running locally via Ollama (no account, no API key). Small local models are slower and simpler than frontier ones — expect fewer frills. Ask away.`
+                                                    : isLs
+                                                        ? `🟢 comfyui-mcp agent ready — ${agentLabel} running locally via LM Studio (no account, no API key). Small local models are slower and simpler than frontier ones — expect fewer frills. Ask away.`
+                                                        : isLc
+                                                            ? `🟢 comfyui-mcp agent ready — ${agentLabel} running locally via llama.cpp (no account, no API key). Small local models are slower and simpler than frontier ones — expect fewer frills. Ask away.`
+                                                            : isCu
+                                                                ? `🟢 comfyui-mcp agent ready — ${agentLabel} via your custom endpoint (${customBaseUrl}). Ask away.`
+                                                                : isOr
+                                                                    ? `🟢 comfyui-mcp agent ready — ${agentLabel} via OpenRouter (hosted API, your OPENROUTER_API_KEY). Ask away.`
+                                                                    : isCp
+                                                                        ? `🟢 comfyui-mcp agent ready — ${agentLabel} on your GitHub Copilot subscription (⚠️ experimental, ToS risk — you opted in). Ask away.`
+                                                                        : `🟢 comfyui-mcp agent ready — ${agentLabel} on your Claude subscription. Ask away.`;
                         bridge.push({ type: "say", text: readyText }, panelTab);
                     }
                     bridge.push({ type: "ack", ok: true, kind: "ready", agent: agentLabel, backend }, panelTab);
                     logger.debug(`[panel-orchestrator] tab ${panelTab.slice(0, 8)} connected (${backend}) — agent healthy, ready ack`);
                 }
                 else {
-                    const degradedText = isCx
-                        ? "⚠️ The background agent isn't responding — the Codex app-server couldn't start. Make sure Codex is installed and signed in (run `codex login`), then Disconnect → Connect to retry."
-                        : isCg
-                            ? "⚠️ The background agent isn't responding — ChatGPT direct OAuth couldn't start. Make sure ~/.codex/auth.json exists (run `codex login`), then Disconnect → Connect to retry."
-                            : isGm
-                                ? "⚠️ The background agent isn't responding — the Gemini CLI couldn't start. Make sure the Gemini CLI is installed and signed in (run `gemini` once and complete the Google sign-in), then Disconnect → Connect to retry."
-                                : isGk
-                                    ? "⚠️ The background agent isn't responding — the Grok CLI couldn't start. Make sure Grok is installed and signed in (run `grok` once and complete the xAI sign-in), then Disconnect → Connect to retry."
-                                    : isGl
-                                        ? "⚠️ The background agent isn't responding — GLM Code API couldn't start. Set ZAI_API_KEY (Z.AI Coding Plan), then Disconnect → Connect to retry."
-                                        : isKm
-                                            ? "⚠️ The background agent isn't responding — Kimi Code couldn't start. Run Kimi Code login (~/.kimi/credentials/kimi-code.json) or set KIMI_API_KEY, then Disconnect → Connect to retry."
-                                            : isMs
-                                                ? "⚠️ The background agent isn't responding — Moonshot (Kimi K3) couldn't start. Set MOONSHOT_API_KEY from platform.kimi.ai, then Disconnect → Connect to retry."
-                                                : isOl
-                                                    ? "⚠️ The background agent isn't responding — Ollama isn't reachable. Start it with `ollama serve` and pull our fine-tuned model (`ollama pull artokun/gemma4-comfyui-mcp:e4b` — gemma4 trained on the comfyui-mcp tool suite — arena-best local model; `:12b` for ~8 GB VRAM), then Disconnect → Connect to retry."
-                                                    : isLs
-                                                        ? `⚠️ The background agent isn't responding — LM Studio isn't reachable at ${LMSTUDIO_BASE_URL}. Open LM Studio → Developer → Start Server and load a tool-calling model (our gemma4-comfyui-mcp GGUFs from Hugging Face work great), or set COMFYUI_MCP_LMSTUDIO_HOST if it serves elsewhere — then Disconnect → Connect to retry.`
-                                                        : isLc
-                                                            ? `⚠️ The background agent isn't responding — llama-server isn't reachable at ${LLAMACPP_BASE_URL}. Start it with \`llama-server -m <model>.gguf -c 16384\` (our gemma4-comfyui-mcp GGUFs work great; add --jinja on older builds — required there for tool calling), or set COMFYUI_MCP_LLAMACPP_HOST — then Disconnect → Connect to retry.`
-                                                            : isCu
-                                                                ? `⚠️ The background agent isn't responding — your custom endpoint isn't answering at ${customBaseUrl}. Check the base URL in Settings → Custom endpoint (it must be OpenAI-compatible and include the /v1) and the API key if the server requires one — then Connect to retry.`
-                                                                : isCp
-                                                                    ? "⚠️ The background agent isn't responding — GitHub Copilot (experimental) couldn't start. Sign in from the panel's experimental row, then Disconnect → Connect to retry."
-                                                                    : "⚠️ The background agent isn't responding — the Claude Agent SDK couldn't start. Make sure you're signed in (run `claude` once), then Disconnect → Connect to retry.";
+                    const degradedText = reg
+                        ? reg.degradedMessage
+                        : isCx
+                            ? "⚠️ The background agent isn't responding — the Codex app-server couldn't start. Make sure Codex is installed and signed in (run `codex login`), then Disconnect → Connect to retry."
+                            : isCg
+                                ? "⚠️ The background agent isn't responding — ChatGPT direct OAuth couldn't start. Make sure ~/.codex/auth.json exists (run `codex login`), then Disconnect → Connect to retry."
+                                : isGm
+                                    ? "⚠️ The background agent isn't responding — the Gemini CLI couldn't start. Make sure the Gemini CLI is installed and signed in (run `gemini` once and complete the Google sign-in), then Disconnect → Connect to retry."
+                                    : isAg
+                                        ? "⚠️ The background agent isn't responding — the Antigravity CLI couldn't answer `agy models`. Install it from https://antigravity.google, run `agy` once and complete the Google Sign-In, then Disconnect → Connect to retry."
+                                        : isGk
+                                            ? "⚠️ The background agent isn't responding — the Grok CLI couldn't start. Make sure Grok is installed and signed in (run `grok` once and complete the xAI sign-in), then Disconnect → Connect to retry."
+                                            : isOl
+                                                ? "⚠️ The background agent isn't responding — Ollama isn't reachable. Start it with `ollama serve` and pull our fine-tuned model (`ollama pull artokun/gemma4-comfyui-mcp:e4b` — gemma4 trained on the comfyui-mcp tool suite — arena-best local model; `:12b` for ~8 GB VRAM), then Disconnect → Connect to retry."
+                                                : isLs
+                                                    ? `⚠️ The background agent isn't responding — LM Studio isn't reachable at ${LMSTUDIO_BASE_URL}. Open LM Studio → Developer → Start Server and load a tool-calling model (our gemma4-comfyui-mcp GGUFs from Hugging Face work great), or set COMFYUI_MCP_LMSTUDIO_HOST if it serves elsewhere — then Disconnect → Connect to retry.`
+                                                    : isLc
+                                                        ? `⚠️ The background agent isn't responding — llama-server isn't reachable at ${LLAMACPP_BASE_URL}. Start it with \`llama-server -m <model>.gguf -c 16384\` (our gemma4-comfyui-mcp GGUFs work great; add --jinja on older builds — required there for tool calling), or set COMFYUI_MCP_LLAMACPP_HOST — then Disconnect → Connect to retry.`
+                                                        : isCu
+                                                            ? `⚠️ The background agent isn't responding — your custom endpoint isn't answering at ${customBaseUrl}. Check the base URL in Settings → Custom endpoint (it must be OpenAI-compatible and include the /v1) and the API key if the server requires one — then Connect to retry.`
+                                                            : isCp
+                                                                ? "⚠️ The background agent isn't responding — GitHub Copilot (experimental) couldn't start. Sign in from the panel's experimental row, then Disconnect → Connect to retry."
+                                                                : "⚠️ The background agent isn't responding — the Claude Agent SDK couldn't start. Make sure you're signed in (run `claude` once), then Disconnect → Connect to retry.";
                     bridge.push({ type: "say", text: degradedText }, panelTab);
                     bridge.push({ type: "ack", ok: false, kind: "degraded" }, panelTab);
                     logger.warn(`[panel-orchestrator] tab ${panelTab.slice(0, 8)} connected (${backend}) but model probe empty — degraded ack`);
@@ -2939,7 +3006,17 @@ export async function runPanelOrchestrator() {
                 type: "say",
                 text: "⏸ A render is running, so I've kept the GPU free for it and queued your message. I'll answer the moment it finishes.",
             }, event.tab_id);
-            bridge.push({ type: "turn", state: "idle" }, event.tab_id); // clear the working spinner
+            // Clear the working spinner — the panel's turn handler only recognizes
+            // "working" and "done", so the old "idle" frame never cleared it and the
+            // spinner ran until the 120s safety timeout (issue #257). But ONLY when no
+            // agent turn is actually in flight for this tab: a tab-wide "done" during
+            // an ACTIVE earlier turn would hide THAT turn's spinner and disarm its
+            // resume nudge (the idle frame was a load-bearing no-op in that case —
+            // #260 review). When a turn IS active we push nothing: the live turn's own
+            // turn:"done" clears the spinner at the right moment.
+            if (!manager.isTurnActive(key)) {
+                bridge.push({ type: "turn", state: "done" }, event.tab_id);
+            }
             return;
         }
         manager.send(agentKeyFor(event.tab_id), outText, sendOpts);
@@ -3017,9 +3094,47 @@ export async function runPanelOrchestrator() {
     // `queue_status` frame at most once per second, and ONLY when the state
     // changed, so an idle rig costs the tabs nothing (see
     // services/queue-status-broadcast.ts for the frame shape + throttle contract).
-    const queueStatusBroadcaster = createQueueStatusBroadcaster(() => QueueMonitor.snapshot(), (frame) => void bridge.push(frame));
-    const queueStatusTimer = setInterval(() => queueStatusBroadcaster.tick(), 1000);
+    const queueStatusBroadcaster = createQueueStatusBroadcaster(() => QueueMonitor.snapshot(), (frame) => void bridge.push(frame), () => QueueMonitor.drainCompletions());
+    // Each tick first refreshes the monitor over HTTP (GET /queue + /history
+    // tail): on modern ComfyUI (0.28+) the passive watchdog WS carries no
+    // prompt_id and no completion events for foreign runs, so the poll is what
+    // restores run attribution (#258) and catches runs shorter than the tick
+    // (#259). poll() never rejects and self-guards against overlap.
+    const queueStatusTimer = setInterval(() => {
+        void QueueMonitor.poll().finally(() => queueStatusBroadcaster.tick());
+    }, 1000);
     queueStatusTimer.unref?.();
+    // RunPod live-status broadcast + idle auto-stop (services/runpod-watch.ts).
+    // Polls the WATCHED pod (set by runpod_pod_connect / runpod_watch) every ~15s
+    // and pushes a `runpod_status` frame to the panel/mobile control panels; when
+    // the connected pod's ComfyUI sits idle past RUNPOD_IDLE_STOP_MINUTES (default
+    // 15; 0 disables) it auto-stops the pod to save GPU cost (gpu-cli parity). No
+    // pod watched → the poller is a no-op, so this costs an idle rig nothing.
+    const runpodIdleStopMinutes = (() => {
+        const v = Number(process.env.RUNPOD_IDLE_STOP_MINUTES);
+        return Number.isFinite(v) && v >= 0 ? v : 15;
+    })();
+    initRunpodWatcher({
+        push: (frame) => void bridge.push(frame),
+        comfyuiIdle: () => {
+            const s = QueueMonitor.snapshot();
+            return s.connected && !s.running && s.queueDepth === 0;
+        },
+        // Idle auto-stop only applies to a pod we're actually rendering on: the active
+        // ComfyUI target is that pod's proxy (its id appears in the URL). A pod we
+        // merely watch while it boots stays local-targeted, so this is false and it is
+        // never auto-stopped on the local rig's idleness.
+        renderingOnPod: (podId) => !isTargetingLocal() && getComfyUIBaseUrl().includes(podId),
+        idleStopMinutes: runpodIdleStopMinutes,
+    });
+    // Honest host indicator: whenever the ComfyUI target moves (RunPod connect,
+    // pod stop → local fallback, "Local" switch), broadcast a `comfyui_target`
+    // frame so every control panel truthfully shows where renders run. Seeded per
+    // tab on connect (below) so a fresh tab knows the host without waiting for a
+    // switch.
+    onComfyuiTargetChanged((url, isLocal) => {
+        void bridge.push({ type: "comfyui_target", url, is_local: isLocal });
+    });
     // Keep the pod's stored bridge URL fresh so a ComfyUI RESTART self-heals fast.
     // The panel's advertised wss:// URL/token lives in the pod ComfyUI process's
     // MEMORY (the panel __init__'s advertise store). A restart — which the agent
@@ -3111,6 +3226,11 @@ export async function runPanelOrchestrator() {
     // opt-out: COMFYUI_MCP_AUTORESTART=0).
     selfRestarter = new SelfRestarter({
         allIdle: () => manager.allIdle() &&
+            // Failed-start held mail (issue #256): teardown erases it, so a restart
+            // while it's parked would silently drop the messages awaiting re-delivery.
+            // (allIdle() already covers this; kept explicit alongside heldDuringGen so
+            // the gate reads as the full "nothing queued or held" contract.)
+            !manager.hasHeldMail() &&
             ![...heldDuringGen.values()].some((msgs) => msgs.length > 0) &&
             !QueueMonitor.isBusy(),
         announce: (text) => void bridge.push({ type: "say", text }),