@lifeaitools/clauth 2.10.2 → 2.15.3

package/cli/supervisor-registry.js

@@ -3,6 +3,9 @@ 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;
@@ -19,6 +22,29 @@ 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 || ""));
@@ -94,6 +120,53 @@ 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);
 }
@@ -107,9 +180,35 @@ 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) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  atomicWriteTextSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
 }
 
 function appendJsonl(filePath, value) {
@@ -132,15 +231,17 @@ function healthUrlForSurface(surface) {
   return `http://127.0.0.1:${surface.port}${String(surface.health).startsWith("/") ? surface.health : `/${surface.health}`}`;
 }
 
-function updateSurfaceState(surfaceId, patch) {
-  const state = loadSupervisorState();
-  state.surfaces = (state.surfaces || []).map((surface) => (
-    `${surface.plugin_id}:${surface.id}` === surfaceId || surface.id === surfaceId
-      ? { ...surface, ...patch }
-      : surface
-  ));
-  saveSupervisorState(state);
-  return state.surfaces.find((surface) => `${surface.plugin_id}:${surface.id}` === surfaceId || surface.id === surfaceId) || null;
+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 appendSupervisorEvent(event) {
@@ -182,19 +283,19 @@ export async function reconcileSurfaceHealth({ fetchImpl = globalThis.fetch, tim
     const error = health.error;
 
     if (healthy) {
-      updateSurfaceState(id, { state: "current", last_health_at: observedAt, last_health_ok: true, last_health_error: null });
+      await updateSurfaceState(id, { state: "current", last_health_at: observedAt, last_health_ok: true, last_health_error: null });
       inspected.push({ surface_id: id, state: "healthy", observed_at: observedAt });
       continue;
     }
 
     const lastAttempt = Date.parse(surface.last_reconcile_at || "") || 0;
     if (Date.now() - lastAttempt < HEALTH_RECONCILE_COOLDOWN_MS) {
-      updateSurfaceState(id, { state: "unavailable", last_health_at: observedAt, last_health_ok: false, last_health_error: error });
+      await updateSurfaceState(id, { state: "unavailable", last_health_at: observedAt, last_health_ok: false, last_health_error: error });
       inspected.push({ surface_id: id, state: "unavailable", error, cooldown: true, observed_at: observedAt });
       continue;
     }
 
-    updateSurfaceState(id, {
+    await updateSurfaceState(id, {
       state: "unavailable",
       last_health_at: observedAt,
       last_health_ok: false,
@@ -206,7 +307,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;
-    updateSurfaceState(id, {
+    await updateSurfaceState(id, {
       state: repaired ? "current" : "unavailable",
       last_health_at: now(),
       last_health_ok: repaired,
@@ -313,25 +414,41 @@ 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]));
-  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,
-    };
+  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);
   });
-  saveSupervisorState(state);
   return { probed };
 }
 
@@ -448,7 +565,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)) throw new Error("surface.id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots");
+  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");
   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
@@ -491,6 +608,8 @@ function normalizeSurface(surface, plugin) {
     start: normalizeCommand(surface.start || plugin.start, "surface.start"),
     stop: normalizeCommand(surface.stop || plugin.stop, "surface.stop"),
     restart: normalizeCommand(surface.restart || plugin.restart, "surface.restart"),
+    promote: normalizeCommand(surface.promote || plugin.promote, "surface.promote"),
+    rollback: normalizeCommand(surface.rollback || plugin.rollback, "surface.rollback"),
     routes: Array.isArray(surface.routes) ? surface.routes : [],
   };
 }
@@ -499,7 +618,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)) throw new Error("id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots");
+  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");
   const version = String(manifest.version || "").trim();
   if (!version) throw new Error("version is required");
   const plugin = {
@@ -588,6 +707,143 @@ 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]));
 }
@@ -734,11 +990,33 @@ 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);
 }
 
