@indigoai-us/hq-cloud 6.13.0 → 6.13.2

package/src/bin/sync-runner.ts

@@ -171,6 +171,37 @@ const DEFAULT_VAULT_API_URL =
   process.env.HQ_VAULT_API_URL ?? "https://hqapi.getindigo.ai";
 
 const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
+const DEFAULT_TELEMETRY_TIMEOUT_MS = 120_000;
+
+function resolveTelemetryTimeoutMs(override?: number): number {
+  if (override !== undefined && Number.isFinite(override) && override >= 0) {
+    return Math.trunc(override);
+  }
+  const raw = process.env.HQ_TELEMETRY_TIMEOUT_MS;
+  if (raw) {
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed >= 0) return parsed;
+  }
+  return DEFAULT_TELEMETRY_TIMEOUT_MS;
+}
+
+async function awaitTelemetryWithTimeout(
+  telemetry: Promise<void>,
+  timeoutMs: number,
+  onTimeout: () => void,
+): Promise<void> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<"timeout">((resolve) => {
+    timeout = setTimeout(() => resolve("timeout"), timeoutMs);
+    timeout.unref?.();
+  });
+  const result = await Promise.race([
+    telemetry.then(() => "done" as const),
+    timeoutPromise,
+  ]);
+  if (timeout) clearTimeout(timeout);
+  if (result === "timeout") onTimeout();
+}
 
 /**
  * Delete-propagation policy honored by the push leg of bidirectional sync.
@@ -559,6 +590,8 @@ export interface RunnerDeps {
    * an explicit stub here.
    */
   collectTelemetry?: () => Promise<void>;
