@indigoai-us/hq-cloud 6.2.7 → 6.3.0

package/dist/operation-lock.js

@@ -0,0 +1,256 @@
+/**
+ * Per-HQ-root mutual exclusion for the long-running operations
+ * (`sync`, `rescue`, `reindex`).
+ *
+ * Contract:
+ *   - At most ONE of sync / rescue / reindex runs at a time **per HQ root**.
+ *     The lock is shared across all three (keyed only by the root, not the
+ *     command), so e.g. a rescue refuses while a sync holds it. Different HQ
+ *     roots are fully independent — they hash to different lock files.
+ *   - The push watcher / watch+event-push runner is EXEMPT: it never calls in
+ *     here, so it neither takes the lock nor is blocked by it (its targeted
+ *     in-process push passes are likewise lock-free).
+ *
+ * ## Where the lock lives — and why
+ *
+ * `<stateDir>/locks/operation-<hash(canonicalRoot)>.lock`, where
+ * `stateDir = $HQ_STATE_DIR || ~/.hq`. This is deliberately NOT inside the HQ
+ * root:
+ *   - It must never round-trip to the cloud. A lock is machine-local, per-run
+ *     state; syncing it to S3 (and thence to other machines/roots) would be a
+ *     correctness bug. `~/.hq` is the established machine-local state dir
+ *     (journals already live there) and is never synced.
+ *   - `rescue` repairs a possibly-broken HQ root; a lock that depends on the
+ *     root being healthy is exactly backwards. `~/.hq` is independent of the
+ *     root's health.
+ *   - Keying the filename by a hash of the *canonical* root path makes the
+ *     lock per-root and prevents leakage across roots, while keeping the path
+ *     short and filesystem-safe.
+ *
+ * ## Atomicity, liveness, takeover
+ *
+ *   - Acquisition uses `open(…, "wx")` (O_CREAT | O_EXCL) — an atomic
+ *     create-if-absent. Exactly one racer can create the file; the loser sees
+ *     EEXIST and re-evaluates.
+ *   - The lock records the holder's `{ pid, command, startedAt, hqRoot }`. On
+ *     EEXIST we test the recorded PID with `process.kill(pid, 0)`:
+ *       * ESRCH  → the holder is gone (crashed / killed -9 / stale file) →
+ *                  reclaim the lock.
+ *       * EPERM  → the PID exists but is owned by another user → treat as ALIVE
+ *                  (conservative: refuse rather than risk two concurrent ops).
+ *       * success → alive → refuse fast with {@link OperationLockedError}
+ *                  naming the holding command + PID.
+ *   - PID reuse is an inherent, un-eliminable race for any PID-based scheme: if
+ *     the original holder crashed and the OS later handed its PID to an
+ *     unrelated process, we conservatively read that as "still held" and
+ *     refuse. We accept that false-busy over the far worse false-free, and
+ *     record `startedAt`/`command` so an operator can diagnose a wedged lock.
+ *
+ * ## Release
+ *
+ *   - Normal exit: the `with*` wrappers release in a `finally`.
+ *   - Signals (SIGINT/SIGTERM): a one-time handler releases every held lock,
+ *     then re-raises the default disposition so exit status is unchanged.
+ *   - Hard crash (SIGKILL / power loss): nothing runs, but the stale-PID
+ *     takeover above reclaims the lock on the next attempt.
+ *   - `process.on("exit")`: a final best-effort synchronous unlink.
+ *
+ * ## Escape hatch
+ *
+ *   `HQ_DISABLE_OP_LOCK=1` makes acquisition a no-op (returns a handle whose
+ *   release does nothing). For emergencies and for callers that manage
+ *   exclusion themselves; documented, off by default.
+ */
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as os from "os";
+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;
+/** Thrown by `acquireOperationLock` when a LIVE holder owns the lock. */
+export class OperationLockedError extends Error {
+    holder;
+    attempted;
+    constructor(holder, attempted) {
+        super(`Refusing to start "${attempted}": another HQ operation is already ` +
+            `running for this HQ root — "${holder.command}" (pid ${holder.pid}, ` +
+            `started ${holder.startedAt}). Wait for it to finish, or stop that ` +
+            `process, then retry.`);
+        this.holder = holder;
+        this.attempted = attempted;
+        this.name = "OperationLockedError";
+    }
+}
+function stateDir() {
+    return process.env.HQ_STATE_DIR || path.join(os.homedir(), ".hq");
+}
+/** Absolute lock path for a given HQ root. Exported for tests. */
+export function lockPathFor(hqRoot) {
+    const canon = path.resolve(hqRoot);
+    const key = crypto.createHash("sha1").update(canon).digest("hex").slice(0, 16);
+    return path.join(stateDir(), "locks", `operation-${key}.lock`);
+}
+/**
+ * Is `pid` a live process? `kill(pid, 0)` sends no signal; it only probes.
+ * ESRCH → no such process (dead/stale). EPERM → exists but not ours → ALIVE
+ * (conservative). Anything else → assume alive rather than risk a double-run.
+ */
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ESRCH")
+            return false;
+        return true; // EPERM (exists) or unknown → treat as alive
+    }
+}
+function readLockInfo(p) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, "utf8"));
+        if (parsed && typeof parsed.pid === "number" && typeof parsed.command === "string") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Process-wide release plumbing ──────────────────────────────────────────
+// Track every lock this process currently holds so the signal/exit hooks can
+// release all of them. The hooks are installed exactly once.
+const heldLocks = new Set();
+let hooksInstalled = false;
+function unlinkIfOwned(p) {
+    // Only remove a lock whose recorded pid is THIS process — never clobber a
+    // lock another process took over after a (hypothetical) reclaim race.
+    const info = readLockInfo(p);
+    if (info && info.pid === process.pid) {
+        try {
+            fs.unlinkSync(p);
+        }
+        catch {
+            /* already gone — fine */
+        }
+    }
+}
+function installHooksOnce() {
+    if (hooksInstalled)
+        return;
+    hooksInstalled = true;
+    process.on("exit", () => {
+        for (const h of heldLocks)
+            unlinkIfOwned(h.path);
+    });
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.on(sig, () => {
+            for (const h of heldLocks)
+                unlinkIfOwned(h.path);
+            // Re-raise with the default disposition so the exit status is the normal
+            // signal status (and a second Ctrl-C still works). Removing our listener
+            // first avoids recursing back into this handler.
+            process.removeAllListeners(sig);
+            process.kill(process.pid, sig);
+        });
+    }
+}
+function makeHandle(p, info) {
+    const handle = {
+        path: p,
+        info,
+        release() {
+            heldLocks.delete(handle);
+            unlinkIfOwned(p);
+        },
+    };
+    heldLocks.add(handle);
+    installHooksOnce();
+    return handle;
+}
+const NOOP_HANDLE_BASE = { release() { } };
+/**
+ * Acquire the per-root operation lock for `command`. Returns a {@link LockHandle}
+ * on success; throws {@link OperationLockedError} when a live holder owns it.
+ * Reclaims a stale lock (dead holder) transparently.
+ */
+export function acquireOperationLock(hqRoot, command) {
+    if (process.env.HQ_DISABLE_OP_LOCK === "1") {
+        const info = {
+            pid: process.pid,
+            command,
+            startedAt: new Date().toISOString(),
+            hqRoot: path.resolve(hqRoot),
+        };
+        return { ...NOOP_HANDLE_BASE, path: "", info };
+    }
+    const p = lockPathFor(hqRoot);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const info = {
+        pid: process.pid,
+        command,
+        startedAt: new Date().toISOString(),
+        hqRoot: path.resolve(hqRoot),
+    };
+    const payload = JSON.stringify(info, null, 2);
+    // Bounded retry: each iteration is one atomic create attempt. EEXIST against
+    // a stale holder reclaims and retries; EEXIST against a live holder refuses.
+    const MAX_ATTEMPTS = 5;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        let fd;
+        try {
+            fd = fs.openSync(p, "wx"); // O_CREAT | O_EXCL — atomic
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+            const holder = readLockInfo(p);
+            if (holder && holder.pid !== process.pid && pidAlive(holder.pid)) {
+                throw new OperationLockedError(holder, command);
+            }
+            // Stale (dead holder), unreadable/torn, or our own leftover → reclaim.
+            try {
+                fs.unlinkSync(p);
+            }
+            catch {
+                /* someone else reclaimed it first; the next openSync re-evaluates */
+            }
+            continue;
+        }
+        try {
+            fs.writeSync(fd, payload);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        return makeHandle(p, info);
+    }
+    // Pathological churn (another process reclaiming in lockstep). Surface it
+    // rather than spin forever.
+    throw new Error(`Could not acquire HQ operation lock at ${p} after ${MAX_ATTEMPTS} attempts`);
+}
+/** Run `fn` while holding the per-root lock for `command` (async). */
+export async function withOperationLock(hqRoot, command, fn) {
+    const handle = acquireOperationLock(hqRoot, command);
+    try {
+        return await fn();
+    }
+    finally {
+        handle.release();
+    }
+}
+/** Run `fn` while holding the per-root lock for `command` (synchronous). */
+export function withOperationLockSync(hqRoot, command, fn) {
+    const handle = acquireOperationLock(hqRoot, command);
+    try {
+        return fn();
+    }
+    finally {
+        handle.release();
+    }
+}
+//# sourceMappingURL=operation-lock.js.map

