@lifeaitools/clauth 2.10.2 → 2.15.3

package/cli/supervisor-registry.test.js

@@ -3,6 +3,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
+import { spawn } from "node:child_process";
+import { pathToFileURL } from "node:url";
 
 import {
   addTunnelRoute,
@@ -14,22 +16,24 @@ import {
   listSurfaces,
   probeAllSurfaceHealth,
   surfaceOpenUrl,
+  isGenuinelyIsolatedInstance,
   reconcileSurfaceHealth,
   registerPlugin,
+  resolveIsolatedSupervisorDir,
   runPluginAction,
   runSurfaceAction,
   removeTunnelRoute,
-  setPluginEnabled,
   shellQuote,
   supervisorHealth,
   syncPluginsFromRepos,
   SYNC_REPO_NAMES,
   SYNC_SKIP_STATES,
   validatePluginManifest,
+  withStateLock,
 } from "./supervisor-registry.js";
 import { isLoopbackAddress, supervisorLogDto, supervisorRequiresWriteToken } from "./commands/serve.js";
 
-function withTempSupervisor(fn) {
+async 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;
@@ -46,7 +50,7 @@ function withTempSupervisor(fn) {
   process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user-plugins");
   delete process.env.CLAUTH_PM2_HOME;
   try {
-    return fn(root);
+    return await fn(root);
   } finally {
     if (oldDir === undefined) delete process.env.CLAUTH_SUPERVISOR_DIR;
     else process.env.CLAUTH_SUPERVISOR_DIR = oldDir;
@@ -292,8 +296,6 @@ test("plugin test marks a private candidate and never creates a public route", (
   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);
@@ -354,7 +356,7 @@ test("reconcile falls back to the declared start command when restart reports a
   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) => {
+test("surface promotion requires the atomic health-checked path and rolls back on failed health", async () => withTempSupervisor(async (root) => {
   const managed = path.join(root, "managed");
   process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
   process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
@@ -364,16 +366,132 @@ test("surface promote and rollback never fall through to restart commands", () =
       name: "Demo surface",
       health: "http://127.0.0.1:3333/health",
       restart: [process.execPath, "--version"],
+      promote: [process.execPath, "--version"],
+      rollback: [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");
-  }
+  const direct = runSurfaceAction("demo:demo-surface", "promote");
+  assert.equal(direct.resulting_state.state, "atomic_promotion_required");
+  const { runSurfacePromotion } = await import("./supervisor-registry.js");
+  const healthy = await runSurfacePromotion("demo:demo-surface", "test", { fetchImpl: async () => ({ ok: true }) });
+  assert.equal(healthy.resulting_state.state, "promotion_healthy");
+  const rolledBack = await runSurfacePromotion("demo:demo-surface", "test", { fetchImpl: async () => ({ ok: false, status: 503 }) });
+  assert.equal(rolledBack.resulting_state.state, "promotion_rolled_back");
+  assert.equal(rolledBack.resulting_state.rollback_ok, true);
+}));
+
+// rdc:review finding (2026-09-02): a healthy promotion always reported
+// evidence "plugin_enabled=true" even when no plugin in state.json matched
+// surface.plugin_id -- the enabled write silently no-op'd (Array.map found no
+// match) while the receipt claimed success. Prove the receipt now tells the
+// truth in that case, and still reports the honest positive when a match
+// exists.
+test("surface promotion reports honestly whether the enabled write actually matched a plugin in state", () => withTempSupervisor(async (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"],
+      promote: [process.execPath, "--version"],
+      rollback: [process.execPath, "--version"],
+    }],
+  }));
+  discoverPlugins();
+  const { runSurfacePromotion } = await import("./supervisor-registry.js");
+
+  const matched = await runSurfacePromotion("demo:demo-surface", "test", { fetchImpl: async () => ({ ok: true }) });
+  assert.equal(matched.resulting_state.state, "promotion_healthy");
+  assert.equal(matched.resulting_state.evidence.includes("plugin_enabled=true"), true);
+
+  // Remove the plugin from state.json entirely, out from under the surface
+  // that still resolves fine via the manifest/registry -- reproduces the gap:
+  // promote can run against a surface whose plugin no longer has a state.json
+  // row (e.g. removed by a concurrent deregister).
+  const statePath = path.join(process.env.CLAUTH_SUPERVISOR_DIR, "state.json");
+  const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+  state.plugins = (state.plugins || []).filter((p) => p.id !== "demo");
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+
+  const unmatched = await runSurfacePromotion("demo:demo-surface", "test", { fetchImpl: async () => ({ ok: true }) });
+  assert.equal(unmatched.resulting_state.state, "promotion_healthy");
+  assert.equal(unmatched.resulting_state.evidence.includes("plugin_enabled=false plugin_not_found_in_state"), true);
+  assert.equal(unmatched.resulting_state.evidence.includes("plugin_enabled=true"), false);
+}));
+
+// rdc:review finding (2026-09-02), second pass -- CONFIRMED regression in the
+// first version of the withStateLock fix: runSurfacePromotion snapshotted the
+// whole `surfaces` array once at function entry and wrote it back WHOLESALE
+// on its pre-action swap and post-action revert. A concurrent write to a
+// DIFFERENT surface (e.g. reconcileSurfaceHealth's health update) landing
+// during promotion's own await gap (the health probe) was silently
+// discarded the moment promotion's revert-write landed -- reopening, in a
+// different shape, the exact class of race withStateLock was written to
+// close. Fixed by routing every surface mutation in runSurfacePromotion
+// through updateSurfaceState() (a single-entity merge-patch) instead of a
+// whole-array snapshot/restore. This test reproduces the exact interleaving:
+// a promotion paused mid-health-probe, a concurrent reconcile completing a
+// write to an UNRELATED surface during that pause, then the promotion
+// finishing -- and asserts the concurrent write survives.
+test("surface promotion does not clobber a concurrent write to a DIFFERENT surface made during its health-probe pause", () => withTempSupervisor(async (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", {
+    core: true,
+    enable_default: true,
+    surfaces: [
+      {
+        id: "demo-surface",
+        name: "Demo surface",
+        health: "http://127.0.0.1:3333/health",
+        restart: [process.execPath, "--version"],
+        promote: [process.execPath, "--version"],
+        rollback: [process.execPath, "--version"],
+      },
+      {
+        id: "other-surface",
+        name: "Other surface",
+        destination: "local/clauth/pm2",
+        lifecycle_owner: "clauth",
+        port: 39115,
+        health: "/health",
+        restart: [process.execPath, "--version"],
+      },
+    ],
+  }));
+  discoverPlugins();
+  const { runSurfacePromotion } = await import("./supervisor-registry.js");
+
+  let releasePromotionHealthGate;
+  const promotionHealthGate = new Promise((resolve) => { releasePromotionHealthGate = resolve; });
+  const promotionPromise = runSurfacePromotion("demo:demo-surface", "test", {
+    fetchImpl: async () => { await promotionHealthGate; return { ok: true }; },
+  });
+
+  // Give the promotion's own microtask chain room to reach its health-probe
+  // await (its pre-action swap + runSurfaceAction already completed
+  // synchronously by this point; it is now genuinely blocked on the gate).
+  await new Promise((resolve) => setImmediate(resolve));
+  await new Promise((resolve) => setImmediate(resolve));
+
+  // Concurrent write to a DIFFERENT surface, completing entirely while the
+  // promotion above is still paused.
+  await reconcileSurfaceHealth({ fetchImpl: async () => ({ ok: true }) });
+  const otherAfterReconcile = listSurfaces().find((s) => s.id === "other-surface");
+  assert.equal(otherAfterReconcile.last_health_ok, true, "reconcile's own write should have landed before the promotion resumes");
+
+  releasePromotionHealthGate();
+  const result = await promotionPromise;
+  assert.equal(result.resulting_state.state, "promotion_healthy");
+
+  const otherAfterPromotion = listSurfaces().find((s) => s.id === "other-surface");
+  assert.equal(otherAfterPromotion.last_health_ok, true, "promotion's own surface writes must not revert a concurrent write to a different surface");
 }));
 
 test("health reconciliation marks a failed clauth surface and repairs it through reconcile", async () => {
@@ -679,6 +797,37 @@ test("registerPlugin validates, writes into the managed root, and discovers the
   fs.rmSync(sourceDir, { recursive: true, force: true });
 }));
 
