@indigoai-us/hq-cli 5.262.0 → 5.264.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [5.264.0] — 2026-09-28
+
+### Removed
+
+- The `checkpoint.ontology.entity-hints` flag and its per-input `known_entities`
+  list. It was never turned on outside measurement runs.
+
+## [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
@@ -13,6 +27,8 @@
 ### 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
 

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

@@ -10,7 +10,6 @@
 import { type CompanyBriefResult } from "./company-brief.js";
 import { type OntologyCompany } from "./company.js";
 import { type MultiWriterStart } from "./multi-writer.js";
-import { type EntityHint } from "./hints.js";
 import { type SyncClientVersions } from "./sync-client.js";
 export declare const ONTOLOGY_FLAG = "checkpoint.ontology";
 /**
@@ -41,13 +40,6 @@ export declare const GROK_BACKEND_FLAG = "checkpoint.ontology.grok-backend";
  * duplicate entities.
  */
 export declare const MULTI_WRITER_FLAG = "checkpoint.ontology.multi-writer";
-/**
- * Each knowledge input lists the existing entities its text names
- * (`known_entities`), and the model is told to use those names and to skip
- * table rows, paths and slugs. CO-41: 11 of 93 creates in the CO-39 grok-4.6
- * runs were model errors, 5 of them duplicates of an existing entity.
- */
-export declare const ENTITY_HINTS_FLAG = "checkpoint.ontology.entity-hints";
 /**
  * A candidate that links to an existing entity adds no aliases to it; the plan
  * carries `link_aliases: false` and apply honours it. CO-42: most aliases
@@ -138,8 +130,6 @@ export interface PlanInput {
     missing_refs?: string[];
     /** Run-directory-relative copy of `path` with annotator entity lists removed; same line numbers. */
     read_path?: string;
