@indigoai-us/hq-cli 5.103.11 → 5.103.13

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [5.103.13] — 2026-08-20
+
+### Fixed
+
+- The bundled checkpoint stop-gate now *enforces* the user-facing reply
+  instead of only asking for it: a satisfying checkpoint on a work turn whose
+  genuine reply is under `HQ_CHECKPOINT_REPLY_MIN` non-whitespace characters
+  (default 80) blocks once with a dedicated reply demand, stamped per
+  checkpoint tool id and counted against the shared 3-consecutive-blocks loop
+  guard, so it can never strand a session. The reply window accepts text on
+  either side of the checkpoint and crosses the gate's own block feedback, so
+  an agent that already replied is never told to repeat itself — composing
+  with the reply-aware block variants — while mid-turn notes written before
+  the last work tool do not count. Flag exemptions are parsed robustly:
+  `--gate-probe` / `--idle` inside a quoted `--summary` value are data, not
+  flags, and a compound command ending in a checkpoint keeps owing the reply.
+  The `--idle` path of `hq core checkpoint` prints a conditional reminder
+  matching the gate's idle-only exemption.
+
+## [5.103.12] — 2026-08-20
+
 ## [5.103.11] — 2026-08-20
 
 ### Reverted

package/assets/scaffold/core/scripts/checkpoint-stop-gate.sh

@@ -232,65 +232,105 @@ set -uo pipefail
       end;
     def checkpoint_command:
       test("(^|[;&|(\\s])(command\\s+)?([A-Za-z_][A-Za-z0-9_]*=[^\\s]*\\s+)*hq\\s+core\\s+checkpoint(\\s|$)");
+    def strip_quoted:
+      # Remove quoted spans so flag text inside a --summary value (e.g.
+      # --summary "investigated --gate-probe behavior") is never mistaken for
+      # an active flag. Double-quoted spans honor backslash escapes. The
+      # u0027 escape is a single-quote character, written that way because
+      # this whole program lives inside a single-quoted shell string.
+      gsub("\"(\\\\.|[^\"\\\\])*\""; "")
+      | gsub("\u0027[^\u0027]*\u0027"; "");
+    def checkpoint_flag($flag):
+      strip_quoted | test("(^|\\s)" + $flag + "(\\s|$)");
+    def pure_checkpoint:
+      # The command is ONLY a checkpoint invocation (optional env-assignment
+      # prefix, no other command joined by a separator). A compound call like
+      # `git status; hq core checkpoint --idle` did other work in the same
+      # tool call, so its exemptions must not apply.
+      strip_quoted
+      | test("^\\s*(command\\s+)?([A-Za-z_][A-Za-z0-9_]*=[^\\s]*\\s+)*hq\\s+core\\s+checkpoint([\\s][^;&|\n]*)?$");
+    def gate_feedback_user:
+      # This gate surfaces its own Stop feedback as a synthetic user row. That
+      # row is a turn boundary for the checkpoint requirement, but NOT for
+      # deciding whether the USER has been answered: a reply the agent wrote
+      # before the block is already on screen and must never be demanded again
+      # (double-messaging).
+      .type == "user"
+      and ((.message.content? | type) == "string")
+      and (.message.content | startswith("Stop hook feedback:"));
     [split("\n")[] | select(length > 0) | {line: ., entry: (fromjson)}] as $rows
     | [range(0; $rows | length) | select($rows[.].entry | real_user)] as $user_indexes
     | if ($user_indexes | length) == 0 then error("no real user entry") else
         $user_indexes[-1] as $user_index
