@indigoai-us/hq-cli 5.309.0 → 5.309.1

package/dist/lib/search-index/index.js

@@ -76,6 +76,10 @@ export class QmdExitError extends Error {
     stdout;
     stderr;
     name = 'QmdExitError';
+    /** Safe route labels for telemetry; raw qmd streams remain local to the error. */
+    entryPath;
+    /** Present only when the invoked executable is the bundled qmd. */
+    qmdVersion;
     constructor(message, args, status, stdout, stderr) {
         super(message);
         this.args = args;
@@ -1239,6 +1243,21 @@ function finishRunQmd(result, bin, args, attribution) {
     }
     throw exitError;
 }
+function finishRunQmdWithDiagnostics(result, bin, args, options, attribution) {
+    try {
+        return finishRunQmd(result, bin, args, attribution);
+    }
+    catch (error) {
+        if (error instanceof QmdExitError) {
+            if (args[0] === 'update' && options.entryPath)
+                error.entryPath = options.entryPath;
+            const bundledBins = [packageLocalBin(), packageLocalNodeEntry()].filter((candidate) => Boolean(candidate));
+            if (bundledBins.includes(bin))
+                error.qmdVersion = resolveQmdVersion();
+        }
+        throw error;
+    }
+}
 /** Run qmd with captured output and typed failures. */
 export function runQmd(args, options = {}) {
     // Legacy string-bin runner seam (tests and callers that inject a fake process):
@@ -1246,7 +1265,7 @@ export function runQmd(args, options = {}) {
     if (options.runner) {
         const bin = options.bin ?? resolveQmdBin({ env: options.env });
         const result = options.runner(bin, args, { cwd: options.cwd, env: options.env });
-        return finishRunQmd(result, bin, args);
+        return finishRunQmdWithDiagnostics(result, bin, args, options);
     }
     // Default path: resolve the full invocation (shell-free Node launcher preferred)
     // and spawn it through the shared Windows-aware plan. An explicit string bin is
@@ -1279,7 +1298,7 @@ export function runQmd(args, options = {}) {
     // genuinely missing qmd — instead of blaming the launcher for all three
     // (HQ-CLI-1A). `command` is the process actually spawned; `launcher` is qmd's
     // file identity.
-    return finishRunQmd(result, launcher, args, {
+    return finishRunQmdWithDiagnostics(result, launcher, args, options, {
         command: invocation.command,
         launcher,
         cwd: options.cwd,

package/dist/lib/search-index/qmd-exit-diagnostics.d.ts

@@ -0,0 +1,5 @@
+/** Bounded Sentry tags for qmd exits; never return captured streams or full argv. */
+export declare function qmdExitCaptureContext(err: unknown): {
+    tags: Record<string, string>;
+} | undefined;
+//# sourceMappingURL=qmd-exit-diagnostics.d.ts.map

package/dist/lib/search-index/qmd-exit-diagnostics.js

@@ -0,0 +1,40 @@
+import { QmdExitError } from "./index.js";
+const QMD_ERROR_CODE_TOKENS = [
+    "SQLITE_BUSY",
+    "SQLITE_CORRUPT",
+    "SQLITE_FULL",
+    "ENOSPC",
+    "EACCES",
+    "EPERM",
+    "ENOENT",
+    "ECONNRESET",
+    "ETIMEDOUT",
+];
+const QMD_UPDATE_ENTRY_PATHS = new Set(["index-sync"]);
+/** Bounded Sentry tags for qmd exits; never return captured streams or full argv. */
+export function qmdExitCaptureContext(err) {
+    if (!(err instanceof QmdExitError))
+        return undefined;
+    const output = err.stderr + "\n" + err.stdout;
+    const errorCode = QMD_ERROR_CODE_TOKENS.find((token) => new RegExp("(^|[^A-Za-z0-9_])" + token + "(?=$|[^A-Za-z0-9_])").test(output)) ?? "none";
+    const firstArg = err.args[0];
+    const subcommand = typeof firstArg === "string" && /^[a-z][a-z0-9_-]{0,31}$/.test(firstArg)
+        ? firstArg
+        : "unknown";
+    const exitStatus = typeof err.status === "number" && Number.isSafeInteger(err.status)
+        ? String(err.status)
+        : "unknown";
+    const tags = {
+        qmd_error_code: errorCode,
+        qmd_subcommand: subcommand,
+        qmd_exit_status: exitStatus,
+    };
+    if (typeof err.qmdVersion === "string" && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(err.qmdVersion)) {
+        tags.qmd_version = err.qmdVersion;
+    }
+    if (typeof err.entryPath === "string" && QMD_UPDATE_ENTRY_PATHS.has(err.entryPath)) {
+        tags.qmd_entry_path = err.entryPath;
+    }
+    return { tags };
+}
+//# sourceMappingURL=qmd-exit-diagnostics.js.map

package/dist/lib/service-manager/launchd.d.ts

@@ -7,7 +7,6 @@
  * touch launchctl.
  */
 import { type ServiceHostPaths, type ServiceSpec } from "./types.js";
-export declare const LAUNCHD_PATH_ENV = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
 export declare function launchAgentsDir(home: string): string;
 export declare function launchdPlistPath(home: string, spec: Pick<ServiceSpec, "label">): string;
 export declare function renderLaunchdPlist(spec: ServiceSpec, host: ServiceHostPaths): string;
@@ -27,12 +26,6 @@ export declare const LAUNCHD_BOOTSTRAP_BACKOFF_MS: readonly number[];
 export declare const LAUNCHD_BOOTSTRAP_ATTEMPTS: number;
 export declare const defaultRunCommand: RunCommand;
 export declare function launchdServiceTarget(plistPath: string, uid?: number): string;
-/** launchd returns EIO (5) when bootstrap races the previous job's exit. */
-export declare function isRetryableLaunchdBootstrap(r: {
-    status: number | null;
-    stdout: string;
-    stderr: string;
-}): boolean;
 /** ProgramArguments from a LaunchAgent plist. */
 export declare function launchdPlistProgramArguments(plist: string): string[];
 /**

package/dist/lib/service-manager/launchd.js

@@ -10,7 +10,7 @@ import { spawnSync } from "node:child_process";
 import * as os from "node:os";
 import * as path from "node:path";
 import { escapeXml, } from "./types.js";
-export const LAUNCHD_PATH_ENV = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
+const LAUNCHD_PATH_ENV = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
 export function launchAgentsDir(home) {
     return path.join(home, "Library", "LaunchAgents");
 }
@@ -89,7 +89,7 @@ function bootstrapErrorText(r) {
     return `${r.stderr} ${r.stdout} exit ${r.status ?? ""}`;
 }
 /** launchd returns EIO (5) when bootstrap races the previous job's exit. */
-export function isRetryableLaunchdBootstrap(r) {
+function isRetryableLaunchdBootstrap(r) {
     if (r.status === 0)
         return false;
     return /Input\/output error|\bEIO\b|Bootstrap failed: 5|Boot-strap failed: 5/i.test(bootstrapErrorText(r));

package/dist/main.js

@@ -24,6 +24,7 @@ import { qmdStoreUnopenableMessage } from "./utils/qmd-store-unopenable-error.js
 import { qmdQueryDocumentMessage } from "./utils/qmd-query-document-error.js";
 import { qmdModelDownloadMessage } from "./utils/qmd-model-download-error.js";
 import { qmdWorkdirMissingMessage } from "./utils/qmd-workdir-missing-error.js";
+import { qmdExitCaptureContext } from "./lib/search-index/qmd-exit-diagnostics.js";
 import { hqStateWriteErrorMessage } from "./utils/hq-state-write-error.js";
 import { checkpointStampWriteCaptureContext, checkpointStampWriteMessage, } from "./utils/checkpoint-stamp-write-error.js";
 import { incompleteInstallMessage, incompleteInstallCaptureContext, } from "./utils/incomplete-install-error.js";
@@ -872,9 +873,13 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             // Every other error captures bare, exactly as before.
             const spawnContext = qmdSpawnFailureCaptureContext(err);
             const installContext = incompleteInstallCaptureContext(err);
-            if (spawnContext || installContext) {
+            const qmdContext = qmdExitCaptureContext(err);
+            if (spawnContext || installContext || qmdContext) {
                 deps.sentry.captureException(err, {
-                    contexts: { ...spawnContext?.contexts, ...installContext },
+                    ...qmdContext,
+                    ...((spawnContext || installContext)
+                        ? { contexts: { ...spawnContext?.contexts, ...installContext } }
+                        : {}),
                 });
             }
             else {

package/dist/startup-registration.js

@@ -17,7 +17,7 @@
  * spawns, waits, or a real install tree.
  */
 import { spawnSync } from "node:child_process";
-import { resolveRunningInstall } from "./utils/version-gate.js";
+import { getVersionGatePhase, resolveRunningInstall } from "./utils/version-gate.js";
 import { stringDerivedPackageRoot } from "./utils/hq-roots.js";
 import { updateLockPath, UPDATE_LOCK_STALE_MS } from "./utils/update-lock.js";
 import { classifyEvalThrow, classifyModuleNotFound, installRewriteInProgress, InstallTreeTornError, waitForInstallTreeSettled, } from "./utils/install-tree-torn.js";
@@ -122,6 +122,7 @@ export async function registerCommandsWithRecovery(args) {
                 cause: err,
                 classified,
                 packageRoot,
+                versionGatePhase: getVersionGatePhase(),
                 outcome: "guarded",
                 treeState: env[INSTALL_TREE_RECOVERY_TREE_STATE_ENV] === "stale" ? "stale" : "in_flight",
                 attempt: 2,
@@ -165,6 +166,9 @@ export async function registerCommandsWithRecovery(args) {
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
                 retiredSiblingPresent: result.retiredSiblingPresent,
+                retiredSiblingKind: result.retiredSiblingKind,
+                installTargetState: result.installTargetState,
+                updaterPidAlive: result.updaterPidAlive,
                 sawTreeChange: result.sawTreeChange,
                 lockHeldAtEnd: result.lockHeldAtEnd,
                 lockedMs: result.lockedMs,
@@ -189,6 +193,7 @@ export async function registerCommandsWithRecovery(args) {
                 cause: err,
                 classified,
                 packageRoot,
+                versionGatePhase: getVersionGatePhase(),
                 outcome: "reexec-failed",
                 treeState,
                 attempt: 1,
@@ -196,6 +201,9 @@ export async function registerCommandsWithRecovery(args) {
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
                 retiredSiblingPresent: result.retiredSiblingPresent,
+                retiredSiblingKind: result.retiredSiblingKind,
+                installTargetState: result.installTargetState,
+                updaterPidAlive: result.updaterPidAlive,
                 sawTreeChange: result.sawTreeChange,
                 lockTool: result.lockTool,
             });

package/dist/utils/client-health.d.ts

@@ -33,8 +33,6 @@
 import { isExpiring, loadCachedTokens } from "./cognito-session.js";
 import { type VersionInfo } from "./feedback-versions.js";
 import { type ClientHealthArch, type ClientHealthHeartbeat, type ClientHealthLocalFilesOverview, type ClientHealthPlatform } from "./client-health-contract.js";
-/** Same bound as CLI telemetry: a heartbeat may never stall a command. */
-export declare const CLIENT_HEALTH_TIMEOUT_MS = 1200;
 export declare const CLIENT_HEALTH_STATE_FILE = "cli-client-health.json";
 /**
  * Single-flight marker for the journal observation below. Held only for the
@@ -66,8 +64,6 @@ export declare const CLIENT_HEALTH_OBSERVATION_FILE = "cli-client-health.observa
  * always re-observe — they have opened the store anyway, so it costs nothing.
  */
 export declare const JOURNAL_OBSERVATION_TTL_MS: number;
-/** An observation lock older than this is treated as abandoned. */
-export declare const JOURNAL_OBSERVATION_LOCK_STALE_MS: number;
 export interface CliClientHealthState {
     /** Stable random installation identity — regenerated only if invalid. */
     installationId: string;

package/dist/utils/client-health.js

@@ -40,7 +40,7 @@ import { collectVersions } from "./feedback-versions.js";
 import { CLIENT_HEALTH_CONTRACT_VERSION, parseClientHealthHeartbeat, } from "./client-health-contract.js";
 import { collectLocalFilesOverview } from "./local-files-overview.js";
 /** Same bound as CLI telemetry: a heartbeat may never stall a command. */
-export const CLIENT_HEALTH_TIMEOUT_MS = 1_200;
+const CLIENT_HEALTH_TIMEOUT_MS = 1_200;
 export const CLIENT_HEALTH_STATE_FILE = "cli-client-health.json";
 /**
  * Single-flight marker for the journal observation below. Held only for the
@@ -73,7 +73,7 @@ export const CLIENT_HEALTH_OBSERVATION_FILE = "cli-client-health.observation.jso
  */
 export const JOURNAL_OBSERVATION_TTL_MS = 15 * 60_000;
 /** An observation lock older than this is treated as abandoned. */
-export const JOURNAL_OBSERVATION_LOCK_STALE_MS = 5 * 60_000;
+const JOURNAL_OBSERVATION_LOCK_STALE_MS = 5 * 60_000;
 /**
  * Pre-filter mirror of the contract's SemVer shape (the contract keeps its
  * validators private). A version failing this is DROPPED individually so one

package/dist/utils/feedback-diagnostics.d.ts

@@ -1,6 +1,6 @@
 import { type VersionInfo } from "./feedback-versions.js";
 import type { FeedbackLogsBlob } from "./feedback-logs.js";
-export interface GitContext {
+interface GitContext {
     branch: string | null;
     head: string | null;
     dirty: boolean;
@@ -37,4 +37,5 @@ export interface DiagnosticsBlob {
 }
 export declare function sanitizeArgv(argv: string[]): string[];
 export declare function collectDiagnostics(): DiagnosticsBlob;
+export {};
 //# sourceMappingURL=feedback-diagnostics.d.ts.map

package/dist/utils/feedback-log-bundle.d.ts

@@ -61,29 +61,6 @@ import { vaultApiFetch } from "./vault-api.js";
  * stay in step or the CLI will build bundles the server will not accept.
  */
 export declare const LOG_BUNDLE_MAX_BYTES: number;
-/**
- * What the presign request declares, and what the server must answer with.
- * Mirrors `LOG_BUNDLE_FORMAT_ZIP` / `LOG_BUNDLE_ZIP_CONTENT_TYPE` in the hq-pro
- * handler `feedback-log-bundles.ts`.
- */
-export declare const LOG_BUNDLE_FORMAT = "zip";
-export declare const LOG_BUNDLE_CONTENT_TYPE = "application/zip";
-/**
- * Headroom between the size we stop feeding at and the hard cap.
- *
- * deflate reports compressed bytes only as its internal buffer flushes, so the
- * running total lags the bytes actually consumed. The lag is bounded by that
- * buffer (tens of KiB); a 1 MiB margin covers it with three orders of magnitude
- * to spare, and the final size is asserted against the real cap regardless.
- */
-export declare const LOG_BUNDLE_SAFETY_MARGIN_BYTES: number;
-/**
- * Per-file raw ceiling. The desktop logger rotates at 32 MiB (hq-desktop-core
- * `logfile.rs`), so this admits a full generation with headroom while stopping
- * one pathological file from consuming the whole bundle. Files above it are
- * read from the TAIL — the end of a log is what explains a failure.
- */
-export declare const LOG_BUNDLE_MAX_FILE_RAW_BYTES: number;
 export interface LogBundleResult {
     /** The zipped NDJSON bytes, ready to PUT. */
     bytes: Buffer;
@@ -150,8 +127,6 @@ export declare const ZIP32_UNCOMPRESSED_STOP_BYTES: number;
  */
 export declare function entryCeiling(requested?: number): number;
 export declare function crc32Fallback(buf: Buffer, seed?: number): number;
-/** Exported for the test that proves the fallback agrees with the native one. */
-export declare function crc32(buf: Buffer, seed?: number): number;
 /**
  * Bytes of ZIP framing around one entry: local header, central directory
  * header, end-of-central-directory. The name is stored twice.

package/dist/utils/feedback-log-bundle.js

@@ -71,8 +71,8 @@ export const LOG_BUNDLE_MAX_BYTES = 50 * 1024 * 1024;
  * Mirrors `LOG_BUNDLE_FORMAT_ZIP` / `LOG_BUNDLE_ZIP_CONTENT_TYPE` in the hq-pro
  * handler `feedback-log-bundles.ts`.
  */
-export const LOG_BUNDLE_FORMAT = "zip";
-export const LOG_BUNDLE_CONTENT_TYPE = "application/zip";
+const LOG_BUNDLE_FORMAT = "zip";
+const LOG_BUNDLE_CONTENT_TYPE = "application/zip";
 /**
  * Headroom between the size we stop feeding at and the hard cap.
  *
@@ -81,14 +81,14 @@ export const LOG_BUNDLE_CONTENT_TYPE = "application/zip";
  * buffer (tens of KiB); a 1 MiB margin covers it with three orders of magnitude
  * to spare, and the final size is asserted against the real cap regardless.
  */
-export const LOG_BUNDLE_SAFETY_MARGIN_BYTES = 1024 * 1024;
+const LOG_BUNDLE_SAFETY_MARGIN_BYTES = 1024 * 1024;
 /**
  * Per-file raw ceiling. The desktop logger rotates at 32 MiB (hq-desktop-core
  * `logfile.rs`), so this admits a full generation with headroom while stopping
  * one pathological file from consuming the whole bundle. Files above it are
  * read from the TAIL — the end of a log is what explains a failure.
  */
-export const LOG_BUNDLE_MAX_FILE_RAW_BYTES = 64 * 1024 * 1024;
+const LOG_BUNDLE_MAX_FILE_RAW_BYTES = 64 * 1024 * 1024;
 /** Read slice size. Bounds peak memory; unrelated to the output chunking. */
 const READ_SLICE_BYTES = 4 * 1024 * 1024;
 /** Target raw text per emitted chunk record. Keeps NDJSON lines manageable. */
@@ -217,7 +217,7 @@ export function crc32Fallback(buf, seed = 0) {
     return (~crc >>> 0) >>> 0;
 }
 /** Exported for the test that proves the fallback agrees with the native one. */
-export function crc32(buf, seed = 0) {
+function crc32(buf, seed = 0) {
     const native = zlib.crc32;
     return typeof native === "function" ? native(buf, seed) : crc32Fallback(buf, seed);
 }

package/dist/utils/feedback-logs.d.ts

@@ -84,13 +84,6 @@ export declare const FEEDBACK_LOGS_MIN_USEFUL_BYTES = 1024;
  * evidence. The overflow count preserves the signal without the bytes.
  */
 export declare const FEEDBACK_MAX_SKIPPED_ENTRIES = 25;
-/** Subdirectory of `~/.hq` whose log files are eligible. Not recursive. */
-export declare const FEEDBACK_LOGS_DIRNAME = "logs";
-/**
- * Eligible extensions inside `~/.hq/logs/`. `.jsonl` is included because the
- * CLI's MCP registry audit trail is JSON-lines, not plain text.
- */
-export declare const FEEDBACK_LOG_EXTENSIONS: readonly string[];
 /**
  * True for a log filename, including a ROTATED generation.
  *
@@ -103,26 +96,6 @@ export declare const FEEDBACK_LOG_EXTENSIONS: readonly string[];
 export declare function isEligibleLogName(name: string): boolean;
 /** Per-state-file ceiling. These are status documents, not streams. */
 export declare const FEEDBACK_STATE_MAX_FILE_BYTES: number;
-/**
- * Ceiling on all state snapshots combined. Deliberately a small slice of the
- * overall budget: state is dense but finite, and the rest belongs to logs.
- */
-export declare const FEEDBACK_STATE_MAX_TOTAL_BYTES: number;
-/**
- * State files at the `~/.hq` ROOT that are eligible, by EXACT name.
- *
- * The root is where `cognito-tokens.json`, `deploy-passwords.json`, and
- * `secrets-cache/` live, so it is never globbed. Adding a name here is a
- * deliberate act: confirm the file carries no credential before listing it.
- */
-export declare const FEEDBACK_STATE_FILENAMES: readonly string[];
-/**
- * Per-company sync journal LOCATORS (`sync-journal.<slug>.json`) are also
- * eligible. Matched by an exact prefix AND a `.json` suffix, which is what
- * excludes the multi-hundred-megabyte `…json.last-good` snapshots sitting
- * beside them. No credential file at the root carries this prefix.
- */
-export declare const FEEDBACK_STATE_JOURNAL_PREFIX = "sync-journal.";
 /**
  * `~/.hq/locks/` — held operation locks and background-work claims.
  *
@@ -141,8 +114,6 @@ export declare const FEEDBACK_LOCKS_DIRNAME = "locks";
  * bounds that walk carries.
  */
 export declare const FEEDBACK_JOBS_DIRNAME = "jobs";
-/** Per-entry ceiling for a lock file. Their value is the name plus a little context. */
-export declare const FEEDBACK_LOCK_MAX_FILE_BYTES = 512;
 /**
  * Bounds on the `jobs/` walk. Depth 3 reaches
  * `jobs/probes/<job>/last-attempt.json`; the file cap stops a pathological
@@ -152,15 +123,9 @@ export declare const FEEDBACK_JOBS_MAX_DEPTH = 3;
 export declare const FEEDBACK_JOBS_MAX_FILES = 20;
 /** Ceiling on how many lock entries are collected. */
 export declare const FEEDBACK_LOCKS_MAX_FILES = 20;
-/**
- * Log files that live at the root of `~/.hq` rather than under `logs/`.
- * Listed explicitly — the root directory holds credentials and must never be
- * enumerated by pattern.
- */
-export declare const FEEDBACK_ROOT_LOG_FILENAMES: readonly string[];
 /** Why a discovered log file contributed nothing to the submission. */
-export type SkipReason = "budget" | "empty" | "unreadable";
-export interface LogTail {
+type SkipReason = "budget" | "empty" | "unreadable";
+interface LogTail {
     /** Path relative to `~/.hq`, e.g. `logs/hq-sync.log`. Never absolute. */
     name: string;
     /** Full on-disk size, even when only a tail was included. */
@@ -177,7 +142,7 @@ export interface LogTail {
     tail: string;
 }
 /** A small JSON status document included whole (or head-truncated). */
-export interface StateSnapshot {
+interface StateSnapshot {
     /** Path relative to `~/.hq`, e.g. `sync-progress.json`. Never absolute. */
     name: string;
     sizeBytes: number;
@@ -331,4 +296,5 @@ export interface CollectFeedbackLogsOptions {
  * omit the field entirely rather than attach an empty object. Never throws.
  */
 export declare function collectFeedbackLogs(opts?: CollectFeedbackLogsOptions): FeedbackLogsBlob | undefined;
+export {};
 //# sourceMappingURL=feedback-logs.d.ts.map

package/dist/utils/feedback-logs.js

@@ -89,12 +89,12 @@ export const FEEDBACK_LOGS_MIN_USEFUL_BYTES = 1024;
  */
 export const FEEDBACK_MAX_SKIPPED_ENTRIES = 25;
 /** Subdirectory of `~/.hq` whose log files are eligible. Not recursive. */
-export const FEEDBACK_LOGS_DIRNAME = "logs";
+const FEEDBACK_LOGS_DIRNAME = "logs";
 /**
  * Eligible extensions inside `~/.hq/logs/`. `.jsonl` is included because the
  * CLI's MCP registry audit trail is JSON-lines, not plain text.
  */
-export const FEEDBACK_LOG_EXTENSIONS = [".log", ".jsonl"];
+const FEEDBACK_LOG_EXTENSIONS = [".log", ".jsonl"];
 /**
  * True for a log filename, including a ROTATED generation.
  *
@@ -120,7 +120,7 @@ export const FEEDBACK_STATE_MAX_FILE_BYTES = 4 * 1024;
  * Ceiling on all state snapshots combined. Deliberately a small slice of the
  * overall budget: state is dense but finite, and the rest belongs to logs.
  */
-export const FEEDBACK_STATE_MAX_TOTAL_BYTES = 12 * 1024;
+const FEEDBACK_STATE_MAX_TOTAL_BYTES = 12 * 1024;
 /**
  * State files at the `~/.hq` ROOT that are eligible, by EXACT name.
  *
@@ -128,7 +128,7 @@ export const FEEDBACK_STATE_MAX_TOTAL_BYTES = 12 * 1024;
  * `secrets-cache/` live, so it is never globbed. Adding a name here is a
  * deliberate act: confirm the file carries no credential before listing it.
  */
-export const FEEDBACK_STATE_FILENAMES = [
+const FEEDBACK_STATE_FILENAMES = [
     // In-flight sync: phase, file counts, conflict count, current file.
     "sync-progress.json",
     // Sync contract version the installation last wrote.
@@ -150,7 +150,7 @@ export const FEEDBACK_STATE_FILENAMES = [
  * excludes the multi-hundred-megabyte `…json.last-good` snapshots sitting
  * beside them. No credential file at the root carries this prefix.
  */
-export const FEEDBACK_STATE_JOURNAL_PREFIX = "sync-journal.";
+const FEEDBACK_STATE_JOURNAL_PREFIX = "sync-journal.";
 /**
  * `~/.hq/locks/` — held operation locks and background-work claims.
  *
@@ -170,7 +170,7 @@ export const FEEDBACK_LOCKS_DIRNAME = "locks";
  */
 export const FEEDBACK_JOBS_DIRNAME = "jobs";
 /** Per-entry ceiling for a lock file. Their value is the name plus a little context. */
-export const FEEDBACK_LOCK_MAX_FILE_BYTES = 512;
+const FEEDBACK_LOCK_MAX_FILE_BYTES = 512;
 /**
  * Bounds on the `jobs/` walk. Depth 3 reaches
  * `jobs/probes/<job>/last-attempt.json`; the file cap stops a pathological
@@ -185,7 +185,7 @@ export const FEEDBACK_LOCKS_MAX_FILES = 20;
  * Listed explicitly — the root directory holds credentials and must never be
  * enumerated by pattern.
  */
-export const FEEDBACK_ROOT_LOG_FILENAMES = [
+const FEEDBACK_ROOT_LOG_FILENAMES = [
     "boot-sync.log",
     "boot-capture.log",
 ];

package/dist/utils/feedback-screenshots.d.ts

@@ -1,5 +1,4 @@
 export declare const MAX_SCREENSHOTS = 5;
-export declare const MAX_SCREENSHOT_BYTES: number;
 export declare function contentTypeForPath(filePath: string): string;
 export interface ScreenshotInput {
     path: string;

package/dist/utils/feedback-screenshots.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import { vaultApiFetch } from "./vault-api.js";
 export const MAX_SCREENSHOTS = 5;
 // Per-image ceiling. Screenshots are PNG/JPEG captures; 10 MB is generous.
-export const MAX_SCREENSHOT_BYTES = 10 * 1024 * 1024;
+const MAX_SCREENSHOT_BYTES = 10 * 1024 * 1024;
 // Extension → content type. Must stay in sync with the server's allowed set
 // (hq-pro feedback-screenshots.ts ALLOWED_CONTENT_TYPES).
 const EXT_CONTENT_TYPE = {

package/dist/utils/install-tree-torn.d.ts

@@ -37,7 +37,7 @@
  * for a module-EVALUATION throw that carries NO real `code` (HQ-CLI-1T) — see
  * {@link ModuleErrorDialect}.
  */
-export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "ENOENT" | "EVAL_THROW";
+type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "ENOENT" | "EVAL_THROW";
 /**
  * The closed set of resolution-failure dialects, verified on Node v22.23.1 and
  * the observed Node 24 synchronous ESM loader shape (the @sentry/node
@@ -78,7 +78,7 @@ export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "
  *   - `unknown`:     a module-not-found whose message did not parse; recovery
  *                    still waits on the lock / retired-dir / quiet signals.
  */
-export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "cjs-relative" | "esm-enoent" | "cjs-enoent" | "resolve-enoent" | "eval-throw" | "unknown";
+type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "cjs-relative" | "esm-enoent" | "cjs-enoent" | "resolve-enoent" | "eval-throw" | "unknown";
 /**
  * The missing thing, re-resolvable by the readiness probe:
  *   - `path`:     an absolute filesystem path (a `.js` file, or a package dir).
@@ -214,15 +214,6 @@ export interface InstallTreeFs {
  * Any filesystem error reads as "not present" rather than throwing.
  */
 export declare function installTargetPresent(target: ModuleErrorTarget, fs?: InstallTreeFs): boolean;
-/**
- * Default ceiling on the CUMULATIVE time the wait may spend observing a FRESH
- * foreign lock held by a live pid. Equal to the shared update-lock contract's own
- * staleness window ({@link UPDATE_LOCK_STALE_MS} — "no healthy npm install -g of
- * this package runs 10 minutes"), so the wait trusts a live cooperating writer for
- * 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 declare const DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS: number;
 export interface WaitForInstallTreeSettledArgs {
     target: ModuleErrorTarget;
     /** The running install's package dir (from resolveRunningInstall), or null. */
@@ -276,8 +267,14 @@ export interface WaitForInstallTreeSettledResult {
     retiredSiblingPresent?: boolean | null;
     /** A stable partial retired-sibling scan ended the wait without claiming the tree is stale. */
     retiredSiblingUnverified?: boolean;
+    retiredSiblingKind?: RetiredSiblingKind;
+    installTargetState?: InstallTargetState;
+    updaterPidAlive?: UpdaterPidAlive;
 }
-export declare const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1500;
+type RetiredSiblingKind = "npm_hash_retired" | "hq_staging" | "hq_backup" | "other" | "unknown";
+type InstallTargetState = "missing" | "manifest_valid" | "manifest_invalid" | "unreadable" | "unknown";
+type UpdaterPidAlive = "true" | "false" | "unknown";
+type VersionGatePhase = "preflight" | "lock_acquired" | "installer_running" | "verifying" | "rollback" | "complete" | "failed" | "unknown";
 /**
  * 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
@@ -337,7 +334,7 @@ export interface InstallRewriteSignalArgs {
 export declare function installRewriteInProgress(args: InstallRewriteSignalArgs): boolean;
 /** The recovery OUTCOME, which — not the dialect — decides capture. */
 export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed" | "lock-held" | "stale_tree" | "retired_unverified";
-export type InstallTreeState = "in_flight" | "stale";
+type InstallTreeState = "in_flight" | "stale";
 export type InstallTreeTornDiagnostics = {
     dialect: ModuleErrorDialect;
     code: ModuleNotFoundCode;
@@ -362,6 +359,10 @@ export type InstallTreeTornDiagnostics = {
     retiredSiblingPresent?: boolean;
     /** The thrown error's `name` for the eval-throw dialect (HQ-CLI-1T), else "". */
     errorName: string;
+    retiredSiblingKind: RetiredSiblingKind;
+    installTargetState: InstallTargetState;
+    versionGatePhase: VersionGatePhase;
+    updaterPidAlive: UpdaterPidAlive;
 };
 export interface InstallTreeTornInit {
     /** The original loader error, carried unchanged as `cause`. */
@@ -383,6 +384,10 @@ export interface InstallTreeTornInit {
     lockTool?: string;
     /** Final retired sibling presence, or null when the scope directory was unreadable. */
     retiredSiblingPresent?: boolean | null;
+    retiredSiblingKind?: RetiredSiblingKind;
+    installTargetState?: InstallTargetState;
+    versionGatePhase?: VersionGatePhase;
+    updaterPidAlive?: UpdaterPidAlive;
 }
 /**
  * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived
@@ -431,4 +436,5 @@ export declare const INSTALL_TREE_LOCK_HELD_REMEDY: string;
  * {@link INSTALL_TREE_TORN_REMEDY} byte-for-byte.
  */
 export declare function installTreeTornStderrLine(err: InstallTreeTornError): string;
+export {};
 //# sourceMappingURL=install-tree-torn.d.ts.map