@indigoai-us/hq-cli 5.103.10 → 5.103.12

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [5.103.12] — 2026-08-20
+
+## [5.103.11] — 2026-08-20
+
+### Reverted
+
+- Reverted the 5.103.10 stop-gate anti-filler wording (#419). Demanding that an
+  agent "emit zero characters" after the checkpoint moved the noise instead of
+  removing it: agents that had stopped appending a meta-note began emitting a
+  bare `<br>` — markup they took to render as nothing — so the dangling line
+  under the reply survived in a third form. Each tightening only selects the
+  next-smallest token, so the wording lever is abandoned here and the branch
+  returns to its 5.103.9 text. The underlying conflict is structural: the gate
+  asks for silence at the one moment a model is least able to produce it, and
+  it only asks because it blocks AFTER a reply is already delivered. Fixing
+  that properly means not blocking in the already-replied case at all.
+
 ## [5.103.10] — 2026-08-20
 
 ### Fixed

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

@@ -390,7 +390,7 @@ set -uo pipefail
   # 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, then STOP - emit zero characters after the command. Ending a turn on a tool call with no trailing text is correct and expected here: it renders as the reply you already wrote followed by a collapsed checkpoint row. Do NOT append a sign-off, an acknowledgement, a status line, or any meta-note about the checkpoint itself - a dangling line such as "(reply already delivered above - turn complete)" is visible noise stuck under your reply, the same defect as repeating the reply. Silence is the finished state:\n\n'"$flags_spec" "$session_id" "$session_id")"
+    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")"
   fi

package/dist/commands/core-checkpoint.js

@@ -60,11 +60,8 @@ export const CHECKPOINT_REPLY_REMINDER = "checkpoint: REMINDER — this checkpoi
     "and it does NOT count as your reply. If this turn's substance (results, findings, " +
     "decisions, state changes, anything awaiting their input) has NOT yet been delivered to " +
     "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 and " +
-    "WITHOUT any closing note — no sign-off, no acknowledgement, no meta-comment about " +
-    "this checkpoint. The user has already seen that message; both repeating it and " +
-    "appending a dangling note leave visible noise under it. Emitting no further text at " +
-    "all is the correct, finished state.";
+    "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.";
 function printResult(line) {
     process.stdout.write(`${line}\n`);
 }

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.10",
+  "version": "5.103.12",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {