@indigoai-us/hq-cli 5.54.0 → 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/dist/utils/version-gate.js

@@ -28,7 +28,7 @@
  * to silence both check + gate).
  */
 
-!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]="0f613895-ad4a-5211-bf75-a2e843782c47")}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]="00fa2aa9-f5d1-57a7-92db-c441c6bef906")}catch(e){}}();
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import path from "node:path";
@@ -185,12 +185,24 @@ function enforceUpdateRequired(decision, deps = {}) {
         process.exit(75);
     }
     const runner = deps.runner ?? runUpdateCommand;
-    const result = prefix
+    // Resolve the concrete install argv once so the sudo fallback below can re-run
+    // the EXACT same command under elevation.
+    let primaryCmd;
+    let primaryArgs;
+    if (prefix) {
+        primaryCmd = "npm";
+        primaryArgs = buildPrefixedInstallArgv(prefix);
+    }
+    else {
+        const parts = (command ?? "").split(/\s+/).filter(Boolean);
+        primaryCmd = parts[0] ?? "";
+        primaryArgs = parts.slice(1);
+    }
+    let result = prefix
         ? (() => {
-            const args = buildPrefixedInstallArgv(prefix);
             console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
-            console.error(chalk.dim(`  Running: npm ${args.join(" ")}`));
-            return performUpdateCommand("npm", args, runner);
+            console.error(chalk.dim(`  Running: npm ${primaryArgs.join(" ")}`));
+            return performUpdateCommand("npm", primaryArgs, runner);
         })()
         : (() => {
             console.error(chalk.dim(`  Running: ${command}`));
@@ -198,6 +210,20 @@ function enforceUpdateRequired(decision, deps = {}) {
                 ? deps.performUpdateString(command)
                 : performUpdate(command, runner);
         })();
+    // A root-owned global install (e.g. a system `/usr` install where the CLI runs
+    // unprivileged — the outpost agent boxes) can't rewrite the prefix's bin dir,
+    // so the install above fails with EACCES (`rename /usr/bin/hq`). Retry ONCE
+    // under non-interactive sudo: `sudo -n` fails fast WITHOUT a password prompt
+    // when passwordless sudo isn't configured, so interactive installs (e.g.
+    // Homebrew on macOS, where the first attempt already succeeded anyway) fall
+    // through to the manual path unchanged, while headless boxes with passwordless
+    // sudo self-update cleanly.
+    if (!result.ok && primaryCmd) {
+        console.error(chalk.dim(`  Update failed unprivileged; retrying with: sudo -n ${primaryCmd} ${primaryArgs.join(" ")}`));
+        const sudoResult = performUpdateCommand("sudo", ["-n", primaryCmd, ...primaryArgs], runner);
+        if (sudoResult.ok)
+            result = sudoResult;
+    }
     if (!result.ok) {
         console.error(chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`));
         const manual = prefix
@@ -253,4 +279,4 @@ export const __test__ = {
     resolveRunningPrefix,
 };
 //# sourceMappingURL=version-gate.js.map
-//# debugId=0f613895-ad4a-5211-bf75-a2e843782c47
+//# debugId=00fa2aa9-f5d1-57a7-92db-c441c6bef906

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.54.0",
+  "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);
     });

package/src/utils/version-gate.test.ts

@@ -364,4 +364,76 @@ describe("enforceVersionGate — hard-update path", () => {
     expect(exitSpy).toHaveBeenCalledWith(0);
     expect(performUpdateString).toHaveBeenCalledWith(updateCommand);
   });
+
+  it("retries under `sudo -n` when the unprivileged install fails (root-owned global)", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    // First (unprivileged) npm install fails with EACCES; the sudo -n retry succeeds.
+    const runner = vi
+      .fn()
+      .mockImplementation((cmd: string) =>
+        cmd === "sudo" ? { ok: true } : { ok: false, detail: "EACCES" },
+      );
+    const { __test__ } = await loadModule();
+    const prefix = "/usr";
+
+    expect(() =>
+      __test__.enforceUpdateRequired(
+        {
+          clientId: "hq-cli",
+          currentVersion: "5.10.0",
+          minVersion: "5.20.0",
+          latestVersion: "5.24.0",
+          updateRequired: true,
+          updateRecommended: false,
+          updateCommand: "npm install -g @indigoai-us/hq-cli@latest",
+        },
+        { resolvePrefix: () => prefix, runner },
+      ),
+    ).toThrow(/__process_exit__:0/); // succeeds after the sudo retry
+
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    const installArgs = [
+      "install",
+      "-g",
+      "--prefix",
+      prefix,
+      "@indigoai-us/hq-cli@latest",
+    ];
+    expect(runner).toHaveBeenCalledWith("npm", installArgs);
+    expect(runner).toHaveBeenCalledWith("sudo", ["-n", "npm", ...installArgs]);
+  });
+
+  it("exits 75 when BOTH the unprivileged install and the sudo -n retry fail", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    const runner = vi.fn().mockReturnValue({ ok: false, detail: "EACCES" });
+    const { __test__ } = await loadModule();
+
+    expect(() =>
+      __test__.enforceUpdateRequired(
+        {
+          clientId: "hq-cli",
+          currentVersion: "5.10.0",
+          minVersion: "5.20.0",
+          latestVersion: "5.24.0",
+          updateRequired: true,
+          updateRecommended: false,
+          updateCommand: "npm install -g @indigoai-us/hq-cli@latest",
+        },
+        { resolvePrefix: () => "/usr", runner },
+      ),
+    ).toThrow(/__process_exit__:75/);
+
+    expect(exitSpy).toHaveBeenCalledWith(75);
+    expect(runner).toHaveBeenCalledWith("sudo", expect.arrayContaining(["-n"]));
+  });
 });

package/src/utils/version-gate.ts

@@ -236,12 +236,24 @@ function enforceUpdateRequired(
   }
 
   const runner = deps.runner ?? runUpdateCommand;
-  const result = prefix
+  // Resolve the concrete install argv once so the sudo fallback below can re-run
+  // the EXACT same command under elevation.
+  let primaryCmd: string;
+  let primaryArgs: string[];
+  if (prefix) {
+    primaryCmd = "npm";
+    primaryArgs = buildPrefixedInstallArgv(prefix);
+  } else {
+    const parts = (command ?? "").split(/\s+/).filter(Boolean);
+    primaryCmd = parts[0] ?? "";
+    primaryArgs = parts.slice(1);
+  }
+
+  let result = prefix
     ? (() => {
-        const args = buildPrefixedInstallArgv(prefix);
         console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
-        console.error(chalk.dim(`  Running: npm ${args.join(" ")}`));
-        return performUpdateCommand("npm", args, runner);
+        console.error(chalk.dim(`  Running: npm ${primaryArgs.join(" ")}`));
+        return performUpdateCommand("npm", primaryArgs, runner);
       })()
     : (() => {
         console.error(chalk.dim(`  Running: ${command}`));
@@ -249,6 +261,29 @@ function enforceUpdateRequired(
           ? deps.performUpdateString(command!)
           : performUpdate(command!, runner);
       })();
+
+  // A root-owned global install (e.g. a system `/usr` install where the CLI runs
+  // unprivileged — the outpost agent boxes) can't rewrite the prefix's bin dir,
+  // so the install above fails with EACCES (`rename /usr/bin/hq`). Retry ONCE
+  // under non-interactive sudo: `sudo -n` fails fast WITHOUT a password prompt
+  // when passwordless sudo isn't configured, so interactive installs (e.g.
+  // Homebrew on macOS, where the first attempt already succeeded anyway) fall
+  // through to the manual path unchanged, while headless boxes with passwordless
+  // sudo self-update cleanly.
+  if (!result.ok && primaryCmd) {
+    console.error(
+      chalk.dim(
+        `  Update failed unprivileged; retrying with: sudo -n ${primaryCmd} ${primaryArgs.join(" ")}`,
+      ),
+    );
+    const sudoResult = performUpdateCommand(
+      "sudo",
+      ["-n", primaryCmd, ...primaryArgs],
+      runner,
+    );
+    if (sudoResult.ok) result = sudoResult;
+  }
+
   if (!result.ok) {
     console.error(
       chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`),