@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/utils/feedback-logs.js

@@ -13,8 +13,9 @@
  *     (`hq-sync.log.1`, `.2`, `.3`) are eligible too — just after a rotation
  *     the active file is nearly empty and the history lives in `.1`.
  *     `logs/mcp-registry.log` is the CLI's own append-only MCP audit trail.
- *     Any future `*.log`/`*.jsonl` dropped into `~/.hq/logs/` is picked up
- *     automatically.
+ *     The daemon runner's `daemon/logs/sync.log` and its three rotations are
+ *     eligible too. When both sync families exist, only the newer family is
+ *     attached.
  *
  *   - STATE SNAPSHOTS (`state`) — small JSON files that describe where sync
  *     and client health currently stand: the in-flight sync phase and conflict
@@ -36,8 +37,9 @@
  *
  *   1. ALLOWLIST, NOT A SCAN. `~/.hq` also holds `cognito-tokens.json`,
  *      `deploy-passwords.json`, and `secrets-cache/`. Only `*.log` files
- *      directly inside `~/.hq/logs/` plus the two known root-level boot logs
- *      are ever eligible. A recursive walk over `~/.hq` is a credential leak
+ *      directly inside `~/.hq/logs/`, the exact daemon sync-log generations
+ *      under the configured daemon root, and the two known root-level boot
+ *      logs are eligible. A recursive walk over `~/.hq` is a credential leak
  *      and must never be introduced here.
  *
  *   2. NO SYMLINKS. Eligibility is decided with `lstat`, and a candidate must
@@ -58,6 +60,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { currentSyncLogFamily, SYNC_LOG_RELATIVE_PATHS, SYNC_LOG_GENERATIONS, syncLogBasePaths, syncLogFamilyForRelativePath, syncLogGenerationPath, } from "./sync-log-sources.js";
 /**
  * Ceiling on the total redacted log text attached to one submission.
  *
@@ -86,12 +89,12 @@ export const FEEDBACK_LOGS_MIN_USEFUL_BYTES = 1024;
  */
 export const FEEDBACK_MAX_SKIPPED_ENTRIES = 25;
 /** Subdirectory of `~/.hq` whose log files are eligible. Not recursive. */
-export const FEEDBACK_LOGS_DIRNAME = "logs";
+const FEEDBACK_LOGS_DIRNAME = "logs";
 /**
  * Eligible extensions inside `~/.hq/logs/`. `.jsonl` is included because the
  * CLI's MCP registry audit trail is JSON-lines, not plain text.
  */
-export const FEEDBACK_LOG_EXTENSIONS = [".log", ".jsonl"];
+const FEEDBACK_LOG_EXTENSIONS = [".log", ".jsonl"];
 /**
  * True for a log filename, including a ROTATED generation.
  *
@@ -117,7 +120,7 @@ export const FEEDBACK_STATE_MAX_FILE_BYTES = 4 * 1024;
  * Ceiling on all state snapshots combined. Deliberately a small slice of the
  * overall budget: state is dense but finite, and the rest belongs to logs.
  */
-export const FEEDBACK_STATE_MAX_TOTAL_BYTES = 12 * 1024;
+const FEEDBACK_STATE_MAX_TOTAL_BYTES = 12 * 1024;
 /**
  * State files at the `~/.hq` ROOT that are eligible, by EXACT name.
  *
@@ -125,7 +128,7 @@ export const FEEDBACK_STATE_MAX_TOTAL_BYTES = 12 * 1024;
  * `secrets-cache/` live, so it is never globbed. Adding a name here is a
  * deliberate act: confirm the file carries no credential before listing it.
  */
