@lifeaitools/clauth 1.31.1 → 2.0.0

package/cli/commands/watchdog.js

@@ -131,7 +131,7 @@ export async function runWatchdog(action, opts = {}) {
       console.log("Usage: clauth watchdog restart <service-id>");
       return;
     }
-    const result = restartWatchdogService(serviceId);
+    const result = await restartWatchdogService(serviceId);
     console.log(JSON.stringify(result, null, 2));
     return;
   }

package/cli/index.js

@@ -149,7 +149,10 @@ program
 import { runInstall } from './commands/install.js';
 import { runUninstall } from './commands/uninstall.js';
 import { runScrub } from './commands/scrub.js';
-import { runServe } from './commands/serve.js';
+import { runServe, MCP_TOOLS } from './commands/serve.js';
+import { listPlugins, registerPlugin } from './supervisor-registry.js';
+import { runOps } from './commands/ops.js';
+import { runOpsInstall } from './commands/ops-install.js';
 import { runCodevelop } from './commands/codevelop.js';
 import { runNpm, runPublish } from './commands/npm.js';
 import { runLogin } from './commands/login.js';
@@ -960,6 +963,77 @@ tunnelCmd
     }
   });
 
+// ──────────────────────────────────────────────
+// clauth mcp list
+// ──────────────────────────────────────────────
+// Known MCP-server plugin ids in the managed fleet. Positive allowlist
+// rather than a naming heuristic (credential-name conventions and health
+// route "kind" vary across these) — dev-center and any future non-MCP
+// pm2-managed surface stay excluded by construction. Deliberately distinct
+// from `clauth list` (vault credential services); this never touches those.
+const MCP_SERVER_PLUGIN_IDS = new Set([
+  "fs-mcp",
+  "web-research",
+  "regen-media",
+  "regen-media-local",
+  "codeflow-mcp",
+  "rdc-skills",
+]);
+
+const mcpCmd = program.command("mcp").description("Inspect clauth's own MCP tool catalog and managed MCP-server surfaces");
+
+mcpCmd
+  .command("list")
+  .description("List clauth's advertised MCP tools and MCP-server surfaces (never vault credential services)")
+  .action(() => {
+    console.log(chalk.cyan(`\n  clauth's own MCP tools (${MCP_TOOLS.length}):\n`));
+    for (const tool of MCP_TOOLS) {
+      console.log(`  ${chalk.white(tool.name)}  ${chalk.gray(tool.description || "")}`);
+    }
+    const mcpPlugins = listPlugins().filter((p) => MCP_SERVER_PLUGIN_IDS.has(p.id));
+    console.log(chalk.cyan(`\n  Managed MCP-server surfaces (${mcpPlugins.length}):\n`));
+    if (!mcpPlugins.length) {
+      console.log(chalk.gray("  none discovered — is the daemon running? clauth serve"));
+    }
+    for (const plugin of mcpPlugins) {
+      const state = plugin.enabled ? plugin.state : "disabled";
+      const icon = state === "current" ? "✓" : state === "disabled" ? "○" : "⚠";
+      console.log(`  ${icon} ${chalk.white(plugin.id)}  ${chalk.gray(state)}`);
+      for (const surface of plugin.surfaces || []) {
+        console.log(`      ${surface.id}  ${chalk.gray(surface.health || surface.routes?.[0]?.url || "no health route")}`);
+      }
+    }
+    console.log("");
+  });
+
+// ──────────────────────────────────────────────
+// clauth plugin register <manifest-path>
+// The self-registration entry point for PLUGIN-ARCHITECTURE-DECISION.md:
+// a product repo's own install/deploy step calls this after its
+// clauth-plugin.json is in place — same role as clauth's own
+// scripts/postinstall.js, for repos that have no npm-install lifecycle
+// hook of their own (monorepo workspace members, not standalone packages).
+// ──────────────────────────────────────────────
+const pluginCmd = program.command('plugin').description("Register and manage clauth-supervised plugin manifests");
+
+pluginCmd
+  .command('register <manifestPath>')
+  .description('Validate a clauth-plugin.json and register it with the local supervisor, then run discovery')
+  .action((manifestPath) => {
+    const resolved = path.resolve(process.cwd(), manifestPath);
+    const receipt = registerPlugin(resolved, 'cli');
+    const ok = receipt.resulting_state?.ok;
+    const state = receipt.resulting_state?.state;
+    if (!ok) {
+      const pluginState = receipt.resulting_state?.plugin_state;
+      const detail = receipt.resulting_state?.error || (pluginState ? `plugin_state=${pluginState}` : 'registration failed');
+      console.error(`  ✗ ${state}: ${detail}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`  ✓ ${chalk.white(receipt.target?.plugin_id || '?')} ${state} — surfaces: ${(receipt.resulting_state?.surfaces || []).join(', ') || 'none'}`);
+  });
+
 // ──────────────────────────────────────────────
 // clauth chitchat --session <id>
 // ──────────────────────────────────────────────
@@ -1079,4 +1153,22 @@ Examples:
     await runServe({ ...opts, action: resolvedAction });
   });
 
+program
+  .command("ops <action>")
+  .description("Call the bearer-authenticated PM2 and Coolify operations control plane")
+  .option("--endpoint <url>", "HTTPS control-plane endpoint (or CLAUTH_OPS_ENDPOINT)")
+  .option("--target <name>", "PM2 process name or id")
+  .option("--script <path>", "PM2 script path for start")
+  .option("--instances <n>", "PM2 scale target")
+  .option("--operation <name>", "PM2 operation for run")
+  .option("--args-json <json>", "JSON positional arguments for a raw pm2_* operation")
+  .option("--options-json <json>", "JSON PM2 options for a typed operation")
+  .option("--application <uuid>", "registered Coolify application UUID for promote")
+  .option("--ref <name>", "registered Git ref for deploy")
+  .option("--job <id>", "job id for status lookup")
+  .option("--config <path>", "server-side JSON policy for ops install")
+  .option("--dry-run", "validate and print ops install configuration without changing PM2")
+  .addHelpText("after", `\nActions: catalog | list | describe | run | deploy | promote | job | install\n\nInstall: clauth ops install --config /etc/clauth/ops-control-plane.json\nThe installer creates or updates a PM2-managed local control plane, then proves /health and the bearer gate without reading a token.\n\nThe bearer is retrieved only from local clauth service vultr-ops-api-token and is never printed.\n`)
+  .action(async (action, opts) => { if (action === "install") await runOpsInstall(opts); else await runOps(action, opts); });
+
 program.parse(process.argv);

package/cli/ops/coolify-adapter.js

@@ -0,0 +1,80 @@
+const TERMINAL = new Map([
+  ["finished", "succeeded"], ["success", "succeeded"], ["successful", "succeeded"],
+  ["failed", "failed"], ["error", "failed"], ["cancelled", "failed"],
+]);
+
+function required(value, name) {
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}
+
+export function normalizeCoolifyState(value) {
+  const raw = String(value || "unknown").toLowerCase();
+  return TERMINAL.get(raw) || (raw.includes("progress") || raw.includes("queue") || raw.includes("running") ? "running" : "unknown");
+}
+
+/**
+ * Extract the deployment UUID from a Coolify deploy response.
+ *
+ * Coolify's `/api/v1/deploy` does NOT return the UUID at the top level — it
+ * answers with a `deployments` ARRAY:
+ *
+ *   { "deployments": [ { "message": "...", "resource_uuid": "...",
+ *                        "deployment_uuid": "ha9xjqcldy7duf2diyjdc20p" } ] }
+ *
+ * Reading only `body.deployment_uuid` therefore yields undefined, the caller
+ * concludes the promotion never started, and the job is marked failed — while
+ * Coolify is in fact building. That happened on a real life.ai promote:
+ * deployment ha9xjqcldy7duf2diyjdc20p was created at the same second the job
+ * reported failure. A failed job invites a retry, so the bug turns one
+ * production deploy into several.
+ *
+ * Accepts the array shape first, then the flat shapes, so a future/simplified
+ * response still resolves.
+ */
+export function deploymentUuidFrom(body) {
+  if (!body || typeof body !== "object") return null;
+  const list = Array.isArray(body.deployments) ? body.deployments : [];
+  for (const entry of list) {
+    if (!entry || typeof entry !== "object") continue;
+    const nested = entry.deployment_uuid || entry.uuid || entry.id;
+    if (typeof nested === "string" && nested) return nested;
+  }
+  const flat = body.deployment_uuid || body.uuid || body.id;
+  return typeof flat === "string" && flat ? flat : null;
+}
+
+export function createCoolifyAdapter({ baseUrl, getToken, fetchImpl = globalThis.fetch } = {}) {
+  const api = String(required(baseUrl, "baseUrl")).replace(/\/$/, "");
+  if (typeof getToken !== "function") throw new Error("getToken is required");
+  async function request(path, options = {}) {
+    const token = await getToken();
+    if (!token) throw new Error("coolify credential unavailable");
+    const headers = new Headers(options.headers || {});
+    headers.set("Accept", "application/json");
+    headers.set("Authorization", `Bearer ${token}`);
+    const response = await fetchImpl(`${api}${path}`, {
+      ...options,
+      headers,
+    });
+    if (!response.ok) throw new Error(`Coolify HTTP ${response.status}`);
+    return response.json();
+  }
+  return {
+    inspect(applicationUuid) { return request(`/api/v1/applications/${encodeURIComponent(required(applicationUuid, "applicationUuid"))}`); },
+    async promote(applicationUuid, options = {}) {
+      const uuid = encodeURIComponent(required(applicationUuid, "applicationUuid"));
+      return request(`/api/v1/deploy?uuid=${uuid}&force=true`, options);
+    },
+    async deployment(deploymentUuid) { return request(`/api/v1/deployments/${encodeURIComponent(required(deploymentUuid, "deploymentUuid"))}`); },
+    async poll(deploymentUuid, { attempts = 30, delay = async () => {} } = {}) {
+      for (let attempt = 1; attempt <= attempts; attempt++) {
+        const deployment = await this.deployment(deploymentUuid);
+        const state = normalizeCoolifyState(deployment.status || deployment.state);
+        if (state === "succeeded" || state === "failed") return { state, deployment, attempts: attempt };
+        await delay(attempt);
+      }
+      return { state: "timed_out", deployment: null, attempts };
+    },
+  };
+}

package/cli/ops/deployment-adapter.js

@@ -0,0 +1,63 @@
+import { execFile as execFileCallback } from "node:child_process";
+
+function execFile(command, args, options) {
+  return new Promise((resolve, reject) => execFileCallback(command, args, { ...options, windowsHide: true }, (error, stdout, stderr) => {
+    if (error) return reject(new Error(`${command} ${args.join(" ")}: ${String(stderr || error.message).trim()}`));
+    resolve({ stdout: String(stdout || "").trim(), stderr: String(stderr || "").trim() });
+  }));
+}
+
+function requireString(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${name} is required`);
+  return value.trim();
+}
+
+function validateApplication(config) {
+  if (!config || typeof config !== "object") throw new Error("deployment_not_registered");
+  requireString(config.repo_path, "deployment.repo_path");
+  requireString(config.pm2_name, "deployment.pm2_name");
+  if (!Array.isArray(config.build) || !config.build.every((value) => typeof value === "string" && value)) throw new Error("deployment.build must be a non-empty argv array");
+  if (!Array.isArray(config.allowed_refs) || !config.allowed_refs.every((value) => typeof value === "string" && value)) throw new Error("deployment.allowed_refs must be a string array");
+  if (!requireString(config.health_url, "deployment.health_url").startsWith("http")) throw new Error("deployment.health_url must be HTTP(S)");
+}
+
+export function parseDeploymentRegistry(raw = "{}") {
+  const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("CLAUTH_OPS_DEPLOYMENTS must be a JSON object");
+  for (const config of Object.values(parsed)) validateApplication(config);
+  return parsed;
+}
+
+export function createDeploymentAdapter({ deployments, run = execFile, fetch = globalThis.fetch, delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), reload }) {
+  if (typeof reload !== "function") throw new Error("reload callback is required");
+  return {
+    async deploy({ application, ref }) {
+      const name = requireString(application, "application");
+      const config = deployments[name];
+      validateApplication(config);
+      const requestedRef = requireString(ref || config.default_ref, "ref");
+      if (!config.allowed_refs.includes(requestedRef)) throw new Error("deployment_ref_not_allowed");
+      const cwd = config.repo_path;
+      const steps = [];
+      await run("git", ["fetch", "origin", requestedRef], { cwd });
+      steps.push("fetched");
+      const sha = (await run("git", ["rev-parse", "FETCH_HEAD"], { cwd })).stdout;
+      if (!/^[0-9a-f]{7,64}$/i.test(sha)) throw new Error("deployment_invalid_git_sha");
+      await run("git", ["checkout", "--detach", sha], { cwd });
+      steps.push("checked_out");
+      await run(config.build[0], config.build.slice(1), { cwd });
+      steps.push("built");
+      await reload(config.pm2_name);
+      steps.push("reloaded");
+      const attempts = Number(config.health_attempts || 30);
+      for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+          const response = await fetch(config.health_url, { signal: AbortSignal.timeout(Number(config.health_timeout_ms || 5000)) });
+          if (response.ok) return { application: name, ref: requestedRef, sha, health_url: config.health_url, attempts: attempt, steps };
+        } catch {}
+        await delay(Number(config.health_delay_ms || 1000));
+      }
+      throw new Error("deployment_health_check_timed_out");
+    },
+  };
+}

