@lifeaitools/clauth 1.31.1 → 2.0.1

package/cli/supervisor-registry.js

@@ -7,7 +7,12 @@ import { spawnSync } from "node:child_process";
 const SCHEMA = "lifeai.plugin.v1";
 const DEFAULT_TIMEOUT_MS = 3000;
 const DEFAULT_SUPERVISOR_PORT = 52439;
-const DESTINATIONS = new Set(["local/clauth/pm2", "vultr/clauth/pm2", "coolify/clauth/docker"]);
+// local/clauth/daemon: for a surface that is not a separately-startable
+// process at all, but literally embedded in the clauth daemon itself (e.g.
+// fs-mcp) — distinct from local/clauth/pm2 (a separate local process clauth
+// manages via pm2) because there is nothing for a surface action to
+// start/stop/restart; the daemon's own lifecycle IS the surface's lifecycle.
+const DESTINATIONS = new Set(["local/clauth/pm2", "local/clauth/daemon", "vultr/clauth/pm2", "coolify/clauth/docker"]);
 const OWNERS = new Set(["clauth", "plugin", "external"]);
 const ACTIONS = new Set(["start", "stop", "restart", "reconcile", "test", "promote", "rollback"]);
 const DEFAULT_HEALTH_RECONCILE_INTERVAL_MS = 10000;
