@indigoai-us/hq-cloud 6.7.1 → 6.9.0

package/src/object-io.test.ts

@@ -109,6 +109,30 @@ describe("factory selection", () => {
   });
 });
 
+describe("S3SdkObjectIO.putObject — conditional-write fence", () => {
+  it("maps ifMatch (re-quoted) and ifNoneMatch onto the PutObjectCommand", async () => {
+    const io = new S3SdkObjectIO(ctx());
+    const sent: Array<Record<string, unknown>> = [];
+    // Swap the private client for a recorder — the fence mapping is pure
+    // input-shaping, no wire needed.
+    (io as unknown as { client: { send: (c: { input: Record<string, unknown> }) => Promise<unknown> } }).client = {
+      send: async (cmd) => {
+        sent.push(cmd.input);
+        return { ETag: '"landed"' };
+      },
+    };
+    await io.putObject({ key: "a", body: Buffer.from("x"), contentType: "t", ifMatch: "abc" });
+    expect(sent[0].IfMatch).toBe('"abc"'); // stripped etags re-quoted for If-Match
+    await io.putObject({ key: "a2", body: Buffer.from("x"), contentType: "t", ifMatch: '"quoted"' });
+    expect(sent[1].IfMatch).toBe('"quoted"'); // already-quoted passes through
+    await io.putObject({ key: "b", body: Buffer.from("y"), contentType: "t", ifNoneMatch: "*" });
+    expect(sent[2].IfNoneMatch).toBe("*");
+    await io.putObject({ key: "c", body: Buffer.from("z"), contentType: "t" });
+    expect(sent[3].IfMatch).toBeUndefined(); // unfenced PUT stays unfenced
+    expect(sent[3].IfNoneMatch).toBeUndefined();
+  });
+});
+
 describe("PresignObjectIO.putObject", () => {
   let fetchMock: ReturnType<typeof vi.fn>;
   beforeEach(() => {
@@ -190,6 +214,58 @@ describe("PresignObjectIO.putObject", () => {
       io.putObject({ key: "k", body: Buffer.from("z"), contentType: "x" }),
     ).rejects.toThrow(/presigned PUT failed for k: 403/);
   });
+
+  it("forwards the conditional-write fence on the presign request (ifMatch stripped, ifNoneMatch verbatim)", async () => {
+    // The server signs If-Match/If-None-Match into the URL (hq-pro follow-up)
+    // and echoes the headers for replay; the client's job is to ASK. Servers
+    // that predate the fields ignore them — never broken, just unconditional.
+    const { vault, presignCalls, setPresign } = makeVault();
+    setPresign([{ key: "fenced.md", op: "put", url: "https://s3/put-url" }]);
+    fetchMock.mockResolvedValue(
+      new Response(null, { status: 200, headers: { etag: '"v2"' } }),
+    );
+    const io = new PresignObjectIO(vault, COMPANY);
+    await io.putObject({
+      key: "fenced.md",
+      body: Buffer.from("x"),
+      contentType: "text/markdown",
+      ifMatch: '"v1"',
+    });
+    expect(presignCalls[0].keys[0]).toMatchObject({
+      key: "fenced.md",
+      op: "put",
+      ifMatch: "v1", // quotes stripped on the wire; server re-quotes when signing
+    });
+
+    await io.putObject({
+      key: "fresh.md",
+      body: Buffer.from("y"),
+      contentType: "text/markdown",
+      ifNoneMatch: "*",
+    });
+    expect(presignCalls[1].keys[0]).toMatchObject({
+      key: "fresh.md",
+      op: "put",
+      ifNoneMatch: "*",
+    });
+  });
+
+  it("maps a 412 PUT response to name:PreconditionFailed (the fence fired — conflict, not failure)", async () => {
+    const { vault, setPresign } = makeVault();
+    setPresign([{ key: "raced.md", op: "put", url: "https://s3/put-url" }]);
+    fetchMock.mockResolvedValue(
+      new Response("PreconditionFailed", { status: 412 }),
+    );
+    const io = new PresignObjectIO(vault, COMPANY);
+    await expect(
+      io.putObject({
+        key: "raced.md",
+        body: Buffer.from("z"),
+        contentType: "text/plain",
+        ifMatch: "old-etag",
+      }),
+    ).rejects.toMatchObject({ name: "PreconditionFailed" });
+  });
 });
 
 describe("PresignObjectIO.getObject", () => {
@@ -354,13 +430,40 @@ describe("PresignObjectIO.headObject", () => {
     expect(await io.headObject("gone")).toBeNull();
   });
 
-  it("returns null when presign denies the key (no usable head)", async () => {
+  it("throws Forbidden when presign denies the key — denial is NOT absence", async () => {
+    // Regression: pre-fix this returned null ("absent"), which made
+    // share.ts's push guard (`if (remoteMeta)`) skip every conflict check
+    // and issue an unconditional PUT — a transient denial mid-pass silently
+    // clobbered newer remote bytes (2026-06-10..12 vault regression storm).
     const { vault, setPresign } = makeVault();
     setPresign([{ key: "secret/x", op: "get", error: "forbidden" }]);
     const io = new PresignObjectIO(vault, COMPANY);
-    expect(await io.headObject("secret/x")).toBeNull();
+    await expect(io.headObject("secret/x")).rejects.toMatchObject({
+      name: "Forbidden",
+    });
     expect(fetchMock).not.toHaveBeenCalled();
   });
+
+  it("throws Forbidden on a presigned-GET 403 — same SDK-parity contract", async () => {
+    // Expired presigned URL, expired signing creds, KMS or bucket-policy
+    // denial all surface as 403 on the signed GET. Unknown state — must
+    // never read as "object missing".
+    const { vault, setPresign } = makeVault();
+    setPresign([{ key: "shared/a.md", op: "get", url: "https://s3/get" }]);
+    fetchMock.mockResolvedValue(new Response("AccessDenied", { status: 403 }));
+    const io = new PresignObjectIO(vault, COMPANY);
+    await expect(io.headObject("shared/a.md")).rejects.toMatchObject({
+      name: "Forbidden",
+    });
+  });
+
+  it("still returns null on a definitive 404 (key truly absent)", async () => {
+    const { vault, setPresign } = makeVault();
+    setPresign([{ key: "gone2", op: "get", url: "https://s3/get" }]);
+    fetchMock.mockResolvedValue(new Response("", { status: 404 }));
+    const io = new PresignObjectIO(vault, COMPANY);
+    expect(await io.headObject("gone2")).toBeNull();
+  });
 });
 
 /**

package/src/object-io.ts

@@ -68,7 +68,29 @@ export interface PresignTransportClient {
 // Wire-primitive shapes
 // ---------------------------------------------------------------------------
 
-export interface PutObjectInput {
+/**
+ * Conditional-write fence for a PUT (S3 conditional writes, GA 2024-11).
+ *
+ * `ifMatch` — only land the PUT if the remote object's ETag still equals
+ * this value (the journal baseline / last-observed HEAD). `ifNoneMatch: "*"`
+ * — only land the PUT if NO object exists at the key (creation fence).
+ * Either mismatch makes S3 reject with 412 PreconditionFailed, which the
+ * push path surfaces as a conflict instead of a silent overwrite.
+ *
+ * This is the storage-level backstop for the entire stale-clobber class:
+ * a HEAD-then-PUT race, a transport bug that misreads remote state, or an
+ * outdated client mid-pass can no longer regress a newer remote object —
+ * S3 itself refuses. (The 2026-06-10..12 vault regression storm was this
+ * class: stale machine copies blind-PUT over newer objects.)
+ */
+export interface PutPrecondition {
+  /** Land only if the current remote ETag equals this (quotes optional). */
+  ifMatch?: string;
+  /** Land only if no object exists at the key. */
+  ifNoneMatch?: "*";
+}
+
+export interface PutObjectInput extends PutPrecondition {
   key: string;
   body: Buffer;
   contentType: string;
@@ -117,7 +139,12 @@ export interface ObjectIO {
   getObject(key: string): Promise<GetObjectResult>;
   listObjects(input: ListObjectsInput): Promise<ListObjectsResult>;
   deleteObject(key: string): Promise<void>;
-  /** Null when the key does not exist (404 / 403-as-absent). */
+  /**
+   * Null ONLY when the key definitively does not exist (404). Access denial
+   * (403 / per-key presign denial) THROWS a `name: "Forbidden"` error — it is
+   * unknown state, never "absent". Conflating the two disables push-side
+   * conflict guards and clobbers newer remote objects.
+   */
   headObject(key: string): Promise<HeadObjectResult | null>;
   /**
    * Optional batch pre-mint. Warms an internal URL cache for `keys` under `op`
@@ -192,6 +219,13 @@ export class S3SdkObjectIO implements ObjectIO {
         ...(input.metadata && Object.keys(input.metadata).length > 0
           ? { Metadata: input.metadata }
           : {}),
+        // Conditional-write fence. If-Match wants the quoted entity-tag form;
+        // callers hand us journal/HEAD etags that may be stripped — re-quote
+        // so both shapes fence identically. A mismatch surfaces as the SDK's
+        // name:"PreconditionFailed" (HTTP 412), which the push path maps to
+        // its conflict flow.
+        ...(input.ifMatch ? { IfMatch: quoteEtag(input.ifMatch) } : {}),
+        ...(input.ifNoneMatch ? { IfNoneMatch: input.ifNoneMatch } : {}),
       }),
     );
     return { etag: res.ETag || "" };
@@ -311,6 +345,44 @@ function notFoundError(key: string): Error {
   return Object.assign(new Error(`Not found: ${key}`), { name: "NotFound" });
 }
 
+/**
+ * An error shaped like the AWS SDK's HeadObject 403 (`name: "Forbidden"`) so
+ * presigned-transport denials route through the SAME catch sites as SDK ones
+ * (share.ts / sync.ts `isAccessDenied`: name === "AccessDenied" | "Forbidden").
+ * Critically this is NOT `null`: "can't read the key" must never be conflated
+ * with "the key does not exist" — that conflation let a transient 403 episode
+ * disable every push-side conflict guard and clobber newer remote objects.
+ */
+function accessDeniedError(key: string, detail: string): Error {
+  return Object.assign(
+    new Error(`Access denied for ${key}: ${detail}`),
+    { name: "Forbidden" },
+  );
+}
+
+/**
+ * An error shaped like the AWS SDK's 412 (`name: "PreconditionFailed"`) so
+ * presigned-transport conditional-write rejections route through the same
+ * catch sites as SDK ones. A 412 means the fence WORKED: the remote moved
+ * past the caller's baseline (If-Match) or the key already exists
+ * (If-None-Match) — surface as a conflict, never overwrite.
+ */
+function preconditionFailedError(key: string, detail: string): Error {
+  return Object.assign(
+    new Error(`Precondition failed for ${key}: ${detail}`),
+    { name: "PreconditionFailed" },
+  );
+}
+
+/**
+ * If-Match compares quoted entity-tags. Journal baselines store etags
+ * stripped (normalizeEtag) while SDK HEADs return them quoted — accept both
+ * and emit the canonical quoted form.
+ */
+function quoteEtag(etag: string): string {
+  return etag.startsWith('"') ? etag : `"${etag}"`;
+}
+
 /**
  * Max keys per presign request when priming — the server's hard batch cap
  * (hq-pro files-presign MAX_BATCH_KEYS = 1000). One presign call costs ONE
@@ -435,7 +507,13 @@ export class PresignObjectIO implements ObjectIO {
   private async resolveUrl(
     op: PresignOp,
     key: string,
-    extra?: { contentType?: string; metadata?: Record<string, string> },
+    extra?: {
+      contentType?: string;
+      metadata?: Record<string, string>;
+      /** Conditional-write fence for PUT presigns — see PutPrecondition. */
+      ifMatch?: string;
+      ifNoneMatch?: "*";
+    },
   ): Promise<{ url: string; headers?: Record<string, string> }> {
     const hit = this.cached(op, key);
     if (hit) return { url: hit.url, headers: hit.headers };
@@ -509,11 +587,23 @@ export class PresignObjectIO implements ObjectIO {
   }
 
   async putObject(input: PutObjectInput): Promise<{ etag: string }> {
+    // Conditional-write fields (ifMatch/ifNoneMatch) are forwarded on the
+    // presign request so the server can sign If-Match/If-None-Match into the
+    // URL and echo them via `headers` for replay. Until hq-pro's
+    // files-presign signs them (follow-up to this PR), the server ignores
+    // the fields and the returned header set carries no condition — the PUT
+    // stays unconditional on this transport, exactly today's behavior. We
+    // deliberately do NOT inject the header client-side: an unsigned
+    // conditional header breaks the SigV4 signature. Enforcement on this
+    // transport activates the moment the server starts signing; the SDK
+    // transport enforces immediately.
     const row = await this.resolveUrl("put", input.key, {
       contentType: input.contentType,
       ...(input.metadata && Object.keys(input.metadata).length > 0
         ? { metadata: input.metadata }
         : {}),
+      ...(input.ifMatch ? { ifMatch: stripQuotes(input.ifMatch) } : {}),
+      ...(input.ifNoneMatch ? { ifNoneMatch: input.ifNoneMatch } : {}),
     });
     // The server signs Content-Type, SSE-KMS, and every x-amz-meta-* into the
     // signature and returns them in `headers`; they MUST be replayed verbatim
@@ -523,6 +613,14 @@ export class PresignObjectIO implements ObjectIO {
       { method: "PUT", body: input.body, headers: row.headers ?? {} },
       `presigned PUT ${input.key}`,
     );
+    if (res.status === 412) {
+      // The signed conditional header fenced this write off: the remote
+      // moved past our baseline (If-Match) or the key already exists
+      // (If-None-Match). Same shape as the SDK's PreconditionFailed so the
+      // push path routes both transports through one conflict handler.
+      const detail = await safeText(res);
+      throw preconditionFailedError(input.key, detail);
+    }
     if (!res.ok) {
       const detail = await safeText(res);
       throw new Error(
@@ -607,18 +705,33 @@ export class PresignObjectIO implements ObjectIO {
       }
       const row = results[0];
       if (!row || row.error || !row.url) {
-        // A per-key denial here means the caller can't read the key — treat as
-        // absent for HEAD semantics (the SDK path would 403, which callers map
-        // to "no usable head"); they all tolerate null.
-        return null;
+        // A per-key denial means the caller can't READ the key — it says
+        // nothing about whether the object EXISTS. Pre-fix this returned
+        // null ("absent"), which made push call sites skip every conflict
+        // guard (`if (remoteMeta)`) and issue an UNCONDITIONAL PUT — a
+        // transient denial episode mid-pass silently clobbered newer remote
+        // bytes with this machine's stale copy (the 2026-06-10..12 vault
+        // regression storm). Throw the same access-denied shape the SDK
+        // transport raises so callers route through their existing
+        // isAccessDenied skip/defer paths instead of "object missing".
+        throw accessDeniedError(key, row?.error ?? "presign denied");
       }
       url = row.url;
     }
     const res = await fetchWithRetry(url, { method: "GET" }, `presigned HEAD ${key}`);
-    if (res.status === 404 || res.status === 403) {
+    if (res.status === 404) {
       await cancelBody(res);
       return null;
     }
+    if (res.status === 403) {
+      // 403 on the signed GET (expired URL, expired signing creds, KMS or
+      // bucket-policy denial) is UNKNOWN state, not absence — see the presign
+      // denial branch above. The SDK transport throws name:"Forbidden" here;
+      // mirror it so both transports agree and no caller mistakes a denial
+      // for a missing object.
+      await cancelBody(res);
+      throw accessDeniedError(key, "presigned HEAD returned 403");
+    }
     if (!res.ok) {
       await cancelBody(res);
       const detail = await safeText(res);

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.