package/cli/ops/job-store.js

@@ -0,0 +1,116 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const TERMINAL = new Set(["succeeded", "failed", "timed_out", "rejected"]);
+
+export function createJobStore({ now = () => new Date().toISOString(), maxJobs = 500, filePath = null } = {}) {
+  const { jobs, recovered } = load(filePath, maxJobs, now);
+  const subscribers = new Map();
+  const persist = () => {
+    if (!filePath) return;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ schema: "clauth.ops.jobs.v1", jobs: [...jobs.values()].map(snapshot) }), { mode: 0o600 });
+    fs.renameSync(tmp, filePath);
+  };
+  if (recovered) persist();
+  const publish = (id) => {
+    const value = get(id);
+    for (const listener of subscribers.get(id) || []) listener(value);
+  };
+  const create = ({ kind, operation, target = null }) => {
+    const id = crypto.randomUUID();
+    const job = { id, kind, operation, target, phase: "queued", created_at: now(), updated_at: now(), events: [] };
+    jobs.set(id, job);
+    event(id, "queued");
+    while (jobs.size > maxJobs) jobs.delete(jobs.keys().next().value);
+    persist();
+    return snapshot(job);
+  };
+  const event = (id, phase, detail = null) => {
+    const job = jobs.get(id);
+    if (!job) return null;
+    if (TERMINAL.has(job.phase)) throw new Error(`job already terminal: ${job.phase}`);
+    job.phase = phase;
+    job.updated_at = now();
+    job.events.push({ phase, at: job.updated_at, detail: detail == null ? null : sanitize(detail) });
+    persist();
+    publish(id);
+    return snapshot(job);
+  };
+  const get = (id) => jobs.has(id) ? snapshot(jobs.get(id)) : null;
+  const subscribe = (id, listener) => {
+    if (!jobs.has(id)) return null;
+    const listeners = subscribers.get(id) || new Set();
+    subscribers.set(id, listeners);
+    listeners.add(listener);
+    listener(get(id));
+    return () => {
+      listeners.delete(listener);
+      if (!listeners.size) subscribers.delete(id);
+    };
+  };
+  return { create, event, get, subscribe };
+}
+
+function load(filePath, maxJobs, now) {
+  if (!filePath || !fs.existsSync(filePath)) return { jobs: new Map(), recovered: false };
+  try {
+    const stored = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    const values = Array.isArray(stored?.jobs) ? stored.jobs.slice(-maxJobs) : [];
+    let recovered = false;
+    const restored = values.filter((job) => job && typeof job.id === "string").map((job) => {
+      const safe = snapshot(job);
+      if (!TERMINAL.has(safe.phase)) {
+        recovered = true;
+        safe.phase = "failed";
+        safe.updated_at = now();
+        safe.events.push({ phase: "failed", at: safe.updated_at, detail: { code: "daemon_restarted" } });
+      }
+      return [safe.id, safe];
+    });
+    return { jobs: new Map(restored), recovered };
+  } catch {
+    return { jobs: new Map(), recovered: false };
+  }
+}
+
+function sanitize(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  // `error` is deliberately NOT allowlisted. Free-form error strings are the
+  // classic credential-leak path -- an upstream message like
+  // `API_KEY=... rejected` would be persisted verbatim to disk and served over
+  // the API. ops-job-store.test.mjs pins this behaviour with an explicit
+  // API_KEY=hidden payload; do not "fix" a missing failure reason by adding
+  // `error` here.
+  //
+  // Producers that need a machine-readable failure reason must emit `code` with
+  // an enumerated value (see submitPromotionJob's coolify_* codes). That keeps
+  // diagnosis available without letting arbitrary upstream text through.
+  const allowed = new Set(["code", "checkout_sha", "ref", "pm2_name", "health_url", "health_status", "deployment_uuid", "status", "processes"]);
+  return Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => {
+    if (!allowed.has(key)) return [];
+    if (key === "processes" && Array.isArray(entry)) {
+      return [[key, entry.filter((process) => process && typeof process === "object").map((process) => ({
+        name: typeof process.name === "string" ? process.name : null,
+        pm_id: typeof process.pm_id === "number" ? process.pm_id : null,
+        pid: typeof process.pid === "number" ? process.pid : null,
+        status: typeof process.status === "string" ? process.status : null,
+        namespace: typeof process.namespace === "string" ? process.namespace : null,
+      }))]];
+    }
+    return (typeof entry === "string" || typeof entry === "number" || typeof entry === "boolean" || entry === null) ? [[key, entry]] : [];
+  }));
+}
+
+function snapshot(job) {
+  return JSON.parse(JSON.stringify({
+    ...job,
+    events: job.events.map((event) => ({
+      phase: event.phase,
+      at: event.at,
+      detail: sanitize(event.detail),
+    })),
+  }));
+}

