@lifeaitools/clauth 1.30.23 → 1.30.24

package/cli/supervisor-registry.test.js

@@ -1,397 +1,397 @@
-import assert from "node:assert/strict";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import test from "node:test";
-
-import {
-  addTunnelRoute,
-  discoverPlugins,
-  getClauthPm2Home,
-  listPlugins,
-  listSurfaces,
-  reconcileSurfaceHealth,
-  runPluginAction,
-  runSurfaceAction,
-  removeTunnelRoute,
-  setPluginEnabled,
-  supervisorHealth,
-  validatePluginManifest,
-} from "./supervisor-registry.js";
-import { isLoopbackAddress, supervisorLogDto, supervisorRequiresWriteToken } from "./commands/serve.js";
-
-function withTempSupervisor(fn) {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-supervisor-"));
-  const oldDir = process.env.CLAUTH_SUPERVISOR_DIR;
-  const oldManaged = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-  const oldUser = process.env.CLAUTH_USER_PLUGIN_ROOTS;
-  const oldPm2 = process.env.CLAUTH_PM2_HOME;
-  process.env.CLAUTH_SUPERVISOR_DIR = root;
-  delete process.env.CLAUTH_PM2_HOME;
-  try {
-    return fn(root);
-  } finally {
-    if (oldDir === undefined) delete process.env.CLAUTH_SUPERVISOR_DIR;
-    else process.env.CLAUTH_SUPERVISOR_DIR = oldDir;
-    if (oldManaged === undefined) delete process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-    else process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = oldManaged;
-    if (oldUser === undefined) delete process.env.CLAUTH_USER_PLUGIN_ROOTS;
-    else process.env.CLAUTH_USER_PLUGIN_ROOTS = oldUser;
-    if (oldPm2 === undefined) delete process.env.CLAUTH_PM2_HOME;
-    else process.env.CLAUTH_PM2_HOME = oldPm2;
-    fs.rmSync(root, { recursive: true, force: true });
-  }
-}
-
-function writePlugin(root, source, id, manifest) {
-  const dir = path.join(root, source, id);
-  fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(path.join(dir, "clauth-plugin.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-  return dir;
-}
-
-function baseManifest(id, overrides = {}) {
-  return {
-    schema: "lifeai.plugin.v1",
-    id,
-    version: "1.0.0",
-    publisher: "LIFEAI",
-    credentials: [{ name: `${id}-secret`, key_type: "secret", description: "fixture key" }],
-    surfaces: [{
-      id: `${id}-surface`,
-      destination: "local/clauth/pm2",
-      lifecycle_owner: "clauth",
-      port: 39111,
-      health: "/health",
-      restart: ["node", "--version"],
-    }],
-    test: { command: ["node", "--version"], port: "auto", health: "/health", selfTest: [["node", "--version"]] },
-    documentation: {
-      architecture: "docs/systems/example/ARCHITECTURE.md",
-      operator_guide: "docs/systems/example/OPERATE.md",
-      tool_reference: ".claude/context/mcp-endpoint-design.md",
-    },
-    ...overrides,
-  };
-}
-
-test("validatePluginManifest accepts LIFEAI plugin contract with isolated test context", () => {
-  const plugin = validatePluginManifest(baseManifest("regen-media-local"), "clauth-plugin.json");
-  assert.equal(plugin.schema, "lifeai.plugin.v1");
-  assert.equal(plugin.test.port, "auto");
-  assert.equal(plugin.surfaces[0].destination, "local/clauth/pm2");
-  assert.equal(plugin.surfaces[0].lifecycle_owner, "clauth");
-  assert.equal(plugin.surfaces[0].health, "http://127.0.0.1:39111/health");
-  assert.equal(plugin.documentation.architecture, "docs/systems/example/ARCHITECTURE.md");
-  assert.equal(plugin.documentation.operator_guide, "docs/systems/example/OPERATE.md");
-});
-
-test("validatePluginManifest accepts empty test command arrays from the v1 template", () => {
-  const plugin = validatePluginManifest(baseManifest("empty-test-command", {
-    test: { command: [], port: "auto", health: "/health", selfTest: [] },
-  }), "clauth-plugin.json");
-  assert.deepEqual(plugin.test.command, []);
-  assert.equal(plugin.test.port, "auto");
-});
-
-test("validatePluginManifest rejects invalid manifests and non-local health URLs", () => {
-  assert.throws(() => validatePluginManifest({ ...baseManifest("bad"), schema: "bad" }), /schema/);
-  assert.throws(() => validatePluginManifest(baseManifest("bad", {
-    surfaces: [{ id: "bad", health: "https://example.com/health" }],
-  })), /localhost-only/);
-  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
-    documentation: { architecture: "../outside.md" },
-  })), /repository-relative/);
-  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
-    documentation: { operator_guide: "docs/guide.md" },
-  })), /documentation.architecture is required/);
-  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
-    documentation: { architecture: "https://example.com/architecture.md" },
-  })), /repository-relative/);
-});
-
-test("discovery merges managed and user roots without silent managed-id shadowing", () => withTempSupervisor((root) => {
-  const managed = path.join(root, "managed");
-  const user = path.join(root, "user");
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = user;
-  writePlugin(root, "managed", "regen-media-local", baseManifest("regen-media-local"));
-  writePlugin(root, "user", "regen-media-local", baseManifest("regen-media-local", { version: "2.0.0" }));
-
-  const result = discoverPlugins();
-  const managedPlugin = result.plugins.find((plugin) => plugin.id === "regen-media-local" && plugin.source === "managed");
-  const invalid = result.plugins.find((plugin) => plugin.id === "regen-media-local" && plugin.source === "user");
-  assert.equal(managedPlugin.state, "awaiting_enable");
-  assert.equal(invalid.state, "manifest_invalid");
-  assert.match(invalid.error, /shadow/);
-}));
-
-test("trusted managed core plugins auto-enable while user plugins remain opt-in", () => withTempSupervisor((root) => {
-  const managed = path.join(root, "managed");
-  const user = path.join(root, "user");
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = user;
-  writePlugin(root, "managed", "core-mcp", baseManifest("core-mcp", { core: true, enable_default: true }));
-  writePlugin(root, "user", "user-mcp", baseManifest("user-mcp", { core: true, enable_default: true }));
-
-  const result = discoverPlugins();
-  const core = result.plugins.find((plugin) => plugin.id === "core-mcp");
-  const userPlugin = result.plugins.find((plugin) => plugin.id === "user-mcp");
-  assert.equal(core.enabled, true);
-  assert.equal(core.state, "current");
-  assert.equal(result.events.some((event) => event.kind === "core_plugin_auto_enabled" && event.plugin_id === "core-mcp"), true);
-  assert.equal(userPlugin.enabled, false);
-  assert.equal(userPlugin.state, "awaiting_enable");
-}));
-
-test("plugin test marks a private candidate and never creates a public route", () => withTempSupervisor((root) => {
-  const managed = path.join(root, "managed");
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
-  writePlugin(root, "managed", "regen-media-local", baseManifest("regen-media-local"));
-  discoverPlugins();
-
-  const enabled = setPluginEnabled("regen-media-local", true);
-  assert.equal(enabled.resulting_state.enabled, true);
-  const receipt = runPluginAction("regen-media-local", "test");
-  assert.equal(receipt.resulting_state.state, "candidate_testing");
-  assert.equal(receipt.resulting_state.public_route, false);
-  assert.equal(listPlugins().find((plugin) => plugin.id === "regen-media-local").candidate.public_route, false);
-}));
-
-test("surface actions use dedicated clauth PM2 home and keep CodeFlow observe-only", () => withTempSupervisor((root) => {
-  const managed = path.join(root, "managed");
-  process.env.REGEN_ROOT = "C:/Dev/regen-root";
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
-  writePlugin(root, "managed", "demo", baseManifest("demo", {
-    surfaces: [{
-      id: "demo-surface",
-      name: "Demo surface",
-      health: "http://127.0.0.1:3333/health",
-      cwd: "$REGEN_ROOT/mcp-servers/regen-media",
-      restart: [process.execPath, "--version"],
-    }],
-  }));
-  writePlugin(root, "managed", "codeflow", baseManifest("codeflow", {
-    surfaces: [{ id: "codeflow-mcp", lifecycle_owner: "clauth", destination: "local/clauth/pm2", restart: ["node", "--version"] }],
-  }));
-  discoverPlugins();
-  const receipt = runSurfaceAction("demo:demo-surface", "restart");
-  assert.equal(receipt.resulting_state.ok, true);
-  assert.match(receipt.resulting_state.evidence[0], /CLAUTH_PM2_HOME/);
-  assert.equal(receipt.prior_state.cwd.replace(/\\/g, "/"), "C:/Dev/regen-root/mcp-servers/regen-media");
-  assert.equal(getClauthPm2Home(), path.join(root, "pm2-home"));
-
-  const codeflow = runSurfaceAction("codeflow:codeflow-mcp", "restart");
-  assert.equal(codeflow.resulting_state.ok, false);
-  assert.equal(codeflow.resulting_state.reason, "codeflow_self_owned");
-  assert.equal(listSurfaces().length, 2);
-  assert.equal(supervisorHealth().surfaces, 2);
-}));
-
-test("reconcile falls back to the declared start command when restart reports a missing process", () => withTempSupervisor((root) => {
-  const managed = path.join(root, "managed");
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
-  writePlugin(root, "managed", "fallback-demo", baseManifest("fallback-demo", {
-    core: true,
-    enable_default: true,
-    surfaces: [{
-      id: "primary",
-      destination: "local/clauth/pm2",
-      lifecycle_owner: "clauth",
-      port: 39114,
-      health: "/health",
-      start: [process.execPath, "--version"],
-      restart: [process.execPath, "-e", "process.exit(1)"],
-    }],
-  }));
-  discoverPlugins();
-  const receipt = runSurfaceAction("fallback-demo:primary", "reconcile");
-  assert.equal(receipt.resulting_state.ok, true);
-  assert.equal(receipt.resulting_state.evidence.includes("reconcile_start_fallback=true"), true);
-}));
-
-test("surface promote and rollback never fall through to restart commands", () => withTempSupervisor((root) => {
-  const managed = path.join(root, "managed");
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
-  writePlugin(root, "managed", "demo", baseManifest("demo", {
-    surfaces: [{
-      id: "demo-surface",
-      name: "Demo surface",
-      health: "http://127.0.0.1:3333/health",
-      restart: [process.execPath, "--version"],
-    }],
-  }));
-  discoverPlugins();
-
-  for (const action of ["promote", "rollback"]) {
-    const receipt = runSurfaceAction("demo:demo-surface", action);
-    assert.equal(receipt.resulting_state.ok, false);
-    assert.equal(receipt.resulting_state.state, "unsupported_surface_action");
-    assert.equal(receipt.resulting_state.evidence[0], "surface action did not execute a process command");
-  }
-}));
-
-test("health reconciliation marks a failed clauth surface and repairs it through reconcile", async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-supervisor-health-"));
-  const oldDir = process.env.CLAUTH_SUPERVISOR_DIR;
-  const oldManaged = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-  const oldUser = process.env.CLAUTH_USER_PLUGIN_ROOTS;
-  process.env.CLAUTH_SUPERVISOR_DIR = root;
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed");
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
-  try {
-    writePlugin(root, "managed", "health-demo", baseManifest("health-demo", {
-      core: true,
-      enable_default: true,
-      surfaces: [{
-        id: "primary",
-        destination: "local/clauth/pm2",
-        lifecycle_owner: "clauth",
-        port: 39111,
-        health: "/health",
-        restart: [process.execPath, "--version"],
-      }],
-    }));
-    discoverPlugins();
-    let healthCalls = 0;
-    const result = await reconcileSurfaceHealth({
-      fetchImpl: async () => ({ ok: ++healthCalls > 1, status: 503 }),
-    });
-    assert.equal(result.inspected[0].surface_id, "health-demo:primary");
-    assert.equal(result.inspected[0].state, "reconciled");
-    const surface = listSurfaces().find((item) => item.plugin_id === "health-demo");
-    assert.equal(surface.state, "current");
-    assert.ok(surface.last_reconcile_operation_id);
-    assert.equal(healthCalls, 2);
-  } finally {
-    if (oldDir === undefined) delete process.env.CLAUTH_SUPERVISOR_DIR;
-    else process.env.CLAUTH_SUPERVISOR_DIR = oldDir;
-    if (oldManaged === undefined) delete process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-    else process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = oldManaged;
-    if (oldUser === undefined) delete process.env.CLAUTH_USER_PLUGIN_ROOTS;
-    else process.env.CLAUTH_USER_PLUGIN_ROOTS = oldUser;
-    fs.rmSync(root, { recursive: true, force: true });
-  }
-});
-
-test("health reconciliation does not claim current when a successful command leaves health down", async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-supervisor-post-health-"));
-  const oldDir = process.env.CLAUTH_SUPERVISOR_DIR;
-  const oldManaged = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-  const oldUser = process.env.CLAUTH_USER_PLUGIN_ROOTS;
-  process.env.CLAUTH_SUPERVISOR_DIR = root;
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed");
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
-  try {
-    writePlugin(root, "managed", "post-health-demo", baseManifest("post-health-demo", {
-      core: true,
-      enable_default: true,
-      surfaces: [{ id: "primary", destination: "local/clauth/pm2", lifecycle_owner: "clauth", port: 39113, health: "/health", restart: [process.execPath, "--version"] }],
-    }));
-    discoverPlugins();
-    const result = await reconcileSurfaceHealth({ fetchImpl: async () => ({ ok: false, status: 503 }) });
-    assert.equal(result.inspected[0].state, "reconcile_failed");
-    assert.equal(listSurfaces()[0].state, "unavailable");
-    assert.equal(listSurfaces()[0].last_health_ok, false);
-  } finally {
-    if (oldDir === undefined) delete process.env.CLAUTH_SUPERVISOR_DIR;
-    else process.env.CLAUTH_SUPERVISOR_DIR = oldDir;
-    if (oldManaged === undefined) delete process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-    else process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = oldManaged;
-    if (oldUser === undefined) delete process.env.CLAUTH_USER_PLUGIN_ROOTS;
-    else process.env.CLAUTH_USER_PLUGIN_ROOTS = oldUser;
-    fs.rmSync(root, { recursive: true, force: true });
-  }
-});
-
-test("health reconciliation never restarts external or plugin-owned surfaces", async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-supervisor-observe-"));
-  const oldDir = process.env.CLAUTH_SUPERVISOR_DIR;
-  const oldManaged = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-  const oldUser = process.env.CLAUTH_USER_PLUGIN_ROOTS;
-  process.env.CLAUTH_SUPERVISOR_DIR = root;
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed");
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
-  try {
-    writePlugin(root, "managed", "external-demo", baseManifest("external-demo", {
-      core: true,
-      enable_default: true,
-      destination: "vultr/clauth/pm2",
-      lifecycle_owner: "external",
-      surfaces: [{ id: "primary", destination: "vultr/clauth/pm2", lifecycle_owner: "external", port: 39112, health: "/health" }],
-    }));
-    discoverPlugins();
-    const result = await reconcileSurfaceHealth({ fetchImpl: async () => ({ ok: false, status: 503 }) });
-    assert.deepEqual(result.inspected, []);
-    assert.equal(listSurfaces()[0].state, "current");
-  } finally {
-    if (oldDir === undefined) delete process.env.CLAUTH_SUPERVISOR_DIR;
-    else process.env.CLAUTH_SUPERVISOR_DIR = oldDir;
-    if (oldManaged === undefined) delete process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-    else process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = oldManaged;
-    if (oldUser === undefined) delete process.env.CLAUTH_USER_PLUGIN_ROOTS;
-    else process.env.CLAUTH_USER_PLUGIN_ROOTS = oldUser;
-    fs.rmSync(root, { recursive: true, force: true });
-  }
-});
-
-test("supervisor write-token policy is temporarily relaxed only for the localhost supervisor port", () => {
-  assert.equal(supervisorRequiresWriteToken(52439, {}), false);
-  assert.equal(supervisorRequiresWriteToken(52439, { CLAUTH_SUPERVISOR_REQUIRE_WRITE_TOKEN: "1" }), true);
-  assert.equal(supervisorRequiresWriteToken(52437, {}), true);
-  assert.equal(isLoopbackAddress("127.0.0.1"), true);
-  assert.equal(isLoopbackAddress("::1"), true);
-  assert.equal(isLoopbackAddress("::ffff:127.0.0.1"), true);
-  assert.equal(isLoopbackAddress("192.168.1.25"), false);
-});
-
-test("supervisor log DTO strips raw operation payloads", () => {
-  const dto = supervisorLogDto({
-    ts: "2026-07-30T00:00:00.000Z",
-    kind: "operation",
-    operationId: "op-secret",
-    actor: "localhost",
-    action: "restart",
-    target: { surface_id: "demo", command: ["node", "--token=secret"] },
-    prior_state: { start: ["node", "--token=secret"], cwd: "C:/secrets" },
-    resulting_state: {
-      ok: false,
-      state: "operation_failed",
-      stderr: "SECRET=abc123",
-      evidence: ["CLAUTH_PM2_HOME=C:/safe"],
-    },
-    stderr: "SECRET=abc123",
-    completed_at: "2026-07-30T00:00:01.000Z",
-  });
-
-  const json = JSON.stringify(dto);
-  assert.equal(dto.operationId, "op-secret");
-  assert.equal(dto.target.surface_id, "demo");
-  assert.equal(dto.resulting_state.state, "operation_failed");
-  assert.equal(json.includes("prior_state"), false);
-  assert.equal(json.includes("stderr"), false);
-  assert.equal(json.includes("SECRET"), false);
-  assert.equal(json.includes("--token"), false);
-});
-
-test("tunnel route add and remove produce reversible operation receipts", () => withTempSupervisor((root) => {
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed");
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
-  discoverPlugins();
-
-  const added = addTunnelRoute("cf-main", {
-    id: "route-1",
-    hostname: "media.example.test",
-    service_url: "http://127.0.0.1:3120",
-  });
-  assert.equal(added.resulting_state.ok, true);
-  assert.equal(added.resulting_state.state, "route_recorded");
-
-  const removed = removeTunnelRoute("cf-main", "route-1");
-  assert.equal(removed.resulting_state.ok, true);
-  assert.equal(removed.resulting_state.state, "route_removed");
-}));
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  addTunnelRoute,
+  discoverPlugins,
+  getClauthPm2Home,
+  listPlugins,
+  listSurfaces,
+  reconcileSurfaceHealth,
+  runPluginAction,
+  runSurfaceAction,
+  removeTunnelRoute,
+  setPluginEnabled,
+  supervisorHealth,
+  validatePluginManifest,
+} from "./supervisor-registry.js";
+import { isLoopbackAddress, supervisorLogDto, supervisorRequiresWriteToken } from "./commands/serve.js";
+
+function withTempSupervisor(fn) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-supervisor-"));
+  const oldDir = process.env.CLAUTH_SUPERVISOR_DIR;
+  const oldManaged = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+  const oldUser = process.env.CLAUTH_USER_PLUGIN_ROOTS;
+  const oldPm2 = process.env.CLAUTH_PM2_HOME;
+  process.env.CLAUTH_SUPERVISOR_DIR = root;
+  delete process.env.CLAUTH_PM2_HOME;
+  try {
+    return fn(root);
+  } finally {
+    if (oldDir === undefined) delete process.env.CLAUTH_SUPERVISOR_DIR;
+    else process.env.CLAUTH_SUPERVISOR_DIR = oldDir;
+    if (oldManaged === undefined) delete process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+    else process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = oldManaged;
+    if (oldUser === undefined) delete process.env.CLAUTH_USER_PLUGIN_ROOTS;
+    else process.env.CLAUTH_USER_PLUGIN_ROOTS = oldUser;
+    if (oldPm2 === undefined) delete process.env.CLAUTH_PM2_HOME;
+    else process.env.CLAUTH_PM2_HOME = oldPm2;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function writePlugin(root, source, id, manifest) {
+  const dir = path.join(root, source, id);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, "clauth-plugin.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return dir;
+}
+
+function baseManifest(id, overrides = {}) {
+  return {
+    schema: "lifeai.plugin.v1",
+    id,
+    version: "1.0.0",
+    publisher: "LIFEAI",
+    credentials: [{ name: `${id}-secret`, key_type: "secret", description: "fixture key" }],
+    surfaces: [{
+      id: `${id}-surface`,
+      destination: "local/clauth/pm2",
+      lifecycle_owner: "clauth",
+      port: 39111,
+      health: "/health",
+      restart: ["node", "--version"],
+    }],
+    test: { command: ["node", "--version"], port: "auto", health: "/health", selfTest: [["node", "--version"]] },
+    documentation: {
+      architecture: "docs/systems/example/ARCHITECTURE.md",
+      operator_guide: "docs/systems/example/OPERATE.md",
+      tool_reference: ".claude/context/mcp-endpoint-design.md",
+    },
+    ...overrides,
+  };
+}
+
+test("validatePluginManifest accepts LIFEAI plugin contract with isolated test context", () => {
+  const plugin = validatePluginManifest(baseManifest("regen-media-local"), "clauth-plugin.json");
+  assert.equal(plugin.schema, "lifeai.plugin.v1");
+  assert.equal(plugin.test.port, "auto");
+  assert.equal(plugin.surfaces[0].destination, "local/clauth/pm2");
+  assert.equal(plugin.surfaces[0].lifecycle_owner, "clauth");
+  assert.equal(plugin.surfaces[0].health, "http://127.0.0.1:39111/health");
+  assert.equal(plugin.documentation.architecture, "docs/systems/example/ARCHITECTURE.md");
+  assert.equal(plugin.documentation.operator_guide, "docs/systems/example/OPERATE.md");
+});
+
+test("validatePluginManifest accepts empty test command arrays from the v1 template", () => {
+  const plugin = validatePluginManifest(baseManifest("empty-test-command", {
+    test: { command: [], port: "auto", health: "/health", selfTest: [] },
+  }), "clauth-plugin.json");
+  assert.deepEqual(plugin.test.command, []);
+  assert.equal(plugin.test.port, "auto");
+});
+
+test("validatePluginManifest rejects invalid manifests and non-local health URLs", () => {
+  assert.throws(() => validatePluginManifest({ ...baseManifest("bad"), schema: "bad" }), /schema/);
+  assert.throws(() => validatePluginManifest(baseManifest("bad", {
+    surfaces: [{ id: "bad", health: "https://example.com/health" }],
+  })), /localhost-only/);
+  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
+    documentation: { architecture: "../outside.md" },
+  })), /repository-relative/);
+  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
+    documentation: { operator_guide: "docs/guide.md" },
+  })), /documentation.architecture is required/);
+  assert.throws(() => validatePluginManifest(baseManifest("bad-docs", {
+    documentation: { architecture: "https://example.com/architecture.md" },
+  })), /repository-relative/);
+});
+
+test("discovery merges managed and user roots without silent managed-id shadowing", () => withTempSupervisor((root) => {
+  const managed = path.join(root, "managed");
+  const user = path.join(root, "user");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = user;
+  writePlugin(root, "managed", "regen-media-local", baseManifest("regen-media-local"));
+  writePlugin(root, "user", "regen-media-local", baseManifest("regen-media-local", { version: "2.0.0" }));
+
+  const result = discoverPlugins();
+  const managedPlugin = result.plugins.find((plugin) => plugin.id === "regen-media-local" && plugin.source === "managed");
+  const invalid = result.plugins.find((plugin) => plugin.id === "regen-media-local" && plugin.source === "user");
+  assert.equal(managedPlugin.state, "awaiting_enable");
+  assert.equal(invalid.state, "manifest_invalid");
+  assert.match(invalid.error, /shadow/);
+}));
+
+test("trusted managed core plugins auto-enable while user plugins remain opt-in", () => withTempSupervisor((root) => {
+  const managed = path.join(root, "managed");
+  const user = path.join(root, "user");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = user;
+  writePlugin(root, "managed", "core-mcp", baseManifest("core-mcp", { core: true, enable_default: true }));
+  writePlugin(root, "user", "user-mcp", baseManifest("user-mcp", { core: true, enable_default: true }));
+
+  const result = discoverPlugins();
+  const core = result.plugins.find((plugin) => plugin.id === "core-mcp");
+  const userPlugin = result.plugins.find((plugin) => plugin.id === "user-mcp");
+  assert.equal(core.enabled, true);
+  assert.equal(core.state, "current");
+  assert.equal(result.events.some((event) => event.kind === "core_plugin_auto_enabled" && event.plugin_id === "core-mcp"), true);
+  assert.equal(userPlugin.enabled, false);
+  assert.equal(userPlugin.state, "awaiting_enable");
+}));
+
+test("plugin test marks a private candidate and never creates a public route", () => withTempSupervisor((root) => {
+  const managed = path.join(root, "managed");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  writePlugin(root, "managed", "regen-media-local", baseManifest("regen-media-local"));
+  discoverPlugins();
+
+  const enabled = setPluginEnabled("regen-media-local", true);
+  assert.equal(enabled.resulting_state.enabled, true);
+  const receipt = runPluginAction("regen-media-local", "test");
+  assert.equal(receipt.resulting_state.state, "candidate_testing");
+  assert.equal(receipt.resulting_state.public_route, false);
+  assert.equal(listPlugins().find((plugin) => plugin.id === "regen-media-local").candidate.public_route, false);
+}));
+
+test("surface actions use dedicated clauth PM2 home and keep CodeFlow observe-only", () => withTempSupervisor((root) => {
+  const managed = path.join(root, "managed");
+  process.env.REGEN_ROOT = "C:/Dev/regen-root";
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  writePlugin(root, "managed", "demo", baseManifest("demo", {
+    surfaces: [{
+      id: "demo-surface",
+      name: "Demo surface",
+      health: "http://127.0.0.1:3333/health",
+      cwd: "$REGEN_ROOT/mcp-servers/regen-media",
+      restart: [process.execPath, "--version"],
+    }],
+  }));
+  writePlugin(root, "managed", "codeflow", baseManifest("codeflow", {
+    surfaces: [{ id: "codeflow-mcp", lifecycle_owner: "clauth", destination: "local/clauth/pm2", restart: ["node", "--version"] }],
+  }));
+  discoverPlugins();
+  const receipt = runSurfaceAction("demo:demo-surface", "restart");
+  assert.equal(receipt.resulting_state.ok, true);
+  assert.match(receipt.resulting_state.evidence[0], /CLAUTH_PM2_HOME/);
+  assert.equal(receipt.prior_state.cwd.replace(/\\/g, "/"), "C:/Dev/regen-root/mcp-servers/regen-media");
+  assert.equal(getClauthPm2Home(), path.join(root, "pm2-home"));
+
+  const codeflow = runSurfaceAction("codeflow:codeflow-mcp", "restart");
+  assert.equal(codeflow.resulting_state.ok, false);
+  assert.equal(codeflow.resulting_state.reason, "codeflow_self_owned");
+  assert.equal(listSurfaces().length, 2);
+  assert.equal(supervisorHealth().surfaces, 2);
+}));
+
+test("reconcile falls back to the declared start command when restart reports a missing process", () => withTempSupervisor((root) => {
+  const managed = path.join(root, "managed");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  writePlugin(root, "managed", "fallback-demo", baseManifest("fallback-demo", {
+    core: true,
+    enable_default: true,
+    surfaces: [{
+      id: "primary",
+      destination: "local/clauth/pm2",
+      lifecycle_owner: "clauth",
+      port: 39114,
+      health: "/health",
+      start: [process.execPath, "--version"],
+      restart: [process.execPath, "-e", "process.exit(1)"],
+    }],
+  }));
+  discoverPlugins();
+  const receipt = runSurfaceAction("fallback-demo:primary", "reconcile");
+  assert.equal(receipt.resulting_state.ok, true);
+  assert.equal(receipt.resulting_state.evidence.includes("reconcile_start_fallback=true"), true);
+}));
+
+test("surface promote and rollback never fall through to restart commands", () => withTempSupervisor((root) => {
+  const managed = path.join(root, "managed");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  writePlugin(root, "managed", "demo", baseManifest("demo", {
+    surfaces: [{
+      id: "demo-surface",
+      name: "Demo surface",
+      health: "http://127.0.0.1:3333/health",
+      restart: [process.execPath, "--version"],
+    }],
+  }));
+  discoverPlugins();
+
+  for (const action of ["promote", "rollback"]) {
+    const receipt = runSurfaceAction("demo:demo-surface", action);
+    assert.equal(receipt.resulting_state.ok, false);
+    assert.equal(receipt.resulting_state.state, "unsupported_surface_action");
+    assert.equal(receipt.resulting_state.evidence[0], "surface action did not execute a process command");
+  }
+}));
+
+test("health reconciliation marks a failed clauth surface and repairs it through reconcile", async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-supervisor-health-"));
+  const oldDir = process.env.CLAUTH_SUPERVISOR_DIR;
+  const oldManaged = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+  const oldUser = process.env.CLAUTH_USER_PLUGIN_ROOTS;
+  process.env.CLAUTH_SUPERVISOR_DIR = root;
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed");
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  try {
+    writePlugin(root, "managed", "health-demo", baseManifest("health-demo", {
+      core: true,
+      enable_default: true,
+      surfaces: [{
+        id: "primary",
+        destination: "local/clauth/pm2",
+        lifecycle_owner: "clauth",
+        port: 39111,
+        health: "/health",
+        restart: [process.execPath, "--version"],
+      }],
+    }));
+    discoverPlugins();
+    let healthCalls = 0;
+    const result = await reconcileSurfaceHealth({
+      fetchImpl: async () => ({ ok: ++healthCalls > 1, status: 503 }),
+    });
+    assert.equal(result.inspected[0].surface_id, "health-demo:primary");
+    assert.equal(result.inspected[0].state, "reconciled");
+    const surface = listSurfaces().find((item) => item.plugin_id === "health-demo");
+    assert.equal(surface.state, "current");
+    assert.ok(surface.last_reconcile_operation_id);
+    assert.equal(healthCalls, 2);
+  } finally {
+    if (oldDir === undefined) delete process.env.CLAUTH_SUPERVISOR_DIR;
+    else process.env.CLAUTH_SUPERVISOR_DIR = oldDir;
+    if (oldManaged === undefined) delete process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+    else process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = oldManaged;
+    if (oldUser === undefined) delete process.env.CLAUTH_USER_PLUGIN_ROOTS;
+    else process.env.CLAUTH_USER_PLUGIN_ROOTS = oldUser;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("health reconciliation does not claim current when a successful command leaves health down", async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-supervisor-post-health-"));
+  const oldDir = process.env.CLAUTH_SUPERVISOR_DIR;
+  const oldManaged = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+  const oldUser = process.env.CLAUTH_USER_PLUGIN_ROOTS;
+  process.env.CLAUTH_SUPERVISOR_DIR = root;
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed");
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  try {
+    writePlugin(root, "managed", "post-health-demo", baseManifest("post-health-demo", {
+      core: true,
+      enable_default: true,
+      surfaces: [{ id: "primary", destination: "local/clauth/pm2", lifecycle_owner: "clauth", port: 39113, health: "/health", restart: [process.execPath, "--version"] }],
+    }));
+    discoverPlugins();
+    const result = await reconcileSurfaceHealth({ fetchImpl: async () => ({ ok: false, status: 503 }) });
+    assert.equal(result.inspected[0].state, "reconcile_failed");
+    assert.equal(listSurfaces()[0].state, "unavailable");
+    assert.equal(listSurfaces()[0].last_health_ok, false);
+  } finally {
+    if (oldDir === undefined) delete process.env.CLAUTH_SUPERVISOR_DIR;
+    else process.env.CLAUTH_SUPERVISOR_DIR = oldDir;
+    if (oldManaged === undefined) delete process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+    else process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = oldManaged;
+    if (oldUser === undefined) delete process.env.CLAUTH_USER_PLUGIN_ROOTS;
+    else process.env.CLAUTH_USER_PLUGIN_ROOTS = oldUser;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("health reconciliation never restarts external or plugin-owned surfaces", async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-supervisor-observe-"));
+  const oldDir = process.env.CLAUTH_SUPERVISOR_DIR;
+  const oldManaged = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+  const oldUser = process.env.CLAUTH_USER_PLUGIN_ROOTS;
+  process.env.CLAUTH_SUPERVISOR_DIR = root;
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed");
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  try {
+    writePlugin(root, "managed", "external-demo", baseManifest("external-demo", {
+      core: true,
+      enable_default: true,
+      destination: "vultr/clauth/pm2",
+      lifecycle_owner: "external",
+      surfaces: [{ id: "primary", destination: "vultr/clauth/pm2", lifecycle_owner: "external", port: 39112, health: "/health" }],
+    }));
+    discoverPlugins();
+    const result = await reconcileSurfaceHealth({ fetchImpl: async () => ({ ok: false, status: 503 }) });
+    assert.deepEqual(result.inspected, []);
+    assert.equal(listSurfaces()[0].state, "current");
+  } finally {
+    if (oldDir === undefined) delete process.env.CLAUTH_SUPERVISOR_DIR;
+    else process.env.CLAUTH_SUPERVISOR_DIR = oldDir;
+    if (oldManaged === undefined) delete process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+    else process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = oldManaged;
+    if (oldUser === undefined) delete process.env.CLAUTH_USER_PLUGIN_ROOTS;
+    else process.env.CLAUTH_USER_PLUGIN_ROOTS = oldUser;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("supervisor write-token policy is temporarily relaxed only for the localhost supervisor port", () => {
+  assert.equal(supervisorRequiresWriteToken(52439, {}), false);
+  assert.equal(supervisorRequiresWriteToken(52439, { CLAUTH_SUPERVISOR_REQUIRE_WRITE_TOKEN: "1" }), true);
+  assert.equal(supervisorRequiresWriteToken(52437, {}), true);
+  assert.equal(isLoopbackAddress("127.0.0.1"), true);
+  assert.equal(isLoopbackAddress("::1"), true);
+  assert.equal(isLoopbackAddress("::ffff:127.0.0.1"), true);
+  assert.equal(isLoopbackAddress("192.168.1.25"), false);
+});
+
+test("supervisor log DTO strips raw operation payloads", () => {
+  const dto = supervisorLogDto({
+    ts: "2026-07-30T00:00:00.000Z",
+    kind: "operation",
+    operationId: "op-secret",
+    actor: "localhost",
+    action: "restart",
+    target: { surface_id: "demo", command: ["node", "--token=secret"] },
+    prior_state: { start: ["node", "--token=secret"], cwd: "C:/secrets" },
+    resulting_state: {
+      ok: false,
+      state: "operation_failed",
+      stderr: "SECRET=abc123",
+      evidence: ["CLAUTH_PM2_HOME=C:/safe"],
+    },
+    stderr: "SECRET=abc123",
+    completed_at: "2026-07-30T00:00:01.000Z",
+  });
+
+  const json = JSON.stringify(dto);
+  assert.equal(dto.operationId, "op-secret");
+  assert.equal(dto.target.surface_id, "demo");
+  assert.equal(dto.resulting_state.state, "operation_failed");
+  assert.equal(json.includes("prior_state"), false);
+  assert.equal(json.includes("stderr"), false);
+  assert.equal(json.includes("SECRET"), false);
+  assert.equal(json.includes("--token"), false);
+});
+
+test("tunnel route add and remove produce reversible operation receipts", () => withTempSupervisor((root) => {
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed");
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  discoverPlugins();
+
+  const added = addTunnelRoute("cf-main", {
+    id: "route-1",
+    hostname: "media.example.test",
+    service_url: "http://127.0.0.1:3120",
+  });
+  assert.equal(added.resulting_state.ok, true);
+  assert.equal(added.resulting_state.state, "route_recorded");
+
+  const removed = removeTunnelRoute("cf-main", "route-1");
+  assert.equal(removed.resulting_state.ok, true);
+  assert.equal(removed.resulting_state.state, "route_removed");
+}));