-export const FEEDBACK_STATE_FILENAMES = [
+const FEEDBACK_STATE_FILENAMES = [
     // In-flight sync: phase, file counts, conflict count, current file.
     "sync-progress.json",
     // Sync contract version the installation last wrote.
@@ -147,7 +150,7 @@ export const FEEDBACK_STATE_FILENAMES = [
  * excludes the multi-hundred-megabyte `…json.last-good` snapshots sitting
  * beside them. No credential file at the root carries this prefix.
  */
-export const FEEDBACK_STATE_JOURNAL_PREFIX = "sync-journal.";
+const FEEDBACK_STATE_JOURNAL_PREFIX = "sync-journal.";
 /**
  * `~/.hq/locks/` — held operation locks and background-work claims.
  *
@@ -167,7 +170,7 @@ export const FEEDBACK_LOCKS_DIRNAME = "locks";
  */
 export const FEEDBACK_JOBS_DIRNAME = "jobs";
 /** Per-entry ceiling for a lock file. Their value is the name plus a little context. */
-export const FEEDBACK_LOCK_MAX_FILE_BYTES = 512;
+const FEEDBACK_LOCK_MAX_FILE_BYTES = 512;
 /**
  * Bounds on the `jobs/` walk. Depth 3 reaches
  * `jobs/probes/<job>/last-attempt.json`; the file cap stops a pathological
@@ -182,7 +185,7 @@ export const FEEDBACK_LOCKS_MAX_FILES = 20;
  * Listed explicitly — the root directory holds credentials and must never be
  * enumerated by pattern.
  */
-export const FEEDBACK_ROOT_LOG_FILENAMES = [
+const FEEDBACK_ROOT_LOG_FILENAMES = [
     "boot-sync.log",
     "boot-capture.log",
 ];
@@ -279,15 +282,15 @@ function lstatOrNull(absPath) {
  * Enumerate eligible log files under `hqDir`.
  *
  * Eligibility is the allowlist described in the module header: `*.log` files
- * directly inside `hqDir/logs/`, plus {@link FEEDBACK_ROOT_LOG_FILENAMES} at
- * the root. Every candidate must be a REGULAR file by `lstat` — directories
- * and, critically, symlinks are rejected. Returned newest-modified first so
- * the most relevant log is offered the budget before older ones.
+ * directly inside `hqDir/logs/`, the exact daemon sync-log generations, plus
+ * {@link FEEDBACK_ROOT_LOG_FILENAMES} at the root. Every candidate must be a
+ * REGULAR file by `lstat` — directories and, critically, symlinks are rejected.
+ * Returned newest-modified first so the most relevant log is offered budget
+ * before older ones.
  */
-export function discoverLogFiles(hqDir) {
+export function discoverLogFiles(hqDir, env = process.env) {
     const candidates = [];
-    const consider = (relName) => {
-        const absPath = path.join(hqDir, relName);
+    const consider = (relName, absPath = path.join(hqDir, relName)) => {
         const st = lstatOrNull(absPath);
         // isFile() is false for both directories and symlinks under lstat. A
         // symlink here would be the credential-exfiltration path (see header).
@@ -313,11 +316,37 @@ export function discoverLogFiles(hqDir) {
             continue;
         consider(`${FEEDBACK_LOGS_DIRNAME}/${entry}`);
     }
+    const daemonLogPath = syncLogBasePaths(hqDir, env).daemon;
+    for (let generation = 0; generation < SYNC_LOG_GENERATIONS; generation += 1) {
+        const relName = syncLogGenerationPath(SYNC_LOG_RELATIVE_PATHS.daemon, generation);
+        const absPath = syncLogGenerationPath(daemonLogPath, generation);
+        consider(relName, absPath);
+    }
     for (const filename of FEEDBACK_ROOT_LOG_FILENAMES) {
         consider(filename);
     }
-    candidates.sort((a, b) => b.modifiedMs - a.modifiedMs);
-    return candidates;
+    let desktopModifiedMs = null;
+    let daemonModifiedMs = null;
+    for (const candidate of candidates) {
+        const family = syncLogFamilyForRelativePath(candidate.name);
+        if (family === "desktop") {
+            desktopModifiedMs = desktopModifiedMs === null
+                ? candidate.modifiedMs
+                : Math.max(desktopModifiedMs, candidate.modifiedMs);
+        }
+        else if (family === "daemon") {
+            daemonModifiedMs = daemonModifiedMs === null
+                ? candidate.modifiedMs
+                : Math.max(daemonModifiedMs, candidate.modifiedMs);
+        }
+    }
+    const selectedFamily = currentSyncLogFamily(desktopModifiedMs, daemonModifiedMs);
+    const selected = candidates.filter((candidate) => {
+        const family = syncLogFamilyForRelativePath(candidate.name);
+        return family === null || family === selectedFamily;
+    });
+    selected.sort((a, b) => b.modifiedMs - a.modifiedMs);
+    return selected;
 }
 /**
  * Read the last `maxBytes` of a file.
@@ -546,7 +575,7 @@ export function collectFeedbackLogs(opts = {}) {
     let logCandidates;
     let stateCandidates;
     try {
-        logCandidates = discoverLogFiles(hqDir);
+        logCandidates = discoverLogFiles(hqDir, opts.env);
         // Order matters: root status documents first, then the lock/claim files
         // (highest signal for a hang), then scheduled-job status. Under a tight
         // budget the earlier ones win, and that is the intended priority.

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

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

package/dist/utils/feedback-screenshots.js

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

package/dist/utils/files-browse-acl.d.ts

@@ -0,0 +1,5 @@
+/** ACL source values and their stable labels in the hq files browse table. */
+export type AclSource = "shared-with-you" | "creator" | "role-bypass" | "personal-vault" | "private-folder";
+export declare const ACL_SOURCE_DISPLAY_LABELS: Readonly<Record<AclSource, string>>;
+export declare function displayAclSource(source: AclSource): string;
+//# sourceMappingURL=files-browse-acl.d.ts.map

package/dist/utils/files-browse-acl.js

@@ -0,0 +1,11 @@
+export const ACL_SOURCE_DISPLAY_LABELS = {
+    "shared-with-you": "shared-with-you",
+    creator: "creator access — creator-only",
+    "role-bypass": "role-bypass",
+    "personal-vault": "personal-vault",
+    "private-folder": "private folder — children are creator-only",
+};
+export function displayAclSource(source) {
+    return ACL_SOURCE_DISPLAY_LABELS[source];
+}
+//# sourceMappingURL=files-browse-acl.js.map

package/dist/utils/hq-core-yaml.d.ts

@@ -0,0 +1,10 @@
+export declare function readHqVersion(hqRoot: string): string | null;
+export interface CatalogEntry {
+    source: string;
+    description?: string;
+    conditional?: string;
+    auto_install?: boolean;
+}
+/** Read recommended_packages from core.yaml (the curated content-pack catalog). */
+export declare function readRecommendedPackages(hqRoot: string): CatalogEntry[];
+//# sourceMappingURL=hq-core-yaml.d.ts.map

package/dist/utils/hq-core-yaml.js

@@ -0,0 +1,40 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+/** Locate core.yaml: v14+ nests it under core/, older layouts at the root. */
+function coreYamlPath(hqRoot) {
+    const nested = path.join(hqRoot, "core", "core.yaml");
+    if (fs.existsSync(nested))
+        return nested;
+    const flat = path.join(hqRoot, "core.yaml");
+    if (fs.existsSync(flat))
+        return flat;
+    return null;
+}
+export function readHqVersion(hqRoot) {
+    const filePath = coreYamlPath(hqRoot);
+    if (!filePath)
+        return null;
+    try {
+        const config = yaml.load(fs.readFileSync(filePath, "utf-8"));
+        return config?.hqVersion ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read recommended_packages from core.yaml (the curated content-pack catalog). */
+export function readRecommendedPackages(hqRoot) {
+    const filePath = coreYamlPath(hqRoot);
+    if (!filePath)
+        return [];
+    try {
+        const config = yaml.load(fs.readFileSync(filePath, "utf-8"));
+        const list = config?.recommended_packages;
+        return Array.isArray(list) ? list : [];
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=hq-core-yaml.js.map

package/dist/utils/hq-root-resolver.d.ts

@@ -0,0 +1,13 @@
+/** Lightweight HQ-root resolver shared by cloud commands and fast flag scope. */
+/**
+ * Resolve the HQ tree root using the same precedence as the Cognito helpers:
+ * explicit HQ_ROOT, nearest cwd root, installer records, known locations, then
+ * the historical ~/hq fallback (or an error when requested).
+ */
+export declare function resolveDefaultHqRoot(opts?: {
+    onMissing?: "throw" | "fallback";
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    home?: string;
+}): string;
+//# sourceMappingURL=hq-root-resolver.d.ts.map

package/dist/utils/hq-root-resolver.js

@@ -0,0 +1,103 @@
+/** Lightweight HQ-root resolver shared by cloud commands and fast flag scope. */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+/**
+ * Resolve the HQ tree root using the same precedence as the Cognito helpers:
+ * explicit HQ_ROOT, nearest cwd root, installer records, known locations, then
+ * the historical ~/hq fallback (or an error when requested).
+ */
+export function resolveDefaultHqRoot(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? os.homedir();
+    if (env.HQ_ROOT)
+        return path.resolve(env.HQ_ROOT);
+    let cur = path.resolve(opts.cwd ?? process.cwd());
+    while (cur !== path.dirname(cur)) {
+        if (isHqRoot(cur))
+            return cur;
+        cur = path.dirname(cur);
+    }
+    const fromConfig = readHqRootFromHqConfig(path.join(home, ".hq"));
+    if (fromConfig)
+        return path.resolve(fromConfig);
+    const discovered = discoverHqRootViaCoreYaml(home);
+    if (discovered)
+        return discovered;
+    if (opts.onMissing === "throw") {
+        throw new Error("Could not find HQ root. Run this command from within your HQ directory " +
+            "(must contain core.yaml AND a companies/ subdirectory), set $HQ_ROOT, " +
+            "or install HQ via the installer/menubar so ~/.hq/menubar.json records " +
+            "its location.");
+    }
+    return path.join(home, "hq");
+}
+function readHqRootFromHqConfig(hqConfigDir) {
+    const fromMenubar = readJsonStringField(path.join(hqConfigDir, "menubar.json"), "hqPath");
+    if (fromMenubar)
+        return fromMenubar;
+    return readJsonStringField(path.join(hqConfigDir, "config.json"), "hqFolderPath");
+}
+function readJsonStringField(file, field) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        const value = parsed[field];
+        return typeof value === "string" && value.length > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function hqDiscoveryCandidates(home) {
+    return [
+        path.join(home, "HQ"),
+        path.join(home, "hq"),
+        path.join(home, "Documents", "HQ"),
+        path.join(home, "Documents", "hq"),
+        path.join(home, "Desktop", "HQ"),
+        path.join(home, "Desktop", "hq"),
+    ];
+}
+function discoverHqRootViaCoreYaml(home) {
+    return hqDiscoveryCandidates(home).find(isValidHqRootSignature);
+}
+function isValidHqRootSignature(dir) {
+    const canonical = path.join(dir, "core", "core.yaml");
+    const legacy = path.join(dir, "core.yaml");
+    let file;
+    if (fileExists(canonical))
+        file = canonical;
+    else if (fileExists(legacy))
+        file = legacy;
+    else
+        return false;
+    try {
+        const parsed = yaml.load(fs.readFileSync(file, "utf-8"));
+        return !!parsed && typeof parsed === "object" && "version" in parsed && "hqVersion" in parsed;
+    }
+    catch {
+        return false;
+    }
+}
+function fileExists(file) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isHqRoot(dir) {
+    const hasCoreYaml = fileExists(path.join(dir, "core", "core.yaml")) ||
+        fileExists(path.join(dir, "core.yaml"));
+    if (!hasCoreYaml)
+        return false;
+    try {
+        return fs.statSync(path.join(dir, "companies")).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=hq-root-resolver.js.map

package/dist/utils/hq-roots.d.ts

@@ -59,8 +59,31 @@ export declare function createPackageRootResolver(options: PackageRootResolverOp
  * answer survives a change in output layout.
  */
 export declare function packageRoot(): string;
-/** Reset the memoized package root. Tests only. */
-export declare function __resetPackageRootCache(): void;
+/**
+ * Derive this package's installed root from the running module's OWN path using
+ * STRING operations only — no `readFileSync`, `realpathSync`, or `existsSync`.
+ *
+ * {@link packageRoot} must read `<dir>/package.json` and `realpathSync` the
+ * module directory to answer, so it THROWS in exactly the situation that most
+ * needs an answer: a concurrent global install has renamed the installed
+ * package directory aside (`.hq-cli-<rand>`) and is re-extracting it file by
+ * file, so both the manifest walk and the dist-owner fallback fail on a
+ * directory that is momentarily gone. This walks the compiled module's
+ * ancestors as strings and returns the DEEPEST one whose trailing segments are
+ * `node_modules/@indigoai-us/hq-cli`, which stays correct while that directory
+ * does not exist on disk.
+ *
+ * It is a FALLBACK only — {@link packageRoot} validates the manifest name and
+ * is authoritative whenever it succeeds. Returns null for a dev checkout or any
+ * layout without that segment triple, so a caller that falls back to it can
+ * only ever degrade to today's behaviour (no resolution), never widen it.
+ *
+ * The deepest match is deliberate: a nested `node_modules/@indigoai-us/hq-cli`
+ * inside another package resolves to ITSELF (the copy the module belongs to),
+ * never an outer decoy. Case is folded only for a Windows-shaped path, matching
+ * the POSIX case-sensitivity the rest of this module assumes.
+ */
+export declare function stringDerivedPackageRoot(moduleFilePath?: string): string | null;
 export type LiveRootOptions = {
     /** Explicit `--hq-root` value. Highest precedence. */
     hqRoot?: string;

package/dist/utils/hq-roots.js

@@ -170,7 +170,7 @@ export function createPackageRootResolver(options) {
     };
 }
 const currentModulePath = fileURLToPath(import.meta.url);
-let defaultPackageRootResolver = createPackageRootResolver({
+const defaultPackageRootResolver = createPackageRootResolver({
     moduleDir: path.dirname(currentModulePath),
     modulePath: currentModulePath,
 });
@@ -184,12 +184,72 @@ let defaultPackageRootResolver = createPackageRootResolver({
 export function packageRoot() {
     return defaultPackageRootResolver();
 }
-/** Reset the memoized package root. Tests only. */
-export function __resetPackageRootCache() {
-    defaultPackageRootResolver = createPackageRootResolver({
-        moduleDir: path.dirname(currentModulePath),
-        modulePath: currentModulePath,
-    });
+/**
+ * The trailing path segments that mark an installed copy of this package:
+ * `node_modules` followed by the package name's own segments (for
+ * `@indigoai-us/hq-cli`, that is `node_modules/@indigoai-us/hq-cli`).
+ */
+const INSTALLED_ROOT_SEGMENTS = ["node_modules", ...CLI_PACKAGE_NAME.split("/")];
+/** A Windows-shaped absolute path (drive letter or UNC), regardless of host OS. */
+function looksWin32Path(p) {
+    return /^[a-zA-Z]:[\\/]/.test(p) || /^\\\\/.test(p);
+}
+/**
+ * Derive this package's installed root from the running module's OWN path using
+ * STRING operations only — no `readFileSync`, `realpathSync`, or `existsSync`.
+ *
+ * {@link packageRoot} must read `<dir>/package.json` and `realpathSync` the
+ * module directory to answer, so it THROWS in exactly the situation that most
+ * needs an answer: a concurrent global install has renamed the installed
+ * package directory aside (`.hq-cli-<rand>`) and is re-extracting it file by
+ * file, so both the manifest walk and the dist-owner fallback fail on a
+ * directory that is momentarily gone. This walks the compiled module's
+ * ancestors as strings and returns the DEEPEST one whose trailing segments are
+ * `node_modules/@indigoai-us/hq-cli`, which stays correct while that directory
+ * does not exist on disk.
+ *
+ * It is a FALLBACK only — {@link packageRoot} validates the manifest name and
+ * is authoritative whenever it succeeds. Returns null for a dev checkout or any
+ * layout without that segment triple, so a caller that falls back to it can
+ * only ever degrade to today's behaviour (no resolution), never widen it.
+ *
+ * The deepest match is deliberate: a nested `node_modules/@indigoai-us/hq-cli`
+ * inside another package resolves to ITSELF (the copy the module belongs to),
+ * never an outer decoy. Case is folded only for a Windows-shaped path, matching
+ * the POSIX case-sensitivity the rest of this module assumes.
+ */
+export function stringDerivedPackageRoot(moduleFilePath = currentModulePath) {
+    if (typeof moduleFilePath !== "string" || moduleFilePath.length === 0) {
+        return null;
+    }
+    const wanted = INSTALLED_ROOT_SEGMENTS;
+    const caseInsensitive = looksWin32Path(moduleFilePath);
+    const sameSegment = (a, b) => caseInsensitive ? a.toLowerCase() === b.toLowerCase() : a === b;
+    // Tokenise into segments with each one's end offset in the ORIGINAL string,
+    // so the returned root keeps the source path's leading root and separators
+    // verbatim (a leading `/`, or a `C:\` drive) rather than a rejoined guess.
+    const segments = [];
+    const segmentPattern = /[^\\/]+/g;
+    let match;
+    while ((match = segmentPattern.exec(moduleFilePath)) !== null) {
+        segments.push({ text: match[0], end: match.index + match[0].length });
+    }
+    if (segments.length < wanted.length)
+        return null;
+    // Scan from the deepest segment upward; the first (deepest) leaf whose
+    // preceding segments complete the triple wins.
+    for (let leaf = segments.length - 1; leaf >= wanted.length - 1; leaf--) {
+        let matched = true;
+        for (let k = 0; k < wanted.length; k++) {
+            if (!sameSegment(segments[leaf - (wanted.length - 1) + k].text, wanted[k])) {
+                matched = false;
+                break;
+            }
+        }
+        if (matched)
+            return moduleFilePath.slice(0, segments[leaf].end);
+    }
+    return null;
 }
 /**
  * Resolve the user's live HQ installation.

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

@@ -10,11 +10,14 @@ import * as fs from "fs";
 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;
+/** Which strategy produced the running install's root, recorded in diagnostics. */
+type PackageRootResolverSource = "manifest-walk" | "string-derivation" | "unresolved" | "injected";
 /**
- * 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.
+ * If `err` is an in-process incomplete-install module-load failure — the CJS
+ * relative-sibling shape (HQ-CLI-1N), the ESM vanished-at-read shape (HQ-CLI-1M),
+ * or the resolve-time lstat shape (HQ-CLI-1S), 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
@@ -22,14 +25,51 @@ export type PackageRootResolver = () => string | null;
  * fails yields null.
  */
 export declare function incompleteInstallMessage(err: unknown, resolvePackageRoot?: PackageRootResolver, fileSystem?: Pick<typeof fs, "readFileSync">): string | null;
-/** Bounded, scrubber-safe diagnostics for an unattributable esm-loader ENOENT (HQ-CLI-1M). */
-export type IncompleteInstallEsmDiagnostics = {
+/**
+ * Bounded, scrubber-safe diagnostics for an unattributable loader/resolver ENOENT
+ * whose `path` did not survive delivery — the esm-loader open shape (HQ-CLI-1M) or
+ * the resolve-time lstat shape (HQ-CLI-1S). The two frame booleans say which.
+ */
+type IncompleteInstallEsmDiagnostics = {
+    /** The resolved install root, or the literal `<unresolved>` when none was found. */
     packageRoot: string;
-    packageJsonExists: boolean;
-    nodeModulesExists: boolean;
+    /** True only when a root was actually resolved (by any strategy). */
+    packageRootResolved: boolean;
+    /** Which resolver answered — so an unresolved root is never read as resolved-but-missing. */
+    resolver: PackageRootResolverSource;
+    /**
+     * Whether `<root>/package.json` and `<root>/node_modules` exist on disk.
+     * Present ONLY when a root was resolved: reported for an unresolved root,
+     * a bare `false` is indistinguishable from "resolved but the file is missing"
+     * — the ambiguity that made the delivered HQ-CLI-1M evidence weaker than
+     * intended (the two booleans were uninitialised defaults).
+     */
+    packageJsonExists?: boolean;
+    nodeModulesExists?: boolean;
+    /** The stack carried an esm-loader (source-read) frame — the HQ-CLI-1M route. */
     esmLoaderFrame: boolean;
+    /** The stack carried a module-resolver frame — the HQ-CLI-1S resolve-time route. */
+    resolverFrame: boolean;
+    /** The stack carried a CJS loader (source-read) frame — the HQ-CLI-20 route. */
+    cjsLoaderFrame: boolean;
     code: string;
 };
+/**
+ * Bounded, scrubber-safe diagnostics for a module-EVALUATION throw that reached
+ * the boundary raw (HQ-CLI-1T) — a code-less TypeError/ReferenceError/SyntaxError
+ * whose throw site sits under the running install's node_modules, so the next
+ * occurrence names the offending third-party package instead of filing bare. Only
+ * the closed error name and the bounded package name are recorded; never the
+ * message, argv, or a full path.
+ */
+type IncompleteInstallEvalThrowDiagnostics = {
+    evalThrow: true;
+    errorName: string;
+    throwSitePackage: string;
+    packageRoot: string;
+    packageRootResolved: boolean;
+    resolver: PackageRootResolverSource;
+};
 /**
  * Bounded, scrubber-safe diagnostics for a NOT-suppressed third-party bare miss
  * (HQ-CLI-1Q): a possible undeclared / peer-only dependency defect, made
@@ -37,30 +77,57 @@ export type IncompleteInstallEsmDiagnostics = {
  * the requirer's own manifest did NOT declare it. Both names live inside
  * hq-cli's dependency graph, so grouping cardinality stays bounded.
  */
-export type IncompleteInstallBareDiagnostics = {
+type IncompleteInstallBareDiagnostics = {
     missingPackage: string;
     requiringPackage: string;
     requirerDeclaresMissing: false;
 };
+/** The four lexical scopes a NOT-suppressed CJS relative requirer can fall into. */
+type RelativeRequirerScope = "dist" | "assets" | "outside-root" | "unresolved-root";
+/**
+ * Bounded, scrubber-safe diagnostics for a NOT-suppressed CJS RELATIVE-specifier
+ * miss (HQ-CLI-1N): the CJS relative-sibling shape that reached the capture path
+ * WITHOUT being suppressed — its requirer sits under the install's own `dist/` or
+ * `assets/`, outside the running install entirely, or the install root could not
+ * be resolved. Records only a bounded, four-value LEXICAL scope of the requirer
+ * against the root — never the requirer path and never the specifier — so
+ * grouping cardinality cannot inflate. `code` is always `MODULE_NOT_FOUND`.
+ */
+type IncompleteInstallRelativeDiagnostics = {
+    code: string;
+    relativeSpecifier: true;
+    packageRoot: string;
+    packageRootResolved: boolean;
+    resolver: PackageRootResolverSource;
+    requirerScope: RelativeRequirerScope;
+};
 /**
- * Both enriched shapes as a single OPEN record — every field optional so a
- * consumer can forward either shape to Sentry without narrowing (the boundary
- * and beforeSend only pass the block through). Every value CONSTRUCTED here is
- * exactly one of the two strict shapes above; the looseness is only at the read
+ * The enriched shapes as a single OPEN record — every field optional so a
+ * consumer can forward any shape to Sentry without narrowing (the boundary and
+ * beforeSend only pass the block through). Every value CONSTRUCTED here is
+ * exactly one of the strict shapes above; the looseness is only at the read
  * boundary.
  */
-export type IncompleteInstallDiagnostics = Partial<IncompleteInstallEsmDiagnostics & IncompleteInstallBareDiagnostics>;
+export type IncompleteInstallDiagnostics = Partial<IncompleteInstallEsmDiagnostics & IncompleteInstallBareDiagnostics & IncompleteInstallRelativeDiagnostics & IncompleteInstallEvalThrowDiagnostics>;
 /**
  * When an incomplete-install failure reaches the capture path WITHOUT being
  * suppressed, return a bounded `contexts.incomplete_install` block so the next
  * occurrence carries the evidence this one lacked; otherwise return undefined
- * (bare capture). Two enriched shapes:
+ * (bare capture). Three enriched shapes:
  *   - a third-party BARE-specifier miss the requirer did not declare (HQ-CLI-1Q)
  *     → { missingPackage, requiringPackage, requirerDeclaresMissing:false };
- *   - an esm-loader ENOENT whose path did not survive delivery (HQ-CLI-1M) — the
- *     shape the delivered payload arrived in, where neither the exception value
- *     nor node_system_error carried a `path` → { packageRoot, packageJsonExists,
- *     nodeModulesExists, esmLoaderFrame, code }.
+ *   - a CJS RELATIVE-specifier miss whose requirer sits under the install's own
+ *     dist/ or assets/, outside the install, or under an unresolved root
+ *     (HQ-CLI-1N) → { code, relativeSpecifier:true, packageRoot,
+ *     packageRootResolved, resolver, requirerScope };
+ *   - a loader/resolver ENOENT whose path did not survive delivery (HQ-CLI-1M
+ *     esm-load open, HQ-CLI-1S resolve-time lstat, HQ-CLI-20 CJS load-time open) —
+ *     where neither the exception value nor node_system_error carried a `path` →
+ *     { packageRoot, packageJsonExists, nodeModulesExists, esmLoaderFrame,
+ *     resolverFrame, cjsLoaderFrame, code };
+ *   - a module-EVALUATION throw that reached the boundary raw (HQ-CLI-1T) →
+ *     { evalThrow, errorName, throwSitePackage, packageRoot, packageRootResolved,
+ *     resolver }.
  * Built with the byte-capped, scrubber-safe discipline of
  * package-root-diagnostics.ts — never a caller argv, query, or user-minted
  * value. Never throws. main.ts attaches this on the generic capture path
@@ -69,4 +136,5 @@ export type IncompleteInstallDiagnostics = Partial<IncompleteInstallEsmDiagnosti
 export declare function incompleteInstallCaptureContext(err: unknown, resolvePackageRoot?: PackageRootResolver, fileSystem?: Pick<typeof fs, "existsSync"> & Partial<Pick<typeof fs, "readFileSync">>): {
     incomplete_install: IncompleteInstallDiagnostics;
 } | undefined;
+export {};
 //# sourceMappingURL=incomplete-install-error.d.ts.map