npm - @lifeaitools/clauth - Versions diffs - 2.0.2 → 2.0.3 - Mend

@lifeaitools/clauth 2.0.2 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/cli/supervisor-registry.js +17 -0
package/cli/supervisor-registry.test.js +964 -926
package/package.json +1 -1

package/cli/supervisor-registry.test.js CHANGED Viewed

@@ -1,926 +1,964 @@
-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,
-  deregisterPlugin,
-  discoverPlugins,
-  getClauthPm2Home,
-  listPlugins,
-  listSurfaces,
-  reconcileSurfaceHealth,
-  registerPlugin,
-  runPluginAction,
-  runSurfaceAction,
-  removeTunnelRoute,
-  setPluginEnabled,
-  shellQuote,
-  supervisorHealth,
-  syncPluginsFromRepos,
-  SYNC_REPO_NAMES,
-  SYNC_SKIP_STATES,
-  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;
-  // CLAUTH_MANAGED_PLUGIN_ROOTS / CLAUTH_USER_PLUGIN_ROOTS are set as PERSISTENT
-  // MACHINE-LEVEL env vars on developer boxes, pointing at the LIVE daemon's
-  // plugin directories. rootEntries() prefers them over CLAUTH_SUPERVISOR_DIR,
-  // so overriding the supervisor dir ALONE leaves registerPlugin/deregisterPlugin
-  // writing to (and deleting from) the live fleet. Pin all three to the temp
-  // root here so a test cannot reach the live daemon by forgetting to.
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed-plugins");
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user-plugins");
-  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;
-}
-// A scoped npm package installs at <root>/@scope/pkg-name/clauth-plugin.json —
-// two levels deep, mirroring node_modules/@lifeaitools/<pkg>/.
-function writeScopedPlugin(root, source, scope, id, manifest) {
-  const dir = path.join(root, source, scope, 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("shellQuote quotes a whitespace-bearing value only when shell is active, and is idempotent", () => {
-  assert.equal(shellQuote("pm2", true), "pm2");
-  assert.equal(shellQuote("C:/Program Files/nodejs/node.exe", true), '"C:/Program Files/nodejs/node.exe"');
-  assert.equal(shellQuote("C:/Program Files/nodejs/node.exe", false), "C:/Program Files/nodejs/node.exe");
-  assert.equal(shellQuote("one two", false), "one two");
-  assert.equal(shellQuote('"already quoted value"', true), '"already quoted value"');
-});
-test("validatePluginManifest rejects shell metacharacters in command ARGS, not just command[0]", () => {
-  // The [;&|<>] guard on command[0] alone is defeated by moving the payload
-  // one index right — args must be validated the same way (verified live
-  // during code review: spawnSync(['cmd','/c','echo','A & echo INJECTED'],
-  // {shell:true}) executed a second command from inside one arg string).
-  assert.throws(() => validatePluginManifest(baseManifest("inject", {
-    surfaces: [{ id: "primary", lifecycle_owner: "clauth", restart: ["pm2", "start svc & calc.exe"] }],
-  })), /shell syntax/);
-  assert.throws(() => validatePluginManifest(baseManifest("inject2", {
-    surfaces: [{ id: "primary", lifecycle_owner: "clauth", restart: ["pm2", "restart", "name; rm -rf /"] }],
-  })), /shell syntax/);
-  // A legitimate arg with no shell metacharacters still passes.
-  const ok = validatePluginManifest(baseManifest("legit", {
-    surfaces: [{ id: "primary", lifecycle_owner: "clauth", restart: ["pm2", "restart", "my-app-name"] }],
-  }), "clauth-plugin.json");
-  assert.deepEqual(ok.surfaces[0].restart, ["pm2", "restart", "my-app-name"]);
-});
-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("discovery finds both a scoped npm-package layout and an unscoped layout from one root", () => 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");
-  // Unscoped: managed/plain-plugin/clauth-plugin.json (one level — existing behavior)
-  writePlugin(root, "managed", "plain-plugin", baseManifest("plain-plugin"));
-  // Scoped: managed/@lifeaitools/fs-mcp/clauth-plugin.json (two levels — the WP-1 fix)
-  writeScopedPlugin(root, "managed", "@lifeaitools", "fs-mcp", baseManifest("fs-mcp"));
-  const result = discoverPlugins();
-  const plain = result.plugins.find((plugin) => plugin.id === "plain-plugin");
-  const scoped = result.plugins.find((plugin) => plugin.id === "fs-mcp");
-  assert.ok(plain, "unscoped layout must still be discovered");
-  assert.equal(plain.state, "awaiting_enable");
-  assert.ok(scoped, "scoped @scope/pkg layout must now be discovered");
-  assert.equal(scoped.state, "awaiting_enable");
-  assert.equal(scoped.manifest_hash?.length > 0, true);
-}));
-test("discovery skips a malformed manifest without aborting the rest of the scan", () => 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", "good-plugin", baseManifest("good-plugin"));
-  const brokenDir = path.join(managed, "broken-plugin");
-  fs.mkdirSync(brokenDir, { recursive: true });
-  fs.writeFileSync(path.join(brokenDir, "clauth-plugin.json"), "{ this is not valid json", "utf8");
-  // Also prove a malformed SCOPED manifest doesn't abort the scoped-dir descent either.
-  const brokenScopedDir = path.join(managed, "@lifeaitools", "broken-scoped");
-  fs.mkdirSync(brokenScopedDir, { recursive: true });
-  fs.writeFileSync(path.join(brokenScopedDir, "clauth-plugin.json"), "{ also not valid json", "utf8");
-  writeScopedPlugin(root, "managed", "@lifeaitools", "good-scoped", baseManifest("good-scoped"));
-  const result = discoverPlugins();
-  const good = result.plugins.find((plugin) => plugin.id === "good-plugin");
-  const broken = result.plugins.find((plugin) => plugin.id === "broken-plugin");
-  const goodScoped = result.plugins.find((plugin) => plugin.id === "good-scoped");
-  const brokenScoped = result.plugins.find((plugin) => plugin.id === "broken-scoped");
-  assert.equal(good.state, "awaiting_enable");
-  assert.equal(broken.state, "manifest_invalid");
-  assert.equal(goodScoped.state, "awaiting_enable");
-  assert.equal(brokenScoped.state, "manifest_invalid");
-}));
-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 {
-    // Both fixtures are deliberately PROBE-ABLE — local destination + port, so
-    // healthUrlForSurface() yields a real URL for each. That is what gives this
-    // test teeth.
-    //
-    // An earlier revision made the external fixture `vultr/` with no port. It
-    // read as equivalent and was not: portless + relative health resolves to a
-    // null URL, so reconcileSurfaceHealth's `if (!url) continue` skipped it
-    // BEFORE the owner/destination guard was consulted. Delete the guard this
-    // test is named for and it still passed green — it proved the surface was
-    // unprobe-able, not that it was probe-able and correctly left alone.
-    //
-    // Now the ONLY thing that can exclude external-demo is lifecycle_owner, and
-    // clauth-owned-demo is the positive control proving the probe machinery
-    // actually runs against this fixture shape. If `inspected` ever comes back
-    // empty, the control failed and the negative result means nothing.
-    writePlugin(root, "managed", "external-demo", baseManifest("external-demo", {
-      core: true,
-      enable_default: true,
-      destination: "local/clauth/pm2",
-      lifecycle_owner: "external",
-      surfaces: [{ id: "primary", destination: "local/clauth/pm2", lifecycle_owner: "external", port: 39112, health: "/health" }],
-    }));
-    writePlugin(root, "managed", "clauth-owned-demo", baseManifest("clauth-owned-demo", {
-      core: true,
-      enable_default: true,
-      destination: "local/clauth/pm2",
-      lifecycle_owner: "clauth",
-      surfaces: [{ id: "primary", destination: "local/clauth/pm2", lifecycle_owner: "clauth", port: 39113, health: "/health" }],
-    }));
-    discoverPlugins();
-    const result = await reconcileSurfaceHealth({ fetchImpl: async () => ({ ok: false, status: 503 }) });
-    const inspectedIds = result.inspected.map((s) => (typeof s === "string" ? s : s.surface_id));
-    // Positive control: the probe machinery ran at all.
-    assert.ok(inspectedIds.some((id) => String(id).includes("clauth-owned-demo")),
-      `control failed — clauth-owned surface was not probed, so "external was skipped" proves nothing (inspected: ${JSON.stringify(result.inspected)})`);
-    // The actual assertion: an externally-owned surface is never touched.
-    assert.ok(!inspectedIds.some((id) => String(id).includes("external-demo")),
-      `external-demo was probed — the lifecycle_owner guard is not excluding it (inspected: ${JSON.stringify(result.inspected)})`);
-    const external = listSurfaces().find((s) => s.plugin_id === "external-demo");
-    assert.equal(external.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("registerPlugin validates, writes into the managed root, and discovers the plugin — idempotent on re-register", () => 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");
-  const sourceDir = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-register-source-"));
-  const manifestPath = path.join(sourceDir, "clauth-plugin.json");
-  fs.writeFileSync(manifestPath, JSON.stringify(baseManifest("registered-demo", { core: true, enable_default: true })), "utf8");
-  const first = registerPlugin(manifestPath, "test");
-  assert.equal(first.resulting_state.ok, true);
-  assert.equal(first.resulting_state.state, "registered");
-  assert.equal(first.resulting_state.plugin_state, "current");
-  const written = fs.existsSync(path.join(managed, "registered-demo", "clauth-plugin.json"));
-  assert.equal(written, true);
-  const found = listPlugins().find((plugin) => plugin.id === "registered-demo");
-  assert.equal(found.enabled, true);
-  const second = registerPlugin(manifestPath, "test");
-  assert.equal(second.resulting_state.state, "unchanged", "re-registering identical content must be a no-op, not a rewrite");
-  fs.rmSync(sourceDir, { recursive: true, force: true });
-}));
-test("registerPlugin rejects a plugin id that would escape the managed-plugins root", () => withTempSupervisor((root) => {
-  // Code-review finding (confidence 95, live PoC): manifest.id of ".." passed
-  // the old id regex (dot is in the allowed character class with no
-  // exclusion of all-dots forms) and path.join(managedRoot, "..") wrote
-  // clauth-plugin.json one level ABOVE the managed root. Two independent
-  // fixes now close this: the id regex rejects all-dots ids, and
-  // registerPlugin asserts containment at the write site so a future regex
-  // relaxation can't reopen it.
-  const managed = path.join(root, "managed");
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
-  const sourceDir = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-register-traversal-"));
-  const manifestPath = path.join(sourceDir, "clauth-plugin.json");
-  fs.writeFileSync(manifestPath, JSON.stringify({ schema: "lifeai.plugin.v1", id: "..", version: "1.0.0", publisher: "t", documentation: { architecture: "a.md" }, surfaces: [] }), "utf8");
-  const receipt = registerPlugin(manifestPath, "test");
-  assert.equal(receipt.resulting_state.ok, false);
-  assert.equal(receipt.resulting_state.state, "manifest_invalid");
-  const escapedPath = path.join(managed, "..", "clauth-plugin.json");
-  assert.equal(fs.existsSync(escapedPath), false, "must never write outside the managed-plugins root");
-  fs.rmSync(sourceDir, { recursive: true, force: true });
-}));
-test("validatePluginManifest rejects an all-dots plugin or surface id", () => {
-  assert.throws(() => validatePluginManifest(baseManifest("..", {}), "clauth-plugin.json"), /may not be all dots/);
-  assert.throws(() => validatePluginManifest(baseManifest("valid-id", {
-    surfaces: [{ id: ".", lifecycle_owner: "clauth" }],
-  }), "clauth-plugin.json"), /may not be all dots/);
-});
-test("registerPlugin rejects an invalid manifest without writing anything", () => 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");
-  const sourceDir = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-register-bad-"));
-  const manifestPath = path.join(sourceDir, "clauth-plugin.json");
-  fs.writeFileSync(manifestPath, JSON.stringify({ schema: "wrong", id: "bad" }), "utf8");
-  const receipt = registerPlugin(manifestPath, "test");
-  assert.equal(receipt.resulting_state.ok, false);
-  assert.equal(receipt.resulting_state.state, "manifest_invalid");
-  assert.equal(fs.existsSync(path.join(managed, "bad")), false);
-  fs.rmSync(sourceDir, { recursive: true, force: true });
-}));
-// Builds throwaway product repos laid out like the real ones, so a sync sweep
-// exercises the real relative manifest paths without reading a live checkout.
-function withTempProductRepos(fn) {
-  const base = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-sync-repos-"));
-  const regenRoot = path.join(base, "regen-root");
-  const rdcSkills = path.join(base, "rdc-skills");
-  const writeManifest = (repoRoot, relPath, manifest) => {
-    const full = path.join(repoRoot, relPath);
-    fs.mkdirSync(path.dirname(full), { recursive: true });
-    fs.writeFileSync(full, typeof manifest === "string" ? manifest : `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-    return full;
-  };
-  writeManifest(regenRoot, "packages/codeflow/clauth-plugin.json", baseManifest("codeflow-mcp"));
-  writeManifest(regenRoot, "apps/dev-center/clauth-plugin.json", baseManifest("dev-center"));
-  writeManifest(regenRoot, "mcp-servers/regen-media/clauth-plugin.json", baseManifest("regen-media"));
-  writeManifest(regenRoot, "mcp-servers/web-research/clauth-plugin.json", baseManifest("web-research"));
-  writeManifest(rdcSkills, "clauth-plugin.json", baseManifest("rdc-skills"));
-  try {
-    return fn({ base, regenRoot, rdcSkills, writeManifest, roots: { "regen-root": regenRoot, "rdc-skills": rdcSkills } });
-  } finally {
-    fs.rmSync(base, { recursive: true, force: true });
-  }
-}
-test("plugin sync inherits registerPlugin idempotence — a second sweep reports every manifest unchanged", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
-  const first = syncPluginsFromRepos(roots, "test");
-  assert.equal(first.length, 5, "one receipt per attempted manifest");
-  assert.deepEqual(
-    first.filter((entry) => !entry.ok).map((entry) => `${entry.repo}:${entry.state}`),
-    [],
-    "every manifest in a complete checkout must register",
-  );
-  assert.equal(first.every((entry) => entry.state === "registered"), true);
-  // registerPlugin sha256-compares before writing; sync must not defeat that by
-  // re-writing or re-hashing on its own.
-  const second = syncPluginsFromRepos(roots, "test");
-  assert.equal(second.length, 5);
-  assert.equal(second.every((entry) => entry.ok && entry.state === "unchanged"), true, "re-sweeping identical content must be a no-op");
-})));
-test("plugin sync warns and continues over a missing repo root instead of throwing", () => withTempSupervisor(() => withTempProductRepos(({ base, rdcSkills }) => {
-  // A box that never checked out regen-root must still sync what it does have.
-  const absent = path.join(base, "no-such-checkout");
-  assert.equal(fs.existsSync(absent), false);
-  let receipts;
-  assert.doesNotThrow(() => {
-    receipts = syncPluginsFromRepos({ "regen-root": absent, "rdc-skills": rdcSkills }, "test");
-  });
-  assert.equal(receipts.length, 5, "a skipped repo still yields a receipt per attempted manifest");
-  const missing = receipts.filter((entry) => entry.state === "repo_root_missing");
-  assert.equal(missing.length, 4, "all four regen-root manifests report the missing root");
-  assert.equal(missing.every((entry) => entry.ok === false), true);
-  const skills = receipts.find((entry) => entry.repo === "rdc-skills");
-  assert.equal(skills.ok, true);
-  assert.equal(skills.state, "registered");
-  assert.ok(listPlugins().find((plugin) => plugin.id === "rdc-skills"), "the reachable repo still registered");
-})));
-test("plugin sync registers the remaining manifests when one is malformed", () => withTempSupervisor(() => withTempProductRepos(({ regenRoot, roots, writeManifest }) => {
-  writeManifest(regenRoot, "apps/dev-center/clauth-plugin.json", "{ this is not valid json");
-  const receipts = syncPluginsFromRepos(roots, "test");
-  assert.equal(receipts.length, 5);
-  const bad = receipts.find((entry) => entry.path.includes("dev-center"));
-  assert.equal(bad.ok, false);
-  assert.equal(bad.state, "manifest_invalid");
-  const good = receipts.filter((entry) => entry !== bad);
-  assert.equal(good.length, 4);
-  assert.equal(good.every((entry) => entry.ok && entry.state === "registered"), true, "one bad manifest must not abort the sweep");
-  const ids = new Set(listPlugins().map((plugin) => plugin.id));
-  for (const id of ["codeflow-mcp", "regen-media", "web-research", "rdc-skills"]) {
-    assert.ok(ids.has(id), `${id} must still be registered`);
-  }
-})));
-test("deregisterPlugin removes only the named plugin and leaves siblings intact", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
-  syncPluginsFromRepos(roots, "test");
-  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-  assert.equal(fs.existsSync(path.join(managed, "web-research")), true);
-  const receipt = deregisterPlugin("web-research", "test");
-  assert.equal(receipt.resulting_state.ok, true);
-  assert.equal(receipt.resulting_state.state, "deregistered");
-  assert.equal(fs.existsSync(path.join(managed, "web-research")), false, "the named plugin directory is gone");
-  for (const sibling of ["codeflow-mcp", "dev-center", "regen-media", "rdc-skills"]) {
-    assert.equal(fs.existsSync(path.join(managed, sibling)), true, `${sibling} must survive`);
-  }
-  // discovery re-ran, so the removed managed plugin is reported missing, not current
-  const after = listPlugins().find((plugin) => plugin.id === "web-research");
-  assert.equal(after.state, "missing_default");
-  assert.equal(after.enabled, false);
-})));
-test("deregisterPlugin on an unregistered id is a safe no-op, not an error", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
-  syncPluginsFromRepos(roots, "test");
-  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-  const before = fs.readdirSync(managed).sort();
-  const receipt = deregisterPlugin("never-registered-plugin", "test");
-  assert.equal(receipt.resulting_state.ok, true, "a no-op is success, not failure");
-  assert.equal(receipt.resulting_state.state, "not_registered");
-  assert.deepEqual(fs.readdirSync(managed).sort(), before, "nothing else may be touched");
-})));
-test("deregisterPlugin rejects an id that would escape the managed-plugins root", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
-  // Mirrors the registerPlugin traversal test. The id here is raw CLI/HTTP
-  // input with no manifest validation upstream, and the operation DELETES
-  // recursively — so an id resolving to the root itself must reject too, which
-  // is where this is strictly stricter than registerPlugin's assertion.
-  syncPluginsFromRepos(roots, "test");
-  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-  const sentinel = path.join(managed, "..", "sentinel-outside-root.txt");
-  fs.writeFileSync(sentinel, "must survive", "utf8");
-  const before = fs.readdirSync(managed).sort();
-  const evilIds = [
-    "..", "../..", "../sentinel-outside-root.txt", "..\\..", "/etc", "", ".",
-    // These three are stopped by the CHARSET guard alone — the containment
-    // assert waves all of them through, because path.resolve() normalizes the
-    // `..` away and Windows re-anchors a drive-relative path, so each lands
-    // back INSIDE the root (measured during code review). They are pinned here
-    // so the two guards are independently tested and nobody "simplifies" the
-    // charset rule believing containment is a safety net for it.
-    "sub/../web-research",
-    "C:web-research",
-    "web-research::$DATA",
-  ];
-  for (const evil of evilIds) {
-    const receipt = deregisterPlugin(evil, "test");
-    assert.equal(receipt.resulting_state.ok, false, `id ${JSON.stringify(evil)} must be rejected`);
-    assert.equal(receipt.resulting_state.state, "invalid_plugin_id");
-  }
-  assert.equal(fs.existsSync(path.join(managed, "web-research")), true, "a charset-rejected alias must not have deleted the real plugin");
-  assert.equal(fs.existsSync(sentinel), true, "must never delete outside the managed-plugins root");
-  assert.equal(fs.existsSync(managed), true, "must never delete the managed-plugins root itself");
-  assert.deepEqual(fs.readdirSync(managed).sort(), before, "no registered plugin may be removed by a rejected id");
-})));
-test("validatePluginManifest rejects a port on any non-local destination, and keeps local ports", () => {
-  // A remote surface is reached by URL; its port is the deployment registry's
-  // fact. Copying it into the manifest creates a second home for one fact that
-  // then drifts (regen-media 3121 vs 3120, dev-center 3012 vs 3003). Worse, a
-  // ported remote surface makes localhostHealth() synthesize
-  // http://127.0.0.1:<port>/health for a service on another box, pointing the
-  // health reconciler at the wrong machine.
-  //
-  // The rule is keyed on the validated DESTINATION enum, never on the surface's
-  // free-text id/role — keying on the label was tried in review and failed both
-  // ways: renaming the surface bypassed it, and a local surface named "remote"
-  // was falsely rejected. Both directions are asserted below.
-  for (const destination of ["vultr/clauth/pm2", "coolify/clauth/docker"]) {
-    for (const port of [3110, "auto", 0]) {
-      assert.throws(() => validatePluginManifest(baseManifest("remote-port", {
-        surfaces: [{ id: "remote", destination, lifecycle_owner: "external", port }],
-      })), /must not declare a port/, `${destination} + port ${JSON.stringify(port)} must be rejected`);
-    }
-  }
-  // Renaming the surface must NOT bypass the rule — this is the bypass that
-  // keying on the `remote` label allowed.
-  for (const id of ["vultr", "prod", "primary", "local"]) {
-    assert.throws(() => validatePluginManifest(baseManifest("renamed-remote", {
-      surfaces: [{ id, destination: "vultr/clauth/pm2", lifecycle_owner: "external", port: 3110 }],
-    })), /must not declare a port/, `a non-local surface named "${id}" must still be rejected`);
-  }
-  // A remote surface WITHOUT a port is accepted — the shape all four shipped
-  // remote surfaces already use.
-  const remote = validatePluginManifest(baseManifest("remote-ok", {
-    surfaces: [{ id: "remote", destination: "vultr/clauth/pm2", lifecycle_owner: "external" }],
-  }), "clauth-plugin.json");
-  assert.equal(remote.surfaces[0].port, null);
-  // A LOCAL surface keeps its port on purpose — that port describes how the
-  // service runs on a developer box. This is not drift; do not "fix" it. A
-  // local surface merely NAMED "remote" is local, and must not be rejected.
-  for (const [id, destination] of [["local", "local/clauth/pm2"], ["primary", "local/clauth/pm2"], ["remote", "local/clauth/daemon"]]) {
-    const localSurface = validatePluginManifest(baseManifest(`${id}-ok`, {
-      surfaces: [{ id, destination, lifecycle_owner: "clauth", port: 3109, health: "/health" }],
-    }), "clauth-plugin.json");
-    assert.equal(localSurface.surfaces[0].port, 3109, `${destination} surface must keep its port`);
-    assert.equal(localSurface.surfaces[0].health, "http://127.0.0.1:3109/health");
-  }
-});
-test("deregisterPlugin removes a scoped @scope/pkg plugin instead of falsely reporting it absent", () => withTempSupervisor((root) => {
-  // A removal verb that reports ✓ while the plugin stays installed AND enabled
-  // is the one receipt this must never get wrong. The flat <root>/<id> probe
-  // misses the scoped layout entirely, so the location is resolved from the
-  // discovery_root/sourcePath discovery already records.
-  const managed = path.join(root, "managed");
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
-  writeScopedPlugin(root, "managed", "@lifeaitools", "fs-mcp", baseManifest("fs-mcp", { core: true, enable_default: true }));
-  discoverPlugins();
-  assert.equal(listPlugins().find((plugin) => plugin.id === "fs-mcp").enabled, true, "precondition: scoped plugin is enabled");
-  const receipt = deregisterPlugin("fs-mcp", "test");
-  assert.equal(receipt.resulting_state.state, "deregistered", "must not report not_registered for a scoped plugin");
-  assert.equal(receipt.resulting_state.ok, true);
-  assert.equal(fs.existsSync(path.join(managed, "@lifeaitools", "fs-mcp")), false, "the scoped package directory is actually gone");
-  const after = listPlugins().find((plugin) => plugin.id === "fs-mcp");
-  assert.equal(after.enabled, false, "a deregistered plugin must not remain enabled");
-  assert.equal(after.state, "missing_default");
-}));
-test("deregisterPlugin finds a plugin in a non-first managed root and refuses a user-root plugin", () => withTempSupervisor((root) => {
-  // CLAUTH_MANAGED_PLUGIN_ROOTS is a path-delimited LIST; honoring only the
-  // first entry silently reports a real plugin as absent.
-  const managedA = path.join(root, "managed-a");
-  const managedB = path.join(root, "managed-b");
-  const user = path.join(root, "user");
-  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = [managedA, managedB].join(path.delimiter);
-  process.env.CLAUTH_USER_PLUGIN_ROOTS = user;
-  writePlugin(root, "managed-b", "second-root-plugin", baseManifest("second-root-plugin"));
-  writePlugin(root, "user", "user-only-plugin", baseManifest("user-only-plugin"));
-  discoverPlugins();
-  const second = deregisterPlugin("second-root-plugin", "test");
-  assert.equal(second.resulting_state.state, "deregistered", "a plugin in the 2nd managed root must be found");
-  assert.equal(fs.existsSync(path.join(managedB, "second-root-plugin")), false);
-  // A user-root plugin is out of this verb's remit — refuse it explicitly
-  // rather than reporting a green "not_registered" that implies it is gone.
-  const userReceipt = deregisterPlugin("user-only-plugin", "test");
-  assert.equal(userReceipt.resulting_state.ok, false);
-  assert.equal(userReceipt.resulting_state.state, "not_managed");
-  assert.equal(fs.existsSync(path.join(user, "user-only-plugin")), true, "the user plugin must be left intact");
-}));
-test("deregisterPlugin --dry-run resolves the target without deleting it", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
-  syncPluginsFromRepos(roots, "test");
-  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
-  const receipt = deregisterPlugin("web-research", "test", { dryRun: true });
-  assert.equal(receipt.resulting_state.ok, true);
-  assert.equal(receipt.resulting_state.state, "would_deregister");
-  assert.equal(receipt.resulting_state.target_dir, path.resolve(managed, "web-research"));
-  assert.equal(fs.existsSync(path.join(managed, "web-research")), true, "a dry run must not delete anything");
-  assert.equal(listPlugins().find((plugin) => plugin.id === "web-research").state !== "missing_default", true);
-})));
-test("plugin sync reports an unknown repo-root override instead of silently sweeping the default checkout", () => withTempSupervisor(() => withTempProductRepos(({ roots, base }) => {
-  // A typo'd override name dropped on the floor means the sweep reads the
-  // DEFAULT checkout while printing ✓ on every line — success from the wrong repo.
-  const receipts = syncPluginsFromRepos({ ...roots, regen_root: path.join(base, "typo-checkout") }, "test");
-  const rejected = receipts.filter((entry) => entry.state === "unknown_repo_name");
-  assert.equal(rejected.length, 1);
-  assert.equal(rejected[0].repo, "regen_root");
-  assert.equal(rejected[0].ok, false);
-  assert.match(rejected[0].error, /unknown repo name/);
-  assert.equal(SYNC_SKIP_STATES.includes("unknown_repo_name"), false, "a typo'd repo name must fail the sweep, not be skipped");
-  assert.deepEqual([...SYNC_REPO_NAMES].sort(), ["rdc-skills", "regen-root"]);
-})));
-test("plugin sync never throws on a malformed repo root — the contract absence must not break", () => withTempSupervisor(() => withTempProductRepos(({ rdcSkills }) => {
-  // path.resolve() throws on a non-string; doing that before the existence
-  // guard aborted the whole sweep and lost every later repo's receipt.
-  for (const badRoot of [123, "   ", {}, [], true]) {
-    let receipts;
-    assert.doesNotThrow(() => {
-      receipts = syncPluginsFromRepos({ "regen-root": badRoot, "rdc-skills": rdcSkills }, "test");
-    }, `root ${JSON.stringify(badRoot)} must not throw`);
-    assert.equal(receipts.length, 5, "every attempted manifest still yields a receipt");
-    assert.equal(
-      receipts.filter((entry) => entry.repo === "regen-root" && entry.state === "repo_root_unknown").length,
-      4,
-      `root ${JSON.stringify(badRoot)} must be reported, not thrown`,
-    );
-    const skills = receipts.find((entry) => entry.repo === "rdc-skills");
-    assert.equal(skills.ok, true, "a later repo must still be swept after a bad earlier root");
-  }
-})));
-test("regression: scoped @scope/pkg and unscoped discovery both still work alongside deregister", () => withTempSupervisor((root) => {
-  // Epic 63d4d778 WP-1 taught findManifestFiles to descend one extra level for
-  // an @scope directory (node_modules/@lifeaitools/fs-mcp). Neither the sync
-  // sweep nor deregisterPlugin may regress that.
-  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", "plain-plugin", baseManifest("plain-plugin"));
-  writeScopedPlugin(root, "managed", "@lifeaitools", "fs-mcp", baseManifest("fs-mcp"));
-  const discovered = discoverPlugins();
-  assert.ok(discovered.plugins.find((plugin) => plugin.id === "plain-plugin"), "unscoped layout still discovered");
-  assert.ok(discovered.plugins.find((plugin) => plugin.id === "fs-mcp"), "scoped layout still discovered");
-  // Deregistering the unscoped plugin must not disturb the scoped tree.
-  const receipt = deregisterPlugin("plain-plugin", "test");
-  assert.equal(receipt.resulting_state.ok, true);
-  assert.equal(fs.existsSync(path.join(managed, "plain-plugin")), false);
-  assert.equal(fs.existsSync(path.join(managed, "@lifeaitools", "fs-mcp", "clauth-plugin.json")), true, "scoped package must be untouched");
-  const after = discoverPlugins();
-  assert.ok(after.plugins.find((plugin) => plugin.id === "fs-mcp" && plugin.state !== "missing_default"), "scoped plugin still discoverable after a sibling deregister");
-}));
-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");
-}));
-test("command arguments expand path tokens, not just cwd", () => {
-  // Regression: expandPathToken() was applied ONLY to `cwd`, so a manifest that
-  // named a root inside a COMMAND ARGUMENT shipped the literal string to the
-  // shell. dev-center's restart is
-  // ["pwsh","-NoProfile","-File","$LIFEAI_ENV/services/restart-dev-center.ps1"]
-  // and pwsh answered "not recognized as the name of a script file" with exit
-  // 64 -- a restart that fails while the service stays up, which reads as a
-  // flaky action rather than an unresolved path.
-  const oldEnv = process.env.LIFEAI_ENV;
-  const oldRoot = process.env.REGEN_ROOT;
-  process.env.LIFEAI_ENV = "C:/tmp/env-root";
-  process.env.REGEN_ROOT = "C:/tmp/regen-root";
-  try {
-    const plugin = validatePluginManifest(baseManifest("token-expansion", {
-      surfaces: [{
-        id: "primary",
-        destination: "local/clauth/pm2",
-        lifecycle_owner: "clauth",
-        port: 3003,
-        health: "/health",
-        restart: ["pwsh", "-NoProfile", "-File", "$LIFEAI_ENV/services/restart-dev-center.ps1"],
-        start: ["node", "${REGEN_ROOT}/scripts/start.mjs"],
-      }],
-    }), "clauth-plugin.json");
-    const s = plugin.surfaces[0];
-    assert.ok(!s.restart.some((a) => a.includes("$LIFEAI_ENV")),
-      `LIFEAI_ENV left unexpanded: ${JSON.stringify(s.restart)}`);
-    assert.ok(s.restart.some((a) => a.includes("C:/tmp/env-root")),
-      `LIFEAI_ENV did not expand to its value: ${JSON.stringify(s.restart)}`);
-    assert.ok(s.start.some((a) => a.includes("C:/tmp/regen-root")),
-      `REGEN_ROOT did not expand in a command arg: ${JSON.stringify(s.start)}`);
-  } finally {
-    if (oldEnv === undefined) delete process.env.LIFEAI_ENV; else process.env.LIFEAI_ENV = oldEnv;
-    if (oldRoot === undefined) delete process.env.REGEN_ROOT; else process.env.REGEN_ROOT = oldRoot;
-  }
-});
+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,
+  deregisterPlugin,
+  discoverPlugins,
+  getClauthPm2Home,
+  listPlugins,
+  listSurfaces,
+  reconcileSurfaceHealth,
+  registerPlugin,
+  runPluginAction,
+  runSurfaceAction,
+  removeTunnelRoute,
+  setPluginEnabled,
+  shellQuote,
+  supervisorHealth,
+  syncPluginsFromRepos,
+  SYNC_REPO_NAMES,
+  SYNC_SKIP_STATES,
+  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;
+  // CLAUTH_MANAGED_PLUGIN_ROOTS / CLAUTH_USER_PLUGIN_ROOTS are set as PERSISTENT
+  // MACHINE-LEVEL env vars on developer boxes, pointing at the LIVE daemon's
+  // plugin directories. rootEntries() prefers them over CLAUTH_SUPERVISOR_DIR,
+  // so overriding the supervisor dir ALONE leaves registerPlugin/deregisterPlugin
+  // writing to (and deleting from) the live fleet. Pin all three to the temp
+  // root here so a test cannot reach the live daemon by forgetting to.
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = path.join(root, "managed-plugins");
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user-plugins");
+  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;
+}
+// A scoped npm package installs at <root>/@scope/pkg-name/clauth-plugin.json —
+// two levels deep, mirroring node_modules/@lifeaitools/<pkg>/.
+function writeScopedPlugin(root, source, scope, id, manifest) {
+  const dir = path.join(root, source, scope, 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("shellQuote quotes a whitespace-bearing value only when shell is active, and is idempotent", () => {
+  assert.equal(shellQuote("pm2", true), "pm2");
+  assert.equal(shellQuote("C:/Program Files/nodejs/node.exe", true), '"C:/Program Files/nodejs/node.exe"');
+  assert.equal(shellQuote("C:/Program Files/nodejs/node.exe", false), "C:/Program Files/nodejs/node.exe");
+  assert.equal(shellQuote("one two", false), "one two");
+  assert.equal(shellQuote('"already quoted value"', true), '"already quoted value"');
+});
+test("validatePluginManifest rejects shell metacharacters in command ARGS, not just command[0]", () => {
+  // The [;&|<>] guard on command[0] alone is defeated by moving the payload
+  // one index right — args must be validated the same way (verified live
+  // during code review: spawnSync(['cmd','/c','echo','A & echo INJECTED'],
+  // {shell:true}) executed a second command from inside one arg string).
+  assert.throws(() => validatePluginManifest(baseManifest("inject", {
+    surfaces: [{ id: "primary", lifecycle_owner: "clauth", restart: ["pm2", "start svc & calc.exe"] }],
+  })), /shell syntax/);
+  assert.throws(() => validatePluginManifest(baseManifest("inject2", {
+    surfaces: [{ id: "primary", lifecycle_owner: "clauth", restart: ["pm2", "restart", "name; rm -rf /"] }],
+  })), /shell syntax/);
+  // A legitimate arg with no shell metacharacters still passes.
+  const ok = validatePluginManifest(baseManifest("legit", {
+    surfaces: [{ id: "primary", lifecycle_owner: "clauth", restart: ["pm2", "restart", "my-app-name"] }],
+  }), "clauth-plugin.json");
+  assert.deepEqual(ok.surfaces[0].restart, ["pm2", "restart", "my-app-name"]);
+});
+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("discovery finds both a scoped npm-package layout and an unscoped layout from one root", () => 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");
+  // Unscoped: managed/plain-plugin/clauth-plugin.json (one level — existing behavior)
+  writePlugin(root, "managed", "plain-plugin", baseManifest("plain-plugin"));
+  // Scoped: managed/@lifeaitools/fs-mcp/clauth-plugin.json (two levels — the WP-1 fix)
+  writeScopedPlugin(root, "managed", "@lifeaitools", "fs-mcp", baseManifest("fs-mcp"));
+  const result = discoverPlugins();
+  const plain = result.plugins.find((plugin) => plugin.id === "plain-plugin");
+  const scoped = result.plugins.find((plugin) => plugin.id === "fs-mcp");
+  assert.ok(plain, "unscoped layout must still be discovered");
+  assert.equal(plain.state, "awaiting_enable");
+  assert.ok(scoped, "scoped @scope/pkg layout must now be discovered");
+  assert.equal(scoped.state, "awaiting_enable");
+  assert.equal(scoped.manifest_hash?.length > 0, true);
+}));
+test("discovery skips a malformed manifest without aborting the rest of the scan", () => 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", "good-plugin", baseManifest("good-plugin"));
+  const brokenDir = path.join(managed, "broken-plugin");
+  fs.mkdirSync(brokenDir, { recursive: true });
+  fs.writeFileSync(path.join(brokenDir, "clauth-plugin.json"), "{ this is not valid json", "utf8");
+  // Also prove a malformed SCOPED manifest doesn't abort the scoped-dir descent either.
+  const brokenScopedDir = path.join(managed, "@lifeaitools", "broken-scoped");
+  fs.mkdirSync(brokenScopedDir, { recursive: true });
+  fs.writeFileSync(path.join(brokenScopedDir, "clauth-plugin.json"), "{ also not valid json", "utf8");
+  writeScopedPlugin(root, "managed", "@lifeaitools", "good-scoped", baseManifest("good-scoped"));
+  const result = discoverPlugins();
+  const good = result.plugins.find((plugin) => plugin.id === "good-plugin");
+  const broken = result.plugins.find((plugin) => plugin.id === "broken-plugin");
+  const goodScoped = result.plugins.find((plugin) => plugin.id === "good-scoped");
+  const brokenScoped = result.plugins.find((plugin) => plugin.id === "broken-scoped");
+  assert.equal(good.state, "awaiting_enable");
+  assert.equal(broken.state, "manifest_invalid");
+  assert.equal(goodScoped.state, "awaiting_enable");
+  assert.equal(brokenScoped.state, "manifest_invalid");
+}));
+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 {
+    // Both fixtures are deliberately PROBE-ABLE — local destination + port, so
+    // healthUrlForSurface() yields a real URL for each. That is what gives this
+    // test teeth.
+    //
+    // An earlier revision made the external fixture `vultr/` with no port. It
+    // read as equivalent and was not: portless + relative health resolves to a
+    // null URL, so reconcileSurfaceHealth's `if (!url) continue` skipped it
+    // BEFORE the owner/destination guard was consulted. Delete the guard this
+    // test is named for and it still passed green — it proved the surface was
+    // unprobe-able, not that it was probe-able and correctly left alone.
+    //
+    // Now the ONLY thing that can exclude external-demo is lifecycle_owner, and
+    // clauth-owned-demo is the positive control proving the probe machinery
+    // actually runs against this fixture shape. If `inspected` ever comes back
+    // empty, the control failed and the negative result means nothing.
+    writePlugin(root, "managed", "external-demo", baseManifest("external-demo", {
+      core: true,
+      enable_default: true,
+      destination: "local/clauth/pm2",
+      lifecycle_owner: "external",
+      surfaces: [{ id: "primary", destination: "local/clauth/pm2", lifecycle_owner: "external", port: 39112, health: "/health" }],
+    }));
+    writePlugin(root, "managed", "clauth-owned-demo", baseManifest("clauth-owned-demo", {
+      core: true,
+      enable_default: true,
+      destination: "local/clauth/pm2",
+      lifecycle_owner: "clauth",
+      surfaces: [{ id: "primary", destination: "local/clauth/pm2", lifecycle_owner: "clauth", port: 39113, health: "/health" }],
+    }));
+    discoverPlugins();
+    const result = await reconcileSurfaceHealth({ fetchImpl: async () => ({ ok: false, status: 503 }) });
+    const inspectedIds = result.inspected.map((s) => (typeof s === "string" ? s : s.surface_id));
+    // Positive control: the probe machinery ran at all.
+    assert.ok(inspectedIds.some((id) => String(id).includes("clauth-owned-demo")),
+      `control failed — clauth-owned surface was not probed, so "external was skipped" proves nothing (inspected: ${JSON.stringify(result.inspected)})`);
+    // The actual assertion: an externally-owned surface is never touched.
+    assert.ok(!inspectedIds.some((id) => String(id).includes("external-demo")),
+      `external-demo was probed — the lifecycle_owner guard is not excluding it (inspected: ${JSON.stringify(result.inspected)})`);
+    const external = listSurfaces().find((s) => s.plugin_id === "external-demo");
+    assert.equal(external.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("registerPlugin validates, writes into the managed root, and discovers the plugin — idempotent on re-register", () => 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");
+  const sourceDir = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-register-source-"));
+  const manifestPath = path.join(sourceDir, "clauth-plugin.json");
+  fs.writeFileSync(manifestPath, JSON.stringify(baseManifest("registered-demo", { core: true, enable_default: true })), "utf8");
+  const first = registerPlugin(manifestPath, "test");
+  assert.equal(first.resulting_state.ok, true);
+  assert.equal(first.resulting_state.state, "registered");
+  assert.equal(first.resulting_state.plugin_state, "current");
+  const written = fs.existsSync(path.join(managed, "registered-demo", "clauth-plugin.json"));
+  assert.equal(written, true);
+  const found = listPlugins().find((plugin) => plugin.id === "registered-demo");
+  assert.equal(found.enabled, true);
+  const second = registerPlugin(manifestPath, "test");
+  assert.equal(second.resulting_state.state, "unchanged", "re-registering identical content must be a no-op, not a rewrite");
+  fs.rmSync(sourceDir, { recursive: true, force: true });
+}));
+test("registerPlugin rejects a plugin id that would escape the managed-plugins root", () => withTempSupervisor((root) => {
+  // Code-review finding (confidence 95, live PoC): manifest.id of ".." passed
+  // the old id regex (dot is in the allowed character class with no
+  // exclusion of all-dots forms) and path.join(managedRoot, "..") wrote
+  // clauth-plugin.json one level ABOVE the managed root. Two independent
+  // fixes now close this: the id regex rejects all-dots ids, and
+  // registerPlugin asserts containment at the write site so a future regex
+  // relaxation can't reopen it.
+  const managed = path.join(root, "managed");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  const sourceDir = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-register-traversal-"));
+  const manifestPath = path.join(sourceDir, "clauth-plugin.json");
+  fs.writeFileSync(manifestPath, JSON.stringify({ schema: "lifeai.plugin.v1", id: "..", version: "1.0.0", publisher: "t", documentation: { architecture: "a.md" }, surfaces: [] }), "utf8");
+  const receipt = registerPlugin(manifestPath, "test");
+  assert.equal(receipt.resulting_state.ok, false);
+  assert.equal(receipt.resulting_state.state, "manifest_invalid");
+  const escapedPath = path.join(managed, "..", "clauth-plugin.json");
+  assert.equal(fs.existsSync(escapedPath), false, "must never write outside the managed-plugins root");
+  fs.rmSync(sourceDir, { recursive: true, force: true });
+}));
+test("validatePluginManifest rejects an all-dots plugin or surface id", () => {
+  assert.throws(() => validatePluginManifest(baseManifest("..", {}), "clauth-plugin.json"), /may not be all dots/);
+  assert.throws(() => validatePluginManifest(baseManifest("valid-id", {
+    surfaces: [{ id: ".", lifecycle_owner: "clauth" }],
+  }), "clauth-plugin.json"), /may not be all dots/);
+});
+test("registerPlugin rejects an invalid manifest without writing anything", () => 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");
+  const sourceDir = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-register-bad-"));
+  const manifestPath = path.join(sourceDir, "clauth-plugin.json");
+  fs.writeFileSync(manifestPath, JSON.stringify({ schema: "wrong", id: "bad" }), "utf8");
+  const receipt = registerPlugin(manifestPath, "test");
+  assert.equal(receipt.resulting_state.ok, false);
+  assert.equal(receipt.resulting_state.state, "manifest_invalid");
+  assert.equal(fs.existsSync(path.join(managed, "bad")), false);
+  fs.rmSync(sourceDir, { recursive: true, force: true });
+}));
+// Builds throwaway product repos laid out like the real ones, so a sync sweep
+// exercises the real relative manifest paths without reading a live checkout.
+function withTempProductRepos(fn) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-sync-repos-"));
+  const regenRoot = path.join(base, "regen-root");
+  const rdcSkills = path.join(base, "rdc-skills");
+  const writeManifest = (repoRoot, relPath, manifest) => {
+    const full = path.join(repoRoot, relPath);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, typeof manifest === "string" ? manifest : `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    return full;
+  };
+  writeManifest(regenRoot, "packages/codeflow/clauth-plugin.json", baseManifest("codeflow-mcp"));
+  writeManifest(regenRoot, "apps/dev-center/clauth-plugin.json", baseManifest("dev-center"));
+  writeManifest(regenRoot, "mcp-servers/regen-media/clauth-plugin.json", baseManifest("regen-media"));
+  writeManifest(regenRoot, "mcp-servers/web-research/clauth-plugin.json", baseManifest("web-research"));
+  writeManifest(rdcSkills, "clauth-plugin.json", baseManifest("rdc-skills"));
+  try {
+    return fn({ base, regenRoot, rdcSkills, writeManifest, roots: { "regen-root": regenRoot, "rdc-skills": rdcSkills } });
+  } finally {
+    fs.rmSync(base, { recursive: true, force: true });
+  }
+}
+test("plugin sync inherits registerPlugin idempotence — a second sweep reports every manifest unchanged", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
+  const first = syncPluginsFromRepos(roots, "test");
+  assert.equal(first.length, 5, "one receipt per attempted manifest");
+  assert.deepEqual(
+    first.filter((entry) => !entry.ok).map((entry) => `${entry.repo}:${entry.state}`),
+    [],
+    "every manifest in a complete checkout must register",
+  );
+  assert.equal(first.every((entry) => entry.state === "registered"), true);
+  // registerPlugin sha256-compares before writing; sync must not defeat that by
+  // re-writing or re-hashing on its own.
+  const second = syncPluginsFromRepos(roots, "test");
+  assert.equal(second.length, 5);
+  assert.equal(second.every((entry) => entry.ok && entry.state === "unchanged"), true, "re-sweeping identical content must be a no-op");
+})));
+test("plugin sync warns and continues over a missing repo root instead of throwing", () => withTempSupervisor(() => withTempProductRepos(({ base, rdcSkills }) => {
+  // A box that never checked out regen-root must still sync what it does have.
+  const absent = path.join(base, "no-such-checkout");
+  assert.equal(fs.existsSync(absent), false);
+  let receipts;
+  assert.doesNotThrow(() => {
+    receipts = syncPluginsFromRepos({ "regen-root": absent, "rdc-skills": rdcSkills }, "test");
+  });
+  assert.equal(receipts.length, 5, "a skipped repo still yields a receipt per attempted manifest");
+  const missing = receipts.filter((entry) => entry.state === "repo_root_missing");
+  assert.equal(missing.length, 4, "all four regen-root manifests report the missing root");
+  assert.equal(missing.every((entry) => entry.ok === false), true);
+  const skills = receipts.find((entry) => entry.repo === "rdc-skills");
+  assert.equal(skills.ok, true);
+  assert.equal(skills.state, "registered");
+  assert.ok(listPlugins().find((plugin) => plugin.id === "rdc-skills"), "the reachable repo still registered");
+})));
+test("plugin sync registers the remaining manifests when one is malformed", () => withTempSupervisor(() => withTempProductRepos(({ regenRoot, roots, writeManifest }) => {
+  writeManifest(regenRoot, "apps/dev-center/clauth-plugin.json", "{ this is not valid json");
+  const receipts = syncPluginsFromRepos(roots, "test");
+  assert.equal(receipts.length, 5);
+  const bad = receipts.find((entry) => entry.path.includes("dev-center"));
+  assert.equal(bad.ok, false);
+  assert.equal(bad.state, "manifest_invalid");
+  const good = receipts.filter((entry) => entry !== bad);
+  assert.equal(good.length, 4);
+  assert.equal(good.every((entry) => entry.ok && entry.state === "registered"), true, "one bad manifest must not abort the sweep");
+  const ids = new Set(listPlugins().map((plugin) => plugin.id));
+  for (const id of ["codeflow-mcp", "regen-media", "web-research", "rdc-skills"]) {
+    assert.ok(ids.has(id), `${id} must still be registered`);
+  }
+})));
+test("deregisterPlugin removes only the named plugin and leaves siblings intact", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
+  syncPluginsFromRepos(roots, "test");
+  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+  assert.equal(fs.existsSync(path.join(managed, "web-research")), true);
+  const receipt = deregisterPlugin("web-research", "test");
+  assert.equal(receipt.resulting_state.ok, true);
+  assert.equal(receipt.resulting_state.state, "deregistered");
+  assert.equal(fs.existsSync(path.join(managed, "web-research")), false, "the named plugin directory is gone");
+  for (const sibling of ["codeflow-mcp", "dev-center", "regen-media", "rdc-skills"]) {
+    assert.equal(fs.existsSync(path.join(managed, sibling)), true, `${sibling} must survive`);
+  }
+  // discovery re-ran, so the removed managed plugin is reported missing, not current
+  const after = listPlugins().find((plugin) => plugin.id === "web-research");
+  assert.equal(after.state, "missing_default");
+  assert.equal(after.enabled, false);
+})));
+test("deregisterPlugin on an unregistered id is a safe no-op, not an error", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
+  syncPluginsFromRepos(roots, "test");
+  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+  const before = fs.readdirSync(managed).sort();
+  const receipt = deregisterPlugin("never-registered-plugin", "test");
+  assert.equal(receipt.resulting_state.ok, true, "a no-op is success, not failure");
+  assert.equal(receipt.resulting_state.state, "not_registered");
+  assert.deepEqual(fs.readdirSync(managed).sort(), before, "nothing else may be touched");
+})));
+test("deregisterPlugin rejects an id that would escape the managed-plugins root", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
+  // Mirrors the registerPlugin traversal test. The id here is raw CLI/HTTP
+  // input with no manifest validation upstream, and the operation DELETES
+  // recursively — so an id resolving to the root itself must reject too, which
+  // is where this is strictly stricter than registerPlugin's assertion.
+  syncPluginsFromRepos(roots, "test");
+  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+  const sentinel = path.join(managed, "..", "sentinel-outside-root.txt");
+  fs.writeFileSync(sentinel, "must survive", "utf8");
+  const before = fs.readdirSync(managed).sort();
+  const evilIds = [
+    "..", "../..", "../sentinel-outside-root.txt", "..\\..", "/etc", "", ".",
+    // These three are stopped by the CHARSET guard alone — the containment
+    // assert waves all of them through, because path.resolve() normalizes the
+    // `..` away and Windows re-anchors a drive-relative path, so each lands
+    // back INSIDE the root (measured during code review). They are pinned here
+    // so the two guards are independently tested and nobody "simplifies" the
+    // charset rule believing containment is a safety net for it.
+    "sub/../web-research",
+    "C:web-research",
+    "web-research::$DATA",
+  ];
+  for (const evil of evilIds) {
+    const receipt = deregisterPlugin(evil, "test");
+    assert.equal(receipt.resulting_state.ok, false, `id ${JSON.stringify(evil)} must be rejected`);
+    assert.equal(receipt.resulting_state.state, "invalid_plugin_id");
+  }
+  assert.equal(fs.existsSync(path.join(managed, "web-research")), true, "a charset-rejected alias must not have deleted the real plugin");
+  assert.equal(fs.existsSync(sentinel), true, "must never delete outside the managed-plugins root");
+  assert.equal(fs.existsSync(managed), true, "must never delete the managed-plugins root itself");
+  assert.deepEqual(fs.readdirSync(managed).sort(), before, "no registered plugin may be removed by a rejected id");
+})));
+test("validatePluginManifest rejects a port on any non-local destination, and keeps local ports", () => {
+  // A remote surface is reached by URL; its port is the deployment registry's
+  // fact. Copying it into the manifest creates a second home for one fact that
+  // then drifts (regen-media 3121 vs 3120, dev-center 3012 vs 3003). Worse, a
+  // ported remote surface makes localhostHealth() synthesize
+  // http://127.0.0.1:<port>/health for a service on another box, pointing the
+  // health reconciler at the wrong machine.
+  //
+  // The rule is keyed on the validated DESTINATION enum, never on the surface's
+  // free-text id/role — keying on the label was tried in review and failed both
+  // ways: renaming the surface bypassed it, and a local surface named "remote"
+  // was falsely rejected. Both directions are asserted below.
+  for (const destination of ["vultr/clauth/pm2", "coolify/clauth/docker"]) {
+    for (const port of [3110, "auto", 0]) {
+      assert.throws(() => validatePluginManifest(baseManifest("remote-port", {
+        surfaces: [{ id: "remote", destination, lifecycle_owner: "external", port }],
+      })), /must not declare a port/, `${destination} + port ${JSON.stringify(port)} must be rejected`);
+    }
+  }
+  // Renaming the surface must NOT bypass the rule — this is the bypass that
+  // keying on the `remote` label allowed.
+  for (const id of ["vultr", "prod", "primary", "local"]) {
+    assert.throws(() => validatePluginManifest(baseManifest("renamed-remote", {
+      surfaces: [{ id, destination: "vultr/clauth/pm2", lifecycle_owner: "external", port: 3110 }],
+    })), /must not declare a port/, `a non-local surface named "${id}" must still be rejected`);
+  }
+  // A remote surface WITHOUT a port is accepted — the shape all four shipped
+  // remote surfaces already use.
+  const remote = validatePluginManifest(baseManifest("remote-ok", {
+    surfaces: [{ id: "remote", destination: "vultr/clauth/pm2", lifecycle_owner: "external" }],
+  }), "clauth-plugin.json");
+  assert.equal(remote.surfaces[0].port, null);
+  // A LOCAL surface keeps its port on purpose — that port describes how the
+  // service runs on a developer box. This is not drift; do not "fix" it. A
+  // local surface merely NAMED "remote" is local, and must not be rejected.
+  for (const [id, destination] of [["local", "local/clauth/pm2"], ["primary", "local/clauth/pm2"], ["remote", "local/clauth/daemon"]]) {
+    const localSurface = validatePluginManifest(baseManifest(`${id}-ok`, {
+      surfaces: [{ id, destination, lifecycle_owner: "clauth", port: 3109, health: "/health" }],
+    }), "clauth-plugin.json");
+    assert.equal(localSurface.surfaces[0].port, 3109, `${destination} surface must keep its port`);
+    assert.equal(localSurface.surfaces[0].health, "http://127.0.0.1:3109/health");
+  }
+});
+test("deregisterPlugin removes a scoped @scope/pkg plugin instead of falsely reporting it absent", () => withTempSupervisor((root) => {
+  // A removal verb that reports ✓ while the plugin stays installed AND enabled
+  // is the one receipt this must never get wrong. The flat <root>/<id> probe
+  // misses the scoped layout entirely, so the location is resolved from the
+  // discovery_root/sourcePath discovery already records.
+  const managed = path.join(root, "managed");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  writeScopedPlugin(root, "managed", "@lifeaitools", "fs-mcp", baseManifest("fs-mcp", { core: true, enable_default: true }));
+  discoverPlugins();
+  assert.equal(listPlugins().find((plugin) => plugin.id === "fs-mcp").enabled, true, "precondition: scoped plugin is enabled");
+  const receipt = deregisterPlugin("fs-mcp", "test");
+  assert.equal(receipt.resulting_state.state, "deregistered", "must not report not_registered for a scoped plugin");
+  assert.equal(receipt.resulting_state.ok, true);
+  assert.equal(fs.existsSync(path.join(managed, "@lifeaitools", "fs-mcp")), false, "the scoped package directory is actually gone");
+  const after = listPlugins().find((plugin) => plugin.id === "fs-mcp");
+  assert.equal(after.enabled, false, "a deregistered plugin must not remain enabled");
+  assert.equal(after.state, "missing_default");
+}));
+test("deregisterPlugin finds a plugin in a non-first managed root and refuses a user-root plugin", () => withTempSupervisor((root) => {
+  // CLAUTH_MANAGED_PLUGIN_ROOTS is a path-delimited LIST; honoring only the
+  // first entry silently reports a real plugin as absent.
+  const managedA = path.join(root, "managed-a");
+  const managedB = path.join(root, "managed-b");
+  const user = path.join(root, "user");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = [managedA, managedB].join(path.delimiter);
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = user;
+  writePlugin(root, "managed-b", "second-root-plugin", baseManifest("second-root-plugin"));
+  writePlugin(root, "user", "user-only-plugin", baseManifest("user-only-plugin"));
+  discoverPlugins();
+  const second = deregisterPlugin("second-root-plugin", "test");
+  assert.equal(second.resulting_state.state, "deregistered", "a plugin in the 2nd managed root must be found");
+  assert.equal(fs.existsSync(path.join(managedB, "second-root-plugin")), false);
+  // A user-root plugin is out of this verb's remit — refuse it explicitly
+  // rather than reporting a green "not_registered" that implies it is gone.
+  const userReceipt = deregisterPlugin("user-only-plugin", "test");
+  assert.equal(userReceipt.resulting_state.ok, false);
+  assert.equal(userReceipt.resulting_state.state, "not_managed");
+  assert.equal(fs.existsSync(path.join(user, "user-only-plugin")), true, "the user plugin must be left intact");
+}));
+test("deregisterPlugin --dry-run resolves the target without deleting it", () => withTempSupervisor(() => withTempProductRepos(({ roots }) => {
+  syncPluginsFromRepos(roots, "test");
+  const managed = process.env.CLAUTH_MANAGED_PLUGIN_ROOTS;
+  const receipt = deregisterPlugin("web-research", "test", { dryRun: true });
+  assert.equal(receipt.resulting_state.ok, true);
+  assert.equal(receipt.resulting_state.state, "would_deregister");
+  assert.equal(receipt.resulting_state.target_dir, path.resolve(managed, "web-research"));
+  assert.equal(fs.existsSync(path.join(managed, "web-research")), true, "a dry run must not delete anything");
+  assert.equal(listPlugins().find((plugin) => plugin.id === "web-research").state !== "missing_default", true);
+})));
+test("plugin sync reports an unknown repo-root override instead of silently sweeping the default checkout", () => withTempSupervisor(() => withTempProductRepos(({ roots, base }) => {
+  // A typo'd override name dropped on the floor means the sweep reads the
+  // DEFAULT checkout while printing ✓ on every line — success from the wrong repo.
+  const receipts = syncPluginsFromRepos({ ...roots, regen_root: path.join(base, "typo-checkout") }, "test");
+  const rejected = receipts.filter((entry) => entry.state === "unknown_repo_name");
+  assert.equal(rejected.length, 1);
+  assert.equal(rejected[0].repo, "regen_root");
+  assert.equal(rejected[0].ok, false);
+  assert.match(rejected[0].error, /unknown repo name/);
+  assert.equal(SYNC_SKIP_STATES.includes("unknown_repo_name"), false, "a typo'd repo name must fail the sweep, not be skipped");
+  assert.deepEqual([...SYNC_REPO_NAMES].sort(), ["rdc-skills", "regen-root"]);
+})));
+test("plugin sync never throws on a malformed repo root — the contract absence must not break", () => withTempSupervisor(() => withTempProductRepos(({ rdcSkills }) => {
+  // path.resolve() throws on a non-string; doing that before the existence
+  // guard aborted the whole sweep and lost every later repo's receipt.
+  for (const badRoot of [123, "   ", {}, [], true]) {
+    let receipts;
+    assert.doesNotThrow(() => {
+      receipts = syncPluginsFromRepos({ "regen-root": badRoot, "rdc-skills": rdcSkills }, "test");
+    }, `root ${JSON.stringify(badRoot)} must not throw`);
+    assert.equal(receipts.length, 5, "every attempted manifest still yields a receipt");
+    assert.equal(
+      receipts.filter((entry) => entry.repo === "regen-root" && entry.state === "repo_root_unknown").length,
+      4,
+      `root ${JSON.stringify(badRoot)} must be reported, not thrown`,
+    );
+    const skills = receipts.find((entry) => entry.repo === "rdc-skills");
+    assert.equal(skills.ok, true, "a later repo must still be swept after a bad earlier root");
+  }
+})));
+test("regression: scoped @scope/pkg and unscoped discovery both still work alongside deregister", () => withTempSupervisor((root) => {
+  // Epic 63d4d778 WP-1 taught findManifestFiles to descend one extra level for
+  // an @scope directory (node_modules/@lifeaitools/fs-mcp). Neither the sync
+  // sweep nor deregisterPlugin may regress that.
+  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", "plain-plugin", baseManifest("plain-plugin"));
+  writeScopedPlugin(root, "managed", "@lifeaitools", "fs-mcp", baseManifest("fs-mcp"));
+  const discovered = discoverPlugins();
+  assert.ok(discovered.plugins.find((plugin) => plugin.id === "plain-plugin"), "unscoped layout still discovered");
+  assert.ok(discovered.plugins.find((plugin) => plugin.id === "fs-mcp"), "scoped layout still discovered");
+  // Deregistering the unscoped plugin must not disturb the scoped tree.
+  const receipt = deregisterPlugin("plain-plugin", "test");
+  assert.equal(receipt.resulting_state.ok, true);
+  assert.equal(fs.existsSync(path.join(managed, "plain-plugin")), false);
+  assert.equal(fs.existsSync(path.join(managed, "@lifeaitools", "fs-mcp", "clauth-plugin.json")), true, "scoped package must be untouched");
+  const after = discoverPlugins();
+  assert.ok(after.plugins.find((plugin) => plugin.id === "fs-mcp" && plugin.state !== "missing_default"), "scoped plugin still discoverable after a sibling deregister");
+}));
+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");
+}));
+test("command arguments expand path tokens, not just cwd", () => {
+  // Regression: expandPathToken() was applied ONLY to `cwd`, so a manifest that
+  // named a root inside a COMMAND ARGUMENT shipped the literal string to the
+  // shell. dev-center's restart is
+  // ["pwsh","-NoProfile","-File","$LIFEAI_ENV/services/restart-dev-center.ps1"]
+  // and pwsh answered "not recognized as the name of a script file" with exit
+  // 64 -- a restart that fails while the service stays up, which reads as a
+  // flaky action rather than an unresolved path.
+  const oldEnv = process.env.LIFEAI_ENV;
+  const oldRoot = process.env.REGEN_ROOT;
+  process.env.LIFEAI_ENV = "C:/tmp/env-root";
+  process.env.REGEN_ROOT = "C:/tmp/regen-root";
+  try {
+    const plugin = validatePluginManifest(baseManifest("token-expansion", {
+      surfaces: [{
+        id: "primary",
+        destination: "local/clauth/pm2",
+        lifecycle_owner: "clauth",
+        port: 3003,
+        health: "/health",
+        restart: ["pwsh", "-NoProfile", "-File", "$LIFEAI_ENV/services/restart-dev-center.ps1"],
+        start: ["node", "${REGEN_ROOT}/scripts/start.mjs"],
+      }],
+    }), "clauth-plugin.json");
+    const s = plugin.surfaces[0];
+    assert.ok(!s.restart.some((a) => a.includes("$LIFEAI_ENV")),
+      `LIFEAI_ENV left unexpanded: ${JSON.stringify(s.restart)}`);
+    assert.ok(s.restart.some((a) => a.includes("C:/tmp/env-root")),
+      `LIFEAI_ENV did not expand to its value: ${JSON.stringify(s.restart)}`);
+    assert.ok(s.start.some((a) => a.includes("C:/tmp/regen-root")),
+      `REGEN_ROOT did not expand in a command arg: ${JSON.stringify(s.start)}`);
+  } finally {
+    if (oldEnv === undefined) delete process.env.LIFEAI_ENV; else process.env.LIFEAI_ENV = oldEnv;
+    if (oldRoot === undefined) delete process.env.REGEN_ROOT; else process.env.REGEN_ROOT = oldRoot;
+  }
+});
+test("registerPlugin resolves ${PACKAGE_ROOT} to the manifest's real origin", () => withTempSupervisor((root) => {
+  // An npm package installs at node_modules/@scope/name/ — a path no shipped
+  // manifest can hardcode. registerPlugin COPIES the manifest into the managed
+  // root, so by the time discoverPlugins() re-reads it the true origin is gone;
+  // the token therefore has to be resolved at registration and baked in.
+  //
+  // Without it, rdc-skills shipped cwd "C:/Dev/rdc-skills" with core +
+  // enable_default, so `npm i -g` on any other machine auto-enabled a CORE
+  // plugin pointing at a directory that does not exist there.
+  const origin = path.join(root, "pretend-node-modules", "@lifeaitools", "some-mcp");
+  fs.mkdirSync(origin, { recursive: true });
+  const manifestPath = path.join(origin, "clauth-plugin.json");
+  fs.writeFileSync(manifestPath, JSON.stringify(baseManifest("package-root-demo", {
+    surfaces: [{
+      id: "local",
+      destination: "local/clauth/pm2",
+      lifecycle_owner: "clauth",
+      port: 39114,
+      health: "/health",
+      cwd: "${PACKAGE_ROOT}",
+      start: ["node", "${PACKAGE_ROOT}/bin/server.mjs"],
+    }],
+  }), null, 2), "utf8");
+  const receipt = registerPlugin(manifestPath, "test");
+  assert.equal(receipt.resulting_state.ok, true, JSON.stringify(receipt.resulting_state));
+  const surface = listSurfaces().find((s) => s.plugin_id === "package-root-demo");
+  assert.ok(surface, "surface was not registered");
+  const expected = origin.replaceAll("\\", "/");
+  assert.equal(surface.cwd.replaceAll("\\", "/"), expected,
+    `cwd did not resolve to the manifest origin: ${surface.cwd}`);
+  assert.ok(surface.start.some((a) => a.replaceAll("\\", "/").includes(expected)),
+    `command arg did not resolve to the manifest origin: ${JSON.stringify(surface.start)}`);
+  assert.ok(!JSON.stringify(surface).includes("PACKAGE_ROOT"),
+    "an unexpanded PACKAGE_ROOT token survived into registered state");
+}));