@@ -162,7 +167,26 @@ function normalizeCommand(command, field) {
   const [cmd, ...args] = command;
   if (typeof cmd !== "string" || !cmd.trim()) throw new Error(`${field}[0] is required`);
   if (/[;&|<>]/.test(cmd)) throw new Error(`${field}[0] must be an executable path/name, not shell syntax`);
-  return [cmd, ...args.map(String)];
+  const normalizedArgs = args.map(String);
+  // shell:true (Windows-only, see execute() in runSurfaceAction) hands each
+  // arg to cmd.exe verbatim — a shell metacharacter in an arg is exactly as
+  // exploitable as one in cmd[0]. A legitimate CLI arg for the pm2/node
+  // invocations this schema targets never needs raw shell syntax.
+  for (const [i, arg] of normalizedArgs.entries()) {
+    if (/[;&|<>]/.test(arg)) throw new Error(`${field}[${i + 1}] must not contain shell syntax`);
+  }
+  return [cmd, ...normalizedArgs];
+}
+
+// Quotes a value for cmd.exe /c when shell:true is active and the value
+// contains whitespace — spawnSync does NOT auto-quote in that mode, so an
+// absolute path like "C:\Program Files\nodejs\node.exe" (or any arg with a
+// space) breaks at the first space unless the caller quotes it. Idempotent:
+// an already-quoted value is left as-is rather than double-quoted.
+export function shellQuote(value, useShell) {
+  if (!useShell || !/\s/.test(value)) return value;
+  if (value.startsWith('"') && value.endsWith('"')) return value;
+  return `"${value}"`;
 }
 
 function expandPathToken(value) {
@@ -189,6 +213,13 @@ function normalizeDestination(destination) {
   return value;
 }
 
+// "Remote" means "not running on this box", read off the validated destination
+// enum. Expressed as NOT-local so a destination added to DESTINATIONS later is
+// treated as remote by default rather than silently escaping the port rule.
+function isRemoteDestination(destination) {
+  return !String(destination).startsWith("local/");
+}
+
 function normalizeDocumentation(value) {
   if (value == null) return null;
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("documentation must be an object");
@@ -224,8 +255,34 @@ function localhostHealth(pathOrUrl, port) {
 function normalizeSurface(surface, plugin) {
   if (!surface || typeof surface !== "object") throw new Error("surface must be an object");
   const id = String(surface.id || "").trim();
-  if (!/^[a-zA-Z0-9_.-]+$/.test(id)) throw new Error("surface.id may contain only letters, numbers, dot, underscore, and dash");
+  if (!/^[a-zA-Z0-9_.-]+$/.test(id) || /^\.+$/.test(id)) throw new Error("surface.id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots");
   const destination = normalizeDestination(surface.destination || plugin.destination);
+  // A remote surface names a service running somewhere else (Vultr/Coolify).
+  // It is reached by URL and its port is the deployment registry's fact, not
+  // the manifest's. A local surface is the opposite case and keeps its port on
+  // purpose: that port describes how the service runs on a developer box,
+  // which is intrinsic to the service and correctly lives in the product repo.
+  //
+  // Keyed on the VALIDATED destination enum, not on the surface's free-text
+  // id/role. Keying on the label `remote` was tried and is wrong twice over:
+  // it lets the drift back in under any other surface name, and it falsely
+  // rejects a genuinely local surface that happens to be named "remote". A
+  // ported non-local surface is also actively harmful, not just untidy —
+  // localhostHealth() below would synthesize http://127.0.0.1:<port>/health
+  // for it, pointing the health reconciler at the wrong box entirely.
+  if (isRemoteDestination(destination) && surface.port !== undefined && surface.port !== null) {
+    throw new Error(`a remote surface must not declare a port — destination ${destination} is not on this box, so its port is the deployment registry's fact, not the manifest's`);
+  }
+  // Same rule, second route to the same harm. Banning `port` alone closes only
+  // the narrower half: localhostHealth() below accepts an ABSOLUTE health URL
+  // and permits localhost hosts only, so any absolute health on a non-local
+  // destination is by construction pointed at the wrong box — the identical
+  // defect the port rule exists to prevent, arriving through a different field.
+  // A remote surface's health is reached by its public route, not by a
+  // loopback URL this box could dial.
+  if (isRemoteDestination(destination) && surface.health && /^https?:\/\//i.test(String(surface.health))) {
+    throw new Error(`a remote surface must not declare an absolute health URL — destination ${destination} is not on this box, so a localhost health URL would probe the wrong machine`);
+  }
   const lifecycle_owner = normalizeLifecycleOwner(surface.lifecycle_owner || plugin.lifecycle_owner);
   const port = surface.port === undefined || surface.port === null || surface.port === "auto" ? surface.port ?? null : Number(surface.port);
   if (port !== null && port !== "auto" && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error("surface.port must be auto or a TCP port");
@@ -249,7 +306,7 @@ export function validatePluginManifest(manifest, sourcePath = "") {
   if (!manifest || typeof manifest !== "object") throw new Error("manifest must be an object");
   if (manifest.schema !== SCHEMA) throw new Error(`schema must be ${SCHEMA}`);
   const id = String(manifest.id || "").trim();
-  if (!/^[a-zA-Z0-9_.-]+$/.test(id)) throw new Error("id may contain only letters, numbers, dot, underscore, and dash");
+  if (!/^[a-zA-Z0-9_.-]+$/.test(id) || /^\.+$/.test(id)) throw new Error("id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots");
   const version = String(manifest.version || "").trim();
   if (!version) throw new Error("version is required");
   const plugin = {
@@ -301,6 +358,17 @@ function findManifestFiles(root) {
   for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
     const full = path.join(root, entry.name);
     if (entry.isDirectory()) {
+      // A scoped npm package (@lifeaitools/fs-mcp) installs two levels deep
+      // under node_modules/@scope/pkg-name/ — descend one extra level only
+      // for @scope directories. Unscoped layout (one level) is unchanged.
+      if (entry.name.startsWith("@")) {
+        for (const scopedEntry of fs.readdirSync(full, { withFileTypes: true })) {
+          if (!scopedEntry.isDirectory()) continue;
+          const scopedCandidate = path.join(full, scopedEntry.name, "clauth-plugin.json");
+          if (fs.existsSync(scopedCandidate)) out.push(scopedCandidate);
+        }
+        continue;
+      }
       const candidate = path.join(full, "clauth-plugin.json");
       if (fs.existsSync(candidate)) out.push(candidate);
     } else if (entry.isFile() && entry.name === "clauth-plugin.json") {
@@ -365,6 +433,15 @@ export function discoverPlugins() {
           id,
           source,
           sourcePath: manifestPath,
+          // discovery_root must be recorded even on the quarantine path.
+          // deregisterPlugin() resolves its target via `prior?.sourcePath &&
+          // prior?.discovery_root`; omitting it here made that check false for
+          // every manifest_invalid row, so deregister fell back to the flat
+          // managed probe, missed the real directory, and returned a
+          // false-success "not_registered" while the plugin stayed on disk.
+          // A broken manifest is precisely what an operator reaches for
+          // deregister to remove, so this path must not be the weak one.
+          discovery_root: root,
           manifest_hash: hash,
           state: "manifest_invalid",
           enabled: false,
@@ -389,6 +466,314 @@ export function discoverPlugins() {
   return { plugins, surfaces, events };
 }
 
+// Registers one plugin manifest into the managed-plugins root, then runs
+// discovery so it's picked up immediately. This is the entry point a product
+// repo's own install/deploy step calls to self-register — the mechanism the
+// PLUGIN-ARCHITECTURE-DECISION.md "each MCP ships its own clauth-plugin.json"
+// model needs for a monorepo workspace member (no npm install lifecycle hook
+// to piggyback on, unlike a standalone published package with postinstall.js).
+// Idempotent: re-registering unchanged content is a safe no-op re-affirm.
+export function registerPlugin(manifestPath, actor = "localhost") {
+  let raw;
+  try {
+    raw = fs.readFileSync(manifestPath, "utf8");
+  } catch (error) {
+    return operation("plugin.register", { manifest_path: manifestPath }, null, {
+      ok: false, state: "manifest_unreadable", error: error instanceof Error ? error.message : String(error),
+    }, actor);
+  }
+  let manifest;
+  try {
+    manifest = validatePluginManifest(JSON.parse(raw), manifestPath);
+  } catch (error) {
+    return operation("plugin.register", { manifest_path: manifestPath }, null, {
+      ok: false, state: "manifest_invalid", error: error instanceof Error ? error.message : String(error),
+    }, actor);
+  }
+  const [{ root: managedRoot }] = rootEntries();
+  const resolvedRoot = path.resolve(managedRoot);
+  const targetDir = path.resolve(managedRoot, manifest.id);
+  // Belt-and-braces: the id regex already rejects traversal-shaped ids, but
+  // this asserts containment at the actual write site so a future regex
+  // relaxation can't silently reopen a path escape out of the managed root —
+  // this is a credential vault writing files from parsed manifest content.
+  if (targetDir !== resolvedRoot && !targetDir.startsWith(resolvedRoot + path.sep)) {
+    return operation("plugin.register", { manifest_path: manifestPath, plugin_id: manifest.id }, null, {
+      ok: false, state: "manifest_invalid", error: "plugin id escapes the managed plugin root",
+    }, actor);
+  }
+  const targetPath = path.join(targetDir, "clauth-plugin.json");
+  const priorRaw = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : null;
+  const unchanged = priorRaw !== null && sha256(priorRaw) === sha256(raw);
+  if (!unchanged) {
+    try {
+      fs.mkdirSync(targetDir, { recursive: true });
+      fs.writeFileSync(targetPath, raw, "utf8");
+    } catch (error) {
+      return operation("plugin.register", { manifest_path: manifestPath, plugin_id: manifest.id }, null, {
+        ok: false, state: "write_failed", error: error instanceof Error ? error.message : String(error),
+      }, actor);
+    }
+  }
+  const discovery = discoverPlugins();
+  const registered = discovery.plugins.find((plugin) => plugin.id === manifest.id);
+  return operation("plugin.register", { manifest_path: manifestPath, plugin_id: manifest.id }, null, {
+    ok: Boolean(registered) && registered.state !== "manifest_invalid",
+    state: unchanged ? "unchanged" : "registered",
+    plugin_state: registered?.state || "not_found",
+    surfaces: registered?.surfaces?.map((surface) => surface.id) || [],
+  }, actor);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// plugin sync — SWEEP, NOT A CATALOG.
+//
+// This reads the ORIGINAL clauth-plugin.json in each product repo and hands it
+// to registerPlugin. It deliberately stores NO inventory: no list of which
+// plugins exist, no copy of manifest content, no port assignments, no versions.
+// The table below is a list of PLACES TO LOOK, not a record of what is there —
+// every fact still comes from the product repo's own manifest, read fresh.
+//
+// That distinction is load-bearing. A central catalog of copied manifests
+// (lifeai-env's services/plugins/catalog.json + generate-catalog.mjs + its 7
+// generated manifests) was just retired precisely because a copy drifts from
+// the original and then two homes disagree about one fact. If a future cleanup
+// pass is tempted to "consolidate" this into a file that lists which plugins
+// exist, or to cache what was found, that rebuilds the thing that was deleted —
+// stop instead.
+// ─────────────────────────────────────────────────────────────────────────────
+const PRODUCT_REPO_MANIFESTS = [
+  { repo: "regen-root", manifest: "packages/codeflow/clauth-plugin.json" },
+  { repo: "regen-root", manifest: "apps/dev-center/clauth-plugin.json" },
+  { repo: "regen-root", manifest: "mcp-servers/regen-media/clauth-plugin.json" },
+  { repo: "regen-root", manifest: "mcp-servers/web-research/clauth-plugin.json" },
+  { repo: "rdc-skills", manifest: "clauth-plugin.json" },
+];
+
+// Sweep outcomes that mean "nothing was there to sync", as distinct from
+// "syncing it failed". Absence is expected on a partial checkout and must not
+// fail the sweep; a malformed manifest or a typo'd repo name must. Exported so
+// the CLI classifies receipts from the same list the audit receipt counts from.
+export const SYNC_SKIP_STATES = Object.freeze(["repo_root_missing", "manifest_missing", "repo_root_unknown"]);
+
+// The repo names syncPluginsFromRepos understands. Exported so a caller can
+// validate an override key up front rather than having a typo'd repo name
+// silently ignored and the sweep quietly read the default checkout instead.
+export const SYNC_REPO_NAMES = Object.freeze([...new Set(PRODUCT_REPO_MANIFESTS.map((entry) => entry.repo))]);
+
+// Mirrors expandPathToken()'s REGEN_ROOT resolution so a box that has already
+// pointed the manifest ${REGEN_ROOT} token somewhere resolves the sweep to the
+// same checkout rather than needing a second, differently-named env var.
+function defaultRepoRoot(repo) {
+  if (repo === "regen-root") return process.env.REGEN_ROOT || process.env.LIFEAI_REPO_ROOT || "C:/Dev/regen-root";
+  if (repo === "rdc-skills") return process.env.RDC_SKILLS_ROOT || "C:/Dev/rdc-skills";
+  return null;
+}
+
+/**
+ * Sweep the known product-repo manifest locations and register each one via the
+ * existing registerPlugin path (which owns validation, idempotence, and the
+ * managed-root containment assertion — none of it is re-implemented here).
+ *
+ * A missing repo root or a missing manifest WARNS AND CONTINUES. A box that has
+ * never checked out regen-root must still be able to sync whatever it does have,
+ * so absence is a reportable observation, never a thrown error.
+ *
+ * @param {Record<string,string>} [repoRoots] partial map of repo name -> root
+ *   path; any repo omitted falls back to its env/default root.
+ * @returns {Array<{repo:string,path:string,id:string|null,state:string,ok:boolean}>}
+ *   one receipt per ATTEMPTED manifest — this array is the return value, not a
+ *   persisted inventory.
+ */
+export function syncPluginsFromRepos(repoRoots = {}, actor = "localhost") {
+  const overrides = repoRoots && typeof repoRoots === "object" && !Array.isArray(repoRoots) ? repoRoots : {};
+  const receipts = [];
+  // An override key naming no known repo is a caller error, not a silent
+  // no-op: dropping it would sweep the DEFAULT checkout while reporting ✓ on
+  // every line, so the operator sees success from the wrong repo.
+  for (const key of Object.keys(overrides)) {
+    if (!SYNC_REPO_NAMES.includes(key)) {
+      receipts.push({ repo: key, path: null, id: null, state: "unknown_repo_name", ok: false, error: `unknown repo name — expected one of ${SYNC_REPO_NAMES.join(", ")}` });
+      appendSupervisorEvent({ kind: "plugin_sync_rejected", repo: key, manifest: null, reason: "unknown_repo_name" });
+    }
+  }
+
+  for (const { repo, manifest } of PRODUCT_REPO_MANIFESTS) {
+    const root = overrides[repo] || defaultRepoRoot(repo);
+    // Validate BEFORE path.resolve() — a non-string root makes path.resolve
+    // throw, which would abort the whole sweep and lose every later repo's
+    // receipt. This function's contract is that a bad or absent root is a
+    // reported observation, never a thrown error, and callers include HTTP.
+    if (typeof root !== "string" || !root.trim()) {
+      receipts.push({ repo, path: null, id: null, state: "repo_root_unknown", ok: false });
+      appendSupervisorEvent({ kind: "plugin_sync_skipped", repo, manifest, reason: "repo_root_unknown" });
+      continue;
+    }
+    const manifestPath = path.resolve(root, manifest);
+    if (!fs.existsSync(root)) {
+      receipts.push({ repo, path: manifestPath, id: null, state: "repo_root_missing", ok: false });
+      appendSupervisorEvent({ kind: "plugin_sync_skipped", repo, manifest: manifestPath, reason: "repo_root_missing" });
+      continue;
+    }
+    if (!fs.existsSync(manifestPath)) {
+      receipts.push({ repo, path: manifestPath, id: null, state: "manifest_missing", ok: false });
+      appendSupervisorEvent({ kind: "plugin_sync_skipped", repo, manifest: manifestPath, reason: "manifest_missing" });
+      continue;
+    }
+    let receipt;
+    try {
+      receipt = registerPlugin(manifestPath, actor);
+    } catch (error) {
+      // registerPlugin already returns receipts for the failure modes it knows
+      // about; this only catches an unforeseen throw so one bad manifest can
+      // never abort the rest of the sweep.
+      receipts.push({
+        repo,
+        path: manifestPath,
+        id: null,
+        state: "register_threw",
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      continue;
+    }
+    receipts.push({
+      repo,
+      path: manifestPath,
+      id: receipt.target?.plugin_id || null,
+      state: receipt.resulting_state?.state || "unknown",
+      ok: receipt.resulting_state?.ok === true,
+      operation_id: receipt.operationId,
+      error: receipt.resulting_state?.error || null,
+    });
+  }
+
+  // One audit receipt for the sweep itself (who swept, when, what happened).
+  // Counts only — deliberately not a stored list of what exists.
+  const isSkip = (entry) => SYNC_SKIP_STATES.includes(entry.state);
+  operation("plugin.sync", { repos: SYNC_REPO_NAMES }, null, {
+    ok: receipts.every((entry) => entry.ok || isSkip(entry)),
+    state: "sync_completed",
+    attempted: receipts.length,
+    registered: receipts.filter((entry) => entry.state === "registered").length,
+    unchanged: receipts.filter((entry) => entry.state === "unchanged").length,
+    skipped: receipts.filter(isSkip).length,
+    failed: receipts.filter((entry) => !entry.ok && !isSkip(entry)).length,
+  }, actor);
+
+  return receipts;
+}
+
+// Removes exactly one managed-plugin directory by id, then re-runs discovery so
+// the removal is reflected immediately. The inverse of registerPlugin — an id
+// reaching this function is attacker-influenced input (a CLI arg or an HTTP
+// field, with no manifest validation upstream to lean on) and this deletes
+// recursively, so both guards below are load-bearing.
+export function deregisterPlugin(id, actor = "localhost", { dryRun = false } = {}) {
+  const pluginId = String(id ?? "").trim();
+  // Guard 1 — charset + all-dots, the same rule a manifest id must satisfy.
+  //
+  // This one is NOT redundant with the containment assert below, and the
+  // containment assert is NOT a safety net for relaxing it. Measured: because
+  // path.resolve() normalizes `..` away and Windows re-anchors drive-relative
+  // paths, `sub/../web-research`, `C:web-research` and `web-research::$DATA`
+  // all resolve back INSIDE the root and sail through containment. Only the
+  // charset rule stops them. Relaxing it to admit a separator, a colon or a
+  // drive letter reopens a real hole — the tests pin all three forms.
+  if (!/^[a-zA-Z0-9_.-]+$/.test(pluginId) || /^\.+$/.test(pluginId)) {
+    return operation("plugin.deregister", { plugin_id: pluginId }, null, {
+      ok: false, state: "invalid_plugin_id", error: "plugin id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots",
+    }, actor);
+  }
+  const roots = rootEntries();
+  const managedRoots = roots.filter((entry) => entry.source === "managed");
+  const prior = (loadSupervisorState().plugins || []).find((plugin) => plugin.id === pluginId) || null;
+
+  // Resolve the plugin's ACTUAL directory rather than assuming a flat
+  // <first-managed-root>/<id> layout. Three real layouts exist that assumption
+  // misses, and in every one of them a bare <root>/<id> probe finds nothing and
+  // would report a green "not_registered" while the plugin stays installed and
+  // ENABLED — the one receipt a removal verb must never get wrong:
+  //   1. a scoped npm package at <root>/@scope/pkg/ (findManifestFiles descends
+  //      one extra level for these; see the @scope arm above),
+  //   2. a plugin in the 2nd..Nth entry of a path-delimited
+  //      CLAUTH_MANAGED_PLUGIN_ROOTS,
+  //   3. a plugin in the USER root, which must be refused explicitly rather
+  //      than silently reported as absent.
+  // Discovery already records discovery_root + sourcePath per plugin, so the
+  // location comes from there when state knows the plugin.
+  let targetDir = null;
+  let containingRoot = null;
+  if (prior?.sourcePath && prior?.discovery_root) {
+    if (prior.source === "user") {
+      return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+        ok: false,
+        state: "not_managed",
+        error: "plugin is installed in a user plugin root; deregister only removes managed plugins",
+      }, actor);
+    }
+    targetDir = path.resolve(path.dirname(prior.sourcePath));
+    containingRoot = path.resolve(prior.discovery_root);
+  } else {
+    // State does not know this id (never discovered, or state was reset). Fall
+    // back to probing the flat layout in every managed root, not just the first.
+    for (const { root } of managedRoots) {
+      const candidate = path.resolve(root, pluginId);
+      if (fs.existsSync(candidate)) {
+        targetDir = candidate;
+        containingRoot = path.resolve(root);
+        break;
+      }
+    }
+  }
+
+  if (!targetDir || !containingRoot || !fs.existsSync(targetDir)) {
+    return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+      ok: true, state: "not_registered", plugin_state: "not_found", surfaces: [],
+    }, actor);
+  }
+
+  // Guard 2 — containment assert at the delete site, against the root that
+  // actually contains the plugin. Note the difference from registerPlugin:
+  // targetDir === containingRoot is a REJECT here, not an accept. This deletes
+  // a directory recursively, so a path resolving to the plugin root itself
+  // would take the entire root with it.
+  if (targetDir === containingRoot || !targetDir.startsWith(containingRoot + path.sep)) {
+    return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+      ok: false, state: "invalid_plugin_id", error: "resolved plugin directory escapes its plugin root",
+    }, actor);
+  }
+  if (!managedRoots.some((entry) => path.resolve(entry.root) === containingRoot)) {
+    return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+      ok: false, state: "not_managed", error: "resolved plugin directory is not inside a managed plugin root",
+    }, actor);
+  }
+  if (dryRun) {
+    return operation("plugin.deregister.dry_run", { plugin_id: pluginId }, prior, {
+      ok: true,
+      state: "would_deregister",
+      target_dir: targetDir,
+      plugin_state: prior?.state || "unknown",
+      surfaces: (prior?.surfaces || []).map((surface) => surface.id),
+    }, actor);
+  }
+  try {
+    fs.rmSync(targetDir, { recursive: true, force: true });
+  } catch (error) {
+    return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+      ok: false, state: "remove_failed", error: error instanceof Error ? error.message : String(error),
+    }, actor);
+  }
+  const discovery = discoverPlugins();
+  const after = discovery.plugins.find((plugin) => plugin.id === pluginId);
+  return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+    ok: true,
+    state: "deregistered",
+    plugin_state: after?.state || "not_found",
+    surfaces: (prior?.surfaces || []).map((surface) => surface.id),
+  }, actor);
+}
+
 export function listPlugins() {
   return loadSupervisorState().plugins || [];
 }
@@ -417,7 +802,7 @@ export function readSupervisorEvents(limit = 100) {
   });
 }
 
