@indigoai-us/hq-cli 5.108.13 → 5.108.15

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 ## [Unreleased]
 
+## [5.108.15] — 2026-09-07
+
+### Fixed
+
+- Work Mesh Live presence daemon (`hq mesh daemon run`) no longer pins a CPU
+  core when the MQTT broker accepts a connection then closes it just past the
+  stable-connect grace window. The full-jitter reconnect backoff could collapse
+  to ~0 ms after the connect handler reset its counters, producing a tight
+  accept-then-close reconnect spin (each pass re-ran the SigV4 presign and
+  re-materialised the daemon state dir) with no network progress and no log
+  output. A hard `RECONNECT_MIN_DELAY_MS` (1s) floor now applies to every
+  reconnect path — normal backoff, the post-grace reset, and the refused-retry
+  path (which a server `Retry-After: 0` could otherwise drive to 0) — so the
+  delay can never shrink below 1s. Regression tests cover the reset and the
+  refused-retry floor. (#524)
+- The Work Mesh Live daemon no longer burns CPU in a self-triggered flush loop.
+  Its spool directory watcher woke on files the daemon writes itself during a
+  flush (`held.jsonl` and the `*.claimed` files), so any box with held events
+  flushed every two seconds forever; the watcher now reacts only to producer
+  appends to `spool.jsonl`. Recovering a very large orphan claim file no longer
+  overflows the stack, mid-flush disposal is O(1), held events are re-attempted
+  at most every five minutes, and `held.jsonl` is capped at 20,000 lines with
+  the oldest overflow dead-lettered as `HELD_OVERFLOW` (loss-free under failure
+  and concurrent flushers). (#525)
+
+## [5.108.14] — 2026-09-07
+
+### Fixed
+
+- An incomplete hq install tree no longer files an unactionable crash when hq
+  fails to load one of its OWN bundled modules in-process (HQ-CLI-1M, HQ-CLI-1N).
+  Two shapes shared one cause — hq-cli's globally installed package tree was not
+  intact at the moment a command loaded a module. In HQ-CLI-1N (`hq core
+  timeout-guard` on Windows) a partial `npm i -g` left a RELATIVE sibling
+  unwritten deep inside a bundled dependency, so Node threw
+  `MODULE_NOT_FOUND`. In HQ-CLI-1M (`hq rescue` on Linux) a concurrent global
+  install rewrote the running tree, so an ESM module that existed at resolve was
+  gone at read and Node's loader raised `ENOENT` — the loader validates
+  existence at resolve, so an ENOENT at LOAD proves the file vanished mid-run
+  rather than being merely absent. Both carried no hq-cli frames, reached the
+  top-level handler's final `else`, and produced a bare Sentry crash plus an
+  `hq:` line the operator could not act on. A new in-process classifier now
+  recognises both shapes — but ONLY when the failing file sits under the running
+  install's own `node_modules/`, the CJS shape additionally requires a relative
+  specifier, and the ESM shape additionally requires an esm-loader frame — and
+  prints an input-free reinstall remedy (run the command again first, then
+  `npm i -g @indigoai-us/hq-cli` / `pnpm add -g @indigoai-us/hq-cli`) while
+  skipping Sentry capture, the same disposition established for the qmd child in
+  HQ-CLI-Y. An hq-cli packaging fault stays reportable: a miss under the
+  package's own `dist/` or `assets/`, a bare-specifier miss (a possible
+  undeclared dependency), and an esm-loader ENOENT whose path did not survive
+  delivery are NOT suppressed — the last is captured WITH a bounded
+  `incomplete_install` context so the next occurrence is attributable. The drop
+  is wired both at the top-level boundary and in the shared `beforeSend`, so it
+  covers every capture route.
+
 ## [5.108.13] — 2026-09-06
 
 ## [5.108.12] - 2026-09-05

package/dist/commands/agents.d.ts

@@ -110,9 +110,20 @@ export interface ProfilePatch {
     description?: string;
 }
 export interface RuntimeConfigPatch {
+    /**
+     * Brain/runtime provider. When present the server routes the PATCH to a
+     * PROVIDER MIGRATION (handleProviderMigration): it TERMINATES and reprovisions
+     * the box and changes the provider/auth contract. Omit for a plain tuning
+     * patch (model / effort / tier).
+     */
+    provider?: string;
     codexModel?: string;
     codexReasoningEffort?: string;
     codexServiceTier?: string;
+    /** Provider-migration auth mode: "subscription" | "apiKey". */
+    codexAuthMode?: string;
+    /** Provider-migration apiKey-mode vault key reference (never a raw secret). */
+    codexApiKeyRef?: string;
 }
 /**
  * Authenticated JSON round-trip against the agents control plane. Throws
@@ -143,7 +154,12 @@ export interface ProvisionAgentInput {
     /** Server quote assertion; hq-pro re-prices and refuses a stale amount. */
     quotedNetMonthlyCents?: number;
     quoteCatalogVersion?: string;
+    /** Funnel attribution: which client surface made the attempt. */
+    surface?: AgentCreateSurface;
 }
+/** Closed set shared with hq-pro's agent_create_* funnel contract. */
+export declare const CLI_AGENT_CREATE_SURFACE: "cli_agents_create";
+export type AgentCreateSurface = typeof CLI_AGENT_CREATE_SURFACE;
 export interface AgentCreateSizeOption {
     key: "basic" | "power" | "dev";
     productName: string;

package/dist/commands/agents.js

@@ -146,6 +146,8 @@ export function slugifyAgentName(name) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "");
 }
+/** Closed set shared with hq-pro's agent_create_* funnel contract. */
+export const CLI_AGENT_CREATE_SURFACE = "cli_agents_create";
 /** Read hq-pro's company-specific creation prices and capacities. */
 export async function getAgentCreateOptions(token, companyUid, idempotencyKey) {
     const raw = await agentsRequest({
@@ -153,7 +155,9 @@ export async function getAgentCreateOptions(token, companyUid, idempotencyKey) {
         path: "/v1/agents/provision-options",
         query: {
             companyUid,
-            ...(idempotencyKey ? { idempotencyKey } : {}),
+            ...(idempotencyKey
+                ? { idempotencyKey, surface: CLI_AGENT_CREATE_SURFACE }
+                : {}),
         },
     });
     if (!raw || typeof raw !== "object") {
@@ -842,6 +846,7 @@ export function registerAgentsCommand(program) {
                         : { desiredInstanceType: quotedSize.instanceType }),
                     quotedNetMonthlyCents: quotedSize.netMonthlyCents,
                     quoteCatalogVersion: createOptions.catalogVersion,
+                    surface: CLI_AGENT_CREATE_SURFACE,
                 });
                 const uid = typeof result.uid === "string" ? result.uid : slug;
                 console.log(chalk.green(`Provisioning started for agent "${name}".`));
@@ -999,15 +1004,54 @@ export function registerAgentsCommand(program) {
     });
     agents
         .command("config <agentUid>")
-        .description("Update an agent's runtime config (model / reasoning effort / service tier)")
+        .description("Update an agent's runtime config (model / reasoning effort / service tier), or migrate its brain/runtime provider with --provider (DESTRUCTIVE: terminates + reprovisions the box)")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--model <model>", "Codex model id")
         .option("--effort <effort>", "Reasoning effort: minimal | low | medium | high | xhigh")
         .option("--tier <tier>", "Service tier (speed): default | priority")