package/dist/operation-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-lock.js","sourceRoot":"","sources":["../src/operation-lock.ts"],"names":[],"mappings":"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"}

package/dist/operation-lock.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for the per-HQ-root operation mutex.
+ */
+export {};
+//# sourceMappingURL=operation-lock.test.d.ts.map

package/dist/operation-lock.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-lock.test.d.ts","sourceRoot":"","sources":["../src/operation-lock.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/operation-lock.test.js

@@ -0,0 +1,140 @@
+/**
+ * Unit tests for the per-HQ-root operation mutex.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { acquireOperationLock, withOperationLockSync, lockPathFor, OperationLockedError, OPERATION_LOCKED_EXIT, } from "./operation-lock.js";
+/** A PID that is guaranteed dead: spawn a node that exits immediately, reuse its pid. */
+function deadPid() {
+    const r = spawnSync(process.execPath, ["-e", ""], { stdio: "ignore" });
+    if (!r.pid)
+        throw new Error("could not spawn to obtain a dead pid");
+    return r.pid;
+}
+function writeLock(p, info) {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const full = {
+        pid: 1,
+        command: "sync",
+        startedAt: new Date(0).toISOString(),
+        hqRoot: "/x",
+        ...info,
+    };
+    fs.writeFileSync(p, JSON.stringify(full));
+}
+describe("operation-lock", () => {
+    let stateDir;
+    let rootA;
+    let rootB;
+    beforeEach(() => {
+        stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-oplock-state-"));
+        process.env.HQ_STATE_DIR = stateDir;
+        delete process.env.HQ_DISABLE_OP_LOCK;
+        rootA = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rootA-"));
+        rootB = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rootB-"));
+    });
+    afterEach(() => {
+        fs.rmSync(stateDir, { recursive: true, force: true });
+        fs.rmSync(rootA, { recursive: true, force: true });
+        fs.rmSync(rootB, { recursive: true, force: true });
+        delete process.env.HQ_STATE_DIR;
+        delete process.env.HQ_DISABLE_OP_LOCK;
+    });
+    it("the lock path is under the state dir, keyed per canonical root", () => {
+        const a = lockPathFor(rootA);
+        const b = lockPathFor(rootB);
+        expect(a.startsWith(path.join(stateDir, "locks"))).toBe(true);
+        expect(a).not.toBe(b); // different roots → different lock files
+        // canonical: a trailing-slash variant maps to the same lock
+        expect(lockPathFor(rootA + path.sep)).toBe(a);
+    });
+    it("acquires, writes holder info, and releases (file gone after release)", () => {
+        const h = acquireOperationLock(rootA, "sync");
+        expect(fs.existsSync(h.path)).toBe(true);
+        const info = JSON.parse(fs.readFileSync(h.path, "utf8"));
+        expect(info.pid).toBe(process.pid);
+        expect(info.command).toBe("sync");
+        h.release();
+        expect(fs.existsSync(h.path)).toBe(false);
+    });
+    it("refuses fast with the holder's command + pid when a LIVE process holds it", () => {
+        // Simulate a DIFFERENT live process holding the lock. PID 1 (init/systemd)
+        // is always alive and is never our own pid, so kill(1,0) reports alive and
+        // the same-process reclaim path does not apply.
+        writeLock(lockPathFor(rootA), { pid: 1, command: "rescue" });
+        expect(() => acquireOperationLock(rootA, "sync")).toThrowError(OperationLockedError);
+        try {
+            acquireOperationLock(rootA, "sync");
+        }
+        catch (e) {
+            const err = e;
+            expect(err.holder.command).toBe("rescue");
+            expect(err.holder.pid).toBe(1);
+            expect(err.message).toContain("rescue");
+            expect(err.message).toContain("pid 1");
+        }
+    });
+    it("reclaims a stale lock whose holder PID is dead (takeover)", () => {
+        const stale = deadPid();
+        writeLock(lockPathFor(rootA), { pid: stale, command: "sync" });
+        // The dead holder must not block us.
+        const h = acquireOperationLock(rootA, "rescue");
+        const info = JSON.parse(fs.readFileSync(h.path, "utf8"));
+        expect(info.pid).toBe(process.pid); // we took it over
+        expect(info.command).toBe("rescue");
+        h.release();
+    });
+    it("reclaims a torn/unreadable lock file", () => {
+        const p = lockPathFor(rootA);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, "{ this is not valid json");
+        const h = acquireOperationLock(rootA, "reindex");
+        expect(fs.existsSync(h.path)).toBe(true);
+        h.release();
+    });
+    it("different HQ roots are independent — both may hold concurrently", () => {
+        const a = acquireOperationLock(rootA, "sync");
+        const b = acquireOperationLock(rootB, "rescue"); // must NOT refuse
+        expect(fs.existsSync(a.path)).toBe(true);
+        expect(fs.existsSync(b.path)).toBe(true);
+        expect(a.path).not.toBe(b.path);
+        a.release();
+        b.release();
+    });
+    it("the same root is mutually exclusive across different commands", () => {
+        // A live sync in ANOTHER process holds the root (pid 1 stands in for it).
+        const p = lockPathFor(rootA);
+        writeLock(p, { pid: 1, command: "sync" });
+        // Neither rescue nor reindex may acquire while that sync holds it.
+        expect(() => acquireOperationLock(rootA, "rescue")).toThrowError(OperationLockedError);
+        expect(() => acquireOperationLock(rootA, "reindex")).toThrowError(OperationLockedError);
+        // Once that sync finishes (its lock is gone), the next command acquires.
+        fs.unlinkSync(p);
+        const h2 = acquireOperationLock(rootA, "reindex");
+        expect(fs.existsSync(h2.path)).toBe(true);
+        h2.release();
+    });
+    it("withOperationLockSync releases even when the body throws", () => {
+        const p = lockPathFor(rootA);
+        expect(() => withOperationLockSync(rootA, "reindex", () => {
+            expect(fs.existsSync(p)).toBe(true); // held during the body
+            throw new Error("boom");
+        })).toThrow("boom");
+        expect(fs.existsSync(p)).toBe(false); // released on the way out
+    });
+    it("HQ_DISABLE_OP_LOCK=1 makes acquisition a no-op", () => {
+        process.env.HQ_DISABLE_OP_LOCK = "1";
+        // Even with a live holder on record, the escape hatch acquires without error.
+        writeLock(lockPathFor(rootA), { pid: process.pid, command: "sync" });
+        const h = acquireOperationLock(rootA, "rescue");
+        expect(h.path).toBe(""); // no real lock file written
+        h.release(); // no-op, no throw
+    });
+    it("OPERATION_LOCKED_EXIT is a stable non-zero code", () => {
+        expect(OPERATION_LOCKED_EXIT).toBe(17);
+    });
+});
+//# sourceMappingURL=operation-lock.test.js.map

