@indigoai-us/hq-cli 5.345.6 → 5.345.7

package/CHANGELOG.md

@@ -2,10 +2,20 @@
 
 ## [Unreleased]
 
+## [5.345.7] — 2026-10-05
+- Retry a just-published hq-cli version when npm briefly reports `notarget`.
+- Wait for an active sync pass to finish before restarting sync after a CLI update.
+- Add bounded context to captured missing-module errors targeting hq-cli's own dist output.
+- Recover interrupted agent inbox polls without duplicating mirrored journal entries.
+- Record the actual launch time, trigger, and caller for resumed lane workers even when legacy launch history is missing.
+
 ## [5.345.6] — 2026-10-05
 - `hq mesh context default set <slug> --count-usage` now works for people signed in with a normal HQ account. It previously refused with "the signed-in person could not be determined". An opt-in saved by 5.344.0 is ignored; run the command again to opt in.
 - `hq daemon sync status` now identifies the executing runner and derives its hq-cloud version from the owner status or runner package when needed.
 
+## [5.345.5] — 2026-10-05
+- `hq daemon sync status` now identifies the executing runner and derives its hq-cloud version from the owner status or runner package when needed.
+
 ## [5.345.4] — 2026-10-05
 - Run a pinned or newer managed hq-cloud sync runner ahead of the staged sync bundle, so daemon sync no longer stays on the hq-cloud version bundled with the CLI after an update or pin (hq-cli#1547).
 - Avoid dispatching the global hook when the working directory is inside an HQ root.

package/dist/lib/agent-kit/run/inbox.js

@@ -54,10 +54,34 @@ export function writeSeenIds(paths, seen) {
     const list = [...seen].slice(-MAX_SEEN_IDS);
     writePrivateFile(path.join(paths.inboxDir, SEEN_IDS_NAME), JSON.stringify(list), 0o600);
 }
+function inboxJournalContains(paths, id) {
+    const journal = path.join(paths.inboxDir, INBOX_JSONL_NAME);
+    if (!fs.existsSync(journal))
+        return false;
+    for (const line of fs.readFileSync(journal, "utf8").split("\n")) {
+        if (!line)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            // An interrupted append can leave one malformed final record; it does
+            // not prove that this item made it into the durable journal.
+            continue;
+        }
+        if (entry && typeof entry === "object" && entry.id === id)
+            return true;
+    }
+    return false;
+}
 export function mirrorInboxItem(paths, item) {
     const dest = path.join(paths.inboxDir, `${item.id}.json`);
+    const recoveringInterruptedMirror = fs.existsSync(dest);
     writePrivateFile(dest, `${JSON.stringify(item.raw, null, 2)}\n`, 0o600);
-    fs.appendFileSync(path.join(paths.inboxDir, INBOX_JSONL_NAME), `${JSON.stringify({ id: item.id, mirroredAt: new Date().toISOString(), ...item.raw })}\n`, { mode: 0o600 });
+    if (!recoveringInterruptedMirror || !inboxJournalContains(paths, item.id)) {
+        fs.appendFileSync(path.join(paths.inboxDir, INBOX_JSONL_NAME), `${JSON.stringify({ id: item.id, mirroredAt: new Date().toISOString(), ...item.raw })}\n`, { mode: 0o600 });
+    }
     return dest;
 }
 export const INBOX_ERROR_BODY_MAX = 300;
