@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/operation-lock.ts

@@ -1,680 +0,0 @@
-/**
- * Per-HQ-root mutual exclusion for the long-running operations
- * (`sync`, `rescue`, `reindex`).
- *
- * Contract:
- *   - `sync` and `rescue` share ONE per-root lock (the "operation" scope, keyed
- *     only by the root, not the command), so at most one of them runs at a time
- *     and e.g. a rescue refuses while a sync holds it. Different HQ roots are
- *     fully independent — they hash to different lock files.
- *   - `reindex` uses a SEPARATE per-root scope ("reindex"), so it is guarded
- *     against other reindexes but is NOT blocked by a held sync/rescue lock.
- *     This is deliberate: a watch-mode `hq-sync-runner` holds the "operation"
- *     lock across its entire lifetime, and a shared lock would starve a
- *     standalone `hq reindex` indefinitely (feedback_ed98d810). reindex only
- *     READS the source trees to rebuild derived artifacts (skill wrappers,
- *     overlay mirrors, the workers registry) and is idempotent + re-run after
- *     every sync pass, so decoupling it from the sync writer lock is safe.
- *     See {@link lockPathFor} for how the scope partitions the lock file.
- *   - 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 writes the full owner payload to a same-directory temp file,
- *     fsyncs it, then publishes that complete file into the final lock name
- *     with create-if-absent semantics. Exactly one racer can publish; 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 IMMEDIATELY (a dead holder never makes us
- *                  wait).
- *       * EPERM  → the PID exists but is owned by another user → treat as ALIVE
- *                  (conservative: wait rather than risk two concurrent ops).
- *       * success → alive → WAIT for the holder to release, then acquire (see
- *                  "Waiting" below). The fast-refusal path is still reachable
- *                  via an explicit timeout / `wait: false`.
- *
- * ## Waiting for a live holder (default behavior)
- *
- *   When a LIVE holder owns the lock, acquisition WAITS by default: it polls
- *   (~2s) and acquires the instant the holder releases, rather than refusing
- *   fast. A single status line is written to stderr the first time we start
- *   waiting ("Waiting for <command> (pid N) to finish…"), never per-poll.
- *   This is what an interactive `sync` / `rescue` / `reindex` invocation wants —
- *   queue behind the running op instead of erroring out.
- *
- *   A bounded escape exists for scripts that must not block forever:
- *     - `timeoutSec` option, or the `HQ_OP_LOCK_TIMEOUT` env var (seconds).
- *       The option wins over the env. After the bound elapses we throw
- *       {@link OperationLockedError} (exit 17) with the same clear refusal
- *       message as before.
- *     - `timeoutSec === 0` (or `HQ_OP_LOCK_TIMEOUT=0`, or `wait: false`) → do
- *       not wait at all; refuse immediately. This is the pre-wait behavior.
- *     - absent / negative / unparseable → INFINITE wait (the documented
- *       default).
- *   Stale-PID takeover is unconditional and happens BEFORE any wait — a dead
- *   holder is reclaimed at once regardless of the wait config.
- *
- *   Ordering / scope caveats:
- *     - This is a CROSS-PROCESS mutex keyed on the holder's PID. In-process
- *       concurrent acquire is unsupported (the real consumers — sync / rescue /
- *       reindex — are separate processes), but a live same-PID holder is still
- *       treated as busy rather than reclaimed.
- *     - When several distinct processes wait on the same lock, the next one to
- *       win the O_EXCL race after a free acquires. Order is best-effort, NOT
- *       FIFO — do not depend on arrival order.
- *   - 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;
-
-/**
- * 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;
-  /** ISO-8601 acquisition time. */
-  startedAt: string;
-  /** Canonical HQ root the lock guards (diagnostic only). */
-  hqRoot: string;
-}
-
-/** Thrown by `acquireOperationLock` when a LIVE holder owns the lock. */
-export class OperationLockedError extends Error {
-  constructor(
-    public readonly holder: LockInfo,
-    public readonly attempted: string,
-  ) {
-    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.name = "OperationLockedError";
-  }
-}
-
-/**
- * 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;
-  /** The info written for this holder. */
-  readonly info: LockInfo;
-  /** Idempotently release the lock iff this process still owns it. */
-  release(): void;
-}
-
-/** Default poll interval while waiting on a live holder. */
-export const DEFAULT_LOCK_POLL_MS = 2000;
-
-/** Options controlling how `acquireOperationLock*` behaves against a LIVE holder. */
-export interface AcquireOptions {
-  /**
-   * When a LIVE holder owns the lock: `true` (default) → WAIT-poll until it
-   * frees, then acquire; `false` → refuse immediately with
-   * {@link OperationLockedError}. A `timeoutSec` of 0 is equivalent to
-   * `wait: false`.
-   */
-  wait?: boolean;
-  /**
-   * Bounded wait, in seconds, before giving up and throwing
-   * {@link OperationLockedError} (exit 17). Precedence: this option > the
-   * `HQ_OP_LOCK_TIMEOUT` env var > infinite. `0` → do not wait at all (refuse
-   * immediately). Negative / non-finite → treated as absent (infinite wait).
-   * Fractional values are honored (used by tests); the CLI flags accept whole
-   * seconds.
-   */
-  timeoutSec?: number;
-  /** Poll interval in ms while waiting. Defaults to {@link DEFAULT_LOCK_POLL_MS}. */
-  pollIntervalMs?: number;
-  /**
-   * Invoked exactly ONCE, the first time we begin waiting on a live holder.
-   * Defaults to a single "Waiting for …" line on stderr. Pass a custom hook
-   * (or a no-op) to redirect/silence the status line.
-   */
-  onWaitStart?: (holder: LockInfo, attempted: string) => void;
-  /**
-   * Lock scope — partitions the per-root mutex into independent lock files (see
-   * {@link lockPathFor}). Defaults to {@link DEFAULT_LOCK_SCOPE} ("operation"),
-   * which `sync`/`rescue` share. `reindex` passes "reindex" so it is guarded
-   * against other reindexes without being blocked by a held sync/rescue lock.
-   */
-  scope?: string;
-}
-
-interface ResolvedWaitConfig {
-  /** null → wait forever; >= 0 → wait at most this many ms (0 = no wait). */
-  timeoutMs: number | null;
-  pollMs: number;
-  onWaitStart: (holder: LockInfo, attempted: string) => void;
-}
-
-/** Default status line: a single stderr message naming the holder. */
-function defaultOnWaitStart(holder: LockInfo, attempted: string): void {
-  process.stderr.write(
-    `Waiting for "${holder.command}" (pid ${holder.pid}) to finish before ` +
-      `starting "${attempted}"… (set HQ_OP_LOCK_TIMEOUT=<secs> to bound the wait)\n`,
-  );
-}
-
-/**
- * Resolve the effective wait config from explicit options + the
- * `HQ_OP_LOCK_TIMEOUT` env var. Option timeout wins over the env; `wait: false`
- * forces a zero (no-wait) timeout.
- */
-function resolveWaitConfig(opts: AcquireOptions): ResolvedWaitConfig {
-  // Parse a seconds value into ms, or null for "absent/infinite". Only a
-  // finite, non-negative number counts; everything else (NaN, Infinity, <0)
-  // means "no explicit bound".
-  const toMs = (sec: number | undefined): number | null => {
-    if (sec === undefined) return null;
-    if (!Number.isFinite(sec) || sec < 0) return null;
-    return Math.round(sec * 1000);
-  };
-
-  let timeoutMs: number | null;
-  if (opts.timeoutSec !== undefined) {
-    timeoutMs = toMs(opts.timeoutSec);
-  } else {
-    const envRaw = process.env.HQ_OP_LOCK_TIMEOUT;
-    timeoutMs = envRaw !== undefined && envRaw !== "" ? toMs(Number(envRaw)) : null;
-  }
-
-  // `wait: false` is shorthand for a zero-length wait (refuse immediately).
-  if (opts.wait === false) timeoutMs = 0;
-
-  const pollMs =
-    opts.pollIntervalMs && opts.pollIntervalMs > 0
-      ? opts.pollIntervalMs
-      : DEFAULT_LOCK_POLL_MS;
-
-  return { timeoutMs, pollMs, onWaitStart: opts.onWaitStart ?? defaultOnWaitStart };
-}
-
-/** Block the current thread for `ms` without busy-spinning (sync consumers). */
-function sleepSync(ms: number): void {
-  if (ms <= 0) return;
-  // Atomics.wait on a private buffer is a clean, CPU-free sleep. The value at
-  // index 0 is 0 and nothing ever notifies it, so this always sleeps the full
-  // timeout (or less if interrupted) and returns "timed-out".
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-/** Non-blocking sleep for the async consumer. */
-function sleepAsync(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
-}
-
-function stateDir(): string {
-  return process.env.HQ_STATE_DIR || path.join(os.homedir(), ".hq");
-}
-
-function canonicalRoot(hqRoot: string): string {
-  const resolved = path.resolve(hqRoot);
-  try {
-    return fs.realpathSync.native(resolved);
-  } catch {
-    return resolved;
-  }
-}
-
-/**
- * Default lock scope. `sync` and `rescue` share this one so they stay mutually
- * exclusive with each other, keyed only by the root.
- */
-export const DEFAULT_LOCK_SCOPE = "operation";
-
-/**
- * Absolute lock path for a given HQ root and `scope`. Exported for tests.
- *
- * The `scope` prefixes the lock filename so callers can partition the mutex:
- * `sync`/`rescue` use {@link DEFAULT_LOCK_SCOPE} ("operation"); `reindex` uses
- * its own "reindex" scope so a long-lived watch-mode sync-runner (which holds
- * the "operation" lock across its whole lifetime) can never starve a standalone
- * `hq reindex`. Different scopes hash to different lock files and never block
- * one another; the same scope is a real cross-process mutex.
- */
-export function lockPathFor(hqRoot: string, scope: string = DEFAULT_LOCK_SCOPE): string {
-  const canon = canonicalRoot(hqRoot);
-  const key = crypto.createHash("sha1").update(canon).digest("hex").slice(0, 16);
-  return path.join(stateDir(), "locks", `${scope}-${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: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException)?.code;
-    if (code === "ESRCH") return false;
-    return true; // EPERM (exists) or unknown → treat as alive
-  }
-}
-
-function readLockInfo(p: string): LockInfo | null {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(p, "utf8")) as LockInfo;
-    if (parsed && typeof parsed.pid === "number" && typeof parsed.command === "string") {
-      return parsed;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-function initializingLockInfo(p: string): LockInfo {
-  let mtimeMs = Date.now();
-  try {
-    const st = fs.statSync(p);
-    mtimeMs = st.mtimeMs;
-  } catch {
-    /* lock disappeared between EEXIST and stat; treat as transient busy */
-  }
-  return {
-    pid: 0,
-    command: "operation-lock writer",
-    startedAt: new Date(mtimeMs).toISOString(),
-    hqRoot: "unknown",
-  };
-}
-
-// ── 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<LockHandle>();
-let hooksInstalled = false;
-
-function unlinkIfOwned(p: string): void {
-  // 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(): void {
-  if (hooksInstalled) return;
-  hooksInstalled = true;
-
-  process.on("exit", () => {
-    for (const h of heldLocks) unlinkIfOwned(h.path);
-  });
-
-  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
-    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: string, info: LockInfo): LockHandle {
-  const handle: LockHandle = {
-    path: p,
-    info,
-    release() {
-      heldLocks.delete(handle);
-      unlinkIfOwned(p);
-    },
-  };
-  heldLocks.add(handle);
-  installHooksOnce();
-  return handle;
-}
-
-const NOOP_HANDLE_BASE = { release() {} };
-
-/** No-op handle for the `HQ_DISABLE_OP_LOCK=1` escape hatch. */
-function disabledHandle(hqRoot: string, command: string): LockHandle {
-  const info: LockInfo = {
-    pid: process.pid,
-    command,
-    startedAt: new Date().toISOString(),
-    hqRoot: canonicalRoot(hqRoot),
-  };
-  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,
-  scope: string = DEFAULT_LOCK_SCOPE,
-): { p: string; info: LockInfo; payload: string } {
-  const p = lockPathFor(hqRoot, scope);
-  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,
-    startedAt: new Date().toISOString(),
-    hqRoot: canonicalRoot(hqRoot),
-  };
-  return { p, info, payload: JSON.stringify(info, null, 2) };
-}
-
-function writeLockTemp(dir: string, payload: string): string {
-  const tmp = path.join(
-    dir,
-    `.operation-lock.${process.pid}.${Date.now()}.${crypto.randomBytes(6).toString("hex")}.tmp`,
-  );
-  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);
-    fs.fsyncSync(fd);
-    fs.closeSync(fd);
-    closed = true;
-    return tmp;
-  } catch (err) {
-    if (!closed) {
-      try {
-        fs.closeSync(fd);
-      } catch {
-        /* best-effort cleanup */
-      }
-    }
-    try {
-      fs.rmSync(tmp, { force: true });
-    } catch {
-      /* best-effort cleanup */
-    }
-    throw err;
-  }
-}
-
-function publishLockPayload(p: string, payload: string): boolean {
-  const dir = path.dirname(p);
-  const tmp = writeLockTemp(dir, payload);
-  try {
-    // `link` is the no-overwrite atomic publish primitive available in Node:
-    // it fails with EEXIST if the final lock name is already present, and the
-    // final name never exists until the fully-written payload is linked there.
-    fs.linkSync(tmp, p);
-    return true;
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException)?.code === "EEXIST") return false;
-    throw err;
-  } finally {
-    try {
-      fs.rmSync(tmp, { force: true });
-    } catch {
-      /* best-effort cleanup */
-    }
-  }
-}
-
-/**
- * One acquisition pass. Returns the {@link LockHandle} on success, or
- * `{ busy }` naming the LIVE holder that blocked us (so the caller can decide
- * to wait or refuse). A valid stale lock is reclaimed in-pass and never
- * reported as busy; empty/torn locks are treated as initializing and left in
- * place. Throws only on genuinely pathological churn or unexpected fs errors.
- */
-function tryAcquireOnce(
-  p: string,
-  info: LockInfo,
-  payload: string,
-): { handle: LockHandle } | { busy: LockInfo } {
-  // Bounded retry: each iteration is one atomic create attempt. EEXIST against
-  // a stale holder reclaims and retries; EEXIST against a live holder reports
-  // it as busy.
-  const MAX_ATTEMPTS = 5;
-  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
-    if (publishLockPayload(p, payload)) {
-      return { handle: makeHandle(p, info) };
-    }
-
-    const holder = readLockInfo(p);
-    if (holder) {
-      if (pidAlive(holder.pid)) return { busy: holder };
-      try {
-        fs.unlinkSync(p);
-      } catch {
-        /* someone else reclaimed it first; the next publish re-evaluates */
-      }
-      continue;
-    }
-
-    return { busy: initializingLockInfo(p) };
-  }
-
-  // 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`,
-  );
-}
-
-/** ms left until `deadline` (null deadline → never expires). */
-function remainingMs(deadline: number | null): number {
-  return deadline === null ? Infinity : deadline - Date.now();
-}
-
-/**
- * Acquire the per-root operation lock for `command` (synchronous). Returns a
- * {@link LockHandle} on success. Against a LIVE holder it WAITS by default
- * (polling, blocking the thread) and acquires the moment the holder releases;
- * pass `timeoutSec`/`wait` (or set `HQ_OP_LOCK_TIMEOUT`) to bound or disable the
- * wait — on expiry it throws {@link OperationLockedError}. A stale lock (dead
- * holder) is reclaimed immediately, never waited on.
- */
-export function acquireOperationLock(
-  hqRoot: string,
-  command: string,
-  opts: AcquireOptions = {},
-): LockHandle {
-  if (process.env.HQ_DISABLE_OP_LOCK === "1") return disabledHandle(hqRoot, command);
-
-  const { p, info, payload } = prepareLock(hqRoot, command, opts.scope);
-  const cfg = resolveWaitConfig(opts);
-  const deadline = cfg.timeoutMs === null ? null : Date.now() + cfg.timeoutMs;
-  let announced = false;
-
-  for (;;) {
-    const res = tryAcquireOnce(p, info, payload);
-    if ("handle" in res) return res.handle;
-
-    // A live holder blocked us. Decide: refuse now, or wait and retry.
-    if (remainingMs(deadline) <= 0) throw new OperationLockedError(res.busy, command);
-    if (!announced) {
-      announced = true;
-      cfg.onWaitStart(res.busy, command);
-    }
-    sleepSync(Math.min(cfg.pollMs, remainingMs(deadline)));
-  }
-}
-
-/**
- * Async counterpart to {@link acquireOperationLock}. Identical semantics, but
- * the wait yields the event loop (via `setTimeout`) instead of blocking the
- * thread — required for the async `sync` runner.
- */
-export async function acquireOperationLockAsync(
-  hqRoot: string,
-  command: string,
-  opts: AcquireOptions = {},
-): Promise<LockHandle> {
-  if (process.env.HQ_DISABLE_OP_LOCK === "1") return disabledHandle(hqRoot, command);
-
-  const { p, info, payload } = prepareLock(hqRoot, command, opts.scope);
-  const cfg = resolveWaitConfig(opts);
-  const deadline = cfg.timeoutMs === null ? null : Date.now() + cfg.timeoutMs;
-  let announced = false;
-
-  for (;;) {
-    const res = tryAcquireOnce(p, info, payload);
-    if ("handle" in res) return res.handle;
-
-    if (remainingMs(deadline) <= 0) throw new OperationLockedError(res.busy, command);
-    if (!announced) {
-      announced = true;
-      cfg.onWaitStart(res.busy, command);
-    }
-    await sleepAsync(Math.min(cfg.pollMs, remainingMs(deadline)));
-  }
-}
-
-/** Run `fn` while holding the per-root lock for `command` (async). */
-export async function withOperationLock<T>(
-  hqRoot: string,
-  command: string,
-  fn: () => Promise<T>,
-  opts: AcquireOptions = {},
-): Promise<T> {
-  const handle = await acquireOperationLockAsync(hqRoot, command, opts);
-  try {
-    return await fn();
-  } finally {
-    handle.release();
-  }
-}
-
-/** Run `fn` while holding the per-root lock for `command` (synchronous). */
-export function withOperationLockSync<T>(
-  hqRoot: string,
-  command: string,
-  fn: () => T,
-  opts: AcquireOptions = {},
-): T {
-  const handle = acquireOperationLock(hqRoot, command, opts);
-  try {
-    return fn();
-  } finally {
-    handle.release();
-  }
-}