@indigoai-us/hq-cli 5.54.1 → 5.55.0

package/dist/commands/reindex.d.ts

@@ -9,6 +9,18 @@
  *
  * Keeps a hidden `master-sync` alias for one release so an updated CLI still
  * answers a not-yet-updated hook shim (and vice-versa) during rollout.
+ *
+ * Lock-wait policy: reindex shares one per-root operation lock with `sync` and
+ * `rescue`. By default acquisition waits UNBOUNDED for a live holder, which is
+ * what a human running `hq reindex` interactively wants. But when invoked from a
+ * Claude/Codex lifecycle hook (SessionStart / UserPromptSubmit / Stop /
+ * PostToolUse), waiting is exactly wrong: if a sync/rescue is mid-flight, the
+ * hook blocks the agent up to the host's per-hook timeout (the multi-minute
+ * "Claude won't load in the HQ folder" spinner). `--from-hook` makes the hook
+ * path refuse-fast (never wait); `--lock-timeout <sec>` bounds it explicitly.
+ * The bound is applied via the HQ_OP_LOCK_TIMEOUT env var that the hq-cloud
+ * operation lock honors, so it works even against an installed hq-cloud build
+ * that predates a typed lock-timeout option.
  */
 import { Command } from 'commander';
 export declare function registerReindexCommand(program: Command): void;

