@lifeaitools/clauth 2.15.3 → 2.15.5

package/cli/supervisor-registry.js

@@ -3,9 +3,6 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { createSerializedExecutor } from "./ops/serialized-executor.js";
-import { atomicWriteTextSync } from "./services/file-io.js";
-import lockfile from "proper-lockfile";
 
 const SCHEMA = "lifeai.plugin.v1";
 const DEFAULT_TIMEOUT_MS = 3000;
@@ -22,29 +19,6 @@ const DEFAULT_HEALTH_RECONCILE_INTERVAL_MS = 10000;
 const DEFAULT_HEALTH_TIMEOUT_MS = 2500;
 const HEALTH_RECONCILE_COOLDOWN_MS = 15000;
 const DOCUMENTATION_FIELDS = ["architecture", "operator_guide", "install", "runbook", "tool_reference", "release", "agent_context"];
-// rdc:review finding (2026-09-02): the charset regex used at manifest-id and
-// surface.id validation (validatePluginManifest, two call sites) accepts
-// Windows reserved device names (CON, NUL, AUX, PRN, COM1-9, LPT1-9) --
-// historically MS-DOS device names special-cased by the Win32 namespace.
-//
-// CORRECTION (2026-09-02, independent review): this comment previously
-// claimed "fs.mkdirSync/writeFileSync/rmSync against a path ending in one of
-// these throws or silently targets the device instead of a real directory" --
-// live-probed directly on this host (current dev/deploy platform: Windows,
-// the Node version this process runs under) and that claim is FALSE.
-// `fs.mkdirSync`/`fs.writeFileSync` for directories/files literally named
-// con/nul/aux/prn/com1/lpt1 all succeeded with no throw and no device
-// redirection. The motivating crash does not reproduce via Node's fs APIs on
-// the platform clauth actually runs on. Retained anyway as low-cost defensive
-// hygiene against a name class other tools (cmd.exe, older shells, or future
-// code that shells out using the raw id) could still special-case -- but
-// ONLY at registration (creating a NEW entry). deregisterPlugin's own id
-// check deliberately does NOT include this rule: removal must never refuse
-// to remove something that already exists (see its Guard 1 comment for why
-// blocking removal here was a real, verified regression with no
-// compensating benefit). Mirrored client-side in
-// standalone/install-clauth-plugin.mjs, registration-only there too.
-const RESERVED_DEVICE_NAMES = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
 
 function hasMcpToken(value) {
   return /(^|[^a-z0-9])mcp([^a-z0-9]|$)/i.test(String(value || ""));
@@ -120,53 +94,6 @@ export function getClauthPm2Home() {
   return path.join(getSupervisorDir(), "pm2-home");
 }
 
-// rdc:review finding (2026-09-02): `clauth serve foreground --isolated` never
-// set CLAUTH_SUPERVISOR_DIR, so an isolated test instance shared the SAME
-// state.json as the live :52437 daemon by default -- the "verify against an
-// isolated instance first" workflow documented in
-// .claude/rules/clauth-endpoints.md did not actually isolate state. Pure
-// function (no env reads) so it's directly testable: given what
-// CLAUTH_SUPERVISOR_DIR already is (undefined if unset) and the port an
-// isolated instance is starting on, returns the dir that instance should use.
-// Port-scoped so two isolated instances on different ports never collide.
-// Returns the existing value unchanged when the caller already set one
-// explicitly -- an operator who deliberately points CLAUTH_SUPERVISOR_DIR
-// somewhere for a specific test still wins.
-export function resolveIsolatedSupervisorDir(port, existingEnvValue) {
-  if (existingEnvValue) return existingEnvValue;
-  return path.join(os.tmpdir(), "clauth-isolated", `port-${port}`);
-}
-
-// CRITICAL follow-up finding (2026-09-02, independent review of the fix
-// above): `opts.isolated` in cli/commands/serve.js is OVERLOADED --
-// actionSupervisor() unconditionally sets it true for an unrelated reason
-// (skip vault password auth on the internal supervisor child every normal
-// `clauth serve start` spawns). Calling resolveIsolatedSupervisorDir()
-// whenever `isolated` is true, with no further check, redirected the REAL
-// production supervisor's state.json to an empty temp dir on every normal
-// boot -- silently disabling the health-reconcile/auto-repair loop with no
-// error. This predicate is the actual gate: the one real internal supervisor
-// process never redirects, regardless of its own isolated/auth-skip flag;
-// any OTHER isolated invocation (serve test, a manual --isolated --port run)
-// is a genuine throwaway instance and should.
-//
-// CORRECTION (2026-09-02, 4th review round): the first version of this gate
-// keyed off `port === supervisorPort`, the same signal
-// test/serve-http-routes.test.mjs's own sanctioned pattern deliberately
-// manufactures (setting CLAUTH_SUPERVISOR_PORT to match its own --port, to
-// exercise the write-token-bypass logic) -- structurally identical to the
-// real internal daemon from the outside, which is why an attempt to ALSO
-// refuse `--isolated` on that port broke 39 passing tests and had to be
-// reverted. ensureSupervisorStarted() already sets an unambiguous marker
-// (__CLAUTH_SUPERVISOR_DAEMON=1) on the ONE process it spawns for exactly
-// this reason -- it was set and never read. Using it here instead of port
-// matching means this gate now answers the actual question ("is this the
-// automatic internal daemon") rather than a proxy for it that a test
-// fixture can innocently collide with.
-export function isGenuinelyIsolatedInstance(isolated, isInternalSupervisorDaemon) {
-  return !!isolated && !isInternalSupervisorDaemon;
-}
-
 function file(name) {
   return path.join(getSupervisorDir(), name);
 }
@@ -180,35 +107,9 @@ function readJson(filePath, fallback) {
   }
 }
 