+test("registerPlugin restarts a clauth-owned surface when the manifest actually changed, and skips the restart when unchanged", () => withTempSupervisor((root) => {
+  // Dave: "plugin install pings clauth to reread -- it should restart the pm2
+  // -- fix the bug". A changed manifest (a version bump, a fresh npm install)
+  // used to only re-run discovery -- the live PM2 process kept serving the
+  // OLD code until something unrelated happened to restart 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-restart-"));
+  const manifestPath = path.join(sourceDir, "clauth-plugin.json");
+  fs.writeFileSync(manifestPath, JSON.stringify(baseManifest("restart-on-change-demo")), "utf8");
+
+  const first = registerPlugin(manifestPath, "test");
+  assert.equal(first.resulting_state.state, "registered");
+  assert.equal(first.resulting_state.restarted.length, 1, "a fresh registration must attempt to restart its clauth-owned surface");
+  assert.equal(first.resulting_state.restarted[0].surface_id, "restart-on-change-demo-surface");
+  assert.equal(first.resulting_state.restarted[0].ok, true, "the fixture's restart command (node --version) must succeed");
+
+  const unchanged = registerPlugin(manifestPath, "test");
+  assert.equal(unchanged.resulting_state.state, "unchanged");
+  assert.equal(unchanged.resulting_state.restarted.length, 0, "re-registering identical content must NOT restart a live service for nothing");
+
+  fs.writeFileSync(manifestPath, JSON.stringify(baseManifest("restart-on-change-demo", { version: "1.0.1" })), "utf8");
+  const changed = registerPlugin(manifestPath, "test");
+  assert.equal(changed.resulting_state.state, "registered");
+  assert.equal(changed.resulting_state.restarted.length, 1, "a genuine content change must restart the surface again");
+  assert.equal(changed.resulting_state.restarted[0].ok, true);
+
+  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
@@ -710,6 +859,75 @@ test("validatePluginManifest rejects an all-dots plugin or surface id", () => {
   }), "clauth-plugin.json"), /may not be all dots/);
 });
 
