@lifeaitools/clauth 1.30.24 → 1.30.26

package/cli/commands/serve.js

@@ -58,6 +58,14 @@ import {
   DEFAULT_BOOTSTRAP,
 } from "./agent-pool.js";
 import { AgentCron, cronEnabled, nextRun } from "./agent-cron.js";
+import pm2 from "pm2";
+import { createPm2Adapter, PM2_OPERATION_CATALOG } from "../ops/pm2-adapter.js";
+import { createOperationPolicy } from "../ops/operation-policy.js";
+import { createJobStore } from "../ops/job-store.js";
+import { createCoolifyAdapter, deploymentUuidFrom } from "../ops/coolify-adapter.js";
+import { createDeploymentAdapter, parseDeploymentRegistry } from "../ops/deployment-adapter.js";
+import { createSerializedExecutor } from "../ops/serialized-executor.js";
+import { requestOps } from "./ops.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"), "utf8"));
@@ -677,6 +685,9 @@ function dashboardHtml(port, whitelist, isStaged = false, initWriteToken = null)
   .btn-unlock:hover{background:#2563eb}
   .btn-unlock:disabled{background:#1e3a5f;color:#4a6fa5;cursor:not-allowed}
   .lock-err{color:#f87171;font-size:.82rem;margin-top:.75rem;min-height:1.2em}
+  #write-unlock-overlay{display:none;position:fixed;inset:0;background:rgba(2,6,23,.72);z-index:9999;align-items:center;justify-content:center;padding:2rem}
+  .write-unlock-cancel{width:100%;background:transparent;color:#94a3b8;border:1px solid #334155;border-radius:8px;padding:8px;font-size:.85rem;cursor:pointer;margin-top:.6rem;transition:border-color .15s}
+  .write-unlock-cancel:hover{border-color:#64748b;color:#cbd5e1}
   /* ── Main view ── */
   #main-view{display:none;padding:2rem}
   .header{display:flex;align-items:center;gap:10px;margin-bottom:1.5rem;flex-wrap:wrap}
@@ -951,6 +962,24 @@ function dashboardHtml(port, whitelist, isStaged = false, initWriteToken = null)
   </div>
 </div>
 
+<!-- Write-unlock modal (replaces window.prompt(), which silently no-ops in
+     embedded/webview browser contexts and after a browser suppresses repeated
+     native dialogs) -->
+<div id="write-unlock-overlay">
+  <div class="lock-card">
+    <div class="lock-icon">🔒</div>
+    <div class="lock-title">Enable writes</div>
+    <div class="lock-sub">Enter your vault password to enable saving changes (30-minute write session)</div>
+    <form onsubmit="submitWriteUnlock();return false;" autocomplete="on">
+      <input type="text" name="username" value="clauth" autocomplete="username" style="display:none">
+      <input class="lock-input" id="write-unlock-input" type="password" placeholder="••••••••••••" autocomplete="current-password">
+      <button class="btn-unlock" id="write-unlock-btn" type="submit">Unlock Writes</button>
+    </form>
+    <div class="lock-err" id="write-unlock-err"></div>
+    <button type="button" class="write-unlock-cancel" onclick="closeWriteUnlockModal()">Cancel</button>
+  </div>
+</div>
+
 <!-- ── Main view (shown after unlock) ──────── -->
 <div id="main-view">
   <div id="upgrade-banner" style="display:none" class="upgrade-banner">
@@ -1166,12 +1195,6 @@ function dashboardHtml(port, whitelist, isStaged = false, initWriteToken = null)
     <div id="supervisor-status" class="supervisor-sub">Loading supervisor state…</div>
     <div id="supervisor-feedback" class="supervisor-feedback" role="status"></div>
     <div class="supervisor-grid" style="margin-top:10px">
-      <div class="supervisor-card">
-        <h4>Plugins</h4>
-        <div class="supervisor-kpi" id="supervisor-plugin-count">—</div>
-        <div class="supervisor-meta" id="supervisor-plugin-meta">awaiting data</div>
-        <div class="supervisor-list" id="supervisor-plugins" style="margin-top:8px"></div>
-      </div>
       <div class="supervisor-card">
         <h4>Surfaces</h4>
         <div class="supervisor-kpi" id="supervisor-surface-count">—</div>
@@ -1231,11 +1254,16 @@ function dashboardHtml(port, whitelist, isStaged = false, initWriteToken = null)
     <span id="service-search-count" class="service-search-count"></span>
   </div>
   <div id="grid" class="grid"><p class="loading">Loading services…</p></div>
-  <div class="footer">localhost:${port} · 127.0.0.1 only · 10-strike lockout</div>
+  <div class="footer" id="originFooter">checking origin… · 10-strike lockout</div>
 </div>
 
 <script>
-const BASE = "http://127.0.0.1:${port}";
+const BASE = location.origin;
+(function reportOrigin() {
+  const isLocal = /^(127\\.0\\.0\\.1|localhost|\\[::1\\])$/.test(location.hostname);
+  const el = document.getElementById("originFooter");
+  if (el) el.textContent = (isLocal ? "LOCAL" : "REMOTE") + " · " + BASE + " · 10-strike lockout";
+})();
 
 const SERVICE_HINTS = {
   "neo4j":           "neo4j+s://username:password@instance.databases.neo4j.io",
@@ -1494,21 +1522,16 @@ async function loadSupervisorCockpit() {
   const status = document.getElementById("supervisor-status");
   if (status) status.textContent = "Loading supervisor state…";
   try {
-    const [health, plugins, surfaces, logs] = await Promise.all([
+    const [health, surfaces, logs] = await Promise.all([
       supervisorJson("/health"),
-      supervisorJson("/v1/plugins"),
       supervisorJson("/v1/surfaces"),
       supervisorJson("/v1/logs?limit=40"),
     ]);
-    const pluginRows = plugins.plugins || [];
     const surfaceRows = surfaces.surfaces || [];
-    document.getElementById("supervisor-plugin-count").textContent = String(pluginRows.length);
     document.getElementById("supervisor-surface-count").textContent = String(surfaceRows.length);
     document.getElementById("supervisor-operation-count").textContent = String((logs.operations || []).length);
-    document.getElementById("supervisor-plugin-meta").textContent = "current " + (pluginRows.filter(p => p.state === "current").length) + " · awaiting " + (pluginRows.filter(p => p.state === "awaiting_enable").length);
     document.getElementById("supervisor-surface-meta").textContent = "pm2 home: " + (health.pm2_home || "—");
     document.getElementById("supervisor-log-path").textContent = logs.log_path || "events.jsonl";
-    document.getElementById("supervisor-plugins").innerHTML = pluginRows.length ? pluginRows.map(renderSupervisorPlugin).join("") : '<div class="supervisor-sub">No plugins discovered.</div>';
     document.getElementById("supervisor-surfaces").innerHTML = surfaceRows.length ? surfaceRows.map(renderSupervisorSurface).join("") : '<div class="supervisor-sub">No surfaces declared.</div>';
     document.getElementById("supervisor-events").textContent = (logs.events || []).slice(-20).reverse().map(e => {
       const label = e.kind === "operation" ? (e.action + " " + JSON.stringify(e.target || {})) : (e.kind + " " + (e.plugin_id || ""));
@@ -1521,14 +1544,6 @@ async function loadSupervisorCockpit() {
   }
 }
 
-function renderSupervisorPlugin(plugin) {
-  const stateKind = plugin.state === "current" ? "ok" : (plugin.state === "manifest_invalid" || plugin.state === "missing" ? "bad" : "warn");
-  return '<div class="supervisor-row"><div class="supervisor-row-top"><span class="supervisor-name">' + htmlEscape(plugin.id) + '</span>' + supervisorBadge(plugin.state || "unknown", stateKind) + '</div>' +
-    '<div class="supervisor-meta">' + htmlEscape(plugin.publisher || "unknown") + ' · ' + htmlEscape(plugin.version || "—") + ' · ' + htmlEscape(plugin.source || "—") + '</div>' +
-    '<div class="supervisor-meta">' + htmlEscape((plugin.manifest_hash || "").slice(0, 12)) + '</div>' +
-    '<div class="supervisor-row-actions"><button class="supervisor-action" onclick="runSupervisorPlugin(' + jsArg(plugin.id) + ',' + jsArg(plugin.enabled ? "disable" : "enable") + ')">' + (plugin.enabled ? "Disable" : "Enable") + '</button><button class="supervisor-action" onclick="runSupervisorPlugin(' + jsArg(plugin.id) + ',' + jsArg("test") + ')">Test</button><button class="supervisor-action" onclick="runSupervisorPlugin(' + jsArg(plugin.id) + ',' + jsArg("promote") + ')">Promote</button></div></div>';
-}
-
 function renderSupervisorSurface(surface) {
   const ownerKind = surface.lifecycle_owner === "clauth" ? "ok" : (surface.lifecycle_owner === "plugin" ? "warn" : "");
   const stateKind = surface.state === "current" || surface.status === "healthy" ? "ok" : (surface.state === "unavailable" ? "bad" : "warn");
@@ -1546,14 +1561,6 @@ async function rescanSupervisorPlugins() {
   } catch (err) { supervisorFeedback("Plugin rescan failed: " + (err.message || err), true); }
 }
 
-async function runSupervisorPlugin(id, action) {
-  try {
-    const receipt = await supervisorJson("/v1/plugins/" + encodeURIComponent(id) + "/" + encodeURIComponent(action), { method: "POST", headers: writeHeaders() });
-    supervisorFeedback("Plugin " + action + " receipt " + (receipt.operationId || "recorded") + " · " + ((receipt.resulting_state && receipt.resulting_state.state) || "completed"), false);
-    await loadSupervisorCockpit();
-  } catch (err) { supervisorFeedback("Plugin " + action + " failed: " + (err.message || err), true); }
-}
-
 async function runSupervisorSurface(id, action) {
   try {
     const receipt = await supervisorJson("/v1/surfaces/" + encodeURIComponent(id) + "/actions", { method: "POST", headers: writeHeaders({ "Content-Type": "application/json" }), body: JSON.stringify({ action }) });
@@ -1644,21 +1651,51 @@ async function lockVault() {
 // ── Unlock writes (re-establish write scope without locking) ──
 // Needed when the daemon auto-unlocks via --pw/boot.key: the page never sees the
 // unlock screen, so it holds no write token. POST /auth mints one (10-min TTL).
-async function unlockWrites() {
-  if (writeToken && !confirm("Writes are already unlocked this session. Re-unlock?")) return;
-  const pw = prompt("Enter your vault password to enable saving changes (10-minute write session):");
-  if (!pw) return;
+function unlockWrites() {
+  openWriteUnlockModal();
+}
+
+function openWriteUnlockModal() {
+  const overlay = document.getElementById("write-unlock-overlay");
+  const input = document.getElementById("write-unlock-input");
+  const err = document.getElementById("write-unlock-err");
+  if (err) err.textContent = "";
+  if (input) { input.value = ""; input.className = "lock-input"; }
+  if (overlay) overlay.style.display = "flex";
+  if (input) setTimeout(() => input.focus(), 50);
+}
+
+function closeWriteUnlockModal() {
+  const overlay = document.getElementById("write-unlock-overlay");
+  if (overlay) overlay.style.display = "none";
+}
+
+async function submitWriteUnlock() {
+  const input = document.getElementById("write-unlock-input");
+  const btn = document.getElementById("write-unlock-btn");
+  const err = document.getElementById("write-unlock-err");
+  const pw = input ? input.value : "";
+  if (!pw) { if (err) err.textContent = "Password is required."; return; }
+  if (btn) { btn.disabled = true; btn.textContent = "Verifying..."; }
   try {
     const r = await fetch(BASE + "/auth", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ password: pw }),
     }).then(r => r.json());
-    if (r.error) { alert("Unlock failed: " + r.error); return; }
+    if (r.error) {
+      if (input) { input.className = "lock-input error"; setTimeout(() => input.className = "lock-input", 600); }
+      if (err) err.textContent = "Invalid: " + (r.error || "Invalid password");
+      return;
+    }
     writeToken = r.write_token || null;
     refreshWriteLockUi();
-    alert(writeToken ? "Writes unlocked for 10 minutes." : "Unlock did not return a write token.");
-  } catch (e) { alert("Unlock error: " + (e.message || e)); }
+    closeWriteUnlockModal();
+  } catch (e) {
+    if (err) err.textContent = "Unlock error: " + (e.message || e);
+  } finally {
+    if (btn) { btn.disabled = false; btn.textContent = "Unlock Writes"; }
+  }
 }
 
 // Reflect write-lock state on the button so it is obvious when a save will fail.
@@ -4027,6 +4064,170 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
   });
   const isSupervisorPort = port === getSupervisorPort();
   const supervisorTestNoToken = process.env.CLAUTH_SUPERVISOR_TEST_NO_TOKEN === "1";
+  const opsAdapter = createPm2Adapter(pm2);
+  const executePm2 = createSerializedExecutor();
+  const opsPolicy = createOperationPolicy({
+    enabled: String(process.env.CLAUTH_OPS_ENABLED || "").split(",").map((item) => item.trim()).filter(Boolean),
+    applications: (() => { try { return JSON.parse(process.env.CLAUTH_OPS_APPLICATIONS || "{}"); } catch { return {}; } })(),
+    adminEnabled: String(process.env.CLAUTH_OPS_ADMIN_ENABLED || "").split(",").map((item) => item.trim()).filter(Boolean),
+    adminApplications: (() => { try { return JSON.parse(process.env.CLAUTH_OPS_ADMIN_APPLICATIONS || "{}"); } catch { return {}; } })(),
+    allowHostWide: process.env.CLAUTH_OPS_ALLOW_HOST_WIDE === "1",
+  });
+  const opsJobs = createJobStore({
+    filePath: process.env.CLAUTH_OPS_JOB_STORE_PATH || path.join(getSupervisorDir(), "ops-jobs.json"),
+  });
+
+  async function getLoopbackSecret(service) {
+    const response = await fetch(`http://127.0.0.1:${LIVE_PORT}/v/${encodeURIComponent(service)}`, { signal: AbortSignal.timeout(5000) });
+    if (!response.ok) throw new Error(`${service} unavailable from local clauth`);
+    const value = (await response.text()).trim();
+    if (!value) throw new Error(`${service} is empty`);
+    return value;
+  }
+  const coolify = createCoolifyAdapter({
+    baseUrl: process.env.CLAUTH_COOLIFY_BASE_URL || "https://deploy.regendevcorp.com",
+    getToken: () => getLoopbackSecret("coolify-api"),
+  });
+  const deployments = (() => { try { return parseDeploymentRegistry(process.env.CLAUTH_OPS_DEPLOYMENTS || "{}"); } catch { return {}; } })();
+  const deploymentAdapter = createDeploymentAdapter({
+    deployments,
+    reload: async (target) => {
+      await executePm2(async () => {
+        await opsAdapter.connect();
+        try { await opsAdapter.execute("reload", { target, options: { updateEnv: true } }); } finally { await opsAdapter.disconnect(); }
+      });
+    },
+  });
+
+  /**
+   * Record an ops failure's upstream message to the LOCAL log only.
+   *
+   * job-store's sanitizer deliberately drops free-form `error` text so an
+   * upstream message cannot carry a credential into the persisted job file or
+   * the API response. That protection left every failure with an empty detail,
+   * so jobs reported `failed` with no reason at all. Jobs now carry an
+   * enumerated `code`; the underlying message goes here, to the same
+   * operator-only log as the rest of the daemon's diagnostics.
+   */
+  function logOpsFailure(kind, operation, error) {
+    const message = String(error?.message || error || "unknown");
+    try {
+      fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [OPS ${kind}/${operation}] ${message}\n`);
+    } catch {}
+  }
+
+  async function opsBearerRole(req) {
+    const header = req.headers.authorization;
+    const supplied = Array.isArray(header) ? header[0] : header;
+    if (!supplied || !String(supplied).startsWith("Bearer ")) return null;
+    const actual = String(supplied).slice(7).trim();
+    let admin; let agent;
+    try { admin = await getLoopbackSecret(process.env.CLAUTH_OPS_ADMIN_TOKEN_SERVICE || "vultr-ops-admin-token"); } catch {}
+    try { agent = await getLoopbackSecret(process.env.CLAUTH_OPS_AGENT_TOKEN_SERVICE || "vultr-ops-api-token"); } catch {}
+    if (admin && agent && admin === agent) return null;
+    for (const [role, expected] of [["admin", admin], ["agent", agent]]) {
+      if (!expected) continue;
+      const a = Buffer.from(actual); const b = Buffer.from(expected);
+      if (a.length === b.length && crypto.timingSafeEqual(a, b)) return role;
+    }
+    return null;
+  }
+
+  async function requireOpsBearer(req, res) {
+    const role = await opsBearerRole(req);
+    if (role) { req._opsRole = role; return true; }
+    res.writeHead(401, { "Content-Type": "application/json", ...CORS });
+    res.end(JSON.stringify({ error: "ops_bearer_required" }));
+    return false;
+  }
+
+  function submitOpsJob(operation, input, role = "agent") {
+    const authorization = opsPolicy.authorize(operation, input, role);
+    const job = opsJobs.create({ kind: "pm2", operation, target: input.target || input.name || null });
+    if (!authorization.ok) {
+      return opsJobs.event(job.id, "rejected", { code: authorization.code });
+    }
+    void (async () => {
+      opsJobs.event(job.id, "running");
+      try {
+        const result = await executePm2(async () => {
+          await opsAdapter.connect();
+          try { return await opsAdapter.execute(operation, input); } finally { await opsAdapter.disconnect(); }
+        });
+        opsJobs.event(job.id, "succeeded", operationReceipt(operation, result, authorization.allowed_targets || []));
+      } catch (error) {
+        // `error` alone is dropped by job-store's sanitizer (it refuses
+        // free-form upstream text so a credential cannot ride along), which
+        // left every failure with an empty detail. Emit an enumerated code so
+        // the failure has a reason; keep the message for the local log only.
+        logOpsFailure("pm2", operation, error);
+        opsJobs.event(job.id, "failed", { code: "pm2_operation_failed" });
+      }
+    })();
+    return opsJobs.get(job.id);
+  }
+
+  function operationReceipt(operation, result, allowedTargets) {
+    if (["list", "describe", "logs"].includes(operation)) {
+      const processes = Array.isArray(result)
+        ? result.filter((process) => allowedTargets.includes("*") || allowedTargets.includes(process?.name))
+        : [];
+      return { processes };
+    }
+    if (operation === "ping") return { status: "connected" };
+    return { status: "completed" };
+  }
+
+  function submitPromotionJob(applicationUuid) {
+    const job = opsJobs.create({ kind: "coolify", operation: "promote", target: applicationUuid });
+    const enabled = String(process.env.CLAUTH_OPS_ENABLED || "").split(",").map((item) => item.trim()).includes("coolify_promote");
+    const allowlist = (() => { try { return JSON.parse(process.env.CLAUTH_COOLIFY_PROMOTE_UUIDS || "[]"); } catch { return []; } })();
+    if (!enabled || !Array.isArray(allowlist) || !allowlist.includes(applicationUuid)) {
+      return opsJobs.event(job.id, "rejected", { code: "service_not_available" });
+    }
+    void (async () => {
+      opsJobs.event(job.id, "running");
+      try {
+        const deployment = await coolify.promote(applicationUuid);
+        // Coolify answers with a `deployments` ARRAY, not a flat object — see
+        // deploymentUuidFrom. Reading the flat field alone marked the job failed
+        // while the deployment was actually running.
+        const deploymentUuid = deploymentUuidFrom(deployment);
+        if (!deploymentUuid) {
+          // The deploy request itself SUCCEEDED (no throw); only the UUID was
+          // unreadable, so the deployment may well be RUNNING. The code says so
+          // explicitly rather than a bare "failed", because a plain failure
+          // invites a retry and a duplicate production deploy.
+          //
+          // An enumerated code, not a free-form error: job-store's sanitizer
+          // drops `error` on purpose to keep upstream text (and any credential
+          // inside it) out of the persisted job.
+          return opsJobs.event(job.id, "failed", { code: "coolify_deploy_accepted_uuid_unreadable" });
+        }
+        opsJobs.event(job.id, "waiting", { deployment_uuid: deploymentUuid });
+        const terminal = await coolify.poll(deploymentUuid, { attempts: Number(process.env.CLAUTH_COOLIFY_POLL_ATTEMPTS || 60), delay: () => new Promise((resolve) => setTimeout(resolve, 5000)) });
+        opsJobs.event(job.id, terminal.state === "succeeded" ? "succeeded" : terminal.state, { deployment_uuid: deploymentUuid, status: terminal.deployment?.status || null });
+      } catch (error) {
+        // The throw may have happened AFTER Coolify accepted the deploy (e.g.
+        // the poll lost the network), so this is not proof nothing shipped.
+        logOpsFailure("coolify", "promote", error);
+        opsJobs.event(job.id, "failed", { code: "coolify_promote_failed" });
+      }
+    })();
+    return opsJobs.get(job.id);
+  }
+
+  function submitDeploymentJob(application, ref) {
+    const job = opsJobs.create({ kind: "deployment", operation: "deploy", target: application });
+    const enabled = String(process.env.CLAUTH_OPS_ENABLED || "").split(",").map((item) => item.trim()).includes("deploy");
+    if (!enabled || !deployments[application]) return opsJobs.event(job.id, "rejected", { code: "service_not_available" });
+    void (async () => {
+      opsJobs.event(job.id, "running");
+      try { opsJobs.event(job.id, "building"); opsJobs.event(job.id, "succeeded", { result: await deploymentAdapter.deploy({ application, ref }) }); }
+      catch (error) { logOpsFailure("deployment", "deploy", error); opsJobs.event(job.id, "failed", { code: "deployment_failed" }); }
+    })();
+    return opsJobs.get(job.id);
+  }
 
   function hasSupervisorWrite(req) {
     if (validateWriteToken(req, writeSession)) return true;
@@ -4623,7 +4824,104 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
     }
 
     if (method === "GET" && reqPath === "/health") {
-      return ok(res, { ...supervisorHealth(), vault_locked: !password, clauth_version: VERSION });
+      return ok(res, { ...supervisorHealth(), listening_port: port, process_id: process.pid, vault_locked: !password, clauth_version: VERSION });
+    }
+
+    // Bearer-gated remote operations surface. It remains loopback-only at this
+    // layer; ingress/tunnel policy decides whether it is reachable remotely.
+    if (method === "GET" && reqPath === "/v1/ops/catalog") {
+      if (!await requireOpsBearer(req, res)) return;
+      return ok(res, { schema: "clauth.ops.v1", operations: PM2_OPERATION_CATALOG });
+    }
+
+    if (method === "GET" && reqPath === "/v1/ops/processes") {
+      if (!await requireOpsBearer(req, res)) return;
+      const job = submitOpsJob("list", {}, req._opsRole);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    const opsProcessMatch = reqPath.match(/^\/v1\/ops\/processes\/([^/]+)$/);
+    if (method === "GET" && opsProcessMatch) {
+      if (!await requireOpsBearer(req, res)) return;
+      const job = submitOpsJob("describe", { target: decodeURIComponent(opsProcessMatch[1]) }, req._opsRole);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    if (method === "POST" && reqPath === "/v1/ops/operations") {
+      if (!await requireOpsBearer(req, res)) return;
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "invalid_json" }));
+      }
+      const operation = String(body?.operation || "");
+      if (!PM2_OPERATION_CATALOG[operation]) {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "unknown_operation" }));
+      }
+      const job = submitOpsJob(operation, body?.input && typeof body.input === "object" ? body.input : {}, req._opsRole);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    if (method === "POST" && reqPath === "/v1/ops/promotions") {
+      if (!await requireOpsBearer(req, res)) return;
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "invalid_json" }));
+      }
+      const applicationUuid = String(body?.application_uuid || "").trim();
+      if (!applicationUuid) {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "application_uuid_required" }));
+      }
+      const job = submitPromotionJob(applicationUuid);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    if (method === "POST" && reqPath === "/v1/ops/deployments") {
+      if (!await requireOpsBearer(req, res)) return;
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "invalid_json" }));
+      }
+      const application = String(body?.application || "").trim();
+      if (!application) {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "application_required" }));
+      }
+      const job = submitDeploymentJob(application, body?.ref ? String(body.ref) : undefined);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    const opsJobMatch = reqPath.match(/^\/v1\/ops\/jobs\/([^/]+)$/);
+    if (method === "GET" && opsJobMatch) {
+      if (!await requireOpsBearer(req, res)) return;
+      const job = opsJobs.get(decodeURIComponent(opsJobMatch[1]));
+      res.writeHead(job ? 200 : 404, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job || { error: "job_not_found" }));
+    }
+
+    const opsJobEventsMatch = reqPath.match(/^\/v1\/ops\/jobs\/([^/]+)\/events$/);
+    if (method === "GET" && opsJobEventsMatch) {
+      if (!await requireOpsBearer(req, res)) return;
+      const jobId = decodeURIComponent(opsJobEventsMatch[1]);
+      if (!opsJobs.get(jobId)) {
+        res.writeHead(404, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "job_not_found" }));
+      }
+      res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive", ...CORS });
+      const unsubscribe = opsJobs.subscribe(jobId, (job) => {
+        if (!res.writableEnded) res.write(`event: job\ndata: ${JSON.stringify(job)}\n\n`);
+      });
+      req.on("close", unsubscribe);
+      return;
     }
 
     if (method === "GET" && reqPath === "/v1/plugins") {
@@ -11343,6 +11641,41 @@ const MCP_TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "clauth_ops_catalog",
+    description: "Return the Vultr deployment-control API catalog. Availability is still decided on Vultr.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_processes",
+    description: "Submit a scoped PM2 process-status query to the Vultr control plane. Only server-approved applications are returned.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_describe",
+    description: "Submit a scoped PM2 status query for one server-approved application.",
+    inputSchema: { type: "object", properties: { application: { type: "string" } }, required: ["application"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_deploy",
+    description: "Submit one manifest-scoped development deployment to Vultr. The server chooses the repository, build, PM2 process, and allowed ref.",
+    inputSchema: { type: "object", properties: { application: { type: "string" }, ref: { type: "string" } }, required: ["application"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_promote",
+    description: "Submit one server-allowlisted Coolify promotion and return its asynchronous job receipt.",
+    inputSchema: { type: "object", properties: { application_uuid: { type: "string" } }, required: ["application_uuid"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_job",
+    description: "Read the terminal or in-progress receipt for a deployment-control job.",
+    inputSchema: { type: "object", properties: { job_id: { type: "string" } }, required: ["job_id"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_run",
+    description: "Submit one PM2 operation through the Vultr control plane. The remote agent/admin profile decides whether the operation and target are available.",
+    inputSchema: { type: "object", properties: { operation: { type: "string" }, input: { type: "object" } }, required: ["operation"], additionalProperties: false },
+  },
 ];
 
 const MCP_WRITE_TOOL_NAMES = new Set([
@@ -11350,6 +11683,9 @@ const MCP_WRITE_TOOL_NAMES = new Set([
   "clauth_disable",
   "clauth_set_project",
   "clauth_generate_token",
+  "clauth_ops_deploy",
+  "clauth_ops_promote",
+  "clauth_ops_run",
 ]);
 
 function filterMcpToolsForWriteMode(tools) {
@@ -11383,6 +11719,24 @@ function mcpError(text) {
   return { content: [{ type: "text", text }], isError: true };
 }
 
+async function callOpsFromMcp(vault, method, requestPath, body, { write = false } = {}) {
+  if (write && !vault.writeEnabled) return mcpError("MCP write tools are disabled by default. Launch clauth with CLAUTH_MCP_WRITE=1 for an explicit write-capable session.");
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+    const endpoint = process.env.CLAUTH_OPS_APPROVED_ORIGIN;
+    if (!endpoint) return mcpError("service_not_available");
+  try {
+    const url = new URL(endpoint);
+    if (url.protocol !== "https:") return mcpError("service_not_available");
+    const service = process.env.CLAUTH_OPS_TOKEN_SERVICE || "vultr-ops-api-token";
+    const credential = await vaultRetrieveValue(vault, service);
+    if (credential.error || !credential.value) return mcpError("service_not_available");
+    const payload = await requestOps({ endpoint: url.toString().replace(/\/$/, ""), token: String(credential.value), method, path: requestPath, body });
+    return mcpResult(JSON.stringify(payload, null, 2));
+  } catch {
+    return mcpError("service_not_available");
+  }
+}
+
 // Windows cmd.exe doesn't support single quotes — use bash for gws JSON args
 const GWS_EXEC_OPTS = { encoding: "utf8", timeout: 30000, windowsHide: true, shell: os.platform() === "win32" ? "bash" : undefined };
 
@@ -11393,6 +11747,13 @@ async function handleMcpTool(vault, name, args) {
   };
 
   switch (name) {
+    case "clauth_ops_catalog": return callOpsFromMcp(vault, "GET", "/v1/ops/catalog");
+    case "clauth_ops_processes": return callOpsFromMcp(vault, "GET", "/v1/ops/processes");
+    case "clauth_ops_describe": return callOpsFromMcp(vault, "GET", `/v1/ops/processes/${encodeURIComponent(args.application || "")}`);
+    case "clauth_ops_deploy": return callOpsFromMcp(vault, "POST", "/v1/ops/deployments", { application: args.application, ...(args.ref ? { ref: args.ref } : {}) }, { write: true });
+    case "clauth_ops_promote": return callOpsFromMcp(vault, "POST", "/v1/ops/promotions", { application_uuid: args.application_uuid }, { write: true });
+    case "clauth_ops_job": return callOpsFromMcp(vault, "GET", `/v1/ops/jobs/${encodeURIComponent(args.job_id || "")}`);
+    case "clauth_ops_run": return callOpsFromMcp(vault, "POST", "/v1/ops/operations", { operation: args.operation, input: args.input && typeof args.input === "object" ? args.input : {} }, { write: true });
     case "clauth_ping": {
       return mcpResult(
         vault.password

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

@@ -150,6 +150,8 @@ 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 { 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';
 
@@ -1050,4 +1052,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);