@indigoai-us/hq-cloud 6.7.1 → 6.8.0

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

@@ -3604,7 +3604,7 @@ describe("runRunnerWithLoop — operation lock", () => {
     return p;
   }
 
-  it("one-shot sync refuses fast (exit 17) when another op holds the root", async () => {
+  it("one-shot sync refuses immediately (exit 17) with --lock-timeout 0 when another op holds the root", async () => {
     const lp = writeLiveHolder("rescue");
     const errs: string[] = [];
     const spy = vi
@@ -3614,12 +3614,21 @@ describe("runRunnerWithLoop — operation lock", () => {
         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]);
+    // No --watch → one-shot. `--lock-timeout 0` keeps the pre-wait
+    // refuse-immediately behavior (the default is now to WAIT for the holder).
+    // Refusal short-circuits BEFORE runRunner (so no network / auth is touched).
+    const start = Date.now();
+    const code = await runRunnerWithLoop([
+      "--companies",
+      "--hq-root",
+      HQ,
+      "--lock-timeout",
+      "0",
+    ]);
 
     spy.mockRestore();
     expect(code).toBe(OPERATION_LOCKED_EXIT);
+    expect(Date.now() - start).toBeLessThan(1500); // did not wait
     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"));
@@ -3627,6 +3636,76 @@ describe("runRunnerWithLoop — operation lock", () => {
     expect(held.command).toBe("rescue");
   });
 
+  it("one-shot sync WAITS for a live holder (default), bounded by --lock-timeout, then refuses with exit 17", 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;
+      });
+
+    // The holder never releases here; --lock-timeout 1 bounds the wait so the
+    // runner waits ~1s, emits a single "Waiting for …" status line, then
+    // refuses (exit 17) — proving the runner threads the flag through and
+    // takes the wait path (rather than refusing instantly). It still never
+    // enters runRunner, so no network/auth is touched.
+    const start = Date.now();
+    const code = await runRunnerWithLoop([
+      "--companies",
+      "--hq-root",
+      HQ,
+      "--lock-timeout",
+      "1",
+    ]);
+    const elapsed = Date.now() - start;
+
+    spy.mockRestore();
+    expect(code).toBe(OPERATION_LOCKED_EXIT);
+    expect(elapsed).toBeGreaterThanOrEqual(800); // actually waited ~1s
+    expect(errs.join("")).toContain("Waiting for"); // status line emitted once
+    expect(errs.join("")).toContain("rescue"); // names the holder
+    const held = JSON.parse(fs.readFileSync(lp, "utf8"));
+    expect(held.pid).toBe(1); // holder untouched
+  }, 20_000);
+
+  it("DEV-1772: one-shot waits out a SHORT-LIVED holder (reindex) then PROCEEDS to sync", async () => {
+    // The exact reported scenario (feedback_28a1833f / DEV-1772): a frequent
+    // ~1-min `reindex` briefly holds the lock; the instant-sync one-shot used
+    // to exit 17 and silently die. Now it WAITS (default) and proceeds the
+    // moment the short holder releases. We model the short holder with a
+    // foreign live pid (1) whose lock file is removed shortly after, and inject
+    // runPass so "proceeds → syncs" is observable without the network.
+    writeLiveHolder("reindex");
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+
+    const runPass = vi.fn().mockResolvedValue(0);
+    // The short-lived holder releases ~150ms in.
+    setTimeout(() => fs.rmSync(lockPathFor(HQ), { force: true }), 150);
+
+    const code = await runRunnerWithLoop(
+      ["--companies", "--hq-root", HQ],
+      { runPass },
+    );
+
+    spy.mockRestore();
+    // It did NOT refuse/die — it waited then ran the sync pass exactly once.
+    expect(code).toBe(0);
+    expect(code).not.toBe(OPERATION_LOCKED_EXIT);
+    expect(runPass).toHaveBeenCalledTimes(1);
+    // A single "Waiting for …" status line named the short holder.
+    const out = errs.join("");
+    expect(out).toContain("Waiting for");
+    expect(out).toContain("reindex");
+  }, 20_000);
+
   it("the watch runner is EXEMPT — runs despite a held lock and never takes it", async () => {
     const lp = writeLiveHolder("sync");
     const watcher = makeWatcherStub();

package/src/bin/sync-runner.ts

@@ -607,6 +607,13 @@ interface ParsedArgs {
    * mode (single-company runs never visit the personal target).
    */
   skipPersonal: boolean;
+  /**
+   * Bounded wait (seconds) for the per-root operation lock when another op is
+   * already running. `0` → refuse immediately (pre-wait behavior); omitted →
+   * inherit `HQ_OP_LOCK_TIMEOUT` / infinite wait. Only meaningful on the
+   * one-shot path (the `--watch` runner is lock-exempt).
+   */
+  lockTimeoutSec?: number;
 }
 
 function parseArgs(argv: string[]): ParsedArgs | { error: string } {
@@ -620,6 +627,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let pollRemoteMs: number | undefined;
   let skipPersonal = false;
   let eventPush = false;
+  let lockTimeoutSec: number | undefined;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -693,6 +701,18 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
         // @getindigo.ai identities for the first release.
         eventPush = true;
         break;
+      case "--lock-timeout": {
+        const val = argv[++i];
+        if (!val) return { error: "--lock-timeout requires a value (seconds)" };
+        const n = Number(val);
+        if (!Number.isInteger(n) || n < 0) {
+          return {
+            error: `--lock-timeout must be a non-negative integer (seconds), got: ${val}`,
+          };
+        }
+        lockTimeoutSec = n;
+        break;
+      }
       default:
         return { error: `Unknown argument: ${arg}` };
     }
@@ -732,6 +752,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
     pollRemoteMs,
     skipPersonal,
     eventPush,
+    lockTimeoutSec,
   };
 }
 
@@ -1855,10 +1876,27 @@ export async function runRunnerWithLoop(
     // surfaces the parse error rather than us masking it with a lock failure.
     const parsed = parseArgs(argv);
     if ("error" in parsed) return runRunner(argv);
+    // The actual sync pass — same seam the watch loop uses (deps.runPass),
+    // so a test can assert "waits for a short-lived holder, THEN proceeds to
+    // sync" without touching the network. Production passes `argv` to
+    // runRunner exactly as before. Regression guard for DEV-1772
+    // (feedback_28a1833f): instant-sync one-shots used to exit 17 and die on
+    // a lock conflict with the ~1-min reindex hook; they now WAIT (default)
+    // and proceed once the short holder releases.
+    const runOnce = deps.runPass ?? ((passArgv: string[]) => runRunner(passArgv));
     try {
-      return await withOperationLock(parsed.hqRoot, "sync", () => runRunner(argv));
+      return await withOperationLock(parsed.hqRoot, "sync", () => runOnce(argv), {
+        timeoutSec: parsed.lockTimeoutSec,
+      });
     } catch (err) {
       if (err instanceof OperationLockedError) {
+        // The lock wait was BOUNDED and tripped (a holder never released
+        // within --lock-timeout / HQ_OP_LOCK_TIMEOUT). Surface it loudly on
+        // stderr and exit with the stable OPERATION_LOCKED_EXIT (17) so the
+        // spawner (menubar) can recognize a lock conflict and SCHEDULE A
+        // RETRY rather than treating it as a hard failure and silently giving
+        // up (DEV-1772). With the default (no bound) we never reach here — the
+        // one-shot waits indefinitely and proceeds.
         process.stderr.write(err.message + "\n");
         return OPERATION_LOCKED_EXIT;
       }

package/src/cli/reindex.test.ts

@@ -135,9 +135,10 @@ describe("reindex", () => {
 
   // ── 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.
+  it("refuses (OPERATION_LOCKED_EXIT) when another op holds this root's lock (lockTimeoutSec:0)", () => {
+    // A live holder in another process (pid 1) → with lockTimeoutSec:0 reindex
+    // refuses immediately and does no work. (The new default is to WAIT; the
+    // wait-then-acquire path is covered in operation-lock.test.ts.)
     const lp = lockPathFor(root);
     fs.mkdirSync(path.dirname(lp), { recursive: true });
     fs.writeFileSync(
@@ -145,7 +146,7 @@ describe("reindex", () => {
       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 });
+    const { status } = reindex({ repoRoot: root, lockTimeoutSec: 0 });
     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);

package/src/cli/reindex.ts

@@ -35,6 +35,17 @@ export interface ReindexOptions {
    * exclusive with a running sync/rescue.
    */
   skipLock?: boolean;
+  /**
+   * Bounded wait (seconds) for the per-root operation lock when a sync/rescue
+   * is already running. `0` → refuse immediately; omitted → inherit
+   * `HQ_OP_LOCK_TIMEOUT` / infinite wait. Ignored when `skipLock` is set.
+   *
+   * NB: standalone `hq reindex` waits by default, which is what a human running
+   * it wants. The hq-core reindex HOOK (Stop / PostToolUse) should set a small
+   * `HQ_OP_LOCK_TIMEOUT` (or `0`) so a hook fired mid-sync never blocks the
+   * interactive agent indefinitely.
+   */
+  lockTimeoutSec?: number;
 }
 
 export interface ReindexResult {
@@ -151,7 +162,7 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
   let opLock: LockHandle | null = null;
   if (!opts.skipLock) {
     try {
-      opLock = acquireOperationLock(root, "reindex");
+      opLock = acquireOperationLock(root, "reindex", { timeoutSec: opts.lockTimeoutSec });
     } catch (err) {
       if (err instanceof OperationLockedError) {
         warn(err.message);

package/src/cli/rescue.test.ts

@@ -1,5 +1,47 @@
 import { describe, it, expect } from "vitest";
-import { buildRescueArgs } from "./rescue.js";
+import { buildRescueArgs, extractLockTimeout } from "./rescue.js";
+
+describe("extractLockTimeout", () => {
+  it("returns the explicit option untouched when extraArgs is empty/absent", () => {
+    expect(extractLockTimeout({ lockTimeoutSec: 5 })).toEqual({
+      lockTimeoutSec: 5,
+      cleanedExtraArgs: undefined,
+    });
+    expect(extractLockTimeout({ lockTimeoutSec: 5, extraArgs: [] })).toEqual({
+      lockTimeoutSec: 5,
+      cleanedExtraArgs: [],
+    });
+  });
+
+  it("pulls --lock-timeout <secs> out of extraArgs and strips it from the forwarded args", () => {
+    const r = extractLockTimeout({
+      extraArgs: ["--lock-timeout", "30", "--dry-run", "--yes"],
+    });
+    expect(r.lockTimeoutSec).toBe(30);
+    // The flag + its value never reach the rescue script.
+    expect(r.cleanedExtraArgs).toEqual(["--dry-run", "--yes"]);
+  });
+
+  it("honors --lock-timeout 0 (refuse immediately)", () => {
+    const r = extractLockTimeout({ extraArgs: ["--lock-timeout", "0"] });
+    expect(r.lockTimeoutSec).toBe(0);
+    expect(r.cleanedExtraArgs).toEqual([]);
+  });
+
+  it("explicit option wins over a flag in extraArgs", () => {
+    const r = extractLockTimeout({
+      lockTimeoutSec: 0,
+      extraArgs: ["--lock-timeout", "60"],
+    });
+    expect(r.lockTimeoutSec).toBe(0);
+    expect(r.cleanedExtraArgs).toEqual([]);
+  });
+
+  it("ignores a non-numeric / negative --lock-timeout value (treated as unset)", () => {
+    expect(extractLockTimeout({ extraArgs: ["--lock-timeout", "abc"] }).lockTimeoutSec).toBeUndefined();
+    expect(extractLockTimeout({ extraArgs: ["--lock-timeout", "-3"] }).lockTimeoutSec).toBeUndefined();
+  });
+});
 
 describe("buildRescueArgs", () => {
   it("emits no args for an empty option set (script defaults apply)", () => {

package/src/cli/rescue.ts

@@ -57,10 +57,52 @@ export interface RescueOptions {
   /** GitHub token forwarded to the script as `GH_TOKEN` (avoids the
    *  anonymous-clone rate limit; required for private sources). */
   ghToken?: string;
+  /**
+   * Bounded wait (seconds) for the per-root operation lock when a sync/reindex
+   * is already running. `0` → refuse immediately; omitted → inherit
+   * `HQ_OP_LOCK_TIMEOUT` / infinite wait. Also accepted as `--lock-timeout
+   * <secs>` inside {@link extraArgs} (the machine `hq-rescue` entrypoint
+   * forwards raw argv) — it is consumed here and never passed to the rescue
+   * script, which doesn't understand it.
+   */
+  lockTimeoutSec?: number;
   /** Escape hatch — additional raw args appended verbatim. */
   extraArgs?: string[];
 }
 
+/**
+ * Pull `--lock-timeout <secs>` out of `extraArgs` (the raw argv the machine
+ * `hq-rescue` entrypoint forwards) so it controls the operation-lock wait
+ * instead of leaking to the rescue script. Returns the resolved timeout
+ * (explicit `opts.lockTimeoutSec` wins) and a copy of extraArgs with the flag
+ * removed.
+ */
+export function extractLockTimeout(opts: RescueOptions): {
+  lockTimeoutSec: number | undefined;
+  cleanedExtraArgs: string[] | undefined;
+} {
+  const raw = opts.extraArgs;
+  if (!raw || raw.length === 0) {
+    return { lockTimeoutSec: opts.lockTimeoutSec, cleanedExtraArgs: raw };
+  }
+  const cleaned: string[] = [];
+  let fromArgs: number | undefined;
+  for (let i = 0; i < raw.length; i++) {
+    if (raw[i] === "--lock-timeout") {
+      const val = Number(raw[i + 1]);
+      if (Number.isInteger(val) && val >= 0) fromArgs = val;
+      i++; // skip the value too
+      continue;
+    }
+    cleaned.push(raw[i]);
+  }
+  // Explicit option beats the parsed flag.
+  return {
+    lockTimeoutSec: opts.lockTimeoutSec ?? fromArgs,
+    cleanedExtraArgs: cleaned,
+  };
+}
+
 export interface RescueResult {
   /** Exit status of the underlying script (0 = success). */
   status: number;
@@ -100,9 +142,13 @@ export function rescue(opts: RescueOptions = {}): RescueResult {
   // lock on the same root the rescue script resolves (cwd when --hq-root is
   // omitted). Rescue is never the exempt push watcher, so it always locks.
   const lockRoot = opts.hqRoot ?? process.cwd();
+  // Consume --lock-timeout from extraArgs (machine entrypoint) before it can
+  // reach the rescue script, which doesn't understand it.
+  const { lockTimeoutSec, cleanedExtraArgs } = extractLockTimeout(opts);
+  const rescueOpts: RescueOptions = { ...opts, extraArgs: cleanedExtraArgs };
   let handle;
   try {
-    handle = acquireOperationLock(lockRoot, "rescue");
+    handle = acquireOperationLock(lockRoot, "rescue", { timeoutSec: lockTimeoutSec });
   } catch (err) {
     if (err instanceof OperationLockedError) {
       process.stderr.write(err.message + "\n");
@@ -111,7 +157,7 @@ export function rescue(opts: RescueOptions = {}): RescueResult {
     throw err;
   }
   try {
-    const args = buildRescueArgs(opts);
+    const args = buildRescueArgs(rescueOpts);
     const env: NodeJS.ProcessEnv = { ...process.env };
     if (opts.ghToken) env.GH_TOKEN = opts.ghToken;
     const { status } = runRescue(args, { env });

package/src/operation-lock.test.ts

@@ -9,10 +9,13 @@ import * as os from "os";
 import * as path from "path";
 import {
   acquireOperationLock,
+  acquireOperationLockAsync,
+  withOperationLock,
   withOperationLockSync,
   lockPathFor,
   OperationLockedError,
   OPERATION_LOCKED_EXIT,
+  DEFAULT_LOCK_POLL_MS,
   type LockInfo,
 } from "./operation-lock.js";
 
@@ -44,6 +47,7 @@ describe("operation-lock", () => {
     stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-oplock-state-"));
     process.env.HQ_STATE_DIR = stateDir;
     delete process.env.HQ_DISABLE_OP_LOCK;
+    delete process.env.HQ_OP_LOCK_TIMEOUT;
     rootA = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rootA-"));
     rootB = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rootB-"));
   });
@@ -54,6 +58,7 @@ describe("operation-lock", () => {
     fs.rmSync(rootB, { recursive: true, force: true });
     delete process.env.HQ_STATE_DIR;
     delete process.env.HQ_DISABLE_OP_LOCK;
+    delete process.env.HQ_OP_LOCK_TIMEOUT;
   });
 
   it("the lock path is under the state dir, keyed per canonical root", () => {
@@ -75,14 +80,17 @@ describe("operation-lock", () => {
     expect(fs.existsSync(h.path)).toBe(false);
   });
 
-  it("refuses fast with the holder's command + pid when a LIVE process holds it", () => {
+  it("refuses immediately (wait:false) 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.
+    // the same-process reclaim path does not apply. `wait:false` keeps the old
+    // refuse-immediately behavior (the default is now to WAIT).
     writeLock(lockPathFor(rootA), { pid: 1, command: "rescue" });
-    expect(() => acquireOperationLock(rootA, "sync")).toThrowError(OperationLockedError);
+    expect(() => acquireOperationLock(rootA, "sync", { wait: false })).toThrowError(
+      OperationLockedError,
+    );
     try {
-      acquireOperationLock(rootA, "sync");
+      acquireOperationLock(rootA, "sync", { wait: false });
     } catch (e) {
       const err = e as OperationLockedError;
       expect(err.holder.command).toBe("rescue");
@@ -92,11 +100,124 @@ describe("operation-lock", () => {
     }
   });
 
-  it("reclaims a stale lock whose holder PID is dead (takeover)", () => {
+  it("timeoutSec:0 refuses immediately (no wait) — equivalent to wait:false", () => {
+    writeLock(lockPathFor(rootA), { pid: 1, command: "sync" });
+    const start = Date.now();
+    expect(() => acquireOperationLock(rootA, "reindex", { timeoutSec: 0 })).toThrowError(
+      OperationLockedError,
+    );
+    // Did not actually sleep.
+    expect(Date.now() - start).toBeLessThan(DEFAULT_LOCK_POLL_MS);
+  });
+
+  it("a bounded timeoutSec waits, then refuses with the old message + exit code", () => {
+    writeLock(lockPathFor(rootA), { pid: 1, command: "rescue" });
+    const start = Date.now();
+    let thrown: unknown;
+    try {
+      // 150ms bound, 40ms poll → waits ~150ms then gives up. Suppress the
+      // stderr status line with a no-op onWaitStart.
+      acquireOperationLock(rootA, "sync", {
+        timeoutSec: 0.15,
+        pollIntervalMs: 40,
+        onWaitStart: () => {},
+      });
+    } catch (e) {
+      thrown = e;
+    }
+    const elapsed = Date.now() - start;
+    expect(thrown).toBeInstanceOf(OperationLockedError);
+    expect((thrown as OperationLockedError).message).toContain("rescue");
+    expect(OPERATION_LOCKED_EXIT).toBe(17);
+    // It actually waited (didn't refuse instantly) but didn't hang forever.
+    expect(elapsed).toBeGreaterThanOrEqual(120);
+    expect(elapsed).toBeLessThan(3000);
+  });
+
+  it("HQ_OP_LOCK_TIMEOUT env bounds the wait when no explicit option is given", () => {
+    process.env.HQ_OP_LOCK_TIMEOUT = "0"; // 0 → refuse immediately
+    writeLock(lockPathFor(rootA), { pid: 1, command: "sync" });
+    const start = Date.now();
+    expect(() =>
+      acquireOperationLock(rootA, "rescue", { onWaitStart: () => {} }),
+    ).toThrowError(OperationLockedError);
+    expect(Date.now() - start).toBeLessThan(DEFAULT_LOCK_POLL_MS);
+  });
+
+  it("an explicit timeoutSec overrides the HQ_OP_LOCK_TIMEOUT env", () => {
+    process.env.HQ_OP_LOCK_TIMEOUT = "9999"; // would be a near-infinite wait
+    writeLock(lockPathFor(rootA), { pid: 1, command: "sync" });
+    // The explicit 0 wins → refuse immediately rather than honoring the env.
+    expect(() =>
+      acquireOperationLock(rootA, "rescue", { timeoutSec: 0 }),
+    ).toThrowError(OperationLockedError);
+  });
+
+  it("onWaitStart fires exactly once, naming the holder, even across many polls", () => {
+    writeLock(lockPathFor(rootA), { pid: 1, command: "rescue" });
+    const calls: Array<{ cmd: string; attempted: string }> = [];
+    expect(() =>
+      acquireOperationLock(rootA, "sync", {
+        timeoutSec: 0.16,
+        pollIntervalMs: 30, // ~5 polls within the window
+        onWaitStart: (holder, attempted) => calls.push({ cmd: holder.command, attempted }),
+      }),
+    ).toThrowError(OperationLockedError);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toEqual({ cmd: "rescue", attempted: "sync" });
+  });
+
+  it("a waiter acquires the lock the moment the holder releases (async poll path)", async () => {
+    const p = lockPathFor(rootA);
+    // A foreign LIVE holder (pid 1) initially owns the lock.
+    writeLock(p, { pid: 1, command: "rescue" });
+    // Simulate the holder finishing ~80ms in by removing its lock file.
+    const release = setTimeout(() => fs.rmSync(p, { force: true }), 80);
+    const start = Date.now();
+    const h = await acquireOperationLockAsync(rootA, "sync", {
+      pollIntervalMs: 20,
+      onWaitStart: () => {},
+    });
+    clearTimeout(release);
+    const elapsed = Date.now() - start;
+    // We waited for the release, then took it over.
+    expect(elapsed).toBeGreaterThanOrEqual(60);
+    const info = JSON.parse(fs.readFileSync(h.path, "utf8")) as LockInfo;
+    expect(info.pid).toBe(process.pid);
+    expect(info.command).toBe("sync");
+    h.release();
+  });
+
+  it("multiple foreign holders in a row: each release lets the next waiter in (no FIFO guarantee)", async () => {
+    // The mutex is CROSS-PROCESS: it keys liveness on the holder's PID. Two
+    // waiters in the SAME process share a pid, so the same-process reclaim path
+    // would let them stomp each other — that scenario is unsupported by design.
+    // Here we model the real case: a sequence of FOREIGN holders (pid 1) that
+    // each release, with a single waiter acquiring the instant the lock frees.
+    // Order among multiple distinct-process waiters is whoever wins the next
+    // O_EXCL race after a free — best-effort, NOT FIFO (documented).
+    const p = lockPathFor(rootA);
+    writeLock(p, { pid: 1, command: "sync" });
+    // Free it shortly; the waiter should grab it right after.
+    setTimeout(() => fs.rmSync(p, { force: true }), 50);
+    const h = await acquireOperationLockAsync(rootA, "reindex", {
+      pollIntervalMs: 15,
+      onWaitStart: () => {},
+    });
+    const info = JSON.parse(fs.readFileSync(h.path, "utf8")) as LockInfo;
+    expect(info.command).toBe("reindex");
+    expect(info.pid).toBe(process.pid);
+    h.release();
+  });
+
+  it("reclaims a stale lock whose holder PID is dead (takeover, never waits)", () => {
     const stale = deadPid();
     writeLock(lockPathFor(rootA), { pid: stale, command: "sync" });
-    // The dead holder must not block us.
+    const start = Date.now();
+    // The dead holder must not block us — even with an infinite default wait,
+    // takeover is immediate.
     const h = acquireOperationLock(rootA, "rescue");
+    expect(Date.now() - start).toBeLessThan(DEFAULT_LOCK_POLL_MS);
     const info = JSON.parse(fs.readFileSync(h.path, "utf8")) as LockInfo;
     expect(info.pid).toBe(process.pid); // we took it over
     expect(info.command).toBe("rescue");
@@ -114,7 +235,7 @@ describe("operation-lock", () => {
 
   it("different HQ roots are independent — both may hold concurrently", () => {
     const a = acquireOperationLock(rootA, "sync");
-    const b = acquireOperationLock(rootB, "rescue"); // must NOT refuse
+    const b = acquireOperationLock(rootB, "rescue"); // must NOT block
     expect(fs.existsSync(a.path)).toBe(true);
     expect(fs.existsSync(b.path)).toBe(true);
     expect(a.path).not.toBe(b.path);
@@ -126,9 +247,14 @@ describe("operation-lock", () => {
     // 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);
+    // Neither rescue nor reindex may acquire while that sync holds it
+    // (wait:false → assert the refusal without hanging on the new wait default).
+    expect(() => acquireOperationLock(rootA, "rescue", { wait: false })).toThrowError(
+      OperationLockedError,
+    );
+    expect(() => acquireOperationLock(rootA, "reindex", { wait: false })).toThrowError(
+      OperationLockedError,
+    );
     // Once that sync finishes (its lock is gone), the next command acquires.
     fs.unlinkSync(p);
     const h2 = acquireOperationLock(rootA, "reindex");
@@ -147,6 +273,17 @@ describe("operation-lock", () => {
     expect(fs.existsSync(p)).toBe(false); // released on the way out
   });
 
+  it("withOperationLock (async) releases even when the body throws", async () => {
+    const p = lockPathFor(rootA);
+    await expect(
+      withOperationLock(rootA, "sync", async () => {
+        expect(fs.existsSync(p)).toBe(true);
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+    expect(fs.existsSync(p)).toBe(false);
+  });
+
   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.