carouselbot 0.3.0 → 0.3.2

package/README.md

@@ -6,8 +6,11 @@ Local-first MCP companion for the hosted [CarouselBot editor](https://carousel.b
 npx carouselbot@latest setup
 ```
 
-Setup pins that exact package version in the generated MCP configuration. Rerun
-the command when you intentionally want to update.
+Setup pins that exact package version in the generated MCP configuration, refreshes
+the agent skill, and automatically upgrades an older shared daemon. Rerun the
+command when you intentionally want to update. When setup runs inside a named
+Hermes profile, it also installs the skill into that profile's active
+HERMES_HOME and non-interactively enables the discovered CarouselBot tools.
 
 For non-interactive agent setup, select the current client explicitly:
 
@@ -34,7 +37,7 @@ Folders use exact canonical slash paths such as `/campaigns` and are derived fro
 
 Always use `list_editors` to check the browser connection. Do not open CarouselBot or click **Connect AI** through a sandboxed, remote, or agent-controlled browser: that is a different browser session and may not reach the local companion.
 
-Browser reconnection is automatic. Retry transient disconnects; use `restart` only for an explicit protocol mismatch or failed daemon health check. Hermes can refresh native tools with `/reload-mcp` and `/reload-skills`. Claude may need a new session to register a newly added server, but the CLI fallback works immediately.
+Browser and MCP-process reconnection are automatic, including after a compatible daemon upgrade. The MCP checks the daemon's advertised internal actions rather than trusting the browser protocol number alone. Retry transient disconnects; use `restart` only when automatic recovery or `doctor` reports a failed daemon health check. An already-running host may still need to refresh its native tool catalog when a release adds entirely new tool names; the CLI fallback works immediately without waiting for that refresh.
 
 The companion binds only to `127.0.0.1`. There is no hosted relay: projects remain in browser IndexedDB and local images remain on the user's computer.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carouselbot",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Local-first MCP companion for the hosted CarouselBot editor",
   "type": "module",
   "license": "MIT",

package/skill/carouselbot/SKILL.md

@@ -16,7 +16,9 @@ Before using any browser or making edits, call `list_editors`. A registered edit
 
 Browser reconnection is automatic. After `EDITOR_DISCONNECTED`, `EDITOR_RELOADED`, a dropped browser request, or an empty `list_editors` result that follows a working connection, wait briefly and retry `list_editors` several times. Do not restart the companion for a transient browser disconnect: restarting invalidates every browser session and makes recovery slower. If the editor does not return, ask the user to keep or reload the real editor tab; preserve completed project work and begin a new edit session after it reconnects.
 
-Run `npx -y carouselbot@latest restart` only when the MCP explicitly reports an outdated companion protocol or `doctor` reports that the daemon itself is unhealthy. After a necessary restart, ask the user to reload their real editor tab and retry `list_editors`.
+The MCP checks the shared daemon's actual internal capabilities before advertising tools. It automatically replaces an outdated daemon, keeps the MCP process alive, and lets the remembered browser connection reconnect. Do not ask the user to reload MCP or restart Hermes for daemon recovery.
+
+If an advertised tool nevertheless returns `UNSUPPORTED_INTERNAL_ACTION` or `Unknown internal action`, stop after that first failure; do not fan out parallel retries that can trip the host's whole-server circuit breaker. Retry `list_editors` once so automatic recovery can finish, then retry the original tool once. If recovery itself reports that no compatible companion could start, run `npx -y carouselbot@latest doctor` and then `npx -y carouselbot@latest restart` once. Only ask the user to reload their real editor tab if it does not reconnect automatically. Never restart the companion for a transient browser disconnect.
 
 If the native MCP tools are not registered in the current session, do not stop or ask for a restart. Use the same validated tools through the local CLI fallback:
 
@@ -27,7 +29,7 @@ npx -y carouselbot@latest call list_tools --json '{"names":["create_project","mo
 npx -y carouselbot@latest call create_project --json '{"name":"My presentation","folderPath":"/campaigns"}'
 ```
 
-Every tool accepts the same JSON arguments as MCP. Use `list_tools` without arguments for compact discovery or pass `{"names":[...]}` to retrieve selected schemas. Prefer `apply_operations` for batches. `render_slide` writes its returned image to a temporary local `previewPath`; inspect that file and remove the temporary directory after the review. Hermes can load the native tools in place with `/reload-mcp` and refresh this skill with `/reload-skills`.
+Every tool accepts the same JSON arguments as MCP. Use `list_tools` without arguments for compact discovery or pass `{"names":[...]}` to retrieve selected schemas. Prefer `apply_operations` for batches. `render_slide` writes its returned image to a temporary local `previewPath`; inspect that file and remove the temporary directory after the review. A daemon replacement never requires `/reload-mcp`. Hermes only needs `/reload-mcp` when a package update adds entirely new native tool names to an already-running agent session; use the CLI fallback immediately in that rare case. A newly installed skill becomes active in the next session or after `/reload-skills`, but correctness must never depend on the user doing that manually.
 
 Before the first mutation in a task, call `get_design_guidance`. The server intentionally rejects mutations until this guidance has been read.
 

package/src/companion.mjs

@@ -2,10 +2,15 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
-import { BRIDGE_URL, DAEMON_STATE_PATH, PACKAGE_VERSION, PROTOCOL_VERSION } from "./config.mjs";
+import {
+  BRIDGE_URL, DAEMON_API_VERSION, DAEMON_INTERNAL_ACTIONS, DAEMON_STATE_PATH,
+  PACKAGE_VERSION, PROTOCOL_VERSION,
+} from "./config.mjs";
 import { preferHostAgent } from "./agent-identity.mjs";
 
 const DAEMON_ENTRY = fileURLToPath(new URL("daemon.mjs", import.meta.url));
+const START_TIMEOUT_MS = 8_000;
+const STOP_TIMEOUT_MS = 8_000;
 
 const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 
@@ -23,62 +28,158 @@ async function daemonRequest(state, path, init = {}) {
   if (!response.ok) {
     const error = new Error(value.error || `Local companion returned ${response.status}.`);
     error.status = response.status;
+    if (value.code) error.code = value.code;
+    if (value.details) error.details = value.details;
     throw error;
   }
   return value;
 }
 
-async function healthyState() {
+function compatibilityIssue(health, { requireCurrentVersion = false } = {}) {
+  if (health.protocolVersion !== PROTOCOL_VERSION) {
+    return `browser protocol ${health.protocolVersion ?? "unknown"} (requires ${PROTOCOL_VERSION})`;
+  }
+  const advertisedActions = new Set(Array.isArray(health.capabilities?.internalActions) ? health.capabilities.internalActions : []);
+  const missingActions = DAEMON_INTERNAL_ACTIONS.filter((action) => !advertisedActions.has(action));
+  if (missingActions.length) return `missing internal actions: ${missingActions.join(", ")}`;
+  const advertisedApiVersion = Number(health.daemonApiVersion);
+  if (!Number.isInteger(advertisedApiVersion) || advertisedApiVersion < DAEMON_API_VERSION) {
+    return `daemon API ${health.daemonApiVersion ?? "unknown"} (requires ${DAEMON_API_VERSION})`;
+  }
+  if (requireCurrentVersion && health.version !== PACKAGE_VERSION) {
+    return `package ${health.version || "unknown"} (requires ${PACKAGE_VERSION})`;
+  }
+  return null;
+}
+
+function stateWithHealth(state, health) {
+  return {
+    ...state,
+    pid: health.pid || state.pid,
+    version: health.version || state.version || null,
+    protocolVersion: health.protocolVersion,
+    daemonApiVersion: health.daemonApiVersion,
+    capabilities: health.capabilities,
+  };
+}
+
+async function inspectDaemon(options = {}) {
   const state = await readState();
   if (!state?.secret || state.port == null) return null;
   try {
-    const result = await daemonRequest(state, "/internal/health");
-    if (result.protocolVersion !== PROTOCOL_VERSION) {
-      const error = new Error(`Local companion ${result.version || "unknown"} uses protocol ${result.protocolVersion}; ${PACKAGE_VERSION} requires protocol ${PROTOCOL_VERSION}. Run \`npx -y carouselbot@latest restart\`, then reload the editor.`);
-      error.code = "EPROTOCOL";
-      throw error;
-    }
-    return state;
-  } catch (error) {
-    if (error.code === "EPROTOCOL") throw error;
+    const health = await daemonRequest(state, "/internal/health");
+    return { state: stateWithHealth(state, health), health, issue: compatibilityIssue(health, options) };
+  } catch {
     return null;
   }
 }
 
-async function ensureDaemon() {
-  const existing = await healthyState();
-  if (existing) return existing;
+async function processIsRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch { return false; }
+}
+
+async function stopDaemon({ state, health }) {
+  const pid = Number(health?.pid || state?.pid);
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  let shutdownAccepted = false;
+  try {
+    const response = await daemonRequest(state, "/internal/shutdown", { method: "POST", body: "{}" });
+    shutdownAccepted = response?.pid === pid;
+  } catch { /* Older companions may not expose graceful shutdown. */ }
+  if (!shutdownAccepted) {
+    try { process.kill(pid, "SIGTERM"); } catch { return; }
+  }
+  const deadline = Date.now() + STOP_TIMEOUT_MS;
+  while (Date.now() < deadline && await processIsRunning(pid)) await wait(100);
+  if (await processIsRunning(pid)) {
+    try { process.kill(pid, "SIGTERM"); } catch { /* It already stopped. */ }
+    const forcedDeadline = Date.now() + 2_000;
+    while (Date.now() < forcedDeadline && await processIsRunning(pid)) await wait(100);
+  }
+}
+
+let ensureQueue = Promise.resolve();
+
+async function ensureDaemonOnce({ forceReplace = false, requireCurrentVersion = false } = {}) {
+  const options = { requireCurrentVersion };
+  const existing = await inspectDaemon(options);
+  if (existing && !forceReplace && !existing.issue) return existing.state;
+  if (existing) await stopDaemon(existing);
+
   const child = spawn(process.execPath, [DAEMON_ENTRY], {
     detached: true,
     stdio: "ignore",
     env: process.env,
   });
   child.unref();
-  const deadline = Date.now() + 8000;
+
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  let lastIssue = existing?.issue || null;
   while (Date.now() < deadline) {
     await wait(100);
-    const state = await healthyState();
-    if (state) return state;
+    const candidate = await inspectDaemon(options);
+    if (!candidate) continue;
+    if (!candidate.issue) return candidate.state;
+    lastIssue = candidate.issue;
   }
-  throw new Error("Could not start the local CarouselBot companion. Run `npx carouselbot doctor` for details.");
+  const detail = lastIssue ? ` Last companion was incompatible: ${lastIssue}.` : "";
+  throw new Error(`Could not start a compatible local CarouselBot companion.${detail} Run \`npx -y carouselbot@latest doctor\` for details.`);
+}
+
+function ensureDaemon(options = {}) {
+  const operation = ensureQueue.then(() => ensureDaemonOnce(options));
+  ensureQueue = operation.catch(() => {});
+  return operation;
+}
+
+function unsupportedInternalAction(error) {
+  return error?.code === "UNSUPPORTED_INTERNAL_ACTION" || /Unknown internal action:/i.test(error?.message || "");
 }
 
 export async function createCompanion(initialName = "MCP agent", initialVersion = null) {
+  // Compatibility is resolved before the stdio server advertises its tools. A
+  // stale shared daemon is replaced in place; this MCP process stays alive and
+  // the browser's remembered loopback connection reconnects automatically.
   let state = await ensureDaemon();
   const clientId = randomUUID();
   let clientName = initialName;
   let clientVersion = initialVersion;
   let closed = false;
+  let unsupportedRecovery = null;
+  const repairedUnsupportedActions = new Set();
 
   const rawPost = (path, body) => daemonRequest(state, path, { method: "POST", body: JSON.stringify(body) });
   const register = () => rawPost("/internal/client/connect", { clientId, name: clientName, version: clientVersion });
+  const recoverUnsupportedAction = (action) => {
+    if (unsupportedRecovery) return unsupportedRecovery;
+    if (repairedUnsupportedActions.has(action)) return null;
+    repairedUnsupportedActions.add(action);
+    const recovery = (async () => {
+      state = await ensureDaemon({ forceReplace: true });
+      await register();
+    })();
+    const trackedRecovery = recovery.finally(() => {
+      if (unsupportedRecovery === trackedRecovery) unsupportedRecovery = null;
+    });
+    unsupportedRecovery = trackedRecovery;
+    return unsupportedRecovery;
+  };
   const post = async (path, body) => {
     try {
       return await rawPost(path, body);
     } catch (error) {
-      if (closed || (error.status && error.status !== 401)) throw error;
-      state = await ensureDaemon();
-      await register();
+      const unsupportedAction = path === "/internal/call" && unsupportedInternalAction(error) ? body.action : null;
+      if (closed || (error.status && error.status !== 401 && !unsupportedAction)) throw error;
+      if (unsupportedAction) {
+        const recovery = recoverUnsupportedAction(unsupportedAction);
+        if (!recovery) throw error;
+        await recovery;
+      } else {
+        state = await ensureDaemon();
+        await register();
+      }
       return rawPost(path, body);
     }
   };
@@ -90,11 +191,20 @@ export async function createCompanion(initialName = "MCP agent", initialVersion
 
   return {
     clientId,
-    get daemon() { return { pid: state.pid, url: BRIDGE_URL, version: state.version, packageVersion: PACKAGE_VERSION }; },
+    get daemon() {
+      return {
+        pid: state.pid,
+        url: BRIDGE_URL,
+        version: state.version,
+        packageVersion: PACKAGE_VERSION,
+        daemonApiVersion: state.daemonApiVersion,
+        capabilities: state.capabilities,
+      };
+    },
     async identify(name, version) {
       clientName = preferHostAgent(name, clientName);
       clientVersion = version || clientVersion;
-      await register();
+      await post("/internal/client/connect", { clientId, name: clientName, version: clientVersion });
     },
     async call(action, body = {}) {
       const response = await post("/internal/call", { clientId, action, ...body });
@@ -112,29 +222,34 @@ export async function createCompanion(initialName = "MCP agent", initialVersion
 export async function companionDoctor() {
   const state = await ensureDaemon();
   const health = await daemonRequest(state, "/internal/health");
-  return { ...health, url: BRIDGE_URL, stateFile: DAEMON_STATE_PATH };
+  return { ...health, packageVersion: PACKAGE_VERSION, compatible: true, url: BRIDGE_URL, stateFile: DAEMON_STATE_PATH };
+}
+
+export async function companionUpgrade() {
+  const previous = await inspectDaemon();
+  const state = await ensureDaemon({ requireCurrentVersion: true });
+  const health = await daemonRequest(state, "/internal/health");
+  return {
+    ...health,
+    packageVersion: PACKAGE_VERSION,
+    compatible: true,
+    upgraded: Boolean(previous && previous.health.version !== health.version),
+    previousPid: previous?.health.pid || null,
+    url: BRIDGE_URL,
+    stateFile: DAEMON_STATE_PATH,
+  };
 }
 
 export async function companionRestart() {
-  const previous = await readState();
-  if (previous?.secret && Number.isInteger(previous.pid) && previous.pid > 0) {
-    const health = await daemonRequest(previous, "/internal/health").catch(() => null);
-    if (health?.pid === previous.pid) {
-      await daemonRequest(previous, "/internal/shutdown", { method: "POST", body: "{}" }).catch(() => {
-        try { process.kill(previous.pid, "SIGTERM"); } catch { /* It already stopped. */ }
-      });
-      const deadline = Date.now() + 8000;
-      while (Date.now() < deadline) {
-        try {
-          process.kill(previous.pid, 0);
-          await wait(100);
-        } catch {
-          break;
-        }
-      }
-    }
-  }
-  const state = await ensureDaemon();
+  const previous = await inspectDaemon();
+  const state = await ensureDaemon({ forceReplace: true });
   const health = await daemonRequest(state, "/internal/health");
-  return { ...health, url: BRIDGE_URL, stateFile: DAEMON_STATE_PATH, previousPid: previous?.pid || null };
+  return {
+    ...health,
+    packageVersion: PACKAGE_VERSION,
+    compatible: true,
+    url: BRIDGE_URL,
+    stateFile: DAEMON_STATE_PATH,
+    previousPid: previous?.health.pid || null,
+  };
 }

package/src/config.mjs

@@ -8,6 +8,26 @@ export const PACKAGE_JSON = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.
 export const PACKAGE_NAME = PACKAGE_JSON.name;
 export const PACKAGE_VERSION = PACKAGE_JSON.version;
 export const PROTOCOL_VERSION = 3;
+// The browser protocol changes only when the hosted editor and companion can no
+// longer communicate. Internal MCP-to-daemon actions evolve independently, so
+// advertise them explicitly instead of treating a matching browser protocol as
+// proof that two installed package versions are compatible.
+export const DAEMON_API_VERSION = 1;
+export const DAEMON_INTERNAL_ACTIONS = Object.freeze([
+  "batch",
+  "begin_edit_session",
+  "browser",
+  "end_edit_session",
+  "list_edit_sessions",
+  "list_editors",
+  "list_local_fonts",
+  "list_recent_operations",
+  "notify",
+  "prepare_font",
+  "prepare_media",
+  "select_editor",
+  "write_export",
+]);
 export const BRIDGE_HOST = "127.0.0.1";
 export const BRIDGE_PORT = Number(process.env.CAROUSELBOT_BRIDGE_PORT || process.env.SLIDE_STUDIO_BRIDGE_PORT) || 43117;
 export const BRIDGE_URL = `http://${BRIDGE_HOST}:${BRIDGE_PORT}`;

package/src/daemon.mjs

@@ -5,7 +5,8 @@ import { appendFile, mkdir, open, readFile, rename, stat, unlink, writeFile } fr
 import { basename, delimiter, extname } from "node:path";
 import {
   ALLOWED_ORIGINS, AUDIT_LOG_PATH, BRIDGE_HOST, BRIDGE_PORT, BRIDGE_URL, DAEMON_LOCK_PATH,
-  DAEMON_STATE_PATH, PACKAGE_NAME, PACKAGE_VERSION, PROTOCOL_VERSION, STATE_DIRECTORY,
+  DAEMON_API_VERSION, DAEMON_INTERNAL_ACTIONS, DAEMON_STATE_PATH, PACKAGE_NAME, PACKAGE_VERSION,
+  PROTOCOL_VERSION, STATE_DIRECTORY,
 } from "./config.mjs";
 import { createLocalFontService } from "./local-fonts.mjs";
 
@@ -78,6 +79,19 @@ function codedError(code, message, details = {}) {
   return error;
 }
 
+function daemonHealth(details = {}) {
+  return {
+    ok: true,
+    service: PACKAGE_NAME,
+    pid: process.pid,
+    version: PACKAGE_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    daemonApiVersion: DAEMON_API_VERSION,
+    capabilities: { internalActions: [...DAEMON_INTERNAL_ACTIONS] },
+    ...details,
+  };
+}
+
 function publicSession(session) {
   return {
     id: session.id,
@@ -546,7 +560,10 @@ async function handleInternalCall(body) {
     for (const item of body.items) results.push(await callBrowser(body.clientId, item.toolName || "apply_operations", item.operation, item.label, { editSessionId: body.editSessionId, mutating: true }));
     return { applied: results.length, results };
   }
-  throw new Error(`Unknown internal action: ${body.action}`);
+  throw codedError("UNSUPPORTED_INTERNAL_ACTION", `Unknown internal action: ${body.action}`, {
+    action: body.action,
+    supportedActions: [...DAEMON_INTERNAL_ACTIONS],
+  });
 }
 
 const server = createServer(async (request, response) => {
@@ -564,13 +581,13 @@ const server = createServer(async (request, response) => {
   }
   if (url.pathname === "/health" && request.method === "GET") {
     if (origin && !cors) return sendJson(response, 403, { error: "Origin not allowed." });
-    return sendJson(response, 200, { ok: true, service: PACKAGE_NAME, version: PACKAGE_VERSION, protocolVersion: PROTOCOL_VERSION, editors: activeEditors().length, agents: activeClients().length }, cors || {});
+    return sendJson(response, 200, daemonHealth({ editors: activeEditors().length, agents: activeClients().length }), cors || {});
   }
 
   try {
     if (url.pathname.startsWith("/internal/")) {
       if (!requireInternal(request, response)) return;
-      if (url.pathname === "/internal/health" && request.method === "GET") return sendJson(response, 200, { ok: true, pid: process.pid, version: PACKAGE_VERSION, protocolVersion: PROTOCOL_VERSION });
+      if (url.pathname === "/internal/health" && request.method === "GET") return sendJson(response, 200, daemonHealth());
       if (url.pathname === "/internal/shutdown" && request.method === "POST") {
         sendJson(response, 202, { ok: true, pid: process.pid });
         setImmediate(() => void shutdown());
@@ -772,7 +789,11 @@ const server = createServer(async (request, response) => {
       : ["EACCES", "FONT_PERMISSION_REQUIRED"].includes(error.code)
         ? 403
         : error.code === "FONT_TRANSFER_LIMIT" ? 429 : 400;
-    return sendJson(response, statusCode, { error: error.message }, headers);
+    return sendJson(response, statusCode, {
+      error: error.message,
+      ...(error.code ? { code: error.code } : {}),
+      ...(error.details && Object.keys(error.details).length ? { details: error.details } : {}),
+    }, headers);
   }
 });
 
@@ -802,7 +823,14 @@ async function acquireDaemonLock() {
 
 async function writeDaemonState() {
   const temporary = `${DAEMON_STATE_PATH}.${process.pid}.tmp`;
-  await writeFile(temporary, JSON.stringify({ pid: process.pid, port: BRIDGE_PORT, secret: daemonSecret, version: PACKAGE_VERSION, protocolVersion: PROTOCOL_VERSION }), { mode: 0o600 });
+  await writeFile(temporary, JSON.stringify({
+    pid: process.pid,
+    port: BRIDGE_PORT,
+    secret: daemonSecret,
+    version: PACKAGE_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    daemonApiVersion: DAEMON_API_VERSION,
+  }), { mode: 0o600 });
   await rename(temporary, DAEMON_STATE_PATH);
 }
 

package/src/mcp-server.mjs

@@ -115,7 +115,7 @@ export async function createCarouselBotMcpServer(companion) {
   let guidanceRead = false;
   let identifiedAs = null;
   const server = new McpServer({ name: PACKAGE_NAME, version: PACKAGE_VERSION }, {
-    instructions: `First call list_editors and use the registered local browser tab. Never open or connect CarouselBot through a sandboxed agent browser. If no editor is listed, retry briefly because browser reconnection is automatic, then ask the user to open ${EDITOR_URL} in their normal browser and click Connect AI. Never restart a healthy companion for a transient editor disconnect; restart only for an explicit protocol mismatch or failed daemon health check. Before edits call get_design_guidance, then begin_edit_session; pass editSessionId to every edit and end it in cleanup. Parallel editing workers require distinct editor sessions. Use render_slide to inspect actual pixels.`,
+    instructions: `First call list_editors and use the registered local browser tab. Never open or connect CarouselBot through a sandboxed agent browser. If no editor is listed, retry briefly because browser reconnection is automatic, then ask the user to open ${EDITOR_URL} in their normal browser and click Connect AI. Companion compatibility and reconnects are automatic. Do not parallel-retry an action that reports an unsupported internal action; retry once after list_editors so automatic recovery can finish. Never restart a healthy companion for a transient editor disconnect. Before edits call get_design_guidance, then begin_edit_session; pass editSessionId to every edit and end it in cleanup. Parallel editing workers require distinct editor sessions. Use render_slide to inspect actual pixels.`,
     capabilities: { tools: {}, resources: {} },
   });
 

package/src/setup.mjs

@@ -1,9 +1,10 @@
 import { spawnSync } from "node:child_process";
 import { cp, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { EDITOR_URL, PACKAGE_NAME, PACKAGE_ROOT, PACKAGE_VERSION } from "./config.mjs";
+import { companionUpgrade } from "./companion.mjs";
 
 const supported = ["claude", "codex", "hermes", "opencode", "openclaw"];
 const serverName = "carouselbot";
@@ -43,13 +44,35 @@ function openCodeSnippet(specifier, version = commandVersion("opencode")) {
     : { mcp: { [serverName]: { ...server, enabled: true } } }, null, 2);
 }
 
-async function installSkill() {
-  const source = join(PACKAGE_ROOT, "skill", "carouselbot");
+export function setupSkillTargets(homeDirectory = homedir(), hermesHome = process.env.HERMES_HOME) {
   const targets = [
-    join(homedir(), ".agents", "skills", "carouselbot"),
-    join(homedir(), ".claude", "skills", "carouselbot"),
-    join(homedir(), ".hermes", "skills", "carouselbot"),
+    join(homeDirectory, ".agents", "skills", "carouselbot"),
+    join(homeDirectory, ".claude", "skills", "carouselbot"),
+    join(homeDirectory, ".hermes", "skills", "carouselbot"),
   ];
+  if (hermesHome?.trim()) targets.push(join(resolve(hermesHome.trim()), "skills", "carouselbot"));
+  return [...new Set(targets)];
+}
+
+export function clientSpawnOptions(client) {
+  if (client === "hermes") {
+    // Hermes tool discovery prompts even after the caller approved CarouselBot
+    // setup, and an existing entry adds an overwrite prompt first. Feed both
+    // approvals explicitly; EOF otherwise looks like a successful cancel.
+    return { input: "y\ny\n", stdio: ["pipe", "inherit", "inherit"] };
+  }
+  return { stdio: "inherit" };
+}
+
+function clientConfigurationPresent(client) {
+  if (client !== "hermes") return true;
+  const result = spawnSync("hermes", ["mcp", "list"], { encoding: "utf8" });
+  return result.status === 0 && /(?:^|\s)carouselbot(?:\s|$)/m.test(String(result.stdout || "") + String(result.stderr || ""));
+}
+
+async function installSkill() {
+  const source = join(PACKAGE_ROOT, "skill", "carouselbot");
+  const targets = setupSkillTargets();
   for (const target of targets) {
     await mkdir(target, { recursive: true });
     await cp(source, target, { recursive: true, force: true });
@@ -92,15 +115,23 @@ export async function runSetup(arguments_) {
   for (const client of clients) {
     const command = shellCommand(client, specifier);
     if (!command) continue;
-    for (const remove of removeCommands(client)) spawnSync(remove[0], remove.slice(1), { stdio: "ignore" });
-    const result = spawnSync(command[0], command.slice(1), { stdio: "inherit" });
-    if (result.status === 0) configured.push(client);
-    else process.stderr.write(`Could not configure ${client}; its command is printed above for manual setup.\n`);
+    if (client !== "hermes") {
+      for (const remove of removeCommands(client)) spawnSync(remove[0], remove.slice(1), { stdio: "ignore" });
+    }
+    const result = spawnSync(command[0], command.slice(1), clientSpawnOptions(client));
+    if (result.status === 0 && clientConfigurationPresent(client)) {
+      configured.push(client);
+      if (client === "hermes") {
+        const legacyRemove = removeCommands(client).find((remove) => remove.at(-1) === legacyServerName);
+        if (legacyRemove) spawnSync(legacyRemove[0], legacyRemove.slice(1), { input: "y\n", stdio: ["pipe", "ignore", "ignore"] });
+      }
+    } else process.stderr.write(`Could not verify ${client}'s CarouselBot config; the existing config was preserved and its command is printed above for manual setup.\n`);
   }
   const skillTargets = await installSkill();
-  process.stdout.write(`\nConfigured: ${configured.join(", ") || "none automatically"}\nSkill installed in:\n${skillTargets.map((value) => `  ${value}`).join("\n")}\n\nOpen ${EDITOR_URL} in your normal local browser and click Connect AI. Do not use a sandboxed agent browser.\n`);
+  const companion = await companionUpgrade();
+  process.stdout.write(`\nConfigured: ${configured.join(", ") || "none automatically"}\nSkill installed in:\n${skillTargets.map((value) => `  ${value}`).join("\n")}\nCompanion: ${companion.version} (${companion.upgraded ? "upgraded automatically" : "already current"})\n\nOpen ${EDITOR_URL} in your normal local browser and click Connect AI. Do not use a sandboxed agent browser.\n`);
   process.stdout.write(`First connection check (no browser automation): npx -y ${specifier} call list_editors\n`);
-  if (clients.includes("hermes")) process.stdout.write("Hermes can also refresh native tools in place with /reload-mcp and /reload-skills.\n");
+  if (clients.includes("hermes")) process.stdout.write("The companion and browser reconnect automatically. Hermes only needs /reload-mcp when adding entirely new native tool names to an already-running session; the CLI fallback remains available immediately.\n");
   if (clients.includes("claude")) process.stdout.write("Claude may require a new session for native MCP registration; use the CLI fallback immediately instead of stopping.\n");
   if (clients.includes("opencode")) process.stdout.write("OpenCode currently uses its JSON config; merge the snippet printed above into opencode.json.\n");
   return { clients, configured, skillTargets };