-    /** Existing entities this input's text names; only when `checkpoint.ontology.entity-hints` is on. */
-    known_entities?: EntityHint[];
 }
 export interface OntologyPlan {
     schema: typeof PLAN_SCHEMA;
@@ -208,7 +198,6 @@ export type PlanOutcome = {
     companyBrief?: CompanyBriefResult;
 };
 export declare const READ_PATH_INSTRUCTION = "When an input has read_path, read that file (relative to the run directory) instead of path, with the same line range. It is the same text with an older annotator's entity lists and entity links removed.";
-export declare const ENTITY_HINTS_INSTRUCTIONS: string[];
 export declare const PERSON_NAME_INSTRUCTION = "Name a person by the full name the input or the company's entities give, not a first name alone.";
 export declare const FIRST_NAME_PEOPLE_INSTRUCTION = "Name a person by the full name the input or the company's entities give. When neither gives more than a first name, name the person by that first name; do not leave them out.";
 export declare function ledgerPath(hqRoot: string, company: OntologyCompany): string;

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

@@ -13,7 +13,6 @@ import * as path from "node:path";
 import { writeCompanyBrief } from "./company-brief.js";
 import { resolveOntologyCompany, safeWriteFile, stateRoot } from "./company.js";
 import { startMultiWriterRun } from "./multi-writer.js";
-import { entityHints, wordWeights } from "./hints.js";
 import { checkSyncClient, readSyncClientVersions } from "./sync-client.js";
 import { buildEntityIndex, listKnowledgeFiles, listSignalFiles, readSignal } from "./tree.js";
 export const ONTOLOGY_FLAG = "checkpoint.ontology";
@@ -45,13 +44,6 @@ export const GROK_BACKEND_FLAG = "checkpoint.ontology.grok-backend";
  * duplicate entities.
  */
 export const MULTI_WRITER_FLAG = "checkpoint.ontology.multi-writer";
-/**
- * Each knowledge input lists the existing entities its text names
- * (`known_entities`), and the model is told to use those names and to skip
- * table rows, paths and slugs. CO-41: 11 of 93 creates in the CO-39 grok-4.6
- * runs were model errors, 5 of them duplicates of an existing entity.
- */
-export const ENTITY_HINTS_FLAG = "checkpoint.ontology.entity-hints";
 /**
  * A candidate that links to an existing entity adds no aliases to it; the plan
  * carries `link_aliases: false` and apply honours it. CO-42: most aliases
@@ -105,10 +97,6 @@ export const BUDGET = {
     chunkTokens: 12_000,
 };
 export const READ_PATH_INSTRUCTION = "When an input has read_path, read that file (relative to the run directory) instead of path, with the same line range. It is the same text with an older annotator's entity lists and entity links removed.";
-export const ENTITY_HINTS_INSTRUCTIONS = [
-    "A knowledge input's known_entities lists entities that already exist in the company and whose names appear in its text. When the input refers to one of them, under that name or another, use that entity's name and type exactly and do not name a new entity for it.",
-    "Skip rows of a glossary or translation table, file and directory paths, and names built from tags or slugs.",
-];
 export const PERSON_NAME_INSTRUCTION = "Name a person by the full name the input or the company's entities give, not a first name alone.";
 export const FIRST_NAME_PEOPLE_INSTRUCTION = "Name a person by the full name the input or the company's entities give. When neither gives more than a first name, name the person by that first name; do not leave them out.";
 const CANDIDATE_INSTRUCTIONS = [
@@ -272,7 +260,6 @@ export async function planOntologyRun(options) {
     const ignoreAnnotations = (await options.readFlag(IGNORE_ANNOTATIONS_FLAG, company)) && payload.backend === "grok";
     recordBackendPreference(hqRoot, company, await options.readFlag(GROK_BACKEND_FLAG, company));
     const multiWriterOn = await options.readFlag(MULTI_WRITER_FLAG, company);
-    const hintsOn = await options.readFlag(ENTITY_HINTS_FLAG, company);
     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);
@@ -289,15 +276,6 @@ export async function planOntologyRun(options) {
     const pending = Object.entries(ledger.entries)
         .filter(([, entry]) => entry.state === "pending" && entry.reason === "session-touched")
         .sort(([aRel, a], [bRel, b]) => a.mtime_ms - b.mtime_ms || aRel.localeCompare(bRel));
-    // Built after merge-back, so merged entities are hinted too.
-    let hintIndex = null;
-    const hintsFor = (text) => {
-        if (!hintIndex) {
-            const index = buildEntityIndex(company.dir);
-            hintIndex = { index, weights: wordWeights(index) };
-        }
-        return entityHints(hintIndex.index, hintIndex.weights, text);
-    };
     const inputs = [];
     let tokens = 0;
     let remaining = 0;
@@ -322,10 +300,6 @@ export async function planOntologyRun(options) {
             const cost = estTokens(Buffer.byteLength(lines.slice(start - 1, end).join("\n"), "utf8"));
             if (inputs.length >= BUDGET.maxInputs || tokens + cost > BUDGET.maxTokens)
                 break;
-            // The model reads the stripped copy when there is one; its line numbers match.
-            const knownEntities = hintsOn && kind === "knowledge"
-                ? hintsFor((cleaned ?? text).split("\n").slice(start - 1, end).join("\n"))
-                : null;
             inputs.push({
                 id: chunks.length > 1 ? `${rel}#${index}` : rel,
                 kind,
@@ -338,7 +312,6 @@ export async function planOntologyRun(options) {
                 chunk: chunks.length > 1 ? { index, count: chunks.length } : null,
                 ...(kind === "signal" ? { missing_refs: missingRefs(company.dir, rel) } : {}),
                 ...(readPath !== null ? { read_path: readPath } : {}),
-                ...(knownEntities !== null ? { known_entities: knownEntities } : {}),
             });
             tokens += cost;
         }
@@ -407,7 +380,6 @@ export async function planOntologyRun(options) {
             ...CANDIDATE_INSTRUCTIONS.slice(0, 3),
             ...(inputs.some((input) => input.read_path) ? [READ_PATH_INSTRUCTION] : []),
             `${CANDIDATE_INSTRUCTIONS[3]} ${firstNamePeople ? FIRST_NAME_PEOPLE_INSTRUCTION : PERSON_NAME_INSTRUCTION}`,
-            ...(inputs.some((input) => input.known_entities) ? ENTITY_HINTS_INSTRUCTIONS : []),
             ...CANDIDATE_INSTRUCTIONS.slice(4),
         ],
     };

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

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

@@ -1,41 +0,0 @@
-/**
- * Existing entities an input names, for `checkpoint.ontology.entity-hints`.
- *
- * The model never sees the company's entities, so it can only link one when it
- * happens to pick a name or alias the index holds. On the CO-39 fixtures it
- * created `SpaceXAI` beside `xAI`, `Indigo desktop app` beside `indigo-nx`
- * (alias `Indigo desktop repo`) and `hq-work-site` beside `Indigo Workspace`
- * (workspace/checkpoint-ontology/analysis/co41-wrong-creates.json). Each
- * input's plan entry lists the existing entities whose name the input text
- * contains, so the model can use that name.
- */
-import type { EntityIndex } from "./tree.js";
-export declare const ENTITY_HINTS: {
-    /** Entities listed per input. */
-    readonly perInput: 25;
-    /** An alias match counts this fraction of a canonical-name match with the same words. */
-    readonly aliasWeight: 0.5;
-    /** Aliases shown per entity. */
-    readonly aliases: 3;
-    /** Longest name, in words, matched through the n-gram set. Longer names use a phrase search. */
-    readonly maxGram: 4;
-};
-export interface EntityHint {
-    type: string;
-    name: string;
-    aliases: string[];
-}
-/**
- * Inverse document frequency of each word over the entities' match names, so
- * `Sentry` outranks `HQ Build` in a document that names both.
- */
-export declare function wordWeights(index: EntityIndex): Map<string, number>;
-/**
- * Up to `ENTITY_HINTS.perInput` writable entities whose canonical name or
- * qualifying alias appears in `text` as whole words within one sentence, table
- * cell or markdown block, highest weight first (ties by path). A match scores the summed word weights, halved for an alias.
- * Entities with the same type and canonical name are listed once. Only
- * entities from `index`, which is the plan's own company.
- */
-export declare function entityHints(index: EntityIndex, weights: Map<string, number>, text: string): EntityHint[];
-//# sourceMappingURL=hints.d.ts.map

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

@@ -1,146 +0,0 @@
-/**
- * Existing entities an input names, for `checkpoint.ontology.entity-hints`.
- *
- * The model never sees the company's entities, so it can only link one when it
- * happens to pick a name or alias the index holds. On the CO-39 fixtures it
- * created `SpaceXAI` beside `xAI`, `Indigo desktop app` beside `indigo-nx`
- * (alias `Indigo desktop repo`) and `hq-work-site` beside `Indigo Workspace`
- * (workspace/checkpoint-ontology/analysis/co41-wrong-creates.json). Each
- * input's plan entry lists the existing entities whose name the input text
- * contains, so the model can use that name.
- */
-export const ENTITY_HINTS = {
-    /** Entities listed per input. */
-    perInput: 25,
-    /** An alias match counts this fraction of a canonical-name match with the same words. */
-    aliasWeight: 0.5,
-    /** Aliases shown per entity. */
-    aliases: 3,
-    /** Longest name, in words, matched through the n-gram set. Longer names use a phrase search. */
-    maxGram: 4,
-};
-const HINT_TYPES = new Set(["person", "project", "company", "concept"]);
-/** Token that stands for a sentence, cell or block boundary. A name never matches across one it does not contain. */
-const BOUNDARY = "\n";
-const TOKEN = /[\p{L}\p{N}]+|[.!?;:](?=\s|$)|\|/gu;
-/**
- * A line that continues the previous one when the previous one is prose or a
- * list item: hard-wrapped markdown keeps a name that wraps across the line
- * break. Blank lines, headings, list items, table rows, quotes and fences start
- * a new block.
- */
-function continuesProse(line) {
-    return line.trim() !== "" && !/^\s*(#|[-*+]\s|\d+[.)]\s|\||>|```|~~~)/.test(line);
-}
-/**
- * Lowercased words, with `BOUNDARY` between sentences (`.`, `!`, `?`, `;` or
- * `:` before whitespace), table cells and markdown blocks. Names and text are
- * split the same way, so a name that holds a boundary, such as `Tip 001:
- * checkpoint`, still matches its own text.
- */
-function tokens(text) {
-    const out = [];
-    const push = (token) => {
-        if (token !== BOUNDARY || (out.length > 0 && out[out.length - 1] !== BOUNDARY))
-            out.push(token);
-    };
-    let prevProse = null;
-    for (const line of text.toLowerCase().split("\n")) {
-        const prose = continuesProse(line);
-        if (prevProse !== null && !(prose && prevProse))
-            push(BOUNDARY);
-        for (const match of line.matchAll(TOKEN))
-            push(/^[\p{L}\p{N}]/u.test(match[0]) ? match[0] : BOUNDARY);
-        prevProse = prose || /^\s*([-*+]|\d+[.)])\s/.test(line);
-    }
-    while (out[0] === BOUNDARY)
-        out.shift();
-    while (out[out.length - 1] === BOUNDARY)
-        out.pop();
-    return out;
-}
-function words(name) {
-    return name.filter((token) => token !== BOUNDARY);
-}
-function matchNames(entity) {
-    const out = [];
-    const canonical = tokens(entity.canonical_name);
-    if (words(canonical).length > 0)
-        out.push({ tokens: canonical, weight: 1 });
-    for (const alias of entity.aliases) {
-        const aliasTokens = tokens(alias);
-        const count = words(aliasTokens).length;
-        if (count >= 2 || (count === 1 && /[-_./0-9]/.test(alias))) {
-            out.push({ tokens: aliasTokens, weight: ENTITY_HINTS.aliasWeight, alias });
-        }
-    }
-    return out;
-}
-/**
- * Inverse document frequency of each word over the entities' match names, so
- * `Sentry` outranks `HQ Build` in a document that names both.
- */
-export function wordWeights(index) {
-    const counts = new Map();
-    let total = 0;
-    for (const entity of index.byRel.values()) {
-        if (!HINT_TYPES.has(entity.type))
-            continue;
-        total += 1;
-        for (const word of new Set(matchNames(entity).flatMap((name) => words(name.tokens))))
-            counts.set(word, (counts.get(word) ?? 0) + 1);
-    }
-    const weights = new Map();
-    for (const [word, count] of counts)
-        weights.set(word, Math.log((total + 1) / count));
-    return weights;
-}
-/**
- * Up to `ENTITY_HINTS.perInput` writable entities whose canonical name or
- * qualifying alias appears in `text` as whole words within one sentence, table
- * cell or markdown block, highest weight first (ties by path). A match scores the summed word weights, halved for an alias.
- * Entities with the same type and canonical name are listed once. Only
- * entities from `index`, which is the plan's own company.
- */
-export function entityHints(index, weights, text) {
-    const textTokens = tokens(text);
-    const grams = new Set();
-    for (let i = 0; i < textTokens.length; i += 1) {
-        for (let n = 1; n <= ENTITY_HINTS.maxGram && i + n <= textTokens.length; n += 1) {
-            grams.add(textTokens.slice(i, i + n).join(" "));
-        }
-    }
-    const padded = ` ${textTokens.join(" ")} `;
-    const best = new Map();
-    for (const entity of index.byRel.values()) {
-        if (!HINT_TYPES.has(entity.type))
-            continue;
-        let score = 0;
-        const matched = [];
-        for (const name of matchNames(entity)) {
-            const phrase = name.tokens.join(" ");
-            const found = name.tokens.length <= ENTITY_HINTS.maxGram ? grams.has(phrase) : padded.includes(` ${phrase} `);
-            if (!found)
-                continue;
-            if (name.alias !== undefined)
-                matched.push(name.alias);
-            score = Math.max(score, name.weight * words(name.tokens).reduce((sum, word) => sum + (weights.get(word) ?? 0), 0));
-        }
-        if (score <= 0)
-            continue;
-        const key = `${entity.type}\0${entity.canonical_name.toLowerCase()}`;
-        const held = best.get(key);
-        if (!held || score > held.score || (score === held.score && entity.rel < held.entity.rel))
-            best.set(key, { entity, score, matched });
-    }
-    return [...best.values()]
-        .sort((a, b) => b.score - a.score || (a.entity.rel < b.entity.rel ? -1 : a.entity.rel > b.entity.rel ? 1 : 0))
-        .slice(0, ENTITY_HINTS.perInput)
-        .map(({ entity, matched }) => ({
-        type: entity.type,
-        name: entity.canonical_name,
-        // Aliases the text used come first, so the model sees the name it read.
-        aliases: [...matched, ...entity.aliases.filter((alias) => !matched.includes(alias))].slice(0, ENTITY_HINTS.aliases),
-    }));
-}
-//# sourceMappingURL=hints.js.map