+  /** Maximum time to wait for pre-completion telemetry. Defaults to 120s. */
+  telemetryTimeoutMs?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -1169,24 +1202,34 @@ export async function runRunner(
 
   // Fire telemetry collector before the all-complete emit so the cursor at
   // `~/.hq/telemetry-cursor.json` is consistent with what the menubar sees.
-  await emitTelemetry({
-    collectTelemetry: deps.collectTelemetry,
-    defaultCollectTelemetry: () =>
-      defaultCollectTelemetry(
-        client,
-        deps.createVaultClient !== undefined,
-        parsed.hqRoot,
-        reportDiagnostic,
-      ),
-    onError: (err) =>
+  await awaitTelemetryWithTimeout(
+    emitTelemetry({
+      collectTelemetry: deps.collectTelemetry,
+      defaultCollectTelemetry: () =>
+        defaultCollectTelemetry(
+          client,
+          deps.createVaultClient !== undefined,
+          parsed.hqRoot,
+          reportDiagnostic,
+        ),
+      onError: (err) =>
+        reportDiagnostic({
+          component: "telemetry",
+          event: "runner.telemetry.collector_failed",
+          message: "telemetry collector failed",
+          err,
+          context: { hqRoot: parsed.hqRoot },
+        }),
+    }),
+    resolveTelemetryTimeoutMs(deps.telemetryTimeoutMs),
+    () =>
       reportDiagnostic({
         component: "telemetry",
-        event: "runner.telemetry.collector_failed",
-        message: "telemetry collector failed",
-        err,
+        event: "runner.telemetry.timeout",
+        message: "telemetry collector timed out; continuing sync completion",
         context: { hqRoot: parsed.hqRoot },
       }),
-  });
+  );
 
   emit({
     type: "all-complete",

package/src/cli/reindex.test.ts

@@ -124,6 +124,66 @@ describe("reindex", () => {
     expect(fs.readlinkSync(link)).toBe("../../personal/policies/myrule.md");
   });
 
+  it("collapses per-file overlay-skip spam into ONE summary line (HQ-SYNC-2)", () => {
+    // A REAL core file sits where an overlay symlink would go — the legitimate
+    // no-op that used to spam one stderr line per entry and flood the Sentry
+    // breadcrumb ring, evicting the real per-company sync error.
+    fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
+    fs.writeFileSync(path.join(root, "personal/policies/collide.md"), "rule\n");
+    fs.mkdirSync(path.join(root, "core/policies"), { recursive: true });
+    fs.writeFileSync(path.join(root, "core/policies/collide.md"), "REAL core file\n");
+
+    const writes: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(((chunk: unknown) => {
+        writes.push(String(chunk));
+        return true;
+      }) as typeof process.stderr.write);
+    let status: number;
+    try {
+      status = reindex({ repoRoot: root }).status;
+    } finally {
+      spy.mockRestore();
+    }
+    const stderr = writes.join("");
+
+    expect(status).toBe(0);
+    // The pre-existing real file is left untouched (never overwritten).
+    expect(fs.lstatSync(path.join(root, "core/policies/collide.md")).isSymbolicLink()).toBe(false);
+    // No per-file spam…
+    expect(stderr).not.toContain("already exists and is not a symlink; skipping");
+    // …just ONE collapsed summary naming the count.
+    expect(stderr).toMatch(/left 1 pre-existing non-symlink entry untouched/);
+    expect(stderr).toContain("HQ_REINDEX_VERBOSE=1");
+  });
+
+  it("keeps per-file overlay-skip detail under HQ_REINDEX_VERBOSE=1", () => {
+    fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
+    fs.writeFileSync(path.join(root, "personal/policies/collide.md"), "rule\n");
+    fs.mkdirSync(path.join(root, "core/policies"), { recursive: true });
+    fs.writeFileSync(path.join(root, "core/policies/collide.md"), "REAL\n");
+
+    const writes: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(((chunk: unknown) => {
+        writes.push(String(chunk));
+        return true;
+      }) as typeof process.stderr.write);
+    process.env.HQ_REINDEX_VERBOSE = "1";
+    try {
+      reindex({ repoRoot: root });
+    } finally {
+      spy.mockRestore();
+      delete process.env.HQ_REINDEX_VERBOSE;
+    }
+    const stderr = writes.join("");
+    expect(stderr).toContain(
+      "core/policies/collide.md already exists and is not a symlink; skipping",
+    );
+  });
+
   it("prunes orphan managed wrappers when the source skill disappears", () => {
     writeSkill("core/skills/demo");
     reindex({ repoRoot: root });

package/src/cli/reindex.ts

@@ -20,7 +20,9 @@ import * as path from "path";
 import {
   acquireOperationLock,
   OperationLockedError,
+  OperationLockUnwritableError,
   OPERATION_LOCKED_EXIT,
+  OPERATION_LOCK_UNWRITABLE_EXIT,
   type LockHandle,
 } from "../operation-lock.js";
 
@@ -218,11 +220,31 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
         warn(err.message);
         return { status: OPERATION_LOCKED_EXIT };
       }
+      if (err instanceof OperationLockUnwritableError) {
+        // The lock dir isn't writable (e.g. macOS EPERM / Linux EACCES on a
+        // root-owned or restricted ~/.hq). This is an environmental problem on
+        // the user's machine, not an HQ fault — surface the actionable guidance
+        // and exit cleanly instead of crashing with a raw `EPERM ... open`
+        // (HQ-CLI-2).
+        warn(err.message);
+        return { status: OPERATION_LOCK_UNWRITABLE_EXIT };
+      }
       throw err;
     }
   }
   try {
 
+  // Overlay/skill-wrapper mirroring is best-effort and, on a normal synced HQ,
+  // legitimately no-ops for MANY entries (a real core file already sits where a
+  // symlink would go, or a link already points elsewhere). Emitting one stderr
+  // line PER such entry floods the runner's Sentry breadcrumb ring (100 entries)
+  // and evicts the real per-company sync error, making code-2 syncs impossible to
+  // triage (HQ-SYNC-2 / HQ-SYNC-WEB-6). Collapse those per-file lines into a
+  // single end-of-run summary; keep per-file detail behind HQ_REINDEX_VERBOSE=1.
+  const verbose = process.env.HQ_REINDEX_VERBOSE === "1";
+  let skippedNonSymlink = 0;
+  let skippedPointsElsewhere = 0;
+
   // Best-effort: each wrapper mkdir below is recursive and re-creates this
   // parent as needed, so a failure here is non-fatal — warn and carry on so
   // personal-overlay mirroring and registry regeneration still run.
@@ -341,12 +363,18 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
         if (lst && lst.isSymbolicLink()) {
           const current = readlinkOrNull(linkPath);
           if (current === relativeTarget) continue;
-          warn(
-            `reindex: .claude/skills/${wrapperName}/${entry} already points to '${current}' (expected '${relativeTarget}'); leaving alone`,
-          );
+          skippedPointsElsewhere++;
+          if (verbose) {
+            warn(
+              `reindex: .claude/skills/${wrapperName}/${entry} already points to '${current}' (expected '${relativeTarget}'); leaving alone`,
+            );
+          }
           continue;
         } else if (lst) {
-          warn(`reindex: ${linkPath} already exists and is not a symlink; skipping`);
+          skippedNonSymlink++;
+          if (verbose) {
+            warn(`reindex: ${linkPath} already exists and is not a symlink; skipping`);
+          }
           continue;
         }
 
@@ -440,12 +468,18 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
       if (lst && lst.isSymbolicLink()) {
         const current = readlinkOrNull(linkPath);
         if (current === relativeTarget) continue;
-        warn(
-          `reindex: core/${type}/${entry} already points to '${current}' (expected '${relativeTarget}'); leaving alone`,
-        );
+        skippedPointsElsewhere++;
+        if (verbose) {
+          warn(
+            `reindex: core/${type}/${entry} already points to '${current}' (expected '${relativeTarget}'); leaving alone`,
+          );
+        }
         continue;
       } else if (lst) {
-        warn(`reindex: core/${type}/${entry} already exists and is not a symlink; skipping`);
+        skippedNonSymlink++;
+        if (verbose) {
+          warn(`reindex: core/${type}/${entry} already exists and is not a symlink; skipping`);
+        }
         continue;
       }
 
@@ -463,6 +497,22 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
     spawnSync("bash", [genScript], { stdio: ["ignore", 2, 2] });
   }
 
+  // One-line summary in place of the per-file overlay-skip spam (see the comment
+  // at the top of the try). Only emitted when something was skipped, so a clean
+  // run stays silent and the breadcrumb ring is free for real sync errors.
+  if (skippedNonSymlink > 0 || skippedPointsElsewhere > 0) {
+    const parts: string[] = [];
+    if (skippedNonSymlink > 0) {
+      parts.push(`${skippedNonSymlink} pre-existing non-symlink ${skippedNonSymlink === 1 ? "entry" : "entries"}`);
+    }
+    if (skippedPointsElsewhere > 0) {
+      parts.push(`${skippedPointsElsewhere} ${skippedPointsElsewhere === 1 ? "entry" : "entries"} already pointing elsewhere`);
+    }
+    warn(
+      `reindex: left ${parts.join(" + ")} untouched (overlay mirror is best-effort; set HQ_REINDEX_VERBOSE=1 for per-file detail)`,
+    );
+  }
+
   return { status: 0 };
   } finally {
     opLock?.release();

package/src/ignore.test.ts

@@ -177,8 +177,8 @@ describe("createIgnoreFilter", () => {
     const shouldSync = createIgnoreFilter(hqRoot);
     expect(shouldSync(path.join(hqRoot, ".claude/worktrees/foo/file.ts"))).toBe(false);
     expect(shouldSync(path.join(hqRoot, "companies/indigo/.claude/worktrees/bar/x.md"))).toBe(false);
-    // The .claude/ dir itself (settings, commands, skills) still syncs.
-    expect(shouldSync(path.join(hqRoot, ".claude/settings.json"))).toBe(true);
+    // The .claude/ dir itself (commands, skills, hooks) still syncs.
+    expect(shouldSync(path.join(hqRoot, ".claude/skills/foo/SKILL.md"))).toBe(true);
   });
 
   it("permissive mode: .hq-* internal state is ignored, .hqignore family still sync", () => {
@@ -226,13 +226,36 @@ describe("createIgnoreFilter", () => {
     expect(
       shouldSync(path.join(hqRoot, "companies/indigo/.claude/audit/instructions.md")),
     ).toBe(false);
-    // The .claude/ dir's other contents (settings, commands, skills,
-    // hooks) still sync — the rule MUST NOT broaden to .claude/.
-    expect(shouldSync(path.join(hqRoot, ".claude/settings.json"))).toBe(true);
+    // The .claude/ dir's other contents (commands, skills, hooks) still
+    // sync — the rule MUST NOT broaden to .claude/.
     expect(shouldSync(path.join(hqRoot, ".claude/skills/foo/SKILL.md"))).toBe(true);
     expect(shouldSync(path.join(hqRoot, ".claude/hooks/foo.sh"))).toBe(true);
   });
 
+  it("permissive mode: .claude/settings*.json is machine-local, never synced (qmd PATH regression)", () => {
+    // 2026-07-01 e2e-mac report (20260701-qmd-path): cloud sync pulled the
+    // operator's .claude/settings.json over a fresh install's copy ~40s
+    // after install, byte-identical to the source machine — reverting the
+    // installer's day-one env.PATH fix and propagating one host's PATH
+    // snapshot to every machine/teammate. This is the recurrence mechanism
+    // behind the recurring "qmd: command not found" reports. Settings are
+    // machine-local (PATH snapshot, model prefs) and must never round-trip
+    // in EITHER direction — the pull planner consults this same filter, so
+    // an existing vault copy is also never applied locally.
+    const shouldSync = createIgnoreFilter(hqRoot);
+    expect(shouldSync(path.join(hqRoot, ".claude/settings.json"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, ".claude/settings.local.json"))).toBe(false);
+    // Nested .claude/ inside a company stays local too — same anchor shape
+    // as the state/audit rules above.
+    expect(
+      shouldSync(path.join(hqRoot, "companies/indigo/.claude/settings.json")),
+    ).toBe(false);
+    // Siblings still sync — the rule must not broaden past settings files.
+    expect(shouldSync(path.join(hqRoot, ".claude/skills/foo/SKILL.md"))).toBe(true);
+    expect(shouldSync(path.join(hqRoot, ".claude/hooks/foo.sh"))).toBe(true);
+    expect(shouldSync(path.join(hqRoot, ".claude/CLAUDE.md"))).toBe(true);
+  });
+
   it("permissive mode: .hq/ directory is per-host state, never synced (Bug #1/#6/#8)", () => {
     // Bug catalog: `.hq/install-manifest.json`, `.hq/machine-id`, and
     // `.hq/machine.json` are per-host source-of-truth files. The original
@@ -289,7 +312,10 @@ describe("createIgnoreFilter", () => {
     expect(shouldSync(path.join(hqRoot, ".claude"), true)).toBe(true);
     // Files inside still resolve correctly without the hint.
     expect(shouldSync(path.join(hqRoot, "companies/indigo/knowledge/x.md"))).toBe(true);
-    expect(shouldSync(path.join(hqRoot, ".claude/settings.json"))).toBe(true);
+    expect(shouldSync(path.join(hqRoot, ".claude/skills/foo/SKILL.md"))).toBe(true);
+    // Machine-local settings stay excluded even inside an allowlisted
+    // subtree — exclusion layers subtract on top of the allowlist.
+    expect(shouldSync(path.join(hqRoot, ".claude/settings.json"))).toBe(false);
     // Non-allowlisted siblings stay excluded — privacy guarantee intact.
     expect(shouldSync(path.join(hqRoot, "companies/indigo/data"), true)).toBe(false);
     expect(shouldSync(path.join(hqRoot, "companies/indigo/workers"), true)).toBe(false);

package/src/ignore.ts

@@ -119,6 +119,17 @@ export const DEFAULT_IGNORES = [
   "**/.claude/state/",
   "**/.claude/audit/",
 
+  // Claude Code settings are machine-local: `env.PATH` is a snapshot of the
+  // host's shell PATH taken at install time, and model/permission prefs are
+  // per-operator-per-machine. Syncing them propagates one machine's PATH
+  // onto every other machine (and overwrites the installer's day-one PATH
+  // fix ~40s after a fresh install pulls existing cloud state) — the root
+  // cause of the recurring "qmd: command not found" reports (see
+  // workspace/e2e-mac/reports/20260701-qmd-path in HQ). Never round-trip
+  // them, in either direction.
+  "**/.claude/settings.json",
+  "**/.claude/settings.local.json",
+
   // HQ repos directory (managed separately, not synced). Root-anchored so
   // only hqRoot/repos/ is excluded; bare `repos/` would match any nested
   // directory named repos (for example companies/<co>/knowledge/repos/),

package/src/journal.test.ts

@@ -25,6 +25,7 @@ import {
   gcTombstones,
   generatePullId,
   TOMBSTONE_TTL_MS,
+  MAX_PULLS_PER_COMPANY,
   PERSONAL_VAULT_JOURNAL_SLUG,
   migratePersonalVaultJournal,
   listJournals,
@@ -463,6 +464,49 @@ describe("journal", () => {
         "2026-05-20T00:00:00.000Z",
       );
     });
+
+    it("bounds pulls per company and preserves newest lastPullRecord", () => {
+      const j: SyncJournal = {
+        version: "2",
+        lastSync: "",
+        files: {},
+        pulls: [],
+      };
+      const completedAt = (n: number) =>
+        `2026-05-20T00:00:${String(n).padStart(2, "0")}.000Z`;
+
+      for (let i = 0; i < MAX_PULLS_PER_COMPANY + 5; i++) {
+        appendPullRecord(
+          j,
+          pull({
+            pullId: `pull-a-${String(i).padStart(2, "0")}`,
+            companyUid: "cmp_a",
+            completedAt: completedAt(i),
+          }),
+        );
+      }
+      for (let i = 0; i < 3; i++) {
+        appendPullRecord(
+          j,
+          pull({
+            pullId: `pull-b-${i}`,
+            companyUid: "cmp_b",
+            completedAt: completedAt(i),
+          }),
+        );
+      }
+
+      const pulls = j.pulls ?? [];
+      const companyA = pulls.filter((p) => p.companyUid === "cmp_a");
+      const companyB = pulls.filter((p) => p.companyUid === "cmp_b");
+      expect(companyA).toHaveLength(MAX_PULLS_PER_COMPANY);
+      expect(companyB).toHaveLength(3);
+      expect(companyA[0].pullId).toBe("pull-a-05");
+      expect(companyA.at(-1)?.pullId).toBe("pull-a-54");
+      expect(companyA.some((p) => p.pullId === "pull-a-00")).toBe(false);
+      expect(lastPullRecord(j, "cmp_a")?.pullId).toBe("pull-a-54");
+      expect(lastPullRecord(j, "cmp_b")?.pullId).toBe("pull-b-2");
+    });
   });
 
   describe("tombstoneEntry + isTombstone", () => {

package/src/journal.ts

@@ -26,6 +26,13 @@ export const TOMBSTONE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 /** Current journal schema version written by all v2-aware writers. */
 export const JOURNAL_VERSION_CURRENT = "2" as const;
 
+/**
+ * Retain bounded pull history per company. Scope-shrink logic only needs the
+ * newest record, but a small tail keeps diagnostics useful without letting
+ * long-running sync loops grow journals forever.
+ */
+export const MAX_PULLS_PER_COMPANY = 50;
+
 const JOURNAL_FILE_PREFIX = "sync-journal.";
 const JOURNAL_FILE_SUFFIX = ".json";
 const JOURNAL_LAST_GOOD_SUFFIX = ".last-good";
@@ -517,13 +524,41 @@ export function lastPullRecord(
   return best;
 }
 
-/** Append a `PullRecord` (mutates `journal.pulls`). */
+function trimPullRecords(journal: SyncJournal): void {
+  const pulls = journal.pulls;
+  if (!pulls || pulls.length === 0) return;
+
+  const byCompany = new Map<string, Array<{ record: PullRecord; index: number }>>();
+  pulls.forEach((record, index) => {
+    const entries = byCompany.get(record.companyUid);
+    if (entries) entries.push({ record, index });
+    else byCompany.set(record.companyUid, [{ record, index }]);
+  });
+
+  const keep = new Set<number>();
+  for (const entries of byCompany.values()) {
+    entries
+      .sort((a, b) => {
+        const byCompletedAt = b.record.completedAt.localeCompare(
+          a.record.completedAt,
+        );
+        return byCompletedAt === 0 ? b.index - a.index : byCompletedAt;
+      })
+      .slice(0, MAX_PULLS_PER_COMPANY)
+      .forEach((entry) => keep.add(entry.index));
+  }
+
+  journal.pulls = pulls.filter((_, index) => keep.has(index));
+}
+
+/** Append a `PullRecord` (mutates `journal.pulls`) and cap retained history. */
 export function appendPullRecord(
   journal: SyncJournal,
   record: PullRecord,
 ): void {
   migrateToV2(journal);
   journal.pulls!.push(record);
+  trimPullRecords(journal);
 }
 
 /**

package/src/operation-lock.test.ts

@@ -13,8 +13,11 @@ import {
   withOperationLock,
   withOperationLockSync,
   lockPathFor,
+  rethrowLockCreateError,
   OperationLockedError,
+  OperationLockUnwritableError,
   OPERATION_LOCKED_EXIT,
+  OPERATION_LOCK_UNWRITABLE_EXIT,
   DEFAULT_LOCK_POLL_MS,
   type LockInfo,
 } from "./operation-lock.js";
@@ -101,6 +104,96 @@ describe("operation-lock", () => {
     expect(fs.existsSync(h.path)).toBe(false);
   });
 
+  // Regression (HQ-CLI-2): when the lock's state dir is not writable, acquiring
+  // must fail with an actionable OperationLockUnwritableError, NOT a raw
+  // `EPERM: operation not permitted, open` (macOS) / `EACCES` (Linux) crash.
+  describe("unwritable lock dir (HQ-CLI-2)", () => {
+    // The classification decision (which fs error codes mean "unwritable lock"
+    // vs. a genuinely different fault) is verified directly against the exported
+    // `rethrowLockCreateError` helper. ESM module namespaces can't be spied, so
+    // we can't mock `fs.openSync`; testing the classifier is both deterministic
+    // (uid/OS-independent) and a tighter unit of the actual decision.
+    const permErr = (code: string, msg: string): NodeJS.ErrnoException =>
+      Object.assign(new Error(`${code}: ${msg}, open`), { code, syscall: "open" });
+
+    it.each(["EPERM", "EACCES", "EROFS"])(
+      "classifies %s as OperationLockUnwritableError with actionable guidance",
+      (code) => {
+        const dir = path.join(stateDir, "locks");
+        let thrown: unknown;
+        try {
+          rethrowLockCreateError(permErr(code, "not permitted"), dir);
+        } catch (e) {
+          thrown = e;
+        }
+        expect(thrown).toBeInstanceOf(OperationLockUnwritableError);
+        const err = thrown as OperationLockUnwritableError;
+        expect(err.lockDir).toBe(dir);
+        expect(err.cause.code).toBe(code);
+        // Actionable: names the recovery levers so the user can self-serve.
+        expect(err.message).toContain("HQ_DISABLE_OP_LOCK=1");
+        expect(err.message).toContain("HQ_STATE_DIR");
+      },
+    );
+
+    it("POSITIVE CONTROL: a NON-permission fs error propagates unchanged (not masked)", () => {
+      // A disk-full error is a genuine, different fault — it must NOT be
+      // reclassified as an unwritable-lock error.
+      const dir = path.join(stateDir, "locks");
+      let thrown: unknown;
+      try {
+        rethrowLockCreateError(permErr("ENOSPC", "no space left on device"), dir);
+      } catch (e) {
+        thrown = e;
+      }
+      expect(thrown).not.toBeInstanceOf(OperationLockUnwritableError);
+      expect((thrown as NodeJS.ErrnoException).code).toBe("ENOSPC");
+    });
+
+    it("real unwritable locks dir → OperationLockUnwritableError, distinct exit (skipped as root)", () => {
+      // End-to-end proof through the real acquire path: a locks dir with no write
+      // bit makes the temp-file create fail (EACCES on Linux / EPERM on macOS),
+      // and acquire must surface the typed error rather than crash. CI runners
+      // run non-root, so this exercises the full path there.
+      if (typeof process.getuid === "function" && process.getuid() === 0) {
+        // root bypasses DAC permission bits, so a chmod-based unwritable dir
+        // cannot be exercised — the classifier cases above cover the logic.
+        return;
+      }
+      const locksDir = path.join(stateDir, "locks");
+      fs.mkdirSync(locksDir, { recursive: true });
+      fs.chmodSync(locksDir, 0o500); // r-x: cannot create files inside
+      try {
+        expect(() => acquireOperationLock(rootA, "reindex", { wait: false })).toThrowError(
+          OperationLockUnwritableError,
+        );
+      } finally {
+        fs.chmodSync(locksDir, 0o700); // restore so afterEach cleanup can rm it
+      }
+    });
+
+    it("async acquire also surfaces the typed error on an unwritable locks dir (skipped as root)", async () => {
+      if (typeof process.getuid === "function" && process.getuid() === 0) {
+        return;
+      }
+      const locksDir = path.join(stateDir, "locks");
+      fs.mkdirSync(locksDir, { recursive: true });
+      fs.chmodSync(locksDir, 0o500);
+      try {
+        await expect(
+          acquireOperationLockAsync(rootB, "reindex", { wait: false }),
+        ).rejects.toBeInstanceOf(OperationLockUnwritableError);
+      } finally {
+        fs.chmodSync(locksDir, 0o700);
+      }
+    });
+
+    it("exposes a distinct exit code from the busy case", () => {
+      expect(OPERATION_LOCK_UNWRITABLE_EXIT).not.toBe(OPERATION_LOCKED_EXIT);
+      expect(OPERATION_LOCK_UNWRITABLE_EXIT).toBe(18);
+    });
+  });
+
   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