@vellumai/cli 0.11.3-dev.202608180132.6a0b3da → 0.11.3-dev.202608181511.30d84a2

package/node_modules/@vellumai/local-mode/src/__tests__/unpair.test.ts

@@ -229,4 +229,37 @@ describe("unpairAssistant", () => {
     }
     expect(result.status).toBe(400);
   });
+
+  test("refuses with 423 under a held write lock, leaving entry and token alone", () => {
+    writeLockfile({
+      assistants: [{ assistantId: "paired-1", cloud: "paired" }],
+      activeAssistant: "paired-1",
+    });
+    const tokenPath = seedGuardianToken("paired-1");
+    fs.mkdirSync(`${lockfilePath}.lock`);
+    try {
+      const result = unpairAssistant([lockfilePath], configDir, "paired-1");
+
+      expect(result).toMatchObject({ ok: false, status: 423 });
+      expect(fs.existsSync(tokenPath)).toBe(true);
+      expect(readLockfileFromDisk().assistants).toEqual([
+        { assistantId: "paired-1", cloud: "paired" },
+      ]);
+    } finally {
+      fs.rmdirSync(`${lockfilePath}.lock`);
+    }
+  });
+
+  test("a successful unpair leaves no lock dir behind", () => {
+    writeLockfile({
+      assistants: [{ assistantId: "paired-1", cloud: "paired" }],
+      activeAssistant: "paired-1",
+    });
+    seedGuardianToken("paired-1");
+
+    const result = unpairAssistant([lockfilePath], configDir, "paired-1");
+
+    expect(result.ok).toBe(true);
+    expect(fs.existsSync(`${lockfilePath}.lock`)).toBe(false);
+  });
 });

package/node_modules/@vellumai/local-mode/src/index.ts

@@ -37,6 +37,7 @@ export {
 } from "./environment";
 export {
   getLockfileData,
+  renameLockfileAssistantIfPresent,
   upsertLockfileAssistant,
   upsertRendererLockfileAssistant,
   replacePlatformAssistants,
@@ -44,6 +45,8 @@ export {
   isPairedLockfileEntry,
 } from "./lockfile";
 export type { LockfileResult, WriteResult } from "./lockfile";
+export { withLockfileLock } from "./lockfile-lock";
+export type { LockfileLockResult } from "./lockfile-lock";
 export { parseLockfile } from "./lockfile-contract";
 export type {
   Lockfile,

package/node_modules/@vellumai/local-mode/src/lockfile-lock.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { withLockfileLock } from "./lockfile-lock";
+
+let dir: string;
+let lockfilePath: string;
+let lockDir: string;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), "lockfile-lock-test-"));
+  lockfilePath = path.join(dir, "lockfile.json");
+  lockDir = `${lockfilePath}.lock`;
+});
+
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe("withLockfileLock", () => {
+  test("runs fn, propagates its result, and removes the lock dir", () => {
+    const result = withLockfileLock([lockfilePath], () => {
+      expect(fs.existsSync(lockDir)).toBe(true);
+      return 42;
+    });
+    expect(result).toEqual({ ok: true, value: 42 });
+    expect(fs.existsSync(lockDir)).toBe(false);
+  });
+
+  test("keys the lock to the write path, ignoring fallback paths", () => {
+    const fallback = path.join(dir, "legacy.json");
+    withLockfileLock([lockfilePath, fallback], () => {
+      expect(fs.existsSync(lockDir)).toBe(true);
+      expect(fs.existsSync(`${fallback}.lock`)).toBe(false);
+    });
+  });
+
+  test("releases the lock when fn throws, rethrowing", () => {
+    expect(() =>
+      withLockfileLock([lockfilePath], () => {
+        throw new Error("boom");
+      }),
+    ).toThrow("boom");
+    expect(fs.existsSync(lockDir)).toBe(false);
+  });
+
+  test("is reentrant within the process", () => {
+    const result = withLockfileLock([lockfilePath], () => {
+      const inner = withLockfileLock([lockfilePath], () => "inner");
+      expect(inner).toEqual({ ok: true, value: "inner" });
+      // Inner exit must not release the outer hold.
+      expect(fs.existsSync(lockDir)).toBe(true);
+      return "outer";
+    });
+    expect(result).toEqual({ ok: true, value: "outer" });
+    expect(fs.existsSync(lockDir)).toBe(false);
+  });
+
+  test("fails cleanly within budget when another holder is fresh", () => {
+    fs.mkdirSync(lockDir);
+    let ran = false;
+    const start = Date.now();
+    const result = withLockfileLock([lockfilePath], () => {
+      ran = true;
+    });
+    expect(Date.now() - start).toBeLessThan(2_000);
+    expect(ran).toBe(false);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain("Timed out acquiring lockfile lock");
+    }
+    // The other holder's lock is untouched.
+    expect(fs.existsSync(lockDir)).toBe(true);
+  });
+
+  test("breaks a stale lock left by a crashed holder", () => {
+    fs.mkdirSync(lockDir);
+    const past = new Date(Date.now() - 60_000);
+    fs.utimesSync(lockDir, past, past);
+
+    const result = withLockfileLock([lockfilePath], () => "ran");
+    expect(result).toEqual({ ok: true, value: "ran" });
+    expect(fs.existsSync(lockDir)).toBe(false);
+  });
+
+  test("creates a missing parent directory and acquires", () => {
+    const nested = path.join(dir, "a", "b", "lockfile.json");
+    const result = withLockfileLock([nested], () => "ran");
+    expect(result).toEqual({ ok: true, value: "ran" });
+    expect(fs.existsSync(`${nested}.lock`)).toBe(false);
+  });
+
+  test("refuses an empty path list", () => {
+    expect(withLockfileLock([], () => "never").ok).toBe(false);
+  });
+});

