@lifeaitools/clauth 2.10.2 → 2.15.3

package/cli/http/components/supervisor-component.js

@@ -1,7 +1,7 @@
 // cli/http/components/supervisor-component.js
-// The Supervisor-write component: plugin rescan/enable/disable/test/
-// promote, surface health probe + surface actions, and tunnel-route
-// CRUD -- all gated by hasSupervisorWrite() (the supervisor's own
+// The Supervisor-write component: plugin rescan/test/promote, surface
+// health probe + surface actions, and tunnel-route CRUD -- all gated by
+// hasSupervisorWrite() (the supervisor's own
 // write-token, a THIRD distinct guard from lockedGuard/writeGuard and
 // from the ops plane's bearer token), except /v1/surfaces/health which
 // is deliberately guard-free (read-only health sweep, run whenever the
@@ -16,10 +16,10 @@
 // every other component this session.
 import {
   discoverPlugins,
-  setPluginEnabled,
   runPluginAction,
   probeAllSurfaceHealth,
   runSurfaceAction,
+  runSurfacePromotion,
   addTunnelRoute,
   removeTunnelRoute,
   supervisorHealth,
@@ -40,16 +40,17 @@ export function registerSupervisorRoutes(ctx) {
       return ctx.ok(res, discoverPlugins());
     }
 
-    const pluginEnableMatch = reqPath.match(/^\/v1\/plugins\/([^/]+)\/(enable|disable|test|promote)$/);
-    if (method === "POST" && pluginEnableMatch) {
+    // enable/disable were removed 2026-08-31: the flag they set was pure
+    // metadata (no process spawn) and never implied a running process --
+    // starting/stopping a surface always required a separate, unrelated
+    // action (runSurfaceAction "start"/"restart"). That disconnect made the
+    // flag actively misleading rather than a real lifecycle control.
+    const pluginActionMatch = reqPath.match(/^\/v1\/plugins\/([^/]+)\/(test|promote)$/);
+    if (method === "POST" && pluginActionMatch) {
       if (!ctx.hasSupervisorWrite(req)) return ctx.rejectSupervisorWrite(res);
-      const pluginId = decodeURIComponent(pluginEnableMatch[1]);
-      const op = pluginEnableMatch[2];
-      const result = op === "enable"
-        ? setPluginEnabled(pluginId, true)
-        : op === "disable"
-          ? setPluginEnabled(pluginId, false)
-          : runPluginAction(pluginId, op);
+      const pluginId = decodeURIComponent(pluginActionMatch[1]);
+      const op = pluginActionMatch[2];
+      const result = runPluginAction(pluginId, op);
       res.writeHead(result.error ? 400 : 200, { "Content-Type": "application/json", ...ctx.CORS });
       return res.end(JSON.stringify(result));
     }
@@ -72,7 +73,10 @@ export function registerSupervisorRoutes(ctx) {
         res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
         return res.end(JSON.stringify({ error: "Invalid JSON" }));
       }
-      const result = runSurfaceAction(decodeURIComponent(surfaceActionMatch[1]), body?.action || "reconcile");
+      const action = body?.action || "reconcile";
+      const result = action === "promote"
+        ? await runSurfacePromotion(decodeURIComponent(surfaceActionMatch[1]))
+        : runSurfaceAction(decodeURIComponent(surfaceActionMatch[1]), action);
       res.writeHead(result.error ? 400 : 200, { "Content-Type": "application/json", ...ctx.CORS });
       return res.end(JSON.stringify(result));
     }

package/cli/http/components/test-static-oauth-component.js

@@ -0,0 +1,233 @@
+// cli/http/components/test-static-oauth-component.js
+// TEST-ONLY, entirely additive: a minimal static-client OAuth 2.0 provider
+// (client_id + client_secret, authorization_code + refresh_token grants)
+// fronting one dummy MCP tool at /test/mcp. Built to test claude.ai's
+// BUILT-IN custom-connector OAuth support (manual client_id/secret entry —
+// no Dynamic Client Registration) side-by-side with the existing DCR+PKCE+
+// attestation stack in oauth-component.js / mcp-transport-component.js.
+// This file does not import from, call into, or modify either of those —
+// separate Maps, separate routes, separate discovery paths.
+//
+// Static credentials come from env so nothing is hardcoded/committed. If
+// unset, a random pair is generated at daemon start and logged once — read
+// it from clauth-serve.log to configure the claude.ai connector.
+//   CLAUTH_TEST_OAUTH_CLIENT_ID / CLAUTH_TEST_OAUTH_CLIENT_SECRET
+//
+// Access tokens are deliberately short-lived (10 min) so refresh_token
+// behavior is observable within a normal test session rather than needing
+// to wait 24h like the real flow.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { readRawBody } from "../request-utils.js";
+
+const LOG_FILE = path.join(os.tmpdir(), "clauth-serve.log");
+const ACCESS_TTL_MS = 10 * 60 * 1000;
+const REFRESH_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+function log(msg) {
+  try { fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] test-oauth: ${msg}\n`); } catch {}
+}
+
+// Constant-time string compare, safe for unequal lengths (timingSafeEqual
+// throws rather than returning false when buffers differ in length).
+function safeEqual(a, b) {
+  const bufA = Buffer.from(String(a ?? ""), "utf8");
+  const bufB = Buffer.from(String(b ?? ""), "utf8");
+  if (bufA.length !== bufB.length) return false;
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+export function registerTestStaticOAuthRoutes(ctx) {
+  const CLIENT_ID = process.env.CLAUTH_TEST_OAUTH_CLIENT_ID || crypto.randomBytes(8).toString("hex");
+  const CLIENT_SECRET = process.env.CLAUTH_TEST_OAUTH_CLIENT_SECRET || crypto.randomBytes(24).toString("hex");
+  log(`static client ready — client_id=${CLIENT_ID} client_secret=${CLIENT_SECRET}`);
+  // No Dynamic Client Registration in this static-client model, so there is
+  // no per-client redirect_uris list to validate against by default — the
+  // real oauth-component.js has one (client.redirect_uris); this needs its
+  // own. Fails closed: unset means no redirect_uri is accepted, not "accept
+  // anything", matching this whole surface's opt-in-only posture.
+  const ALLOWED_REDIRECT_URIS = (process.env.CLAUTH_TEST_OAUTH_REDIRECT_URIS || "")
+    .split(",").map((s) => s.trim()).filter(Boolean);
+
+  const codes = new Map();         // code -> { redirect_uri, expires }
+  const accessTokens = new Map();  // token -> { expires }
+  const refreshTokens = new Map(); // token -> { expires }
+
+  function issueTokenPair() {
+    const access_token = crypto.randomBytes(32).toString("hex");
+    const refresh_token = crypto.randomBytes(32).toString("hex");
+    accessTokens.set(access_token, { expires: Date.now() + ACCESS_TTL_MS });
+    refreshTokens.set(refresh_token, { expires: Date.now() + REFRESH_TTL_MS });
+    return { access_token, refresh_token };
+  }
+
+  // ── Discovery ──
+  // Namespaced entirely under /test/ — mcp-transport-component.js registers
+  // a broad /^\/\.well-known\// catch-all BEFORE this component runs, and
+  // registerPatternRoute matches in registration order (first match wins,
+  // confirmed serve.js:2523), so a bare /.well-known/... path here would be
+  // silently swallowed by that existing route rather than reaching this one.
+  ctx.registerPatternRoute("GET", /^\/test\/\.well-known\/oauth-protected-resource$/, async (req, res) => {
+    const base = ctx.oauthBase();
+    res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    return res.end(JSON.stringify({
+      resource: `${base}/test/mcp`,
+      authorization_servers: [`${base}/test`],
+      scopes_supported: ["test:tools"],
+      bearer_methods_supported: ["header"],
+    }));
+  });
+  function authServerMetadata(base) {
+    return {
+      issuer: `${base}/test`,
+      authorization_endpoint: `${base}/test/authorize`,
+      token_endpoint: `${base}/test/token`,
+      response_types_supported: ["code"],
+      grant_types_supported: ["authorization_code", "refresh_token"],
+      token_endpoint_auth_methods_supported: ["client_secret_post", "client_secret_basic"],
+      code_challenge_methods_supported: ["S256"],
+      scopes_supported: ["test:tools"],
+    };
+  }
+  function serveAuthServerMetadata(req, res) {
+    const base = ctx.oauthBase();
+    res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    return res.end(JSON.stringify(authServerMetadata(base)));
+  }
+  // Observed via live claude.ai request log (2026-08-31): it tries several
+  // conventional discovery URL shapes before falling back to guessing
+  // <origin>/authorize directly. RFC 8414's actual spec puts .well-known
+  // BEFORE the issuer's path (/.well-known/oauth-authorization-server/test),
+  // not after -- that was the original bug here. Serving every shape it was
+  // observed trying, rather than guessing which one it "should" use.
+  ctx.registerPatternRoute("GET", /^\/\.well-known\/oauth-authorization-server\/test$/, serveAuthServerMetadata);
+  ctx.registerPatternRoute("GET", /^\/\.well-known\/openid-configuration\/test$/, serveAuthServerMetadata);
+  ctx.registerPatternRoute("GET", /^\/test\/\.well-known\/openid-configuration$/, serveAuthServerMetadata);
+  ctx.registerPatternRoute("GET", /^\/test\/\.well-known\/oauth-authorization-server$/, serveAuthServerMetadata);
+
+  // ── Authorize — static client, auto-approve (test only), PKCE optional
+  // since this exists specifically to test claude.ai's own client behavior,
+  // not to enforce our own policy on it. ──
+  ctx.registerWriteRoute("GET", "/test/authorize", async (req, res, url) => {
+    const clientId = url.searchParams.get("client_id");
+    const redirectUri = url.searchParams.get("redirect_uri");
+    const state = url.searchParams.get("state");
+    if (clientId !== CLIENT_ID || !redirectUri || !ALLOWED_REDIRECT_URIS.includes(redirectUri)) {
+      res.writeHead(400, { "Content-Type": "text/plain" });
+      return res.end("invalid client_id or unregistered redirect_uri");
+    }
+    const code = crypto.randomBytes(24).toString("hex");
+    codes.set(code, { redirect_uri: redirectUri, expires: Date.now() + 300_000 });
+    const redirect = new URL(redirectUri);
+    redirect.searchParams.set("code", code);
+    if (state) redirect.searchParams.set("state", state);
+    log(`authorize -> code issued for client ${clientId}`);
+    res.writeHead(302, { Location: redirect.toString(), "Cache-Control": "no-store" });
+    return res.end();
+  });
+
+  // ── Token — authorization_code AND refresh_token grants ──
+  ctx.registerWriteRoute("POST", "/test/token", async (req, res) => {
+    const raw = await readRawBody(req);
+    const ct = req.headers["content-type"] || "";
+    const body = ct.includes("application/json") ? JSON.parse(raw || "{}") : Object.fromEntries(new URLSearchParams(raw));
+
+    // Client auth: client_secret_post (body) or client_secret_basic (header)
+    let clientId = body.client_id, clientSecret = body.client_secret;
+    const authHeader = req.headers.authorization;
+    if (!clientSecret && authHeader?.startsWith("Basic ")) {
+      const [u, p] = Buffer.from(authHeader.slice(6), "base64").toString().split(":");
+      clientId = clientId || u; clientSecret = p;
+    }
+    if (clientId !== CLIENT_ID || !safeEqual(clientSecret, CLIENT_SECRET)) {
+      log(`token: client auth failed (client_id=${clientId})`);
+      res.writeHead(401, { "Content-Type": "application/json" });
+      return res.end(JSON.stringify({ error: "invalid_client" }));
+    }
+
+    if (body.grant_type === "authorization_code") {
+      const stored = codes.get(body.code);
+      codes.delete(body.code);
+      if (!stored || stored.expires < Date.now() || stored.redirect_uri !== body.redirect_uri) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        return res.end(JSON.stringify({ error: "invalid_grant" }));
+      }
+      const pair = issueTokenPair();
+      log(`token: issued via authorization_code`);
+      res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+      return res.end(JSON.stringify({ ...pair, token_type: "Bearer", scope: "test:tools", expires_in: ACCESS_TTL_MS / 1000 }));
+    }
+
+    if (body.grant_type === "refresh_token") {
+      const stored = refreshTokens.get(body.refresh_token);
+      if (!stored || stored.expires < Date.now()) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        return res.end(JSON.stringify({ error: "invalid_grant" }));
+      }
+      refreshTokens.delete(body.refresh_token); // rotate — old refresh token is one-time use
+      const pair = issueTokenPair();
+      log(`token: rotated via refresh_token`);
+      res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+      return res.end(JSON.stringify({ ...pair, token_type: "Bearer", scope: "test:tools", expires_in: ACCESS_TTL_MS / 1000 }));
+    }
+
+    res.writeHead(400, { "Content-Type": "application/json" });
+    return res.end(JSON.stringify({ error: "unsupported_grant_type" }));
+  });
+
+  // ── MCP endpoint — self-contained, one dummy tool, no dependency on the
+  // real vault/tool surface. 401 gate mirrors the real transport's shape. ──
+  ctx.registerWriteRoute("POST", "/test/mcp", async (req, res) => {
+    const authHeader = req.headers.authorization;
+    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
+    const stored = token && accessTokens.get(token);
+    if (!stored || stored.expires < Date.now()) {
+      const base = ctx.oauthBase();
+      res.writeHead(401, {
+        "Content-Type": "application/json",
+        "WWW-Authenticate": `Bearer realm="test-MCP", resource_metadata="${base}/test/.well-known/oauth-protected-resource"`,
+        "Cache-Control": "no-store",
+      });
+      return res.end(JSON.stringify({ error: "unauthorized", error_description: "Bearer token required or expired" }));
+    }
+    let body;
+    try { body = JSON.parse(await readRawBody(req)); } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      return res.end(JSON.stringify({ error: "Invalid JSON" }));
+    }
+    const { id, method, params } = body;
+    if (method === "notifications/initialized" || method === "initialized") { res.writeHead(202); return res.end(); }
+    if (method === "initialize") {
+      return respond(res, req, { jsonrpc: "2.0", id, result: {
+        protocolVersion: "2025-03-26",
+        serverInfo: { name: "test-mcp", version: "0.1.0" },
+        capabilities: { tools: { listChanged: true } },
+      } });
+    }
+    if (method === "tools/list") {
+      return respond(res, req, { jsonrpc: "2.0", id, result: { tools: [{
+        name: "test_ping",
+        description: "Returns a fixed value — used only to confirm the static-client OAuth token grants tool access.",
+        inputSchema: { type: "object", properties: {} },
+      }] } });
+    }
+    if (method === "tools/call" && params?.name === "test_ping") {
+      log(`tools/call test_ping invoked`);
+      return respond(res, req, { jsonrpc: "2.0", id, result: { content: [{ type: "text", text: "pong from test-mcp" }] } });
+    }
+    return respond(res, req, { jsonrpc: "2.0", id, error: { code: -32601, message: `Unknown method: ${method}` } });
+  });
+
+  function respond(res, req, payload) {
+    if ((req.headers.accept || "").includes("text/event-stream")) {
+      const buf = Buffer.from(`event: message\ndata: ${JSON.stringify(payload)}\n\n`, "utf8");
+      res.writeHead(200, { "Content-Type": "text/event-stream", "Content-Length": buf.length, "Cache-Control": "no-cache" });
+      return res.end(buf);
+    }
+    res.writeHead(200, { "Content-Type": "application/json" });
+    return res.end(JSON.stringify(payload));
+  }
+}

package/cli/ops/pm2-adapter.js

@@ -53,6 +53,116 @@ function callbackCall(pm2, method, args = []) {
   });
 }
 
+// PM2's own stop/restart/delete callbacks resolve once the daemon has ISSUED
+// the kill, not once the OS has actually reclaimed the process -- confirmed
+// live 2026-09-04, Windows: a `restart` on a real app left its outgoing
+// child alive and still holding its listen port for 1000+ cycles, and a
+// plain `stop` right before an `npm install -g` over that same app's
+// install directory still hit EBUSY because the "stopped" process was, in
+// fact, not. Every caller of this adapter (the ops CLI, ops HTTP surface,
+// and every cutover procedure built on top of it) inherits that lie unless
+// this file closes it once, here, rather than each caller re-discovering it
+// under pressure.
+function isAlive(pid) {
+  if (typeof pid !== "number" || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // ESRCH: no such process -- genuinely gone. Anything else (EPERM, etc.)
+    // means the OS still has an opinion about this pid, so it isn't safe to
+    // call it dead.
+    return error.code !== "ESRCH";
+  }
+}
+
+// pm2's own death check on Windows is also parent-pid-only (God.processIsDead
+// reads pm2_env._tree_pids || [pid], and treekill's taskkill callback reports
+// only the pid it was given) -- so a spawned-child topology like clauth's own
+// next-runner fixture can have its child survive everything pm2 itself
+// thinks killed it. Capture _tree_pids alongside pid so this adapter isn't
+// blind to exactly the shape its own fixtures use.
+function pidsOf(processes) {
+  return (Array.isArray(processes) ? processes : [processes])
+    .flatMap((entry) => [entry?.pid, ...(entry?.pm2_env?._tree_pids || [])])
+    .filter((pid) => typeof pid === "number" && pid > 0);
+}
+
+const DEATH_TIMEOUT_MS = 3000;
+const KILL_TIMEOUT_MS = 1000;
+
+// describe() resolving with [] IS the normal "no such app" case -- do not
+// mask that behind a try/catch that also swallows a real RPC/transport
+// failure. A caller that can't see whether the old process is still alive
+// must not silently report success; let it fail loudly instead.
+function pidsFor(pm2, target) {
+  return callbackCall(pm2, "describe", [target]).then(pidsOf);
+}
+
+async function waitForDeath(pids, { pollMs = 150, timeoutMs = DEATH_TIMEOUT_MS } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let survivors = pids.filter(isAlive);
+  while (survivors.length > 0 && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+    survivors = survivors.filter(isAlive);
+  }
+  return survivors;
+}
+
+// Verifies the pids captured BEFORE a stop/restart/reload/delete are
+// actually gone afterward, escalating to SIGKILL (TerminateProcess on
+// Windows, same as POSIX SIGKILL) if PM2's own signal didn't finish the job
+// within the timeout. Only throws if a process survives an explicit SIGKILL,
+// which should not happen -- if it does, the caller needs to know its
+// "stop" silently didn't, rather than proceed as though it did. The thrown
+// error carries the surviving pids as structured fields (not just in the
+// message) so a caller logging/job-recording the failure can act on them
+// even after this operation's own bookkeeping (e.g. a deleted pm2 record)
+// is gone.
+async function verifyTerminated(target, oldPids, operation) {
+  if (oldPids.length === 0) return;
+  const survivors = await waitForDeath(oldPids);
+  if (survivors.length === 0) return;
+  console.error(
+    `[ops] pm2 ${operation} "${target}" did not stop pid(s) ${survivors.join(", ")} within ${DEATH_TIMEOUT_MS}ms -- force-killing`,
+  );
+  for (const pid of survivors) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // Already gone between the check and the kill -- fine.
+    }
+  }
+  const stillAlive = await waitForDeath(survivors, { timeoutMs: KILL_TIMEOUT_MS });
+  if (stillAlive.length > 0) {
+    const error = new Error(
+      `pm2 ${operation} "${target}": pid(s) ${stillAlive.join(", ")} survived SIGKILL -- refusing to report success`,
+    );
+    error.pids = stillAlive;
+    error.operation = operation;
+    error.target = target;
+    error.reason = "survived_sigkill";
+    throw error;
+  }
+}
+
+// restart/reload spawn the replacement BEFORE the pm2 callback this adapter
+// awaits resolves (confirmed against pm2's own God.restartProcessId, and
+// reload falls through to the identical path outside cluster_mode -- which
+// is every app this control plane manages). So by the time verification
+// starts, a genuinely new process can already exist, and on Windows a freed
+// pid can be reallocated to it inside the same poll window this adapter is
+// watching. Re-describing AFTER the operation and only verifying death for
+// pids no longer reported as current tells the two apart: a truly orphaned
+// old pid is never in the fresh describe and still gets killed; a pid pm2
+// still reports as live is never touched, whether that's because pm2
+// genuinely didn't rotate it or because it now belongs to the new process.
+async function survivorsOf(pm2, target, oldPids) {
+  if (oldPids.length === 0) return [];
+  const currentPids = new Set(await pidsFor(pm2, target));
+  return oldPids.filter((pid) => !currentPids.has(pid));
+}
+
 function normalizeProcess(process) {
   if (!process || typeof process !== "object") return process;
   return {
@@ -101,10 +211,43 @@ export function createPm2Adapter(pm2) {
         case "logs": return (await callbackCall(pm2, "describe", [missing(input.target, "target")])).map(normalizeProcess);
         case "bus": return callbackCall(pm2, "launchBus");
         case "start": return callbackCall(pm2, "start", [missing(input.script, "script"), input.options || {}]);
-        case "stop": return callbackCall(pm2, "stop", [missing(input.target, "target")]);
-        case "restart": return callbackCall(pm2, "restart", [missing(input.target, "target"), input.options || {}]);
-        case "reload": return callbackCall(pm2, "reload", [missing(input.target, "target"), input.options || {}]);
-        case "delete": return callbackCall(pm2, "delete", [missing(input.target, "target")]);
+        case "stop": {
+          const target = missing(input.target, "target");
+          const oldPids = await pidsFor(pm2, target);
+          const result = await callbackCall(pm2, "stop", [target]);
+          await verifyTerminated(target, oldPids, "stop");
+          return result;
+        }
+        case "restart": {
+          const target = missing(input.target, "target");
+          const oldPids = await pidsFor(pm2, target);
+          const result = await callbackCall(pm2, "restart", [target, input.options || {}]);
+          await verifyTerminated(target, await survivorsOf(pm2, target, oldPids), "restart");
+          return result;
+        }
+        case "reload": {
+          // Fork mode -- every app this control plane manages -- makes
+          // reload identical to restart inside pm2 (God.reloadProcessId only
+          // takes the cluster branch in cluster_mode; everything else falls
+          // straight through to God.restartProcessId). clauth's own deploy
+          // cutover (deployment-adapter.js) calls this operation, not
+          // "restart" -- so this is the actual path "install then hit
+          // restart, pm2 should pick up the new one" travels in production,
+          // and it needs the identical guarantee, not a lighter one because
+          // the pm2 verb sounds gentler.
+          const target = missing(input.target, "target");
+          const oldPids = await pidsFor(pm2, target);
+          const result = await callbackCall(pm2, "reload", [target, input.options || {}]);
+          await verifyTerminated(target, await survivorsOf(pm2, target, oldPids), "reload");
+          return result;
+        }
+        case "delete": {
+          const target = missing(input.target, "target");
+          const oldPids = await pidsFor(pm2, target);
+          const result = await callbackCall(pm2, "delete", [target]);
+          await verifyTerminated(target, oldPids, "delete");
+          return result;
+        }
         case "scale": return callbackCall(pm2, "scale", [missing(input.target, "target"), missing(input.instances, "instances")]);
         case "reset": return callbackCall(pm2, "reset", [missing(input.target, "target")]);
         case "dump": return callbackCall(pm2, "dump");

package/cli/services/file-io.js

@@ -4,6 +4,7 @@
 // git-exec.js/fs-upload-sessions.js — these are file-content concerns, not
 // mount-resolution concerns.
 
+import fsSync from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { mkdir, writeFile, rename, stat, readFile } from "node:fs/promises";
@@ -12,16 +13,33 @@ export function sha256Hex(value) {
   return crypto.createHash("sha256").update(value).digest("hex");
 }
 
-export async function atomicWriteText(filePath, content) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const tempPath = path.join(
+function atomicTempPath(filePath) {
+  return path.join(
     path.dirname(filePath),
     `.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`
   );
+}
+
+export async function atomicWriteText(filePath, content) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = atomicTempPath(filePath);
   await writeFile(tempPath, content, "utf8");
   await rename(tempPath, filePath);
 }
 
+// Sync twin of atomicWriteText -- same mkdir+temp+write+rename contract, for
+// callers that can't be async (e.g. cli/supervisor-registry.js's mutators,
+// all currently synchronous). Identified as a needed pairing rather than a
+// fourth independent reimplementation of this pattern (also hand-rolled in
+// cli/ops/job-store.js and standalone/fs-mcp/lib/webdav-config.js) by a peer
+// review of the commit that first needed it.
+export function atomicWriteTextSync(filePath, content) {
+  fsSync.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = atomicTempPath(filePath);
+  fsSync.writeFileSync(tempPath, content, "utf8");
+  fsSync.renameSync(tempPath, filePath);
+}
+
 export async function fileInfo(filePath, requestedPath) {
   const s = await stat(filePath);
   const info = {

package/cli/services/file-io.test.js

@@ -1,10 +1,42 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 
-import { sha256Hex } from "./file-io.js";
+import { sha256Hex, atomicWriteTextSync } from "./file-io.js";
 
 test("sha256Hex hashes deterministically", () => {
   assert.equal(sha256Hex("hello"), sha256Hex("hello"));
   assert.notEqual(sha256Hex("hello"), sha256Hex("world"));
   assert.match(sha256Hex("hello"), /^[0-9a-f]{64}$/);
 });
+
+// atomicWriteTextSync is the sync twin of atomicWriteText, added so
+// cli/supervisor-registry.js's (synchronous) writeJson could reuse this
+// module's atomic-write contract instead of hand-rolling a fourth
+// independent copy of it (peer-review finding, 2026-09-02).
+test("atomicWriteTextSync creates the target file with the given content, creating parent dirs as needed", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-atomic-write-"));
+  try {
+    const target = path.join(root, "nested", "dir", "file.txt");
+    atomicWriteTextSync(target, "hello world");
+    assert.equal(fs.readFileSync(target, "utf8"), "hello world");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("atomicWriteTextSync replaces existing content and leaves no temp file behind", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-atomic-write-"));
+  try {
+    const target = path.join(root, "file.txt");
+    atomicWriteTextSync(target, "first");
+    atomicWriteTextSync(target, "second");
+    assert.equal(fs.readFileSync(target, "utf8"), "second");
+    const leftovers = fs.readdirSync(root).filter((name) => name !== "file.txt");
+    assert.deepEqual(leftovers, [], `expected no stray temp files, found: ${JSON.stringify(leftovers)}`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});