@@ -148,7 +172,6 @@ export async function pollInboxOnce(deps) {
     const fresh = extractInboxItems(res.body).filter((i) => !seen.has(i.id));
     for (const item of fresh) {
         mirrorInboxItem(deps.paths, item);
-        seen.add(item.id);
         if (deps.ack) {
             try {
                 const status = await ackItem(token, item.id);
@@ -159,9 +182,12 @@ export async function pollInboxOnce(deps) {
                 deps.log("warn", `ack ${item.id} failed: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
+        // Persist each completed item before starting another one. If shutdown
+        // interrupts a later ack or mirror, earlier items will not be replayed.
+        seen.add(item.id);
+        writeSeenIds(deps.paths, seen);
     }
     if (fresh.length > 0) {
-        writeSeenIds(deps.paths, seen);
         deps.log("info", `inbox mirrored ${fresh.length} item(s)`);
         try {
             await warmCache(token, deps.agentUid);

package/dist/lib/daemon/supervisor.d.ts

@@ -27,6 +27,7 @@ import type { ControlRequest } from "./requests.js";
 import { syncPassResult } from "./sync-runner.js";
 export declare const STOP_ESCALATION_MS = 10000;
 export declare const CLI_UPDATE_SYNC_IDLE_MAX_MS: number;
+export declare const CLI_UPDATE_SYNC_IDLE_KILL_GRACE_MS = 60000;
 /** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
 export declare const HANDOFF_STAGGER_MS = 15000;
 /** How long a draining unit may take to finish its work before it gets SIGTERM. */

package/dist/lib/daemon/supervisor.js

@@ -28,6 +28,7 @@ const BACKOFF_MAX_MS = 60_000;
 const HEALTHY_RUN_MS = 60_000;
 export const STOP_ESCALATION_MS = 10_000;
 export const CLI_UPDATE_SYNC_IDLE_MAX_MS = 10 * 60_000;
+export const CLI_UPDATE_SYNC_IDLE_KILL_GRACE_MS = 60_000;
 const MESH_OWNER_RECHECK_MS = 15_000;
 const MESH_OWNER_LOG_INTERVAL_MS = 10 * 60_000;
 /** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
@@ -92,6 +93,7 @@ export function createSupervisor(deps) {
     let deferredCliRestart = false;
     let deferredCliRestartTimer;
     let cliRestartInProgress = false;
+    let pendingSyncCommandRestart;
     const snapshot = () => ({
         version: 1,
         pid: deps.pid,
@@ -125,15 +127,26 @@ export function createSupervisor(deps) {
             clearT(deferredCliRestartTimer);
         deferredCliRestartTimer = undefined;
     };
-    const runDeferredCliRestart = () => {
+    const clearPendingSyncCommandRestart = (slot) => {
+        if (!pendingSyncCommandRestart || (slot && pendingSyncCommandRestart.slot !== slot))
+            return;
+        if (pendingSyncCommandRestart.timer !== undefined)
+            clearT(pendingSyncCommandRestart.timer);
+        pendingSyncCommandRestart = undefined;
+    };
+    const runDeferredCliRestart = (idleTimeout = false) => {
         if (!deferredCliRestart)
             return;
+        clearPendingSyncCommandRestart();
         clearDeferredCliRestart();
         cliRestartInProgress = true;
         const sync = [...slots.values()].find((slot) => slot.plan.service === "sync" && slot.child);
-        if (sync)
-            terminate(sync);
-        deps.log("info", "sync runner is between passes; restarting daemon onto the updated CLI");
+        if (sync) {
+            terminate(sync, undefined, false, idleTimeout ? CLI_UPDATE_SYNC_IDLE_KILL_GRACE_MS : STOP_ESCALATION_MS);
+        }
+        deps.log(idleTimeout ? "warn" : "info", idleTimeout
+            ? "sync pass remained active for 10 minutes; restarting daemon onto the updated CLI"
+            : "sync runner is between passes; restarting daemon onto the updated CLI");
         const releaseHold = () => {
             cliRestartInProgress = false;
             const currentSync = [...slots.values()].find((slot) => slot.plan.service === "sync");
@@ -163,6 +176,17 @@ export function createSupervisor(deps) {
             releaseHold();
         }
     };
+    const finishPendingSyncCommandRestart = (idleTimeout = false) => {
+        const pending = pendingSyncCommandRestart;
+        if (!pending)
+            return;
+        clearPendingSyncCommandRestart(pending.slot);
+        if (deferredCliRestart) {
+            runDeferredCliRestart(idleTimeout);
+            return;
+        }
+        pending.onFinish(idleTimeout);
+    };
     const requestCliUpdateRestart = () => {
         if (!deps.restartDaemon)
             return;
@@ -173,7 +197,10 @@ export function createSupervisor(deps) {
         }
         if (sync.syncPassActive === false) {
             deferredCliRestart = true;
-            runDeferredCliRestart();
+            if (pendingSyncCommandRestart?.slot === sync)
+                finishPendingSyncCommandRestart();
+            else
+                runDeferredCliRestart();
             return;
         }
         if (deferredCliRestart) {
@@ -182,7 +209,25 @@ export function createSupervisor(deps) {
         }
         deferredCliRestart = true;
         deps.log("info", "deferring CLI-update restart until sync is idle (maximum 10 minutes)");
-        deferredCliRestartTimer = setT(runDeferredCliRestart, CLI_UPDATE_SYNC_IDLE_MAX_MS);
+        if (pendingSyncCommandRestart?.slot === sync)
+            return;
+        deferredCliRestartTimer = setT(() => runDeferredCliRestart(true), CLI_UPDATE_SYNC_IDLE_MAX_MS);
+    };
+    const deferSyncCommandRestart = (slot, onFinish) => {
+        if (slot.syncPassActive === false) {
+            onFinish(false);
+            return;
+        }
+        if (pendingSyncCommandRestart?.slot === slot)
+            return;
+        clearPendingSyncCommandRestart();
+        const pending = { slot, onFinish };
+        pendingSyncCommandRestart = pending;
+        deps.log("info", `deferring restart of ${slot.plan.id} until its sync pass is idle (maximum 10 minutes)`);
+        // A pending CLI restart already owns the same 10-minute idle window.
+        if (!deferredCliRestart) {
+            pending.timer = setT(() => finishPendingSyncCommandRestart(true), CLI_UPDATE_SYNC_IDLE_MAX_MS);
+        }
     };
     const setBlocked = (slot) => {
         const block = slot.plan.blocked;
@@ -204,7 +249,8 @@ export function createSupervisor(deps) {
      * `drain`, a unit that has a drain signal gets it first and SIGTERM only
      * after HANDOFF_DRAIN_MAX_MS; SIGKILL follows SIGTERM after STOP_ESCALATION_MS.
      */
-    const terminate = (slot, then, drain = false) => {
+    const terminate = (slot, then, drain = false, killGraceMs = STOP_ESCALATION_MS) => {
+        clearPendingSyncCommandRestart(slot);
         clearTimer(slot);
         clearHeartbeatTimer(slot);
         const child = slot.child;
@@ -227,9 +273,9 @@ export function createSupervisor(deps) {
                 slot.killTimer = undefined;
                 if (slot.child !== child)
                     return;
-                deps.log("warn", `${slot.plan.id} did not exit within ${STOP_ESCALATION_MS / 1_000} s of SIGTERM; sending SIGKILL${lastProtocolHint(slot)}`);
+                deps.log("warn", `${slot.plan.id} did not exit within ${killGraceMs / 1_000} s of SIGTERM; sending SIGKILL${lastProtocolHint(slot)}`);
                 signalChild(slot, child, "SIGKILL");
-            }, STOP_ESCALATION_MS);
+            }, killGraceMs);
         };
         const drainSignal = drain ? slot.plan.drainSignal : undefined;
         if (drainSignal) {
@@ -309,8 +355,12 @@ export function createSupervisor(deps) {
                         slot.syncPassActive = true;
                     }
                 }
-                if (deferredCliRestart && slot.syncPassActive === false)
-                    runDeferredCliRestart();
+                if (slot.syncPassActive === false) {
+                    if (pendingSyncCommandRestart?.slot === slot)
+                        finishPendingSyncCommandRestart();
+                    else if (deferredCliRestart)
+                        runDeferredCliRestart();
+                }
             }
             const at = now();
             slot.state.lastHeartbeatAt = new Date(at).toISOString();
@@ -357,6 +407,11 @@ export function createSupervisor(deps) {
             if (slot.child !== child)
                 return;
             slot.child = undefined;
+            if (pendingSyncCommandRestart?.slot === slot) {
+                clearPendingSyncCommandRestart(slot);
+                if (deferredCliRestart)
+                    runDeferredCliRestart();
+            }
             clearHeartbeatTimer(slot);
             if (slot.killTimer !== undefined) {
                 clearT(slot.killTimer);
@@ -652,6 +707,34 @@ export function createSupervisor(deps) {
                 else
                     activate(existing);
             }
+            else if (changed && cliRestartInProgress && plan.service === "sync" && existing.child) {
+                // The deferred CLI restart owns this stop; do not queue a second
+                // replacement through the adopted-unit handoff path.
+                terminate(existing);
+            }
+            else if (changed && plan.service === "sync" && existing.child) {
+                existing.attempts = 0;
+                existing.state.restarts = 0;
+                const replaceWhenIdle = () => {
+                    if (adopted) {
+                        deps.log("info", `will replace ${plan.id}: it runs an older CLI or command`);
+                        handoffQueue.push(existing);
+                        pumpHandoff();
+                    }
+                    else {
+                        deps.log("info", `restarting ${plan.id}: its command changed`);
+                        terminate(existing, () => activate(existing));
+                    }
+                };
+                deferSyncCommandRestart(existing, (idleTimeout) => {
+                    if (!idleTimeout) {
+                        replaceWhenIdle();
+                        return;
+                    }
+                    deps.log("warn", `${plan.id} sync pass did not become idle within 10 minutes; stopping it to apply the changed command`);
+                    terminate(existing, () => activate(existing), false, CLI_UPDATE_SYNC_IDLE_KILL_GRACE_MS);
+                });
+            }
             else if (changed && adopted && existing.child) {
                 deps.log("info", `will replace ${plan.id}: it runs an older CLI or command`);
                 handoffQueue.push(existing);
@@ -878,6 +961,7 @@ export function createSupervisor(deps) {
             if (handoffTimer !== undefined)
                 clearT(handoffTimer);
             clearDeferredCliRestart();
+            clearPendingSyncCommandRestart();
             const childOwners = new Map();
             for (const slot of slots.values()) {
                 if (slot.child)

package/dist/lib/lanes/spawn.js

@@ -2421,6 +2421,8 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 ...(resumeHistoryCaller ? { caller: resumeHistoryCaller } : {}),
             }),
         }));
+    }
+    if (priorStartRecorded || resume !== undefined) {
         appendLaneWorkerResumeEvent({
             hqRoot,
             laneId: lane.lane_id,

package/dist/lib/local-tree-diff.d.ts

@@ -24,8 +24,8 @@
  * for the destructive side effects (delete, tombstone, PUT sync-config).
  */
 import { type SyncJournal } from "@indigoai-us/hq-cloud";
-export type DirtyReason = "modified-after-sync" | "hash-mismatch" | "not-in-journal" | "stat-error";
-export interface NarrowFile {
+type DirtyReason = "modified-after-sync" | "hash-mismatch" | "not-in-journal" | "stat-error";
+interface NarrowFile {
     /**
      * COMPANY-RELATIVE path (e.g. `meetings/a.md`) — the canonical namespace
      * shared by the per-company journal keys, the vault S3 keys, and the
@@ -117,4 +117,5 @@ export declare function toPosixKey(p: string): string;
 export declare function formatNarrowPlanSummary(plan: NarrowPlan): string;
 /** Human-readable byte counts with a fixed unit ladder. */
 export declare function formatBytes(n: number): string;
+export {};
 //# sourceMappingURL=local-tree-diff.d.ts.map

package/dist/lib/search-index/background.d.ts

@@ -93,8 +93,6 @@ export declare function defaultSpawnWorker({ logPath, fallbackLogPath }: {
 }, io?: SpawnWorkerIo): number;
 /** Defaults used by the CLI; tests supply every nondeterministic dependency. */
 export declare function defaultBackgroundDependencies(hqRoot: string): BackgroundDependencies;
-/** Match the shell forwarder's hosted-agent markers before looking up qmd. */
-export declare function isHostedAgent(env?: NodeJS.ProcessEnv): boolean;
 export declare function installWorkerCleanup(cleanup: () => void, processEvents?: Pick<NodeJS.Process, 'once'>, exit?: (code: number) => void): void;
 /** Start a detached worker; this public entry never owns the qmd pipeline. */
 export declare function runBackgroundLauncher(dependencies: BackgroundDependencies): BackgroundResult;

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

@@ -129,7 +129,7 @@ export function defaultBackgroundDependencies(hqRoot) {
     };
 }
 /** Match the shell forwarder's hosted-agent markers before looking up qmd. */
-export function isHostedAgent(env = process.env) {
+function isHostedAgent(env = process.env) {
     if (env.HQ_QMD_REINDEX_MODE === 'skip-agent' || env.HQ_QMD_REINDEX_MODE === 'skip')
         return true;
     if (env.HQ_AGENT_BOX && env.HQ_AGENT_BOX !== '0')

package/dist/lib/search-index/index.d.ts

@@ -327,19 +327,6 @@ export type ResolveQmdBinOptions = {
  * independent of the dependency's own exports map.
  */
 export declare function packageLocalBin(): string | undefined;
-/**
- * Locate the bundled qmd's Node LAUNCHER — `@tobilu/qmd`'s `bin.qmd` entry
- * (`bin/qmd`, a `#!/usr/bin/env node` script) — by the same upward walk
- * {@link resolveQmdVersion} uses to find the package. Returns the absolute
- * launcher path only when both the manifest and the launcher file exist.
- *
- * This is the shell-free preferred resolution: invoking `node <launcher>`
- * bypasses the npm-generated `.cmd` shim entirely, so the Windows CVE-2024-27980
- * EINVAL never arises and no user-supplied search text reaches cmd.exe. A
- * missing/partial layout returns undefined so the caller falls back to the
- * `.bin` shim (which the shared spawn plan now makes spawnable on Windows too).
- */
-export declare function packageLocalNodeEntry(): string | undefined;
 /**
  * Return the pinned package version when qmd is supplied by this CLI.
  *
@@ -412,12 +399,6 @@ export type EnsureQmdStoreDirOptions = {
 export declare function ensureQmdStoreDir(env?: NodeJS.ProcessEnv, options?: EnsureQmdStoreDirOptions): void;
 /** Reset per-process probe/repair memoisation. Test-only. */
 export declare function __resetQmdProbeStateForTests(): void;
-/** Probe a resolved invocation, memoised per invocation; records the failure
- * detail under the qmd bin identity so repair can read it. */
-export declare function isUsableInvocation(invocation: QmdInvocation, options?: {
-    platform?: NodeJS.Platform;
-    spawn?: QmdSpawn;
-}): boolean;
 /** Backwards-compatible string form: probe a bare bin path shell-free (or via
  * the shell plan when it is a Windows `.cmd`/`.bat`). */
 export declare function isUsableQmd(bin: string): boolean;

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

@@ -332,7 +332,7 @@ export function packageLocalBin() {
  * missing/partial layout returns undefined so the caller falls back to the
  * `.bin` shim (which the shared spawn plan now makes spawnable on Windows too).
  */
-export function packageLocalNodeEntry() {
+function packageLocalNodeEntry() {
     let directory = path.dirname(fileURLToPath(import.meta.url));
     for (let depth = 0; depth < 10; depth++) {
         const manifest = path.join(directory, 'node_modules', '@tobilu', 'qmd', 'package.json');
@@ -644,7 +644,7 @@ function probeQmd(invocation, options = {}) {
 }
 /** Probe a resolved invocation, memoised per invocation; records the failure
  * detail under the qmd bin identity so repair can read it. */
-export function isUsableInvocation(invocation, options = {}) {
+function isUsableInvocation(invocation, options = {}) {
     const key = invocationKey(invocation);
     const cached = usableQmdCache.get(key);
     if (cached !== undefined)

package/dist/main.d.ts

@@ -44,6 +44,9 @@ export type TopLevelErrorDependencies = {
     openUrl?: (url: string) => Promise<void>;
     upgradeToTeam?: typeof upgradeToTeam;
 };
+export declare const MAX_OWN_DIST_RELATIVE_PATH_BYTES = 256;
+/** Return a bounded path only when targetPath is beneath packageRoot/dist. */
+export declare function relativeOwnDistModulePath(packageRootPath: string, targetPath: string): string | undefined;
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export declare function handleTopLevelError(err: unknown, deps?: TopLevelErrorDependencies): Promise<void>;
 //# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -6,6 +6,7 @@
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
 import "./node-network-compat.js";
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
@@ -52,10 +53,11 @@ import { settleWithin } from "./utils/settle-with-timeout.js";
 import { isVersionRequest } from "./version-request.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
 import { kickFlagRegistryReadiness, waitForFlagRegistryRefresh, } from "./lib/flag-registry.js";
-import { isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
+import { boundedDiagnosticValue, isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
 import { registerCommandsWithRecovery } from "./startup-registration.js";
 import { releasePackageUseLeaseAfterCommandLoad } from "./utils/package-use-lease.js";
-import { installTreeTornCaptureContext, installTreeTornStderrLine, isInstallTreeTornError, } from "./utils/install-tree-torn.js";
+import { packageRoot } from "./utils/hq-roots.js";
+import { classifyModuleNotFound, installTreeTornCaptureContext, installTreeTornStderrLine, isInstallTreeTornError, } from "./utils/install-tree-torn.js";
 import { isVaultAccessDeniedError, vaultAccessDeniedMessage, } from "./utils/vault-access-denied-error.js";
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
 import { runGlobalNetworkLifecycle } from "./utils/cli-network-lifecycle.js";
@@ -410,6 +412,110 @@ function integrationsGatewayCaptureContext(err) {
         },
     };
 }
+export const MAX_OWN_DIST_RELATIVE_PATH_BYTES = 256;
+function resolveThroughExistingAncestors(pathApi, inputPath) {
+    let cursor = pathApi.resolve(inputPath);
+    const missingSegments = [];
+    while (true) {
+        try {
+            const realPath = fs.realpathSync.native(cursor);
+            if (missingSegments.length > 0 && !fs.statSync(realPath).isDirectory()) {
+                return undefined;
+            }
+            return pathApi.join(realPath, ...missingSegments);
+        }
+        catch (error) {
+            const code = error !== null && typeof error === "object" && "code" in error
+                ? error.code
+                : undefined;
+            // A missing final module is expected here. Walk to its nearest existing
+            // parent so symlinked package roots and junctions still compare by their
+            // actual location. Other filesystem errors leave enrichment unavailable;
+            // the original error remains on the generic capture path.
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                return undefined;
+            const parent = pathApi.dirname(cursor);
+            if (parent === cursor)
+                return undefined;
+            missingSegments.unshift(pathApi.basename(cursor));
+            cursor = parent;
+        }
+    }
+}
+/** Return a bounded path only when targetPath is beneath packageRoot/dist. */
+export function relativeOwnDistModulePath(packageRootPath, targetPath) {
+    const hasWindowsAbsolutePath = (value) => /^[A-Za-z]:[\\/]/.test(value) || /^\\\\/.test(value);
+    const pathApi = hasWindowsAbsolutePath(packageRootPath) || hasWindowsAbsolutePath(targetPath)
+        ? path.win32
+        : path;
+    let resolvedRoot;
+    let resolvedTarget;
+    if (pathApi === path.win32) {
+        // Use Windows lexical semantics for drive paths and UNC paths even when
+        // this helper is exercised on a non-Windows host.
+        resolvedRoot = pathApi.resolve(packageRootPath);
+        resolvedTarget = pathApi.resolve(targetPath);
+    }
+    else {
+        const canonicalRoot = resolveThroughExistingAncestors(pathApi, packageRootPath);
+        const canonicalTarget = resolveThroughExistingAncestors(pathApi, targetPath);
+        if (canonicalRoot === undefined || canonicalTarget === undefined)
+            return undefined;
+        resolvedRoot = canonicalRoot;
+        resolvedTarget = canonicalTarget;
+    }
+    const distRoot = pathApi.resolve(resolvedRoot, "dist");
+    const relativePath = pathApi.relative(distRoot, resolvedTarget);
+    if (relativePath.length === 0 ||
+        relativePath === ".." ||
+        relativePath.startsWith(`..${pathApi.sep}`) ||
+        pathApi.isAbsolute(relativePath)) {
+        return undefined;
+    }
+    return boundedDiagnosticValue(relativePath, MAX_OWN_DIST_RELATIVE_PATH_BYTES);
+}
+/**
+ * Add bounded evidence when an ESM resolver failure names a file in hq-cli's
+ * own dist tree. This only enriches an event that is already captured; it does
+ * not infer that the package tree was torn or change the recovery path.
+ */
+function ownDistModuleMissingCaptureContext(err) {
+    if (err === null || typeof err !== "object")
+        return undefined;
+    const record = err;
+    if (record.code !== "ERR_MODULE_NOT_FOUND")
+        return undefined;
+    const classified = classifyModuleNotFound(err);
+    if (!classified ||
+        classified.code !== "ERR_MODULE_NOT_FOUND" ||
+        classified.dialect !== "esm-path" ||
+        classified.target.kind !== "path") {
+        return undefined;
+    }
+    let root;
+    try {
+        root = packageRoot();
+    }
+    catch {
+        // Enrichment is optional. If root discovery itself is unavailable, retain
+        // the original generic capture without changing its recovery or output.
+        return undefined;
+    }
+    const relativePath = relativeOwnDistModulePath(root, classified.target.path);
+    if (relativePath === undefined)
+        return undefined;
+    return {
+        tags: {
+            module_missing_scope: "own_dist",
+            cli_version: CLI_VERSION,
+        },
+        contexts: {
+            module_missing_target: {
+                relative_path: relativePath,
+            },
+        },
+    };
+}
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export async function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies) {
     // A typed plan gate, or an hq-cloud vault error carrying a plan-limit
@@ -920,22 +1026,30 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else {
             // 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 a loader/resolver ENOENT whose path
-            // did not survive delivery (HQ-CLI-1M esm-load, HQ-CLI-1S resolve-time,
-            // HQ-CLI-20 CJS load-time — the unattributable incomplete-install shape).
+            // carries evidence otherwise missing: qmd spawn failures (HQ-CLI-1A),
+            // loader/resolver ENOENTs with no usable path (HQ-CLI-1M/1S/20), and an
+            // ESM module miss under hq-cli's own dist tree. The latter remains a
+            // captured fault without guessing whether the artifact or install tore.
             // Every other error captures bare, exactly as before.
             const spawnContext = qmdSpawnFailureCaptureContext(err);
             const installContext = incompleteInstallCaptureContext(err);
             const qmdContext = qmdExitCaptureContext(err);
             const gatewayContext = integrationsGatewayCaptureContext(err);
-            if (spawnContext || installContext || qmdContext || gatewayContext) {
+            const moduleContext = ownDistModuleMissingCaptureContext(err);
+            const tags = {
+                ...qmdContext?.tags,
+                ...gatewayContext?.tags,
+                ...moduleContext?.tags,
+            };
+            const contexts = {
+                ...spawnContext?.contexts,
+                ...installContext,
+                ...moduleContext?.contexts,
+            };
+            if (Object.keys(tags).length > 0 || Object.keys(contexts).length > 0) {
                 deps.sentry.captureException(err, {
-                    ...qmdContext,
-                    ...(gatewayContext ? { tags: gatewayContext.tags } : {}),
-                    ...((spawnContext || installContext)
-                        ? { contexts: { ...spawnContext?.contexts, ...installContext } }
-                        : {}),
+                    ...(Object.keys(tags).length > 0 ? { tags } : {}),
+                    ...(Object.keys(contexts).length > 0 ? { contexts } : {}),
                 });
             }
             else {

package/dist/types.d.ts

@@ -9,9 +9,8 @@
  */
 import type { ContributionKey } from './utils/contribution-table.js';
 export type LegacyStrategy = 'link' | 'merge' | 'copy';
-export type SyncStrategy = LegacyStrategy | 'package';
 export type AccessLevel = 'public' | 'team' | `role:${string}`;
-export interface PathMapping {
+interface PathMapping {
     src: string;
     dest: string;
 }
@@ -83,7 +82,7 @@ export interface PackAuthor {
  * tracks installed packs by FILESYSTEM PRESENCE — not `modules.yaml`). `version`
  * is an optional semver RANGE the installed dependency must satisfy.
  */
-export interface PackDependency {
+interface PackDependency {
     name: string;
     version?: string;
 }
@@ -129,4 +128,5 @@ export interface PackManifest {
         prompt?: string;
     };
 }
+export {};
 //# sourceMappingURL=types.d.ts.map

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

@@ -32,19 +32,19 @@
  *     ({@link shouldApplyHeartbeat}).
  */
 export declare const CLIENT_HEALTH_CONTRACT_VERSION = 1;
-export declare const CLIENT_HEALTH_PLATFORMS: readonly ["macos", "windows", "linux"];
+declare const CLIENT_HEALTH_PLATFORMS: readonly ["macos", "windows", "linux"];
 export type ClientHealthPlatform = (typeof CLIENT_HEALTH_PLATFORMS)[number];
-export declare const CLIENT_HEALTH_ARCHS: readonly ["x64", "arm64"];
+declare const CLIENT_HEALTH_ARCHS: readonly ["x64", "arm64"];
 export type ClientHealthArch = (typeof CLIENT_HEALTH_ARCHS)[number];
 /** Which client produced the heartbeat. Desktop is always-on; CLI contributes per invocation. */
-export declare const CLIENT_HEALTH_SOURCES: readonly ["desktop", "cli"];
-export type ClientHealthSource = (typeof CLIENT_HEALTH_SOURCES)[number];
+declare const CLIENT_HEALTH_SOURCES: readonly ["desktop", "cli"];
+type ClientHealthSource = (typeof CLIENT_HEALTH_SOURCES)[number];
 /**
  * Current sync state of the installation. `paused` and `conflict_blocked` are
  * first-class states (not failures folded into `error`) because support treats
  * them differently: pause may be intentional and conflicts are user-owned.
  */
-export declare const CLIENT_HEALTH_SYNC_STATES: readonly ["idle", "syncing", "paused", "conflict_blocked", "error", "never_synced"];
+declare const CLIENT_HEALTH_SYNC_STATES: readonly ["idle", "syncing", "paused", "conflict_blocked", "error", "never_synced"];
 export type ClientHealthSyncState = (typeof CLIENT_HEALTH_SYNC_STATES)[number];
 /**
  * Updater state. ABSENCE of the field means the client is too old to report
@@ -62,19 +62,15 @@ export type ClientHealthFailureReason = (typeof CLIENT_HEALTH_FAILURE_REASONS)[n
  * fails closed.
  */
 export declare const CLIENT_HEALTH_REPAIR_KINDS: readonly ["CHECK_NOW", "RETRY_SYNC", "RESUME_SYNC", "REPAIR_CLI", "UPDATE_CORE", "APPLY_DESKTOP_UPDATE", "RESTART_APP"];
-export type ClientHealthRepairKind = (typeof CLIENT_HEALTH_REPAIR_KINDS)[number];
+type ClientHealthRepairKind = (typeof CLIENT_HEALTH_REPAIR_KINDS)[number];
 /** Command/receipt lifecycle states (queued → acknowledged → running → terminal). */
-export declare const CLIENT_HEALTH_COMMAND_STATES: readonly ["queued", "acknowledged", "running", "succeeded", "failed", "expired"];
-export type ClientHealthCommandState = (typeof CLIENT_HEALTH_COMMAND_STATES)[number];
+declare const CLIENT_HEALTH_COMMAND_STATES: readonly ["queued", "acknowledged", "running", "succeeded", "failed", "expired"];
+type ClientHealthCommandState = (typeof CLIENT_HEALTH_COMMAND_STATES)[number];
 /** Closed diagnostic probe identifiers (US-007). */
-export declare const CLIENT_HEALTH_DIAGNOSTIC_CHECKS: readonly ["auth", "runner", "cli", "core", "updater", "sync", "conflicts", "storage", "permissions"];
-export type ClientHealthDiagnosticCheck = (typeof CLIENT_HEALTH_DIAGNOSTIC_CHECKS)[number];
-export declare const CLIENT_HEALTH_CHECK_STATUSES: readonly ["pass", "fail", "skip"];
-export type ClientHealthCheckStatus = (typeof CLIENT_HEALTH_CHECK_STATUSES)[number];
-export declare const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
-export declare const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100000;
-export declare const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100000;
-export declare const CLIENT_HEALTH_MAX_CHECKS = 16;
+declare const CLIENT_HEALTH_DIAGNOSTIC_CHECKS: readonly ["auth", "runner", "cli", "core", "updater", "sync", "conflicts", "storage", "permissions"];
+type ClientHealthDiagnosticCheck = (typeof CLIENT_HEALTH_DIAGNOSTIC_CHECKS)[number];
+declare const CLIENT_HEALTH_CHECK_STATUSES: readonly ["pass", "fail", "skip"];
+type ClientHealthCheckStatus = (typeof CLIENT_HEALTH_CHECK_STATUSES)[number];
 /**
  * Local-files-overview bounds (client-sync-health-control-plane hq-cli
  * addition, US-016). These cap the closed set of bounded facts support sees
@@ -146,7 +142,7 @@ export interface ClientHealthHeartbeat {
     /** Absent on older clients / non-sync-outcome events. See {@link ClientHealthLocalFilesOverview}. */
     localFilesOverview?: ClientHealthLocalFilesOverview;
 }
-export interface ClientHealthCheckResult {
+interface ClientHealthCheckResult {
     check: ClientHealthDiagnosticCheck;
     status: ClientHealthCheckStatus;
     /** Present only on `fail` — a closed reason code, never prose. */
@@ -187,4 +183,5 @@ export declare function parseClientHealthCommandReceipt(input: unknown): ClientH
  * answers idempotently and the current snapshot remains unchanged).
  */
 export declare function shouldApplyHeartbeat(storedSequence: number | undefined, incomingSequence: number): boolean;
+export {};
 //# sourceMappingURL=client-health-contract.d.ts.map

package/dist/utils/client-health-contract.js

@@ -34,16 +34,16 @@
 // ─── Contract version ────────────────────────────────────────────────────────
 export const CLIENT_HEALTH_CONTRACT_VERSION = 1;
 // ─── Closed enums ────────────────────────────────────────────────────────────
-export const CLIENT_HEALTH_PLATFORMS = ["macos", "windows", "linux"];
-export const CLIENT_HEALTH_ARCHS = ["x64", "arm64"];
+const CLIENT_HEALTH_PLATFORMS = ["macos", "windows", "linux"];
+const CLIENT_HEALTH_ARCHS = ["x64", "arm64"];
 /** Which client produced the heartbeat. Desktop is always-on; CLI contributes per invocation. */
-export const CLIENT_HEALTH_SOURCES = ["desktop", "cli"];
+const CLIENT_HEALTH_SOURCES = ["desktop", "cli"];
 /**
  * Current sync state of the installation. `paused` and `conflict_blocked` are
  * first-class states (not failures folded into `error`) because support treats
  * them differently: pause may be intentional and conflicts are user-owned.
  */
-export const CLIENT_HEALTH_SYNC_STATES = [
+const CLIENT_HEALTH_SYNC_STATES = [
     "idle",
     "syncing",
     "paused",
@@ -94,7 +94,7 @@ export const CLIENT_HEALTH_REPAIR_KINDS = [
     "RESTART_APP",
 ];
 /** Command/receipt lifecycle states (queued → acknowledged → running → terminal). */
-export const CLIENT_HEALTH_COMMAND_STATES = [
+const CLIENT_HEALTH_COMMAND_STATES = [
     "queued",
     "acknowledged",
     "running",
@@ -103,7 +103,7 @@ export const CLIENT_HEALTH_COMMAND_STATES = [
     "expired",
 ];
 /** Closed diagnostic probe identifiers (US-007). */
-export const CLIENT_HEALTH_DIAGNOSTIC_CHECKS = [
+const CLIENT_HEALTH_DIAGNOSTIC_CHECKS = [
     "auth",
     "runner",
     "cli",
@@ -114,12 +114,12 @@ export const CLIENT_HEALTH_DIAGNOSTIC_CHECKS = [
     "storage",
     "permissions",
 ];
-export const CLIENT_HEALTH_CHECK_STATUSES = ["pass", "fail", "skip"];
+const CLIENT_HEALTH_CHECK_STATUSES = ["pass", "fail", "skip"];
 // ─── Bounds ──────────────────────────────────────────────────────────────────
-export const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
-export const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100_000;
-export const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100_000;
-export const CLIENT_HEALTH_MAX_CHECKS = 16;
+const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
+const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100_000;
+const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100_000;
+const CLIENT_HEALTH_MAX_CHECKS = 16;
 /**
  * Local-files-overview bounds (client-sync-health-control-plane hq-cli
  * addition, US-016). These cap the closed set of bounded facts support sees

package/dist/utils/self-update.d.ts

@@ -145,6 +145,8 @@ export interface SelfUpdateDeps {
     /** Same-filesystem install rename, injectable for rollback tests. */
     renamePath?: typeof fs.renameSync;
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
+    /** Delay between bounded npm retries when the just-published target is not visible yet. */
+    sleep?: (ms: number) => Promise<void>;
     reexec?: (argv: string[], env: NodeJS.ProcessEnv) => number | null;
     /** Async process-spawn seam for lease handoff tests. */
     spawnReexec?: typeof spawn;

package/dist/utils/self-update.js

@@ -693,6 +693,18 @@ function reexecErrorClass(error) {
     }
     return "unknown";
 }
+const NPM_NOTARGET_RETRY_DELAYS_MS = [30_000, 60_000, 90_000];
+const NPM_NOTARGET_MAX_ATTEMPTS = NPM_NOTARGET_RETRY_DELAYS_MS.length + 1;
+function isNpmNotargetFailure(result) {
+    const code = (result.diagnosticCode ?? result.code)?.toUpperCase();
+    if (code === "ETARGET" || code === "NOTARGET")
+        return true;
+    return result.failureKind === "package_manager_exit" &&
+        /\bETARGET\b|\bnpm\s+(?:ERR!|error)\s+notarget\b/i.test(result.detail ?? "");
+}
+function sleepForRetry(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function updateAndReexec(argv, flavor, known, deps) {
     const env = deps.env ?? process.env;
     if (env[REEXEC_GUARD_ENV] === "1" || env.HQ_NO_UPDATE_CHECK === "1") {
@@ -795,14 +807,32 @@ async function updateAndReexec(argv, flavor, known, deps) {
         // Forward env only when PNPM_HOME had to be injected, so the common path
         // spawns with the inherited environment and keeps the two-argument runner
         // call it has always made.
-        if (staged) {
-            result = stagedNpmInstall(install, latestValid, { run: runner, env, rename: renamePath });
-        }
-        else if (updateEnv === undefined) {
-            result = runner(plan.cmd, plan.args);
+        const runInstall = () => {
+            if (staged) {
+                return stagedNpmInstall(install, latestValid, { run: runner, env, rename: renamePath });
+            }
+            return updateEnv === undefined
+                ? runner(plan.cmd, plan.args)
+                : runner(plan.cmd, plan.args, updateEnv);
+        };
+        let attempt = 1;
+        result = runInstall();
+        while (install.manager === "npm" &&
+            !result.ok &&
+            isNpmNotargetFailure(result) &&
+            attempt < NPM_NOTARGET_MAX_ATTEMPTS) {
+            const delay = NPM_NOTARGET_RETRY_DELAYS_MS[attempt - 1];
+            const nextAttempt = attempt + 1;
+            console.error(chalk.dim(`  npm has not published hq-cli ${latestValid} yet; retrying install (attempt ${nextAttempt}/${NPM_NOTARGET_MAX_ATTEMPTS}) after ${delay} ms.`));
+            await (deps.sleep ?? sleepForRetry)(delay);
+            attempt = nextAttempt;
+            result = runInstall();
         }
-        else {
-            result = runner(plan.cmd, plan.args, updateEnv);
+        if (!result.ok && attempt > 1) {
+            result = {
+                ...result,
+                detail: `${result.detail ?? "npm install failed"} (attempts: ${attempt})`,
+            };
         }
         if (result.ok && !staged && install.manager === "npm" && install.prefix && install.packageRoot) {
             const bins = verifyOrRepairNpmBins(install.prefix, install.packageRoot);

package/package.json

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