@lifeaitools/clauth 1.30.23 → 1.30.25

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"));
@@ -486,7 +494,7 @@ const LOG_FILE = path.join(os.tmpdir(), "clauth-serve.log");
 const LIVE_PORT = 52437;
 const STAGED_PORT = 52438;
 const WRITE_TOKEN_BYTES = 32;
-const WRITE_TOKEN_TTL_MS = 30 * 60 * 1000;
+const WRITE_TOKEN_TTL_MS = 10 * 60 * 1000;
 
 function makeWriteToken() {
   return {
@@ -677,9 +685,6 @@ 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}
@@ -933,7 +938,7 @@ function dashboardHtml(port, whitelist, isStaged = false, initWriteToken = null)
   .supervisor-name{font-size:.82rem;color:#e2e8f0;font-weight:600;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
   .supervisor-row-actions{display:flex;gap:5px;flex-wrap:wrap;margin-top:7px}
   .supervisor-log{font-family:'Courier New',monospace;font-size:.7rem;color:#94a3b8;white-space:pre-wrap;word-break:break-word;max-height:280px;overflow:auto}
-  .supervisor-feedback{margin-top:8px;padding:9px 12px;border-radius:6px;font-family:'Courier New',monospace;font-size:.88rem;font-weight:600;color:#86efac;background:rgba(34,197,94,.12);border:1px solid rgba(74,222,128,.35);border-left:4px solid #4ade80;display:none}
+  .supervisor-feedback{margin-top:8px;padding:7px 9px;border-radius:6px;font-family:'Courier New',monospace;font-size:.72rem;color:#86efac;background:rgba(34,197,94,.08);border:1px solid rgba(74,222,128,.22);display:none}
   .supervisor-feedback.bad{color:#fecaca;background:rgba(248,113,113,.08);border-color:rgba(248,113,113,.25)}
 </style>
 </head>
@@ -954,24 +959,6 @@ 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">
@@ -1187,6 +1174,12 @@ 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>
@@ -1246,11 +1239,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",
@@ -1509,16 +1507,21 @@ async function loadSupervisorCockpit() {
   const status = document.getElementById("supervisor-status");
   if (status) status.textContent = "Loading supervisor state…";
   try {
-    const [health, surfaces, logs] = await Promise.all([
+    const [health, plugins, 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 || ""));
@@ -1531,13 +1534,21 @@ 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");
   return '<div class="supervisor-row"><div class="supervisor-row-top"><span class="supervisor-name">' + htmlEscape(surface.plugin_id + ":" + surface.id) + '</span>' + supervisorBadge(surface.lifecycle_owner || "unknown", ownerKind) + supervisorBadge(surface.state || surface.status || "unknown", stateKind) + '</div>' +
     '<div class="supervisor-meta">' + htmlEscape(surface.destination || "—") + ' · port ' + htmlEscape(surface.port || "—") + '</div>' +
     '<div class="supervisor-meta">' + htmlEscape(surface.health || surface.health_url || "no health") + '</div>' +
-    '<div class="supervisor-row-actions">' + '<button class="supervisor-action" data-supervisor-action="enable" onclick="toggleSurfaceEnabled(' + jsArg(surface.plugin_id) + ',' + (surface.enabled === false ? 'true' : 'false') + ',this)">' + (surface.enabled === false ? "enable" : "disable") + '</button>' + ["start","stop","restart","reconcile","test","promote","rollback"].map(a => '<button class="supervisor-action" data-supervisor-action="' + a + '" onclick="runSupervisorSurface(' + jsArg(surface.plugin_id + ":" + surface.id) + ',' + jsArg(a) + ',this)">' + a + '</button>').join("") + '</div></div>';
+    '<div class="supervisor-row-actions">' + ["start","stop","restart","reconcile","test","promote","rollback"].map(a => '<button class="supervisor-action" data-supervisor-action="' + a + '" onclick="runSupervisorSurface(' + jsArg(surface.id) + ',' + jsArg(a) + ')">' + a + '</button>').join("") + '</div></div>';
 }
 
 async function rescanSupervisorPlugins() {
@@ -1548,37 +1559,21 @@ async function rescanSupervisorPlugins() {
   } catch (err) { supervisorFeedback("Plugin rescan failed: " + (err.message || err), true); }
 }
 
-async function runSupervisorSurface(id, action, btn) {
-  const originalLabel = btn ? btn.textContent : null;
-  if (btn) { btn.disabled = true; btn.textContent = "..."; btn.style.opacity = "0.6"; }
-  supervisorFeedback(action + " " + id + ": sending...", false);
+async function runSupervisorPlugin(id, action) {
   try {
-    const receipt = await supervisorJson("/v1/surfaces/" + encodeURIComponent(id) + "/actions", { method: "POST", headers: writeHeaders({ "Content-Type": "application/json" }), body: JSON.stringify({ action }) });
-    const result = receipt.resulting_state || {};
-    const ok = result.ok !== false;
-    if (btn) { btn.textContent = ok ? "done" : "failed"; btn.style.background = ok ? "#14532d" : "#7f1d1d"; }
-    supervisorFeedback(id + " " + action + " " + (ok ? "succeeded" : "failed") + " -> " + (result.state || result.reason || "completed"), !ok);
-    await new Promise((resolve) => setTimeout(resolve, 700));
+    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) {
-    if (btn) { btn.textContent = "failed"; btn.style.background = "#7f1d1d"; }
-    supervisorFeedback(id + " " + action + " failed: " + (err.message || err), true);
-    if (btn) { setTimeout(() => { btn.disabled = false; btn.textContent = originalLabel; btn.style.opacity = ""; btn.style.background = ""; }, 2500); }
-  }
+  } catch (err) { supervisorFeedback("Plugin " + action + " failed: " + (err.message || err), true); }
 }
 
-async function toggleSurfaceEnabled(pluginId, enable, btn) {
-  const originalLabel = btn ? btn.textContent : null;
-  if (btn) { btn.disabled = true; btn.textContent = "..."; btn.style.opacity = "0.6"; }
+async function runSupervisorSurface(id, action) {
   try {
-    const receipt = await supervisorJson("/v1/plugins/" + encodeURIComponent(pluginId) + "/" + (enable ? "enable" : "disable"), { method: "POST", headers: writeHeaders() });
-    supervisorFeedback(pluginId + " " + (enable ? "enabled" : "disabled"), receipt.error ? true : false);
-    await new Promise((resolve) => setTimeout(resolve, 500));
+    const receipt = await supervisorJson("/v1/surfaces/" + encodeURIComponent(id) + "/actions", { method: "POST", headers: writeHeaders({ "Content-Type": "application/json" }), body: JSON.stringify({ action }) });
+    const result = receipt.resulting_state || {};
+    supervisorFeedback("Surface " + action + " receipt " + (receipt.operationId || "recorded") + " · " + (result.state || "completed"), result.ok === false);
     await loadSupervisorCockpit();
-  } catch (err) {
-    supervisorFeedback(pluginId + " " + (enable ? "enable" : "disable") + " failed: " + (err.message || err), true);
-    if (btn) { setTimeout(() => { btn.disabled = false; btn.textContent = originalLabel; btn.style.opacity = ""; }, 2000); }
-  }
+  } catch (err) { supervisorFeedback("Surface " + action + " failed: " + (err.message || err), true); }
 }
 
 // ── Unlock ──────────────────────────────────
@@ -1659,60 +1654,24 @@ async function lockVault() {
   showLockScreen(r.hard_locked || false);
 }
 
-// -- Unlock writes (re-establish write scope without locking) --
+// ── 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 (30-min TTL).
-//
-// Uses an in-page modal rather than window.prompt()/confirm()/alert(): those
-// native dialogs silently no-op in embedded/webview browser contexts (VS Code
-// Simple Browser, WebView2, Electron wrappers) and after a real browser
-// suppresses repeated dialogs for a tab ("prevent this page from creating
-// additional dialogs") -- both cases fail with zero visible feedback.
-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..."; }
+// 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;
   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) {
-      if (input) { input.className = "lock-input error"; setTimeout(() => input.className = "lock-input", 600); }
-      if (err) err.textContent = "Invalid: " + (r.error || "Invalid password");
-      return;
-    }
+    if (r.error) { alert("Unlock failed: " + r.error); return; }
     writeToken = r.write_token || null;
     refreshWriteLockUi();
-    closeWriteUnlockModal();
-  } catch (e) {
-    if (err) err.textContent = "Unlock error: " + (e.message || e);
-  } finally {
-    if (btn) { btn.disabled = false; btn.textContent = "Unlock Writes"; }
-  }
+    alert(writeToken ? "Writes unlocked for 10 minutes." : "Unlock did not return a write token.");
+  } catch (e) { alert("Unlock error: " + (e.message || e)); }
 }
 
 // Reflect write-lock state on the button so it is obvious when a save will fail.
@@ -4081,6 +4040,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;
@@ -4677,7 +4800,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") {
@@ -11397,6 +11617,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([
@@ -11404,6 +11659,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) {
@@ -11437,6 +11695,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 };
 
@@ -11447,6 +11723,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