package/dist/commands/reindex.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9d81df7d-0153-5f51-9cfb-60f1409c6b94")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="91aee9b3-dd72-5f05-99a8-d23b37f5eabe")}catch(e){}}();
 import { reindex } from '@indigoai-us/hq-cloud';
 export function registerReindexCommand(program) {
     program
@@ -7,10 +7,32 @@ export function registerReindexCommand(program) {
         .alias('master-sync')
         .description('Surface namespaced skills, mirror the personal overlay into core/, and regenerate the workers registry')
         .option('--repo-root <path>', 'HQ root to operate on (defaults to the current directory)')
+        .option('--from-hook', 'Invoked from a Claude/Codex lifecycle hook: never wait on the per-root operation lock — if a sync/rescue holds it, skip this reindex instead of blocking the session (equivalent to --lock-timeout 0)')
+        .option('--lock-timeout <seconds>', 'Bound the wait for the per-root operation lock (seconds). 0 = refuse immediately; omitted = wait indefinitely (the interactive default). --from-hook implies 0; an explicit --lock-timeout wins.')
         .action((opts) => {
+        // Resolve the lock-wait bound. An explicit --lock-timeout wins; otherwise
+        // --from-hook forces 0 (refuse-fast) so a hook fired while a sync/rescue
+        // holds the shared per-root operation lock can never stall the agent.
+        let lockTimeoutSec;
+        if (opts.lockTimeout !== undefined) {
+            const parsed = Number(opts.lockTimeout);
+            if (Number.isFinite(parsed) && parsed >= 0)
+                lockTimeoutSec = parsed;
+        }
+        else if (opts.fromHook) {
+            lockTimeoutSec = 0;
+        }
+        // Apply via HQ_OP_LOCK_TIMEOUT — the env var the hq-cloud operation lock
+        // reads (acquireOperationLock → resolveWaitConfig). Going through the env
+        // (rather than a typed reindex() option) keeps this forward/backward
+        // compatible with any installed hq-cloud build. Never clobber a value the
+        // caller already set explicitly.
+        if (lockTimeoutSec !== undefined && process.env.HQ_OP_LOCK_TIMEOUT === undefined) {
+            process.env.HQ_OP_LOCK_TIMEOUT = String(lockTimeoutSec);
+        }
         const { status } = reindex({ repoRoot: opts.repoRoot });
         process.exit(status);
     });
 }
 //# sourceMappingURL=reindex.js.map
-//# debugId=9d81df7d-0153-5f51-9cfb-60f1409c6b94
+//# debugId=91aee9b3-dd72-5f05-99a8-d23b37f5eabe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.54.1",
+  "version": "5.55.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/reindex.test.ts

@@ -0,0 +1,94 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from "vitest";
+
+// Mock the hq-cloud reindex() so the command runs without touching the FS.
+vi.mock("@indigoai-us/hq-cloud", () => ({
+  reindex: vi.fn(() => ({ status: 0 })),
+}));
+
+import { Command } from "commander";
+import { reindex } from "@indigoai-us/hq-cloud";
+import { registerReindexCommand } from "./reindex.js";
+
+const reindexMock = reindex as unknown as MockInstance<typeof reindex>;
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+  program.configureOutput({
+    writeOut: () => undefined,
+    writeErr: () => undefined,
+  });
+  registerReindexCommand(program);
+  return program;
+}
+
+async function run(...args: string[]): Promise<void> {
+  // process.exit is spied to throw; swallow that so parseAsync resolves.
+  try {
+    await buildProgram().parseAsync(["node", "hq", "reindex", ...args]);
+  } catch (err) {
+    if (!(err instanceof Error) || !err.message.startsWith("__EXIT__:")) throw err;
+  }
+}
+
+let exitSpy: MockInstance<typeof process.exit>;
+let savedLockTimeout: string | undefined;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  savedLockTimeout = process.env.HQ_OP_LOCK_TIMEOUT;
+  delete process.env.HQ_OP_LOCK_TIMEOUT;
+  exitSpy = vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+    throw new Error(`__EXIT__:${code ?? 0}`);
+  }) as never);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  if (savedLockTimeout === undefined) delete process.env.HQ_OP_LOCK_TIMEOUT;
+  else process.env.HQ_OP_LOCK_TIMEOUT = savedLockTimeout;
+});
+
+describe("hq reindex lock-wait policy", () => {
+  it("--from-hook forces a no-wait lock acquisition (HQ_OP_LOCK_TIMEOUT=0)", async () => {
+    await run("--from-hook");
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBe("0");
+    expect(reindexMock).toHaveBeenCalledTimes(1);
+    expect(exitSpy).toHaveBeenCalledWith(0);
+  });
+
+  it("--lock-timeout <sec> sets an explicit bounded wait", async () => {
+    await run("--lock-timeout", "5");
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBe("5");
+  });
+
+  it("an explicit --lock-timeout wins over --from-hook", async () => {
+    await run("--from-hook", "--lock-timeout", "10");
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBe("10");
+  });
+
+  it("a plain interactive reindex leaves the wait unbounded (env unset)", async () => {
+    await run();
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBeUndefined();
+    expect(reindexMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("never clobbers an HQ_OP_LOCK_TIMEOUT the caller already set", async () => {
+    process.env.HQ_OP_LOCK_TIMEOUT = "42";
+    await run("--from-hook");
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBe("42");
+  });
+
+  it("ignores an invalid --lock-timeout (negative / non-numeric)", async () => {
+    await run("--lock-timeout", "nope");
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBeUndefined();
+  });
+});

package/src/commands/reindex.ts

@@ -9,6 +9,18 @@
  *
  * Keeps a hidden `master-sync` alias for one release so an updated CLI still
  * answers a not-yet-updated hook shim (and vice-versa) during rollout.
+ *
+ * Lock-wait policy: reindex shares one per-root operation lock with `sync` and
+ * `rescue`. By default acquisition waits UNBOUNDED for a live holder, which is
+ * what a human running `hq reindex` interactively wants. But when invoked from a
+ * Claude/Codex lifecycle hook (SessionStart / UserPromptSubmit / Stop /
+ * PostToolUse), waiting is exactly wrong: if a sync/rescue is mid-flight, the
+ * hook blocks the agent up to the host's per-hook timeout (the multi-minute
+ * "Claude won't load in the HQ folder" spinner). `--from-hook` makes the hook
+ * path refuse-fast (never wait); `--lock-timeout <sec>` bounds it explicitly.
+ * The bound is applied via the HQ_OP_LOCK_TIMEOUT env var that the hq-cloud
+ * operation lock honors, so it works even against an installed hq-cloud build
+ * that predates a typed lock-timeout option.
  */
 import { Command } from 'commander';
 import { reindex } from '@indigoai-us/hq-cloud';
@@ -21,7 +33,35 @@ export function registerReindexCommand(program: Command): void {
       'Surface namespaced skills, mirror the personal overlay into core/, and regenerate the workers registry'
     )
     .option('--repo-root <path>', 'HQ root to operate on (defaults to the current directory)')
-    .action((opts: { repoRoot?: string }) => {
+    .option(
+      '--from-hook',
+      'Invoked from a Claude/Codex lifecycle hook: never wait on the per-root operation lock — if a sync/rescue holds it, skip this reindex instead of blocking the session (equivalent to --lock-timeout 0)'
+    )
+    .option(
+      '--lock-timeout <seconds>',
+      'Bound the wait for the per-root operation lock (seconds). 0 = refuse immediately; omitted = wait indefinitely (the interactive default). --from-hook implies 0; an explicit --lock-timeout wins.'
+    )
+    .action((opts: { repoRoot?: string; fromHook?: boolean; lockTimeout?: string }) => {
+      // Resolve the lock-wait bound. An explicit --lock-timeout wins; otherwise
+      // --from-hook forces 0 (refuse-fast) so a hook fired while a sync/rescue
+      // holds the shared per-root operation lock can never stall the agent.
+      let lockTimeoutSec: number | undefined;
+      if (opts.lockTimeout !== undefined) {
+        const parsed = Number(opts.lockTimeout);
+        if (Number.isFinite(parsed) && parsed >= 0) lockTimeoutSec = parsed;
+      } else if (opts.fromHook) {
+        lockTimeoutSec = 0;
+      }
+
+      // Apply via HQ_OP_LOCK_TIMEOUT — the env var the hq-cloud operation lock
+      // reads (acquireOperationLock → resolveWaitConfig). Going through the env
+      // (rather than a typed reindex() option) keeps this forward/backward
+      // compatible with any installed hq-cloud build. Never clobber a value the
+      // caller already set explicitly.
+      if (lockTimeoutSec !== undefined && process.env.HQ_OP_LOCK_TIMEOUT === undefined) {
+        process.env.HQ_OP_LOCK_TIMEOUT = String(lockTimeoutSec);
+      }
+
       const { status } = reindex({ repoRoot: opts.repoRoot });
       process.exit(status);
     });