Building a Single-Process Mutex Command Runner for CLI Apps in Node/Bun

When building autonomous software agencies or multi-agent pipelines (like our own Slack-driven mobile command bot), you quickly run into a fundamental operational hazard: state collision.

If your background agents or cron hooks trigger file mutations, Git operations, or third-party deployments concurrently, they will inevitably clobber each other. A deployment command running while a Git commit is in progress will fail; two agents trying to write to the same configuration file simultaneously will corrupt the state.

To prevent this, we engineered a lightweight, single-process, file-system-backed Mutual Exclusion (Mutex) locker for Node and Bun CLI runtimes. This guarantees that critical operations run sequentially without blocking your primary process thread.

---

The Core Concept: File-System Lock Primitives

In distributed systems, you might reach for Redis Redlock. But for single-machine background CLI tools, Redis introduces unnecessary operational footprint and dependency bloat.

Instead, we can exploit atomic file-system operations. On Unix-like systems, creating a directory (fs.mkdir) or creating a file with exclusive write flags (wx on fs.open) are atomic operations at the OS kernel level. If two processes attempt to create the same lock directory at the exact same microsecond, only one will succeed, while the other receives an EEXIST error.

Here is how to build a robust Mutex class in TypeScript using Bun's fast native file primitives.

---

🛠️ TypeScript Implementation: Atomic Mutex Runner

Below is a self-contained Mutex implementation designed to safely queue tasks or fail gracefully if a lock is held.

import { mkdir, rmdir, stat } from "fs/promises";
import { join } from "path";
export class FileMutex {
  private lockPath: string;
  private maxAgeMs: number;
  constructor(lockName: string, maxAgeMs = 300000) {
    // We use a temporary system path for lock directories
    this.lockPath = join("/tmp", ${lockName}.lock);
    this.maxAgeMs = maxAgeMs; // 5-minute safety threshold
  }
  /
Attempts to acquire the lock. Returns true if successful, false if already locked.
   */
  async acquire(): Promise {
    try {
      await mkdir(this.lockPath);
      // Optional: Write the current process ID (PID) and timestamp for debugging
      await Bun.write(join(this.lockPath, "metadata.json"), JSON.stringify({
        pid: process.pid,
        createdAt: Date.now()
      }));
      return true;
    } catch (err: any) {
      if (err.code === "EEXIST") {
        // Double-check if the lock is stale (safety mechanism against process crashes)
        if (await this.isLockStale()) {
          console.warn("⚠️ Mutex lock is stale. Forcing release...");
          await this.release();
          return this.acquire(); // Try acquiring again
        }
        return false;
      }
      throw err;
    }
  }
  /
Releases the lock by deleting the lock directory.
   */
  async release(): Promise {
    try {
      // Remove metadata first, then the folder
      await Bun.write(join(this.lockPath, "metadata.json"), "");
      await rmdir(this.lockPath, { recursive: true });
    } catch (err) {
      // Ignore if directory already deleted
    }
  }
  private async isLockStale(): Promise {
    try {
      const info = await stat(this.lockPath);
      const age = Date.now() - info.mtimeMs;
      return age > this.maxAgeMs;
    } catch {
      return false;
    }
  }
}

---

🚀 Running Commands Safely with the Mutex Wrapper

We can wrap our shell execution or file operations inside a simple helper function. If the lock is held, the command can either queue itself (using a retry delay) or exit gracefully with a warning to Slack.

async function runWithMutex(lockName: string, task: () => Promise) {
  const mutex = new FileMutex(lockName);
  console.log(🔒 Acquiring mutex lock for [${lockName}]...);
  let retries = 5;
  
  while (retries > 0) {
    if (await mutex.acquire()) {
      console.log(✅ Lock acquired! Executing critical operations...);
      try {
        await task();
      } finally {
        await mutex.release();
        console.log(🔓 Lock released successfully.);
      }
      return;
    } else {
      retries--;
      console.warn(🛑 Lock held by another process. Retrying in 2 seconds... (${retries} retries left));
      await Bun.sleep(2000);
    }
  }
  throw new Error(❌ Mutex Lock Timeout: Could not execute task [${lockName}]. Process blocked.);
}
// EXAMPLE USAGE:
await runWithMutex("vercel-deploy-pipeline", async () => {
  // Safe from race conditions!
  console.log("Staging changes...");
  await Bun.$git add . && git commit -m "chore: automated sync";
  console.log("Pushing and deploying to production...");
  await Bun.$git push && vercel --prod --yes;
});

---

Key Takeaways