-function operation(action, target, prior, result, actor = "localhost") {
+export function operation(action, target, prior, result, actor = "localhost") {
   const receipt = {
     operationId: crypto.randomUUID(),
     actor,
@@ -517,10 +902,22 @@ export function runSurfaceAction(id, action, actor = "localhost") {
   }
   const execute = (selectedCommand) => {
     const [cmd, ...args] = selectedCommand;
-    return spawnSync(cmd, args, {
+    const useShell = process.platform === "win32";
+    // With shell:true on Windows, spawnSync hands cmd/args to cmd.exe /c
+    // verbatim and does NOT auto-quote — an absolute path or arg containing
+    // a space (e.g. "C:\Program Files\nodejs\node.exe") breaks at the first
+    // space unless quoted. Bare shim names (pm2, npm) never contain spaces,
+    // so this only ever affects absolute-path values, and only on Windows.
+    const resolvedCmd = shellQuote(cmd, useShell);
+    const resolvedArgs = args.map((arg) => shellQuote(arg, useShell));
+    return spawnSync(resolvedCmd, resolvedArgs, {
       cwd: surface.cwd || undefined,
       env: { ...process.env, CLAUTH_PM2_HOME: getClauthPm2Home(), PM2_HOME: getClauthPm2Home() },
       windowsHide: true,
+      // Windows resolves CLI shims (pm2, npm, etc.) to .cmd files that
+      // spawnSync cannot exec directly without a shell — ENOENT otherwise.
+      // POSIX targets (Vultr/Coolify) need no shell and keep prior behavior.
+      shell: useShell,
       encoding: "utf8",
       timeout: Number(surface.timeoutMs || 30000),
     });