package/cli/ops/operation-policy.js

@@ -0,0 +1,51 @@
+import { PM2_OPERATION_CATALOG, isReadOperation } from "./pm2-adapter.js";
+
+function configuredProfile(config, role) {
+  if (config?.[role] && typeof config[role] === "object" && !Array.isArray(config[role])) return config[role];
+  return config && typeof config === "object" && !Array.isArray(config) ? config : {};
+}
+
+function targetFrom(input = {}) {
+  const value = input.target || input.name || input.options?.name || (Array.isArray(input.args) ? input.args[0] : null);
+  return value == null ? null : String(value);
+}
+
+function enabled(enabled, operation) {
+  return enabled.has(operation) || enabled.has("*");
+}
+
+export function createOperationPolicy({ enabled: agentEnabled = [], applications = {}, adminEnabled = [], adminApplications = {}, allowHostWide = false } = {}) {
+  const agentEnabledSet = new Set(agentEnabled);
+  const adminEnabledSet = new Set(adminEnabled);
+  return {
+    authorize(operation, input = {}, role = "agent") {
+      if (!PM2_OPERATION_CATALOG[operation]) return { ok: false, code: "service_not_available" };
+      const isAdmin = role === "admin";
+      const profile = configuredProfile(isAdmin ? adminApplications : applications, role);
+      const allowed = Array.isArray(profile[operation])
+        ? profile[operation].filter((target) => typeof target === "string" && target.length > 0)
+        : [];
+      const target = targetFrom(input);
+      const hostWide = operation === "kill_daemon" || operation === "pm2_killDaemon" || target === "all";
+
+      // The public catalog remains complete. Only the remote admin capability
+      // may execute raw PM2 calls or host-level lifecycle actions, and every
+      // one still has to be enabled and allowlisted in Vultr configuration.
+      if (!isAdmin && (operation.startsWith("pm2_") || ["start", "dump", "resurrect", "kill_daemon", "startup", "unstartup", "update", "deep_update"].includes(operation))) {
+        return { ok: false, code: "service_not_available" };
+      }
+      if (hostWide && (!isAdmin || !allowHostWide)) return { ok: false, code: "service_not_available" };
+      if (!isReadOperation(operation) && !enabled(isAdmin ? adminEnabledSet : agentEnabledSet, operation)) {
+        return { ok: false, code: "service_not_available" };
+      }
+      if (!allowed.length) return { ok: false, code: "service_not_available" };
+      if (hostWide) {
+        if (!allowed.includes("*") && !allowed.includes("all")) return { ok: false, code: "service_not_available" };
+        return { ok: true, mode: isReadOperation(operation) ? "read" : "mutate", allowed_targets: allowed };
+      }
+      if (operation === "list" || operation === "ping") return { ok: true, mode: isReadOperation(operation) ? "read" : "mutate", allowed_targets: allowed };
+      if (!target || (!allowed.includes("*") && !allowed.includes(target))) return { ok: false, code: "service_not_available" };
+      return { ok: true, mode: isReadOperation(operation) ? "read" : "mutate", allowed_targets: allowed };
+    },
+  };
+}