package/node_modules/@vellumai/local-mode/src/lockfile-lock.ts

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export type LockfileLockResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: string };
+
+/** A holder only holds for the microseconds a read-modify-write takes, so a
+ *  lock this old belongs to a crashed process and is safe to break. */
+const STALE_LOCK_MS = 5_000;
+const ACQUIRE_ATTEMPTS = 10;
+const RETRY_DELAY_MS = 25;
+
+/** Locks held by this process, so composed writers reenter instead of deadlocking. */
+const heldLocks = new Set<string>();
+
+/** Node-compatible synchronous sleep (no Bun.sleepSync in Electron/Vite hosts). */
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function tryBreakStaleLock(lockDir: string): void {
+  try {
+    if (Date.now() - fs.statSync(lockDir).mtimeMs > STALE_LOCK_MS) {
+      fs.rmdirSync(lockDir);
+    }
+  } catch {
+    // Holder released or another contender broke it; next mkdir attempt decides.
+  }
+}
+
+/**
+ * Run `fn` under a cross-process advisory lock keyed to the lockfile write
+ * path (`lockfilePaths[0]`). The lock is a `${writePath}.lock` directory:
+ * mkdir has O_EXCL semantics on every platform, so exactly one process wins.
+ * Acquisition is bounded (~250ms worst case) and failure is returned
+ * structurally rather than thrown, so never-throw seams stay never-throw;
+ * `fn`'s own exceptions propagate, with the lock released in `finally`.
+ */
+export function withLockfileLock<T>(
+  lockfilePaths: string[],
+  fn: () => T,
+): LockfileLockResult<T> {
+  const writePath = lockfilePaths[0];
+  if (!writePath) {
+    return { ok: false, error: "No lockfile path to lock" };
+  }
+  const lockDir = `${writePath}.lock`;
+
+  if (heldLocks.has(lockDir)) {
+    return { ok: true, value: fn() };
+  }
+
+  let acquired = false;
+  for (let attempt = 0; attempt < ACQUIRE_ATTEMPTS; attempt++) {
+    if (attempt > 0) sleepSync(RETRY_DELAY_MS);
+    try {
+      fs.mkdirSync(lockDir);
+      acquired = true;
+      break;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "EEXIST") {
+        tryBreakStaleLock(lockDir);
+        continue;
+      }
+      if (code === "ENOENT") {
+        try {
+          fs.mkdirSync(path.dirname(lockDir), { recursive: true });
+        } catch {
+          // Surfaced by the next mkdir attempt.
+        }
+        continue;
+      }
+      return { ok: false, error: `Failed to acquire lockfile lock: ${err}` };
+    }
+  }
+  if (!acquired) {
+    return {
+      ok: false,
+      error: `Timed out acquiring lockfile lock at ${lockDir}`,
+    };
+  }
+
+  heldLocks.add(lockDir);
+  try {
+    return { ok: true, value: fn() };
+  } finally {
+    heldLocks.delete(lockDir);
+    try {
+      fs.rmdirSync(lockDir);
+    } catch {
+      // Best effort; a leftover dir is broken as stale by the next acquirer.
+    }
+  }
+}

package/node_modules/@vellumai/local-mode/src/lockfile.test.ts

@@ -6,6 +6,7 @@ import path from "node:path";
 import {
   getLockfileData,
   isPairedLockfileEntry,
+  renameLockfileAssistantIfPresent,
   replacePlatformAssistants,
   upsertLockfileAssistant,
   upsertRendererLockfileAssistant,
@@ -224,6 +225,33 @@ describe("upsertLockfileAssistant", () => {
     });
   });
 
