@indigoai-us/hq-cloud 6.2.7 → 6.3.1

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

@@ -30,6 +30,7 @@ import type {
 } from "./sync-runner.js";
 import { FakeClock } from "../watcher.js";
 import { PERSONAL_VAULT_JOURNAL_SLUG } from "../journal.js";
+import { lockPathFor, OPERATION_LOCKED_EXIT } from "../operation-lock.js";
 import type { SyncResult, SyncOptions } from "../cli/sync.js";
 import type { ShareResult, ShareOptions } from "../cli/share.js";
 import type {
@@ -3566,3 +3567,325 @@ describe("readPinnedPrefixes", () => {
     expect(readPinnedPrefixes(root, "acme")).toEqual([]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Operation lock — one-shot sync takes it; the watch runner is exempt.
+// ---------------------------------------------------------------------------
+describe("runRunnerWithLoop — operation lock", () => {
+  const HQ = "/tmp/hq-oplock";
+
+  /** Write a live-holder lock (pid 1) for the HQ root into the test state dir. */
+  function writeLiveHolder(command: string): string {
+    const p = lockPathFor(HQ);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(
+      p,
+      JSON.stringify({ pid: 1, command, startedAt: new Date(0).toISOString(), hqRoot: HQ }),
+    );
+    return p;
+  }
+
+  it("one-shot sync refuses fast (exit 17) when another op holds the root", async () => {
+    const lp = writeLiveHolder("rescue");
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+
+    // No --watch → one-shot. Refusal short-circuits BEFORE runRunner (so no
+    // network / auth is touched).
+    const code = await runRunnerWithLoop(["--companies", "--hq-root", HQ]);
+
+    spy.mockRestore();
+    expect(code).toBe(OPERATION_LOCKED_EXIT);
+    expect(errs.join("")).toContain("rescue"); // names the holder
+    // The holder's lock is left intact — we refused, we didn't take it over.
+    const held = JSON.parse(fs.readFileSync(lp, "utf8"));
+    expect(held.pid).toBe(1);
+    expect(held.command).toBe("rescue");
+  });
+
+  it("the watch runner is EXEMPT — runs despite a held lock and never takes it", async () => {
+    const lp = writeLiveHolder("sync");
+    const watcher = makeWatcherStub();
+    let triggerShutdown = () => {};
+    const runPass = vi.fn().mockResolvedValue(0);
+
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", HQ],
+      {
+        runPass,
+        clock: new FakeClock(),
+        createWatcher: () => watcher,
+        sleep: () => new Promise<void>(() => {}),
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+      },
+    );
+
+    await Promise.resolve();
+    await Promise.resolve();
+    // It started and ran a pass even though the lock is held → not blocked.
+    expect(watcher.started).toBe(true);
+    expect(runPass).toHaveBeenCalled();
+
+    triggerShutdown();
+    await loop;
+
+    // The pre-existing holder lock is untouched → the watcher never took it.
+    const held = JSON.parse(fs.readFileSync(lp, "utf8"));
+    expect(held.pid).toBe(1);
+    expect(held.command).toBe("sync");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Phase 3 — event-driven publish + pull wiring (US-017/018/019)
+// ---------------------------------------------------------------------------
+//
+// Exercises the rollout-gated bring-up through the `startEventSync` /
+// `getIdTokenClaims` seams: gate-off is byte-identical to today (the seam is
+// never consulted), gate-on passes the wiring the right identity + sync
+// bridge, and the publish leg fires only AFTER a SUCCESSFUL targeted push
+// pass (events must never announce bytes that are not in S3 yet).
+
+interface BatchWatcherStub extends WatcherSurface {
+  emit(changedRelPath?: string, batch?: { paths: Map<string, string> }): void;
+  disposed: boolean;
+}
+
+function makeBatchWatcherStub(): BatchWatcherStub {
+  const listeners = new Set<
+    (p?: string, b?: { paths: Map<string, string> }) => void
+  >();
+  return {
+    disposed: false,
+    onChange(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    start() {},
+    stop() {},
+    dispose() {
+      this.disposed = true;
+      listeners.clear();
+    },
+    emit(changedRelPath?: string, batch?: { paths: Map<string, string> }) {
+      for (const l of [...listeners]) l(changedRelPath, batch);
+    },
+  };
+}
+
+describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", () => {
+  const ENROLLED_CLAIMS = { email: "hassaan@getindigo.ai" };
+  const UNENROLLED_CLAIMS = { email: "someone@getindigo.ai" };
+
+  function runLoop(opts: {
+    claims: { email?: string } | null;
+    startEventSync?: ReturnType<typeof vi.fn>;
+    watcher?: BatchWatcherStub;
+    runPass?: ReturnType<typeof vi.fn>;
+  }) {
+    const watcher = opts.watcher ?? makeBatchWatcherStub();
+    const runPass = opts.runPass ?? vi.fn().mockResolvedValue(0);
+    const clock = new FakeClock();
+    let triggerShutdown = () => {};
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"],
+      {
+        runPass,
+        clock,
+        createWatcher: () => watcher,
+        sleep: () => new Promise<void>(() => {}),
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+        getIdTokenClaims: () => opts.claims as never,
+        getAccessToken: async () => "jwt-test",
+        startEventSync: (opts.startEventSync ??
+          vi.fn().mockResolvedValue(null)) as never,
+      },
+    );
+    return { loop, watcher, runPass, clock, shutdown: () => triggerShutdown() };
+  }
+
+  async function microtasks(n = 6) {
+    for (let i = 0; i < n; i++) await Promise.resolve();
+  }
+
+  it("gate OFF (unenrolled email): the event-sync seam is never consulted", async () => {
+    const startEventSync = vi.fn().mockResolvedValue(null);
+    const { loop, shutdown } = runLoop({
+      claims: UNENROLLED_CLAIMS,
+      startEventSync,
+    });
+    await microtasks();
+    shutdown();
+    await loop;
+    expect(startEventSync).not.toHaveBeenCalled();
+  });
+
+  it("gate OFF (no cached claims): the event-sync seam is never consulted", async () => {
+    const startEventSync = vi.fn().mockResolvedValue(null);
+    const { loop, shutdown } = runLoop({ claims: null, startEventSync });
+    await microtasks();
+    shutdown();
+    await loop;
+    expect(startEventSync).not.toHaveBeenCalled();
+  });
+
+  it("gate ON (enrolled email): wiring receives root, api url, auth + a sync bridge", async () => {
+    const startEventSync = vi.fn().mockResolvedValue(null);
+    const { loop, shutdown } = runLoop({
+      claims: ENROLLED_CLAIMS,
+      startEventSync,
+    });
+    await microtasks();
+    shutdown();
+    await loop;
+    expect(startEventSync).toHaveBeenCalledTimes(1);
+    const arg = startEventSync.mock.calls[0][0];
+    expect(arg.hqRoot).toBe("/tmp/hq");
+    expect(arg.apiUrl).toContain("https://");
+    expect(typeof arg.deviceId).toBe("string");
+    expect(arg.deviceId.length).toBeGreaterThan(0);
+    expect(typeof arg.resolveTenantId).toBe("function");
+    expect(typeof arg.syncFn).toBe("function");
+  });
+
+  it("publishes the batch ONLY after a successful targeted push pass", async () => {
+    const publishBatch = vi.fn();
+    const startEventSync = vi.fn().mockResolvedValue({
+      publishBatch,
+      receiver: { start: async () => {}, dispose: async () => {}, connected: true },
+      ownDeviceId: "dev-test",
+      dispose: vi.fn().mockResolvedValue(undefined),
+    });
+    const runPass = vi.fn().mockResolvedValue(0);
+    const { loop, watcher, clock, shutdown } = runLoop({
+      claims: ENROLLED_CLAIMS,
+      startEventSync,
+      runPass,
+    });
+    await microtasks(); // initial poll pass + async event-sync bring-up
+    runPass.mockClear();
+
+    const batch = {
+      paths: new Map([["/tmp/hq/companies/indigo/a.md", "companies/indigo/a.md"]]),
+    };
+    watcher.emit("companies/indigo/a.md", batch);
+    clock.advance(0);
+    await microtasks();
+
+    // Targeted push ran and succeeded → batch published.
+    expect(runPass).toHaveBeenCalled();
+    expect(publishBatch).toHaveBeenCalledTimes(1);
+    expect(publishBatch.mock.calls[0][0]).toBe(batch);
+
+    shutdown();
+    await loop;
+  });
+
+  it("publishes NOTHING when the targeted push pass fails", async () => {
+    const publishBatch = vi.fn();
+    const startEventSync = vi.fn().mockResolvedValue({
+      publishBatch,
+      receiver: { start: async () => {}, dispose: async () => {}, connected: true },
+      ownDeviceId: "dev-test",
+      dispose: vi.fn().mockResolvedValue(undefined),
+    });
+    // Initial poll pass succeeds; the targeted pass fails.
+    const runPass = vi
+      .fn()
+      .mockResolvedValueOnce(0)
+      .mockResolvedValue(1);
+    const { loop, watcher, clock, shutdown } = runLoop({
+      claims: ENROLLED_CLAIMS,
+      startEventSync,
+      runPass,
+    });
+    await microtasks();
+
+    watcher.emit(
+      "companies/indigo/a.md",
+      { paths: new Map([["/tmp/hq/companies/indigo/a.md", "companies/indigo/a.md"]]) },
+    );
+    clock.advance(0);
+    await microtasks();
+
+    expect(publishBatch).not.toHaveBeenCalled();
+    shutdown();
+    await loop;
+  });
+
+  it("falls back to a synthesized single-path batch when the watcher emits a bare path", async () => {
+    const publishBatch = vi.fn();
+    const startEventSync = vi.fn().mockResolvedValue({
+      publishBatch,
+      receiver: { start: async () => {}, dispose: async () => {}, connected: true },
+      ownDeviceId: "dev-test",
+      dispose: vi.fn().mockResolvedValue(undefined),
+    });
+    const { loop, watcher, clock, shutdown } = runLoop({
+      claims: ENROLLED_CLAIMS,
+      startEventSync,
+    });
+    await microtasks();
+
+    watcher.emit("companies/indigo/b.md"); // no batch
+    clock.advance(0);
+    await microtasks();
+
+    expect(publishBatch).toHaveBeenCalledTimes(1);
+    const synthesized = publishBatch.mock.calls[0][0] as {
+      paths: Map<string, string>;
+    };
+    expect([...synthesized.paths.values()]).toEqual(["companies/indigo/b.md"]);
+
+    shutdown();
+    await loop;
+  });
+
+  it("disposes the event-sync handles on shutdown", async () => {
+    const dispose = vi.fn().mockResolvedValue(undefined);
+    const startEventSync = vi.fn().mockResolvedValue({
+      publishBatch: vi.fn(),
+      receiver: { start: async () => {}, dispose: async () => {}, connected: true },
+      ownDeviceId: "dev-test",
+      dispose,
+    });
+    const { loop, shutdown } = runLoop({
+      claims: ENROLLED_CLAIMS,
+      startEventSync,
+    });
+    await microtasks();
+    shutdown();
+    await loop;
+    expect(dispose).toHaveBeenCalled();
+  });
+
+  it("env override HQ_SYNC_EVENT_SYNC=0 keeps the seam dormant for the enrolled account", async () => {
+    const prev = process.env.HQ_SYNC_EVENT_SYNC;
+    process.env.HQ_SYNC_EVENT_SYNC = "0";
+    try {
+      const startEventSync = vi.fn().mockResolvedValue(null);
+      const { loop, shutdown } = runLoop({
+        claims: ENROLLED_CLAIMS,
+        startEventSync,
+      });
+      await microtasks();
+      shutdown();
+      await loop;
+      expect(startEventSync).not.toHaveBeenCalled();
+    } finally {
+      if (prev === undefined) delete process.env.HQ_SYNC_EVENT_SYNC;
+      else process.env.HQ_SYNC_EVENT_SYNC = prev;
+    }
+  });
+});

package/src/bin/sync-runner.ts

@@ -100,6 +100,11 @@ import { collectAndSendTelemetry } from "../telemetry.js";
 import { collectAndSendSkillTelemetry } from "../skill-telemetry.js";
 import { reindexAfterSync } from "../qmd-reindex.js";
 import { pruneConflictIndex } from "../lib/conflict-index.js";
+import {
+  withOperationLock,
+  OperationLockedError,
+  OPERATION_LOCKED_EXIT,
+} from "../operation-lock.js";
 import { describeError } from "../lib/describe-error.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
 import {
@@ -107,12 +112,19 @@ import {
   WatchPushDriver,
   systemClock,
   type Clock,
+  type TreeChangeBatch,
 } from "../watcher.js";
 import {
   NoopPushReceiver,
   type PushReceiver,
   type SyncEngineFn,
 } from "../sync/push-receiver.js";
+import {
+  resolveEventSync,
+  startEventSync as defaultStartEventSync,
+  type EventSyncHandles,
+  type StartEventSyncOptions,
+} from "../sync/event-sync.js";
 import {
   PERSONAL_VAULT_JOURNAL_SLUG,
   migratePersonalVaultJournal,
@@ -1824,6 +1836,27 @@ export interface RunnerLoopDeps {
     syncFn: SyncEngineFn;
     hqRoot: string;
   }) => PushReceiver;
+  /**
+   * Phase 3 (US-017/US-018/US-019): factory for the event-driven publish +
+   * pull wiring, consulted only when `--event-push` is on AND the rollout
+   * gate ({@link resolveEventSync}) passes for the signed-in account.
+   * Defaults to the real {@link defaultStartEventSync}. Tests inject a stub
+   * to assert gate behavior without network/AWS.
+   */
+  startEventSync?: (
+    opts: StartEventSyncOptions,
+  ) => Promise<EventSyncHandles | null>;
+  /**
+   * Identity-claims source for the Phase 3 rollout gate (the loop has no
+   * RunnerDeps; mirror of RunnerDeps.getIdTokenClaims). Defaults to reading
+   * the cached Cognito idToken.
+   */
+  getIdTokenClaims?: () => IdTokenClaims | null;
+  /**
+   * Access-token source for the Phase 3 vault API calls (publish transport +
+   * subscribe). Defaults to {@link getValidAccessToken} non-interactive.
+   */
+  getAccessToken?: () => Promise<string>;
 }
 
 /**
@@ -1838,7 +1871,9 @@ export interface RunnerLoopDeps {
  * relative path so the loop targets just that company.
  */
 export interface WatcherSurface {
-  onChange(listener: (changedRelPath?: string) => void): () => void;
+  onChange(
+    listener: (changedRelPath?: string, batch?: TreeChangeBatch) => void,
+  ): () => void;
   start(): void;
   stop(): void;
   dispose(): void;
@@ -1920,7 +1955,23 @@ export async function runRunnerWithLoop(
   deps: RunnerLoopDeps = {},
 ): Promise<number> {
   if (!argv.includes("--watch")) {
-    return runRunner(argv);
+    // One-shot cloud sync — take the per-root operation lock so it is mutually
+    // exclusive with rescue/reindex. The `--watch` path below is the push
+    // watcher and is intentionally EXEMPT (it neither takes nor is blocked by
+    // the lock; its in-process targeted passes call `runRunner` directly, not
+    // through here). If args don't parse, fall through to `runRunner` so it
+    // surfaces the parse error rather than us masking it with a lock failure.
+    const parsed = parseArgs(argv);
+    if ("error" in parsed) return runRunner(argv);
+    try {
+      return await withOperationLock(parsed.hqRoot, "sync", () => runRunner(argv));
+    } catch (err) {
+      if (err instanceof OperationLockedError) {
+        process.stderr.write(err.message + "\n");
+        return OPERATION_LOCKED_EXIT;
+      }
+      throw err;
+    }
   }
   const sleep =
     deps.sleep ??
@@ -1978,12 +2029,17 @@ export async function runRunnerWithLoop(
   let driver: WatchPushDriver | null = null;
   let detachSignal: (() => void) | null = null;
   let lastChangedRel: string | null = null;
+  let lastBatch: TreeChangeBatch | null = null;
   // ---- pull-on-event receiver (Phase 2, US-009) ------------------------
   // Started after the watcher, disposed before the watcher (mirror of the
   // PushTransport ordering). Dormant by default: the default factory returns
   // a NoopPushReceiver, and even a real receiver stays dormant unless the
   // per-tenant feature flag is on AND a queue URL is provisioned server-side.
   let receiver: PushReceiver | null = null;
+  // ---- event-driven publish + pull (Phase 3, US-017/018/019) ------------
+  // Brought up asynchronously after the watcher when the rollout gate
+  // passes; null until ready (and stays null on startup failure → poll-only).
+  let eventSync: EventSyncHandles | null = null;
 
   if (eventPush) {
     const clock = deps.clock ?? systemClock;
@@ -2011,12 +2067,28 @@ export async function runRunnerWithLoop(
       push: async () => {
         if (stopped) return;
         const rel = lastChangedRel;
+        // Snapshot the settled batch BEFORE the await: a change landing
+        // mid-pass overwrites lastBatch for the NEXT pass, and this pass
+        // must only announce what it actually pushed.
+        const batchForPublish = lastBatch;
+        lastBatch = null;
         const route = rel
           ? routeChangeToTarget(rel)
           : { kind: "personal" as const };
         if (!route) return;
         const targetedArgv = buildTargetedPushArgv(route, passArgv);
-        await runGuarded(() => runPass(targetedArgv));
+        const result = await runGuarded(() => runPass(targetedArgv));
+        // Phase 3 (US-017): publish PushEvents only AFTER the targeted push
+        // pass succeeded — an event must never announce bytes that are not
+        // in S3 yet. A skipped pass (guard held) or a failed pass publishes
+        // nothing; the cadence poll covers the miss. Fall back to a
+        // single-path batch when the watcher emitted a bare path signal.
+        if (result === 0 && eventSync) {
+          const batch: TreeChangeBatch | null =
+            batchForPublish ??
+            (rel ? { paths: new Map([[path.join(hqRoot, rel), rel]]) } : null);
+          if (batch) eventSync.publishBatch(batch);
+        }
       },
     });
 
@@ -2025,9 +2097,10 @@ export async function runRunnerWithLoop(
     // still serialized behind any in-flight pass. A path-aware watcher passes
     // the changed relative path so the push targets just its owning company;
     // the bare-signal TreeWatcher leaves it null → personal-vault route.
-    watcher.onChange((changedRelPath) => {
+    watcher.onChange((changedRelPath, batch) => {
       if (stopped) return;
       lastChangedRel = changedRelPath ?? null;
+      lastBatch = batch ?? null;
       driver?.notifyChange();
     });
     watcher.start();
@@ -2056,6 +2129,60 @@ export async function runRunnerWithLoop(
     // start also keeps the poll loop's microtask timing identical to the
     // pre-US-009 wiring.)
     void Promise.resolve(receiver.start()).catch(() => undefined);
+
+    // ---- Phase 3: event-driven publish + pull (US-017/018/019) ----------
+    // Gated to enrolled accounts (resolveEventSync — exact-email allowlist +
+    // HQ_SYNC_EVENT_SYNC override). Brought up asynchronously so a slow
+    // subscribe/vend can't delay the first poll pass; until (and unless) the
+    // handles resolve, behavior is byte-identical to the gate-off path.
+    const getClaims = deps.getIdTokenClaims ?? defaultGetIdTokenClaims;
+    const email = getClaims()?.email;
+    if (resolveEventSync(email, process.env.HQ_SYNC_EVENT_SYNC)) {
+      const getAccessToken =
+        deps.getAccessToken ??
+        (() => getValidAccessToken(DEFAULT_COGNITO, { interactive: false }));
+      const startES = deps.startEventSync ?? defaultStartEventSync;
+      // Entirely async + caught: NOTHING in the Phase 3 bring-up (device-id
+      // persistence, tenant resolution, subscribe) may crash or delay the
+      // daemon — any failure degrades to poll-only.
+      void (async () => {
+        const handles = await startES({
+          hqRoot,
+          apiUrl: DEFAULT_VAULT_API_URL,
+          authToken: getAccessToken,
+          deviceId: getOrCreateMachineId(hqRoot),
+          // The server rejects publishes whose originTenantId mismatches the
+          // JWT principal, so resolve the SAME canonical person uid the vault
+          // API derives from this token.
+          resolveTenantId: async () => {
+            const client = new VaultClient({
+              apiUrl: DEFAULT_VAULT_API_URL,
+              authToken: getAccessToken,
+              region: DEFAULT_COGNITO.region,
+            });
+            const persons = await client.entity.listByType("person");
+            const pick = pickCanonicalPersonEntity(persons);
+            if (!pick?.uid) {
+              throw new Error("no canonical person entity for this account");
+            }
+            return pick.uid;
+          },
+          syncFn: receiverSyncFn,
+          log: (m) => process.stderr.write(`${m}\n`),
+        });
+        if (!handles) return;
+        if (stopped) {
+          // Shutdown raced the async bring-up — tear straight down.
+          void handles.dispose();
+          return;
+        }
+        eventSync = handles;
+      })().catch((err) => {
+        process.stderr.write(
+          `event-sync: wiring failed, continuing poll-only: ${describeError(err)}\n`,
+        );
+      });
+    }
   }
 
   // ---- clean shutdown --------------------------------------------------
@@ -2080,6 +2207,14 @@ export async function runRunnerWithLoop(
     } catch {
       /* ignore */
     }
+    // Phase 3 wiring (publish transport + live receiver) — torn down with
+    // the same fire-and-forget posture as the Phase 2 receiver above.
+    try {
+      void eventSync?.dispose();
+    } catch {
+      /* ignore */
+    }
+    eventSync = null;
     try {
       driver?.dispose();
     } catch {

package/src/cli/reindex.test.ts

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

package/src/cli/reindex.ts

@@ -17,10 +17,24 @@
 import { spawnSync } from "child_process";
 import * as fs from "fs";
 import * as path from "path";
+import {
+  acquireOperationLock,
+  OperationLockedError,
+  OPERATION_LOCKED_EXIT,
+  type LockHandle,
+} from "../operation-lock.js";
 
 export interface ReindexOptions {
   /** HQ root to operate on. Defaults to process.cwd(). */
   repoRoot?: string;
+  /**
+   * Skip the per-root operation lock. Internal callers (`sync()` / `rescue()`)
+   * already hold the lock for this root and pass `true` so reindex doesn't try
+   * to re-acquire it and refuse against their own live PID. Standalone callers
+   * (`hq reindex`, the reindex hook) leave it falsy so reindex is mutually
+   * exclusive with a running sync/rescue.
+   */
+  skipLock?: boolean;
 }
 
 export interface ReindexResult {
@@ -129,6 +143,25 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
   }
   const root = path.resolve(rawRoot);
 
+  // Acquire the per-root operation lock unless an internal caller (sync/rescue,
+  // which already hold it) opted out. A live holder → refuse fast with the
+  // holder's command + PID. The whole body runs inside the try so the lock is
+  // released on every exit path (the process-level signal/exit hooks are the
+  // crash backstop).
+  let opLock: LockHandle | null = null;
+  if (!opts.skipLock) {
+    try {
+      opLock = acquireOperationLock(root, "reindex");
+    } catch (err) {
+      if (err instanceof OperationLockedError) {
+        warn(err.message);
+        return { status: OPERATION_LOCKED_EXIT };
+      }
+      throw err;
+    }
+  }
+  try {
+
   fs.mkdirSync(path.join(root, ".claude", "skills"), { recursive: true });
 
   // --- Build (namespace, src_rel) pairs -------------------------------------
@@ -363,4 +396,7 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
   }
 
   return { status: 0 };
+  } finally {
+    opLock?.release();
+  }
 }