package/dist/operation-lock.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-lock.test.js","sourceRoot":"","sources":["../src/operation-lock.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "6.2.7",
+  "version": "6.3.0",
   "description": "HQ by Indigo cloud sync engine \u2014 bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/bin/sync-runner.test.ts

@@ -30,6 +30,7 @@ import type {
 } from "./sync-runner.js";
 import { FakeClock } from "../watcher.js";
 import { PERSONAL_VAULT_JOURNAL_SLUG } from "../journal.js";
+import { lockPathFor, OPERATION_LOCKED_EXIT } from "../operation-lock.js";
 import type { SyncResult, SyncOptions } from "../cli/sync.js";
 import type { ShareResult, ShareOptions } from "../cli/share.js";
 import type {
@@ -3566,3 +3567,79 @@ describe("readPinnedPrefixes", () => {
     expect(readPinnedPrefixes(root, "acme")).toEqual([]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Operation lock — one-shot sync takes it; the watch runner is exempt.
+// ---------------------------------------------------------------------------
+describe("runRunnerWithLoop — operation lock", () => {
+  const HQ = "/tmp/hq-oplock";
+
+  /** Write a live-holder lock (pid 1) for the HQ root into the test state dir. */
+  function writeLiveHolder(command: string): string {
+    const p = lockPathFor(HQ);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(
+      p,
+      JSON.stringify({ pid: 1, command, startedAt: new Date(0).toISOString(), hqRoot: HQ }),
+    );
+    return p;
+  }
+
+  it("one-shot sync refuses fast (exit 17) when another op holds the root", async () => {
+    const lp = writeLiveHolder("rescue");
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+
+    // No --watch → one-shot. Refusal short-circuits BEFORE runRunner (so no
+    // network / auth is touched).
+    const code = await runRunnerWithLoop(["--companies", "--hq-root", HQ]);
+
+    spy.mockRestore();
+    expect(code).toBe(OPERATION_LOCKED_EXIT);
+    expect(errs.join("")).toContain("rescue"); // names the holder
+    // The holder's lock is left intact — we refused, we didn't take it over.
+    const held = JSON.parse(fs.readFileSync(lp, "utf8"));
+    expect(held.pid).toBe(1);
+    expect(held.command).toBe("rescue");
+  });
+
+  it("the watch runner is EXEMPT — runs despite a held lock and never takes it", async () => {
+    const lp = writeLiveHolder("sync");
+    const watcher = makeWatcherStub();
+    let triggerShutdown = () => {};
+    const runPass = vi.fn().mockResolvedValue(0);
+
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", HQ],
+      {
+        runPass,
+        clock: new FakeClock(),
+        createWatcher: () => watcher,
+        sleep: () => new Promise<void>(() => {}),
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+      },
+    );
+
+    await Promise.resolve();
+    await Promise.resolve();
+    // It started and ran a pass even though the lock is held → not blocked.
+    expect(watcher.started).toBe(true);
+    expect(runPass).toHaveBeenCalled();
+
+    triggerShutdown();
+    await loop;
+
+    // The pre-existing holder lock is untouched → the watcher never took it.
+    const held = JSON.parse(fs.readFileSync(lp, "utf8"));
+    expect(held.pid).toBe(1);
+    expect(held.command).toBe("sync");
+  });
+});

package/src/bin/sync-runner.ts

@@ -100,6 +100,11 @@ import { collectAndSendTelemetry } from "../telemetry.js";
 import { collectAndSendSkillTelemetry } from "../skill-telemetry.js";
 import { reindexAfterSync } from "../qmd-reindex.js";
 import { pruneConflictIndex } from "../lib/conflict-index.js";
+import {
+  withOperationLock,
+  OperationLockedError,
+  OPERATION_LOCKED_EXIT,
+} from "../operation-lock.js";
 import { describeError } from "../lib/describe-error.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
 import {
@@ -1920,7 +1925,23 @@ export async function runRunnerWithLoop(
   deps: RunnerLoopDeps = {},
 ): Promise<number> {
   if (!argv.includes("--watch")) {
-    return runRunner(argv);
+    // One-shot cloud sync — take the per-root operation lock so it is mutually
+    // exclusive with rescue/reindex. The `--watch` path below is the push
+    // watcher and is intentionally EXEMPT (it neither takes nor is blocked by
+    // the lock; its in-process targeted passes call `runRunner` directly, not
+    // through here). If args don't parse, fall through to `runRunner` so it
+    // surfaces the parse error rather than us masking it with a lock failure.
+    const parsed = parseArgs(argv);
+    if ("error" in parsed) return runRunner(argv);
+    try {
+      return await withOperationLock(parsed.hqRoot, "sync", () => runRunner(argv));
+    } catch (err) {
+      if (err instanceof OperationLockedError) {
+        process.stderr.write(err.message + "\n");
+        return OPERATION_LOCKED_EXIT;
+      }
+      throw err;
+    }
   }
   const sleep =
     deps.sleep ??

package/src/cli/reindex.test.ts

@@ -13,16 +13,24 @@ import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 import { reindex } from "./reindex.js";
+import { lockPathFor, OPERATION_LOCKED_EXIT } from "../operation-lock.js";
 
 describe("reindex", () => {
   let root: string;
+  let stateDir: string;
 
   beforeEach(() => {
     root = fs.mkdtempSync(path.join(os.tmpdir(), "ms-test-"));
+    // Redirect the operation lock into a throwaway dir so reindex's default
+    // locking never touches the real ~/.hq during tests.
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "ms-state-"));
+    process.env.HQ_STATE_DIR = stateDir;
   });
 
   afterEach(() => {
     fs.rmSync(root, { recursive: true, force: true });
+    fs.rmSync(stateDir, { recursive: true, force: true });
+    delete process.env.HQ_STATE_DIR;
   });
 
   function writeSkill(rel: string): void {
@@ -124,4 +132,41 @@ describe("reindex", () => {
     expect(fs.existsSync(wrapper)).toBe(true);
     expect(fs.lstatSync(path.join(wrapper, "SKILL.md")).isSymbolicLink()).toBe(true);
   });
+
+  // ── operation lock (mutual exclusion with sync/rescue) ──────────────────
+
+  it("refuses (OPERATION_LOCKED_EXIT) when another op holds this root's lock", () => {
+    // A live holder in another process (pid 1) → reindex must refuse fast and
+    // do no work.
+    const lp = lockPathFor(root);
+    fs.mkdirSync(path.dirname(lp), { recursive: true });
+    fs.writeFileSync(
+      lp,
+      JSON.stringify({ pid: 1, command: "sync", startedAt: new Date(0).toISOString(), hqRoot: root }),
+    );
+    const before = fs.existsSync(path.join(root, ".claude/skills"));
+    const { status } = reindex({ repoRoot: root });
+    expect(status).toBe(OPERATION_LOCKED_EXIT);
+    // It refused before doing any work (didn't create .claude/skills).
+    expect(fs.existsSync(path.join(root, ".claude/skills"))).toBe(before);
+  });
+
+  it("skipLock bypasses the lock (internal sync/rescue caller path)", () => {
+    const lp = lockPathFor(root);
+    fs.mkdirSync(path.dirname(lp), { recursive: true });
+    fs.writeFileSync(
+      lp,
+      JSON.stringify({ pid: 1, command: "sync", startedAt: new Date(0).toISOString(), hqRoot: root }),
+    );
+    // Even with a live holder on record, the internal caller (which already
+    // holds the lock) runs to completion.
+    const { status } = reindex({ repoRoot: root, skipLock: true });
+    expect(status).toBe(0);
+    expect(fs.existsSync(path.join(root, ".claude/skills"))).toBe(true);
+  });
+
+  it("releases the lock after a normal run (no leftover lock file)", () => {
+    reindex({ repoRoot: root });
+    expect(fs.existsSync(lockPathFor(root))).toBe(false);
+  });
 });