@@ -759,12 +1037,26 @@ 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
@@ -897,6 +1189,16 @@ 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",
@@ -1077,6 +1379,28 @@ 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(),
@@ -1119,18 +1443,6 @@ 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();
@@ -1175,6 +1487,17 @@ export function runSurfaceAction(id, action, actor = "localhost") {
   if (surface.plugin_id === "codeflow" || surface.tags?.includes("codeflow")) {
     return operation(action, { surface_id: id }, surface, { ok: false, state: "observed_only", reason: "codeflow_self_owned" }, actor);
   }
+  // Promotion changes a surface's release state.  It must go through
+  // runSurfacePromotion(), which requires both a rollback command and a
+  // post-activation health check; this generic command runner is deliberately
+  // not allowed to bypass those invariants.
+  if (action === "promote") {
+    return operation(action, { surface_id: id }, surface, {
+      ok: false,
+      state: "atomic_promotion_required",
+      reason: "use_runSurfacePromotion",
+    }, actor);
+  }
   if (action === "test") {
     const port = surface.port === "auto" || !surface.port ? 0 : surface.port;
     return operation(action, { surface_id: id }, surface, { ok: true, state: "candidate_testing", port, private: true, public_route: false, evidence: ["candidate surfaces bind localhost only"] }, actor);
@@ -1182,19 +1505,12 @@ export function runSurfaceAction(id, action, actor = "localhost") {
   if (surface.lifecycle_owner === "plugin") {
     return operation(action, { surface_id: id }, surface, { ok: true, state: "delegated_to_plugin_adapter", evidence: ["plugin lifecycle owner retained"] }, actor);
   }
-  if (action === "promote" || action === "rollback") {
-    return operation(action, { surface_id: id }, surface, {
-      ok: false,
-      state: "unsupported_surface_action",
-      reason: `${action}_is_plugin_candidate_lifecycle`,
-      evidence: ["surface action did not execute a process command"],
-    }, actor);
-  }
   let command = null;
   if (action === "stop") command = surface.stop;
   else if (action === "start") command = surface.start;
   else if (action === "restart") command = surface.restart;
   else if (action === "reconcile") command = surface.enabled === false ? surface.stop : (surface.restart || surface.start);
+  else if (action === "rollback") command = surface.rollback;
   if (!command || command.length === 0) {
     return operation(action, { surface_id: id }, surface, { ok: false, state: "command_missing" }, actor);
   }
@@ -1240,6 +1556,151 @@ export function runSurfaceAction(id, action, actor = "localhost") {
   }, actor);
 }
 
+/**
+ * Promote a clauth-owned surface as one bounded lifecycle operation.  A
+ * declared rollback and a resolvable health target are preconditions, so a
+ * manifest cannot accidentally turn a one-way command into a "promotion".
+ */
+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);
+  }
+  if (surface.plugin_id === "codeflow" || surface.tags?.includes("codeflow")) {
+    return operation("promote", { surface_id: id }, surface, { ok: false, state: "observed_only", reason: "codeflow_self_owned" }, actor);
+  }
+  if (!Array.isArray(surface.promote) || surface.promote.length === 0) {
+    return operation("promote", { surface_id: id }, surface, { ok: false, state: "command_missing" }, actor);
+  }
+  if (!Array.isArray(surface.rollback) || surface.rollback.length === 0) {
+    return operation("promote", { surface_id: id }, surface, { ok: false, state: "atomic_rollback_missing" }, actor);
+  }
+  const healthUrl = surfaceProbeUrl(surface);
+  if (!healthUrl) {
+    return operation("promote", { surface_id: id }, surface, { ok: false, state: "atomic_health_probe_missing" }, actor);
+  }
+
+  // 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 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",
+      ],
+    }, actor);
+  }
+
+  await updateSurfaceState(qualifiedId, { restart: surface.rollback });
+  const rollback = runSurfaceAction(qualifiedId, "restart", actor);
+  await updateSurfaceState(qualifiedId, { restart: surface.restart });
+  const rollbackOk = rollback?.resulting_state?.ok === true;
+  return operation("promote", { surface_id: id }, surface, {
+    ok: false,
+    state: rollbackOk ? "promotion_rolled_back" : "promotion_rollback_failed",
+    health_url: healthUrl,
+    health_error: health.error || null,
+    rollback_ok: rollbackOk,
+    evidence: ["rollback_command_declared=true", `post_promotion_health=${health.healthy ? "healthy" : "unhealthy"}`],
+  }, actor);
+}
+
 export function addTunnelRoute(tunnelId, route, actor = "localhost") {
   const tunnels = listTunnels();
   const tunnel = tunnels.find((item) => item.id === tunnelId);