+// rdc:review finding (2026-09-02): the charset regex validatePluginManifest()
+// uses is not sufficient on Windows -- CON/NUL/AUX/PRN/COM1-9/LPT1-9 pass the
+// charset check but are OS-reserved device names, so mkdirSync/writeFileSync
+// against a path ending in one throws or targets the device instead of a real
+// directory. Covers both call sites inside validatePluginManifest (manifest.id
+// via normalizePlugin, surface.id via normalizeSurface) plus deregisterPlugin's
+// own duplicated id check, all three of which are meant to be kept in lockstep.
+// rdc:review finding (2026-09-02): the two RESERVED_DEVICE_NAMES copies
+// (here, and standalone/install-clauth-plugin.mjs) are asserted "kept in
+// sync deliberately" by comment alone -- no test compared the two literal
+// regex sources, so a future edit to one gives no mechanical signal the
+// other also needs it. Reads both files as TEXT (not import -- the
+// standalone script does real fs/network work at module-load time from its
+// own cwd, which a test must not trigger) and compares the literal regex
+// source string.
+test("RESERVED_DEVICE_NAMES stays byte-identical between supervisor-registry.js and the standalone installer", () => {
+  const extract = (filePath) => {
+    const src = fs.readFileSync(filePath, "utf8");
+    const match = src.match(/const RESERVED_DEVICE_NAMES = (\/.*\/i);/);
+    assert.ok(match, `RESERVED_DEVICE_NAMES declaration not found in ${filePath}`);
+    return match[1];
+  };
+  const inRegistry = extract(path.join(process.cwd(), "cli", "supervisor-registry.js"));
+  const inInstaller = extract(path.join(process.cwd(), "standalone", "install-clauth-plugin.mjs"));
+  assert.equal(inRegistry, inInstaller, "the two RESERVED_DEVICE_NAMES copies have drifted apart");
+});
+
+test("validatePluginManifest rejects Windows-reserved device names, case-insensitively, at registration", () => {
+  for (const reserved of ["CON", "nul", "Aux", "prn", "COM1", "lpt9"]) {
+    assert.throws(
+      () => validatePluginManifest(baseManifest(reserved, {}), "clauth-plugin.json"),
+      /reserved device name/,
+      `manifest.id=${reserved} should be rejected`,
+    );
+    assert.throws(
+      () => validatePluginManifest(baseManifest("valid-id", {
+        surfaces: [{ id: reserved, lifecycle_owner: "clauth" }],
+      }), "clauth-plugin.json"),
+      /reserved device name/,
+      `surface.id=${reserved} should be rejected`,
+    );
+  }
+  // Names that merely CONTAIN a reserved token are fine -- only an exact
+  // (case-insensitive) match to the whole id is a real device name.
+  assert.doesNotThrow(() => validatePluginManifest(baseManifest("nully-plugin", {}), "clauth-plugin.json"));
+  assert.doesNotThrow(() => validatePluginManifest(baseManifest("console-app", {}), "clauth-plugin.json"));
+});
+
+// rdc:review finding (2026-09-02), confirmed regression + fix: the first
+// version of this check also rejected reserved-name ids in deregisterPlugin's
+// own Guard 1 -- meaning a plugin that somehow got registered with such an id
+// (pre-upgrade, or by any other path) could never be removed again, under
+// force:true included, with no remediation. Live-probed the original crash
+// premise directly on this host (Node fs.mkdirSync/writeFileSync for
+// directories literally named con/nul/aux/prn/com1/lpt1 all succeeded, no
+// throw, no device redirection) -- the reserved-name check is retained as
+// low-cost defensive hygiene against NEW registrations only; removal must
+// never be blocked by it.
+test("deregisterPlugin does not reject a Windows-reserved-device-name id -- removal is never blocked by this check", () => 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 receipt = deregisterPlugin("NUL", "test");
+  assert.notEqual(receipt.resulting_state.state, "invalid_plugin_id");
+  // No such plugin is registered in this fixture -- safe no-op, same
+  // contract as "deregisterPlugin on an unregistered id is a safe no-op".
+  assert.equal(receipt.resulting_state.ok, true);
+}));
+
 test("registerPlugin rejects an invalid manifest without writing anything", () => withTempSupervisor((root) => {
   const managed = path.join(root, "managed");
   process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
@@ -726,8 +944,16 @@ test("registerPlugin rejects an invalid manifest without writing anything", () =
   fs.rmSync(sourceDir, { recursive: true, force: true });
 }));
 
-// Builds throwaway product repos laid out like the real ones, so a sync sweep
+// Builds a throwaway product repo laid out like the real one, so a sync sweep
 // exercises the real relative manifest paths without reading a live checkout.
+//
+// rdc-skills is deliberately NOT part of PRODUCT_REPO_MANIFESTS (and so not
+// part of `roots` below) -- it is npm-published and self-registers via its
+// own postinstall against the INSTALLED package, never via this checkout
+// sweep (see the comment on PRODUCT_REPO_MANIFESTS). `rdcSkills` is still
+// returned as a plain unrelated directory: several tests below use it purely
+// as a stand-in for "some directory that is not a known repo name", to prove
+// an unrecognized override is reported rather than silently dropped.
 function withTempProductRepos(fn) {
   const base = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-sync-repos-"));
   const regenRoot = path.join(base, "regen-root");
@@ -740,11 +966,12 @@ function withTempProductRepos(fn) {
   };
   writeManifest(regenRoot, "packages/codeflow/clauth-plugin.json", baseManifest("codeflow-mcp"));
   writeManifest(regenRoot, "apps/dev-center/clauth-plugin.json", baseManifest("dev-center"));
+  writeManifest(regenRoot, "apps/codeflow-explorer/clauth-plugin.json", baseManifest("codeflow-explorer"));
   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 } });
