@indigoai-us/hq-cloud 6.7.1 → 6.9.0

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

@@ -3604,7 +3604,7 @@ describe("runRunnerWithLoop — operation lock", () => {
     return p;
   }
 
-  it("one-shot sync refuses fast (exit 17) when another op holds the root", async () => {
+  it("one-shot sync refuses immediately (exit 17) with --lock-timeout 0 when another op holds the root", async () => {
     const lp = writeLiveHolder("rescue");
     const errs: string[] = [];
     const spy = vi
@@ -3614,12 +3614,21 @@ describe("runRunnerWithLoop — operation lock", () => {
         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]);
+    // No --watch → one-shot. `--lock-timeout 0` keeps the pre-wait
+    // refuse-immediately behavior (the default is now to WAIT for the holder).
+    // Refusal short-circuits BEFORE runRunner (so no network / auth is touched).
+    const start = Date.now();
+    const code = await runRunnerWithLoop([
+      "--companies",
+      "--hq-root",
+      HQ,
+      "--lock-timeout",
+      "0",
+    ]);
 
     spy.mockRestore();
     expect(code).toBe(OPERATION_LOCKED_EXIT);
+    expect(Date.now() - start).toBeLessThan(1500); // did not wait
     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"));
@@ -3627,6 +3636,76 @@ describe("runRunnerWithLoop — operation lock", () => {
     expect(held.command).toBe("rescue");
   });
 
+  it("one-shot sync WAITS for a live holder (default), bounded by --lock-timeout, then refuses with exit 17", 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;
+      });
+
+    // The holder never releases here; --lock-timeout 1 bounds the wait so the
+    // runner waits ~1s, emits a single "Waiting for …" status line, then
+    // refuses (exit 17) — proving the runner threads the flag through and
+    // takes the wait path (rather than refusing instantly). It still never
+    // enters runRunner, so no network/auth is touched.
+    const start = Date.now();
+    const code = await runRunnerWithLoop([
+      "--companies",
+      "--hq-root",
+      HQ,
+      "--lock-timeout",
+      "1",
+    ]);
+    const elapsed = Date.now() - start;
+
+    spy.mockRestore();
+    expect(code).toBe(OPERATION_LOCKED_EXIT);
+    expect(elapsed).toBeGreaterThanOrEqual(800); // actually waited ~1s
+    expect(errs.join("")).toContain("Waiting for"); // status line emitted once
+    expect(errs.join("")).toContain("rescue"); // names the holder
+    const held = JSON.parse(fs.readFileSync(lp, "utf8"));
+    expect(held.pid).toBe(1); // holder untouched
+  }, 20_000);
+
+  it("DEV-1772: one-shot waits out a SHORT-LIVED holder (reindex) then PROCEEDS to sync", async () => {
+    // The exact reported scenario (feedback_28a1833f / DEV-1772): a frequent
+    // ~1-min `reindex` briefly holds the lock; the instant-sync one-shot used
+    // to exit 17 and silently die. Now it WAITS (default) and proceeds the
+    // moment the short holder releases. We model the short holder with a
+    // foreign live pid (1) whose lock file is removed shortly after, and inject
+    // runPass so "proceeds → syncs" is observable without the network.
+    writeLiveHolder("reindex");
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+
+    const runPass = vi.fn().mockResolvedValue(0);
+    // The short-lived holder releases ~150ms in.
+    setTimeout(() => fs.rmSync(lockPathFor(HQ), { force: true }), 150);
+
+    const code = await runRunnerWithLoop(
+      ["--companies", "--hq-root", HQ],
+      { runPass },
+    );
+
+    spy.mockRestore();
+    // It did NOT refuse/die — it waited then ran the sync pass exactly once.
+    expect(code).toBe(0);
+    expect(code).not.toBe(OPERATION_LOCKED_EXIT);
+    expect(runPass).toHaveBeenCalledTimes(1);
+    // A single "Waiting for …" status line named the short holder.
+    const out = errs.join("");
+    expect(out).toContain("Waiting for");
+    expect(out).toContain("reindex");
+  }, 20_000);
+
   it("the watch runner is EXEMPT — runs despite a held lock and never takes it", async () => {
     const lp = writeLiveHolder("sync");
     const watcher = makeWatcherStub();

package/src/bin/sync-runner.ts

@@ -607,6 +607,13 @@ interface ParsedArgs {
    * mode (single-company runs never visit the personal target).
    */
   skipPersonal: boolean;
+  /**
+   * Bounded wait (seconds) for the per-root operation lock when another op is
+   * already running. `0` → refuse immediately (pre-wait behavior); omitted →
+   * inherit `HQ_OP_LOCK_TIMEOUT` / infinite wait. Only meaningful on the
+   * one-shot path (the `--watch` runner is lock-exempt).
+   */
+  lockTimeoutSec?: number;
 }
 
 function parseArgs(argv: string[]): ParsedArgs | { error: string } {
@@ -620,6 +627,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let pollRemoteMs: number | undefined;
   let skipPersonal = false;
   let eventPush = false;
+  let lockTimeoutSec: number | undefined;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -693,6 +701,18 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
         // @getindigo.ai identities for the first release.
         eventPush = true;
         break;
+      case "--lock-timeout": {
+        const val = argv[++i];
+        if (!val) return { error: "--lock-timeout requires a value (seconds)" };
+        const n = Number(val);
+        if (!Number.isInteger(n) || n < 0) {
+          return {
+            error: `--lock-timeout must be a non-negative integer (seconds), got: ${val}`,
+          };
+        }
+        lockTimeoutSec = n;
+        break;
+      }
       default:
         return { error: `Unknown argument: ${arg}` };
     }
@@ -732,6 +752,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
     pollRemoteMs,
     skipPersonal,
     eventPush,
+    lockTimeoutSec,
   };
 }
 
@@ -1855,10 +1876,27 @@ export async function runRunnerWithLoop(
     // surfaces the parse error rather than us masking it with a lock failure.
     const parsed = parseArgs(argv);
     if ("error" in parsed) return runRunner(argv);
+    // The actual sync pass — same seam the watch loop uses (deps.runPass),
+    // so a test can assert "waits for a short-lived holder, THEN proceeds to
+    // sync" without touching the network. Production passes `argv` to
+    // runRunner exactly as before. Regression guard for DEV-1772
+    // (feedback_28a1833f): instant-sync one-shots used to exit 17 and die on
+    // a lock conflict with the ~1-min reindex hook; they now WAIT (default)
+    // and proceed once the short holder releases.
+    const runOnce = deps.runPass ?? ((passArgv: string[]) => runRunner(passArgv));
     try {
-      return await withOperationLock(parsed.hqRoot, "sync", () => runRunner(argv));
+      return await withOperationLock(parsed.hqRoot, "sync", () => runOnce(argv), {
+        timeoutSec: parsed.lockTimeoutSec,
+      });
     } catch (err) {
       if (err instanceof OperationLockedError) {
+        // The lock wait was BOUNDED and tripped (a holder never released
+        // within --lock-timeout / HQ_OP_LOCK_TIMEOUT). Surface it loudly on
+        // stderr and exit with the stable OPERATION_LOCKED_EXIT (17) so the
+        // spawner (menubar) can recognize a lock conflict and SCHEDULE A
+        // RETRY rather than treating it as a hard failure and silently giving
+        // up (DEV-1772). With the default (no bound) we never reach here — the
+        // one-shot waits indefinitely and proceeds.
         process.stderr.write(err.message + "\n");
         return OPERATION_LOCKED_EXIT;
       }

package/src/cli/reindex.test.ts

@@ -135,9 +135,10 @@ describe("reindex", () => {
 
   // ── 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.
+  it("refuses (OPERATION_LOCKED_EXIT) when another op holds this root's lock (lockTimeoutSec:0)", () => {
+    // A live holder in another process (pid 1) → with lockTimeoutSec:0 reindex
+    // refuses immediately and does no work. (The new default is to WAIT; the
+    // wait-then-acquire path is covered in operation-lock.test.ts.)
     const lp = lockPathFor(root);
     fs.mkdirSync(path.dirname(lp), { recursive: true });
     fs.writeFileSync(
@@ -145,7 +146,7 @@ describe("reindex", () => {
       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 });
+    const { status } = reindex({ repoRoot: root, lockTimeoutSec: 0 });
     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);

package/src/cli/reindex.ts

@@ -35,6 +35,17 @@ export interface ReindexOptions {
    * exclusive with a running sync/rescue.
    */
   skipLock?: boolean;
+  /**
+   * Bounded wait (seconds) for the per-root operation lock when a sync/rescue
+   * is already running. `0` → refuse immediately; omitted → inherit
+   * `HQ_OP_LOCK_TIMEOUT` / infinite wait. Ignored when `skipLock` is set.
+   *
+   * NB: standalone `hq reindex` waits by default, which is what a human running
+   * it wants. The hq-core reindex HOOK (Stop / PostToolUse) should set a small
+   * `HQ_OP_LOCK_TIMEOUT` (or `0`) so a hook fired mid-sync never blocks the
+   * interactive agent indefinitely.
+   */
+  lockTimeoutSec?: number;
 }
 
 export interface ReindexResult {
@@ -151,7 +162,7 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
   let opLock: LockHandle | null = null;
   if (!opts.skipLock) {
     try {
-      opLock = acquireOperationLock(root, "reindex");
+      opLock = acquireOperationLock(root, "reindex", { timeoutSec: opts.lockTimeoutSec });
     } catch (err) {
       if (err instanceof OperationLockedError) {
         warn(err.message);

package/src/cli/rescue.test.ts

@@ -1,5 +1,47 @@
 import { describe, it, expect } from "vitest";
-import { buildRescueArgs } from "./rescue.js";
+import { buildRescueArgs, extractLockTimeout } from "./rescue.js";
+
+describe("extractLockTimeout", () => {
+  it("returns the explicit option untouched when extraArgs is empty/absent", () => {
+    expect(extractLockTimeout({ lockTimeoutSec: 5 })).toEqual({
+      lockTimeoutSec: 5,
+      cleanedExtraArgs: undefined,
+    });
+    expect(extractLockTimeout({ lockTimeoutSec: 5, extraArgs: [] })).toEqual({
+      lockTimeoutSec: 5,
+      cleanedExtraArgs: [],
+    });
+  });
+
+  it("pulls --lock-timeout <secs> out of extraArgs and strips it from the forwarded args", () => {
+    const r = extractLockTimeout({
+      extraArgs: ["--lock-timeout", "30", "--dry-run", "--yes"],
+    });
+    expect(r.lockTimeoutSec).toBe(30);
+    // The flag + its value never reach the rescue script.
+    expect(r.cleanedExtraArgs).toEqual(["--dry-run", "--yes"]);
+  });
+
+  it("honors --lock-timeout 0 (refuse immediately)", () => {
+    const r = extractLockTimeout({ extraArgs: ["--lock-timeout", "0"] });
+    expect(r.lockTimeoutSec).toBe(0);
+    expect(r.cleanedExtraArgs).toEqual([]);
+  });
+
+  it("explicit option wins over a flag in extraArgs", () => {
+    const r = extractLockTimeout({
+      lockTimeoutSec: 0,
+      extraArgs: ["--lock-timeout", "60"],
+    });
+    expect(r.lockTimeoutSec).toBe(0);
+    expect(r.cleanedExtraArgs).toEqual([]);
+  });
+
+  it("ignores a non-numeric / negative --lock-timeout value (treated as unset)", () => {
+    expect(extractLockTimeout({ extraArgs: ["--lock-timeout", "abc"] }).lockTimeoutSec).toBeUndefined();
+    expect(extractLockTimeout({ extraArgs: ["--lock-timeout", "-3"] }).lockTimeoutSec).toBeUndefined();
+  });
+});
 
 describe("buildRescueArgs", () => {
   it("emits no args for an empty option set (script defaults apply)", () => {

package/src/cli/rescue.ts

@@ -57,10 +57,52 @@ export interface RescueOptions {
   /** GitHub token forwarded to the script as `GH_TOKEN` (avoids the
    *  anonymous-clone rate limit; required for private sources). */
   ghToken?: string;
+  /**
+   * Bounded wait (seconds) for the per-root operation lock when a sync/reindex
+   * is already running. `0` → refuse immediately; omitted → inherit
+   * `HQ_OP_LOCK_TIMEOUT` / infinite wait. Also accepted as `--lock-timeout
+   * <secs>` inside {@link extraArgs} (the machine `hq-rescue` entrypoint
+   * forwards raw argv) — it is consumed here and never passed to the rescue
+   * script, which doesn't understand it.
+   */
+  lockTimeoutSec?: number;
   /** Escape hatch — additional raw args appended verbatim. */
   extraArgs?: string[];
 }
 
+/**
+ * Pull `--lock-timeout <secs>` out of `extraArgs` (the raw argv the machine
+ * `hq-rescue` entrypoint forwards) so it controls the operation-lock wait
+ * instead of leaking to the rescue script. Returns the resolved timeout
+ * (explicit `opts.lockTimeoutSec` wins) and a copy of extraArgs with the flag
+ * removed.
+ */
+export function extractLockTimeout(opts: RescueOptions): {
+  lockTimeoutSec: number | undefined;
+  cleanedExtraArgs: string[] | undefined;
+} {
+  const raw = opts.extraArgs;
+  if (!raw || raw.length === 0) {
+    return { lockTimeoutSec: opts.lockTimeoutSec, cleanedExtraArgs: raw };
+  }
+  const cleaned: string[] = [];
+  let fromArgs: number | undefined;
+  for (let i = 0; i < raw.length; i++) {
+    if (raw[i] === "--lock-timeout") {
+      const val = Number(raw[i + 1]);
+      if (Number.isInteger(val) && val >= 0) fromArgs = val;
+      i++; // skip the value too
+      continue;
+    }
+    cleaned.push(raw[i]);
+  }
+  // Explicit option beats the parsed flag.
+  return {
+    lockTimeoutSec: opts.lockTimeoutSec ?? fromArgs,
+    cleanedExtraArgs: cleaned,
+  };
+}
+
 export interface RescueResult {
   /** Exit status of the underlying script (0 = success). */
   status: number;
@@ -100,9 +142,13 @@ export function rescue(opts: RescueOptions = {}): RescueResult {
   // lock on the same root the rescue script resolves (cwd when --hq-root is
   // omitted). Rescue is never the exempt push watcher, so it always locks.
   const lockRoot = opts.hqRoot ?? process.cwd();
+  // Consume --lock-timeout from extraArgs (machine entrypoint) before it can
+  // reach the rescue script, which doesn't understand it.
+  const { lockTimeoutSec, cleanedExtraArgs } = extractLockTimeout(opts);
+  const rescueOpts: RescueOptions = { ...opts, extraArgs: cleanedExtraArgs };
   let handle;
   try {
-    handle = acquireOperationLock(lockRoot, "rescue");
+    handle = acquireOperationLock(lockRoot, "rescue", { timeoutSec: lockTimeoutSec });
   } catch (err) {
     if (err instanceof OperationLockedError) {
       process.stderr.write(err.message + "\n");
@@ -111,7 +157,7 @@ export function rescue(opts: RescueOptions = {}): RescueResult {
     throw err;
   }
   try {
-    const args = buildRescueArgs(opts);
+    const args = buildRescueArgs(rescueOpts);
     const env: NodeJS.ProcessEnv = { ...process.env };
     if (opts.ghToken) env.GH_TOKEN = opts.ghToken;
     const { status } = runRescue(args, { env });