package/cli/ops/pm2-adapter.js

@@ -0,0 +1,128 @@
+const READ_OPERATIONS = new Set(["list", "describe", "ping", "logs", "bus", "pm2_list", "pm2_describe", "pm2_ping", "pm2_get", "pm2_getPID", "pm2_getVersion", "pm2_inspect", "pm2_jlist", "pm2_slist", "pm2_monitorState"]);
+
+// Derived from PM2 v7's public API prototype. We intentionally expose every
+// method through a stable prefixed operation name; potentially destructive or
+// interactive methods stay policy-disabled unless an operator explicitly opts in.
+export const PM2_PUBLIC_METHODS = Object.freeze([
+  "agentInfos", "attach", "autodump", "autoinstall", "backward", "boilerplate", "clearDump", "clearSetup", "close", "conf", "connect", "dashboard", "deepUpdate", "delete", "deleteModule", "deploy", "describe", "destroy", "disconnect", "dockerMode", "dump", "env", "exitCli", "flush", "forward", "generateDockerfile", "generateModuleSample", "generateSample", "get", "getPID", "getProcessIdByName", "getVersion", "inspect", "install", "jlist", "kill", "killAgent", "killDaemon", "launchAll", "launchBus", "launchModules", "launchSysMonitoring", "link", "linkManagement", "list", "logrotate", "minimumSetup", "monit", "monitorState", "msgProcess", "multiset", "openDashboard", "package", "ping", "printLogs", "profile", "publish", "pullAndReload", "pullAndRestart", "pullCommitId", "reload", "reloadLogs", "remote", "remoteV2", "report", "reset", "restart", "resurrect", "scale", "sendDataToProcessId", "sendLineToStdin", "sendSignalToProcessId", "sendSignalToProcessName", "serve", "set", "slist", "speedList", "start", "startup", "stop", "streamLogs", "trigger", "uninstall", "uninstallStartup", "unlink", "unset", "update",
+]);
+
+const CORE_OPERATIONS = {
+  list: { mode: "read", args: [] },
+  describe: { mode: "read", args: ["target"] },
+  ping: { mode: "read", args: [] },
+  logs: { mode: "read", args: ["target"] },
+  bus: { mode: "read", args: [] },
+  start: { mode: "mutate", args: ["script", "options"] },
+  stop: { mode: "mutate", args: ["target"] },
+  restart: { mode: "mutate", args: ["target", "options"] },
+  reload: { mode: "mutate", args: ["target", "options"] },
+  delete: { mode: "mutate", args: ["target"] },
+  scale: { mode: "mutate", args: ["target", "instances"] },
+  reset: { mode: "mutate", args: ["target"] },
+  dump: { mode: "mutate", args: [] },
+  resurrect: { mode: "mutate", args: [] },
+  kill_daemon: { mode: "mutate", args: [] },
+  startup: { mode: "mutate", args: ["platform", "options"] },
+  unstartup: { mode: "mutate", args: ["platform"] },
+  update: { mode: "mutate", args: [] },
+  deep_update: { mode: "mutate", args: [] },
+  send_data: { mode: "mutate", args: ["target", "packet"] },
+  send_signal: { mode: "mutate", args: ["target", "signal"] },
+  trigger: { mode: "mutate", args: ["target", "action", "params"] },
+};
+
+export const PM2_OPERATION_CATALOG = Object.freeze({
+  ...CORE_OPERATIONS,
+  ...Object.fromEntries(PM2_PUBLIC_METHODS.map((method) => [`pm2_${method}`, {
+    mode: READ_OPERATIONS.has(`pm2_${method}`) ? "read" : "mutate",
+    args: ["args"],
+    pm2_method: method,
+  }])),
+});
+
+function missing(value, name) {
+  if (value === undefined || value === null || value === "") throw new Error(`${name} is required`);
+  return value;
+}
+
+function callbackCall(pm2, method, args = []) {
+  return new Promise((resolve, reject) => {
+    if (typeof pm2?.[method] !== "function") return reject(new Error(`PM2 method unavailable: ${method}`));
+    pm2[method](...args, (error, result) => error ? reject(error) : resolve(result));
+  });
+}
+
+function normalizeProcess(process) {
+  if (!process || typeof process !== "object") return process;
+  return {
+    name: process.name || process.pm2_env?.name || null,
+    pm_id: process.pm_id ?? process.pm2_env?.pm_id ?? null,
+    pid: process.pid ?? null,
+    status: process.pm2_env?.status ?? process.status ?? null,
+    restart_time: process.pm2_env?.restart_time ?? null,
+    created_at: process.pm2_env?.created_at ?? null,
+    cwd: process.pm2_env?.pm_cwd ?? null,
+    script: process.pm2_env?.pm_exec_path ?? null,
+    namespace: process.pm2_env?.namespace ?? null,
+  };
+}
+
+function normalizeProcessResult(result) {
+  // PM2's lower-level aliases (jlist, inspect, get) can return the same rich
+  // process object as list/describe. Normalize it at the adapter boundary so a
+  // future caller cannot accidentally serialize pm2_env or other credentials.
+  if (Array.isArray(result)) {
+    return result.map((item) => item && typeof item === "object" && (item.pm2_env || "pm_id" in item || "pid" in item)
+      ? normalizeProcess(item)
+      : item);
+  }
+  if (result && typeof result === "object" && (result.pm2_env || "pm_id" in result || "pid" in result)) return normalizeProcess(result);
+  return result;
+}
+
+export function createPm2Adapter(pm2) {
+  if (!pm2) throw new Error("pm2 facade is required");
+  return {
+    catalog() { return PM2_OPERATION_CATALOG; },
+    async connect() { await callbackCall(pm2, "connect", [false]); return { connected: true }; },
+    async disconnect() { await callbackCall(pm2, "disconnect"); return { connected: false }; },
+    async execute(operation, input = {}) {
+      if (!PM2_OPERATION_CATALOG[operation]) throw new Error(`unknown PM2 operation: ${operation}`);
+      if (operation.startsWith("pm2_")) {
+        const method = PM2_OPERATION_CATALOG[operation].pm2_method;
+        const args = Array.isArray(input.args) ? input.args : [];
+        return normalizeProcessResult(await callbackCall(pm2, method, args));
+      }
+      switch (operation) {
+        case "list": return (await callbackCall(pm2, "list")).map(normalizeProcess);
+        case "describe": return (await callbackCall(pm2, "describe", [missing(input.target, "target")])).map(normalizeProcess);
+        case "ping": return { connected: true, processes: (await callbackCall(pm2, "list")).length };
+        case "logs": return (await callbackCall(pm2, "describe", [missing(input.target, "target")])).map(normalizeProcess);
+        case "bus": return callbackCall(pm2, "launchBus");
+        case "start": return callbackCall(pm2, "start", [missing(input.script, "script"), input.options || {}]);
+        case "stop": return callbackCall(pm2, "stop", [missing(input.target, "target")]);
+        case "restart": return callbackCall(pm2, "restart", [missing(input.target, "target"), input.options || {}]);
+        case "reload": return callbackCall(pm2, "reload", [missing(input.target, "target"), input.options || {}]);
+        case "delete": return callbackCall(pm2, "delete", [missing(input.target, "target")]);
+        case "scale": return callbackCall(pm2, "scale", [missing(input.target, "target"), missing(input.instances, "instances")]);
+        case "reset": return callbackCall(pm2, "reset", [missing(input.target, "target")]);
+        case "dump": return callbackCall(pm2, "dump");
+        case "resurrect": return callbackCall(pm2, "resurrect");
+        case "kill_daemon": return callbackCall(pm2, "killDaemon");
+        case "startup": return callbackCall(pm2, "startup", [input.platform, input.options || {}]);
+        case "unstartup": return callbackCall(pm2, "uninstallStartup", [input.platform]);
+        case "update": return callbackCall(pm2, "update");
+        case "deep_update": return callbackCall(pm2, "deepUpdate");
+        case "send_data": return callbackCall(pm2, "sendDataToProcessId", [missing(input.target, "target"), missing(input.packet, "packet")]);
+        case "send_signal": return callbackCall(pm2, "sendSignalToProcessName", [missing(input.target, "target"), input.signal || "SIGINT"]);
+        case "trigger": return callbackCall(pm2, "trigger", [missing(input.target, "target"), missing(input.action, "action"), input.params || {}]);
+        default: throw new Error(`unimplemented PM2 operation: ${operation}`);
+      }
+    },
+  };
+}
+
+export function isReadOperation(operation) {
+  return READ_OPERATIONS.has(operation);
+}

package/cli/ops/serialized-executor.js

@@ -0,0 +1,9 @@
+export function createSerializedExecutor() {
+  let tail = Promise.resolve();
+  return function execute(task) {
+    if (typeof task !== "function") throw new Error("task must be a function");
+    const run = tail.then(task, task);
+    tail = run.catch(() => {});
+    return run;
+  };
+}