@vellumai/cli 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

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,165 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+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("breaks a stale lock whose recorded owner process is dead", () => {
+    // A synchronously-spawned child has exited by the time spawnSync returns.
+    const deadPid = spawnSync(process.execPath, ["--version"]).pid;
+    fs.mkdirSync(lockDir);
+    fs.writeFileSync(path.join(lockDir, "owner"), String(deadPid));
+    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("never steals a stale-aged lock whose owner is still alive", () => {
+    fs.mkdirSync(lockDir);
+    fs.writeFileSync(path.join(lockDir, "owner"), String(process.pid));
+    const past = new Date(Date.now() - 60_000);
+    fs.utimesSync(lockDir, past, past);
+
+    let ran = false;
+    const result = withLockfileLock([lockfilePath], () => {
+      ran = true;
+    });
+    expect(ran).toBe(false);
+    expect(result.ok).toBe(false);
+    expect(fs.existsSync(lockDir)).toBe(true);
+    expect(fs.readFileSync(path.join(lockDir, "owner"), "utf-8")).toBe(
+      String(process.pid),
+    );
+  });
+
+  test("breaks a hard-stale lock even when the recorded owner pid is alive", () => {
+    // Models a crashed holder whose pid was recycled to a live process: past
+    // the hard ceiling the pid check no longer keeps the lock alive.
+    fs.mkdirSync(lockDir);
+    fs.writeFileSync(path.join(lockDir, "owner"), String(process.pid));
+    const past = new Date(Date.now() - 11 * 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("records this process as the owner while the lock is held", () => {
+    withLockfileLock([lockfilePath], () => {
+      expect(fs.readFileSync(path.join(lockDir, "owner"), "utf-8")).toBe(
+        String(process.pid),
+      );
+    });
+  });
+
+  test("release leaves a lock re-acquired by another owner untouched", () => {
+    const result = withLockfileLock([lockfilePath], () => {
+      // Simulate a break-and-reacquire while suspended: another process now
+      // records itself as the owner of the lock path.
+      fs.writeFileSync(path.join(lockDir, "owner"), String(process.pid + 1));
+      return "ran";
+    });
+    expect(result).toEqual({ ok: true, value: "ran" });
+    expect(fs.existsSync(lockDir)).toBe(true);
+    expect(fs.readFileSync(path.join(lockDir, "owner"), "utf-8")).toBe(
+      String(process.pid + 1),
+    );
+  });
+
+  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,156 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export type LockfileLockResult<T> =
+  { ok: true; value: T } | { ok: false; error: string };
+
+/** Minimum age before a lock is even considered for breaking; the owner pid
+ *  check is what decides, so a live-but-slow holder is never stolen from. */
+const STALE_LOCK_MS = 5_000;
+/** A pid is not stable identity: a crashed holder's pid can be recycled to an
+ *  unrelated long-lived process, which would wedge writers forever. Real holds
+ *  last microseconds, so past this ceiling the pid check is ignored. */
+const HARD_STALE_LOCK_MS = 10 * 60_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>();
+
+/** Disambiguates concurrent break attempts within one process. */
+let breakCounter = 0;
+
+/** 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 ownerFilePath(lockDir: string): string {
+  return path.join(lockDir, "owner");
+}
+
+function readOwnerPid(lockDir: string): number | null {
+  try {
+    const pid = Number(fs.readFileSync(ownerFilePath(lockDir), "utf-8"));
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the pid exists but belongs to another user.
+    return (err as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+function tryBreakStaleLock(lockDir: string): void {
+  try {
+    const age = Date.now() - fs.statSync(lockDir).mtimeMs;
+    if (age <= STALE_LOCK_MS) return;
+    if (age <= HARD_STALE_LOCK_MS) {
+      const ownerPid = readOwnerPid(lockDir);
+      if (ownerPid !== null && isProcessAlive(ownerPid)) return;
+    }
+    // Rename before removing so exactly one contender wins the break.
+    const tombstone = `${lockDir}.stale-${process.pid}-${breakCounter++}`;
+    fs.renameSync(lockDir, tombstone);
+    fs.rmSync(tombstone, { recursive: true, force: true });
+  } catch {
+    // Holder released or another contender broke it; next mkdir attempt decides.
+  }
+}
+
+/** Remove the lock only if this process still owns it: a lock broken as stale
+ *  and re-acquired while `fn` ran records the replacement holder's pid. */
+function releaseLock(lockDir: string): void {
+  try {
+    if (readOwnerPid(lockDir) !== process.pid) return;
+    fs.rmSync(lockDir, { recursive: true, force: true });
+  } catch {
+    // Best effort; a leftover dir is broken once its owner process dies.
+  }
+}
+
+/**
+ * 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.
+ * The winner records its pid in an `owner` file; a contender breaks the lock
+ * only when the recorded owner process is gone (or never recorded ownership),
+ * except past a hard age ceiling that bounds recovery from pid reuse.
+ * 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);
+    } 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}` };
+    }
+    try {
+      fs.writeFileSync(ownerFilePath(lockDir), String(process.pid));
+    } catch (err) {
+      try {
+        fs.rmSync(lockDir, { recursive: true, force: true });
+      } catch {
+        // An ownerless dir is broken as stale once it ages out.
+      }
+      return {
+        ok: false,
+        error: `Failed to record lockfile lock ownership: ${err}`,
+      };
+    }
+    acquired = true;
+    break;
+  }
+  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);
+    releaseLock(lockDir);
+  }
+}

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,216 @@ 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("refuses non-object JSON on disk without clobbering it", () => {
+    for (const raw of ["null", "[]", '"text"', "7"]) {
+      fs.writeFileSync(lockfilePath, raw);
+
+      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(raw);
+    }
+  });
+
+  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",
@@ -337,14 +575,17 @@ describe("replacePlatformAssistants", () => {
     });
 
     expect(
-      replacePlatformAssistants([lockfilePath], [
-        {
-          assistantId: "asst_local",
-          cloud: "paired",
-          paired: true,
-          runtimeUrl: "https://attacker.example.com",
-        },
-      ]),
+      replacePlatformAssistants(
+        [lockfilePath],
+        [
+          {
+            assistantId: "asst_local",
+            cloud: "paired",
+            paired: true,
+            runtimeUrl: "https://attacker.example.com",
+          },
+        ],
+      ),
     ).toMatchObject({ ok: false, status: 403 });
     expect(readOnDisk()).toEqual({
       activeAssistant: "asst_local",