@remnic/core 1.1.31 → 9.3.515

package/src/connectors/live/state-store.ts

@@ -21,15 +21,14 @@
  * touches this module.
  */
 
+import { randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 
 import { expandTildePath } from "../../utils/path.js";
 
-import {
-  isValidConnectorId,
-  type ConnectorCursor,
-} from "./framework.js";
+import { type ConnectorCursor, isValidConnectorId } from "./framework.js";
 
 /**
  * Status of the most recent sync attempt for a connector.
@@ -66,12 +65,13 @@ export interface ConnectorState {
 
 const STATE_DIR_NAME = "state";
 const CONNECTORS_DIR_NAME = "connectors";
+const CONNECTOR_LOCKS_DIR_NAME = "connector-locks";
 const MAX_ERROR_LENGTH = 1024;
-const VALID_SYNC_STATUSES: ReadonlySet<ConnectorSyncStatus> = new Set([
-  "success",
-  "error",
-  "never",
-]);
+const CONNECTOR_LOCK_STALE_MS = 10 * 60 * 1000;
+const CONNECTOR_LOCK_HEARTBEAT_MS = Math.max(1_000, Math.floor(CONNECTOR_LOCK_STALE_MS / 4));
+const CONNECTOR_LOCK_TIMEOUT_MS = 60 * 1000;
+const CONNECTOR_LOCK_RETRY_MS = 50;
+const VALID_SYNC_STATUSES: ReadonlySet<ConnectorSyncStatus> = new Set(["success", "error", "never"]);
 
 /**
  * Internal error thrown when a state file's JSON is unparseable or its shape
@@ -86,6 +86,30 @@ class ConnectorStateCorruptionError extends Error {
   }
 }
 
+export class ConnectorStateLockLostError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConnectorStateLockLostError";
+  }
+}
+
+interface ConnectorLockLease {
+  readonly path: string;
+  readonly token: string;
+}
+
+interface ConnectorLockMetadata {
+  readonly pid: number;
+  readonly token: string;
+  readonly createdAt: string;
+  readonly refreshedAt: string;
+}
+
+interface ConnectorStateLockOptions {
+  readonly heartbeatMs?: number;
+  readonly unrefHeartbeat?: boolean;
+}
+
 /**
  * Resolve `<memoryDir>/state/connectors/`, expanding `~` per CLAUDE.md #17.
  */
@@ -96,6 +120,13 @@ function resolveConnectorsDir(memoryDir: string): string {
   return path.join(expandTildePath(memoryDir), STATE_DIR_NAME, CONNECTORS_DIR_NAME);
 }
 
+function resolveConnectorLocksDir(memoryDir: string): string {
+  if (typeof memoryDir !== "string" || memoryDir.length === 0) {
+    throw new TypeError("memoryDir must be a non-empty string");
+  }
+  return path.join(expandTildePath(memoryDir), STATE_DIR_NAME, CONNECTOR_LOCKS_DIR_NAME);
+}
+
 /**
  * Resolve the state file path for a single connector. Throws on invalid id
  * to prevent path traversal via crafted ids.
@@ -103,12 +134,21 @@ function resolveConnectorsDir(memoryDir: string): string {
 function resolveConnectorStatePath(memoryDir: string, id: string): string {
   if (!isValidConnectorId(id)) {
     throw new TypeError(
-      `invalid connector id ${JSON.stringify(id)} — must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`,
+      `invalid connector id ${JSON.stringify(id)} — must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`
     );
   }
   return path.join(resolveConnectorsDir(memoryDir), `${id}.json`);
 }
 
+function resolveConnectorLockPath(memoryDir: string, id: string): string {
+  if (!isValidConnectorId(id)) {
+    throw new TypeError(
+      `invalid connector id ${JSON.stringify(id)} — must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`
+    );
+  }
+  return path.join(resolveConnectorLocksDir(memoryDir), `${id}.lock`);
+}
+
 /**
  * Type guard for parsed state records. Validates the on-disk shape so a
  * corrupted/edited file produces a clear error rather than crashing later.
@@ -139,6 +179,58 @@ function isConnectorStateShape(value: unknown): value is ConnectorState {
   return true;
 }
 
+function isConnectorLockMetadata(value: unknown): value is ConnectorLockMetadata {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.pid === "number" &&
+    Number.isInteger(v.pid) &&
+    v.pid > 0 &&
+    typeof v.token === "string" &&
+    v.token.length > 0 &&
+    typeof v.createdAt === "string" &&
+    typeof v.refreshedAt === "string"
+  );
+}
+
+function connectorLockMetadata(token: string, createdAt = new Date().toISOString()): ConnectorLockMetadata {
+  return {
+    pid: process.pid,
+    token,
+    createdAt,
+    refreshedAt: new Date().toISOString(),
+  };
+}
+
+async function readConnectorLockMetadata(lockPath: string): Promise<ConnectorLockMetadata | null> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(lockPath, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return isConnectorLockMetadata(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseConnectorLockMetadata(raw: string): ConnectorLockMetadata | null {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return isConnectorLockMetadata(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isSameFileIdentity(left: import("node:fs").Stats, right: import("node:fs").Stats): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
 /**
  * Reject any path component along `<memoryDir>/state/connectors/<id>.json`
  * that is a symlink. Without this guard, a symlink in any of those
@@ -160,9 +252,7 @@ async function assertNoSymlinkOnPath(memoryDir: string, filePath: string): Promi
   const rel = path.relative(root, target);
   // path.relative() yields a "../..." prefix when target escapes root.
   if (rel.startsWith("..") || path.isAbsolute(rel)) {
-    throw new Error(
-      `connector state path ${target} escapes memory root ${root}`,
-    );
+    throw new Error(`connector state path ${target} escapes memory root ${root}`);
   }
   // Walk every component from root to target (inclusive) and lstat each.
   const segments = rel.length === 0 ? [] : rel.split(path.sep);
@@ -184,13 +274,310 @@ async function assertNoSymlinkOnPath(memoryDir: string, filePath: string): Promi
       throw err;
     }
     if (stat.isSymbolicLink()) {
-      throw new Error(
-        `connector state path component ${component} is a symlink; refusing to follow`,
-      );
+      throw new Error(`connector state path component ${component} is a symlink; refusing to follow`);
     }
   }
 }
 
+async function tryAcquireConnectorLock(memoryDir: string, id: string): Promise<ConnectorLockLease | null> {
+  const dir = resolveConnectorLocksDir(memoryDir);
+  const lockPath = resolveConnectorLockPath(memoryDir, id);
+  await assertNoSymlinkOnPath(memoryDir, lockPath);
+  await fs.mkdir(dir, { recursive: true });
+  let handle: Awaited<ReturnType<typeof fs.open>> | null = null;
+  let acquiredLockFile = false;
+  const token = randomUUID();
+  try {
+    handle = await fs.open(lockPath, "wx", 0o600);
+    acquiredLockFile = true;
+    await handle.writeFile(`${JSON.stringify(connectorLockMetadata(token))}\n`, "utf8");
+    await handle.close();
+    handle = null;
+    return { path: lockPath, token };
+  } catch (err) {
+    if (acquiredLockFile) {
+      if (handle !== null) {
+        try {
+          await handle.close();
+        } catch {
+          // The original write/close failure is more actionable.
+        }
+      }
+      try {
+        await fs.unlink(lockPath);
+      } catch (cleanupErr) {
+        if ((cleanupErr as NodeJS.ErrnoException).code !== "ENOENT") {
+          throw new AggregateError(
+            [err, cleanupErr],
+            `failed to initialize connector state lock at ${lockPath}; cleanup also failed`
+          );
+        }
+      }
+      throw err;
+    }
+    if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw err;
+    }
+    let stat: import("node:fs").Stats;
+    try {
+      stat = await fs.lstat(lockPath);
+    } catch (statErr) {
+      if ((statErr as NodeJS.ErrnoException).code === "ENOENT") {
+        return null;
+      }
+      throw statErr;
+    }
+    if (stat.isSymbolicLink()) {
+      throw new Error(`connector state path component ${lockPath} is a symlink; refusing to follow`);
+    }
+    if (Date.now() - stat.mtimeMs > CONNECTOR_LOCK_STALE_MS) {
+      await unlinkStaleConnectorLock(lockPath);
+      return null;
+    }
+    return null;
+  }
+}
+
+async function shouldUnlinkStaleConnectorLock(lockPath: string, stat: import("node:fs").Stats): Promise<boolean> {
+  if (Date.now() - stat.mtimeMs <= CONNECTOR_LOCK_STALE_MS) return false;
+  const metadata = await readConnectorLockMetadata(lockPath);
+  if (metadata === null) return true;
+  const refreshedAtMs = Date.parse(metadata.refreshedAt);
+  if (!Number.isFinite(refreshedAtMs)) return true;
+  return Date.now() - refreshedAtMs > CONNECTOR_LOCK_STALE_MS;
+}
+
+async function unlinkStaleConnectorLock(lockPath: string): Promise<void> {
+  const reclaimHandle = await openConnectorReclaimLock(lockPath);
+  if (!reclaimHandle) return;
+  try {
+    await reclaimHandle.writeFile(`${process.pid}:${new Date().toISOString()}`, "utf8");
+    await unlinkStaleConnectorLockWhileReclaimHeld(lockPath);
+  } finally {
+    await reclaimHandle.close().catch(() => undefined);
+    await fs.unlink(connectorReclaimLockPath(lockPath)).catch(() => undefined);
+  }
+}
+
+async function unlinkStaleConnectorLockWhileReclaimHeld(lockPath: string): Promise<void> {
+  let stat: import("node:fs").Stats;
+  try {
+    stat = await fs.lstat(lockPath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw err;
+  }
+  if (stat.isSymbolicLink()) {
+    throw new Error(`connector state path component ${lockPath} is a symlink; refusing to follow`);
+  }
+  if (!(await shouldUnlinkStaleConnectorLock(lockPath, stat))) return;
+  try {
+    await fs.unlink(lockPath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw err;
+    }
+  }
+}
+
+function connectorReclaimLockPath(lockPath: string): string {
+  return `${lockPath}.reclaim`;
+}
+
+async function openConnectorReclaimLock(lockPath: string): Promise<Awaited<ReturnType<typeof fs.open>> | null> {
+  const reclaimPath = connectorReclaimLockPath(lockPath);
+  try {
+    return await fs.open(reclaimPath, "wx");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+  }
+
+  let reclaimStat: import("node:fs").Stats;
+  try {
+    reclaimStat = await fs.lstat(reclaimPath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+  if (reclaimStat.isSymbolicLink()) {
+    throw new Error(`connector state path component ${reclaimPath} is a symlink; refusing to follow`);
+  }
+  if (Date.now() - reclaimStat.mtimeMs <= CONNECTOR_LOCK_STALE_MS) return null;
+  await fs.unlink(reclaimPath);
+
+  try {
+    return await fs.open(reclaimPath, "wx");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "EEXIST") return null;
+    throw err;
+  }
+}
+
+async function refreshConnectorLock(lease: ConnectorLockLease): Promise<boolean> {
+  const reclaimHandle = await openConnectorReclaimLock(lease.path);
+  if (!reclaimHandle) return false;
+  try {
+    await reclaimHandle.writeFile(`${process.pid}:${new Date().toISOString()}`, "utf8");
+    return await refreshConnectorLockWhileReclaimHeld(lease);
+  } finally {
+    await reclaimHandle.close().catch(() => undefined);
+    await fs.unlink(connectorReclaimLockPath(lease.path)).catch(() => undefined);
+  }
+}
+
+async function refreshConnectorLockWhileReclaimHeld(lease: ConnectorLockLease): Promise<boolean> {
+  let handle: Awaited<ReturnType<typeof fs.open>>;
+  try {
+    handle = await fs.open(lease.path, "r+");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw err;
+  }
+  try {
+    const openedStat = await handle.stat();
+    const metadata = parseConnectorLockMetadata(await handle.readFile("utf8"));
+    if (metadata?.token !== lease.token) return false;
+    const body = `${JSON.stringify(connectorLockMetadata(lease.token, metadata.createdAt))}\n`;
+    await handle.truncate(0);
+    await handle.write(body, 0, "utf8");
+    let pathStat: import("node:fs").Stats;
+    try {
+      pathStat = await fs.lstat(lease.path);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return false;
+      throw err;
+    }
+    if (pathStat.isSymbolicLink()) {
+      throw new Error(`connector state path component ${lease.path} is a symlink; refusing to follow`);
+    }
+    return isSameFileIdentity(openedStat, pathStat);
+  } finally {
+    await handle.close();
+  }
+}
+
+async function releaseConnectorLock(lease: ConnectorLockLease): Promise<void> {
+  const reclaimHandle = await openConnectorReclaimLock(lease.path);
+  if (!reclaimHandle) return;
+  try {
+    await reclaimHandle.writeFile(`${process.pid}:${new Date().toISOString()}`, "utf8");
+    await releaseConnectorLockWhileReclaimHeld(lease);
+  } finally {
+    await reclaimHandle.close().catch(() => undefined);
+    await fs.unlink(connectorReclaimLockPath(lease.path)).catch(() => undefined);
+  }
+}
+
+async function releaseConnectorLockWhileReclaimHeld(lease: ConnectorLockLease): Promise<void> {
+  let handle: Awaited<ReturnType<typeof fs.open>>;
+  try {
+    handle = await fs.open(lease.path, "r");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw err;
+  }
+  try {
+    const openedStat = await handle.stat();
+    const metadata = parseConnectorLockMetadata(await handle.readFile("utf8"));
+    if (metadata?.token !== lease.token) return;
+    let pathStat: import("node:fs").Stats;
+    try {
+      pathStat = await fs.lstat(lease.path);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
+      throw err;
+    }
+    if (pathStat.isSymbolicLink()) {
+      throw new Error(`connector state path component ${lease.path} is a symlink; refusing to follow`);
+    }
+    if (!isSameFileIdentity(openedStat, pathStat)) return;
+    try {
+      await fs.unlink(lease.path);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw err;
+      }
+    }
+  } finally {
+    await handle.close();
+  }
+}
+
+async function withConnectorStateLockInternal<T>(
+  memoryDir: string,
+  id: string,
+  run: (abortSignal: AbortSignal) => Promise<T>,
+  options: ConnectorStateLockOptions = {}
+): Promise<T> {
+  const deadline = Date.now() + CONNECTOR_LOCK_TIMEOUT_MS;
+  let lease: ConnectorLockLease | null = null;
+  while (lease === null) {
+    lease = await tryAcquireConnectorLock(memoryDir, id);
+    if (lease !== null) break;
+    if (Date.now() >= deadline) {
+      throw new Error(`timed out waiting for connector "${id}" state lock`);
+    }
+    await delay(CONNECTOR_LOCK_RETRY_MS);
+  }
+  const abortController = new AbortController();
+  let rejectLockLost!: (err: Error) => void;
+  let lockLost = false;
+  const lockLostPromise = new Promise<never>((_resolve, reject) => {
+    rejectLockLost = reject;
+  });
+  const failLostLock = (message: string): void => {
+    if (lockLost) return;
+    lockLost = true;
+    const err = new ConnectorStateLockLostError(message);
+    abortController.abort(err);
+    rejectLockLost(err);
+  };
+  const heartbeat = setInterval(() => {
+    void refreshConnectorLock(lease)
+      .then((refreshed) => {
+        if (!refreshed) {
+          failLostLock(`lost connector "${id}" state lock`);
+        }
+      })
+      .catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        failLostLock(`lost connector "${id}" state lock: ${message}`);
+      });
+  }, options.heartbeatMs ?? CONNECTOR_LOCK_HEARTBEAT_MS);
+  if (options.unrefHeartbeat !== false) {
+    heartbeat.unref?.();
+  }
+  const runPromise = run(abortController.signal);
+  try {
+    return await Promise.race([runPromise, lockLostPromise]);
+  } catch (err) {
+    if (err instanceof ConnectorStateLockLostError) {
+      await runPromise.catch(() => undefined);
+    }
+    throw err;
+  } finally {
+    clearInterval(heartbeat);
+    await releaseConnectorLock(lease);
+  }
+}
+
+export async function withConnectorStateLock<T>(
+  memoryDir: string,
+  id: string,
+  run: (abortSignal: AbortSignal) => Promise<T>
+): Promise<T> {
+  return withConnectorStateLockInternal(memoryDir, id, run);
+}
+
+export async function _withConnectorStateLockForTest<T>(
+  memoryDir: string,
+  id: string,
+  run: (abortSignal: AbortSignal) => Promise<T>,
+  options: ConnectorStateLockOptions
+): Promise<T> {
+  return withConnectorStateLockInternal(memoryDir, id, run, options);
+}
+
 /**
  * Read the persisted state for a single connector.
  *
@@ -200,10 +587,7 @@ async function assertNoSymlinkOnPath(memoryDir: string, filePath: string): Promi
  * Rejects symlinks anywhere on the path so a planted symlink can't redirect
  * reads outside the memory root. (PR #724 review.)
  */
-export async function readConnectorState(
-  memoryDir: string,
-  id: string,
-): Promise<ConnectorState | null> {
+export async function readConnectorState(memoryDir: string, id: string): Promise<ConnectorState | null> {
   const filePath = resolveConnectorStatePath(memoryDir, id);
   await assertNoSymlinkOnPath(memoryDir, filePath);
   let raw: string;
@@ -218,17 +602,15 @@ export async function readConnectorState(
     parsed = JSON.parse(raw);
   } catch (err) {
     throw new ConnectorStateCorruptionError(
-      `connector state at ${filePath} is not valid JSON: ${(err as Error).message}`,
+      `connector state at ${filePath} is not valid JSON: ${(err as Error).message}`
     );
   }
   if (!isConnectorStateShape(parsed)) {
-    throw new ConnectorStateCorruptionError(
-      `connector state at ${filePath} does not match ConnectorState shape`,
-    );
+    throw new ConnectorStateCorruptionError(`connector state at ${filePath} does not match ConnectorState shape`);
   }
   if (parsed.id !== id) {
     throw new ConnectorStateCorruptionError(
-      `connector state at ${filePath} has mismatched id ${JSON.stringify(parsed.id)}; expected ${JSON.stringify(id)}`,
+      `connector state at ${filePath} has mismatched id ${JSON.stringify(parsed.id)}; expected ${JSON.stringify(id)}`
     );
   }
   return parsed;
@@ -244,16 +626,16 @@ export async function readConnectorState(
 export async function writeConnectorState(
   memoryDir: string,
   id: string,
-  state: Omit<ConnectorState, "updatedAt">,
+  state: Omit<ConnectorState, "updatedAt">
 ): Promise<ConnectorState> {
   if (!isValidConnectorId(id)) {
     throw new TypeError(
-      `invalid connector id ${JSON.stringify(id)} — must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`,
+      `invalid connector id ${JSON.stringify(id)} — must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`
     );
   }
   if (state.id !== id) {
     throw new Error(
-      `writeConnectorState(): state.id ${JSON.stringify(state.id)} does not match id argument ${JSON.stringify(id)}`,
+      `writeConnectorState(): state.id ${JSON.stringify(state.id)} does not match id argument ${JSON.stringify(id)}`
     );
   }
   // Full boundary validation. Persisting an out-of-shape record would brick
@@ -262,13 +644,11 @@ export async function writeConnectorState(
   // bypassing TS types must be rejected here, not later. (PR #724 review.)
   if (!VALID_SYNC_STATUSES.has(state.lastSyncStatus as ConnectorSyncStatus)) {
     throw new Error(
-      `writeConnectorState(): lastSyncStatus must be one of ${[...VALID_SYNC_STATUSES].join(", ")}, got ${JSON.stringify(state.lastSyncStatus)}`,
+      `writeConnectorState(): lastSyncStatus must be one of ${[...VALID_SYNC_STATUSES].join(", ")}, got ${JSON.stringify(state.lastSyncStatus)}`
     );
   }
   if (state.lastSyncAt !== null && typeof state.lastSyncAt !== "string") {
-    throw new Error(
-      `writeConnectorState(): lastSyncAt must be a string or null, got ${typeof state.lastSyncAt}`,
-    );
+    throw new Error(`writeConnectorState(): lastSyncAt must be a string or null, got ${typeof state.lastSyncAt}`);
   }
   if (state.cursor !== null) {
     if (typeof state.cursor !== "object") {
@@ -279,9 +659,7 @@ export async function writeConnectorState(
       typeof state.cursor.value !== "string" ||
       typeof state.cursor.updatedAt !== "string"
     ) {
-      throw new Error(
-        `writeConnectorState(): cursor must have string kind, value, and updatedAt`,
-      );
+      throw new Error(`writeConnectorState(): cursor must have string kind, value, and updatedAt`);
     }
   }
   if (
@@ -289,9 +667,7 @@ export async function writeConnectorState(
     !Number.isInteger(state.totalDocsImported) ||
     state.totalDocsImported < 0
   ) {
-    throw new Error(
-      `writeConnectorState(): totalDocsImported must be a non-negative integer`,
-    );
+    throw new Error(`writeConnectorState(): totalDocsImported must be a non-negative integer`);
   }
   if (state.lastSyncError !== undefined && typeof state.lastSyncError !== "string") {
     throw new Error(`writeConnectorState(): lastSyncError must be a string when provided`);
@@ -397,3 +773,8 @@ export async function listConnectorStates(memoryDir: string): Promise<ConnectorS
 export function _connectorStatePathForTest(memoryDir: string, id: string): string {
   return resolveConnectorStatePath(memoryDir, id);
 }
+
+export const _unlinkStaleConnectorLockForTest = unlinkStaleConnectorLock;
+export const _tryAcquireConnectorLockForTest = tryAcquireConnectorLock;
+export const _refreshConnectorLockForTest = refreshConnectorLock;
+export const _releaseConnectorLockForTest = releaseConnectorLock;

package/src/connectors/weclone-installer.test.ts

@@ -465,15 +465,15 @@ test("installConnector weclone install error reports token rollback status truth
       REMNIC_HOME: sandbox.remnicHome,
     },
     () => {
-      // Force proxy write to fail so we hit the WeClone catch branch.
+      // Force proxy atomic replace to fail so we hit the WeClone catch branch.
       const proxyConfigPath = resolveWeCloneProxyConfigPath();
-      const originalWrite = fs.writeFileSync.bind(fs);
+      const originalRename = fs.renameSync.bind(fs);
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const mock = t.mock.method(fs, "writeFileSync", (...args: [any, any, any?]) => {
-        if (String(args[0] ?? "") === proxyConfigPath) {
+      const mock = t.mock.method(fs, "renameSync", (...args: [any, any]) => {
+        if (String(args[1] ?? "") === proxyConfigPath) {
           throw new Error("ENOSPC: simulated proxy write failure");
         }
-        return originalWrite(...args);
+        return originalRename(...args);
       });
 
       const result = installConnector({ connectorId: "weclone" });
@@ -491,11 +491,10 @@ test("installConnector weclone install error reports token rollback status truth
   );
 });
 
-test("installConnector weclone restores prior proxy config when write throws mid-truncate", async (t) => {
-  // Reviewer (codex P2): writeSecretFileSync opens the file in truncate
-  // mode, so a mid-write failure (ENOSPC) can leave weclone.json empty.
-  // The rollback closure must be installed BEFORE the write so prior
-  // contents are restored on failure.
+test("installConnector weclone restores prior proxy config when atomic replace fails", async (t) => {
+  // Reviewer (codex P2): failures during the proxy-config replace must not
+  // corrupt or replace the prior weclone.json. The rollback closure is
+  // installed BEFORE the write so prior contents are restored on failure.
   const sandbox = makeSandbox(t);
   await withEnv(
     {
@@ -515,18 +514,17 @@ test("installConnector weclone restores prior proxy config when write throws mid
       const priorBytes = fs.readFileSync(proxyConfigPath, "utf8");
       assert.ok(priorBytes.length > 0);
 
-      // Now mock the internal writeFileSync so that the NEXT call targeting
-      // proxyConfigPath fails. We target writeFileSync because
-      // writeSecretFileSync calls through to it via a wrapper; catching that
-      // exception drives our new rollback path.
-      const originalWrite = fs.writeFileSync.bind(fs);
+      // Now mock the atomic rename so that the NEXT attempt to replace
+      // proxyConfigPath fails. writeSecretFileSync writes to a temp file and
+      // renames into place, so the destination path is the second arg.
+      const originalRename = fs.renameSync.bind(fs);
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const mock = t.mock.method(fs, "writeFileSync", (...args: [any, any, any?]) => {
-        const target = String(args[0] ?? "");
+      const mock = t.mock.method(fs, "renameSync", (...args: [any, any]) => {
+        const target = String(args[1] ?? "");
         if (target === proxyConfigPath) {
           throw new Error("ENOSPC: no space left on device (simulated)");
         }
-        return originalWrite(...args);
+        return originalRename(...args);
       });
 
       const second = installConnector({

package/src/connectors-cli.ts

@@ -63,6 +63,25 @@ export interface ConnectorRow {
   state: ConnectorState | null;
 }
 
+export interface ConnectorRowDefinition {
+  id: string;
+  displayName: string;
+  enabled: boolean;
+}
+
+export function buildConnectorRowsFromDefinitions(
+  definitions: readonly ConnectorRowDefinition[],
+  states: readonly ConnectorState[],
+): ConnectorRow[] {
+  const stateMap = new Map(states.map((state) => [state.id, state]));
+  return definitions.map((definition) => ({
+    id: definition.id,
+    displayName: definition.displayName,
+    enabled: definition.enabled,
+    state: stateMap.get(definition.id) ?? null,
+  }));
+}
+
 /**
  * Result returned by the `run` command's poll function.
  */