-        | $rows[($user_index + 1):] as $turn
+        | ([$user_indexes[] | select(($rows[.].entry | gate_feedback_user) | not)]
+           | if length > 0 then .[-1] else $user_indexes[0] end) as $genuine_index
         | [
-            range(0; $turn | length) as $ti
-            | $turn[$ti].entry
+            range($genuine_index + 1; $rows | length) as $ri
+            | $rows[$ri].entry
             | if .type == "assistant" then
                 .message.content?
                 | if type == "array" then .[]? else empty end
-                | select(.type == "tool_use")
-                | {
-                    i: $ti,
-                    runtime: "claude",
-                    id: (.id? // ""),
-                    name: (.name? // ""),
-                    command: (.input.command? // "")
-                  }
+                | if .type == "tool_use" then
+                    {
+                      row: $ri,
+                      kind: "tool",
+                      runtime: "claude",
+                      id: (.id? // ""),
+                      name: (.name? // ""),
+                      command: (.input.command? // "")
+                    }
+                  elif .type == "text" then
+                    # Whitespace-stripped so blank filler can never pass for a
+                    # reply.
+                    {row: $ri, kind: "text",
+                     chars: ((.text? // "") | gsub("\\s+"; "") | length)}
+                  else empty
+                  end
               elif (
                 .type == "response_item"
                 and (.payload.type? == "custom_tool_call" or .payload.type? == "function_call")
               ) then
                 .payload
                 | {
-                    i: $ti,
+                    row: $ri,
+                    kind: "tool",
                     runtime: "codex",
                     id: (.call_id? // .id? // ""),
                     name: (.name? // ""),
                     command: codex_command
                   }
+              elif (
+                .type == "response_item"
+                and .payload.type? == "message"
+                and .payload.role? == "assistant"
+                and ((.payload.content? | type) == "array")
+              ) then
+                {row: $ri, kind: "text",
+                 chars: ([.payload.content[]? | (.text? // "")] | join("")
+                         | gsub("\\s+"; "") | length)}
               else empty
               end
-          ] as $tools
+          ] as $events
+        | [$events[] | select(.row > $user_index)] as $seg_events
+        | [$seg_events[] | select(.kind == "tool")] as $tools
         | (if ($tools | length) > 0 then $tools[-1] else {} end) as $last_tool
-        # A user-visible assistant reply strictly AFTER the turn-s last tool call
-        # means the user has already been answered, so the block reason must
-        # forbid a restatement instead of demanding one. Text earlier in the turn
-        # (status notes between tool calls) does not count as the reply.
-        | (if ($tools | length) > 0 then $tools[-1].i else -1 end) as $last_tool_i
-        | ([
-             $turn[($last_tool_i + 1):][]
-             | .entry
-             | if .type == "assistant" then
-                 .message.content?
-                 | if type == "string" then .
-                   elif type == "array" then ([.[]? | select(.type == "text") | (.text? // "")] | join(""))
-                   else ""
-                   end
-               elif (
-                 .type == "response_item"
-                 and .payload.type? == "message"
-                 and .payload.role? == "assistant"
-                 and ((.payload.content? | type) == "array")
-               ) then
-                 ([.payload.content[]? | (.text? // "")] | join(""))
-               else ""
-               end
-           ] | join("") | test("\\S")) as $replied
+        # Reply visible after THIS segment last tool call: chooses which block
+        # variant an unsatisfied turn gets (write your reply vs do not repeat
+        # it). Mid-turn notes between tool calls do not count.
+        | ([range(0; $seg_events | length) | select($seg_events[.].kind == "tool")]
+           | if length > 0 then .[-1] else -1 end) as $seg_last_tool_index
+        | ([$seg_events[($seg_last_tool_index + 1):][] | select(.kind == "text") | .chars]
+           | add // 0) as $seg_reply_chars
+        # Reply owed by the WHOLE genuine turn: all assistant text after its
+        # last non-checkpoint tool call, crossing this gate feedback
+        # boundaries. An agent that replied and then checkpointed (in either
+        # order across a block) is never told to write the reply again.
+        | ([range(0; $events | length)
+            | select(($events[.].kind == "tool")
+                     and (($events[.].command | checkpoint_command) | not))]
+           | if length > 0 then .[-1] else -1 end) as $last_work_index
+        | ([$events[($last_work_index + 1):][] | select(.kind == "text") | .chars]
+           | add // 0) as $reply_chars
         | ([$tools[] | select((.command | checkpoint_command) | not)] | length) as $work_tool_count
         | ([
              $rows[]
@@ -305,18 +345,50 @@ set -uo pipefail
             ($tools | length) > 0
             and ($last_tool.command | checkpoint_command)
           ) then
-            if $last_tool.runtime == "claude" and ($last_result_error | not) then "1"
+            if $last_tool.runtime == "claude" and ($last_result_error | not) then
+              # A reply is owed after a real (--summary) checkpoint always, and
+              # after an --idle checkpoint only when the turn ran other tools
+              # (a read-only investigation still owes its findings). A
+              # --gate-probe is pure bookkeeping and never owes one. Both
+              # exemptions apply only to a PURE checkpoint invocation, with the
+              # flags read outside quoted text — a compound command did other
+              # work in the same call, and flag text inside a --summary value
+              # is data, not a flag.
+              (
+                (($last_tool.command | pure_checkpoint) | not)
+                or (
+                  (($last_tool.command | checkpoint_flag("--gate-probe")) | not)
+                  and (
+                    (($last_tool.command | checkpoint_flag("--idle")) | not)
+                    or ($work_tool_count > 0)
+                  )
+                )
+              ) as $reply_required
+              | "1\t\($last_tool.id)\t\($reply_chars)\t\(if $reply_required then 1 else 0 end)"
             elif $last_tool.runtime == "codex" then "stamp"
-            else (if $replied then "0-replied" else "0-unreplied" end)
+            else (if $seg_reply_chars > 0 then "0-replied" else "0-unreplied" end)
             end
           elif $work_tool_count == 0 then "idle"
-          else (if $replied then "0-replied" else "0-unreplied" end)
+          else (if $seg_reply_chars > 0 then "0-replied" else "0-unreplied" end)
           end
       end
   ' 2>/dev/null)" || exit 0
+  # A Claude success verdict carries the satisfying checkpoint's tool id, the
+  # count of non-whitespace assistant text characters delivered after the
+  # genuine turn's last work tool (its user-facing reply, wherever it sits
+  # relative to the checkpoint), and whether this checkpoint shape owes the
+  # user a reply at all. An unsatisfied verdict says whether a reply is
+  # already visible, so the block message never demands a duplicate.
   satisfied="$parsed"
   replied=0
-  case "$satisfied" in
+  reply_tool_id=""
+  reply_chars=""
+  reply_required=""
+  gate_tab="$(printf '\t')"
+  case "$parsed" in
+    "1${gate_tab}"*)
+      IFS="$gate_tab" read -r satisfied reply_tool_id reply_chars reply_required <<<"$parsed"
+      ;;
     0-replied) satisfied=0; replied=1 ;;
     0-unreplied) satisfied=0 ;;
   esac
@@ -350,49 +422,95 @@ set -uo pipefail
   # there is nothing to record. Demanding one anyway turns every conversational
   # reply — and every background-notification wake-up — into an --idle round
   # trip that writes no state and only costs a turn.
+  # Consecutive-block counter, shared by every block this gate can emit (the
+  # missing-checkpoint demand and the reply demand alike). A session whose
+  # checkpoint command keeps FAILING (a broken or mid-self-update `hq` binary)
+  # would otherwise be re-prompted on every Stop, forever. Past the cap the
+  # gate fails open per this file's never-strand-a-session doctrine; any Stop
+  # that ends in an allow resets it.
+  block_count_file="$state_dir/checkpoint-block-count-$session_key"
+  block_count="$(tr -d '\r\n' <"$block_count_file" 2>/dev/null || true)"
+  case "$block_count" in
+    ''|*[!0-9]*) block_count=0 ;;
+  esac
+  bump_block_count() {
+    block_count_tmp="$block_count_file.$$"
+    if (umask 077 && printf '%s' "$((block_count + 1))" >"$block_count_tmp" && mv -f "$block_count_tmp" "$block_count_file"); then
+      :
+    else
+      rm -f "$block_count_tmp" 2>/dev/null || true
+    fi
+  }
+
   if [ "$satisfied" = "1" ] || [ "$satisfied" = "idle" ]; then
     if [ "$runtime" = "codex" ]; then
       rm -f "$state_dir/codex-checkpoint-reprompt-$session_key" 2>/dev/null || true
     fi
-    rm -f "$state_dir/checkpoint-block-count-$session_key" 2>/dev/null || true
+
+    # Reply-owed enforcement (Claude runtime only). The checkpoint payload
+    # goes to the background sibling, never the user. A genuine turn that did
+    # work and reaches a satisfying checkpoint with (next to) no assistant
+    # text after its last WORK tool call is a turn whose user-facing reply is
+    # missing, however rich the checkpoint flags are: block once and demand
+    # the reply. The window deliberately crosses this gate's own feedback
+    # boundaries and accepts a reply on either side of the checkpoint, so an
+    # agent that replied and then checkpointed is never told to repeat itself
+    # (double-messaging is the failure the reply-aware block variants exist
+    # to prevent). Evidence (transcript audit 2026-08-19, 1471 stop-gate
+    # checkpoint turns): 2.7% ended with no reply anywhere while the substance
+    # lived only in the checkpoint payload. The nudge fires at most once per
+    # checkpoint tool id (stamped in hook-state), so a legitimately terse turn
+    # costs exactly one extra Stop round-trip and the gate can never loop.
+    # Codex is excluded: its Stop feedback is a synthetic re-prompt with its
+    # own delivery contract. HQ_CHECKPOINT_REPLY_MIN overrides the minimum
+    # non-whitespace character threshold; 0 disables the enforcement.
+    if [ "$satisfied" = "1" ] && [ "$runtime" = "claude" ] \
+      && [ "$reply_required" = "1" ] && [ -n "$reply_tool_id" ]; then
+      reply_min="${HQ_CHECKPOINT_REPLY_MIN:-80}"
+      case "$reply_min" in ''|*[!0-9]*) reply_min=80 ;; esac
+      case "$reply_chars" in ''|*[!0-9]*) reply_chars=0 ;; esac
+      if [ "$reply_min" -gt 0 ] && [ "$reply_chars" -lt "$reply_min" ] && [ "$block_count" -lt 3 ]; then
+        nudge_file="$state_dir/checkpoint-reply-nudge-$session_key"
+        nudge_prev="$(cat "$nudge_file" 2>/dev/null || true)"
+        if [ "$nudge_prev" != "$reply_tool_id" ]; then
+          nudge_tmp="$nudge_file.$$"
+          if (umask 077 && printf '%s' "$reply_tool_id" >"$nudge_tmp" && mv -f "$nudge_tmp" "$nudge_file"); then
+            bump_block_count
+            reply_reason='Checkpoint recorded — but the turn cannot end yet: the user has not received a reply this turn. The checkpoint payload went to a background maintenance agent; the user sees NONE of it, and nothing you have written since your last real action reads as a reply to them. Deliver your complete reply to the user now, as ordinary text: every result, finding, link, decision, and anything awaiting their input, in plain language. Do not run another checkpoint and do not call any other tool — end the turn with text only.'
+            printf '{"decision":"block","reason":%s}\n' "$(printf '%s' "$reply_reason" | hq_json_encode)"
+            exit 0
+          fi
+          rm -f "$nudge_tmp" 2>/dev/null || true
+        fi
+      fi
+    fi
+    # This Stop ends in an allow: the session is not stuck, so the
+    # consecutive-block counter starts over.
+    rm -f "$block_count_file" 2>/dev/null || true
     exit 0
   fi
 
-  # Loop guard: a session whose checkpoint command keeps FAILING (a broken or
-  # mid-self-update `hq` binary) would otherwise be re-prompted on every Stop,
-  # forever — block → retry checkpoint → error → block again. Cap consecutive
-  # blocks per session; past the cap, fail open per this file's
-  # never-strand-a-session doctrine. Any successful checkpoint or idle turn
-  # resets the counter above.
-  block_count_file="$state_dir/checkpoint-block-count-$session_key"
-  block_count="$(tr -d '\r\n' <"$block_count_file" 2>/dev/null || true)"
-  case "$block_count" in
-    ''|*[!0-9]*) block_count=0 ;;
-  esac
+  # Loop guard for the missing-checkpoint demand below: cap consecutive blocks
+  # per session, then fail open (see the counter's comment above).
   if [ "$block_count" -ge 3 ]; then
     exit 0
   fi
-  block_count_tmp="$block_count_file.$$"
-  if (umask 077 && printf '%s' "$((block_count + 1))" >"$block_count_tmp" && mv -f "$block_count_tmp" "$block_count_file"); then
-    :
-  else
-    rm -f "$block_count_tmp" 2>/dev/null || true
-  fi
+  bump_block_count
 
   # Built with printf rather than concatenation so the session id can appear in
   # both commands without re-splitting the message into fragments.
   #
   # Two variants, chosen from the transcript rather than left to the agent's
-  # judgment: the historical single instruction either demanded a full
-  # restatement (double-messaging hosts that render pre-tool text — the CLI and
-  # the desktop app both do) or forbade post-checkpoint text (hiding the reply
-  # when the agent had not yet written one). The transcript already tells us
-  # which case we are in, so say exactly one thing.
+  # judgment: a single instruction either demanded a full restatement
+  # (double-messaging hosts that render pre-tool text) or forbade
+  # post-checkpoint text (hiding the reply when the agent had not yet written
+  # one). The transcript already tells us which case we are in, so say exactly
+  # one thing.
   flags_spec='  hq core checkpoint --session-id %s --trigger stop-gate --summary "<what changed, in one line>" [--file <path>] [--decision "<choice and why>"] [--learning "<reusable rule>"] [--next "<outstanding step>"]\n\nOnly --summary is required, and the repeatable flags are what the sibling uses to enrich the record, distil policies and update the indexes — a bare summary gives it almost nothing to work with. Write them as machine record, not prose for the user, and pass each one that genuinely applies:\n  --file      every path you created or modified this turn\n  --decision  a choice you made that a reader would otherwise have to reverse-engineer\n  --learning  a rule that changes how someone acts next time, not a restatement of what just happened\n  --next      work that is genuinely still outstanding\nOmit a flag rather than padding it: an empty or invented learning is worse than none.\n\nIf this turn only read or inspected things and changed no state, the correct call instead is:\n\n  hq core checkpoint --session-id %s --idle'
   if [ "$replied" = 1 ]; then
     reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint before it can end.\n\nYour user-facing reply is ALREADY delivered — the message you just wrote is visible to the user. Do NOT send it again, in full or summarized: repeating it double-messages the user, which is exactly the bug this gate guards against.\n\nTHE SIBLING (a background maintenance agent) reads only the checkpoint payload, never your chat reply — anything it needs must go into the flags.\n\nRun the checkpoint now as the FINAL action of the turn and end the turn immediately after it, adding no further text:\n\n'"$flags_spec" "$session_id" "$session_id")"
   else
-    reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. You have not sent one yet this turn — everything you owe them (results, links, answers, status, decisions) must go into it. The checkpoint is invisible to them and does NOT count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nORDER: run the checkpoint FIRST, then deliver your complete user-facing reply as the FINAL text of the turn — final-position text is the one placement every host renders in full. Every link, URL, instruction, command, and decision the user needs must appear in that final message.\n\n'"$flags_spec" "$session_id" "$session_id")"
+    reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. You have not sent one yet this turn — everything you owe them (results, links, answers, status, decisions) must go into it. The checkpoint is invisible to them and does NOT count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nORDER: run the checkpoint FIRST, then deliver your complete user-facing reply as the FINAL text of the turn — final-position text is the one placement every host renders in full. Every link, URL, instruction, command, and decision the user needs must appear in that final message. The gate enforces this: a turn that ends without a user-facing reply is blocked until the reply is delivered.\n\n'"$flags_spec" "$session_id" "$session_id")"
   fi
 
   # Codex surfaces a blocked Stop reason as a synthetic user prompt. Preserve

package/dist/commands/core-checkpoint.d.ts

@@ -20,12 +20,21 @@ type SpawnableBackend = Exclude<Backend, "none">;
  * (both the CLI and the desktop app render pre-tool-call text), while an
  * unconditional "no commentary after" hid the reply from agents that had not
  * yet written one. The Stop gate makes the same distinction from the
- * transcript; this line covers proactive checkpoints the gate never sees.
- * Mirrors the hq-core policies
+ * transcript — and backstops this reminder mechanically: a satisfying
+ * checkpoint on a work turn whose genuine reply is still missing is blocked
+ * once with a dedicated reply demand. This line covers proactive checkpoints
+ * the gate never sees. Mirrors the hq-core policies
  * `checkpoint-is-bookkeeping-not-user-communication` and
  * `checkpoint-is-not-the-user-report`.
  */
 export declare const CHECKPOINT_REPLY_REMINDER: string;
+/**
+ * The --idle variant: an idle-only turn (nothing ran, nothing to report) is
+ * exempt at the Stop gate, so this text must never order a reply into
+ * existence — but an --idle after read-only work is NOT exempt (the gate
+ * demands the findings), so the conditional half still points there.
+ */
+export declare const CHECKPOINT_IDLE_REPLY_REMINDER: string;
 /**
  * Kept in TypeScript rather than in a bundled asset: it is an instruction to
  * a locally-installed agent, not a scaffold script that should be packaged.

package/dist/commands/core-checkpoint.js

@@ -51,8 +51,10 @@ class CheckpointUsageError extends Error {
  * (both the CLI and the desktop app render pre-tool-call text), while an
  * unconditional "no commentary after" hid the reply from agents that had not
  * yet written one. The Stop gate makes the same distinction from the
- * transcript; this line covers proactive checkpoints the gate never sees.
- * Mirrors the hq-core policies
+ * transcript — and backstops this reminder mechanically: a satisfying
+ * checkpoint on a work turn whose genuine reply is still missing is blocked
+ * once with a dedicated reply demand. This line covers proactive checkpoints
+ * the gate never sees. Mirrors the hq-core policies
  * `checkpoint-is-bookkeeping-not-user-communication` and
  * `checkpoint-is-not-the-user-report`.
  */
@@ -62,6 +64,15 @@ export const CHECKPOINT_REPLY_REMINDER = "checkpoint: REMINDER — this checkpoi
     "the user, write your user-facing reply now as the FINAL text of the turn. If you " +
     "already delivered it earlier this turn, end the turn now WITHOUT repeating it — the " +
     "user has already seen that message, and repeating it double-messages them.";
+/**
+ * The --idle variant: an idle-only turn (nothing ran, nothing to report) is
+ * exempt at the Stop gate, so this text must never order a reply into
+ * existence — but an --idle after read-only work is NOT exempt (the gate
+ * demands the findings), so the conditional half still points there.
+ */
+export const CHECKPOINT_IDLE_REPLY_REMINDER = "checkpoint: idle recorded — invisible bookkeeping; the user sees none of it. If this " +
+    "turn surfaced findings or answers the user has not been told, deliver them now as the " +
+    "turn's final text. If the turn genuinely produced nothing to report, end it.";
 function printResult(line) {
     process.stdout.write(`${line}\n`);
 }
@@ -824,8 +835,10 @@ function runCheckpoint(options, command, group) {
         writeStamps(liveRoot, resolveSessionId(options, command, readPayload(options.payload)));
         printResult("checkpoint: idle (nothing to record)");
         // An idle turn persisted nothing, but a read-only turn can still have
-        // produced substantive findings the user has not been told about.
-        printResult(CHECKPOINT_REPLY_REMINDER);
+        // produced substantive findings the user has not been told about. The
+        // conditional idle variant matches the Stop gate, which exempts an
+        // idle-only turn from the reply demand.
+        printResult(CHECKPOINT_IDLE_REPLY_REMINDER);
         return;
     }
     const payload = readPayload(options.payload);

package/dist/utils/self-update.d.ts

@@ -104,15 +104,18 @@ export declare function buildSelfUpdatePlan(install: RunningInstall): {
  */
 export declare function runUpdateQuiet(cmd: string, args: string[], env?: NodeJS.ProcessEnv): UpdateResult;
 /**
- * Serialize self-updates across concurrent `hq` processes. Without this, a
- * machine running several HQ agents can fire many `npm install -g` at the same
- * global prefix at once, and the losers fail with ENOTEMPTY mid-rename — the
- * exact partial-install state `cleanStalePartialInstall` exists to repair.
- * A caller that cannot take the lock simply skips its update: another process
- * is already installing the very version it wanted.
+ * Serialize self-updates across concurrent `hq` processes AND the hq-sync
+ * menubar app. Without this, a machine running several HQ agents can fire many
+ * `npm install -g` at the same global prefix at once, and the losers fail with
+ * ENOTEMPTY mid-rename — the exact partial-install state
+ * `cleanStalePartialInstall` exists to repair. A caller that cannot take the
+ * lock simply skips its update: another process is already installing the very
+ * version it wanted.
  *
- * `mkdir` is the atomic primitive (same approach as version-check's refresh
- * lock); a lock left behind by a killed process goes stale and is reclaimed.
+ * Delegates to the shared advisory lock in `update-lock.ts`
+ * (`$HOME/.hq/locks/cli-update.lock` — a cross-repo contract also honored by
+ * the hq-sync Rust app), so every updater on the machine contends on ONE lock
+ * instead of each tool keeping its own.
  */
 export declare function acquireUpdateLock(now?: number): (() => void) | null;
 /** Injectable surface so the flow is unit-testable without network or spawns. */

package/dist/utils/self-update.js

@@ -57,13 +57,11 @@
  * version-check), `hq rescue --no-self-update`, and the re-exec guard env.
  */
 import { spawnSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
 import semver from "semver";
 import chalk from "chalk";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, inOwnProcessGroup, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
+import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 /**
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
  * One update + one re-exec per user invocation, ever.
@@ -71,8 +69,6 @@ import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, bu
 export const REEXEC_GUARD_ENV = "HQ_RESCUE_SELF_UPDATED";
 const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(CLI_NAME)}/latest`;
 const FETCH_TIMEOUT_MS = 3_000;
-/** A held update lock older than this is treated as abandoned (crashed owner). */
-const UPDATE_LOCK_STALE_MS = 10 * 60 * 1000;
 /** Tail of captured package-manager stderr kept for the failure warning. */
 const DETAIL_MAX_CHARS = 400;
 /** npm `latest` for this package, or null on any failure (offline, 5xx, bad body). */
@@ -150,49 +146,23 @@ export function runUpdateQuiet(cmd, args, env) {
         output.dispose();
     }
 }
-function lockDir() {
-    return path.join(os.homedir(), ".hq", "self-update.lock");
-}
 /**
- * Serialize self-updates across concurrent `hq` processes. Without this, a
- * machine running several HQ agents can fire many `npm install -g` at the same
- * global prefix at once, and the losers fail with ENOTEMPTY mid-rename — the
- * exact partial-install state `cleanStalePartialInstall` exists to repair.
- * A caller that cannot take the lock simply skips its update: another process
- * is already installing the very version it wanted.
+ * Serialize self-updates across concurrent `hq` processes AND the hq-sync
+ * menubar app. Without this, a machine running several HQ agents can fire many
+ * `npm install -g` at the same global prefix at once, and the losers fail with
+ * ENOTEMPTY mid-rename — the exact partial-install state
+ * `cleanStalePartialInstall` exists to repair. A caller that cannot take the
+ * lock simply skips its update: another process is already installing the very
+ * version it wanted.
  *
- * `mkdir` is the atomic primitive (same approach as version-check's refresh
- * lock); a lock left behind by a killed process goes stale and is reclaimed.
+ * Delegates to the shared advisory lock in `update-lock.ts`
+ * (`$HOME/.hq/locks/cli-update.lock` — a cross-repo contract also honored by
+ * the hq-sync Rust app), so every updater on the machine contends on ONE lock
+ * instead of each tool keeping its own.
  */
 export function acquireUpdateLock(now = Date.now()) {
-    const dir = lockDir();
-    const release = () => {
-        try {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-        catch {
-            // best-effort lock cleanup
-        }
-    };
-    try {
-        fs.mkdirSync(path.dirname(dir), { recursive: true });
-        fs.mkdirSync(dir);
-        return release;
-    }
-    catch {
-        try {
-            const stat = fs.statSync(dir);
-            if (now - stat.mtimeMs > UPDATE_LOCK_STALE_MS) {
-                fs.rmSync(dir, { recursive: true, force: true });
-                fs.mkdirSync(dir);
-                return release;
-            }
-        }
-        catch {
-            // lock vanished or is unreadable — treat as held and skip
-        }
-        return null;
-    }
+    const handle = acquireSharedUpdateLock({ now, tool: "hq-cli-self-update" });
+    return handle ? handle.release : null;
 }
 /**
  * Re-run `hq <argv…>` from PATH so the freshly-installed version handles the

package/dist/utils/update-lock.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared advisory cross-process lock serializing every actor that runs
+ * `npm install -g @indigoai-us/hq-cli` (or the pnpm/bun equivalent) against
+ * the same machine.
+ *
+ * Why: production logs showed FOUR independent updaters — this CLI's hard
+ * version-gate, the soft self-updater, and updaters inside the hq-sync menubar
+ * app — each firing `npm install -g` with no coordination. On a machine with a
+ * second "ghost" install (e.g. a pnpm-global shim shadowing the npm one) the
+ * updaters kept "successfully updating" forever, and eventually two concurrent
+ * installs collided mid-rename (npm stages by renaming the package dir aside
+ * to a hidden `.hq-cli-XXXX` dir), gutting the install: no package.json, no
+ * bin/hq. This lock makes losing that race impossible for cooperating actors.
+ *
+ * ── CROSS-REPO CONTRACT ─────────────────────────────────────────────────────
+ * The lock file path and JSON shape below are a contract shared with the
+ * hq-sync Rust menubar app, which honors the SAME file before running its own
+ * CLI updates. Do not change either without a coordinated hq-sync release.
+ *
+ *   Path:    $HOME/.hq/locks/cli-update.lock
+ *   Content: JSON object with exactly these fields:
+ *     {
+ *       "pid":       <number>  — owning process id,
+ *       "startedAt": <string>  — ISO-8601 acquisition timestamp,
+ *       "tool":      <string>  — which actor holds it (e.g. "hq-cli-version-gate"),
+ *       "version":   <string>  — the holder's own version
+ *     }
+ *   Staleness: a holder is stale when `startedAt` is older than 10 minutes OR
+ *   its `pid` is no longer alive (`kill(pid, 0)` → ESRCH). A stale lock may be
+ *   removed and re-acquired; a fresh one means "someone else is installing the
+ *   very version you want — skip".
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ * Mechanics: acquisition is a single atomic `open(…, 'wx')` (O_CREAT|O_EXCL) —
+ * no mkdir dance, no read-then-write window. Unparseable lock content is
+ * treated as stale (a torn write from a crashed holder must not wedge updates
+ * forever). Everything is best-effort: any unexpected filesystem error reads
+ * as "lock held", because the callers' shared philosophy is that updating is
+ * optional and the CLI keeps working either way.
+ */
+/** A held lock older than this is treated as abandoned (crashed owner). */
+export declare const UPDATE_LOCK_STALE_MS: number;
+/** `tool` recorded when this CLI takes the lock. */
+export declare const UPDATE_LOCK_TOOL = "hq-cli-version-gate";
+export interface UpdateLockInfo {
+    pid: number;
+    startedAt: string;
+    tool: string;
+    version: string;
+}
+export interface UpdateLockHandle {
+    /** Absolute path of the held lock file. */
+    path: string;
+    /** Delete the lock file. Idempotent, never throws. */
+    release: () => void;
+}
+/** Injectable knobs so contention/staleness are unit-testable hermetically. */
+export interface UpdateLockOptions {
+    lockPath?: string;
+    now?: number;
+    /** Override liveness probe (defaults to `process.kill(pid, 0)`). */
+    isPidAlive?: (pid: number) => boolean;
+    tool?: string;
+    version?: string;
+}
+export declare function updateLockPath(): string;
+/**
+ * Whether an existing lock's recorded holder is safe to displace: its
+ * `startedAt` is older than {@link UPDATE_LOCK_STALE_MS}, or its pid is dead.
+ * Unreadable / malformed content is stale by definition — only a crashed or
+ * interrupted holder leaves one behind, and treating it as fresh would block
+ * every future update on this machine.
+ */
+export declare function isLockStale(raw: string | null, now: number, isPidAlive: (pid: number) => boolean): boolean;
+/**
+ * Take the machine-wide CLI-update lock, or return `null` when a fresh holder
+ * has it (this process should skip its install). A stale holder is removed and
+ * acquisition retried exactly once — two genuinely-racing processes still
+ * serialize correctly because the retry goes back through O_EXCL.
+ *
+ * Callers MUST release in a `finally` around the install.
+ */
+export declare function acquireUpdateLock(options?: UpdateLockOptions): UpdateLockHandle | null;
+//# sourceMappingURL=update-lock.d.ts.map

package/dist/utils/update-lock.js

@@ -0,0 +1,173 @@
+/**
+ * Shared advisory cross-process lock serializing every actor that runs
+ * `npm install -g @indigoai-us/hq-cli` (or the pnpm/bun equivalent) against
+ * the same machine.
+ *
+ * Why: production logs showed FOUR independent updaters — this CLI's hard
+ * version-gate, the soft self-updater, and updaters inside the hq-sync menubar
+ * app — each firing `npm install -g` with no coordination. On a machine with a
+ * second "ghost" install (e.g. a pnpm-global shim shadowing the npm one) the
+ * updaters kept "successfully updating" forever, and eventually two concurrent
+ * installs collided mid-rename (npm stages by renaming the package dir aside
+ * to a hidden `.hq-cli-XXXX` dir), gutting the install: no package.json, no
+ * bin/hq. This lock makes losing that race impossible for cooperating actors.
+ *
+ * ── CROSS-REPO CONTRACT ─────────────────────────────────────────────────────
+ * The lock file path and JSON shape below are a contract shared with the
+ * hq-sync Rust menubar app, which honors the SAME file before running its own
+ * CLI updates. Do not change either without a coordinated hq-sync release.
+ *
+ *   Path:    $HOME/.hq/locks/cli-update.lock
+ *   Content: JSON object with exactly these fields:
+ *     {
+ *       "pid":       <number>  — owning process id,
+ *       "startedAt": <string>  — ISO-8601 acquisition timestamp,
+ *       "tool":      <string>  — which actor holds it (e.g. "hq-cli-version-gate"),
+ *       "version":   <string>  — the holder's own version
+ *     }
+ *   Staleness: a holder is stale when `startedAt` is older than 10 minutes OR
+ *   its `pid` is no longer alive (`kill(pid, 0)` → ESRCH). A stale lock may be
+ *   removed and re-acquired; a fresh one means "someone else is installing the
+ *   very version you want — skip".
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ * Mechanics: acquisition is a single atomic `open(…, 'wx')` (O_CREAT|O_EXCL) —
+ * no mkdir dance, no read-then-write window. Unparseable lock content is
+ * treated as stale (a torn write from a crashed holder must not wedge updates
+ * forever). Everything is best-effort: any unexpected filesystem error reads
+ * as "lock held", because the callers' shared philosophy is that updating is
+ * optional and the CLI keeps working either way.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { CLI_VERSION } from "../cli-version.js";
+/** A held lock older than this is treated as abandoned (crashed owner). */
+export const UPDATE_LOCK_STALE_MS = 10 * 60 * 1000;
+/** `tool` recorded when this CLI takes the lock. */
+export const UPDATE_LOCK_TOOL = "hq-cli-version-gate";
+export function updateLockPath() {
+    return path.join(os.homedir(), ".hq", "locks", "cli-update.lock");
+}
+function defaultIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH — no such process. EPERM means it exists but is not ours; that
+        // still counts as alive (we must not steal a root-owned updater's lock).
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Whether an existing lock's recorded holder is safe to displace: its
+ * `startedAt` is older than {@link UPDATE_LOCK_STALE_MS}, or its pid is dead.
+ * Unreadable / malformed content is stale by definition — only a crashed or
+ * interrupted holder leaves one behind, and treating it as fresh would block
+ * every future update on this machine.
+ */
+export function isLockStale(raw, now, isPidAlive) {
+    if (raw == null)
+        return true;
+    let info;
+    try {
+        info = JSON.parse(raw);
+    }
+    catch {
+        return true;
+    }
+    if (typeof info.pid !== "number" || typeof info.startedAt !== "string") {
+        return true;
+    }
+    const startedAt = Date.parse(info.startedAt);
+    if (Number.isNaN(startedAt))
+        return true;
+    if (now - startedAt > UPDATE_LOCK_STALE_MS)
+        return true;
+    if (!isPidAlive(info.pid))
+        return true;
+    return false;
+}
+function tryCreate(lockPath, body) {
+    let fd;
+    try {
+        // 'wx' — O_CREAT|O_EXCL|O_WRONLY: fails atomically if the file exists.
+        fd = fs.openSync(lockPath, "wx");
+    }
+    catch {
+        return null;
+    }
+    try {
+        fs.writeSync(fd, body);
+    }
+    catch {
+        // A lock we created but could not stamp is still OURS — keep it.
+    }
+    finally {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            // already closed
+        }
+    }
+    return {
+        path: lockPath,
+        release: () => {
+            try {
+                fs.rmSync(lockPath, { force: true });
+            }
+            catch {
+                // best-effort lock cleanup
+            }
+        },
+    };
+}
+/**
+ * Take the machine-wide CLI-update lock, or return `null` when a fresh holder
+ * has it (this process should skip its install). A stale holder is removed and
+ * acquisition retried exactly once — two genuinely-racing processes still
+ * serialize correctly because the retry goes back through O_EXCL.
+ *
+ * Callers MUST release in a `finally` around the install.
+ */
+export function acquireUpdateLock(options = {}) {
+    const lockPath = options.lockPath ?? updateLockPath();
+    const now = options.now ?? Date.now();
+    const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
+    const info = {
+        pid: process.pid,
+        startedAt: new Date(now).toISOString(),
+        tool: options.tool ?? UPDATE_LOCK_TOOL,
+        version: options.version ?? CLI_VERSION,
+    };
+    const body = JSON.stringify(info);
+    try {
+        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    }
+    catch {
+        return null; // can't even create ~/.hq/locks — treat as held, skip update
+    }
+    const first = tryCreate(lockPath, body);
+    if (first)
+        return first;
+    // Lock exists. Fresh holder → back off. Stale → remove and retry ONCE.
+    let raw;
+    try {
+        raw = fs.readFileSync(lockPath, "utf-8");
+    }
+    catch {
+        raw = null; // vanished (holder just released) or unreadable — stale path
+    }
+    if (!isLockStale(raw, now, isPidAlive))
+        return null;
+    try {
+        fs.rmSync(lockPath, { force: true });
+    }
+    catch {
+        return null;
+    }
+    return tryCreate(lockPath, body);
+}
+//# sourceMappingURL=update-lock.js.map

package/dist/utils/version-gate.d.ts

@@ -28,6 +28,7 @@
  * to silence both check + gate).
  */
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
+import { type UpdateLockHandle } from "./update-lock.js";
 /** Which package manager owns the running global install. */
 export type InstallManager = "npm" | "pnpm" | "bun";
 export interface VersionCheckResponse {
@@ -250,21 +251,60 @@ declare function performUpdate(command: string, runner?: UpdateRunner): UpdateRe
  */
 declare function nudgeUpdateRecommended(decision: VersionCheckResponse, install?: RunningInstall): void;
 /**
- * Hard enforcement when the server says we're below `minVersion`. Print a
- * red banner, attempt the update, then exit so the user reruns against the
- * fresh binary. Sequence chosen so a user with a broken `npm` global prefix
- * still gets a clear error rather than an opaque silent failure.
+ * The `hq` binary an ordinary shell PATH lookup would run, or null when it
+ * can't be resolved. Uses `command -v` through `/bin/sh` (POSIX) / `where`
+ * (Windows) rather than trusting our own install path — the whole point is to
+ * see what the USER's next invocation resolves.
+ */
+export declare function resolveHqOnPath(): string | null;
+/** `<bin> --version` output (trimmed), or null on any failure/timeout. */
+export declare function probeCliVersion(bin: string): string | null;
+/**
+ * Read-your-writes convergence check, run after an install reports success.
  *
- * Exit codes:
- *   0 — update succeeded; user must rerun their command
- *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
+ * A "successful" `npm install -g` proves only that the npm prefix was
+ * rewritten — NOT that the `hq` the user's PATH resolves is the copy that was
+ * just installed. On a machine with a second "ghost" install (e.g. a
+ * pnpm-global shim at `~/Library/pnpm/bin/hq` shadowing the npm bin dir),
+ * every updater on the box probes the ghost's version, sees it stale, installs
+ * into the npm prefix, reports success, and repeats forever — the production
+ * updater-war this fix exists for. Detect the divergence here, warn ONCE with
+ * the exact shadowing path, and never retry: no number of retries into the
+ * same prefix can change what PATH resolves.
+ *
+ * Advisory only — resolution failure warns once and continues; nothing in
+ * here may crash or block the CLI.
  */
-declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: {
+export declare function checkUpdateConvergence(targetVersion: string, deps?: {
+    resolveBin?: () => string | null;
+    probeVersion?: (bin: string) => string | null;
+}): void;
+/** Injectable surface for {@link enforceUpdateRequired} (unit tests). */
+interface EnforceUpdateDeps {
     performUpdateString?: (command: string) => UpdateResult;
     resolveInstall?: () => RunningInstall;
     runner?: UpdateRunner;
     cleanStale?: (prefix: string) => string[];
-}): never;
+    acquireLock?: () => UpdateLockHandle | null;
+    checkConvergence?: (targetVersion: string) => void;
+}
+/**
+ * Hard enforcement when the server says we're below `minVersion`. Print a
+ * red banner, take the machine-wide update lock, attempt the update, then
+ * exit so the user reruns against the fresh binary. Sequence chosen so a user
+ * with a broken `npm` global prefix still gets a clear error rather than an
+ * opaque silent failure.
+ *
+ * When another updater already holds the lock (fresh, live holder) the gate
+ * SKIPS the install and RETURNS, letting the CLI continue on the current
+ * version — the gate must never break the CLI, and the lock holder is
+ * installing the very version we want anyway.
+ *
+ * Exit codes:
+ *   0 — update succeeded; user must rerun their command
+ *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
+ */
+declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: EnforceUpdateDeps): void;
 /**
  * Public entry point. Call before commander parses argv. Blocks the CLI on
  * network IO for up to FETCH_TIMEOUT_MS — acceptable because the alternative
@@ -291,8 +331,12 @@ export declare function enforceVersionGate(onUpdateRecommended?: (decision: Vers
 export declare function shouldSkipGate(argv: readonly string[]): boolean;
 export declare const __test__: {
     CLIENT_ID: string;
+    CONVERGENCE_TIMEOUT_MS: number;
     ENDPOINT_PATH: string;
     FETCH_TIMEOUT_MS: number;
+    checkUpdateConvergence: typeof checkUpdateConvergence;
+    probeCliVersion: typeof probeCliVersion;
+    resolveHqOnPath: typeof resolveHqOnPath;
     buildBunInstallArgv: typeof buildBunInstallArgv;
     buildPnpmInstallArgv: typeof buildPnpmInstallArgv;
     buildPrefixedInstallArgv: typeof buildPrefixedInstallArgv;

package/dist/utils/version-gate.js

@@ -36,6 +36,7 @@ import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
+import { acquireUpdateLock, } from "./update-lock.js";
 const CLIENT_ID = "hq-cli";
 const ENDPOINT_PATH = "/v1/client-version/check";
 const FETCH_TIMEOUT_MS = 3_000;
@@ -514,11 +515,103 @@ function nudgeUpdateRecommended(decision, install = resolveRunningInstall()) {
         console.error(chalk.dim(`  Update: ${command}`));
     }
 }
+/** Timeout for the read-your-writes PATH/version probes below. A broken or
+ * hung shell must not stall the gate — the probes are advisory only. */
+const CONVERGENCE_TIMEOUT_MS = 3_000;
+/**
+ * The `hq` binary an ordinary shell PATH lookup would run, or null when it
+ * can't be resolved. Uses `command -v` through `/bin/sh` (POSIX) / `where`
+ * (Windows) rather than trusting our own install path — the whole point is to
+ * see what the USER's next invocation resolves.
+ */
+export function resolveHqOnPath() {
+    try {
+        const probe = process.platform === "win32"
+            ? spawnSync("where", ["hq"], {
+                encoding: "utf-8",
+                timeout: CONVERGENCE_TIMEOUT_MS,
+            })
+            : spawnSync("/bin/sh", ["-c", "command -v hq"], {
+                encoding: "utf-8",
+                timeout: CONVERGENCE_TIMEOUT_MS,
+            });
+        if (probe.error || probe.status !== 0)
+            return null;
+        const first = (probe.stdout ?? "")
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)[0];
+        return first ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `<bin> --version` output (trimmed), or null on any failure/timeout. */
+export function probeCliVersion(bin) {
+    try {
+        const result = spawnSync(bin, ["--version"], {
+            encoding: "utf-8",
+            timeout: CONVERGENCE_TIMEOUT_MS,
+        });
+        if (result.error || result.status !== 0)
+            return null;
+        const out = (result.stdout ?? "").trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read-your-writes convergence check, run after an install reports success.
+ *
+ * A "successful" `npm install -g` proves only that the npm prefix was
+ * rewritten — NOT that the `hq` the user's PATH resolves is the copy that was
+ * just installed. On a machine with a second "ghost" install (e.g. a
+ * pnpm-global shim at `~/Library/pnpm/bin/hq` shadowing the npm bin dir),
+ * every updater on the box probes the ghost's version, sees it stale, installs
+ * into the npm prefix, reports success, and repeats forever — the production
+ * updater-war this fix exists for. Detect the divergence here, warn ONCE with
+ * the exact shadowing path, and never retry: no number of retries into the
+ * same prefix can change what PATH resolves.
+ *
+ * Advisory only — resolution failure warns once and continues; nothing in
+ * here may crash or block the CLI.
+ */
+export function checkUpdateConvergence(targetVersion, deps = {}) {
+    try {
+        const bin = (deps.resolveBin ?? resolveHqOnPath)();
+        if (!bin) {
+            console.error(chalk.yellow("⚠ Updated, but couldn't resolve `hq` on PATH to verify the new version took effect."));
+            return;
+        }
+        const reported = (deps.probeVersion ?? probeCliVersion)(bin);
+        if (!reported) {
+            console.error(chalk.yellow(`⚠ Updated, but \`${bin} --version\` did not respond — couldn't verify the new version took effect.`));
+            return;
+        }
+        if (reported === targetVersion)
+            return; // converged — the normal case
+        console.error(chalk.yellow(`⚠ hq updated to ${targetVersion} but PATH still resolves ${bin} at version ${reported} — ` +
+            `a second install is shadowing the managed one. Remove it (e.g. \`pnpm remove -g ${CLI_NAME}\`) ` +
+            "or the updater will loop forever."));
+    }
+    catch {
+        // Verification is best-effort; never break the CLI over a probe.
+    }
+}
 /**
  * Hard enforcement when the server says we're below `minVersion`. Print a
- * red banner, attempt the update, then exit so the user reruns against the
- * fresh binary. Sequence chosen so a user with a broken `npm` global prefix
- * still gets a clear error rather than an opaque silent failure.
+ * red banner, take the machine-wide update lock, attempt the update, then
+ * exit so the user reruns against the fresh binary. Sequence chosen so a user
+ * with a broken `npm` global prefix still gets a clear error rather than an
+ * opaque silent failure.
+ *
+ * When another updater already holds the lock (fresh, live holder) the gate
+ * SKIPS the install and RETURNS, letting the CLI continue on the current
+ * version — the gate must never break the CLI, and the lock holder is
+ * installing the very version we want anyway.
  *
  * Exit codes:
  *   0 — update succeeded; user must rerun their command
@@ -545,6 +638,38 @@ function enforceUpdateRequired(decision, deps = {}) {
         }
         process.exit(75);
     }
+    // Serialize against every other updater on the machine (other hq processes,
+    // the hq-sync menubar app) via the shared advisory lock — see update-lock.ts
+    // for the cross-repo contract. A fresh holder means someone else is already
+    // installing the version we want: skip and continue on the current version
+    // (the gate must never break the CLI).
+    const lock = (deps.acquireLock ?? acquireUpdateLock)();
+    if (!lock) {
+        console.error(chalk.dim("  Another hq updater is already installing (update lock held); continuing on the current version."));
+        return;
+    }
+    let exitCode;
+    try {
+        exitCode = attemptRequiredUpdate(decision, deps, install);
+    }
+    finally {
+        // `process.exit` skips `finally` blocks, so the exit itself lives OUTSIDE
+        // the lock scope; this `finally` releases on the normal path and on any
+        // unexpected throw from the install attempt.
+        lock.release();
+    }
+    process.exit(exitCode);
+}
+/**
+ * The install attempt itself (npm/pnpm/bun routing, stale-partial cleanup,
+ * sudo fallback, post-success convergence check). Runs with the machine-wide
+ * update lock held. Returns the process exit code: 0 on success, 75
+ * (EX_TEMPFAIL) on failure.
+ */
+function attemptRequiredUpdate(decision, deps, install) {
+    const command = decision.updateCommand;
+    const isManagedOutsideNpm = install.manager !== "npm";
+    const prefix = install.prefix;
     const runner = deps.runner ?? runUpdateCommand;
     // Resolve the concrete install argv once so the sudo fallback below can re-run
     // the EXACT same command under elevation.
@@ -641,10 +766,14 @@ function enforceUpdateRequired(decision, deps = {}) {
         if (isManagedOutsideNpm && result.code === "ENOENT" && command) {
             console.error(chalk.dim(`  (hq-pro suggests \`${command}\` — that is for npm-managed installs; use it only if you have switched this install to npm.)`));
         }
-        process.exit(75);
+        return 75;
     }
     console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
-    process.exit(0);
+    // Read-your-writes: a "successful" install into the npm prefix does not
+    // prove the user's PATH resolves it. Warn (once, no retry) when a ghost
+    // install is shadowing the copy we just wrote — see checkUpdateConvergence.
+    (deps.checkConvergence ?? checkUpdateConvergence)(decision.latestVersion);
+    return 0;
 }
 export async function enforceVersionGate(onUpdateRecommended) {
     if (isOptedOut())
@@ -658,7 +787,10 @@ export async function enforceVersionGate(onUpdateRecommended) {
     // neither downstream path repeats it.
     const install = resolveRunningInstall();
     if (decision.updateRequired) {
-        enforceUpdateRequired(decision, { resolveInstall: () => install }); // exits process
+        // Exits the process, EXCEPT when another updater holds the shared update
+        // lock — then it returns and the CLI continues on the current version.
+        enforceUpdateRequired(decision, { resolveInstall: () => install });
+        return "continue";
     }
     if (decision.updateRecommended) {
         if (onUpdateRecommended) {
@@ -682,8 +814,12 @@ export function shouldSkipGate(argv) {
 }
 export const __test__ = {
     CLIENT_ID,
+    CONVERGENCE_TIMEOUT_MS,
     ENDPOINT_PATH,
     FETCH_TIMEOUT_MS,
+    checkUpdateConvergence,
+    probeCliVersion,
+    resolveHqOnPath,
     buildBunInstallArgv,
     buildPnpmInstallArgv,
     buildPrefixedInstallArgv,

package/package.json

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