@lifeaitools/clauth 1.30.23 → 1.30.24

package/cli/supervisor-registry.js

@@ -1,589 +1,594 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-
-const SCHEMA = "lifeai.plugin.v1";
-const DEFAULT_TIMEOUT_MS = 3000;
-const DEFAULT_SUPERVISOR_PORT = 52439;
-const DESTINATIONS = new Set(["local/clauth/pm2", "vultr/clauth/pm2", "coolify/clauth/docker"]);
-const OWNERS = new Set(["clauth", "plugin", "external"]);
-const ACTIONS = new Set(["start", "stop", "restart", "reconcile", "test", "promote", "rollback"]);
-const DEFAULT_HEALTH_RECONCILE_INTERVAL_MS = 10000;
-const DEFAULT_HEALTH_TIMEOUT_MS = 2500;
-const HEALTH_RECONCILE_COOLDOWN_MS = 15000;
-const DOCUMENTATION_FIELDS = ["architecture", "operator_guide", "install", "runbook", "tool_reference", "release", "agent_context"];
-
-export function getSupervisorPort() {
-  return Number(process.env.CLAUTH_SUPERVISOR_PORT || DEFAULT_SUPERVISOR_PORT);
-}
-
-export function getSupervisorDir() {
-  if (process.env.CLAUTH_SUPERVISOR_DIR) return process.env.CLAUTH_SUPERVISOR_DIR;
-  const appdata = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
-  return path.join(appdata, "clauth", "supervisor");
-}
-
-export function getClauthPm2Home() {
-  if (process.env.CLAUTH_PM2_HOME) return process.env.CLAUTH_PM2_HOME;
-  return path.join(getSupervisorDir(), "pm2-home");
-}
-
-function file(name) {
-  return path.join(getSupervisorDir(), name);
-}
-
-function readJson(filePath, fallback) {
-  try {
-    if (!fs.existsSync(filePath)) return fallback;
-    return JSON.parse(fs.readFileSync(filePath, "utf8"));
-  } catch {
-    return fallback;
-  }
-}
-
-function writeJson(filePath, value) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
-}
-
-function appendJsonl(filePath, value) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.appendFileSync(filePath, `${JSON.stringify(value)}\n`, "utf8");
-}
-
-function sha256(value) {
-  return crypto.createHash("sha256").update(value).digest("hex");
-}
-
-function now() {
-  return new Date().toISOString();
-}
-
-function healthUrlForSurface(surface) {
-  if (!surface?.health) return null;
-  if (/^https?:\/\//i.test(surface.health)) return surface.health;
-  if (!surface.port || surface.port === "auto") return null;
-  return `http://127.0.0.1:${surface.port}${String(surface.health).startsWith("/") ? surface.health : `/${surface.health}`}`;
-}
-
-function updateSurfaceState(surfaceId, patch) {
-  const state = loadSupervisorState();
-  state.surfaces = (state.surfaces || []).map((surface) => (
-    `${surface.plugin_id}:${surface.id}` === surfaceId || surface.id === surfaceId
-      ? { ...surface, ...patch }
-      : surface
-  ));
-  saveSupervisorState(state);
-  return state.surfaces.find((surface) => `${surface.plugin_id}:${surface.id}` === surfaceId || surface.id === surfaceId) || null;
-}
-
-function appendSupervisorEvent(event) {
-  appendJsonl(file("events.jsonl"), { ts: now(), ...event });
-}
-
-async function probeSurfaceHealth(url, fetchImpl, timeoutMs) {
-  try {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-      const response = await fetchImpl(url, { signal: controller.signal });
-      return response?.ok
-        ? { healthy: true, error: null }
-        : { healthy: false, error: `HTTP ${response?.status ?? "unknown"}` };
-    } finally {
-      clearTimeout(timer);
-    }
-  } catch (err) {
-    return { healthy: false, error: err?.name === "AbortError" ? "health timeout" : String(err?.message || err) };
-  }
-}
-
-/**
- * Probe enabled local clauth-owned surfaces and repair an unavailable one via
- * the same governed action path exposed to Dev Center. External/plugin-owned
- * surfaces are intentionally observe-only and are never restarted here.
- */
-export async function reconcileSurfaceHealth({ fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_HEALTH_TIMEOUT_MS } = {}) {
-  const inspected = [];
-  for (const surface of listSurfaces()) {
-    if (!surface.enabled || surface.lifecycle_owner !== "clauth" || surface.destination !== "local/clauth/pm2") continue;
-    const id = `${surface.plugin_id}:${surface.id}`;
-    const url = healthUrlForSurface(surface);
-    if (!url) continue;
-    const observedAt = now();
-    const health = await probeSurfaceHealth(url, fetchImpl, timeoutMs);
-    const healthy = health.healthy;
-    const error = health.error;
-
-    if (healthy) {
-      updateSurfaceState(id, { state: "current", last_health_at: observedAt, last_health_ok: true, last_health_error: null });
-      inspected.push({ surface_id: id, state: "healthy", observed_at: observedAt });
-      continue;
-    }
-
-    const lastAttempt = Date.parse(surface.last_reconcile_at || "") || 0;
-    if (Date.now() - lastAttempt < HEALTH_RECONCILE_COOLDOWN_MS) {
-      updateSurfaceState(id, { state: "unavailable", last_health_at: observedAt, last_health_ok: false, last_health_error: error });
-      inspected.push({ surface_id: id, state: "unavailable", error, cooldown: true, observed_at: observedAt });
-      continue;
-    }
-
-    updateSurfaceState(id, {
-      state: "unavailable",
-      last_health_at: observedAt,
-      last_health_ok: false,
-      last_health_error: error,
-      last_reconcile_at: observedAt,
-    });
-    appendSupervisorEvent({ kind: "surface_health_failed", surface_id: id, error, health: url });
-    const receipt = runSurfaceAction(id, "reconcile", "supervisor-health-loop");
-    const commandCompleted = receipt?.resulting_state?.ok === true;
-    const postHealth = commandCompleted ? await probeSurfaceHealth(url, fetchImpl, timeoutMs) : { healthy: false, error: receipt?.resulting_state?.state || "reconcile_failed" };
-    const repaired = commandCompleted && postHealth.healthy;
-    updateSurfaceState(id, {
-      state: repaired ? "current" : "unavailable",
-      last_health_at: now(),
-      last_health_ok: repaired,
-      last_health_error: repaired ? null : postHealth.error,
-      last_reconcile_operation_id: receipt?.operationId || null,
-    });
-    appendSupervisorEvent({ kind: repaired ? "surface_reconciled" : "surface_reconcile_failed", surface_id: id, operation_id: receipt?.operationId || null, command_completed: commandCompleted, health_ok: postHealth.healthy, error: postHealth.error || null });
-    inspected.push({ surface_id: id, state: repaired ? "reconciled" : "reconcile_failed", error: postHealth.error || error, operation_id: receipt?.operationId || null, observed_at: observedAt });
-  }
-  return { inspected };
-}
-
-function normalizeCommand(command, field) {
-  if (!command) return [];
-  if (!Array.isArray(command)) throw new Error(`${field} must be a command array`);
-  if (command.length === 0) return [];
-  const [cmd, ...args] = command;
-  if (typeof cmd !== "string" || !cmd.trim()) throw new Error(`${field}[0] is required`);
-  if (/[;&|<>]/.test(cmd)) throw new Error(`${field}[0] must be an executable path/name, not shell syntax`);
-  return [cmd, ...args.map(String)];
-}
-
-function expandPathToken(value) {
-  if (!value) return null;
-  const root = process.env.REGEN_ROOT || process.env.LIFEAI_REPO_ROOT || "C:/Dev/regen-root";
-  return String(value)
-    .replace(/\$\{REGEN_ROOT\}/g, root)
-    .replace(/\$REGEN_ROOT/g, root)
-    .replace(/%REGEN_ROOT%/gi, root)
-    .replace(/\$\{LIFEAI_REPO_ROOT\}/g, root)
-    .replace(/\$LIFEAI_REPO_ROOT/g, root)
-    .replace(/%LIFEAI_REPO_ROOT%/gi, root);
-}
-
-function normalizeLifecycleOwner(owner) {
-  const value = owner || "clauth";
-  if (!OWNERS.has(value)) throw new Error(`lifecycle_owner must be one of ${[...OWNERS].join(", ")}`);
-  return value;
-}
-
-function normalizeDestination(destination) {
-  const value = destination || "local/clauth/pm2";
-  if (!DESTINATIONS.has(value)) throw new Error(`destination must be one of ${[...DESTINATIONS].join(", ")}`);
-  return value;
-}
-
-function normalizeDocumentation(value) {
-  if (value == null) return null;
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("documentation must be an object");
-  const documentation = {};
-  for (const field of DOCUMENTATION_FIELDS) {
-    if (value[field] == null) continue;
-    if (typeof value[field] !== "string" || !value[field].trim()) {
-      throw new Error(`documentation.${field} must be a non-empty path`);
-    }
-    const ref = value[field].trim().replaceAll("\\", "/");
-    if (ref.startsWith("/") || ref.includes("..") || /^[a-z]+:/i.test(ref)) {
-      throw new Error(`documentation.${field} must be a repository-relative path`);
-    }
-    documentation[field] = ref;
-  }
-  if (!documentation.architecture) throw new Error("documentation.architecture is required");
-  return documentation;
-}
-
-function localhostHealth(pathOrUrl, port) {
-  if (!pathOrUrl) return null;
-  if (/^https?:\/\//i.test(pathOrUrl)) {
-    const url = new URL(pathOrUrl);
-    if (!["127.0.0.1", "localhost", "[::1]", "::1"].includes(url.hostname)) {
-      throw new Error("health URLs must be localhost-only");
-    }
-    return url.toString();
-  }
-  const safePath = String(pathOrUrl).startsWith("/") ? String(pathOrUrl) : `/${pathOrUrl}`;
-  return port ? `http://127.0.0.1:${port}${safePath}` : safePath;
-}
-
-function normalizeSurface(surface, plugin) {
-  if (!surface || typeof surface !== "object") throw new Error("surface must be an object");
-  const id = String(surface.id || "").trim();
-  if (!/^[a-zA-Z0-9_.-]+$/.test(id)) throw new Error("surface.id may contain only letters, numbers, dot, underscore, and dash");
-  const destination = normalizeDestination(surface.destination || plugin.destination);
-  const lifecycle_owner = normalizeLifecycleOwner(surface.lifecycle_owner || plugin.lifecycle_owner);
-  const port = surface.port === undefined || surface.port === null || surface.port === "auto" ? surface.port ?? null : Number(surface.port);
-  if (port !== null && port !== "auto" && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error("surface.port must be auto or a TCP port");
-  return {
-    id,
-    plugin_id: plugin.id,
-    name: surface.name || id,
-    destination,
-    lifecycle_owner,
-    port,
-    health: localhostHealth(surface.health || "/health", port === "auto" ? null : port),
-    cwd: expandPathToken(surface.cwd || plugin.cwd),
-    start: normalizeCommand(surface.start || plugin.start, "surface.start"),
-    stop: normalizeCommand(surface.stop || plugin.stop, "surface.stop"),
-    restart: normalizeCommand(surface.restart || plugin.restart, "surface.restart"),
-    routes: Array.isArray(surface.routes) ? surface.routes : [],
-  };
-}
-
-export function validatePluginManifest(manifest, sourcePath = "") {
-  if (!manifest || typeof manifest !== "object") throw new Error("manifest must be an object");
-  if (manifest.schema !== SCHEMA) throw new Error(`schema must be ${SCHEMA}`);
-  const id = String(manifest.id || "").trim();
-  if (!/^[a-zA-Z0-9_.-]+$/.test(id)) throw new Error("id may contain only letters, numbers, dot, underscore, and dash");
-  const version = String(manifest.version || "").trim();
-  if (!version) throw new Error("version is required");
-  const plugin = {
-    schema: SCHEMA,
-    id,
-    version,
-    publisher: String(manifest.publisher || "unknown"),
-    documentation: normalizeDocumentation(manifest.documentation),
-    // Only trusted managed manifests may opt into automatic startup. User
-    // plugins remain awaiting_enable until an operator explicitly enables them.
-    core: manifest.core === true,
-    enable_default: manifest.enable_default === true,
-    sourcePath,
-    destination: normalizeDestination(manifest.destination),
-    lifecycle_owner: normalizeLifecycleOwner(manifest.lifecycle_owner),
-    credentials: Array.isArray(manifest.credentials) ? manifest.credentials.map((c) => ({
-      name: String(c.name || c.id || "").trim(),
-      key_type: String(c.key_type || c.type || "secret"),
-      description: String(c.description || ""),
-      required: c.required !== false,
-    })).filter((c) => /^[a-zA-Z0-9_.-]+$/.test(c.name)) : [],
-    surfaces: [],
-    routes: Array.isArray(manifest.routes) ? manifest.routes : [],
-    test: manifest.test && typeof manifest.test === "object" ? {
-      command: normalizeCommand(manifest.test.command, "test.command"),
-      port: manifest.test.port || "auto",
-      health: manifest.test.health || "/health",
-      selfTest: Array.isArray(manifest.test.selfTest) ? manifest.test.selfTest.map((cmd, i) => normalizeCommand(cmd, `test.selfTest[${i}]`)) : [],
-    } : null,
-  };
-  plugin.surfaces = (Array.isArray(manifest.surfaces) ? manifest.surfaces : []).map((surface) => normalizeSurface(surface, plugin));
-  return plugin;
-}
-
-function rootEntries() {
-  const managed = (process.env.CLAUTH_MANAGED_PLUGIN_ROOTS || "").split(path.delimiter).filter(Boolean);
-  const user = (process.env.CLAUTH_USER_PLUGIN_ROOTS || "").split(path.delimiter).filter(Boolean);
-  if (managed.length === 0) managed.push(path.join(getSupervisorDir(), "managed-plugins"));
-  if (user.length === 0) user.push(path.join(getSupervisorDir(), "user-plugins"));
-  return [
-    ...managed.map((root) => ({ root, source: "managed" })),
-    ...user.map((root) => ({ root, source: "user" })),
-  ];
-}
-
-function findManifestFiles(root) {
-  const out = [];
-  if (!fs.existsSync(root)) return out;
-  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-    const full = path.join(root, entry.name);
-    if (entry.isDirectory()) {
-      const candidate = path.join(full, "clauth-plugin.json");
-      if (fs.existsSync(candidate)) out.push(candidate);
-    } else if (entry.isFile() && entry.name === "clauth-plugin.json") {
-      out.push(full);
-    }
-  }
-  return out;
-}
-
-export function loadSupervisorState() {
-  return readJson(file("state.json"), { plugins: [], surfaces: [], routes: [], observations: [], operations: [] });
-}
-
-function saveSupervisorState(state) {
-  writeJson(file("state.json"), state);
-  writeJson(file("last-known-good.json"), {
-    signed_at: now(),
-    hash: sha256(JSON.stringify(state)),
-    state,
-  });
-}
-
-function existingById(state) {
-  return new Map((state.plugins || []).map((plugin) => [plugin.id, plugin]));
-}
-
-export function discoverPlugins() {
-  const previous = loadSupervisorState();
-  const seen = new Set();
-  const byId = existingById(previous);
-  const plugins = [];
-  const surfaces = [];
-  const events = [];
-  const managedIds = new Set();
-
-  for (const { root, source } of rootEntries()) {
-    fs.mkdirSync(root, { recursive: true });
-    for (const manifestPath of findManifestFiles(root)) {
-      const raw = fs.readFileSync(manifestPath, "utf8");
-      const hash = sha256(raw);
-      try {
-        const manifest = validatePluginManifest(JSON.parse(raw), manifestPath);
-        if (source === "managed") managedIds.add(manifest.id);
-        if (source === "user" && managedIds.has(manifest.id)) {
-          throw new Error("user plugin cannot silently shadow a managed plugin id");
-        }
-        const prior = byId.get(manifest.id);
-        const autoEnabled = source === "managed" && manifest.core === true && manifest.enable_default === true;
-        const enabled = Boolean(prior?.enabled || autoEnabled);
-        const state = enabled ? (prior?.manifest_hash === hash || autoEnabled ? "current" : "version_drift") : "awaiting_enable";
-        const plugin = { ...manifest, source, discovery_root: root, manifest_hash: hash, state, enabled, discovered_at: now() };
-        plugins.push(plugin);
-        for (const surface of plugin.surfaces) surfaces.push({ ...surface, enabled: plugin.enabled, state });
-        for (const credential of plugin.credentials) {
-          events.push({ kind: "credential_required", plugin_id: plugin.id, credential, value_set: false });
-        }
-        seen.add(plugin.id);
-        events.push({ kind: autoEnabled && !prior?.enabled ? "core_plugin_auto_enabled" : "plugin_discovered", plugin_id: plugin.id, state, source, manifest_hash: hash });
-      } catch (error) {
-        const id = path.basename(path.dirname(manifestPath));
-        plugins.push({
-          id,
-          source,
-          sourcePath: manifestPath,
-          manifest_hash: hash,
-          state: "manifest_invalid",
-          enabled: false,
-          error: error instanceof Error ? error.message : String(error),
-          discovered_at: now(),
-        });
-        events.push({ kind: "plugin_quarantined", plugin_id: id, source, error: error instanceof Error ? error.message : String(error) });
-      }
-    }
-  }
-
-  for (const prior of previous.plugins || []) {
-    if (!seen.has(prior.id) && prior.state !== "manifest_invalid") {
-      plugins.push({ ...prior, enabled: false, state: prior.source === "managed" ? "missing_default" : "missing", missing_since: now() });
-      events.push({ kind: "plugin_missing", plugin_id: prior.id, source: prior.source });
-    }
-  }
-
-  const next = { ...previous, plugins, surfaces, routes: previous.routes || [], observations: previous.observations || [], operations: previous.operations || [] };
-  saveSupervisorState(next);
-  for (const event of events) appendJsonl(file("events.jsonl"), { ts: now(), ...event });
-  return { plugins, surfaces, events };
-}
-
-export function listPlugins() {
-  return loadSupervisorState().plugins || [];
-}
-
-export function listSurfaces() {
-  return loadSupervisorState().surfaces || [];
-}
-
-export function listRoutes() {
-  return loadSupervisorState().routes || [];
-}
-
-export function listTunnels() {
-  return readJson(file("tunnels.json"), { tunnels: [] }).tunnels;
-}
-
-function writeTunnels(tunnels) {
-  writeJson(file("tunnels.json"), { tunnels });
-}
-
-export function readSupervisorEvents(limit = 100) {
-  const p = file("events.jsonl");
-  if (!fs.existsSync(p)) return [];
-  return fs.readFileSync(p, "utf8").split(/\r?\n/).filter(Boolean).slice(-limit).map((line) => {
-    try { return JSON.parse(line); } catch { return { raw: line }; }
-  });
-}
-
-function operation(action, target, prior, result, actor = "localhost") {
-  const receipt = {
-    operationId: crypto.randomUUID(),
-    actor,
-    action,
-    target,
-    prior_state: prior || null,
-    resulting_state: result,
-    evidence: result?.evidence || [],
-    created_at: now(),
-    completed_at: now(),
-  };
-  const state = loadSupervisorState();
-  state.operations = [receipt, ...(state.operations || [])].slice(0, 500);
-  saveSupervisorState(state);
-  appendJsonl(file("events.jsonl"), { ts: now(), kind: "operation", ...receipt });
-  return receipt;
-}
-
-export function setPluginEnabled(id, enabled, actor = "localhost") {
-  const state = loadSupervisorState();
-  const prior = (state.plugins || []).find((plugin) => plugin.id === id);
-  if (!prior) return { error: "plugin_not_found" };
-  if (prior.state === "manifest_invalid") return { error: "manifest_invalid" };
-  const nextPlugin = { ...prior, enabled: Boolean(enabled), state: enabled ? "current" : "awaiting_enable" };
-  state.plugins = state.plugins.map((plugin) => plugin.id === id ? nextPlugin : plugin);
-  state.surfaces = (state.surfaces || []).map((surface) => surface.plugin_id === id ? { ...surface, enabled: Boolean(enabled), state: nextPlugin.state } : surface);
-  saveSupervisorState(state);
-  return operation(enabled ? "enable" : "disable", { plugin_id: id }, prior, nextPlugin, actor);
-}
-
-export function runPluginAction(id, action, actor = "localhost") {
-  if (!["test", "promote"].includes(action)) return { error: "invalid_action" };
-  const state = loadSupervisorState();
-  const prior = (state.plugins || []).find((plugin) => plugin.id === id);
-  if (!prior) return { error: "plugin_not_found" };
-  if (prior.state === "manifest_invalid") return { error: "manifest_invalid" };
-  const resultingState = action === "test" ? "candidate_testing" : "promotion_ready";
-  const nextPlugin = {
-    ...prior,
-    state: resultingState,
-    candidate: action === "test"
-      ? {
-          port: prior.test?.port === "auto" || !prior.test?.port ? 0 : prior.test.port,
-          public_route: false,
-          bind: "127.0.0.1",
-          tested_at: now(),
-        }
-      : prior.candidate || null,
-  };
-  state.plugins = state.plugins.map((plugin) => plugin.id === id ? nextPlugin : plugin);
-  saveSupervisorState(state);
-  return operation(action, { plugin_id: id }, prior, {
-    ok: true,
-    state: resultingState,
-    private: true,
-    public_route: false,
-    evidence: ["plugin candidate context does not create a Cloudflare route"],
-  }, actor);
-}
-
-function findSurface(id) {
-  return (loadSupervisorState().surfaces || []).find((surface) => surface.id === id || `${surface.plugin_id}:${surface.id}` === id);
-}
-
-export function runSurfaceAction(id, action, actor = "localhost") {
-  if (!ACTIONS.has(action)) return { error: "invalid_action" };
-  const surface = findSurface(id);
-  if (!surface) return { error: "surface_not_found" };
-  if (surface.lifecycle_owner === "external") {
-    return operation(action, { surface_id: id }, surface, { ok: false, state: "observed_only", reason: "external_owner" }, actor);
-  }
-  if (surface.plugin_id === "codeflow" || surface.tags?.includes("codeflow")) {
-    return operation(action, { surface_id: id }, surface, { ok: false, state: "observed_only", reason: "codeflow_self_owned" }, actor);
-  }
-  if (action === "test") {
-    const port = surface.port === "auto" || !surface.port ? 0 : surface.port;
-    return operation(action, { surface_id: id }, surface, { ok: true, state: "candidate_testing", port, private: true, public_route: false, evidence: ["candidate surfaces bind localhost only"] }, actor);
-  }
-  if (surface.lifecycle_owner === "plugin") {
-    return operation(action, { surface_id: id }, surface, { ok: true, state: "delegated_to_plugin_adapter", evidence: ["plugin lifecycle owner retained"] }, actor);
-  }
-  if (action === "promote" || action === "rollback") {
-    return operation(action, { surface_id: id }, surface, {
-      ok: false,
-      state: "unsupported_surface_action",
-      reason: `${action}_is_plugin_candidate_lifecycle`,
-      evidence: ["surface action did not execute a process command"],
-    }, actor);
-  }
-  let command = null;
-  if (action === "stop") command = surface.stop;
-  else if (action === "start") command = surface.start;
-  else if (action === "restart") command = surface.restart;
-  else if (action === "reconcile") command = surface.enabled === false ? surface.stop : (surface.restart || surface.start);
-  if (!command || command.length === 0) {
-    return operation(action, { surface_id: id }, surface, { ok: false, state: "command_missing" }, actor);
-  }
-  const execute = (selectedCommand) => {
-    const [cmd, ...args] = selectedCommand;
-    return spawnSync(cmd, args, {
-      cwd: surface.cwd || undefined,
-      env: { ...process.env, CLAUTH_PM2_HOME: getClauthPm2Home(), PM2_HOME: getClauthPm2Home() },
-      windowsHide: true,
-      encoding: "utf8",
-      timeout: Number(surface.timeoutMs || 30000),
-    });
-  };
-  let result = execute(command);
-  let fallbackUsed = false;
-  // PM2 restart returns non-zero when the process was deleted. Reconcile is
-  // allowed to fall back to the declared start command; explicit restart keeps
-  // its strict failure semantics for operator-requested actions.
-  if (action === "reconcile" && result.status !== 0 && Array.isArray(surface.start) && surface.start.length > 0 && command !== surface.start) {
-    const restartStatus = result.status;
-    result = execute(surface.start);
-    fallbackUsed = true;
-    result.stderr = `restart exited ${restartStatus}; start fallback attempted\n${result.stderr || ""}`;
-  }
-  return operation(action, { surface_id: id }, surface, {
-    ok: result.status === 0,
-    state: result.status === 0 ? "operation_completed" : "operation_failed",
-    status: result.status,
-    stderr: result.stderr?.slice(0, 2000),
-    evidence: [`CLAUTH_PM2_HOME=${getClauthPm2Home()}`, ...(fallbackUsed ? ["reconcile_start_fallback=true"] : [])],
-  }, actor);
-}
-
-export function addTunnelRoute(tunnelId, route, actor = "localhost") {
-  const tunnels = listTunnels();
-  const tunnel = tunnels.find((item) => item.id === tunnelId);
-  const prior = tunnel || { id: tunnelId, provider: "cloudflare", routes: [] };
-  const routeId = String(route?.routeId || route?.id || crypto.randomUUID());
-  const nextRoute = {
-    id: routeId,
-    hostname: String(route?.hostname || "").trim(),
-    service_url: String(route?.service_url || route?.serviceUrl || "").trim(),
-    desired_state: "enabled",
-    public_route: true,
-  };
-  if (!nextRoute.hostname || !nextRoute.service_url) {
-    return operation("tunnel_route_add", { tunnel_id: tunnelId }, prior, { ok: false, state: "invalid_route" }, actor);
-  }
-  const nextTunnel = { ...prior, routes: [nextRoute, ...(prior.routes || []).filter((item) => item.id !== routeId)] };
-  writeTunnels([nextTunnel, ...tunnels.filter((item) => item.id !== tunnelId)]);
-  return operation("tunnel_route_add", { tunnel_id: tunnelId, route_id: routeId }, prior, { ok: true, state: "route_recorded", route: nextRoute }, actor);
-}
-
-export function removeTunnelRoute(tunnelId, routeId, actor = "localhost") {
-  const tunnels = listTunnels();
-  const tunnel = tunnels.find((item) => item.id === tunnelId);
-  if (!tunnel) return operation("tunnel_route_remove", { tunnel_id: tunnelId, route_id: routeId }, {}, { ok: false, state: "tunnel_not_found" }, actor);
-  const prior = tunnel;
-  const nextTunnel = { ...tunnel, routes: (tunnel.routes || []).filter((item) => item.id !== routeId) };
-  writeTunnels([nextTunnel, ...tunnels.filter((item) => item.id !== tunnelId)]);
-  return operation("tunnel_route_remove", { tunnel_id: tunnelId, route_id: routeId }, prior, { ok: true, state: "route_removed", route_id: routeId }, actor);
-}
-
-export function supervisorHealth() {
-  const state = loadSupervisorState();
-  return {
-    status: "ok",
-    port: getSupervisorPort(),
-    schema: "clauth.supervisor.v1",
-    pm2_home: getClauthPm2Home(),
-    plugins: (state.plugins || []).length,
-    surfaces: (state.surfaces || []).length,
-    operations: (state.operations || []).length,
-  };
-}
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const SCHEMA = "lifeai.plugin.v1";
+const DEFAULT_TIMEOUT_MS = 3000;
+const DEFAULT_SUPERVISOR_PORT = 52439;
+// local/clauth/daemon: for a surface that is not a separately-startable
+// process at all, but literally embedded in the clauth daemon itself (e.g.
+// fs-mcp) — distinct from local/clauth/pm2 (a separate local process clauth
+// manages via pm2) because there is nothing for a surface action to
+// start/stop/restart; the daemon's own lifecycle IS the surface's lifecycle.
+const DESTINATIONS = new Set(["local/clauth/pm2", "local/clauth/daemon", "vultr/clauth/pm2", "coolify/clauth/docker"]);
+const OWNERS = new Set(["clauth", "plugin", "external"]);
+const ACTIONS = new Set(["start", "stop", "restart", "reconcile", "test", "promote", "rollback"]);
+const DEFAULT_HEALTH_RECONCILE_INTERVAL_MS = 10000;
+const DEFAULT_HEALTH_TIMEOUT_MS = 2500;
+const HEALTH_RECONCILE_COOLDOWN_MS = 15000;
+const DOCUMENTATION_FIELDS = ["architecture", "operator_guide", "install", "runbook", "tool_reference", "release", "agent_context"];
+
+export function getSupervisorPort() {
+  return Number(process.env.CLAUTH_SUPERVISOR_PORT || DEFAULT_SUPERVISOR_PORT);
+}
+
+export function getSupervisorDir() {
+  if (process.env.CLAUTH_SUPERVISOR_DIR) return process.env.CLAUTH_SUPERVISOR_DIR;
+  const appdata = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+  return path.join(appdata, "clauth", "supervisor");
+}
+
+export function getClauthPm2Home() {
+  if (process.env.CLAUTH_PM2_HOME) return process.env.CLAUTH_PM2_HOME;
+  return path.join(getSupervisorDir(), "pm2-home");
+}
+
+function file(name) {
+  return path.join(getSupervisorDir(), name);
+}
+
+function readJson(filePath, fallback) {
+  try {
+    if (!fs.existsSync(filePath)) return fallback;
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function appendJsonl(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, `${JSON.stringify(value)}\n`, "utf8");
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function now() {
+  return new Date().toISOString();
+}
+
+function healthUrlForSurface(surface) {
+  if (!surface?.health) return null;
+  if (/^https?:\/\//i.test(surface.health)) return surface.health;
+  if (!surface.port || surface.port === "auto") return null;
+  return `http://127.0.0.1:${surface.port}${String(surface.health).startsWith("/") ? surface.health : `/${surface.health}`}`;
+}
+
+function updateSurfaceState(surfaceId, patch) {
+  const state = loadSupervisorState();
+  state.surfaces = (state.surfaces || []).map((surface) => (
+    `${surface.plugin_id}:${surface.id}` === surfaceId || surface.id === surfaceId
+      ? { ...surface, ...patch }
+      : surface
+  ));
+  saveSupervisorState(state);
+  return state.surfaces.find((surface) => `${surface.plugin_id}:${surface.id}` === surfaceId || surface.id === surfaceId) || null;
+}
+
+function appendSupervisorEvent(event) {
+  appendJsonl(file("events.jsonl"), { ts: now(), ...event });
+}
+
+async function probeSurfaceHealth(url, fetchImpl, timeoutMs) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetchImpl(url, { signal: controller.signal });
+      return response?.ok
+        ? { healthy: true, error: null }
+        : { healthy: false, error: `HTTP ${response?.status ?? "unknown"}` };
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    return { healthy: false, error: err?.name === "AbortError" ? "health timeout" : String(err?.message || err) };
+  }
+}
+
+/**
+ * Probe enabled local clauth-owned surfaces and repair an unavailable one via
+ * the same governed action path exposed to Dev Center. External/plugin-owned
+ * surfaces are intentionally observe-only and are never restarted here.
+ */
+export async function reconcileSurfaceHealth({ fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_HEALTH_TIMEOUT_MS } = {}) {
+  const inspected = [];
+  for (const surface of listSurfaces()) {
+    if (!surface.enabled || surface.lifecycle_owner !== "clauth" || surface.destination !== "local/clauth/pm2") continue;
+    const id = `${surface.plugin_id}:${surface.id}`;
+    const url = healthUrlForSurface(surface);
+    if (!url) continue;
+    const observedAt = now();
+    const health = await probeSurfaceHealth(url, fetchImpl, timeoutMs);
+    const healthy = health.healthy;
+    const error = health.error;
+
+    if (healthy) {
+      updateSurfaceState(id, { state: "current", last_health_at: observedAt, last_health_ok: true, last_health_error: null });
+      inspected.push({ surface_id: id, state: "healthy", observed_at: observedAt });
+      continue;
+    }
+
+    const lastAttempt = Date.parse(surface.last_reconcile_at || "") || 0;
+    if (Date.now() - lastAttempt < HEALTH_RECONCILE_COOLDOWN_MS) {
+      updateSurfaceState(id, { state: "unavailable", last_health_at: observedAt, last_health_ok: false, last_health_error: error });
+      inspected.push({ surface_id: id, state: "unavailable", error, cooldown: true, observed_at: observedAt });
+      continue;
+    }
+
+    updateSurfaceState(id, {
+      state: "unavailable",
+      last_health_at: observedAt,
+      last_health_ok: false,
+      last_health_error: error,
+      last_reconcile_at: observedAt,
+    });
+    appendSupervisorEvent({ kind: "surface_health_failed", surface_id: id, error, health: url });
+    const receipt = runSurfaceAction(id, "reconcile", "supervisor-health-loop");
+    const commandCompleted = receipt?.resulting_state?.ok === true;
+    const postHealth = commandCompleted ? await probeSurfaceHealth(url, fetchImpl, timeoutMs) : { healthy: false, error: receipt?.resulting_state?.state || "reconcile_failed" };
+    const repaired = commandCompleted && postHealth.healthy;
+    updateSurfaceState(id, {
+      state: repaired ? "current" : "unavailable",
+      last_health_at: now(),
+      last_health_ok: repaired,
+      last_health_error: repaired ? null : postHealth.error,
+      last_reconcile_operation_id: receipt?.operationId || null,
+    });
+    appendSupervisorEvent({ kind: repaired ? "surface_reconciled" : "surface_reconcile_failed", surface_id: id, operation_id: receipt?.operationId || null, command_completed: commandCompleted, health_ok: postHealth.healthy, error: postHealth.error || null });
+    inspected.push({ surface_id: id, state: repaired ? "reconciled" : "reconcile_failed", error: postHealth.error || error, operation_id: receipt?.operationId || null, observed_at: observedAt });
+  }
+  return { inspected };
+}
+
+function normalizeCommand(command, field) {
+  if (!command) return [];
+  if (!Array.isArray(command)) throw new Error(`${field} must be a command array`);
+  if (command.length === 0) return [];
+  const [cmd, ...args] = command;
+  if (typeof cmd !== "string" || !cmd.trim()) throw new Error(`${field}[0] is required`);
+  if (/[;&|<>]/.test(cmd)) throw new Error(`${field}[0] must be an executable path/name, not shell syntax`);
+  return [cmd, ...args.map(String)];
+}
+
+function expandPathToken(value) {
+  if (!value) return null;
+  const root = process.env.REGEN_ROOT || process.env.LIFEAI_REPO_ROOT || "C:/Dev/regen-root";
+  return String(value)
+    .replace(/\$\{REGEN_ROOT\}/g, root)
+    .replace(/\$REGEN_ROOT/g, root)
+    .replace(/%REGEN_ROOT%/gi, root)
+    .replace(/\$\{LIFEAI_REPO_ROOT\}/g, root)
+    .replace(/\$LIFEAI_REPO_ROOT/g, root)
+    .replace(/%LIFEAI_REPO_ROOT%/gi, root);
+}
+
+function normalizeLifecycleOwner(owner) {
+  const value = owner || "clauth";
+  if (!OWNERS.has(value)) throw new Error(`lifecycle_owner must be one of ${[...OWNERS].join(", ")}`);
+  return value;
+}
+
+function normalizeDestination(destination) {
+  const value = destination || "local/clauth/pm2";
+  if (!DESTINATIONS.has(value)) throw new Error(`destination must be one of ${[...DESTINATIONS].join(", ")}`);
+  return value;
+}
+
+function normalizeDocumentation(value) {
+  if (value == null) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("documentation must be an object");
+  const documentation = {};
+  for (const field of DOCUMENTATION_FIELDS) {
+    if (value[field] == null) continue;
+    if (typeof value[field] !== "string" || !value[field].trim()) {
+      throw new Error(`documentation.${field} must be a non-empty path`);
+    }
+    const ref = value[field].trim().replaceAll("\\", "/");
+    if (ref.startsWith("/") || ref.includes("..") || /^[a-z]+:/i.test(ref)) {
+      throw new Error(`documentation.${field} must be a repository-relative path`);
+    }
+    documentation[field] = ref;
+  }
+  if (!documentation.architecture) throw new Error("documentation.architecture is required");
+  return documentation;
+}
+
+function localhostHealth(pathOrUrl, port) {
+  if (!pathOrUrl) return null;
+  if (/^https?:\/\//i.test(pathOrUrl)) {
+    const url = new URL(pathOrUrl);
+    if (!["127.0.0.1", "localhost", "[::1]", "::1"].includes(url.hostname)) {
+      throw new Error("health URLs must be localhost-only");
+    }
+    return url.toString();
+  }
+  const safePath = String(pathOrUrl).startsWith("/") ? String(pathOrUrl) : `/${pathOrUrl}`;
+  return port ? `http://127.0.0.1:${port}${safePath}` : safePath;
+}
+
+function normalizeSurface(surface, plugin) {
+  if (!surface || typeof surface !== "object") throw new Error("surface must be an object");
+  const id = String(surface.id || "").trim();
+  if (!/^[a-zA-Z0-9_.-]+$/.test(id)) throw new Error("surface.id may contain only letters, numbers, dot, underscore, and dash");
+  const destination = normalizeDestination(surface.destination || plugin.destination);
+  const lifecycle_owner = normalizeLifecycleOwner(surface.lifecycle_owner || plugin.lifecycle_owner);
+  const port = surface.port === undefined || surface.port === null || surface.port === "auto" ? surface.port ?? null : Number(surface.port);
+  if (port !== null && port !== "auto" && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error("surface.port must be auto or a TCP port");
+  return {
+    id,
+    plugin_id: plugin.id,
+    name: surface.name || id,
+    destination,
+    lifecycle_owner,
+    port,
+    health: localhostHealth(surface.health || "/health", port === "auto" ? null : port),
+    cwd: expandPathToken(surface.cwd || plugin.cwd),
+    start: normalizeCommand(surface.start || plugin.start, "surface.start"),
+    stop: normalizeCommand(surface.stop || plugin.stop, "surface.stop"),
+    restart: normalizeCommand(surface.restart || plugin.restart, "surface.restart"),
+    routes: Array.isArray(surface.routes) ? surface.routes : [],
+  };
+}
+
+export function validatePluginManifest(manifest, sourcePath = "") {
+  if (!manifest || typeof manifest !== "object") throw new Error("manifest must be an object");
+  if (manifest.schema !== SCHEMA) throw new Error(`schema must be ${SCHEMA}`);
+  const id = String(manifest.id || "").trim();
+  if (!/^[a-zA-Z0-9_.-]+$/.test(id)) throw new Error("id may contain only letters, numbers, dot, underscore, and dash");
+  const version = String(manifest.version || "").trim();
+  if (!version) throw new Error("version is required");
+  const plugin = {
+    schema: SCHEMA,
+    id,
+    version,
+    publisher: String(manifest.publisher || "unknown"),
+    documentation: normalizeDocumentation(manifest.documentation),
+    // Only trusted managed manifests may opt into automatic startup. User
+    // plugins remain awaiting_enable until an operator explicitly enables them.
+    core: manifest.core === true,
+    enable_default: manifest.enable_default === true,
+    sourcePath,
+    destination: normalizeDestination(manifest.destination),
+    lifecycle_owner: normalizeLifecycleOwner(manifest.lifecycle_owner),
+    credentials: Array.isArray(manifest.credentials) ? manifest.credentials.map((c) => ({
+      name: String(c.name || c.id || "").trim(),
+      key_type: String(c.key_type || c.type || "secret"),
+      description: String(c.description || ""),
+      required: c.required !== false,
+    })).filter((c) => /^[a-zA-Z0-9_.-]+$/.test(c.name)) : [],
+    surfaces: [],
+    routes: Array.isArray(manifest.routes) ? manifest.routes : [],
+    test: manifest.test && typeof manifest.test === "object" ? {
+      command: normalizeCommand(manifest.test.command, "test.command"),
+      port: manifest.test.port || "auto",
+      health: manifest.test.health || "/health",
+      selfTest: Array.isArray(manifest.test.selfTest) ? manifest.test.selfTest.map((cmd, i) => normalizeCommand(cmd, `test.selfTest[${i}]`)) : [],
+    } : null,
+  };
+  plugin.surfaces = (Array.isArray(manifest.surfaces) ? manifest.surfaces : []).map((surface) => normalizeSurface(surface, plugin));
+  return plugin;
+}
+
+function rootEntries() {
+  const managed = (process.env.CLAUTH_MANAGED_PLUGIN_ROOTS || "").split(path.delimiter).filter(Boolean);
+  const user = (process.env.CLAUTH_USER_PLUGIN_ROOTS || "").split(path.delimiter).filter(Boolean);
+  if (managed.length === 0) managed.push(path.join(getSupervisorDir(), "managed-plugins"));
+  if (user.length === 0) user.push(path.join(getSupervisorDir(), "user-plugins"));
+  return [
+    ...managed.map((root) => ({ root, source: "managed" })),
+    ...user.map((root) => ({ root, source: "user" })),
+  ];
+}
+
+function findManifestFiles(root) {
+  const out = [];
+  if (!fs.existsSync(root)) return out;
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      const candidate = path.join(full, "clauth-plugin.json");
+      if (fs.existsSync(candidate)) out.push(candidate);
+    } else if (entry.isFile() && entry.name === "clauth-plugin.json") {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+export function loadSupervisorState() {
+  return readJson(file("state.json"), { plugins: [], surfaces: [], routes: [], observations: [], operations: [] });
+}
+
+function saveSupervisorState(state) {
+  writeJson(file("state.json"), state);
+  writeJson(file("last-known-good.json"), {
+    signed_at: now(),
+    hash: sha256(JSON.stringify(state)),
+    state,
+  });
+}
+
+function existingById(state) {
+  return new Map((state.plugins || []).map((plugin) => [plugin.id, plugin]));
+}
+
+export function discoverPlugins() {
+  const previous = loadSupervisorState();
+  const seen = new Set();
+  const byId = existingById(previous);
+  const plugins = [];
+  const surfaces = [];
+  const events = [];
+  const managedIds = new Set();
+
+  for (const { root, source } of rootEntries()) {
+    fs.mkdirSync(root, { recursive: true });
+    for (const manifestPath of findManifestFiles(root)) {
+      const raw = fs.readFileSync(manifestPath, "utf8");
+      const hash = sha256(raw);
+      try {
+        const manifest = validatePluginManifest(JSON.parse(raw), manifestPath);
+        if (source === "managed") managedIds.add(manifest.id);
+        if (source === "user" && managedIds.has(manifest.id)) {
+          throw new Error("user plugin cannot silently shadow a managed plugin id");
+        }
+        const prior = byId.get(manifest.id);
+        const autoEnabled = source === "managed" && manifest.core === true && manifest.enable_default === true;
+        const enabled = Boolean(prior?.enabled || autoEnabled);
+        const state = enabled ? (prior?.manifest_hash === hash || autoEnabled ? "current" : "version_drift") : "awaiting_enable";
+        const plugin = { ...manifest, source, discovery_root: root, manifest_hash: hash, state, enabled, discovered_at: now() };
+        plugins.push(plugin);
+        for (const surface of plugin.surfaces) surfaces.push({ ...surface, enabled: plugin.enabled, state });
+        for (const credential of plugin.credentials) {
+          events.push({ kind: "credential_required", plugin_id: plugin.id, credential, value_set: false });
+        }
+        seen.add(plugin.id);
+        events.push({ kind: autoEnabled && !prior?.enabled ? "core_plugin_auto_enabled" : "plugin_discovered", plugin_id: plugin.id, state, source, manifest_hash: hash });
+      } catch (error) {
+        const id = path.basename(path.dirname(manifestPath));
+        plugins.push({
+          id,
+          source,
+          sourcePath: manifestPath,
+          manifest_hash: hash,
+          state: "manifest_invalid",
+          enabled: false,
+          error: error instanceof Error ? error.message : String(error),
+          discovered_at: now(),
+        });
+        events.push({ kind: "plugin_quarantined", plugin_id: id, source, error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  }
+
+  for (const prior of previous.plugins || []) {
+    if (!seen.has(prior.id) && prior.state !== "manifest_invalid") {
+      plugins.push({ ...prior, enabled: false, state: prior.source === "managed" ? "missing_default" : "missing", missing_since: now() });
+      events.push({ kind: "plugin_missing", plugin_id: prior.id, source: prior.source });
+    }
+  }
+
+  const next = { ...previous, plugins, surfaces, routes: previous.routes || [], observations: previous.observations || [], operations: previous.operations || [] };
+  saveSupervisorState(next);
+  for (const event of events) appendJsonl(file("events.jsonl"), { ts: now(), ...event });
+  return { plugins, surfaces, events };
+}
+
+export function listPlugins() {
+  return loadSupervisorState().plugins || [];
+}
+
+export function listSurfaces() {
+  return loadSupervisorState().surfaces || [];
+}
+
+export function listRoutes() {
+  return loadSupervisorState().routes || [];
+}
+
+export function listTunnels() {
+  return readJson(file("tunnels.json"), { tunnels: [] }).tunnels;
+}
+
+function writeTunnels(tunnels) {
+  writeJson(file("tunnels.json"), { tunnels });
+}
+
+export function readSupervisorEvents(limit = 100) {
+  const p = file("events.jsonl");
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, "utf8").split(/\r?\n/).filter(Boolean).slice(-limit).map((line) => {
+    try { return JSON.parse(line); } catch { return { raw: line }; }
+  });
+}
+
+function operation(action, target, prior, result, actor = "localhost") {
+  const receipt = {
+    operationId: crypto.randomUUID(),
+    actor,
+    action,
+    target,
+    prior_state: prior || null,
+    resulting_state: result,
+    evidence: result?.evidence || [],
+    created_at: now(),
+    completed_at: now(),
+  };
+  const state = loadSupervisorState();
+  state.operations = [receipt, ...(state.operations || [])].slice(0, 500);
+  saveSupervisorState(state);
+  appendJsonl(file("events.jsonl"), { ts: now(), kind: "operation", ...receipt });
+  return receipt;
+}
+
+export function setPluginEnabled(id, enabled, actor = "localhost") {
+  const state = loadSupervisorState();
+  const prior = (state.plugins || []).find((plugin) => plugin.id === id);
+  if (!prior) return { error: "plugin_not_found" };
+  if (prior.state === "manifest_invalid") return { error: "manifest_invalid" };
+  const nextPlugin = { ...prior, enabled: Boolean(enabled), state: enabled ? "current" : "awaiting_enable" };
+  state.plugins = state.plugins.map((plugin) => plugin.id === id ? nextPlugin : plugin);
+  state.surfaces = (state.surfaces || []).map((surface) => surface.plugin_id === id ? { ...surface, enabled: Boolean(enabled), state: nextPlugin.state } : surface);
+  saveSupervisorState(state);
+  return operation(enabled ? "enable" : "disable", { plugin_id: id }, prior, nextPlugin, actor);
+}
+
+export function runPluginAction(id, action, actor = "localhost") {
+  if (!["test", "promote"].includes(action)) return { error: "invalid_action" };
+  const state = loadSupervisorState();
+  const prior = (state.plugins || []).find((plugin) => plugin.id === id);
+  if (!prior) return { error: "plugin_not_found" };
+  if (prior.state === "manifest_invalid") return { error: "manifest_invalid" };
+  const resultingState = action === "test" ? "candidate_testing" : "promotion_ready";
+  const nextPlugin = {
+    ...prior,
+    state: resultingState,
+    candidate: action === "test"
+      ? {
+          port: prior.test?.port === "auto" || !prior.test?.port ? 0 : prior.test.port,
+          public_route: false,
+          bind: "127.0.0.1",
+          tested_at: now(),
+        }
+      : prior.candidate || null,
+  };
+  state.plugins = state.plugins.map((plugin) => plugin.id === id ? nextPlugin : plugin);
+  saveSupervisorState(state);
+  return operation(action, { plugin_id: id }, prior, {
+    ok: true,
+    state: resultingState,
+    private: true,
+    public_route: false,
+    evidence: ["plugin candidate context does not create a Cloudflare route"],
+  }, actor);
+}
+
+function findSurface(id) {
+  return (loadSupervisorState().surfaces || []).find((surface) => surface.id === id || `${surface.plugin_id}:${surface.id}` === id);
+}
+
+export function runSurfaceAction(id, action, actor = "localhost") {
+  if (!ACTIONS.has(action)) return { error: "invalid_action" };
+  const surface = findSurface(id);
+  if (!surface) return { error: "surface_not_found" };
+  if (surface.lifecycle_owner === "external") {
+    return operation(action, { surface_id: id }, surface, { ok: false, state: "observed_only", reason: "external_owner" }, actor);
+  }
+  if (surface.plugin_id === "codeflow" || surface.tags?.includes("codeflow")) {
+    return operation(action, { surface_id: id }, surface, { ok: false, state: "observed_only", reason: "codeflow_self_owned" }, actor);
+  }
+  if (action === "test") {
+    const port = surface.port === "auto" || !surface.port ? 0 : surface.port;
+    return operation(action, { surface_id: id }, surface, { ok: true, state: "candidate_testing", port, private: true, public_route: false, evidence: ["candidate surfaces bind localhost only"] }, actor);
+  }
+  if (surface.lifecycle_owner === "plugin") {
+    return operation(action, { surface_id: id }, surface, { ok: true, state: "delegated_to_plugin_adapter", evidence: ["plugin lifecycle owner retained"] }, actor);
+  }
+  if (action === "promote" || action === "rollback") {
+    return operation(action, { surface_id: id }, surface, {
+      ok: false,
+      state: "unsupported_surface_action",
+      reason: `${action}_is_plugin_candidate_lifecycle`,
+      evidence: ["surface action did not execute a process command"],
+    }, actor);
+  }
+  let command = null;
+  if (action === "stop") command = surface.stop;
+  else if (action === "start") command = surface.start;
+  else if (action === "restart") command = surface.restart;
+  else if (action === "reconcile") command = surface.enabled === false ? surface.stop : (surface.restart || surface.start);
+  if (!command || command.length === 0) {
+    return operation(action, { surface_id: id }, surface, { ok: false, state: "command_missing" }, actor);
+  }
+  const execute = (selectedCommand) => {
+    const [cmd, ...args] = selectedCommand;
+    return spawnSync(cmd, args, {
+      cwd: surface.cwd || undefined,
+      env: { ...process.env, CLAUTH_PM2_HOME: getClauthPm2Home(), PM2_HOME: getClauthPm2Home() },
+      windowsHide: true,
+      encoding: "utf8",
+      timeout: Number(surface.timeoutMs || 30000),
+    });
+  };
+  let result = execute(command);
+  let fallbackUsed = false;
+  // PM2 restart returns non-zero when the process was deleted. Reconcile is
+  // allowed to fall back to the declared start command; explicit restart keeps
+  // its strict failure semantics for operator-requested actions.
+  if (action === "reconcile" && result.status !== 0 && Array.isArray(surface.start) && surface.start.length > 0 && command !== surface.start) {
+    const restartStatus = result.status;
+    result = execute(surface.start);
+    fallbackUsed = true;
+    result.stderr = `restart exited ${restartStatus}; start fallback attempted\n${result.stderr || ""}`;
+  }
+  return operation(action, { surface_id: id }, surface, {
+    ok: result.status === 0,
+    state: result.status === 0 ? "operation_completed" : "operation_failed",
+    status: result.status,
+    stderr: result.stderr?.slice(0, 2000),
+    evidence: [`CLAUTH_PM2_HOME=${getClauthPm2Home()}`, ...(fallbackUsed ? ["reconcile_start_fallback=true"] : [])],
+  }, actor);
+}
+
+export function addTunnelRoute(tunnelId, route, actor = "localhost") {
+  const tunnels = listTunnels();
+  const tunnel = tunnels.find((item) => item.id === tunnelId);
+  const prior = tunnel || { id: tunnelId, provider: "cloudflare", routes: [] };
+  const routeId = String(route?.routeId || route?.id || crypto.randomUUID());
+  const nextRoute = {
+    id: routeId,
+    hostname: String(route?.hostname || "").trim(),
+    service_url: String(route?.service_url || route?.serviceUrl || "").trim(),
+    desired_state: "enabled",
+    public_route: true,
+  };
+  if (!nextRoute.hostname || !nextRoute.service_url) {
+    return operation("tunnel_route_add", { tunnel_id: tunnelId }, prior, { ok: false, state: "invalid_route" }, actor);
+  }
+  const nextTunnel = { ...prior, routes: [nextRoute, ...(prior.routes || []).filter((item) => item.id !== routeId)] };
+  writeTunnels([nextTunnel, ...tunnels.filter((item) => item.id !== tunnelId)]);
+  return operation("tunnel_route_add", { tunnel_id: tunnelId, route_id: routeId }, prior, { ok: true, state: "route_recorded", route: nextRoute }, actor);
+}
+
+export function removeTunnelRoute(tunnelId, routeId, actor = "localhost") {
+  const tunnels = listTunnels();
+  const tunnel = tunnels.find((item) => item.id === tunnelId);
+  if (!tunnel) return operation("tunnel_route_remove", { tunnel_id: tunnelId, route_id: routeId }, {}, { ok: false, state: "tunnel_not_found" }, actor);
+  const prior = tunnel;
+  const nextTunnel = { ...tunnel, routes: (tunnel.routes || []).filter((item) => item.id !== routeId) };
+  writeTunnels([nextTunnel, ...tunnels.filter((item) => item.id !== tunnelId)]);
+  return operation("tunnel_route_remove", { tunnel_id: tunnelId, route_id: routeId }, prior, { ok: true, state: "route_removed", route_id: routeId }, actor);
+}
+
+export function supervisorHealth() {
+  const state = loadSupervisorState();
+  return {
+    status: "ok",
+    port: getSupervisorPort(),
+    schema: "clauth.supervisor.v1",
+    pm2_home: getClauthPm2Home(),
+    plugins: (state.plugins || []).length,
+    surfaces: (state.surfaces || []).length,
+    operations: (state.operations || []).length,
+  };
+}