@indigoai-us/hq-cloud 6.13.1 → 6.13.3

package/src/operation-lock.ts

@@ -103,6 +103,12 @@ import * as path from "path";
 /** Process exit code used when an operation is refused because the lock is held. */
 export const OPERATION_LOCKED_EXIT = 17;
 
+/**
+ * Process exit code used when an operation is refused because the lock's state
+ * directory is not writable (a permission-class fs error, not a live holder).
+ */
+export const OPERATION_LOCK_UNWRITABLE_EXIT = 18;
+
 export interface LockInfo {
   pid: number;
   command: string;
@@ -128,6 +134,36 @@ export class OperationLockedError extends Error {
   }
 }
 
+/**
+ * Thrown by `acquireOperationLock*` when the per-root lock CANNOT BE CREATED
+ * because its state directory is not writable — a permission-class fs error
+ * (`EPERM` / `EACCES` / `EROFS`) on the lock dir or its temp file, NOT a live
+ * holder. Distinct from {@link OperationLockedError}: nothing is holding the
+ * lock; this process simply cannot write there — e.g. `~/.hq` owned by another
+ * user (created by a past `sudo` run), a macOS privacy/security restriction
+ * (which surfaces as `EPERM: operation not permitted`), or a read-only volume.
+ * Callers turn this into a clear, actionable message + clean exit rather than a
+ * raw uncaught `fs` crash (HQ-CLI-2).
+ */
+export class OperationLockUnwritableError extends Error {
+  constructor(
+    public readonly lockDir: string,
+    public readonly cause: NodeJS.ErrnoException,
+  ) {
+    super(
+      `Cannot create the HQ operation lock in "${lockDir}" ` +
+        `(${cause.code}: ${cause.message}). That directory is not writable, so ` +
+        `HQ can't guard this operation against a concurrent run. Likely causes: ` +
+        `it is owned by another user (e.g. created by a past "sudo" command), a ` +
+        `macOS privacy/security restriction, or a read-only volume. To fix: make ` +
+        `it writable (e.g. "sudo chown -R $(whoami) ~/.hq"), or point HQ at a ` +
+        `writable state directory with HQ_STATE_DIR=<dir>. To bypass the lock for ` +
+        `a single run (drops concurrency protection), set HQ_DISABLE_OP_LOCK=1.`,
+    );
+    this.name = "OperationLockUnwritableError";
+  }
+}
+
 export interface LockHandle {
   /** Absolute path of the lock file. */
   readonly path: string;
@@ -363,10 +399,42 @@ function disabledHandle(hqRoot: string, command: string): LockHandle {
   return { ...NOOP_HANDLE_BASE, path: "", info };
 }
 
+/**
+ * Permission-class fs error codes that mean the lock's state directory itself is
+ * unusable for THIS process (not a transient/EEXIST race). macOS surfaces the
+ * restricted-location case as `EPERM`; Linux as `EACCES`; a read-only mount as
+ * `EROFS`.
+ */
+const UNWRITABLE_LOCK_CODES = new Set(["EPERM", "EACCES", "EROFS"]);
+
+/**
+ * If `err` is a permission-class fs error against the lock dir, rethrow it as an
+ * actionable {@link OperationLockUnwritableError}; otherwise rethrow it
+ * unchanged. Always throws (return type `never`).
+ *
+ * Exported for unit testing: ESM module namespaces can't be spied, so the
+ * classification decision is verified directly here rather than by mocking
+ * `fs.openSync` (see operation-lock.test.ts, HQ-CLI-2).
+ */
+export function rethrowLockCreateError(err: unknown, lockDir: string): never {
+  const e = err as NodeJS.ErrnoException | null;
+  if (e && typeof e.code === "string" && UNWRITABLE_LOCK_CODES.has(e.code)) {
+    throw new OperationLockUnwritableError(lockDir, e);
+  }
+  throw err;
+}
+
 /** Build the lock payload + ensure the locks dir exists. */
 function prepareLock(hqRoot: string, command: string): { p: string; info: LockInfo; payload: string } {
   const p = lockPathFor(hqRoot);
-  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const dir = path.dirname(p);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    // The state dir (e.g. ~/.hq) can't be created — surface it as an actionable
+    // unwritable-lock error rather than a raw mkdir crash.
+    rethrowLockCreateError(err, dir);
+  }
   const info: LockInfo = {
     pid: process.pid,
     command,
@@ -381,7 +449,15 @@ function writeLockTemp(dir: string, payload: string): string {
     dir,
     `.operation-lock.${process.pid}.${Date.now()}.${crypto.randomBytes(6).toString("hex")}.tmp`,
   );
-  const fd = fs.openSync(tmp, "wx", 0o600);
+  let fd: number;
+  try {
+    fd = fs.openSync(tmp, "wx", 0o600);
+  } catch (err) {
+    // The locks dir isn't writable (e.g. macOS EPERM / Linux EACCES on a
+    // root-owned or restricted ~/.hq) — surface an actionable error, not a raw
+    // `EPERM: operation not permitted, open` crash (HQ-CLI-2).
+    rethrowLockCreateError(err, dir);
+  }
   let closed = false;
   try {
     fs.writeSync(fd, payload);