@indigoai-us/hq-cli 5.261.0 → 5.263.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [5.263.0] — 2026-09-28
+
+### Fixed
+
+- The version gate compares offers with the running CLI and recognizes
+  generated global shims before reporting a PATH shadow.
+
+## [5.262.0] — 2026-09-28
+
+### Added
+
+- The `checkpoint.ontology.concept-project-link` flag (off by default) lets
+  checkpoint ontology link a knowledge concept whose alias is ambiguous to the
+  one project with the same canonical name, such as HQ. It writes nothing.
+
+### Fixed
+
+- `hq doctor --live-runtimes` uses a Windows `.cmd` shim only when the sibling file exists.
+- Flag reads validate company UIDs before registry requests while preserving local
+  override precedence; Work Mesh ignores malformed UID overrides.
+
 ## [5.261.0] — 2026-09-28
 
 ### Fixed

package/dist/lib/checkpoint-ontology/apply.js

@@ -370,6 +370,21 @@ export function applyOntologyRun(options) {
             }
             continue;
         }
+        if (resolved.tier === "ambiguous_alias") {
+            // checkpoint.ontology.concept-project-link: a knowledge concept whose name is the
+            // canonical name of exactly one project links to that project. Nothing is written.
+            // Like the tier 1 and 2 links above, it runs before the stopword guard,
+            // which only stops new entities.
+            const projects = plan.concept_project_link === true && input.kind === "knowledge" && candidate.type === "concept"
+                ? [...(index.canonical.get(entityKey("project", normalizeEntityName(canonical, "project"))) ?? [])]
+                : [];
+            if (projects.length === 1) {
+                const linked = index.byRel.get(projects[0]);
+                report.matched += 1;
+                report.links.push({ input: candidate.input, action: "link", type: linked.type, canonical_name: linked.canonical_name, path: projects[0] });
+                continue;
+            }
+        }
         // A generic word never becomes a new entity, whatever else it collides with.
         if (isRejectedName(normalizeEntityName(canonical, candidate.type))) {
             note(report.rejected, "stopword");

package/dist/lib/checkpoint-ontology/plan.d.ts

@@ -78,6 +78,17 @@ export declare const FIRST_NAME_PEOPLE_FLAG = "checkpoint.ontology.first-name-pe
  * to 0.803 and cost recall 0.023 on a replay of six runs.
  */
 export declare const SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG = "checkpoint.ontology.skip-ambiguous-concept-links";
+/**
+ * A knowledge concept candidate whose name is an alias of more than one
+ * entity, and which apply would defer as `ambiguous_alias`, links instead to
+ * the one project whose canonical name it is (`HQ` typed as a concept beside
+ * `project/HQ` and several concepts aliased `HQ`). The plan carries
+ * `concept_project_link: true`. CO-51: over six runs of the shipping config
+ * the model typed HQ as a concept in some runs and not others, and the
+ * deferral lost 61 gold links; a replay of this rule raised recall from 0.639
+ * to 0.709 at precision 0.747 to 0.731 (61 of the 63 added links are HQ).
+ */
+export declare const CONCEPT_PROJECT_LINK_FLAG = "checkpoint.ontology.concept-project-link";
 export declare const PLAN_FILE = "ontology-plan.json";
 export declare const CANDIDATES_FILE = "ontology-candidates.json";
 export declare const REPORT_FILE = "ontology-report.json";
@@ -150,6 +161,8 @@ export interface OntologyPlan {
     first_name_people?: true;
     /** Set by checkpoint.ontology.skip-ambiguous-concept-links: apply rejects a knowledge link to a concept whose name another type also holds. */
     skip_ambiguous_concept_links?: true;
+    /** Set by checkpoint.ontology.concept-project-link: apply links a knowledge concept with an ambiguous alias to the one project of that canonical name. */
+    concept_project_link?: true;
     inputs: PlanInput[];
     /** The session's summary, decisions and learnings, for the `session` input. */
     session_text: string | null;

package/dist/lib/checkpoint-ontology/plan.js

@@ -82,6 +82,17 @@ export const FIRST_NAME_PEOPLE_FLAG = "checkpoint.ontology.first-name-people";
  * to 0.803 and cost recall 0.023 on a replay of six runs.
  */
 export const SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG = "checkpoint.ontology.skip-ambiguous-concept-links";
+/**
+ * A knowledge concept candidate whose name is an alias of more than one
+ * entity, and which apply would defer as `ambiguous_alias`, links instead to
+ * the one project whose canonical name it is (`HQ` typed as a concept beside
+ * `project/HQ` and several concepts aliased `HQ`). The plan carries
+ * `concept_project_link: true`. CO-51: over six runs of the shipping config
+ * the model typed HQ as a concept in some runs and not others, and the
+ * deferral lost 61 gold links; a replay of this rule raised recall from 0.639
+ * to 0.709 at precision 0.747 to 0.731 (61 of the 63 added links are HQ).
+ */
+export const CONCEPT_PROJECT_LINK_FLAG = "checkpoint.ontology.concept-project-link";
 export const PLAN_FILE = "ontology-plan.json";
 export const CANDIDATES_FILE = "ontology-candidates.json";
 export const REPORT_FILE = "ontology-report.json";
@@ -265,6 +276,7 @@ export async function planOntologyRun(options) {
     const noLinkAliases = await options.readFlag(NO_LINK_ALIASES_FLAG, company);
     const firstNamePeople = await options.readFlag(FIRST_NAME_PEOPLE_FLAG, company);
     const skipAmbiguousConceptLinks = await options.readFlag(SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG, company);
+    const conceptProjectLink = await options.readFlag(CONCEPT_PROJECT_LINK_FLAG, company);
     const touched = sessionTouched(hqRoot, company, payload.files);
     // A first run takes its boundary from the entity tree, so the ledger is
     // refreshed before merge-back moves any `last_updated` forward.
@@ -380,6 +392,7 @@ export async function planOntologyRun(options) {
         ...(noLinkAliases ? { link_aliases: false } : {}),
         ...(firstNamePeople ? { first_name_people: true } : {}),
         ...(skipAmbiguousConceptLinks ? { skip_ambiguous_concept_links: true } : {}),
+        ...(conceptProjectLink ? { concept_project_link: true } : {}),
         inputs,
         session_text: sessionText,
         pending_after_run: remaining,

package/dist/lib/doctor/checks/runtime-health.d.ts

@@ -76,6 +76,8 @@ export interface ProbeOutcome {
 export interface RuntimeHealthDeps {
     /** Resolve an executable against PATH; null when not found. */
     resolveBinary?: (binary: string) => string | null;
+    /** Check whether a Windows command shim exists next to its resolved binary. */
+    fileExists?: (file: string) => boolean;
     /** Execute one probe. The default spawns from the OS temp dir. */
     execProbe?: (file: string, args: string[], timeoutMs: number) => Promise<ProbeOutcome>;
     /** Per-probe timeout. Default {@link DEFAULT_PROBE_TIMEOUT_MS}. */

package/dist/lib/doctor/checks/runtime-health.js

@@ -103,7 +103,7 @@ async function runRuntimeChecks(context, deps) {
     const resolved = {
         resolveBinary: deps.resolveBinary ?? resolveOnPath,
         execProbe: deps.execProbe ??
-            ((file, args, timeoutMs) => defaultExecProbe(file, args, timeoutMs, deps.platform ?? process.platform)),
+            ((file, args, timeoutMs) => defaultExecProbe(file, args, timeoutMs, deps.platform ?? process.platform, deps.fileExists ?? fs.existsSync)),
         timeoutMs: deps.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS,
         live: context.liveRuntimes === true,
     };
@@ -270,10 +270,13 @@ export function resolveOnPath(binary) {
  * CLI that reads piped stdin in non-TTY mode — blocks forever on a pipe that
  * never reaches EOF, which turns every probe into a timeout.
  */
-function defaultExecProbe(file, args, timeoutMs, platform) {
+function defaultExecProbe(file, args, timeoutMs, platform, fileExists) {
     return new Promise((resolve) => {
-        const command = platform === "win32" && !/\.(?:cmd|bat|exe|com)$/i.test(file)
-            ? `${file}.cmd`
+        const cmdSibling = `${file}.cmd`;
+        const command = platform === "win32" &&
+            !/\.(?:cmd|bat|exe|com)$/i.test(file) &&
+            fileExists(cmdSibling)
+            ? cmdSibling
             : file;
         const plan = planCommandSpawn(command, args, platform);
         const child = spawn(plan.cmd, plan.args, {

package/dist/lib/lanes/manager-status-gate.js

@@ -96,8 +96,12 @@ export async function resolveManagerStatusGateForLane(root, lane, options = {})
     const reportError = options.onError ?? ((err) => logManagerStatusGateFailure(lane, err));
     let enabled;
     try {
+        const company = lane.company ?? lane.mesh_company ?? undefined;
         enabled = await (options.readFlag ?? readLanesRegistryFlag)(MANAGER_STATUS_GATE_FLAG, {
-            company: lane.company ?? lane.mesh_company ?? undefined,
+            company,
+            ...(company ? {
+                companyUidSource: lane.company ? "lane.company.uid" : "lane.mesh_company.uid",
+            } : {}),
             env: options.env,
         });
     }

package/dist/lib/lanes/outpost-pruner-install.js

@@ -161,11 +161,22 @@ export function installOutpostPrunerTimers(options) {
     const nodeBinary = options.nodeBinary ?? resolveNodeBinary();
     const hqBinary = options.hqBinary ?? resolveHqBinary();
     const home = options.home ?? os.homedir();
-    const flagApiUrl = resolveFlagRegistryEndpoint(options.flagApiUrl);
     const companyUid = (options.companyUid ?? process.env.HQ_COMPANY_UID ?? "").trim();
+    const companyUidSource = options.companyUid !== undefined
+        ? "install option companyUid"
+        : "HQ_COMPANY_UID";
     if (!companyUid) {
         throw new TypeError("install requires HQ_COMPANY_UID for the timer services");
     }
+    if (!companyUid.startsWith("cmp_")) {
+        process.stderr.write(`${JSON.stringify({
+            event: "outpost.worktree_pruner.install_invalid_company_uid",
+            source: companyUidSource,
+            expected_prefix: "cmp_",
+        })}\n`);
+        throw new TypeError(`${companyUidSource} must start with cmp_ before installing the timer services`);
+    }
+    const flagApiUrl = resolveFlagRegistryEndpoint(options.flagApiUrl);
     const flagEnvironment = [
         systemdEnvironment("HQ_FLAGS_API_URL", flagApiUrl),
         systemdEnvironment("HQ_COMPANY_UID", companyUid),

package/dist/lib/lanes/outpost-worktree-pruner-flag.js

@@ -22,7 +22,6 @@ function reportFlagFailure(error) {
 }
 export async function outpostWorktreePrunerEnabled(dependencies = {}) {
     const env = dependencies.env ?? process.env;
-    const endpoint = resolveFlagRegistryEndpoint(undefined, env);
     const companyUid = env.HQ_COMPANY_UID?.trim() || "";
     if (!companyUid) {
         process.stderr.write(`${JSON.stringify({
@@ -35,6 +34,17 @@ export async function outpostWorktreePrunerEnabled(dependencies = {}) {
         })}\n`);
         return OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK;
     }
+    if (!companyUid.startsWith("cmp_")) {
+        process.stderr.write(`${JSON.stringify({
+            event: "outpost.worktree_pruner.invalid_company_uid",
+            flag: OUTPOST_WORKTREE_PRUNER_FLAG,
+            source: "HQ_COMPANY_UID",
+            expected_prefix: "cmp_",
+            fallback: OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK,
+        })}\n`);
+        return OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK;
+    }
+    const endpoint = resolveFlagRegistryEndpoint(undefined, env);
     const companySlug = env.HQ_COMPANY_SLUG?.trim() || "";
     let client;
     let enabled = OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK;

package/dist/lib/lanes/registry-flag.d.ts

@@ -12,6 +12,7 @@ export interface LanesFlagClient {
 export type LanesFlagClientFactory = (options: FlagClientOptions) => LanesFlagClient;
 export interface ReadLanesFlagOptions {
     company?: LaneCompanyRef | null;
+    companyUidSource?: string;
     env?: NodeJS.ProcessEnv;
     createClient?: LanesFlagClientFactory;
     getToken?: () => string | Promise<string>;

package/dist/lib/lanes/registry-flag.js

@@ -25,6 +25,16 @@ function reportReadFailure(flagKey, error) {
         fallback: false,
     })}\n`);
 }
+function reportInvalidCompanyUid(flagKey, source) {
+    const suffix = flagKey.replace(/^lanes\./, "").replaceAll(/[^a-zA-Z0-9]+/g, "_");
+    process.stderr.write(`${JSON.stringify({
+        event: `lanes.${suffix}.invalid_company_uid`,
+        flag: flagKey,
+        source,
+        expected_prefix: "cmp_",
+        fallback: false,
+    })}\n`);
+}
 function cacheKey(flagKey, company, endpoint) {
     return JSON.stringify([
         flagKey,
@@ -43,6 +53,11 @@ export async function readLanesRegistryFlag(flagKey, options = {}) {
     const localOverride = readLanesFlagLocalOverride(flagKey, env);
     if (localOverride !== null)
         return localOverride;
+    const companyUid = options.company?.uid?.trim();
+    if (companyUid && !companyUid.startsWith("cmp_")) {
+        reportInvalidCompanyUid(flagKey, options.companyUidSource ?? "company.uid");
+        return false;
+    }
     const endpoint = resolveFlagRegistryEndpoint(undefined, env);
     const key = cacheKey(flagKey, options.company, endpoint);
     const cached = registryReads.get(key);

package/dist/lib/lanes/watcher.js

@@ -646,8 +646,12 @@ async function settleManagerStatusGate(hqRoot, lane, manifestTurnId, at, deps, l
     const readFlag = deps.readManagerStatusGateFlag ?? readLanesRegistryFlag;
     let enabled = false;
     try {
+        const company = lane.company ?? lane.mesh_company ?? undefined;
         enabled = await readFlag(MANAGER_STATUS_GATE_FLAG, {
-            company: lane.company ?? lane.mesh_company ?? undefined,
+            company,
+            ...(company ? {
+                companyUidSource: lane.company ? "lane.company.uid" : "lane.mesh_company.uid",
+            } : {}),
         });
     }
     catch (err) {

package/dist/lib/mesh/api.d.ts

@@ -94,8 +94,8 @@ export declare function listActiveMembershipCompanies(token: string): Promise<Me
  *
  * Lists the caller's active companies via GET /membership/me and matches the
  * requested slug (case-insensitive). Does **not** honour HQ_COMPANY_UID /
- * HQ_WORK_MESH_COMPANY_UID env overrides or treat a raw `cmp_`/`co_` ref as
- * proof of membership without an active membership row.
+ * HQ_WORK_MESH_COMPANY_UID env overrides or treat a raw `cmp_` ref as proof
+ * of membership without an active membership row.
  *
  * Returns null when the caller is not an active member. Throws on transport /
  * auth failures so the caller can surface DEFAULT_COMPANY_UNAVAILABLE.

package/dist/lib/mesh/api.js

@@ -63,14 +63,27 @@ export async function meshJson(token, path, init = {}) {
     return data;
 }
 export async function resolveMeshCompany(token, company) {
-    const explicit = process.env.HQ_WORK_MESH_COMPANY_UID || process.env.HQ_COMPANY_UID;
-    if (explicit?.trim()) {
-        return { companyUid: explicit.trim(), companySlug: company || explicit.trim() };
-    }
-    if (company && /^(cmp|co)_/.test(company)) {
+    const meshOverride = process.env.HQ_WORK_MESH_COMPANY_UID?.trim();
+    const companyOverride = process.env.HQ_COMPANY_UID?.trim();
+    const explicit = meshOverride || companyOverride;
+    const explicitSource = meshOverride ? "HQ_WORK_MESH_COMPANY_UID" : "HQ_COMPANY_UID";
+    if (explicit && explicit.startsWith("cmp_")) {
+        return { companyUid: explicit, companySlug: company || explicit };
+    }
+    if (explicit) {
+        // hq-pro accepts companyUid only with the cmp_ prefix (flags-resolve.ts:145-150).
+        // Ignore a malformed UID override so it cannot become a request identity.
+        process.stderr.write(`${JSON.stringify({
+            event: "work_mesh.invalid_company_uid_override",
+            source: explicitSource,
+            expected_prefix: "cmp_",
+        })}\n`);
+    }
+    if (company?.startsWith("cmp_")) {
         return { companyUid: company, companySlug: company };
     }
-    const uid = await getCompanyUid(token, company);
+    const companySlug = company?.trim();
+    const uid = await getCompanyUid(token, companySlug || undefined);
     return { companyUid: uid, companySlug: company || uid };
 }
 /**
@@ -107,8 +120,8 @@ export async function listActiveMembershipCompanies(token) {
  *
  * Lists the caller's active companies via GET /membership/me and matches the
  * requested slug (case-insensitive). Does **not** honour HQ_COMPANY_UID /
- * HQ_WORK_MESH_COMPANY_UID env overrides or treat a raw `cmp_`/`co_` ref as
- * proof of membership without an active membership row.
+ * HQ_WORK_MESH_COMPANY_UID env overrides or treat a raw `cmp_` ref as proof
+ * of membership without an active membership row.
  *
  * Returns null when the caller is not an active member. Throws on transport /
  * auth failures so the caller can surface DEFAULT_COMPANY_UNAVAILABLE.

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

@@ -371,9 +371,10 @@ export declare function probeCliVersion(bin: string): string | null;
  * 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.
+ * updater-war this fix exists for. Detect a stale PATH result here, identify a
+ * distinct package managed by a supported global manager before calling it a
+ * shadow, 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.
@@ -381,6 +382,8 @@ export declare function probeCliVersion(bin: string): string | null;
 export declare function checkUpdateConvergence(targetVersion: string, deps?: {
     resolveBin?: () => string | null;
     probeVersion?: (bin: string) => string | null;
+    currentInstall?: () => RunningInstall;
+    packageRootForBin?: (bin: string) => string | null;
 }): boolean;
 /** Injectable surface for {@link enforceUpdateRequired} (unit tests). */
 interface EnforceUpdateDeps {

package/dist/utils/version-gate.js

@@ -30,7 +30,7 @@
 import { spawnSync } from "node:child_process";
 import { installPathCompatibilityEnabled } from "../lib/install-path-compatibility-flag.js";
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
-import { accessSync, closeSync, constants as fsConstants, existsSync, mkdtempSync, openSync, readdirSync, readFileSync, rmSync, } from "node:fs";
+import { accessSync, closeSync, constants as fsConstants, existsSync, mkdtempSync, openSync, readdirSync, realpathSync, readFileSync, rmSync, } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -46,8 +46,8 @@ const LATEST_PACKAGE_SPEC = `${CLI_NAME}@latest`;
 function isOptedOut() {
     return process.env.HQ_NO_UPDATE_CHECK === "1";
 }
-function findRunningPackageRoot() {
-    let dir = path.dirname(fileURLToPath(import.meta.url));
+function findCliPackageRoot(startDir) {
+    let dir = startDir;
     while (true) {
         try {
             const pkg = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf-8"));
@@ -63,6 +63,106 @@ function findRunningPackageRoot() {
         dir = parent;
     }
 }
+function findRunningPackageRoot() {
+    return findCliPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
+}
+/** Resolve an on-PATH executable back to the installed hq-cli package it loads. */
+function findPackageRootForExecutable(bin) {
+    try {
+        const packageRoot = findCliPackageRoot(path.dirname(realpathSync(bin)));
+        if (packageRoot)
+            return packageRoot;
+    }
+    catch {
+        // A missing or inaccessible executable may still be recoverable from the
+        // configured pnpm global layout below.
+    }
+    // pnpm emits shell/.cmd shims into its global bin directory. realpathSync()
+    // resolves symlinks, but a generated shim is a regular file, so walking up
+    // from its real path never reaches the package it invokes. Look up only the
+    // hq-cli package under the matching PNPM_HOME/global layout instead.
+    const binDir = path.dirname(bin);
+    const configuredHome = process.env.PNPM_HOME;
+    const inferredHome = path.basename(binDir).toLowerCase() === "bin"
+        ? path.dirname(binDir)
+        : binDir;
+    const candidateHomes = [configuredHome, inferredHome].filter((home, index, homes) => Boolean(home) && homes.findIndex((candidate) => candidate === home) === index);
+    const home = candidateHomes.find((candidate) => samePath(binDir, candidate) ||
+        samePath(binDir, path.join(candidate, "bin")));
+    if (!home)
+        return null;
+    const globalRoot = path.join(home, "global");
+    let storeVersions;
+    try {
+        storeVersions = readdirSync(globalRoot);
+    }
+    catch {
+        return null;
+    }
+    const packageSegments = CLI_NAME.split("/");
+    for (const storeVersion of storeVersions) {
+        const storeRoot = path.join(globalRoot, storeVersion);
+        const packageRoots = [
+            path.join(storeRoot, "node_modules", ...packageSegments),
+        ];
+        // pnpm v11 adds a hash between its global store version and node_modules.
+        // Its `vN` layout remains subject to the existing compatibility gate unless
+        // PNPM_HOME itself authorizes the global root via isPnpmManagedPackageDir.
+        if (/^v\d+$/.test(storeVersion)) {
+            try {
+                for (const hash of readdirSync(storeRoot)) {
+                    packageRoots.push(path.join(storeRoot, hash, "node_modules", ...packageSegments));
+                }
+            }
+            catch {
+                // A missing or unreadable version directory is simply not a candidate.
+            }
+        }
+        for (const candidate of packageRoots) {
+            const packageRoot = findCliPackageRoot(candidate);
+            if (packageRoot &&
+                samePath(packageRoot, candidate) &&
+                isPnpmManagedPackageDir(packageRoot, installPathCompatibilityEnabled())) {
+                return packageRoot;
+            }
+        }
+    }
+    return null;
+}
+function samePath(left, right) {
+    const canonical = (value) => {
+        try {
+            return realpathSync(value);
+        }
+        catch {
+            return path.resolve(value);
+        }
+    };
+    const a = canonical(left);
+    const b = canonical(right);
+    return process.platform === "win32"
+        ? a.toLowerCase() === b.toLowerCase()
+        : a === b;
+}
+function globalInstallManagerForPath(bin, packageRoot) {
+    if (isPnpmManagedPackageDir(packageRoot, installPathCompatibilityEnabled())) {
+        return "pnpm";
+    }
+    if (isBunManagedPackageDir(packageRoot))
+        return "bun";
+    const prefix = npmPrefixFromPackageDir(packageRoot);
+    if (!prefix)
+        return null;
+    const normalizedRoot = packageRoot.replace(/\\/g, "/");
+    const normalizedPrefix = prefix.replace(/\\/g, "/").replace(/\/$/, "");
+    // POSIX global npm packages live under <prefix>/lib/node_modules. On
+    // Windows npm puts hq.cmd directly in <prefix>, so also verify the bin's
+    // directory against the prefix-derived shim location there.
+    const posixGlobal = normalizedRoot.includes("/lib/node_modules/");
+    const windowsGlobal = process.platform === "win32" &&
+        samePath(path.dirname(bin), normalizedPrefix);
+    return posixGlobal || windowsGlobal ? "npm" : null;
+}
 export function npmPrefixFromPackageDir(pkgDir) {
     const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
     const segments = normalized.split("/");
@@ -768,7 +868,9 @@ function manualUpdateCommand(install, decision) {
  * remains for callers that pass no handler.
  */
 function nudgeUpdateRecommended(decision, install = resolveRunningInstall()) {
-    const msg = chalk.yellow(`⚠ A new version of hq-cli is available: ${decision.latestVersion} (current: ${decision.currentVersion}).`);
+    if (!isNewerVersion(decision.latestVersion, CLI_VERSION))
+        return;
+    const msg = chalk.yellow(`⚠ A new version of hq-cli is available: ${decision.latestVersion} (current: ${CLI_VERSION}).`);
     console.error(msg);
     // A local copy is not updated by any global command. Printing the server's
     // npm-shaped one would send the user to install a second copy that this
@@ -881,9 +983,10 @@ export function probeCliVersion(bin) {
  * 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.
+ * updater-war this fix exists for. Detect a stale PATH result here, identify a
+ * distinct package managed by a supported global manager before calling it a
+ * shadow, 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.
@@ -903,12 +1006,6 @@ export function checkUpdateConvergence(targetVersion, deps = {}) {
         }
         if (reported === targetVersion)
             return true; // 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."));
-        // The warning above fires for ANY mismatch — something other than the copy
-        // we just wrote is winning PATH resolution, which is worth saying either
-        // way. But only a STALE result disproves convergence.
         //
         // The install runs `@latest`, not `@<targetVersion>`, so it can legitimately
         // land a version NEWER than the `latestVersion` the gate was handed: the npm
@@ -923,6 +1020,36 @@ export function checkUpdateConvergence(targetVersion, deps = {}) {
             semver.gte(reportedSemver, targetSemver)) {
             return true;
         }
+        const runningInstall = (deps.currentInstall ?? resolveRunningInstall)();
+        const packageRoot = (deps.packageRootForBin ?? findPackageRootForExecutable)(bin);
+        const manager = packageRoot &&
+            runningInstall.packageRoot &&
+            !samePath(packageRoot, runningInstall.packageRoot)
+            ? globalInstallManagerForPath(bin, packageRoot)
+            : null;
+        let detail;
+        if (manager) {
+            const removeCommand = manager === "pnpm"
+                ? `pnpm remove -g ${CLI_NAME}`
+                : manager === "bun"
+                    ? `bun remove -g ${CLI_NAME}`
+                    : `npm uninstall -g ${CLI_NAME}`;
+            let realPath = bin;
+            try {
+                realPath = realpathSync(bin);
+            }
+            catch {
+                // Keep the shell-resolved path when a platform shim is not canonicalizable.
+            }
+            detail =
+                `PATH resolves ${realPath} at version ${reported} (manager: ${manager}); ` +
+                    `that second hq-cli install is shadowing the managed one. Remove it with \`${removeCommand}\`.`;
+        }
+        else {
+            detail =
+                `PATH resolves ${bin} at version ${reported}, but no second managed hq-cli install was confirmed.`;
+        }
+        console.error(chalk.yellow(`⚠ hq updated to ${targetVersion} but did not converge: ${detail}`));
         return false;
     }
     catch {
@@ -950,7 +1077,7 @@ export function checkUpdateConvergence(targetVersion, deps = {}) {
  * gate returns and lets the user's command run on the current version.
  */
 function enforceUpdateRequired(decision, deps = {}) {
-    const banner = chalk.red.bold(`✗ hq-cli ${decision.currentVersion} is below the minimum required version (${decision.minVersion}).`);
+    const banner = chalk.red.bold(`✗ hq-cli ${CLI_VERSION} is below the minimum required version (${decision.minVersion}).`);
     console.error(banner);
     if (decision.message)
         console.error(chalk.dim(`  ${decision.message}`));
@@ -976,8 +1103,8 @@ function enforceUpdateRequired(decision, deps = {}) {
     // stale dist-tag, a bad cache, a misconfigured pin), reinstalling it on every
     // invocation and announcing success each time is strictly worse than saying
     // so once.
-    if (!isNewerVersion(decision.latestVersion, decision.currentVersion)) {
-        console.error(chalk.red(`  Refusing to update: the offered version ${decision.latestVersion} is not newer than the installed ${decision.currentVersion}.`));
+    if (!isNewerVersion(decision.latestVersion, CLI_VERSION)) {
+        console.error(chalk.red(`  Refusing to update: the offered version ${decision.latestVersion} is not newer than the running ${CLI_VERSION}.`));
         console.error(chalk.dim("  This is a server-side or registry problem, not a local one — reinstalling would loop without ever converging."));
         process.exit(75);
     }

package/package.json

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