+  test("a name-only payload preserves resources and on-disk secrets byte-for-byte", () => {
+    const entry = {
+      assistantId: "asst_1",
+      cloud: "local",
+      runtimeUrl: "http://a",
+      name: "Old Name",
+      resources: { gatewayPort: 7830, daemonPort: 7831, dataDir: "/tmp/x" },
+      signingKey: "sk-on-disk-secret",
+      bearerToken: "bt-on-disk-secret",
+      guardianBootstrapSecret: "gb-on-disk-secret",
+    };
+    writeOnDisk({ activeAssistant: "asst_1", assistants: [entry] });
+
+    const result = upsertLockfileAssistant(
+      [lockfilePath],
+      { assistantId: "asst_1", name: "Renamed" },
+      undefined,
+    );
+
+    expect(result.ok).toBe(true);
+    const assistants = readOnDisk().assistants as Array<
+      Record<string, unknown>
+    >;
+    expect(assistants).toHaveLength(1);
+    expect(assistants[0]).toEqual({ ...entry, name: "Renamed" });
+  });
+
   test("preserves activeAssistant when no active id is provided", () => {
     writeOnDisk({
       activeAssistant: "asst_active",
@@ -251,6 +279,198 @@ describe("upsertLockfileAssistant", () => {
   });
 });
 
+describe("renameLockfileAssistantIfPresent", () => {
+  const entry = {
+    assistantId: "asst_1",
+    cloud: "local",
+    runtimeUrl: "http://a",
+    name: "Old Name",
+    resources: { gatewayPort: 7830, daemonPort: 7831, dataDir: "/tmp/x" },
+    signingKey: "sk-on-disk-secret",
+    bearerToken: "bt-on-disk-secret",
+  };
+
+  test("renames the entry preserving resources, secrets, and activeAssistant", () => {
+    writeOnDisk({
+      activeAssistant: "asst_other",
+      assistants: [entry, { assistantId: "asst_other", cloud: "local" }],
+    });
+
+    const result = renameLockfileAssistantIfPresent(
+      [lockfilePath],
+      "asst_1",
+      "Renamed",
+    );
+
+    expect(result.ok).toBe(true);
+    const onDisk = readOnDisk();
+    expect(onDisk.activeAssistant).toBe("asst_other");
+    const assistants = onDisk.assistants as Array<Record<string, unknown>>;
+    expect(assistants).toEqual([
+      { ...entry, name: "Renamed" },
+      { assistantId: "asst_other", cloud: "local" },
+    ]);
+  });
+
+  test("refuses a missing entry without writing the file", () => {
+    const result = renameLockfileAssistantIfPresent(
+      [lockfilePath],
+      "asst_gone",
+      "Renamed",
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      status: 404,
+      error: "No lockfile entry for this assistant",
+    });
+    expect(fs.existsSync(lockfilePath)).toBe(false);
+  });
+
+  test("refuses when the id names another process's retired entry", () => {
+    writeOnDisk({ activeAssistant: null, assistants: [entry] });
+    const before = fs.readFileSync(lockfilePath, "utf-8");
+
+    const result = renameLockfileAssistantIfPresent(
+      [lockfilePath],
+      "asst_retired",
+      "Renamed",
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.status).toBe(404);
+    }
+    expect(fs.readFileSync(lockfilePath, "utf-8")).toBe(before);
+  });
+
+  test("refuses a corrupt on-disk file without clobbering it", () => {
+    fs.writeFileSync(lockfilePath, "{ not json");
+
+    const result = renameLockfileAssistantIfPresent(
+      [lockfilePath],
+      "asst_1",
+      "Renamed",
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.status).toBe(409);
+    }
+    expect(fs.readFileSync(lockfilePath, "utf-8")).toBe("{ not json");
+  });
+
+  test("an already-equal name succeeds without rewriting the file", () => {
+    // Compact formatting: any rewrite would re-indent and change the bytes.
+    fs.writeFileSync(
+      lockfilePath,
+      JSON.stringify({ activeAssistant: null, assistants: [entry] }),
+    );
+    const before = fs.readFileSync(lockfilePath, "utf-8");
+
+    const result = renameLockfileAssistantIfPresent(
+      [lockfilePath],
+      "asst_1",
+      "Old Name",
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.lockfile.assistants[0]?.name).toBe("Old Name");
+      expect(result.lockfile.assistants[0]).not.toHaveProperty("signingKey");
+    }
+    expect(fs.readFileSync(lockfilePath, "utf-8")).toBe(before);
+  });
+
+  test("rejects a missing id or name without touching disk", () => {
+    writeOnDisk({ activeAssistant: null, assistants: [entry] });
+    const before = fs.readFileSync(lockfilePath, "utf-8");
+
+    expect(renameLockfileAssistantIfPresent([lockfilePath], "", "N").ok).toBe(
+      false,
+    );
+    expect(
+      renameLockfileAssistantIfPresent([lockfilePath], "asst_1", "").ok,
+    ).toBe(false);
+    expect(fs.readFileSync(lockfilePath, "utf-8")).toBe(before);
+  });
+});
+
+describe("lockfile writers under lock contention", () => {
+  const entry = {
+    assistantId: "asst_1",
+    cloud: "local",
+    runtimeUrl: "http://a",
+    name: "Old Name",
+  };
+
+  function holdLock(): string {
+    const lockDir = `${lockfilePath}.lock`;
+    fs.mkdirSync(lockDir);
+    return lockDir;
+  }
+
+  test("rename refuses with 423 and leaves the file untouched", () => {
+    writeOnDisk({ activeAssistant: null, assistants: [entry] });
+    const before = fs.readFileSync(lockfilePath, "utf-8");
+    holdLock();
+
+    const result = renameLockfileAssistantIfPresent(
+      [lockfilePath],
+      "asst_1",
+      "Renamed",
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.status).toBe(423);
+    }
+    expect(fs.readFileSync(lockfilePath, "utf-8")).toBe(before);
+  });
+
+  test("upsert refuses with 423 and leaves the file untouched", () => {
+    writeOnDisk({ activeAssistant: null, assistants: [entry] });
+    const before = fs.readFileSync(lockfilePath, "utf-8");
+    holdLock();
+
+    const result = upsertLockfileAssistant(
+      [lockfilePath],
+      { assistantId: "asst_2", cloud: "local" },
+      undefined,
+    );
+
+    expect(result).toMatchObject({ ok: false, status: 423 });
+    expect(fs.readFileSync(lockfilePath, "utf-8")).toBe(before);
+  });
+
+  test("platform replace refuses with 423 and leaves the file untouched", () => {
+    writeOnDisk({ activeAssistant: null, assistants: [entry] });
+    const before = fs.readFileSync(lockfilePath, "utf-8");
+    holdLock();
+
+    const result = replacePlatformAssistants(
+      [lockfilePath],
+      [{ assistantId: "asst_p", cloud: "vellum", runtimeUrl: "http://p" }],
+    );
+
+    expect(result).toMatchObject({ ok: false, status: 423 });
+    expect(fs.readFileSync(lockfilePath, "utf-8")).toBe(before);
+  });
+
+  test("a successful rename leaves no lock dir behind", () => {
+    writeOnDisk({ activeAssistant: null, assistants: [entry] });
+
+    const result = renameLockfileAssistantIfPresent(
+      [lockfilePath],
+      "asst_1",
+      "Renamed",
+    );
+
+    expect(result.ok).toBe(true);
+    expect(fs.existsSync(`${lockfilePath}.lock`)).toBe(false);
+  });
+});
+
 describe("upsertRendererLockfileAssistant", () => {
   const paired = {
     assistantId: "paired-1",

package/node_modules/@vellumai/local-mode/src/lockfile.ts

@@ -6,6 +6,7 @@ import {
   resolveCloud,
   type Lockfile,
 } from "./lockfile-contract";
+import { withLockfileLock } from "./lockfile-lock";
 import { stripSensitiveFields } from "./util";
 
 export type LockfileResult =
@@ -63,6 +64,11 @@ export type WriteResult =
   | { ok: true; lockfile: Lockfile }
   | { ok: false; status: number; error: string };
 
+/** 423 Locked: the cross-process advisory lock could not be acquired. */
+function lockFailure(error: string): WriteResult {
+  return { ok: false, status: 423, error };
+}
+
 /**
  * Read the first parseable lockfile as raw JSON (unknown fields intact) for a
  * read-modify-write cycle; an unreadable file yields an empty lockfile.
@@ -83,6 +89,50 @@ export function readRawLockfile(
   return { assistants: [], activeAssistant: null };
 }
 
+export type RawLockfileReadResult =
+  | { ok: true; lockfile: Record<string, unknown> }
+  | { ok: false; error: string };
+
+/**
+ * Like {@link readRawLockfile}, but a file that exists and cannot be read or
+ * parsed refuses instead of degrading to the empty registry. Missing or empty
+ * files still yield the empty registry. Use for writes that must never
+ * replace a registry they could not actually read.
+ */
+export function readRawLockfileStrict(
+  lockfilePaths: string[],
+): RawLockfileReadResult {
+  for (const candidate of lockfilePaths) {
+    let raw: string;
+    try {
+      raw = fs.readFileSync(candidate, "utf-8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") continue;
+      return { ok: false, error: `Failed to read lockfile: ${err}` };
+    }
+    if (raw.trim() === "") continue;
+    try {
+      return {
+        ok: true,
+        lockfile: JSON.parse(raw) as Record<string, unknown>,
+      };
+    } catch (err) {
+      return { ok: false, error: `Failed to parse lockfile: ${err}` };
+    }
+  }
+  return { ok: true, lockfile: { assistants: [], activeAssistant: null } };
+}
+
+/** The validated, sensitive-field-stripped wire view of a raw lockfile. */
+function toWireLockfile(lockfile: Record<string, unknown>): Lockfile {
+  const stripped = JSON.parse(JSON.stringify(lockfile)) as Record<
+    string,
+    unknown
+  >;
+  stripSensitiveFields(stripped);
+  return parseLockfile(stripped);
+}
+
 /**
  * Atomically persist a raw lockfile (write-to-temp + rename) and return the
  * validated, sensitive-field-stripped view of what was written.
@@ -102,12 +152,56 @@ export function writeRawLockfile(
     return { ok: false, status: 500, error: `Failed to write lockfile: ${err}` };
   }
 
-  const stripped = JSON.parse(JSON.stringify(lockfile)) as Record<
-    string,
-    unknown
-  >;
-  stripSensitiveFields(stripped);
-  return { ok: true, lockfile: parseLockfile(stripped) };
+  return { ok: true, lockfile: toWireLockfile(lockfile) };
+}
+
+/**
+ * Rename an existing assistant entry, never creating one. Unlike the upserts,
+ * a missing entry refuses (404) and an unreadable on-disk file refuses (409)
+ * instead of being treated as an empty registry, so a stale renderer cache
+ * can neither resurrect a retired assistant nor replace a registry it could
+ * not read with a skeleton row. Never touches `activeAssistant`. The whole
+ * read-check-write runs under the shared advisory lock so a concurrent writer
+ * (e.g. a CLI retire) cannot be clobbered by this snapshot; lock contention
+ * refuses (423) without writing.
+ */
+export function renameLockfileAssistantIfPresent(
+  lockfilePaths: string[],
+  assistantId: string,
+  name: string,
+): WriteResult {
+  if (typeof assistantId !== "string" || assistantId === "") {
+    return { ok: false, status: 400, error: "Missing assistantId" };
+  }
+  if (typeof name !== "string" || name === "") {
+    return { ok: false, status: 400, error: "Missing name" };
+  }
+
+  const locked = withLockfileLock(lockfilePaths, (): WriteResult => {
+    const read = readRawLockfileStrict(lockfilePaths);
+    if (!read.ok) {
+      return { ok: false, status: 409, error: read.error };
+    }
+    const lockfile = read.lockfile;
+    const assistants = Array.isArray(lockfile.assistants)
+      ? (lockfile.assistants as Array<Record<string, unknown>>)
+      : [];
+    const idx = assistants.findIndex((a) => a?.assistantId === assistantId);
+    if (idx < 0) {
+      return {
+        ok: false,
+        status: 404,
+        error: "No lockfile entry for this assistant",
+      };
+    }
+    if (assistants[idx]!.name === name) {
+      return { ok: true, lockfile: toWireLockfile(lockfile) };
+    }
+    assistants[idx] = { ...assistants[idx], name };
+    lockfile.assistants = assistants;
+    return writeRawLockfile(lockfilePaths, lockfile);
+  });
+  return locked.ok ? locked.value : lockFailure(locked.error);
 }
 
 export function upsertLockfileAssistant(
@@ -119,22 +213,25 @@ export function upsertLockfileAssistant(
     return { ok: false, status: 400, error: "Missing assistant.assistantId" };
   }
 
-  const lockfile = readRawLockfile(lockfilePaths);
-  const assistants = Array.isArray(lockfile.assistants) ? lockfile.assistants : [];
-  const existingIdx = assistants.findIndex(
-    (a: Record<string, unknown>) => a?.assistantId === assistant.assistantId,
-  );
-  if (existingIdx >= 0) {
-    assistants[existingIdx] = { ...assistants[existingIdx], ...assistant };
-  } else {
-    assistants.push(assistant);
-  }
-  lockfile.assistants = assistants;
-  if (activeAssistant !== undefined) {
-    lockfile.activeAssistant = activeAssistant;
-  }
+  const locked = withLockfileLock(lockfilePaths, (): WriteResult => {
+    const lockfile = readRawLockfile(lockfilePaths);
+    const assistants = Array.isArray(lockfile.assistants) ? lockfile.assistants : [];
+    const existingIdx = assistants.findIndex(
+      (a: Record<string, unknown>) => a?.assistantId === assistant.assistantId,
+    );
+    if (existingIdx >= 0) {
+      assistants[existingIdx] = { ...assistants[existingIdx], ...assistant };
+    } else {
+      assistants.push(assistant);
+    }
+    lockfile.assistants = assistants;
+    if (activeAssistant !== undefined) {
+      lockfile.activeAssistant = activeAssistant;
+    }
 
-  return writeRawLockfile(lockfilePaths, lockfile);
+    return writeRawLockfile(lockfilePaths, lockfile);
+  });
+  return locked.ok ? locked.value : lockFailure(locked.error);
 }
 
 const PAIRED_LOCKFILE_WRITE_ERROR =
@@ -154,33 +251,38 @@ export function upsertRendererLockfileAssistant(
     return { ok: false, status: 400, error: "Missing assistant.assistantId" };
   }
 
-  const lockfile = readRawLockfile(lockfilePaths);
-  const assistants = Array.isArray(lockfile.assistants)
-    ? (lockfile.assistants as Array<Record<string, unknown>>)
-    : [];
-  const existing = assistants.find(
-    (entry) => entry?.assistantId === assistant.assistantId,
-  );
-  const merged = { ...existing, ...assistant };
-  const existingIsPaired =
-    existing != null &&
-    (resolveCloud(existing) === "paired" || existing.paired === true);
-  const mergedIsPaired =
-    resolveCloud(merged) === "paired" || merged.paired === true;
-
-  if (!existingIsPaired && mergedIsPaired) {
-    return { ok: false, status: 403, error: PAIRED_LOCKFILE_WRITE_ERROR };
-  }
-  if (
-    existingIsPaired &&
-    (resolveCloud(merged) !== "paired" ||
-      merged.runtimeUrl !== existing.runtimeUrl ||
-      merged.paired !== existing.paired)
-  ) {
-    return { ok: false, status: 403, error: PAIRED_LOCKFILE_WRITE_ERROR };
-  }
+  // Lock spans the paired-guard read and the upsert (which reenters) so the
+  // guard cannot be judged against a snapshot another writer replaces.
+  const locked = withLockfileLock(lockfilePaths, (): WriteResult => {
+    const lockfile = readRawLockfile(lockfilePaths);
+    const assistants = Array.isArray(lockfile.assistants)
+      ? (lockfile.assistants as Array<Record<string, unknown>>)
+      : [];
+    const existing = assistants.find(
+      (entry) => entry?.assistantId === assistant.assistantId,
+    );
+    const merged = { ...existing, ...assistant };
+    const existingIsPaired =
+      existing != null &&
+      (resolveCloud(existing) === "paired" || existing.paired === true);
+    const mergedIsPaired =
+      resolveCloud(merged) === "paired" || merged.paired === true;
 
-  return upsertLockfileAssistant(lockfilePaths, assistant, activeAssistant);
+    if (!existingIsPaired && mergedIsPaired) {
+      return { ok: false, status: 403, error: PAIRED_LOCKFILE_WRITE_ERROR };
+    }
+    if (
+      existingIsPaired &&
+      (resolveCloud(merged) !== "paired" ||
+        merged.runtimeUrl !== existing.runtimeUrl ||
+        merged.paired !== existing.paired)
+    ) {
+      return { ok: false, status: 403, error: PAIRED_LOCKFILE_WRITE_ERROR };
+    }
+
+    return upsertLockfileAssistant(lockfilePaths, assistant, activeAssistant);
+  });
+  return locked.ok ? locked.value : lockFailure(locked.error);
 }
 
 export function isActiveAssistant(
@@ -226,24 +328,27 @@ export function replacePlatformAssistants(
     };
   }
 
-  const lockfile = readRawLockfile(lockfilePaths);
-  const existing = Array.isArray(lockfile.assistants) ? lockfile.assistants : [];
-  const syncedIds = new Set(platformAssistants.map((a) => a.assistantId));
-  // Org-scoped sync preserves other orgs' platform entries; no org full-replaces.
-  const preserved = existing.filter((a: Record<string, unknown>) => {
-    if (a?.cloud !== "vellum") return true;
-    if (syncedIds.has(a.assistantId)) return false;
-    return organizationId != null && a.organizationId !== organizationId;
-  });
-  lockfile.assistants = [...preserved, ...platformAssistants];
+  const locked = withLockfileLock(lockfilePaths, (): WriteResult => {
+    const lockfile = readRawLockfile(lockfilePaths);
+    const existing = Array.isArray(lockfile.assistants) ? lockfile.assistants : [];
+    const syncedIds = new Set(platformAssistants.map((a) => a.assistantId));
+    // Org-scoped sync preserves other orgs' platform entries; no org full-replaces.
+    const preserved = existing.filter((a: Record<string, unknown>) => {
+      if (a?.cloud !== "vellum") return true;
+      if (syncedIds.has(a.assistantId)) return false;
+      return organizationId != null && a.organizationId !== organizationId;
+    });
+    lockfile.assistants = [...preserved, ...platformAssistants];
 
-  const active = lockfile.activeAssistant as string | null;
-  if (active) {
-    const stillExists = (lockfile.assistants as Array<Record<string, unknown>>).some(
-      (a) => a.assistantId === active,
-    );
-    if (!stillExists) lockfile.activeAssistant = null;
-  }
+    const active = lockfile.activeAssistant as string | null;
+    if (active) {
+      const stillExists = (lockfile.assistants as Array<Record<string, unknown>>).some(
+        (a) => a.assistantId === active,
+      );
+      if (!stillExists) lockfile.activeAssistant = null;
+    }
 
-  return writeRawLockfile(lockfilePaths, lockfile);
+    return writeRawLockfile(lockfilePaths, lockfile);
+  });
+  return locked.ok ? locked.value : lockFailure(locked.error);
 }

package/node_modules/@vellumai/local-mode/src/unpair.ts

@@ -8,6 +8,7 @@ import {
   type WriteResult,
 } from "./lockfile";
 import { resolveCloud } from "./lockfile-contract";
+import { withLockfileLock } from "./lockfile-lock";
 
 /**
  * Forget a paired assistant on this machine: remove its lockfile entry and
@@ -21,6 +22,23 @@ export function unpairAssistant(
   lockfilePaths: string[],
   configDir: string,
   assistantId: string,
+): WriteResult {
+  // The whole transaction holds the shared write lock so a concurrent
+  // read-modify-write (e.g. a persona-name rename) cannot restore the entry
+  // after its credential is deleted.
+  const locked = withLockfileLock(lockfilePaths, (): WriteResult =>
+    unpairAssistantLocked(lockfilePaths, configDir, assistantId),
+  );
+  if (!locked.ok) {
+    return { ok: false, status: 423, error: locked.error };
+  }
+  return locked.value;
+}
+
+function unpairAssistantLocked(
+  lockfilePaths: string[],
+  configDir: string,
+  assistantId: string,
 ): WriteResult {
   const lockfile = readRawLockfile(lockfilePaths);
   const assistants = Array.isArray(lockfile.assistants)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.11.3-dev.202608180132.6a0b3da",
+  "version": "0.11.3-dev.202608181511.30d84a2",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/assistant-config.test.ts

@@ -8,10 +8,12 @@ import {
   spyOn,
 } from "bun:test";
 import {
+  existsSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
   rmSync,
+  utimesSync,
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
@@ -97,6 +99,39 @@ describe("assistant-config", () => {
     expect(all[0].assistantId).toBe("test-1");
   });
 
+  test("saveAssistantEntry writes under the advisory lock and cleans it up", () => {
+    saveAssistantEntry(makeEntry("locked-1"));
+    expect(loadAllAssistants()).toHaveLength(1);
+    // The shared `${lockfilePath}.lock` key hosts contend on is released.
+    expect(existsSync(join(testDir, ".vellum.lock.json.lock"))).toBe(false);
+  });
+
+  test("saveAssistantEntry breaks a stale lock and still lands the write", () => {
+    const lockDir = join(testDir, ".vellum.lock.json.lock");
+    mkdirSync(lockDir);
+    const past = new Date(Date.now() - 60_000);
+    utimesSync(lockDir, past, past);
+
+    saveAssistantEntry(makeEntry("stale-lock-1"));
+    expect(loadAllAssistants()).toHaveLength(1);
+    expect(existsSync(lockDir)).toBe(false);
+  });
+
+  test("saveAssistantEntry fails fast without writing when another holder is fresh", () => {
+    const lockDir = join(testDir, ".vellum.lock.json.lock");
+    mkdirSync(lockDir);
+    try {
+      const start = Date.now();
+      expect(() => saveAssistantEntry(makeEntry("contended-1"))).toThrow(
+        /Timed out acquiring lockfile lock/,
+      );
+      expect(Date.now() - start).toBeLessThan(2_000);
+      expect(loadAllAssistants()).toEqual([]);
+    } finally {
+      rmSync(lockDir, { recursive: true, force: true });
+    }
+  });
+
   test("findAssistantByName returns matching entry", () => {
     writeLockfile({
       assistants: [makeEntry("alpha"), makeEntry("beta")],

package/src/commands/client.ts

@@ -29,6 +29,7 @@ import {
 } from "../lib/client-identity";
 import {
   getLockfileData,
+  renameLockfileAssistantIfPresent,
   upsertRendererLockfileAssistant,
   replacePlatformAssistants,
   isActiveAssistant,
@@ -556,6 +557,13 @@ async function handleLocalEndpoints(
           body.platformAssistants as Array<Record<string, unknown>>,
           body.organizationId as string | undefined,
         );
+      } else if (body.rename && typeof body.rename === "object") {
+        const rename = body.rename as Record<string, unknown>;
+        result = renameLockfileAssistantIfPresent(
+          lockfilePaths,
+          rename.assistantId as string,
+          rename.name as string,
+        );
       } else {
         result = upsertRendererLockfileAssistant(
           lockfilePaths,

package/src/lib/assistant-config.ts

@@ -11,6 +11,7 @@ import { homedir } from "os";
 import { dirname, join } from "path";
 
 import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
+import { withLockfileLock } from "@vellumai/local-mode";
 import {
   resolveCloud,
   type LocalAssistantResources,
@@ -186,7 +187,7 @@ function readLockfile(): LockfileData {
   return {};
 }
 
-function writeLockfile(data: LockfileData): void {
+function writeLockfileUnlocked(data: LockfileData): void {
   const lockfilePath = getLockfilePath(getCurrentEnvironment());
   mkdirSync(dirname(lockfilePath), { recursive: true });
   const tmpPath = `${lockfilePath}.${randomBytes(4).toString("hex")}.tmp`;
@@ -201,6 +202,23 @@ function writeLockfile(data: LockfileData): void {
   }
 }
 
+/**
+ * Run `fn` under the same cross-process advisory lock the local-mode hosts
+ * use, keyed to this environment's write-path lockfile, so CLI writers and
+ * package-side writers (Electron main, Vite plugin, `vellum client`) never
+ * interleave read-modify-write cycles. Reentrant, so wrapped units may call
+ * the locked write helpers. Throws on lock timeout, matching the fs-error
+ * contract of the write path.
+ */
+function withCliLockfileLock<T>(fn: () => T): T {
+  const locked = withLockfileLock(
+    [getLockfilePath(getCurrentEnvironment())],
+    fn,
+  );
+  if (!locked.ok) throw new Error(locked.error);
+  return locked.value;
+}
+
 /**
  * Try to extract a port number from a URL string (e.g. `http://localhost:7830`).
  * Returns undefined if the URL is malformed or has no explicit port.
@@ -322,7 +340,18 @@ function readAssistants(): AssistantEntry[] {
   }
 
   if (migrated) {
-    writeLockfile(data);
+    // Persist the backfill against a fresh read under the lock so this
+    // snapshot cannot clobber a concurrent writer; skip on contention (the
+    // in-memory result below is already migrated).
+    withLockfileLock([getLockfilePath(getCurrentEnvironment())], () => {
+      const fresh = readLockfile();
+      if (!Array.isArray(fresh.assistants)) return;
+      let freshMigrated = false;
+      for (const entry of fresh.assistants) {
+        if (migrateLegacyEntry(entry)) freshMigrated = true;
+      }
+      if (freshMigrated) writeLockfileUnlocked(fresh);
+    });
   }
 
   const result: AssistantEntry[] = [];
@@ -342,9 +371,11 @@ function readAssistants(): AssistantEntry[] {
 }
 
 function writeAssistants(entries: AssistantEntry[]): void {
-  const data = readLockfile();
-  data.assistants = entries;
-  writeLockfile(data);
+  withCliLockfileLock(() => {
+    const data = readLockfile();
+    data.assistants = entries;
+    writeLockfileUnlocked(data);
+  });
 }
 
 export function loadLatestAssistant(): AssistantEntry | null {
@@ -428,21 +459,23 @@ export function formatAssistantLookupError(
 }
 
 export function removeAssistantEntry(assistantId: string): void {
-  const data = readLockfile();
-  const entries = (data.assistants ?? []).filter(
-    (e) => e.assistantId !== assistantId,
-  );
-  data.assistants = entries;
-  // Reassign active assistant if it matches the removed entry
-  if (data.activeAssistant === assistantId) {
-    const remaining = entries[0];
-    if (remaining) {
-      data.activeAssistant = String(remaining.assistantId);
-    } else {
-      delete data.activeAssistant;
+  withCliLockfileLock(() => {
+    const data = readLockfile();
+    const entries = (data.assistants ?? []).filter(
+      (e) => e.assistantId !== assistantId,
+    );
+    data.assistants = entries;
+    // Reassign active assistant if it matches the removed entry
+    if (data.activeAssistant === assistantId) {
+      const remaining = entries[0];
+      if (remaining) {
+        data.activeAssistant = String(remaining.assistantId);
+      } else {
+        delete data.activeAssistant;
+      }
     }
-  }
-  writeLockfile(data);
+    writeLockfileUnlocked(data);
+  });
 }
 
 export function loadAllAssistants(): AssistantEntry[] {
@@ -519,9 +552,11 @@ export function getActiveAssistant(): string | null {
 }
 
 export function setActiveAssistant(assistantId: string): void {
-  const data = readLockfile();
-  data.activeAssistant = assistantId;
-  writeLockfile(data);
+  withCliLockfileLock(() => {
+    const data = readLockfile();
+    data.activeAssistant = assistantId;
+    writeLockfileUnlocked(data);
+  });
 }
 
 /**
@@ -607,11 +642,13 @@ export function extractHostFromUrl(url: string): string {
 }
 
 export function saveAssistantEntry(entry: AssistantEntry): void {
-  const entries = readAssistants().filter(
-    (e) => e.assistantId !== entry.assistantId,
-  );
-  entries.unshift(entry);
-  writeAssistants(entries);
+  withCliLockfileLock(() => {
+    const entries = readAssistants().filter(
+      (e) => e.assistantId !== entry.assistantId,
+    );
+    entries.unshift(entry);
+    writeAssistants(entries);
+  });
 }
 
 /**