+        .option("--provider <provider>", "Migrate brain/runtime provider (codex | grok | claude | agents-v2). DESTRUCTIVE: terminates and reprovisions the box; requires --model and --yes.")
+        .option("--auth-mode <mode>", "Provider-migration auth mode: subscription | apiKey (default: keep current)")
+        .option("--api-key-ref <ref>", "Provider-migration apiKey-mode vault key reference (never a raw key)")
+        .option("--yes", "Confirm a destructive provider migration (required with --provider)")
         .option("--json", "Emit raw JSON")
         .action(async function (agentUid, opts) {
         try {
             const patch = {};
+            if (opts.provider !== undefined) {
+                // A `provider` field routes the server to handleProviderMigration,
+                // which TERMINATES and reprovisions the box. Guard it: valid provider,
+                // an explicit target --model (the server requires it), and --yes.
+                // Reuses the module-level VALID_PROVIDERS (shared with `provision`).
+                const provider = opts.provider.trim().toLowerCase();
+                if (!VALID_PROVIDERS.has(provider)) {
+                    console.error(chalk.red(`Invalid --provider '${opts.provider}': must be one of codex, grok, claude, agents-v2`));
+                    process.exit(1);
+                }
+                if (opts.model === undefined) {
+                    console.error(chalk.red("A provider migration requires --model (the target brain's model id)."));
+                    process.exit(1);
+                }
+                if (!opts.yes) {
+                    console.error(chalk.red(`Refusing to migrate agent ${agentUid} to provider '${provider}' without --yes.\n` +
+                        "This TERMINATES and reprovisions the box (irreversible) and changes the auth contract.\n" +
+                        "Re-run with --yes once you have confirmed the exact agent, company, and model."));
+                    process.exit(1);
+                }
+                if (provider !== "agents-v2") {
+                    // v1 RESIDENT runtime guard: codex|grok|claude migrate the agent OFF
+                    // agents-v2 onto the legacy resident runtime. Fleet boxes run
+                    // agents-v2 (brain derived from the model), so this is almost always
+                    // a mistake — warn loudly but proceed (the operator passed --yes).
+                    console.warn(chalk.yellow(`Warning: --provider ${provider} targets the V1 RESIDENT runtime, not agents-v2.\n` +
+                        "Fleet boxes run agents-v2. To keep this agent on the v2 runtime with a\n" +
+                        `${provider} brain, use: --provider agents-v2 --model <${provider} model id>`));
+                }
+                patch.provider = provider;
+                if (opts.authMode !== undefined)
+                    patch.codexAuthMode = opts.authMode;
+                if (opts.apiKeyRef !== undefined)
+                    patch.codexApiKeyRef = opts.apiKeyRef;
+            }
             if (opts.model !== undefined)
                 patch.codexModel = opts.model;
             if (opts.effort !== undefined) {

package/dist/lib/mesh/live/daemon/presence.d.ts

@@ -20,6 +20,20 @@ export type MqttConnectionState = "idle" | "connecting" | "connected" | "reconne
  * then closes immediately after a denied publish).
  */
 export declare const CONNECT_STABLE_GRACE_MS = 5000;
+/**
+ * Hard floor for the delay between MQTT presence reconnect attempts.
+ *
+ * The full-jitter backoff can otherwise compute ~0 ms: after a connection
+ * survives {@link CONNECT_STABLE_GRACE_MS} the connect handler resets both
+ * `attempt` and `lastBackoffMs` to 0, so a broker that accepts-then-closes just
+ * past the grace window makes the next `backoffDelayMs(0, base, cap, random, 0)`
+ * return `random() * base` — frequently a handful of ms, or 0 when `random()`
+ * is near 0. That produces a tight reconnect loop (each pass re-runs the SigV4
+ * presign and re-materialises the daemon state dir) that pins a CPU core with
+ * no network progress and no log output. This floor guarantees every reconnect
+ * waits at least this long regardless of the backoff/grace-reset state.
+ */
+export declare const RECONNECT_MIN_DELAY_MS = 1000;
 /** Always emit the first N close info lines, then at most one per interval. */
 export declare const CLOSE_LOG_ALWAYS_COUNT = 3;
 export declare const CLOSE_LOG_INTERVAL_MS = 60000;
@@ -69,9 +83,13 @@ export interface PresenceClientOptions {
 }
 /**
  * Full-jitter capped exponential backoff (1s base → 60s cap by default),
- * floored at `previousMs` so consecutive failures never shrink the delay.
+ * floored at `previousMs` so consecutive failures never shrink the delay and at
+ * `minMs` so the result can never collapse to ~0 (see
+ * {@link RECONNECT_MIN_DELAY_MS}). The `minMs` floor is what prevents the
+ * accept-then-close reconnect spin after the connect handler resets the
+ * backoff counters.
  */
-export declare function backoffDelayMs(attempt: number, baseMs: number, maxMs: number, random: () => number, previousMs?: number): number;
+export declare function backoffDelayMs(attempt: number, baseMs: number, maxMs: number, random: () => number, previousMs?: number, minMs?: number): number;
 export declare function buildPresencePayload(input: {
     status: "online" | "offline";
     actorUid: string;

package/dist/lib/mesh/live/daemon/presence.js

@@ -20,17 +20,35 @@ import { presignIotWssUrl } from "./presign.js";
  * then closes immediately after a denied publish).
  */
 export const CONNECT_STABLE_GRACE_MS = 5_000;
+/**
+ * Hard floor for the delay between MQTT presence reconnect attempts.
+ *
+ * The full-jitter backoff can otherwise compute ~0 ms: after a connection
+ * survives {@link CONNECT_STABLE_GRACE_MS} the connect handler resets both
+ * `attempt` and `lastBackoffMs` to 0, so a broker that accepts-then-closes just
+ * past the grace window makes the next `backoffDelayMs(0, base, cap, random, 0)`
+ * return `random() * base` — frequently a handful of ms, or 0 when `random()`
+ * is near 0. That produces a tight reconnect loop (each pass re-runs the SigV4
+ * presign and re-materialises the daemon state dir) that pins a CPU core with
+ * no network progress and no log output. This floor guarantees every reconnect
+ * waits at least this long regardless of the backoff/grace-reset state.
+ */
+export const RECONNECT_MIN_DELAY_MS = 1_000;
 /** Always emit the first N close info lines, then at most one per interval. */
 export const CLOSE_LOG_ALWAYS_COUNT = 3;
 export const CLOSE_LOG_INTERVAL_MS = 60_000;
 /**
  * Full-jitter capped exponential backoff (1s base → 60s cap by default),
- * floored at `previousMs` so consecutive failures never shrink the delay.
+ * floored at `previousMs` so consecutive failures never shrink the delay and at
+ * `minMs` so the result can never collapse to ~0 (see
+ * {@link RECONNECT_MIN_DELAY_MS}). The `minMs` floor is what prevents the
+ * accept-then-close reconnect spin after the connect handler resets the
+ * backoff counters.
  */
-export function backoffDelayMs(attempt, baseMs, maxMs, random, previousMs = 0) {
+export function backoffDelayMs(attempt, baseMs, maxMs, random, previousMs = 0, minMs = 0) {
     const cap = Math.min(maxMs, baseMs * 2 ** attempt);
     const raw = Math.max(0, random() * cap);
-    return Math.min(maxMs, Math.max(previousMs, raw));
+    return Math.min(maxMs, Math.max(previousMs, raw, minMs));
 }
 export function buildPresencePayload(input) {
     return {
@@ -341,12 +359,14 @@ export class PresenceClient {
             else {
                 delay = refusedRetryDelayMs(this.refusedRetryMs, this.random);
             }
-            delay = clampRetryDelayMs(delay);
+            // Floor the refused retry too: a server `Retry-After: 0` (or a 0 env
+            // override) would otherwise clamp to 0 and hot-loop the refused path.
+            delay = Math.max(RECONNECT_MIN_DELAY_MS, clampRetryDelayMs(delay));
             const nextRetryAt = new Date(this.timers.now() + delay).toISOString();
             this.noteRefusal(refused, nextRetryAt);
         }
         else {
-            delay = backoffDelayMs(this.attempt, this.baseBackoffMs, this.maxBackoffMs, this.random, this.lastBackoffMs);
+            delay = backoffDelayMs(this.attempt, this.baseBackoffMs, this.maxBackoffMs, this.random, this.lastBackoffMs, RECONNECT_MIN_DELAY_MS);
             this.lastBackoffMs = delay;
             this.attempt += 1;
             // Do not clear refusal here — MQTT close must retain doctor/status refusal

package/dist/lib/mesh/live/daemon/run.d.ts

@@ -15,6 +15,16 @@ import { PresenceClient, type MqttConnectFn } from "./presence.js";
 import { TranscriptWatcher, type TranscriptFs } from "./transcript-watch.js";
 export declare const SPOOL_DEBOUNCE_MS = 2000;
 export declare const FLUSH_INTERVAL_MS = 10000;
+/**
+ * Only producer appends to spool.jsonl should wake the watcher. Every other
+ * file in the work-mesh root (held.jsonl, spool.<ts>.claimed, held.<ts>.claimed,
+ * live-cache.json, dead-letter.jsonl, ...) is written by the daemon itself
+ * during a flush; reacting to those turned each flush into a self-triggered
+ * flush 2s later, forever (observed ~1,750 watch flushes/hour and >50% of a
+ * core on fleet boxes with a non-empty held file). A null filename (platforms
+ * that do not report one) keeps the conservative behaviour and flushes.
+ */
+export declare function shouldFlushOnSpoolDirEvent(filename: string | Buffer | null | undefined): boolean;
 export interface DaemonRunDeps {
     home?: string;
     env?: NodeJS.ProcessEnv;

package/dist/lib/mesh/live/daemon/run.js

@@ -17,7 +17,7 @@ import { ensureCognitoToken } from "../../../../utils/cognito-session.js";
 import { replayOutbox } from "../../../work-context/outbox.js";
 import { workContextRoot } from "../../../work-context/paths.js";
 import { createSessionEventsPoster, resolveVaultApiBase, } from "../session-events-client.js";
-import { flushSessionEvents } from "../flush.js";
+import { flushSessionEvents, HELD_RETRY_INTERVAL_MS, } from "../flush.js";
 import { workMeshRoot, workMeshSpoolPath } from "../paths.js";
 import { createVaultBoardReader, refreshBoundSessionBoards, BOARD_REFRESH_INTERVAL_MS, } from "./board-refresh.js";
 import { createContract3Fetcher, realTimerHost, } from "./credentials.js";
@@ -30,6 +30,20 @@ import { workMeshHeldPath } from "../paths.js";
 import { noteHookSessionsFromSpoolFile, TRANSCRIPT_WATCH_INTERVAL_MS, TranscriptWatcher, } from "./transcript-watch.js";
 export const SPOOL_DEBOUNCE_MS = 2_000;
 export const FLUSH_INTERVAL_MS = 10_000;
+/**
+ * Only producer appends to spool.jsonl should wake the watcher. Every other
+ * file in the work-mesh root (held.jsonl, spool.<ts>.claimed, held.<ts>.claimed,
+ * live-cache.json, dead-letter.jsonl, ...) is written by the daemon itself
+ * during a flush; reacting to those turned each flush into a self-triggered
+ * flush 2s later, forever (observed ~1,750 watch flushes/hour and >50% of a
+ * core on fleet boxes with a non-empty held file). A null filename (platforms
+ * that do not report one) keeps the conservative behaviour and flushes.
+ */
+export function shouldFlushOnSpoolDirEvent(filename) {
+    if (filename === null || filename === undefined)
+        return true;
+    return String(filename) === "spool.jsonl";
+}
 function alive(pid) {
     try {
         process.kill(pid, 0);
@@ -76,6 +90,8 @@ export async function runMeshDaemon(deps = {}) {
     // daemon went dark once its IoT credentials expired.
     const defaultGetToken = async () => ensureCognitoToken({ interactive: false, tokenSource: "machine" });
     const getToken = deps.getToken ?? defaultGetToken;
+    /** In-memory held re-attempt throttle (survives watch-triggered flushes). */
+    let lastHeldRetryAtMs = 0;
     const flushFn = deps.flush ??
         (async () => {
             const t = await getToken();
@@ -87,6 +103,12 @@ export async function runMeshDaemon(deps = {}) {
                 workMeshRoot: meshRoot,
                 workContextRoot: ctxRoot,
                 poster,
+                heldRetryIntervalMs: HELD_RETRY_INTERVAL_MS,
+                lastHeldRetryAtMs,
+                onHeldClaimed: (atMs) => {
+                    lastHeldRetryAtMs = atMs;
+                },
+                log: (message) => log(dir, message),
             });
         });
     const replayFn = deps.replayOutbox ??
@@ -243,7 +265,10 @@ export async function runMeshDaemon(deps = {}) {
                     lastFlushAt: now().toISOString(),
                     lastFlushResult: { ...summary, ok: true },
                 }, now);
-                if (summary.claimed > 0 || summary.posted > 0 || summary.held > 0) {
+                if (summary.claimed > 0 ||
+                    summary.posted > 0 ||
+                    summary.held > 0 ||
+                    (summary.heldOverflow ?? 0) > 0) {
                     log(dir, `flush(${reason}): claimed=${summary.claimed} posted=${summary.posted} held=${summary.held}`);
                 }
             }
@@ -292,11 +317,7 @@ export async function runMeshDaemon(deps = {}) {
         watcher = fs.watch(path.dirname(spoolPath), { persistent: true }, (_event, filename) => {
             if (stopped)
                 return;
-            if (!filename ||
-                filename === "spool.jsonl" ||
-                filename === "held.jsonl" ||
-                String(filename).startsWith("spool.") ||
-                String(filename).startsWith("held.")) {
+            if (shouldFlushOnSpoolDirEvent(filename)) {
                 scheduleDebouncedFlush();
             }
         });

package/dist/lib/mesh/live/flush.d.ts

@@ -11,7 +11,11 @@
 import { type RandomFn, type SleepFn } from "./backoff.js";
 import { type SessionEventsPoster } from "./session-events-client.js";
 export declare const HELD_TTL_MS: number;
-export type HeldReason = "STATE_ABSENT" | "NEEDS_COMPANY" | "COMPANY_CONFLICT" | "HELD_EXPIRED";
+/** Re-attempt held events at most this often (spool still flushes every cycle). */
+export declare const HELD_RETRY_INTERVAL_MS: number;
+/** Cap held.jsonl size; oldest overflow is dead-lettered with HELD_OVERFLOW. */
+export declare const HELD_MAX_LINES = 20000;
+export type HeldReason = "STATE_ABSENT" | "NEEDS_COMPANY" | "COMPANY_CONFLICT" | "HELD_EXPIRED" | "HELD_OVERFLOW";
 export interface HeldLineRecord {
     /** Original spool event fields. */
     event: Record<string, unknown>;
@@ -26,6 +30,19 @@ export interface FlushDeps {
     sleep?: SleepFn;
     random?: RandomFn;
     maxAttempts?: number;
+    /**
+     * Minimum gap between held re-attempts. Default HELD_RETRY_INTERVAL_MS.
+     * Pass 0 in tests to re-claim held every flush.
+     */
+    heldRetryIntervalMs?: number;
+    /** Epoch ms of the last flush that claimed held (daemon keeps this in memory). */
+    lastHeldRetryAtMs?: number;
+    /** Invoked when this flush claims held, so the daemon can advance its timestamp. */
+    onHeldClaimed?: (atMs: number) => void;
+    /** Max lines retained in held.jsonl after a flush. Default HELD_MAX_LINES. */
+    heldMaxLines?: number;
+    /** Optional logger (daemon wires this); used once per overflow trim. */
+    log?: (message: string) => void;
 }
 export interface FlushSummary {
     claimed: number;
@@ -35,6 +52,10 @@ export interface FlushSummary {
     deadLettered: number;
     restored: number;
     batches: number;
+    /** True when this flush claimed/re-read held.jsonl. */
+    heldClaimed?: boolean;
+    /** Oldest held lines dead-lettered this flush due to HELD_MAX_LINES. */
+    heldOverflow?: number;
 }
 /**
  * Flush spool + held. Safe to call concurrently with enqueue (claim-by-rename).

package/dist/lib/mesh/live/flush.js

@@ -15,9 +15,13 @@ import { workContextRoot } from "../../work-context/paths.js";
 import { defaultSleep, FLUSH_MAX_ATTEMPTS, fullJitterDelayMs, } from "./backoff.js";
 import { LOCAL_ONLY_FIELDS, stripLocalOnlyFields } from "./format-spool-line.js";
 import { SESSION_EVENTS_BATCH_MAX, WRITABLE_CONTEXT_STATUSES, parseSessionEventsBatchAck, } from "./session-events-client.js";
-import { appendDeadLetterLine, appendDroppedReceipt, appendHeldLine, appendSpoolLine, claimHeld, claimSpool, recoverOrphanClaims, removeClaimFile, } from "./spool.js";
-import { workMeshRoot } from "./paths.js";
+import { appendDeadLetterLine, appendDroppedReceipt, appendHeldLine, appendSpoolLine, claimHeld, claimSpool, countJsonlLines, ensureSpoolFile, recoverOrphanClaims, removeClaimFile, } from "./spool.js";
+import { workMeshHeldPath, workMeshRoot } from "./paths.js";
 export const HELD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** Re-attempt held events at most this often (spool still flushes every cycle). */
+export const HELD_RETRY_INTERVAL_MS = 5 * 60 * 1000;
+/** Cap held.jsonl size; oldest overflow is dead-lettered with HELD_OVERFLOW. */
+export const HELD_MAX_LINES = 20_000;
 function parseLine(line) {
     try {
         const v = JSON.parse(line);
@@ -101,10 +105,22 @@ export async function flushSessionEvents(deps) {
     const sleep = deps.sleep ?? defaultSleep;
     const random = deps.random ?? Math.random;
     const maxAttempts = deps.maxAttempts ?? FLUSH_MAX_ATTEMPTS;
-    const ts = `${now().getTime()}`;
+    const heldRetryIntervalMs = deps.heldRetryIntervalMs ?? HELD_RETRY_INTERVAL_MS;
+    const heldMaxLines = deps.heldMaxLines ?? HELD_MAX_LINES;
+    const nowMs = now().getTime();
+    const ts = `${nowMs}`;
     const orphans = recoverOrphanClaims(deps.workMeshRoot);
     const spoolClaim = claimSpool(deps.workMeshRoot, ts);
-    const heldClaim = claimHeld(deps.workMeshRoot, `${ts}.held`);
+    // Throttle held re-attempts; spool (fresh) events still flush every cycle.
+    const lastHeldRetryAtMs = deps.lastHeldRetryAtMs ?? 0;
+    const shouldClaimHeld = heldRetryIntervalMs <= 0 ||
+        nowMs - lastHeldRetryAtMs >= heldRetryIntervalMs;
+    const heldClaim = shouldClaimHeld
+        ? claimHeld(deps.workMeshRoot, `${ts}.held`)
+        : { claimPath: null, lines: [] };
+    if (shouldClaimHeld) {
+        deps.onHeldClaimed?.(nowMs);
+    }
     const claimPaths = [
         ...orphans.claimPaths,
         spoolClaim.claimPath,
@@ -118,42 +134,45 @@ export async function flushSessionEvents(deps) {
         deadLettered: 0,
         restored: 0,
         batches: 0,
+        heldClaimed: shouldClaimHeld,
+        heldOverflow: 0,
     };
-    /** Original events still awaiting disposition (restored on throw). */
-    const pendingRestore = [];
+    /** Original events still awaiting disposition (restored on throw). O(1) delete. */
+    const pendingRestore = new Set();
     const collected = [];
     try {
-        for (const line of [...orphans.lines, ...spoolClaim.lines, ...heldClaim.lines]) {
-            summary.claimed += 1;
-            const parsed = parseLine(line);
-            if (!parsed) {
-                appendDeadLetterLine(deadLetterEnvelope({ raw: line.slice(0, 200) }, "SCHEMA_REJECTED", "parse_error", now().toISOString()), deps.workMeshRoot);
-                summary.deadLettered += 1;
-                continue;
-            }
-            const { event, heldAt } = unwrapHeld(parsed);
-            if (!sessionIdOf(event)) {
-                appendDeadLetterLine(deadLetterEnvelope(event, "SCHEMA_REJECTED", "missing_sessionId", now().toISOString()), deps.workMeshRoot);
-                summary.deadLettered += 1;
-                continue;
-            }
-            // Expire held lines older than 7 days.
-            if (heldAt) {
-                const age = now().getTime() - Date.parse(heldAt);
-                if (Number.isFinite(age) && age > HELD_TTL_MS) {
-                    appendDeadLetterLine(deadLetterEnvelope(event, "HELD_EXPIRED", "held_ttl", now().toISOString()), deps.workMeshRoot);
+        // Iterate sources separately — avoid building one giant combined array.
+        for (const source of [orphans.lines, spoolClaim.lines, heldClaim.lines]) {
+            for (const line of source) {
+                summary.claimed += 1;
+                const parsed = parseLine(line);
+                if (!parsed) {
+                    appendDeadLetterLine(deadLetterEnvelope({ raw: line.slice(0, 200) }, "SCHEMA_REJECTED", "parse_error", now().toISOString()), deps.workMeshRoot);
+                    summary.deadLettered += 1;
+                    continue;
+                }
+                const { event, heldAt } = unwrapHeld(parsed);
+                if (!sessionIdOf(event)) {
+                    appendDeadLetterLine(deadLetterEnvelope(event, "SCHEMA_REJECTED", "missing_sessionId", now().toISOString()), deps.workMeshRoot);
                     summary.deadLettered += 1;
                     continue;
                 }
+                // Expire held lines older than 7 days.
+                if (heldAt) {
+                    const age = now().getTime() - Date.parse(heldAt);
+                    if (Number.isFinite(age) && age > HELD_TTL_MS) {
+                        appendDeadLetterLine(deadLetterEnvelope(event, "HELD_EXPIRED", "held_ttl", now().toISOString()), deps.workMeshRoot);
+                        summary.deadLettered += 1;
+                        continue;
+                    }
+                }
+                pendingRestore.add(event);
+                collected.push({ event, heldAt });
             }
-            pendingRestore.push(event);
-            collected.push({ event, heldAt });
         }
         const bySession = groupBySession(collected);
         const markDisposed = (event) => {
-            const idx = pendingRestore.indexOf(event);
-            if (idx >= 0)
-                pendingRestore.splice(idx, 1);
+            pendingRestore.delete(event);
         };
         for (const [sessionId, items] of bySession) {
             const state = readSessionState(sessionId, deps.workContextRoot);
@@ -238,13 +257,100 @@ export async function flushSessionEvents(deps) {
                 /* best-effort; orphan claim scan will retry next flush */
             }
         }
-        pendingRestore.length = 0;
+        pendingRestore.clear();
         for (const p of claimPaths) {
             removeClaimFile(p);
         }
     }
+    const overflowed = trimHeldOverflow(deps.workMeshRoot, heldMaxLines, now, summary);
+    if (overflowed > 0) {
+        deps.log?.(`held overflow: dead-lettered ${overflowed} oldest events (cap=${heldMaxLines})`);
+    }
     return summary;
 }
+/**
+ * After a flush, if held.jsonl exceeds maxLines, dead-letter the oldest
+ * overflow (by heldAt, not file position) with HELD_OVERFLOW and keep the rest.
+ *
+ * Durability rules:
+ * - Retained lines are APPENDED to held.jsonl, never written over it: another
+ *   flusher (`hq mesh flush` beside the daemon) may have appended to a fresh
+ *   held.jsonl after our claim renamed the old one away.
+ * - The overflow claim file is removed only after every dead letter and every
+ *   retained line is on disk. If anything throws, the claim stays behind and
+ *   recoverOrphanClaims re-reads it on the next flush (duplicates are possible,
+ *   loss is not).
+ */
+function trimHeldOverflow(meshRoot, maxLines, now, summary) {
+    if (maxLines <= 0)
+        return 0;
+    const heldPath = workMeshHeldPath(meshRoot);
+    if (countJsonlLines(heldPath) <= maxLines)
+        return 0;
+    const claim = claimHeld(meshRoot, `${now().getTime()}.overflow`);
+    if (!claim.claimPath)
+        return 0;
+    if (claim.lines.length === 0) {
+        removeClaimFile(claim.claimPath);
+        return 0;
+    }
+    try {
+        if (claim.lines.length <= maxLines) {
+            appendHeldLines(meshRoot, claim.lines);
+            removeClaimFile(claim.claimPath);
+            return 0;
+        }
+        const overflow = claim.lines.length - maxLines;
+        // Oldest by heldAt: retries regroup held by session, so file order is not
+        // chronological. Unparseable lines sort first (dead-lettered first).
+        const ordered = claim.lines
+            .map((line, idx) => ({ line, idx, atMs: heldAtMs(line) }))
+            .sort((a, b) => a.atMs - b.atMs || a.idx - b.idx);
+        const toDead = ordered.slice(0, overflow);
+        const toKeep = ordered
+            .slice(overflow)
+            .sort((a, b) => a.idx - b.idx)
+            .map((x) => x.line);
+        const at = now().toISOString();
+        for (const { line } of toDead) {
+            const parsed = parseLine(line);
+            if (!parsed) {
+                appendDeadLetterLine(deadLetterEnvelope({ raw: line.slice(0, 200) }, "HELD_OVERFLOW", "held_max_lines", at), meshRoot);
+            }
+            else {
+                const { event } = unwrapHeld(parsed);
+                appendDeadLetterLine(deadLetterEnvelope(event, "HELD_OVERFLOW", "held_max_lines", at), meshRoot);
+            }
+            summary.deadLettered += 1;
+        }
+        appendHeldLines(meshRoot, toKeep);
+        summary.heldOverflow = overflow;
+        removeClaimFile(claim.claimPath);
+        return overflow;
+    }
+    catch {
+        // Leave the claim for orphan recovery; never drop held events on a failed trim.
+        return 0;
+    }
+}
+/** heldAt of a held line as epoch ms; 0 when missing or unparseable. */
+function heldAtMs(line) {
+    const parsed = parseLine(line);
+    if (!parsed)
+        return 0;
+    const { heldAt } = unwrapHeld(parsed);
+    if (!heldAt)
+        return 0;
+    const ms = Date.parse(heldAt);
+    return Number.isFinite(ms) ? ms : 0;
+}
+function appendHeldLines(meshRoot, lines) {
+    if (lines.length === 0)
+        return;
+    const heldPath = workMeshHeldPath(meshRoot);
+    ensureSpoolFile(heldPath);
+    fs.appendFileSync(heldPath, `${lines.join("\n")}\n`, { mode: 0o600 });
+}
 /**
  * Account a 2xx batch: dead-letter rejected eventIds with their codes;
  * count accepted+duplicates as posted; restore any eventId not accounted for.

package/dist/lib/mesh/live/index.d.ts

@@ -13,7 +13,7 @@ export { workMeshClaimPath, workMeshDeadLetterPath, workMeshDroppedReceiptPath,
 export { SPOOL_LINE_MAX_BYTES, SpoolWriteError, appendDeadLetterLine, appendDroppedReceipt, appendHeldLine, appendJsonlLine, appendSpoolLine, claimHeld, claimJsonlByRename, claimSpool, countJsonlLines, deadLetterNonEmpty, ensureSpoolFile, removeClaimFile, } from "./spool.js";
 export { CLI_KIND_TO_SCHEMA, EnqueueValidationError, enqueueSessionEvent, resolveEnqueueSessionId, } from "./enqueue.js";
 export type { EnqueueOptions, EnqueueResult } from "./enqueue.js";
-export { HELD_TTL_MS, assertNoBindCacheAccess, bindCacheExists, defaultFlushRoots, flushSessionEvents, sessionsBindPath, } from "./flush.js";
+export { HELD_MAX_LINES, HELD_RETRY_INTERVAL_MS, HELD_TTL_MS, assertNoBindCacheAccess, bindCacheExists, defaultFlushRoots, flushSessionEvents, sessionsBindPath, } from "./flush.js";
 export type { FlushDeps, FlushSummary, HeldReason } from "./flush.js";
 export { BACKOFF_BASE_MS, BACKOFF_CAP_MS, FLUSH_MAX_ATTEMPTS, defaultSleep, fullJitterDelayMs, } from "./backoff.js";
 export { SESSION_EVENTS_BATCH_MAX, SESSION_EVENTS_PATH, WRITABLE_CONTEXT_STATUSES, classifySessionEventsResponse, createSessionEventsPoster, resolveVaultApiBase, } from "./session-events-client.js";

package/dist/lib/mesh/live/index.js

@@ -9,7 +9,7 @@ export { encodeCrockford, generateUlid, isUlid } from "./ulid.js";
 export { workMeshClaimPath, workMeshDeadLetterPath, workMeshDroppedReceiptPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "./paths.js";
 export { SPOOL_LINE_MAX_BYTES, SpoolWriteError, appendDeadLetterLine, appendDroppedReceipt, appendHeldLine, appendJsonlLine, appendSpoolLine, claimHeld, claimJsonlByRename, claimSpool, countJsonlLines, deadLetterNonEmpty, ensureSpoolFile, removeClaimFile, } from "./spool.js";
 export { CLI_KIND_TO_SCHEMA, EnqueueValidationError, enqueueSessionEvent, resolveEnqueueSessionId, } from "./enqueue.js";
-export { HELD_TTL_MS, assertNoBindCacheAccess, bindCacheExists, defaultFlushRoots, flushSessionEvents, sessionsBindPath, } from "./flush.js";
+export { HELD_MAX_LINES, HELD_RETRY_INTERVAL_MS, HELD_TTL_MS, assertNoBindCacheAccess, bindCacheExists, defaultFlushRoots, flushSessionEvents, sessionsBindPath, } from "./flush.js";
 export { BACKOFF_BASE_MS, BACKOFF_CAP_MS, FLUSH_MAX_ATTEMPTS, defaultSleep, fullJitterDelayMs, } from "./backoff.js";
 export { SESSION_EVENTS_BATCH_MAX, SESSION_EVENTS_PATH, WRITABLE_CONTEXT_STATUSES, classifySessionEventsResponse, createSessionEventsPoster, resolveVaultApiBase, } from "./session-events-client.js";
 export * from "./daemon/index.js";

package/dist/lib/mesh/live/spool.js

@@ -153,7 +153,12 @@ export function recoverOrphanClaims(root) {
     const claimPaths = listOrphanClaimFiles(root);
     const lines = [];
     for (const p of claimPaths) {
-        lines.push(...readClaimFileLines(p));
+        // Plain loop: Array#push(...huge) exceeds V8's argument limit (~65k–128k)
+        // and throws RangeError ("Maximum call stack size exceeded").
+        const orphanLines = readClaimFileLines(p);
+        for (const line of orphanLines) {
+            lines.push(line);
+        }
     }
     return { lines, claimPaths };
 }

package/dist/main.js

@@ -23,6 +23,7 @@ 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 { hqStateWriteErrorMessage } from "./utils/hq-state-write-error.js";
+import { incompleteInstallMessage, incompleteInstallCaptureContext, } from "./utils/incomplete-install-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isVarlockEnvError } from "./run/env-graph-guard.js";
 import { isEpipe } from "./utils/epipe.js";
@@ -515,7 +516,28 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         const stateWriteMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg
             ? null
             : hqStateWriteErrorMessage(err);
-        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg
+        // An IN-PROCESS module-load failure that means hq-cli's OWN installed
+        // package tree is incomplete at load time — a partial/interrupted global
+        // install left a bundled file unwritten (HQ-CLI-1N, a CJS relative-sibling
+        // MODULE_NOT_FOUND), or a concurrent global install rewrote the running
+        // tree so an ESM module present at resolve was gone at read (HQ-CLI-1M, an
+        // esm-loader ENOENT). Both carry no hq-cli frames and reached the final
+        // else, filing a bare crash and an unactionable line. An incomplete
+        // install is the caller's machine, the disposition HQ-CLI-Y already
+        // established for the qmd CHILD — print the input-free reinstall remedy and
+        // skip capture. Placed with the environmental family (after the typed qmd
+        // carriers and the hq state-write carrier, before environmentalFsErrorMessage):
+        // the signatures are disjoint — ENVIRONMENTAL_FS_CODES is only
+        // ENOSPC/EDQUOT/EROFS (never ENOENT/MODULE_NOT_FOUND), no qmd carrier sets
+        // requireStack or an esm-loader frame, and the classified file must sit
+        // under <packageRoot>/node_modules — so ordering changes nothing that
+        // exists. The UNATTRIBUTABLE shape (an esm-loader ENOENT whose path did not
+        // survive) is deliberately NOT suppressed; it is captured WITH bounded
+        // context on the generic path below.
+        const incompleteInstallMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg
+            ? null
+            : incompleteInstallMessage(err);
+        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg || incompleteInstallMsg
             ? null
             : environmentalFsErrorMessage(err);
         // A LOCAL sync-state lock failure (@indigoai-us/hq-cloud's
@@ -532,7 +554,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // environmental-fs check, before network-transport — is pinned by tests.
         // The `in-process-async-holder` reason is deliberately NOT suppressed here
         // (see sync-state-lock-error.ts); it stays captured.
-        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg || envMsg
+        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg || incompleteInstallMsg || envMsg
             ? null
             : syncStateLockMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
@@ -556,6 +578,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             modelDownloadMsg ||
             workdirMissingMsg ||
             stateWriteMsg ||
+            incompleteInstallMsg ||
             envMsg ||
             lockMsg
             ? null
@@ -593,6 +616,9 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (stateWriteMsg) {
             deps.stderr.write(`hq: ${stateWriteMsg}\n`);
         }
+        else if (incompleteInstallMsg) {
+            deps.stderr.write(`hq: ${incompleteInstallMsg}\n`);
+        }
         else if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }
@@ -603,13 +629,18 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             deps.stderr.write(`hq: ${transportMsg}\n`);
         }
         else {
-            // A genuinely unclassified fault is still captured exactly once. When it
-            // is a qmd spawn-level failure the fix could not attribute, attach the
-            // bounded existence context so the next occurrence carries the evidence
-            // the reported HQ-CLI-1A event lacked; every other error captures bare.
+            // A genuinely unclassified fault is still captured exactly once. Two
+            // shapes attach bounded, hq-derived context so the next occurrence
+            // carries the evidence this one lacked: a qmd spawn-level failure the fix
+            // could not attribute (HQ-CLI-1A), and an esm-loader ENOENT whose path
+            // did not survive delivery (HQ-CLI-1M — the unattributable incomplete-
+            // install shape). Every other error captures bare, exactly as before.
             const spawnContext = qmdSpawnFailureCaptureContext(err);
-            if (spawnContext) {
-                deps.sentry.captureException(err, spawnContext);
+            const installContext = incompleteInstallCaptureContext(err);
+            if (spawnContext || installContext) {
+                deps.sentry.captureException(err, {
+                    contexts: { ...spawnContext?.contexts, ...installContext },
+                });
             }
             else {
                 deps.sentry.captureException(err);

package/dist/sentry.js

@@ -6,6 +6,7 @@ import { CLI_VERSION } from "./cli-version.js";
 import { getCachedSentryUser } from "./utils/sentry-identity.js";
 import { isEpipe } from "./utils/epipe.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { incompleteInstallMessage } from "./utils/incomplete-install-error.js";
 import { sentryFingerprintFor } from "./utils/sentry-fingerprint.js";
 /**
  * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
@@ -31,6 +32,20 @@ export function epipeAwareBeforeSend(event, hint) {
     // route, while the CLI still exits non-zero. HQ-CLI-R (Sentry 7671416365).
     if (environmentalFsErrorMessage(hint?.originalException))
         return null;
+    // Path-independent belt for an IN-PROCESS incomplete-install module-load
+    // failure — hq-cli's own globally installed tree is not intact at load time
+    // (HQ-CLI-1N, a CJS relative-sibling MODULE_NOT_FOUND under its bundled
+    // node_modules; HQ-CLI-1M, an esm-loader ENOENT for a file present at resolve
+    // and gone at read). handleTopLevelError already prints the reinstall remedy
+    // for the top-level route; dropping the event here suppresses the fatal
+    // regardless of route — the unhandled-rejection boundary, the command-level
+    // captureException sites, and bin/hq-auth-refresh — mirroring the EPIPE and
+    // environmental-fs drops above. The classifier reads only structured fields
+    // and the failing file must sit under the running install's node_modules, so
+    // an hq-cli packaging fault (a dist/ miss, a bare-specifier miss) and the
+    // path-less unattributable shape are NOT dropped here and stay captured.
+    if (incompleteInstallMessage(hint?.originalException))
+        return null;
     // Group an event that survives to send by a BOUNDED machine discriminator so
     // unrelated gateway/HTTP failures stop colliding into one fungible issue
     // (HQ-CLI collision, Sentry 7642756130). Placed here — path-independent,

package/dist/utils/incomplete-install-error.d.ts

@@ -0,0 +1,50 @@
+import * as fs from "fs";
+/**
+ * The actionable remedy shown to the operator. Input-free — nothing from the
+ * error, the argv, or the filesystem is interpolated — so there is no injection
+ * surface and no way to inflate Sentry grouping, matching the bounded-remedy
+ * discipline of every sibling classifier. Covers BOTH sub-cases in the order a
+ * user should try them: re-run first (an install that finished mid-run leaves
+ * the next invocation healthy), then reinstall if it persists.
+ */
+export declare const INCOMPLETE_INSTALL_REMEDY: string;
+/** A resolver for the running install's root; returns null instead of throwing. */
+export type PackageRootResolver = () => string | null;
+/**
+ * If `err` is an in-process incomplete-install module-load failure — either the
+ * CJS relative-sibling shape (HQ-CLI-1N) or the ESM vanished-file shape
+ * (HQ-CLI-1M), with the failing file confirmed under `<packageRoot>/node_modules/`
+ * — return the actionable, input-free reinstall remedy; otherwise return null.
+ *
+ * Mirrors qmdModuleMissingMessage so the top-level handler and beforeSend branch
+ * the same way: a non-null result means print-the-remedy-and-skip-Sentry, null
+ * means "handle as usual (capture to Sentry)". Never throws — a resolver that
+ * fails yields null.
+ */
+export declare function incompleteInstallMessage(err: unknown, resolvePackageRoot?: PackageRootResolver): string | null;
+/** Bounded, scrubber-safe diagnostics for an unattributable esm-loader ENOENT. */
+export type IncompleteInstallDiagnostics = {
+    packageRoot: string;
+    packageJsonExists: boolean;
+    nodeModulesExists: boolean;
+    esmLoaderFrame: boolean;
+    code: string;
+};
+/**
+ * When an esm-loader ENOENT reaches the capture path WITHOUT being suppressed —
+ * the exact shape the delivered HQ-CLI-1M payload arrived in, where neither the
+ * exception value nor node_system_error carried a `path` — return a bounded
+ * `contexts.incomplete_install` block so the next occurrence carries the
+ * evidence this one lacked; otherwise return undefined (bare capture). Built
+ * with the byte-capped, scrubber-safe discipline of package-root-diagnostics.ts:
+ * the resolved package root and whether its package.json / node_modules exist,
+ * the loader-frame marker, and the bounded errno code — never a caller argv,
+ * query, or user-minted value. Never throws.
+ *
+ * main.ts attaches this on the generic capture path exactly as
+ * qmdSpawnFailureCaptureContext already does.
+ */
+export declare function incompleteInstallCaptureContext(err: unknown, resolvePackageRoot?: PackageRootResolver, fileSystem?: Pick<typeof fs, "existsSync">): {
+    incomplete_install: IncompleteInstallDiagnostics;
+} | undefined;
+//# sourceMappingURL=incomplete-install-error.d.ts.map

package/dist/utils/incomplete-install-error.js

@@ -0,0 +1,250 @@
+// src/utils/incomplete-install-error.ts
+//
+// Classify an IN-PROCESS module-load failure that means hq-cli's OWN globally
+// installed package tree is not intact at the moment it loads a module — the
+// caller's incomplete install, not an hq-cli code defect. Sibling in spirit to
+// qmd-module-missing-error.ts (HQ-CLI-Y), but keyed on the ERROR OBJECT of a
+// failure inside THIS process rather than a qmd child's captured stderr, which
+// is the gap HQ-CLI-Y's classifier cannot cover.
+//
+// Two shapes, one cause — a partial/interrupted global install left a file
+// unwritten, or a concurrent global install rewrote the running tree
+// underneath a command:
+//
+//   HQ-CLI-1N (Sentry 7714890525) — CJS, in-process. `hq core timeout-guard`
+//   loads the mesh presence client, whose `import mqtt` pulls a chain that ends
+//   at js-sdsl requiring a RELATIVE sibling (`./Base/TreeIterator`) that is
+//   absent on disk inside hq-cli's own bundled node_modules. Node throws
+//   `Error{ code: 'MODULE_NOT_FOUND', requireStack: [...] }`. A relative
+//   specifier internal to a third-party package can only be a truncated on-disk
+//   copy, never an hq-cli manifest defect.
+//
+//   HQ-CLI-1M (Sentry 7714870912) — ESM load, in-process. A module that existed
+//   at RESOLVE was gone at READ (a concurrent writer rewrote the install tree),
+//   so Node's ESM loader raised `ENOENT` from getSourceSync/readFileSync/openSync
+//   with an `esm/…` loader frame in the stack. A merely-absent ESM module raises
+//   ERR_MODULE_NOT_FOUND at resolve, never ENOENT at load; an ENOENT at load
+//   proves the file vanished between resolve and read.
+//
+// Both shapes carry no hq-cli frames, reach the boundary's final `else`, and —
+// before this classifier — filed a bare captureException plus an unactionable
+// `hq: <fallback>` line. The disposition is the one HQ-CLI-Y already
+// established: an incomplete install is the caller's machine, so the CLI prints
+// an input-free reinstall remedy and skips Sentry capture.
+//
+// The gate is deliberately narrow so neither an hq-cli packaging fault nor
+// user free-text can trip it. Only structured fields are read — `code`,
+// `syscall`, `path`, `requireStack`, and the stack's loader-frame marker, plus
+// the first message line for the CJS specifier. THREE independent narrowings
+// keep a genuine hq-cli defect reportable:
+//   1. The failing file must sit under `<packageRoot>/node_modules/` — a
+//      third-party file hq-cli does not author. A miss under `<packageRoot>/dist`
+//      or `/assets` is hq-cli's OWN shipped output and stays captured.
+//   2. The CJS shape additionally requires a RELATIVE specifier — a
+//      bare-specifier miss (`Cannot find module 'mqtt'`) can be an undeclared
+//      dependency (an hq-cli manifest defect) and stays captured.
+//   3. The ESM shape additionally requires an esm-loader frame — an ordinary
+//      `fs.readFileSync` ENOENT written by hq's own code stays captured.
+import * as fs from "fs";
+import * as path from "path";
+import { packageRoot } from "./hq-roots.js";
+import { boundedDiagnosticValue } from "./package-root-diagnostics.js";
+/**
+ * The actionable remedy shown to the operator. Input-free — nothing from the
+ * error, the argv, or the filesystem is interpolated — so there is no injection
+ * surface and no way to inflate Sentry grouping, matching the bounded-remedy
+ * discipline of every sibling classifier. Covers BOTH sub-cases in the order a
+ * user should try them: re-run first (an install that finished mid-run leaves
+ * the next invocation healthy), then reinstall if it persists.
+ */
+export const INCOMPLETE_INSTALL_REMEDY = "hq couldn't load part of its own installed files, so the hq install tree is " +
+    "incomplete on this machine — most often because a global install (its own " +
+    "self-update, the desktop background installer, another hq process, or a " +
+    "hand-run install) rewrote the package while this command was running, or an " +
+    "earlier install was interrupted before every file was written. Run the " +
+    "command again first: an install that finished mid-run leaves the next " +
+    "invocation healthy. If it keeps failing, reinstall hq — for a global install " +
+    "run `npm i -g @indigoai-us/hq-cli` (or the pnpm equivalent, " +
+    "`pnpm add -g @indigoai-us/hq-cli`).";
+/** A relative module specifier — `./x`, `../x`, `.\x`, `..\x`. */
+const RELATIVE_SPECIFIER = /^\.\.?[\\/]/;
+/** A Node ESM loader frame — proves the ENOENT came from the module loader, not hq's own fs call. */
+const ESM_LOADER_FRAME = /node:internal[\\/]modules[\\/]esm[\\/]/;
+const ROOT_DIAGNOSTIC_BYTES = 256;
+const CODE_DIAGNOSTIC_BYTES = 32;
+/**
+ * packageRoot() walks up from the compiled module and THROWS
+ * PackageRootResolutionError when it cannot resolve. This classifier runs inside
+ * beforeSend on EVERY event, so it must never throw — a resolution failure
+ * returns null and the error stays captured.
+ */
+function safePackageRoot() {
+    try {
+        return packageRoot();
+    }
+    catch {
+        return null;
+    }
+}
+/** Call a (possibly injected) resolver without letting it throw. */
+function resolveRootSafely(resolve) {
+    try {
+        return resolve();
+    }
+    catch {
+        return null;
+    }
+}
+/** Fold `\`/`/` runs to a single `/` and drop any trailing separator. */
+function foldSeparators(p) {
+    return p.replace(/[\\/]+/g, "/").replace(/\/+$/, "");
+}
+/** A Windows-shaped absolute path (drive letter or UNC), regardless of host OS. */
+function looksWin32(p) {
+    return /^[a-zA-Z]:[\\/]/.test(p) || /^\\\\/.test(p);
+}
+/**
+ * Normalise a path for prefix comparison: separators folded, and case folded
+ * ONLY for a Windows-shaped path (drive-letter case and AppData\Roaming casing
+ * drift there, but POSIX paths are case-sensitive and must stay so). Detecting
+ * win32 by the path's SHAPE — not `process.platform` — lets the reported
+ * Windows path classify on a Linux CI runner.
+ */
+function normalizeForCompare(p) {
+    const folded = foldSeparators(p);
+    return looksWin32(p) ? folded.toLowerCase() : folded;
+}
+/**
+ * True when `candidate` lives under `<root>/node_modules/`. Anchored at a true
+ * directory boundary (`<root>` + sep + `node_modules` + sep) so a sibling such
+ * as `<root>-old/node_modules/...` can never match.
+ */
+function isUnderNodeModules(candidate, root) {
+    if (!candidate || !root)
+        return false;
+    const prefix = `${normalizeForCompare(root)}/node_modules/`;
+    return normalizeForCompare(candidate).startsWith(prefix);
+}
+/** The failing specifier from a `Cannot find module '<spec>'` message, or null. */
+function parseMissingSpecifier(message) {
+    if (typeof message !== "string")
+        return null;
+    const match = message.match(/Cannot find module ['"]([^'"]+)['"]/);
+    return match ? match[1] : null;
+}
+/** True when `stack` carries a Node ESM loader frame. */
+function hasEsmLoaderFrame(stack) {
+    return typeof stack === "string" && ESM_LOADER_FRAME.test(stack);
+}
+/**
+ * The ESM-loader ENOENT SIGNATURE, independent of whether a usable `path`
+ * survived: `code === 'ENOENT'`, `syscall === 'open'`, and an esm-loader frame
+ * in the stack. This is the shape the instrumentation fallback attaches context
+ * to; the message classifier additionally requires a `path` under node_modules.
+ */
+function isEsmLoaderEnoent(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const record = err;
+    return (record.code === "ENOENT" &&
+        record.syscall === "open" &&
+        hasEsmLoaderFrame(record.stack));
+}
+/**
+ * If `err` is an in-process incomplete-install module-load failure — either the
+ * CJS relative-sibling shape (HQ-CLI-1N) or the ESM vanished-file shape
+ * (HQ-CLI-1M), with the failing file confirmed under `<packageRoot>/node_modules/`
+ * — return the actionable, input-free reinstall remedy; otherwise return null.
+ *
+ * Mirrors qmdModuleMissingMessage so the top-level handler and beforeSend branch
+ * the same way: a non-null result means print-the-remedy-and-skip-Sentry, null
+ * means "handle as usual (capture to Sentry)". Never throws — a resolver that
+ * fails yields null.
+ */
+export function incompleteInstallMessage(err, resolvePackageRoot = safePackageRoot) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    const code = typeof record.code === "string" ? record.code : undefined;
+    if (code !== "MODULE_NOT_FOUND" && code !== "ENOENT")
+        return null;
+    const root = resolveRootSafely(resolvePackageRoot);
+    if (!root)
+        return null;
+    if (code === "MODULE_NOT_FOUND") {
+        // Shape A (CJS, HQ-CLI-1N): a RELATIVE specifier internal to a package under
+        // the running install's node_modules can only be a truncated on-disk copy.
+        const requireStack = record.requireStack;
+        if (!Array.isArray(requireStack) || typeof requireStack[0] !== "string") {
+            return null;
+        }
+        const specifier = parseMissingSpecifier(record.message);
+        if (specifier === null || !RELATIVE_SPECIFIER.test(specifier))
+            return null;
+        return isUnderNodeModules(requireStack[0], root)
+            ? INCOMPLETE_INSTALL_REMEDY
+            : null;
+    }
+    // Shape B (ESM load, HQ-CLI-1M): an ENOENT from the module loader for a file
+    // that was present at resolve and gone at read.
+    if (record.syscall !== "open")
+        return null;
+    if (typeof record.path !== "string")
+        return null;
+    if (!hasEsmLoaderFrame(record.stack))
+        return null;
+    return isUnderNodeModules(record.path, root)
+        ? INCOMPLETE_INSTALL_REMEDY
+        : null;
+}
+/**
+ * When an esm-loader ENOENT reaches the capture path WITHOUT being suppressed —
+ * the exact shape the delivered HQ-CLI-1M payload arrived in, where neither the
+ * exception value nor node_system_error carried a `path` — return a bounded
+ * `contexts.incomplete_install` block so the next occurrence carries the
+ * evidence this one lacked; otherwise return undefined (bare capture). Built
+ * with the byte-capped, scrubber-safe discipline of package-root-diagnostics.ts:
+ * the resolved package root and whether its package.json / node_modules exist,
+ * the loader-frame marker, and the bounded errno code — never a caller argv,
+ * query, or user-minted value. Never throws.
+ *
+ * main.ts attaches this on the generic capture path exactly as
+ * qmdSpawnFailureCaptureContext already does.
+ */
+export function incompleteInstallCaptureContext(err, resolvePackageRoot = safePackageRoot, fileSystem = fs) {
+    if (!isEsmLoaderEnoent(err))
+        return undefined;
+    // Only instrument what we did NOT already confidently suppress: a path under
+    // node_modules is classified and printed above, never captured.
+    if (incompleteInstallMessage(err, resolvePackageRoot) !== null)
+        return undefined;
+    const record = err;
+    const root = resolveRootSafely(resolvePackageRoot);
+    const code = typeof record.code === "string" ? record.code : "";
+    let packageJsonExists = false;
+    let nodeModulesExists = false;
+    if (root) {
+        try {
+            packageJsonExists = fileSystem.existsSync(path.join(root, "package.json"));
+        }
+        catch {
+            packageJsonExists = false;
+        }
+        try {
+            nodeModulesExists = fileSystem.existsSync(path.join(root, "node_modules"));
+        }
+        catch {
+            nodeModulesExists = false;
+        }
+    }
+    return {
+        incomplete_install: {
+            packageRoot: boundedDiagnosticValue(root ?? "<unresolved>", ROOT_DIAGNOSTIC_BYTES),
+            packageJsonExists,
+            nodeModulesExists,
+            esmLoaderFrame: true,
+            code: boundedDiagnosticValue(code, CODE_DIAGNOSTIC_BYTES),
+        },
+    };
+}
+//# sourceMappingURL=incomplete-install-error.js.map

package/package.json

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