+    return fn({ base, regenRoot, rdcSkills, writeManifest, roots: { "regen-root": regenRoot } });
   } finally {
     fs.rmSync(base, { recursive: true, force: true });
   }
@@ -767,22 +994,19 @@ test("plugin sync inherits registerPlugin idempotence — a second sweep reports
   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.
+test("plugin sync warns and continues over a missing repo root instead of throwing", () => withTempSupervisor(() => withTempProductRepos(({ base }) => {
+  // A box that never checked out regen-root must still return a receipt per
+  // manifest instead of throwing.
   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");
+    receipts = syncPluginsFromRepos({ "regen-root": absent }, "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.length, 5, "all five 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 }) => {
@@ -797,7 +1021,7 @@ test("plugin sync registers the remaining manifests when one is malformed", () =
   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"]) {
+  for (const id of ["codeflow-mcp", "codeflow-explorer", "regen-media", "web-research"]) {
     assert.ok(ids.has(id), `${id} must still be registered`);
   }
 })));
@@ -814,7 +1038,7 @@ test("deregisterPlugin removes only the named plugin and leaves siblings intact"
   assert.equal(receipt.resulting_state.cleanup[0].ok, true);
   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"]) {
+  for (const sibling of ["codeflow-mcp", "dev-center", "codeflow-explorer", "regen-media"]) {
     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
@@ -1039,25 +1263,30 @@ test("plugin sync reports an unknown repo-root override instead of silently swee
   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"]);
+  assert.deepEqual([...SYNC_REPO_NAMES].sort(), ["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.
+  // rdc-skills is passed alongside the bad root purely as an unrecognized
+  // override key -- it must be reported (unknown_repo_name), not thrown, and
+  // its presence must not stop regen-root's own manifests from still being
+  // reported too.
   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.length, 6, "every attempted manifest plus the rejected override still yields a receipt");
     assert.equal(
       receipts.filter((entry) => entry.repo === "regen-root" && entry.state === "repo_root_unknown").length,
-      4,
+      5,
       `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");
+    assert.equal(skills.ok, false, "rdc-skills is not a known sync repo name -- it must be rejected, not swept");
+    assert.equal(skills.state, "unknown_repo_name");
   }
 })));
 
@@ -1233,3 +1462,208 @@ test("surfaceOpenUrl never points a browser at an MCP transport endpoint", () =>
   );
   assert.equal(surfaceOpenUrl({}), null);
 });
+
+// rdc:review finding (2026-09-02), part 3 of 3: `--isolated` never set
+// CLAUTH_SUPERVISOR_DIR, so an isolated instance shared state.json with the
+// live daemon by default. resolveIsolatedSupervisorDir is the pure decision
+// extracted out of cli/commands/serve.js's actionForeground so it's testable
+// without spawning a server.
+test("resolveIsolatedSupervisorDir picks a port-scoped dir, and never overrides an explicit CLAUTH_SUPERVISOR_DIR", () => {
+  const a = resolveIsolatedSupervisorDir(52440, undefined);
+  const b = resolveIsolatedSupervisorDir(53137, undefined);
+  assert.notEqual(a, b, "two different ports must not resolve to the same dir");
+  assert.match(a, /clauth-isolated/);
+  assert.match(a, /52440/);
+  assert.equal(resolveIsolatedSupervisorDir(52440, "C:\\custom\\explicit-dir"), "C:\\custom\\explicit-dir");
+});
+
+// CRITICAL rdc:review finding (2026-09-02), confirmed regression: the first
+// version of the isolation fix called resolveIsolatedSupervisorDir() whenever
+// `opts.isolated` was true, with no further check. actionSupervisor() in
+// cli/commands/serve.js unconditionally sets `opts.isolated = true` for an
+// unrelated reason (skip vault password auth on the internal supervisor child
+// process every normal `clauth serve start` spawns). The result: the REAL
+// production supervisor's state.json got silently redirected to an empty
+// temp dir on every normal boot, disabling the whole health-reconcile/
+// auto-repair loop with no error. isGenuinelyIsolatedInstance() is the actual
+// gate now used in serve.js.
+//
+// CORRECTED (4th review round): the first fix keyed this off `port ===
+// supervisorPort`, which collided with test/serve-http-routes.test.mjs's own
+// sanctioned pattern of setting CLAUTH_SUPERVISOR_PORT to match its --port --
+// structurally identical from the outside, so a stricter port-based refusal
+// elsewhere broke 39 tests. This version keys off the unambiguous
+// __CLAUTH_SUPERVISOR_DAEMON marker ensureSupervisorStarted() already sets
+// (and nothing previously read) instead of port matching.
+test("isGenuinelyIsolatedInstance excludes the real internal daemon (via its marker) even when isolated=true, and includes every other isolated invocation", () => {
+  // The exact regressed case: actionSupervisor() sets isolated=true for its
+  // automatic boot, which DOES carry the internal-daemon marker -- must NOT
+  // be treated as a throwaway isolated instance.
+  assert.equal(isGenuinelyIsolatedInstance(true, true), false);
+  // Any other isolated invocation (serve test, a manual --isolated --port
+  // run, or a test fixture deliberately constructing a supervisor-port
+  // scenario) never carries the marker and is a genuine throwaway instance.
+  assert.equal(isGenuinelyIsolatedInstance(true, false), true);
+  // Not isolated at all -- never redirect, regardless of the marker.
+  assert.equal(isGenuinelyIsolatedInstance(false, false), false);
+  assert.equal(isGenuinelyIsolatedInstance(false, true), false);
+});
+
+// rdc:review finding (2026-09-02), part 1 of 3: state.json's read-modify-write
+// had no lock. withStateLock is the in-process promise-chained mutex added to
+// close it. This test proves the primitive itself provides real mutual
+// exclusion using the textbook counter-race shape (read, await, increment,
+// write) -- the exact shape an async critical section with a network/health
+// probe in the middle has. Without the lock this loses updates (every
+// concurrent reader sees the same pre-race value); with it, none are lost.
+// withStateLock now does real cross-process file I/O (a lockfile alongside
+// state.json) as well as in-process serialization -- MUST run under
+// withTempSupervisor. Without it, every withStateLock call below reads
+// CLAUTH_SUPERVISOR_DIR from whatever the ambient environment happens to be
+// (unset -> the LIVE %APPDATA%/clauth/supervisor/ directory), and this test
+// would create/delete a real state.lock file there.
+test("withStateLock serializes overlapping async critical sections -- no lost updates", () => withTempSupervisor(async () => {
+  let counter = 0;
+  const N = 25;
+  async function unsafeIncrement() {
+    const seen = counter;
+    await new Promise((resolve) => setImmediate(resolve)); // force a real interleaving window
+    counter = seen + 1;
+  }
+  async function lockedIncrement() {
+    return withStateLock(async () => {
+      const seen = counter;
+      await new Promise((resolve) => setImmediate(resolve));
+      counter = seen + 1;
+    });
+  }
+
+  counter = 0;
+  await Promise.all(Array.from({ length: N }, () => unsafeIncrement()));
+  const unsafeResult = counter;
+  assert.ok(unsafeResult < N, `expected the unlocked version to lose updates (got ${unsafeResult}/${N} -- if this ever equals ${N}, the interleaving window isn't forcing a real race and this test needs a stronger delay)`);
+
+  counter = 0;
+  await Promise.all(Array.from({ length: N }, () => lockedIncrement()));
+  assert.equal(counter, N, "withStateLock must serialize every critical section -- zero lost updates");
+}));
+
+// rdc:review finding (2026-09-02), fourth pass -- confirmed, material to the
+// prior interview: an in-process mutex provides ZERO protection between two
+// separate OS processes, and `clauth serve start`'s STANDARD topology
+// (ensureSupervisorStarted's real detached spawn() for the :52439 supervisor
+// child, sharing state.json with the main :52437 daemon by design) is
+// exactly that -- not an edge case. The in-process test above cannot catch
+// this; it never leaves one process. This test spawns two REAL, separate
+// Node processes racing to increment a shared counter file, each increment
+// guarded by the real, exported withStateLock -- proving the cross-process
+// lockfile (acquireCrossProcessStateLock/releaseCrossProcessStateLock)
+// actually serializes across process boundaries, not just within one.
+test("withStateLock provides real cross-process mutual exclusion, not just in-process", () => withTempSupervisor(async (root) => {
+  const counterPath = path.join(root, "counter.txt");
+  fs.writeFileSync(counterPath, "0");
+  const registryUrl = pathToFileURL(path.join(process.cwd(), "cli", "supervisor-registry.js")).href;
+  const workerPath = path.join(root, "cross-process-lock-worker.mjs");
+  fs.writeFileSync(workerPath, `
+import { withStateLock } from ${JSON.stringify(registryUrl)};
+import fs from "node:fs";
+const counterPath = process.env.COUNTER_PATH;
+const increments = Number(process.env.INCREMENTS);
+async function run() {
+  for (let i = 0; i < increments; i++) {
+    await withStateLock(async () => {
+      const current = Number(fs.readFileSync(counterPath, "utf8"));
+      // Force a real interleaving window -- without cross-process mutual
+      // exclusion, the other process's concurrent read+write lands here.
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      fs.writeFileSync(counterPath, String(current + 1));
+    });
+  }
+}
+run().then(() => process.exit(0)).catch((err) => { console.error(err); process.exit(1); });
+`);
+
+  const INCREMENTS_PER_WORKER = 12;
+  const env = { ...process.env, CLAUTH_SUPERVISOR_DIR: root, COUNTER_PATH: counterPath, INCREMENTS: String(INCREMENTS_PER_WORKER) };
+  const spawnWorker = () => new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [workerPath], { env, stdio: ["ignore", "inherit", "inherit"] });
+    child.on("error", reject);
+    child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`cross-process lock worker exited ${code}`))));
+  });
+
+  await Promise.all([spawnWorker(), spawnWorker()]);
+  const final = Number(fs.readFileSync(counterPath, "utf8"));
+  assert.equal(final, INCREMENTS_PER_WORKER * 2, "withStateLock must serialize across two real OS processes sharing CLAUTH_SUPERVISOR_DIR -- zero lost updates");
+}));
+
+// rdc:review finding (2026-09-02), 4th independent round, empirically
+// reproduced against an instrumented mirror of the shipped algorithm: the
+// PREVIOUS reclaim mechanism (unlinkSync a stale lock, then loop back to
+// retry openSync('wx')) was not atomic -- multiple waiters racing the SAME
+// stale lock could each independently decide to reclaim and each
+// independently succeed, becoming simultaneous holders (2-3 in 5 of 12 runs
+// in the reviewer's repro). This test exercises exactly that scenario
+// against the REAL shipped code (not a mirror): pre-seeds a genuinely stale
+// lock (dead pid, 60s old -- past STATE_LOCK_STALE_MS), then spawns several
+// real processes SIMULTANEOUSLY, all of which must race the same stale
+// reclaim on their very first acquisition attempt. The current algorithm
+// closes this via an atomic renameSync claim -- only one racing process can
+// ever successfully rename a given stale directory instance away.
+// rdc:review finding (2026-09-02), 5th round: three consecutive hand-rolled
+// versions of this lock each had a distinct real concurrency bug (see
+// withStateLock's own header comment in supervisor-registry.js for the full
+// history) -- replaced with proper-lockfile, a mature library, rather than a
+// 4th hand-rolled attempt. Its on-disk shape and staleness mechanism are
+// different from any prior version: it locks `<file>.lock` (here,
+// state.json.lock, not state.lock) and judges staleness via the lock
+// directory's own mtime (continuously refreshed while a holder is active),
+// not a point-in-time pid/timestamp record inside it. This test is updated
+// to match that real contract rather than testing an obsolete on-disk shape.
+test("withStateLock's stale-lock reclaim is atomic under multiple processes racing the SAME abandoned lock", () => withTempSupervisor(async (root) => {
+  const counterPath = path.join(root, "counter.txt");
+  fs.writeFileSync(counterPath, "0");
+
+  // Pre-seed a stale lock at proper-lockfile's real path (state.json.lock,
+  // sibling to state.json -- see stateLockTargetPath()) with an mtime well
+  // past the stale threshold (30s) -- the one signal proper-lockfile's own
+  // isLockStale() checks, so this is unambiguously reclaimable by design.
+  const lockPath = path.join(root, "state.json.lock");
+  fs.mkdirSync(lockPath, { recursive: true });
+  const staleTime = new Date(Date.now() - 60000);
+  fs.utimesSync(lockPath, staleTime, staleTime);
+
+  const registryUrl = pathToFileURL(path.join(process.cwd(), "cli", "supervisor-registry.js")).href;
+  const workerPath = path.join(root, "stale-reclaim-worker.mjs");
+  fs.writeFileSync(workerPath, `
+import { withStateLock } from ${JSON.stringify(registryUrl)};
+import fs from "node:fs";
+const counterPath = process.env.COUNTER_PATH;
+const increments = Number(process.env.INCREMENTS);
+async function run() {
+  for (let i = 0; i < increments; i++) {
+    await withStateLock(async () => {
+      const current = Number(fs.readFileSync(counterPath, "utf8"));
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      fs.writeFileSync(counterPath, String(current + 1));
+    });
+  }
+}
+run().then(() => process.exit(0)).catch((err) => { console.error(err); process.exit(1); });
+`);
+
+  const WORKER_COUNT = 6;
+  const INCREMENTS_PER_WORKER = 5;
+  const env = { ...process.env, CLAUTH_SUPERVISOR_DIR: root, COUNTER_PATH: counterPath, INCREMENTS: String(INCREMENTS_PER_WORKER) };
+  const spawnWorker = () => new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [workerPath], { env, stdio: ["ignore", "inherit", "inherit"] });
+    child.on("error", reject);
+    child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`stale-reclaim worker exited ${code}`))));
+  });
+
+  // All WORKER_COUNT processes launched together -- their first acquisition
+  // attempt genuinely races the same pre-seeded stale lock simultaneously,
+  // which is the exact condition the prior algorithm failed under.
+  await Promise.all(Array.from({ length: WORKER_COUNT }, () => spawnWorker()));
+  const final = Number(fs.readFileSync(counterPath, "utf8"));
+  assert.equal(final, WORKER_COUNT * INCREMENTS_PER_WORKER, "stale-lock reclaim must be atomic -- zero lost updates even when multiple processes race the same abandoned lock");
+}));

package/cli/watchdog-registry.js

@@ -66,6 +66,15 @@ function validateCommand(command, field) {
 export function validateWatchdogService(service) {
   if (!service || typeof service !== "object") throw new Error("service must be an object");
   if (!service.id || typeof service.id !== "string") throw new Error("service.id is required");
+  // rdc:review finding (2026-09-02): shaped identically to the id checks in
+  // cli/supervisor-registry.js (validatePluginManifest, normalizeSurface),
+  // which also reject Windows-reserved device names (con/nul/aux/prn/
+  // com1-9/lpt1-9) at registration. NOT extended here deliberately: unlike
+  // those, service.id is not used to derive a filesystem path anywhere in
+  // this file today, so there is nothing for a reserved name to collide
+  // with. Revisit if a future change starts deriving a per-service path from
+  // service.id -- that would reintroduce the same defect class this comment
+  // exists to flag before it does.
   if (!/^[a-zA-Z0-9_.-]+$/.test(service.id)) throw new Error("service.id may contain only letters, numbers, dot, underscore, and dash");
   if (!service.label || typeof service.label !== "string") throw new Error("service.label is required");
   if (!VALID_KINDS.has(service.kind)) throw new Error(`service.kind must be one of ${[...VALID_KINDS].join(", ")}`);