@indigoai-us/hq-cli 5.309.0 → 5.309.1

package/dist/utils/install-tree-torn.js

@@ -609,7 +609,7 @@ export function installTargetPresent(target, fs = nodeInstallTreeFs) {
  * exactly as long as the contract legitimises holding the lock, and never longer.
  * Overridable by the seam (env HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS).
  */
-export const DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS = UPDATE_LOCK_STALE_MS;
+const DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS = UPDATE_LOCK_STALE_MS;
 /** The scope/leaf split of CLI_NAME, e.g. `@indigoai-us` / `hq-cli`. */
 function cliNameParts() {
     const slash = CLI_NAME.indexOf("/");
@@ -652,6 +652,68 @@ function retiredSiblingPresent(packageRoot, fs) {
     const entries = fs.readdirSync(parent); // caller treats a throw as "not ready"
     return entries.some((entry) => entry.startsWith(stagingPrefix));
 }
+/** Reduce an observed sibling basename to a closed kind without retaining it. */
+function retiredSiblingKind(packageRoot, fs) {
+    if (!packageRoot)
+        return "unknown";
+    try {
+        const { leaf } = cliNameParts();
+        const prefix = "." + leaf + "-";
+        const siblings = fs
+            .readdirSync(path.dirname(packageRoot))
+            .filter((entry) => entry.startsWith(prefix))
+            .sort();
+        if (siblings.length === 0)
+            return "unknown";
+        const name = siblings[0];
+        if (/^\.hq-cli-staging-[A-Za-z0-9-]+$/.test(name))
+            return "hq_staging";
+        if (/^\.hq-cli-backup-[A-Za-z0-9-]+$/.test(name))
+            return "hq_backup";
+        if (/^\.hq-cli-[A-Za-z0-9]{8}$/.test(name))
+            return "npm_hash_retired";
+        return "other";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Classify current target/manifest state without retaining paths or file contents. */
+function installTargetState(target, packageRoot, fs) {
+    if (target.kind === "unknown")
+        return "unknown";
+    if (!installTargetPresent(target, fs))
+        return "missing";
+    if (!packageRoot)
+        return "unknown";
+    try {
+        const raw = fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8");
+        let manifest;
+        try {
+            manifest = JSON.parse(raw);
+        }
+        catch {
+            return "manifest_invalid";
+        }
+        return manifest.name === CLI_NAME ? "manifest_valid" : "manifest_invalid";
+    }
+    catch (error) {
+        return error?.code === "ENOENT" ? "missing" : "unreadable";
+    }
+}
+/** Read only the lock's recorded owner PID; never retain or report the PID. */
+function updaterPidAlive(lockPath, fs, isPidAlive) {
+    try {
+        const lock = JSON.parse(fs.readFileSync(lockPath, "utf-8"));
+        if (typeof lock.pid !== "number" || !Number.isSafeInteger(lock.pid) || lock.pid <= 0) {
+            return "unknown";
+        }
+        return isPidAlive(lock.pid) ? "true" : "false";
+    }
+    catch {
+        return "unknown";
+    }
+}
 /** Snapshot retired sibling trees so changes below their root stay observable. */
 function retiredSiblingActivitySignature(packageRoot, fs) {
     const { leaf } = cliNameParts();
@@ -851,7 +913,7 @@ function canProbeUnsettledRetiredSibling(snapshot) {
     return snapshot.observed ||
         (snapshot.nonRetiredObserved && snapshot.retiredSiblingPresent === true);
 }
-export const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
+const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
 /**
  * Poll until the install tree has been continuously READY for `quietMs`, or the
  * wait exhausts its bounds. READY means: (i) no FRESH update lock held by another
@@ -986,6 +1048,9 @@ export async function waitForInstallTreeSettled(args) {
                 sawTreeChange,
                 staleTree: false,
                 retiredSiblingPresent: retiredPresent,
+                retiredSiblingKind: retiredSiblingKind(args.packageRoot, fs),
+                installTargetState: installTargetState(args.target, args.packageRoot, fs),
+                updaterPidAlive: updaterPidAlive(args.lockPath, fs, isPidAlive),
             };
         }
         if (!ready &&
@@ -1007,6 +1072,9 @@ export async function waitForInstallTreeSettled(args) {
                 staleTree: lastActivitySnapshot.observed,
                 retiredSiblingPresent: retiredPresent,
                 retiredSiblingUnverified: !lastActivitySnapshot.observed && lastActivitySnapshot.retiredSiblingPresent === true,
+                retiredSiblingKind: retiredSiblingKind(args.packageRoot, fs),
+                installTargetState: installTargetState(args.target, args.packageRoot, fs),
+                updaterPidAlive: updaterPidAlive(args.lockPath, fs, isPidAlive),
             };
         }
         // Give up when the TREE has had a full unlocked budget with no writer visible,
@@ -1029,6 +1097,9 @@ export async function waitForInstallTreeSettled(args) {
                 sawTreeChange,
                 staleTree: false,
                 retiredSiblingPresent: retiredPresent,
+                retiredSiblingKind: retiredSiblingKind(args.packageRoot, fs),
+                installTargetState: installTargetState(args.target, args.packageRoot, fs),
+                updaterPidAlive: updaterPidAlive(args.lockPath, fs, isPidAlive),
             };
         }
         // The first poll at which the wait has reached `deadlineMs` while a lock is
@@ -1129,6 +1200,10 @@ export class InstallTreeTornError extends Error {
             lockTool: boundedDiagnosticValue(init.lockTool ?? "", LOCK_TOOL_BYTES),
             node: process.version,
             errorName: boundedDiagnosticValue(init.classified.errorName ?? "", ERRORNAME_BYTES),
+            retiredSiblingKind: init.retiredSiblingKind ?? "unknown",
+            installTargetState: init.installTargetState ?? "unknown",
+            versionGatePhase: init.versionGatePhase ?? "unknown",
+            updaterPidAlive: init.updaterPidAlive ?? "unknown",
         };
         if (typeof init.retiredSiblingPresent === "boolean") {
             diagnostics.retiredSiblingPresent = init.retiredSiblingPresent;

package/dist/utils/local-files-overview.d.ts

@@ -26,12 +26,6 @@
  * must never break a heartbeat, let alone a CLI command.
  */
 import { type ClientHealthLocalFilesOverview } from "./client-health-contract.js";
-/**
- * Only the last N bytes of the sync log are read for error-line counting —
- * this bounds memory/CPU regardless of how large the on-disk log has grown.
- * Metadata (size/age) still reflects the FULL file via `fs.stat`.
- */
-export declare const LOCAL_FILES_OVERVIEW_TAIL_READ_BYTES: number;
 /**
  * Count lines that look like an error marker in the last
  * {@link LOCAL_FILES_OVERVIEW_TAIL_READ_BYTES} of `filePath`, capped at

package/dist/utils/local-files-overview.js

@@ -36,7 +36,7 @@ import { CLIENT_HEALTH_MAX_ERROR_LINE_COUNT, CLIENT_HEALTH_MAX_FILE_AGE_SECONDS,
  * this bounds memory/CPU regardless of how large the on-disk log has grown.
  * Metadata (size/age) still reflects the FULL file via `fs.stat`.
  */
-export const LOCAL_FILES_OVERVIEW_TAIL_READ_BYTES = 2 * 1024 * 1024; // 2 MiB
+const LOCAL_FILES_OVERVIEW_TAIL_READ_BYTES = 2 * 1024 * 1024; // 2 MiB
 /** Case-insensitive marker matched against each line (or JSON-lines `level`). */
 const ERROR_MARKER = /error/i;
 const JSON_LEVEL_ERROR = /"level"\s*:\s*"error"\s*(?=[,}])/i;

package/dist/utils/qmd-model-download-error.d.ts

@@ -1,11 +1,3 @@
-/**
- * The actionable remedy shown to the caller. Input-free — nothing is
- * interpolated from the error, the argv, or qmd's output — so there is no
- * injection surface. The disposition holds for every reading of a vanished
- * `.ipull` partial (a concurrent finisher, a cache eviction, a partially-written
- * file): it is transient and retryable, and re-running resumes the download.
- */
-export declare const QMD_MODEL_DOWNLOAD_REMEDY: string;
 /**
  * True when `err` is a qmd interrupted-model-download failure: qmd's OWN captured
  * streams carry BOTH an ENOENT-rename signature AND a `.ipull` partial-download

package/dist/utils/qmd-model-download-error.js

@@ -50,7 +50,7 @@ const MODEL_FETCH_READS = new Set(["query", "vsearch", "embed"]);
  * `.ipull` partial (a concurrent finisher, a cache eviction, a partially-written
  * file): it is transient and retryable, and re-running resumes the download.
  */
-export const QMD_MODEL_DOWNLOAD_REMEDY = "hq's local search couldn't finish downloading a model it needs: the partial " +
+const QMD_MODEL_DOWNLOAD_REMEDY = "hq's local search couldn't finish downloading a model it needs: the partial " +
     "download file disappeared before it could be saved, which usually means " +
     "another hq or qmd process on this machine finished or cleared the same " +
     "download. Re-run the command — the download resumes.";

package/dist/utils/qmd-query-document-error.d.ts

@@ -1,9 +1,3 @@
-/**
- * The actionable remedy shown to the caller. Input-free: nothing is interpolated
- * from the error, the argv, or qmd's output, so there is no injection surface —
- * matching the bounded-fingerprint discipline of its siblings.
- */
-export declare const QMD_QUERY_DOCUMENT_REMEDY: string;
 /**
  * True when `err` carries, in qmd's OWN captured streams, a query-document
  * syntax diagnostic — i.e. qmd's `query` parser rejected the positional as a

package/dist/utils/qmd-query-document-error.js

@@ -61,7 +61,7 @@ const QUERY_DOCUMENT_READS = new Set(["query"]);
  * from the error, the argv, or qmd's output, so there is no injection surface —
  * matching the bounded-fingerprint discipline of its siblings.
  */
-export const QMD_QUERY_DOCUMENT_REMEDY = "Hybrid search was given a multi-line query, and qmd read it as a structured " +
+const QMD_QUERY_DOCUMENT_REMEDY = "Hybrid search was given a multi-line query, and qmd read it as a structured " +
     "query document whose lines must each begin with a lex:, vec:, hyde:, or " +
     "intent: prefix. Put your search terms on a single line, or prefix every line, " +
     "then run the command again.";

package/dist/utils/scaffold-fast-import-guard.d.ts

@@ -1,3 +1,2 @@
-export declare function forbiddenFastPathModules(loadedModules: readonly string[], distDirectory: string, allowedCommandModules?: readonly string[]): string[];
 export declare function assertFastPathStaysCommandGraphFree(loadedModules: readonly string[], distDirectory: string, allowedCommandModules?: readonly string[]): void;
 //# sourceMappingURL=scaffold-fast-import-guard.d.ts.map

package/dist/utils/scaffold-fast-import-guard.js

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-export function forbiddenFastPathModules(loadedModules, distDirectory, allowedCommandModules = []) {
+function forbiddenFastPathModules(loadedModules, distDirectory, allowedCommandModules = []) {
     const dist = path.resolve(distDirectory);
     const main = path.join(dist, "main.js");
     const commands = `${path.join(dist, "commands")}${path.sep}`;

package/dist/utils/scaffold-sibling-references.d.ts

@@ -1,8 +1,8 @@
-export type SiblingAssetReference = {
+type SiblingAssetReference = {
     referringAsset: string;
     targetAsset: string;
 };
-export type HqRootAssetReference = {
+type HqRootAssetReference = {
     referringAsset: string;
     reference: string;
 };
@@ -18,4 +18,5 @@ export type ScaffoldReferenceScan = {
  */
 export declare function scanScaffoldSiblingReferences(scaffoldRoot: string): ScaffoldReferenceScan;
 export declare function assertNoMissingScaffoldSiblings(scan: ScaffoldReferenceScan): void;
+export {};
 //# sourceMappingURL=scaffold-sibling-references.d.ts.map

package/dist/utils/sentry-fingerprint.js

@@ -250,6 +250,23 @@ export function installTreeTornSentryTagsFor(err) {
     if (typeof diagnostics.retiredSiblingPresent === "boolean") {
         tags.retired_sibling = diagnostics.retiredSiblingPresent ? "present" : "absent";
     }
+    const retiredSiblingKind = diagnostics.retiredSiblingKind;
+    tags.retired_sibling_kind = typeof retiredSiblingKind === "string" &&
+        ["npm_hash_retired", "hq_staging", "hq_backup", "other", "unknown"].includes(retiredSiblingKind)
+        ? retiredSiblingKind
+        : "unknown";
+    const targetState = diagnostics.installTargetState;
+    tags.install_target_state = typeof targetState === "string" &&
+        ["missing", "manifest_valid", "manifest_invalid", "unreadable", "unknown"].includes(targetState)
+        ? targetState
+        : "unknown";
+    const gatePhase = diagnostics.versionGatePhase;
+    tags.version_gate_phase = typeof gatePhase === "string" &&
+        ["preflight", "lock_acquired", "installer_running", "verifying", "rollback", "complete", "failed", "unknown"].includes(gatePhase)
+        ? gatePhase
+        : "unknown";
+    const pidAlive = diagnostics.updaterPidAlive;
+    tags.updater_pid_alive = pidAlive === "true" || pidAlive === "false" ? pidAlive : "unknown";
     if (recoveryOutcome)
         tags.recovery_outcome = recoveryOutcome;
     const lockTool = diagnostics.lockTool;

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

@@ -29,6 +29,9 @@
  */
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
 import { type UpdateLockHandle } from "./update-lock.js";
+export type VersionGatePhase = "preflight" | "lock_acquired" | "installer_running" | "verifying" | "rollback" | "complete" | "failed" | "unknown";
+/** The last closed version-gate phase observed in this process. */
+export declare function getVersionGatePhase(): VersionGatePhase;
 /** Which package manager owns the running global install. */
 export type InstallManager = "npm" | "pnpm" | "bun";
 export interface VersionCheckResponse {
@@ -489,6 +492,7 @@ export declare function enforceVersionGate(onUpdateRecommended?: (decision: Vers
 export declare function shouldSkipGate(argv: readonly string[]): boolean;
 export declare const __test__: {
     CLIENT_ID: string;
+    getVersionGatePhase: typeof getVersionGatePhase;
     CONVERGENCE_TIMEOUT_MS: number;
     DEFAULT_UPDATE_TIMEOUT_MS: number;
     ENDPOINT_PATH: string;

package/dist/utils/version-gate.js

@@ -45,6 +45,11 @@ const CLIENT_ID = "hq-cli";
 const ENDPOINT_PATH = "/v1/client-version/check";
 const FETCH_TIMEOUT_MS = 3_000;
 const LATEST_PACKAGE_SPEC = `${CLI_NAME}@latest`;
+let currentVersionGatePhase = "unknown";
+/** The last closed version-gate phase observed in this process. */
+export function getVersionGatePhase() {
+    return currentVersionGatePhase;
+}
 function isOptedOut() {
     return process.env.HQ_NO_UPDATE_CHECK === "1";
 }
@@ -1291,6 +1296,7 @@ export function checkUpdateConvergence(targetVersion, deps = {}) {
  * gate returns and lets the user's command run on the current version.
  */
 function enforceUpdateRequired(decision, deps = {}) {
+    currentVersionGatePhase = "preflight";
     const banner = chalk.red.bold(`✗ hq-cli ${CLI_VERSION} is below the minimum required version (${decision.minVersion}).`);
     console.error(banner);
     if (decision.message)
@@ -1341,6 +1347,7 @@ function enforceUpdateRequired(decision, deps = {}) {
         console.error(chalk.dim("  Another hq updater is already installing (update lock held); continuing on the current version."));
         return;
     }
+    currentVersionGatePhase = "lock_acquired";
     let attempt;
     try {
         attempt = attemptRequiredUpdate(decision, deps, install);
@@ -1406,6 +1413,7 @@ function attemptRequiredUpdate(decision, deps, install) {
     const updateEnv = pnpmUpdateEnv(install);
     let result;
     let noticeFlush = null;
+    currentVersionGatePhase = "installer_running";
     if (isManagedOutsideNpm) {
         console.error(chalk.dim(`  Detected a ${install.manager}-managed global install; updating with ${install.manager}`));
         console.error(chalk.dim(`  Running: ${primaryCmd} ${primaryArgs.join(" ")}`));
@@ -1475,6 +1483,7 @@ function attemptRequiredUpdate(decision, deps, install) {
             result = sudoResult;
     }
     if (!result.ok) {
+        currentVersionGatePhase = "failed";
         console.error(chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`));
         // If the npm prefix is still unwritable after the unprivileged and sudo
         // attempts, explain the permission wall plainly instead of leaving exit 75
@@ -1524,11 +1533,14 @@ function attemptRequiredUpdate(decision, deps, install) {
     // install shadowing the copy we just wrote is reported as the failed update
     // it is rather than as a success the caller will keep retrying — see
     // checkUpdateConvergence.
+    currentVersionGatePhase = "verifying";
     const converged = (deps.checkConvergence ?? checkUpdateConvergence)(decision.latestVersion);
     if (converged === false) {
+        currentVersionGatePhase = "failed";
         console.error(chalk.red(`✗ Update did not take effect: \`hq\` on PATH still resolves a different build than ${decision.latestVersion}.`));
         return 75;
     }
+    currentVersionGatePhase = "complete";
     console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
     return 0;
 }
@@ -1585,6 +1597,7 @@ export function shouldSkipGate(argv) {
 }
 export const __test__ = {
     CLIENT_ID,
+    getVersionGatePhase,
     CONVERGENCE_TIMEOUT_MS,
     DEFAULT_UPDATE_TIMEOUT_MS,
     ENDPOINT_PATH,

package/package.json

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