-// rdc:review finding (2026-09-02), 4th independent round, empirically
-// reproduced: a plain fs.writeFileSync is NOT atomic -- an UNLOCKED reader
-// (findSurface/listSurfaces/discoverPlugins's own `previous` read, none of
-// which are lock-protected even after this same round's mutator-coverage
-// fix) can observe a torn, truncated, or empty file mid-write. Measured: one
-// process doing ~3500 locked writes of a realistic-sized state.json while
-// two unrelated processes did unlocked reads saw EMPTY content on 16-17% of
-// reads -- not a rare edge case. discoverPlugins() runs unconditionally on
-// every boot and reads via `previous = loadSupervisorState()`; landing in
-// that window silently resets every plugin's enabled flag and drops the
-// operations audit log, then WRITES THAT BACK -- a transient read glitch
-// becomes permanent data loss. Fixed here, at the write layer, rather than
-// requiring every reader to coordinate: temp-file + rename is atomic --
-// any reader, locked or not, sees either the complete OLD file or the
-// complete NEW file, never a partial one. This closes the finding
-// unconditionally, independent of which callers do or don't hold the lock.
-//
-// rdc:review finding (peer session, 2026-09-02): this hand-rolled the exact
-// same mkdir+temp+write+rename contract cli/services/file-io.js's
-// atomicWriteText() already implements (that file's own header: split out of
-// serve.js specifically as a shared fs_* primitive) -- and two MORE
-// independent copies already existed (cli/ops/job-store.js,
-// standalone/fs-mcp/lib/webdav-config.js). atomicWriteText is async
-// (fs/promises); every writeJson caller in this file is synchronous, so a
-// direct swap wasn't free -- added atomicWriteTextSync as its sync twin in
-// file-io.js instead of shipping a fourth reimplementation of the same
-// fragile contract.
 function writeJson(filePath, value) {
-  atomicWriteTextSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
 
 function appendJsonl(filePath, value) {
@@ -231,17 +132,15 @@ function healthUrlForSurface(surface) {
   return `http://127.0.0.1:${surface.port}${String(surface.health).startsWith("/") ? surface.health : `/${surface.health}`}`;
 }
 
-async function updateSurfaceState(surfaceId, patch) {
-  return withStateLock(() => {
-    const state = loadSupervisorState();
-    state.surfaces = (state.surfaces || []).map((surface) => (
-      `${surface.plugin_id}:${surface.id}` === surfaceId || surface.id === surfaceId
-        ? { ...surface, ...patch }
-        : surface
-    ));
-    saveSupervisorState(state);
-    return state.surfaces.find((surface) => `${surface.plugin_id}:${surface.id}` === surfaceId || surface.id === surfaceId) || null;
-  });
+function updateSurfaceState(surfaceId, patch) {
+  const state = loadSupervisorState();
+  state.surfaces = (state.surfaces || []).map((surface) => (
+    `${surface.plugin_id}:${surface.id}` === surfaceId || surface.id === surfaceId
+      ? { ...surface, ...patch }
+      : surface
+  ));
+  saveSupervisorState(state);
+  return state.surfaces.find((surface) => `${surface.plugin_id}:${surface.id}` === surfaceId || surface.id === surfaceId) || null;
 }
 
 function appendSupervisorEvent(event) {
@@ -283,19 +182,19 @@ export async function reconcileSurfaceHealth({ fetchImpl = globalThis.fetch, tim
     const error = health.error;
 
     if (healthy) {
-      await updateSurfaceState(id, { state: "current", last_health_at: observedAt, last_health_ok: true, last_health_error: null });
+      updateSurfaceState(id, { state: "current", last_health_at: observedAt, last_health_ok: true, last_health_error: null });
       inspected.push({ surface_id: id, state: "healthy", observed_at: observedAt });
       continue;
     }
 
     const lastAttempt = Date.parse(surface.last_reconcile_at || "") || 0;
     if (Date.now() - lastAttempt < HEALTH_RECONCILE_COOLDOWN_MS) {
-      await updateSurfaceState(id, { state: "unavailable", last_health_at: observedAt, last_health_ok: false, last_health_error: error });
+      updateSurfaceState(id, { state: "unavailable", last_health_at: observedAt, last_health_ok: false, last_health_error: error });
       inspected.push({ surface_id: id, state: "unavailable", error, cooldown: true, observed_at: observedAt });
       continue;
     }
 
-    await updateSurfaceState(id, {
+    updateSurfaceState(id, {
       state: "unavailable",
       last_health_at: observedAt,
       last_health_ok: false,
@@ -307,7 +206,7 @@ export async function reconcileSurfaceHealth({ fetchImpl = globalThis.fetch, tim
     const commandCompleted = receipt?.resulting_state?.ok === true;
     const postHealth = commandCompleted ? await probeSurfaceHealth(url, fetchImpl, timeoutMs) : { healthy: false, error: receipt?.resulting_state?.state || "reconcile_failed" };
     const repaired = commandCompleted && postHealth.healthy;
-    await updateSurfaceState(id, {
+    updateSurfaceState(id, {
       state: repaired ? "current" : "unavailable",
       last_health_at: now(),
       last_health_ok: repaired,
@@ -414,41 +313,25 @@ export async function probeAllSurfaceHealth({ fetchImpl = globalThis.fetch, time
   // load-modify-save per call, so N concurrent probes calling it would each
   // save a copy loaded before its siblings finished — last writer wins and the
   // rest are silently lost.
-  //
-  // rdc:review finding (2026-09-02): this write was outside withStateLock --
-  // the sibling to the race class that mutex exists to close, left open here.
-  // Routed through it for consistency with every other state.json mutator in
-  // this file. Note what this does and doesn't fix: `probed` is computed from
-  // measurements taken BEFORE this critical section runs (the Promise.all
-  // above), so a concurrent writer's fresher last_health_* value for the same
-  // field on the same surface can still be overwritten by this sweep's own
-  // (now-stale) measurement -- the lock serializes WRITES, it cannot un-stale
-  // data that was already measured before the lock was acquired. What it DOES
-  // guarantee: this sweep's own load-modify-save can no longer interleave
-  // with another lock-using mutator's load-modify-save landing at the same
-  // instant, and every field this sweep doesn't touch is protected by the
-  // same fresh-read-under-lock discipline as everywhere else in this file.
   const byId = new Map(probed.map((entry) => [entry.surface_id, entry]));
-  await withStateLock(() => {
-    const state = loadSupervisorState();
-    state.surfaces = (state.surfaces || []).map((surface) => {
-      const entry = byId.get(`${surface.plugin_id}:${surface.id}`);
-      if (!entry) return surface;
-      // last_health_url is the RESOLVED probe target, not the manifest's health
-      // field. A remote surface carries a relative "/health" by contract, so the
-      // manifest value alone cannot be opened in a browser — only the resolved
-      // one can, and it is the fallback when the Open root turns out to be dead.
-      const next = { ...surface, last_open_url: entry.open_url, last_open_ok: entry.open_ok, last_health_url: entry.url };
-      if (entry.health === "no_probe") return next;
-      return {
-        ...next,
-        last_health_at: entry.observed_at,
-        last_health_ok: entry.health === "healthy",
-        last_health_error: entry.health === "healthy" ? null : entry.error,
-      };
-    });
-    saveSupervisorState(state);
+  const state = loadSupervisorState();
+  state.surfaces = (state.surfaces || []).map((surface) => {
+    const entry = byId.get(`${surface.plugin_id}:${surface.id}`);
+    if (!entry) return surface;
+    // last_health_url is the RESOLVED probe target, not the manifest's health
+    // field. A remote surface carries a relative "/health" by contract, so the
+    // manifest value alone cannot be opened in a browser — only the resolved
+    // one can, and it is the fallback when the Open root turns out to be dead.
+    const next = { ...surface, last_open_url: entry.open_url, last_open_ok: entry.open_ok, last_health_url: entry.url };
+    if (entry.health === "no_probe") return next;
+    return {
+      ...next,
+      last_health_at: entry.observed_at,
+      last_health_ok: entry.health === "healthy",
+      last_health_error: entry.health === "healthy" ? null : entry.error,
+    };
   });
+  saveSupervisorState(state);
   return { probed };
 }
 
@@ -565,7 +448,7 @@ function localhostHealth(pathOrUrl, port) {
 function normalizeSurface(surface, plugin) {
   if (!surface || typeof surface !== "object") throw new Error("surface must be an object");
   const id = String(surface.id || "").trim();
-  if (!/^[a-zA-Z0-9_.-]+$/.test(id) || /^\.+$/.test(id) || RESERVED_DEVICE_NAMES.test(id)) throw new Error("surface.id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots, and may not be a Windows reserved device name");
+  if (!/^[a-zA-Z0-9_.-]+$/.test(id) || /^\.+$/.test(id)) throw new Error("surface.id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots");
   const destination = normalizeDestination(surface.destination || plugin.destination);
   // A remote surface names a service running somewhere else (Vultr/Coolify).
   // It is reached by URL and its port is the deployment registry's fact, not
@@ -618,7 +501,7 @@ export function validatePluginManifest(manifest, sourcePath = "") {
   if (!manifest || typeof manifest !== "object") throw new Error("manifest must be an object");
   if (manifest.schema !== SCHEMA) throw new Error(`schema must be ${SCHEMA}`);
   const id = String(manifest.id || "").trim();
-  if (!/^[a-zA-Z0-9_.-]+$/.test(id) || /^\.+$/.test(id) || RESERVED_DEVICE_NAMES.test(id)) throw new Error("id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots, and may not be a Windows reserved device name");
+  if (!/^[a-zA-Z0-9_.-]+$/.test(id) || /^\.+$/.test(id)) throw new Error("id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots");
   const version = String(manifest.version || "").trim();
   if (!version) throw new Error("version is required");
   const plugin = {
@@ -707,143 +590,6 @@ function saveSupervisorState(state) {
   });
 }
 
-// state.json's read-modify-write needs a real lock: two separate OS
-// processes share it by design in the STANDARD deployment topology (`clauth
-// serve start`'s ensureSupervisorStarted() spawns the :52439 supervisor
-// child via a genuinely separate `spawn(..., {detached:true})`, deliberately
-// sharing CLAUTH_SUPERVISOR_DIR with the main :52437 daemon -- and
-// registerSupervisorRoutes() mounts the promote route on both), so an
-// in-process-only mutex protects nothing between a promote via :52437 and
-// the health-reconcile loop's write via :52439 (gated to exactly that one
-// process by `port === getSupervisorPort()`). Confirmed by direct code
-// tracing, not assumed.
-//
-// withStateLock does two things: an in-process queue (createSerializedExecutor,
-// cli/ops/serialized-executor.js -- reused, not duplicated) avoids
-// unnecessary lock-file contention among same-process callers, and
-// proper-lockfile below is a real cross-process lock serializing across BOTH
-// processes. Every mutator in this file (discoverPlugins, registerPlugin,
-// deregisterPlugin, runPluginAction, operation, runSurfacePromotion,
-// updateSurfaceState, probeAllSurfaceHealth) is routed through it.
-//
-// Deliberately NOT held across slow work: every withStateLock call site
-// wraps only a load+patch+save (fast, no network/spawnSync inside the locked
-// section) -- runSurfaceAction's actual command execution (which can run up
-// to `surface.timeoutMs || 30000`ms) and health probes both run OUTSIDE any
-// withStateLock call. This is what keeps normal contention brief: no
-// legitimate holder should ever approach the stale threshold below.
-//
-// HISTORY: three hand-rolled versions of this lock were built, reviewed, and
-// each found to have a distinct real concurrency bug -- all via direct
-// empirical reproduction (real spawned processes racing the real code), not
-// by inspection alone:
-//   1. openSync(path,'wx') + a SEPARATE writeSync for content -- the file
-//      observably existed empty for a brief window between the two; a
-//      concurrent reader landing there saw unparseable content and
-//      immediately treated it as abandoned, racing the legitimate holder's
-//      in-flight write. Reproduced: 23 increments landed instead of 24
-//      across two real processes each doing 12 locked increments.
-//   2. Fixed (1) via a directory (one atomic mkdirSync, no separate
-//      content-write step) but reclaimed a stale lock via unlinkSync +
-//      retry -- TWO waiters could both read the same stale record, both
-//      decide to reclaim, and both succeed independently (unlink doesn't
-//      prove you were first). Reproduced: 2-3 simultaneous "holders" in 5 of
-//      12 runs against an instrumented mirror of the algorithm.
-//   3. Fixed (2) via an atomic renameSync-based reclaim claim, but had no
-//      FENCING: release() removed "whatever is at the lock path" rather
-//      than "the specific instance this process acquired," so a holder that
-//      stalled past the stale threshold while still alive could have its
-//      lock reclaimed by a waiter, and the original holder's eventual
-//      release() would then delete the NEW holder's active lock. Separately,
-//      a leftover lock from version (1) or (2)'s on-disk shape permanently
-//      deadlocked version (3) on upgrade -- reproduced directly.
-//
-// Three distinct real bugs in three consecutive attempts at hand-rolling the
-// same primitive is a pattern, not bad luck -- proper file locking with
-// correct fencing, staleness detection, and crash recovery is a well-studied
-// problem with mature solutions, and continuing to re-derive one under time
-// pressure was the wrong instinct from the start (this was explicitly
-// offered as "option 2" in the very first interview on this topic and set
-// aside for "no new dependency," a preference that cost far more in
-// engineering time and risk than the dependency would have). Replaced with
-// proper-lockfile (moxystudio/node-proper-lockfile, MIT, minimal dependency
-// footprint -- graceful-fs, retry, signal-exit, all already-common
-// transitive deps): mkdir-based atomic creation (same primitive as version
-// 2/3 above), staleness via continuously-updated mtime rather than a
-// point-in-time pid/age snapshot (detects an ACTUALLY-stuck holder, not just
-// an old one), and release() is tied to the specific acquisition via its own
-// compromise detection (onCompromised fires if the lock is found to have
-// been reclaimed out from under an active holder) -- closing the fencing gap
-// hand-rolling never got right. Its lockfile path is `<file>.lock`, distinct
-// from every prior on-disk shape used here (`state.lock` as both a file and
-// a directory across the three versions above), so no upgrade-collision
-// migration is needed -- a leftover artifact from any prior version simply
-// sits unused at a path this version never touches.
-const inProcessStateQueue = createSerializedExecutor();
-// Matches the generous, crash-recovery-oriented threshold from the
-// hand-rolled versions: no legitimate critical section here holds the lock
-// anywhere near this long (see "deliberately NOT held across slow work"
-// above), so this is a backstop, not a normal-operation timeout.
-const STATE_LOCK_STALE_MS = 30000;
-// ~5s total wait budget under contention, matching the prior versions'
-// timeout, expressed as proper-lockfile's retry-package options.
-const STATE_LOCK_RETRIES = { retries: 50, minTimeout: 100, maxTimeout: 100, randomize: false };
-
-function stateLockTargetPath() {
-  // realpath:false below means this path is never required to exist (pure
-  // string resolution, no fs check) -- safe to point at state.json even
-  // before it's ever been written, e.g. a brand-new install's first boot.
-  return file("state.json");
-}
-
-// rdc:review finding (2026-09-02), 4th round: cli/commands/serve.js had its
-// own, older copy of this exact function that did NOT special-case EPERM as
-// "alive" -- ensureSupervisorStarted()/stopSupervisorSibling() use it to
-// decide whether the real :52439 supervisor child is already running, and
-// under EPERM (a live process signalled across a security/account boundary)
-// the stale definition wrongly reported it dead, risking a duplicate
-// supervisor child spawn -- two real processes racing the port bind and the
-// health-reconcile loop. Exported here and imported by serve.js instead of
-// duplicated, so there is exactly one definition to keep correct. (No longer
-// used by the lock itself -- proper-lockfile's own mtime-based staleness
-// check replaced the hand-rolled pid-liveness check -- but still the shared
-// definition serve.js's supervisor-child bookkeeping depends on.)
-export function isProcessAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    // EPERM: the process exists but we lack permission to signal it -- still
-    // alive. Any other error (ESRCH, etc.) means it's gone.
-    return err.code === "EPERM";
-  }
-}
-
-export async function withStateLock(criticalSection) {
-  return inProcessStateQueue(async () => {
-    const release = await lockfile.lock(stateLockTargetPath(), {
-      realpath: false,
-      stale: STATE_LOCK_STALE_MS,
-      retries: STATE_LOCK_RETRIES,
-      onCompromised: (err) => {
-        // Should be effectively unreachable given how short every critical
-        // section here is relative to `stale` -- logged, not thrown, so a
-        // detection here can't itself crash the process the way the
-        // library's default onCompromised (rethrow) would.
-        try {
-          const logFile = process.env.CLAUTH_SERVE_LOG || path.join(os.tmpdir(), "clauth-serve.log");
-          fs.appendFileSync(logFile, `[${now()}] state.json lock compromised: ${err?.message || err}\n`, "utf8");
-        } catch { /* logging must never itself throw */ }
-      },
-    });
-    try {
-      return await criticalSection();
-    } finally {
-      await release();
-    }
-  });
-}
-
 function existingById(state) {
   return new Map((state.plugins || []).map((plugin) => [plugin.id, plugin]));
 }
@@ -990,33 +736,11 @@ export function registerPlugin(manifestPath, actor = "localhost") {
   }
   const discovery = discoverPlugins();
   const registered = discovery.plugins.find((plugin) => plugin.id === manifest.id);
-
-  // A changed manifest means changed code (a version bump, a fresh
-  // `npm install -g`) — registering it used to only re-read metadata and
-  // never touch the actual running process, so the live PM2 surface kept
-  // serving the OLD code indefinitely until something else happened to
-  // restart it (Dave: "plugin install pings clauth to reread -- it should
-  // restart the pm2 -- fix the bug"). Restart every surface clauth actually
-  // owns (lifecycle_owner:"clauth", i.e. PM2-managed, not an "external"-owned
-  // surface like codeflow's) that declares a real restart command. Skipped
-  // entirely when unchanged — an unrelated dependency bump must not restart
-  // a live service for nothing.
-  const restarted = [];
-  if (!unchanged && registered) {
-    for (const surface of registered.surfaces || []) {
-      if (surface.lifecycle_owner !== "clauth") continue;
-      if (!Array.isArray(surface.restart) || surface.restart.length === 0) continue;
-      const result = runSurfaceAction(`${manifest.id}:${surface.id}`, "restart", actor);
-      restarted.push({ surface_id: surface.id, ok: result?.resulting_state?.ok === true, state: result?.resulting_state?.state || result?.error || "unknown" });
-    }
-  }
-
   return operation("plugin.register", { manifest_path: manifestPath, plugin_id: manifest.id }, null, {
     ok: Boolean(registered) && registered.state !== "manifest_invalid",
     state: unchanged ? "unchanged" : "registered",
     plugin_state: registered?.state || "not_found",
     surfaces: registered?.surfaces?.map((surface) => surface.id) || [],
-    restarted,
   }, actor);
 }
 
@@ -1037,26 +761,12 @@ export function registerPlugin(manifestPath, actor = "localhost") {
 // exist, or to cache what was found, that rebuilds the thing that was deleted —
 // stop instead.
 // ─────────────────────────────────────────────────────────────────────────────
-// rdc-skills is deliberately NOT in this list. It is npm-published, so unlike
-// every entry below it already has its own real install lifecycle — its own
-// postinstall (scripts/postinstall.js) calls `clauth plugin register` against
-// the INSTALLED package's own manifest (__dirname-anchored, never cwd). A
-// checkout-path sweep entry here would read a DIFFERENT, unrelated copy
-// (a dev git checkout that may not exist on every machine, or may hold
-// unreleased content) and could overwrite the correct, install-based
-// registration with it. This already happened once: the earlier version of
-// this entry shipped a manifest carrying a literal cwd "C:/Dev/rdc-skills",
-// so `npm i -g` on any OTHER machine auto-enabled a core plugin pointing at
-// a directory that did not exist there (Dave: "rdc skills is an mcp
-// application is it installed - no checkout is allowed"). The ${PACKAGE_ROOT}
-// token fix in registerPlugin() solved the symptom; removing this entry
-// removes the actual competing registration path.
 const PRODUCT_REPO_MANIFESTS = [
   { repo: "regen-root", manifest: "packages/codeflow/clauth-plugin.json" },
   { repo: "regen-root", manifest: "apps/dev-center/clauth-plugin.json" },
-  { repo: "regen-root", manifest: "apps/codeflow-explorer/clauth-plugin.json" },
   { repo: "regen-root", manifest: "mcp-servers/regen-media/clauth-plugin.json" },
   { repo: "regen-root", manifest: "mcp-servers/web-research/clauth-plugin.json" },
+  { repo: "rdc-skills", manifest: "clauth-plugin.json" },
 ];
 
 // Sweep outcomes that mean "nothing was there to sync", as distinct from
@@ -1189,16 +899,6 @@ export function deregisterPlugin(id, actor = "localhost", { dryRun = false, expe
   // all resolve back INSIDE the root and sail through containment. Only the
   // charset rule stops them. Relaxing it to admit a separator, a colon or a
   // drive letter reopens a real hole — the tests pin all three forms.
-  //
-  // rdc:review finding (2026-09-02): unlike validatePluginManifest (which
-  // guards CREATING new entries), this guard deliberately does NOT reject
-  // RESERVED_DEVICE_NAMES. Removal must never refuse to remove something that
-  // already exists on disk, and blocking it here had no compensating safety
-  // benefit -- it only trapped any plugin whose id happened to match a
-  // reserved name (registered before this check existed, or by any other
-  // path) in a permanent, un-removable quarantined state with no
-  // remediation, since deregisterPlugin is the ONLY removal API, including
-  // under force:true.
   if (!/^[a-zA-Z0-9_.-]+$/.test(pluginId) || /^\.+$/.test(pluginId)) {
     return operation("plugin.deregister", { plugin_id: pluginId }, null, {
       ok: false, state: "invalid_plugin_id", error: "plugin id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots",
@@ -1379,28 +1079,6 @@ export function readSupervisorEvents(limit = 100) {
   });
 }
 
-// rdc:review finding (2026-09-02), 4th round: this function's own
-// read-modify-write of state.operations is NOT withStateLock-protected, and
-// -- corrected from an earlier, inaccurate version of this note -- its
-// residual risk is NOT limited to a lost operations audit-log entry.
-// loadSupervisorState()/saveSupervisorState() here operate on the WHOLE
-// state object, not a scoped patch: if a withStateLock-protected mutator's
-// write (e.g. a plugin-enable flip) lands between this function's own
-// unlocked load and save, this function's save reverts that change too, not
-// just its own append. operation() is called by EVERY mutator in this file
-// (runSurfaceAction, runSurfacePromotion, registerPlugin, deregisterPlugin,
-// runPluginAction, addTunnelRoute, removeTunnelRoute), all currently
-// synchronous, so converting operation() to route through withStateLock
-// requires converting all of them (and their own callers throughout
-// serve.js/index.js/the HTTP components) to async -- a large, real ripple,
-// not a quick patch, and the wrong thing to attempt under time pressure atop
-// a lock implementation that has already had two genuine bugs found and
-// fixed in it this same session. Left honestly unlocked and documented
-// rather than converted hastily. state.json's write being atomic (see
-// writeJson) means this can no longer corrupt the FILE (no torn reads), only
-// silently lose a concurrent WRITE under real contention -- narrower than
-// before this session's atomic-write fix, but still real. Tracked for the
-// full-mutator-coverage follow-up rather than fixed here.
 export function operation(action, target, prior, result, actor = "localhost") {
   const receipt = {
     operationId: crypto.randomUUID(),
@@ -1443,6 +1121,18 @@ export function operation(action, target, prior, result, actor = "localhost") {
   return receipt;
 }
 
+export function setPluginEnabled(id, enabled, actor = "localhost") {
+  const state = loadSupervisorState();
+  const prior = (state.plugins || []).find((plugin) => plugin.id === id);
+  if (!prior) return { error: "plugin_not_found" };
+  if (prior.state === "manifest_invalid") return { error: "manifest_invalid" };
+  const nextPlugin = { ...prior, enabled: Boolean(enabled), state: enabled ? "current" : "awaiting_enable" };
+  state.plugins = state.plugins.map((plugin) => plugin.id === id ? nextPlugin : plugin);
+  state.surfaces = (state.surfaces || []).map((surface) => surface.plugin_id === id ? { ...surface, enabled: Boolean(enabled), state: nextPlugin.state } : surface);
+  saveSupervisorState(state);
+  return operation(enabled ? "enable" : "disable", { plugin_id: id }, prior, nextPlugin, actor);
+}
+
 export function runPluginAction(id, action, actor = "localhost") {
   if (!["test", "promote"].includes(action)) return { error: "invalid_action" };
   const state = loadSupervisorState();
@@ -1522,8 +1212,16 @@ export function runSurfaceAction(id, action, actor = "localhost") {
     // a space (e.g. "C:\Program Files\nodejs\node.exe") breaks at the first
     // space unless quoted. Bare shim names (pm2, npm) never contain spaces,
     // so this only ever affects absolute-path values, and only on Windows.
-    const resolvedCmd = shellQuote(cmd, useShell);
-    const resolvedArgs = args.map((arg) => shellQuote(arg, useShell));
+    // Expand $LIFEAI_ENV / $REGEN_ROOT tokens in the command AND its args, the same
+    // way surface.cwd is expanded at normalize time. A surface start such as
+    // `pwsh -File $LIFEAI_ENV/services/restart-dev-center.ps1` (dev-center) or
+    // `pm2 start $REGEN_ROOT/apps/codeflow-explorer/... ` otherwise reached the shell
+    // with the literal token and failed ("not recognized as the name of a script
+    // file", exit 64) — a start/restart that fails while the service stays down.
+    // expandPathToken is a no-op on token-free values (pm2, --name, --cwd), so it is
+    // safe on every arg.
+    const resolvedCmd = shellQuote(expandPathToken(cmd) || cmd, useShell);
+    const resolvedArgs = args.map((arg) => shellQuote(expandPathToken(arg) || arg, useShell));
     return spawnSync(resolvedCmd, resolvedArgs, {
       cwd: surface.cwd || undefined,
       env: { ...process.env, CLAUTH_PM2_HOME: getClauthPm2Home(), PM2_HOME: getClauthPm2Home() },
@@ -1564,30 +1262,6 @@ export function runSurfaceAction(id, action, actor = "localhost") {
 export async function runSurfacePromotion(id, actor = "localhost", { fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_HEALTH_TIMEOUT_MS } = {}) {
   const surface = findSurface(id);
   if (!surface) return { error: "surface_not_found" };
-  // rdc:review finding (2026-09-02), third pass: the caller-supplied `id` can
-  // be a short, non-qualified form (findSurface() resolves via `surface.id
-  // === id` too, not qualified-only). updateSurfaceState()'s matcher is
-  // OR-based and applied via `.map()` -- it patches EVERY surface whose id OR
-  // qualified id matches, not just the one resolved above. Two different
-  // plugins registering a surface with the same short id (nothing enforces
-  // cross-plugin uniqueness) would have every updateSurfaceState(id, ...)
-  // call below silently patch BOTH surfaces. The old (pre-this-fix) code
-  // never had this hole because its array .map() matched on the RESOLVED
-  // surface's own qualified identity, not the raw caller-supplied id.
-  //
-  // rdc:review finding (2026-09-02), 4th round: runSurfaceAction(id, ...)
-  // below was left on the raw `id`, reasoning that its own findSurface()
-  // resolves via first-match .find() rather than multi-patch .map() so a
-  // short-id collision couldn't touch the WRONG surface's data the way
-  // updateSurfaceState's .map() could -- but .find() can still resolve a
-  // DIFFERENT surface than the one this function already committed to if a
-  // concurrent unlocked discoverPlugins() reorders state.surfaces between
-  // this function's own findSurface(id) above and runSurfaceAction's later,
-  // independent one. A colon can never appear in a valid id (the charset
-  // regex forbids it), so a qualified string can never accidentally match a
-  // different surface's raw short id -- using it everywhere below, including
-  // runSurfaceAction, is strictly safer with no downside.
-  const qualifiedId = `${surface.plugin_id}:${surface.id}`;
   if (surface.lifecycle_owner === "external" || surface.lifecycle_owner === "plugin") {
     return operation("promote", { surface_id: id }, surface, { ok: false, state: "observed_only", reason: "lifecycle_not_owned_by_clauth" }, actor);
   }
@@ -1608,88 +1282,27 @@ export async function runSurfacePromotion(id, actor = "localhost", { fetchImpl =
   // Reuse the guarded command runner internally without exposing a promote
   // bypass to API callers.  Its action is labelled restart only for execution;
   // the durable receipt below remains the authoritative promotion record.
-  //
-  // rdc:review finding (2026-09-02), second pass on this same function: the
-  // first version of this fix snapshotted the whole `surfaces` array ONCE at
-  // function entry and wrote it back WHOLESALE on both the pre-action swap
-  // and the post-action revert -- a stale-snapshot overwrite, not a merge, so
-  // any concurrent write to a DIFFERENT surface (reconcileSurfaceHealth's
-  // health update, another promotion, discoverPlugins) landing during this
-  // function's real await gaps (the health probe below, or a slow
-  // spawnSync-backed command) was silently discarded the moment this
-  // function's own revert-write landed -- reopening, in a different shape,
-  // the exact class of race withStateLock exists to close. Fixed by routing
-  // every surface mutation here through updateSurfaceState(), the same
-  // single-entity merge-patch helper reconcileSurfaceHealth already uses --
-  // it re-reads fresh state under the same lock and patches ONLY this
-  // surface's fields, so a concurrent writer's change to any other surface
-  // (or any other field on this one) survives regardless of how long this
-  // function's own await gaps run.
-  // rdc:review finding (2026-09-02), third pass: the plugins-flip block below
-  // added `matchFound` so a concurrent-removal no-op is reported honestly
-  // instead of a false success claim. The four updateSurfaceState() calls in
-  // this function had the identical exposure (a concurrent deregisterPlugin
-  // removing this surface mid-promotion makes each call's own internal
-  // .map() a silent no-op) but discarded their return values, so the same
-  // vanished-mid-flight case here produced a misleading
-  // "promotion_rollback_failed" receipt instead of naming what happened.
-  // Checked only at the FIRST call: if the surface is already gone before
-  // the promote-command swap even lands, there is nothing left to execute --
-  // short-circuit with an honest receipt instead of running commands against
-  // and probing the health of a surface findSurface() itself would already
-  // report has vanished, then mislabeling the result.
-  const swapped = await updateSurfaceState(qualifiedId, { restart: surface.promote });
-  if (!swapped) {
-    return operation("promote", { surface_id: id }, surface, {
-      ok: false, state: "surface_vanished_during_promotion",
-      reason: "surface was removed (e.g. concurrent deregister) before the promote command could run",
-    }, actor);
-  }
-  const promotion = runSurfaceAction(qualifiedId, "restart", actor);
-  await updateSurfaceState(qualifiedId, { restart: surface.restart });
+  const promoteSurface = { ...surface, restart: surface.promote };
+  const state = loadSupervisorState();
+  const surfaces = state.surfaces || [];
+  saveSupervisorState({ ...state, surfaces: surfaces.map((item) => `${item.plugin_id}:${item.id}` === `${surface.plugin_id}:${surface.id}` ? promoteSurface : item) });
+  const promotion = runSurfaceAction(id, "restart", actor);
+  saveSupervisorState({ ...loadSupervisorState(), surfaces });
 
   const commandOk = promotion?.resulting_state?.ok === true;
   const health = commandOk ? await probeSurfaceHealth(healthUrl, fetchImpl, timeoutMs) : { healthy: false, error: promotion?.resulting_state?.state || "promotion_command_failed" };
   if (commandOk && health.healthy) {
-    // A healthy promotion is the real, verified "this is live" event that
-    // setPluginEnabled() used to fake with a bare metadata flip -- so this is
-    // where `enabled` belongs now. Without this, a core:false plugin (every
-    // standalone MCP: fs-mcp/gws-mcp/test-mcp all ship core:false) can never
-    // reach enabled:true by any path, which silently disables
-    // reconcileSurfaceHealth()'s auto-repair for it forever.
-    // `state` is not touched here -- discoverPlugins() recomputes it from
-    // `prior.enabled` on the next pass, the same way it always has.
-    //
-    // rdc:review finding (2026-09-02): the evidence line below used to claim
-    // "plugin_enabled=true" unconditionally, even when no plugin matched
-    // surface.plugin_id (e.g. deregistered concurrently, between this
-    // function's own reads) -- .map() with no match is a silent no-op, so the
-    // receipt was reporting a mutation that never happened. matchFound makes
-    // the evidence honest about which case actually occurred.
-    const matchFound = await withStateLock(() => {
-      const enabledState = loadSupervisorState();
-      let found = false;
-      const nextPlugins = (enabledState.plugins || []).map((plugin) => {
-        if (plugin.id !== surface.plugin_id) return plugin;
-        found = true;
-        return { ...plugin, enabled: true };
-      });
-      saveSupervisorState({ ...enabledState, plugins: nextPlugins });
-      return found;
-    });
     return operation("promote", { surface_id: id }, surface, {
       ok: true, state: "promotion_healthy", health_url: healthUrl,
-      evidence: [
-        "rollback_command_declared=true",
-        "post_promotion_health=healthy",
-        matchFound ? "plugin_enabled=true" : "plugin_enabled=false plugin_not_found_in_state",
-      ],
+      evidence: ["rollback_command_declared=true", "post_promotion_health=healthy"],
     }, actor);
   }
 
-  await updateSurfaceState(qualifiedId, { restart: surface.rollback });
-  const rollback = runSurfaceAction(qualifiedId, "restart", actor);
-  await updateSurfaceState(qualifiedId, { restart: surface.restart });
+  const rollbackSurface = { ...surface, restart: surface.rollback };
+  const rollbackState = loadSupervisorState();
+  saveSupervisorState({ ...rollbackState, surfaces: (rollbackState.surfaces || []).map((item) => `${item.plugin_id}:${item.id}` === `${surface.plugin_id}:${surface.id}` ? rollbackSurface : item) });
+  const rollback = runSurfaceAction(id, "restart", actor);
+  saveSupervisorState({ ...loadSupervisorState(), surfaces });
   const rollbackOk = rollback?.resulting_state?.ok === true;
   return operation("promote", { surface_id: id }, surface, {
     ok: false,