@indigoai-us/hq-cli 5.109.6 → 5.109.8

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## [Unreleased]
 
+## [5.109.8] — 2026-09-11
+
+### Fixed
+
+- A background reinstall no longer turns into a crash report (HQ-CLI-1M,
+  HQ-CLI-1N). When another program reinstalls hq globally while a command is
+  running — the box's own update timer, the desktop app, or a second `hq` — it
+  renames hq's files aside and rewrites them file by file over a few seconds, and
+  a command already running can try to load a file that vanished in that window.
+  hq already knew to treat that as "your install was mid-update, not an hq bug"
+  and print a re-run/reinstall note instead of a crash, but it could only do so
+  while it could still find its own install directory on disk — which, in this
+  exact situation, it usually could not, because that directory is what just got
+  renamed away. That one blind spot silenced the recovery for two different crash
+  shapes: the ESM-loader `ENOENT` seen in production (HQ-CLI-1M) and a lazy
+  CommonJS `require('./sibling')` from a bundled dependency that resolves after
+  the tear (HQ-CLI-1N). hq now locates its own directory without reading the
+  disk, so the mid-update case is recognized for both: a registration-time tear
+  waits for the install to settle and re-runs once, and a tear anywhere else
+  prints the reinstall note. A genuine packaging fault in hq's own shipped files
+  (a miss under the install's own `dist/` or `assets/`) is still reported.
+
+## [5.109.7] — 2026-09-10
+
+### Fixed
+
+- Add `whoami --json`, structured `files acl --json` with explicit absence,
+  and `people resolve --membership-only` with canonical company/person IDs.
+  Delegation helpers can now verify exact grants without parsing display tables
+  or treating a missing ACL as a transport failure. Existing human output stays available.
+
 ## [5.109.6] — 2026-09-10
 
 ### Fixed

package/dist/commands/files.js

@@ -276,7 +276,8 @@ export function registerFilesCommand(program) {
     files
         .command("acl <prefix>")
         .description("Show the ACL (access control list) for a file prefix")
-        .action(async (prefix) => {
+        .option("--json", "Output structured ACL data, including explicit absence")
+        .action(async (prefix, opts) => {
         try {
             // Read-only, so stripping is safe — but a mismatched anchor would show
             // a DIFFERENT company's ACL than the one the operator pasted.
@@ -321,7 +322,16 @@ export function registerFilesCommand(program) {
                 process.exit(1);
             }
             const tree = (await treeRes.json());
+            if (!tree || typeof tree.prefix !== 'string' || !Array.isArray(tree.direct)
+                || !Array.isArray(tree.inherited) || !Array.isArray(tree.children)
+                || !(tree.directRow === null || (typeof tree.directRow === 'object' && tree.directRow))) {
+                throw new Error('Invalid ACL tree response');
+            }
             const row = tree.directRow;
+            if (opts.json) {
+                console.log(JSON.stringify({ ...tree, schemaVersion: 1, companyUid, exists: row !== null }, null, 2));
+                return;
+            }
             // No own row AND nothing inherited or granted below — preserve the
             // original "no ACL record" exit path.
             if (!row && tree.inherited.length === 0 && tree.children.length === 0) {

package/dist/commands/people.d.ts

@@ -20,6 +20,7 @@ interface PeopleCommandDeps {
 }
 interface PeopleLookupOpts {
     localOnly?: boolean;
+    membershipOnly?: boolean;
     json?: boolean;
 }
 export declare function activeMemberToPersonRecord(m: ActiveMember): PersonRecord | null;

package/dist/commands/people.js

@@ -41,6 +41,8 @@ export function activeMemberToPersonRecord(m) {
         slug,
         name,
         email,
+        personUid: m.personUid,
+        companyUid: m.companyUid,
         role: m.role || undefined,
         type: "internal",
         source: `hq-pro membership: /membership/company/${m.companyUid}`,
@@ -147,6 +149,13 @@ async function tryFetchRoster(fetchRoster, hqRoot, slug) {
     }
 }
 export async function resolvePersonWithRosterFallback(input) {
+    if (input.opts?.membershipOnly) {
+        if (input.opts.localOnly)
+            throw new Error('--membership-only cannot be combined with --local-only');
+        // No local fallback: callers need authoritative IDs and must see transport errors.
+        const roster = await (input.fetchRoster ?? fetchMembershipRoster)(input.hqRoot, input.slug);
+        return resolveNameToEmail(roster, input.name);
+    }
     const localPeople = listCompanyPeople(input.hqRoot, input.slug);
     const local = resolveNameToEmail(localPeople, input.name);
     if (local.status !== "not_found" || input.opts?.localOnly)
@@ -239,6 +248,7 @@ export function registerPeopleCommand(program, deps = {}) {
     people
         .command("resolve <name>")
         .description("Resolve a person name to their email address")
+        .option("--membership-only", "Resolve from authoritative company membership, ignoring local records")
         .option("--json", "Output JSON instead of plain text")
         .option("--local-only", "Skip network fallback; resolve only from the local people roster")
         .action(async (name, opts) => {

package/dist/commands/pkg-install.d.ts

@@ -1,17 +1,3 @@
-/**
- * hq packages install <slug> — download, verify, and extract a package (US-005)
- *
- * Flow:
- * 1. Check auth (prompt login if needed)
- * 2. Check entitlement via API
- * 3. Download tarball via presigned URL
- * 4. Verify SHA256 hash
- * 5. Verify RSA signature (if provided)
- * 6. Extract to packages/installed/<slug>/
- * 7. Validate extracted package.yaml slug matches
- * 8. Update packages/registry.yaml
- * 9. Print next-step message
- */
 import { Command } from 'commander';
 export declare function registerPackageInstallCommand(parent: Command): void;
 //# sourceMappingURL=pkg-install.d.ts.map

package/dist/commands/pkg-install.js

@@ -1,28 +1,4 @@
-/**
- * hq packages install <slug> — download, verify, and extract a package (US-005)
- *
- * Flow:
- * 1. Check auth (prompt login if needed)
- * 2. Check entitlement via API
- * 3. Download tarball via presigned URL
- * 4. Verify SHA256 hash
- * 5. Verify RSA signature (if provided)
- * 6. Extract to packages/installed/<slug>/
- * 7. Validate extracted package.yaml slug matches
- * 8. Update packages/registry.yaml
- * 9. Print next-step message
- */
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import { parseUserYaml } from '../utils/user-yaml-error.js';
-import { execSync } from 'child_process';
 import chalk from 'chalk';
-import { ensureCognitoToken } from '../utils/cognito-session.js';
-import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
-import { getRegistryUrl, RegistryClient, } from '../utils/registry-client.js';
-import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
-import { addToRegistry } from '../utils/registry.js';
 import { peekHqApiKey, requireApiKeyCapability, } from '../utils/resolve-vault-credential.js';
 import { MARKETPLACE_PREFIX, installPack, sourceMatchesPackPattern, } from './pack-install.js';
 /**
@@ -105,107 +81,4 @@ export function registerPackageInstallCommand(parent) {
         }
     });
 }
-async function installPackage(slug, company) {
-    // 1. Auth
-    const accessToken = await ensureCognitoToken();
-    const registryUrl = getRegistryUrl();
-    const client = new RegistryClient(registryUrl, accessToken);
-    // 2. Check entitlement
-    console.log(chalk.dim(`Checking entitlement for ${slug}...`));
-    const entitlement = await client.checkEntitlement(slug);
-    if (!entitlement.entitled) {
-        throw new Error(`You are not entitled to package "${slug}". Visit the registry to purchase or request access.`);
-    }
-    // 3. Get download URL
-    console.log(chalk.dim('Fetching download URL...'));
-    const download = await client.getDownloadUrl(slug);
-    // 4. Download to temp file
-    const tmpDir = os.tmpdir();
-    const tmpFile = path.resolve(tmpDir, `hq-pkg-${slug}-${Date.now()}.tar.gz`);
-    try {
-        console.log(chalk.dim('Downloading package...'));
-        const response = await fetch(download.url, {
-            signal: AbortSignal.timeout(120_000),
-        });
-        if (!response.ok) {
-            throw new Error(`Download failed (${response.status})`);
-        }
-        const buffer = Buffer.from(await response.arrayBuffer());
-        fs.writeFileSync(tmpFile, buffer);
-        // 5. Verify SHA256
-        console.log(chalk.dim('Verifying integrity...'));
-        const hashValid = await verifySha256(tmpFile, download.sha256);
-        if (!hashValid) {
-            throw new Error('SHA256 hash mismatch — the downloaded file may be corrupted or tampered with.');
-        }
-        // 6. Verify RSA signature (if provided)
-        if (download.signature) {
-            const sigValid = verifyRsaSignature(download.sha256, download.signature);
-            if (!sigValid) {
-                throw new Error('RSA signature verification failed — the package may have been tampered with or the public key is missing/invalid. Aborting install.');
-            }
-        }
-        // 7. Extract
-        const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
-        const installDir = path.resolve(hqRoot, 'packages', 'installed', slug);
-        // Clean existing installation
-        if (fs.existsSync(installDir)) {
-            fs.rmSync(installDir, { recursive: true, force: true });
-        }
-        fs.mkdirSync(installDir, { recursive: true });
-        execSync(`tar -xzf "${tmpFile}" -C "${installDir}"`, {
-            stdio: 'pipe',
-        });
-        // 8. Validate package.yaml slug
-        const packageYamlPath = path.resolve(installDir, 'package.yaml');
-        if (fs.existsSync(packageYamlPath)) {
-            const pkgContent = fs.readFileSync(packageYamlPath, 'utf-8');
-            const pkgMeta = parseUserYaml(pkgContent, packageYamlPath);
-            if (pkgMeta?.slug && pkgMeta.slug !== slug) {
-                // Mismatch — clean up and abort
-                fs.rmSync(installDir, { recursive: true, force: true });
-                throw new Error(`Package slug mismatch: expected "${slug}", got "${pkgMeta.slug}"`);
-            }
-        }
-        // 9. Get package info for registry entry
-        let version = 'unknown';
-        let name = slug;
-        try {
-            const pkgInfo = await client.getPackage(slug);
-            version = pkgInfo.package.latest_version;
-            name = pkgInfo.package.name;
-        }
-        catch {
-            // Best-effort — fall back to package.yaml if present
-            const packageYaml = path.resolve(installDir, 'package.yaml');
-            if (fs.existsSync(packageYaml)) {
-                const content = fs.readFileSync(packageYaml, 'utf-8');
-                const meta = parseUserYaml(content, packageYaml);
-                if (meta?.version)
-                    version = meta.version;
-                if (meta?.name)
-                    name = meta.name;
-            }
-        }
-        // 10. Update registry.yaml
-        const now = new Date().toISOString();
-        addToRegistry(hqRoot, {
-            name,
-            slug,
-            version,
-            source: registryUrl,
-            scope: company,
-            installed_at: now,
-            updated_at: now,
-        });
-        console.log(chalk.green(`\nInstalled ${slug}@${version} to packages/installed/${slug}/`));
-        console.log(chalk.cyan('Run /package-install ' + slug + ' in Claude to merge into your HQ.'));
-    }
-    finally {
-        // Clean up temp file — never leave partial downloads
-        if (fs.existsSync(tmpFile)) {
-            fs.unlinkSync(tmpFile);
-        }
-    }
-}
 //# sourceMappingURL=pkg-install.js.map

package/dist/commands/whoami.js

@@ -4,7 +4,7 @@
 import chalk from 'chalk';
 import { loadCachedTokens, isExpiring, loadMachineCreds, } from '@indigoai-us/hq-cloud';
 import { peekIdToken as decodeIdToken } from "../utils/id-token.js";
-import { resolveCognitoTokenSource } from "../utils/cognito-session.js";
+import { loadMachineCachedTokens, resolveCognitoTokenSource } from "../utils/cognito-session.js";
 function peekIdToken(idToken) {
     const decoded = decodeIdToken(idToken);
     return {
@@ -22,13 +22,39 @@ export function registerWhoamiCommand(program) {
     program
         .command('whoami')
         .description('Show the currently authenticated user')
-        .action(async () => {
+        .option('--json', 'Output identity metadata as JSON (never tokens)')
+        .action(async (opts) => {
         try {
             // Effective source (same as auth status / ensureCognitoToken): env
             // opt-in, fresh-box default-creds when no usable person session, or
             // after a definitive person-refresh rejection marked the session rejected.
             const machine = resolveCognitoTokenSource() === "machine";
             const cached = loadCachedTokens();
+            if (opts.json) {
+                const machineCreds = machine ? loadMachineCreds() : null;
+                const identityCache = machine ? loadMachineCachedTokens() : cached;
+                const identity = identityCache ? peekIdToken(identityCache.idToken) : {};
+                const claims = identityCache ? decodeIdToken(identityCache.idToken) : {};
+                // Modern credentials carry the canonical UID. Legacy caches may only
+                // supply a UID when their subject is bound to the selected username.
+                const boundLegacyAgent = machineCreds && identity.entityType === 'agent'
+                    && (claims['cognito:username'] === machineCreds.username
+                        || claims.username === machineCreds.username || claims.sub === machineCreds.username)
+                    ? identity.entityUid ?? null : null;
+                const agentUid = machineCreds?.entityUid !== undefined
+                    ? (machineCreds.entityUid.startsWith('agt_') ? machineCreds.entityUid : null)
+                    : boundLegacyAgent;
+                console.log(JSON.stringify({
+                    schemaVersion: 1,
+                    authenticated: machine ? Boolean(machineCreds) : Boolean(cached && !isExpiring(cached, 0)),
+                    tokenSource: machine ? 'machine' : 'person',
+                    email: machine ? null : identity.email ?? null,
+                    personUid: !machine && identity.entityType === 'person' ? identity.entityUid ?? null : null,
+                    agentUid,
+                    username: machineCreds?.username ?? null,
+                }, null, 2));
+                return;
+            }
             if (machine) {
                 // Machine identities (company agents) mint sessions on demand from
                 // long-lived creds — report the machine identity honestly even when

package/dist/lib/doctor/checks/runtime-probe.d.ts

@@ -50,7 +50,7 @@ export declare const POLICY_TRIGGER_LEDGER_RELPATH = "workspace/orchestrator/pol
 /** The two lifecycle events `check-hq-hooks.sh` requires a command hook on. */
 export declare const REQUIRED_HOOK_EVENTS: readonly ["SessionStart", "PreToolUse"];
 /**
- * Default runtime marker path an agents-v2 (hermes) box writes its runtime mode
+ * Default runtime marker path an agents-v2 (hq-fleet) box writes its runtime mode
  * to. Overridable via `HQ_RUNTIME_MARKER_FILE`, exactly as the shell reads
  * `${HQ_RUNTIME_MARKER_FILE:-/var/lib/hq-agent/runtime.json}`.
  */
@@ -129,31 +129,31 @@ export interface AgentsV2AttestationOptions {
  */
 export declare function isAgentsV2Runtime(hqRoot: string, env?: NodeJS.ProcessEnv): boolean;
 /**
- * Env var overriding the agents-v2 runtime (hermes) config path (chiefly for
+ * Env var overriding the agents-v2 runtime (hq-fleet) config path (chiefly for
  * tests), mirroring `HQ_RUNTIME_MARKER_FILE` and the shell's
- * `HQ_HERMES_CONFIG_FILE`.
+ * `HQ_FLEET_CONFIG_FILE`.
  */
-export declare const HQ_HERMES_CONFIG_ENV = "HQ_HERMES_CONFIG_FILE";
+export declare const HQ_FLEET_CONFIG_ENV = "HQ_FLEET_CONFIG_FILE";
 /**
- * The agents-v2 runtime (hermes) config whose `hooks:` block wires the on-box
- * adapter into every lifecycle event — the env override, else `~/.hermes/config.yaml`
+ * The agents-v2 runtime (hq-fleet) config whose `hooks:` block wires the on-box
+ * adapter into every lifecycle event — the env override, else `~/.hq-fleet/config.yaml`
  * (where `provision/render-config.sh` renders it). Mirrors the shell's
- * `HQ_HERMES_CONFIG_FILE="${HQ_HERMES_CONFIG_FILE:-$HOME/.hermes/config.yaml}"`.
+ * `HQ_FLEET_CONFIG_FILE="${HQ_FLEET_CONFIG_FILE:-$HOME/.hq-fleet/config.yaml}"`.
  */
-export declare function resolveHermesConfigPath(env?: NodeJS.ProcessEnv): string;
+export declare function resolveHqFleetConfigPath(env?: NodeJS.ProcessEnv): string;
 /**
  * Whether the agents-v2 runtime actually wires the on-box hook adapter.
  *
  * The wiring lives in the RUNTIME's hook config, not `.claude/settings.json`. On
  * a real box the v2 runtime's shell-hook dispatcher (`agent/shell_hooks.py`)
- * reads a `hooks:` block from `~/.hermes/config.yaml` with one entry per
+ * reads a `hooks:` block from `~/.hq-fleet/config.yaml` with one entry per
  * lifecycle event, each invoking `hq-agents-v2-hook-adapter.sh`; the adapter in
  * turn READS `.claude/settings.json` (via `hook-adapter-core.sh`) to fan out to
  * the classic `.claude/hooks` set. So `.claude/settings.json` never NAMES the
  * adapter — it wires the classic `hook-gate.sh` hooks — and grepping it for the
  * adapter always fails on a real box (verified on the v2.17 canary
  * i-0277243ad3aed8109, 2026-09-05: settings.json had 0 adapter refs / 94
- * hook-gate.sh refs, while ~/.hermes/config.yaml wired the adapter across 7
+ * hook-gate.sh refs, while ~/.hq-fleet/config.yaml wired the adapter across 7
  * events). Require BOTH the adapter installed under the tree at
  * {@link AGENTS_V2_ADAPTER_RELPATH} AND the runtime config invoking it. Mirrors
  * `hq_runtime_config_wires_v2_adapter` in `check-hq-hooks.sh`.
@@ -169,7 +169,7 @@ export declare function runtimeConfigWiresV2Adapter(hqRoot: string, env?: NodeJS
 export declare function v2LedgerPresent(opts: AgentsV2AttestationOptions): boolean;
 /**
  * All three agents-v2 self-attestation conditions. Used only to GRANT PASS to a
- * hermes box that host detection leaves platform-unknown; never to withhold it.
+ * hq-fleet box that host detection leaves platform-unknown; never to withhold it.
  * The exact conjunction of `agents_v2_attested` in `check-hq-hooks.sh`.
  */
 export declare function agentsV2Attested(opts: AgentsV2AttestationOptions): boolean;

package/dist/lib/doctor/checks/runtime-probe.js

@@ -53,7 +53,7 @@ export const POLICY_TRIGGER_LEDGER_RELPATH = "workspace/orchestrator/policy-trig
 /** The two lifecycle events `check-hq-hooks.sh` requires a command hook on. */
 export const REQUIRED_HOOK_EVENTS = ["SessionStart", "PreToolUse"];
 /**
- * Default runtime marker path an agents-v2 (hermes) box writes its runtime mode
+ * Default runtime marker path an agents-v2 (hq-fleet) box writes its runtime mode
  * to. Overridable via `HQ_RUNTIME_MARKER_FILE`, exactly as the shell reads
  * `${HQ_RUNTIME_MARKER_FILE:-/var/lib/hq-agent/runtime.json}`.
  */
@@ -161,36 +161,36 @@ function readRuntimeMarkerMode(markerPath) {
     }
 }
 /**
- * Env var overriding the agents-v2 runtime (hermes) config path (chiefly for
+ * Env var overriding the agents-v2 runtime (hq-fleet) config path (chiefly for
  * tests), mirroring `HQ_RUNTIME_MARKER_FILE` and the shell's
- * `HQ_HERMES_CONFIG_FILE`.
+ * `HQ_FLEET_CONFIG_FILE`.
  */
-export const HQ_HERMES_CONFIG_ENV = "HQ_HERMES_CONFIG_FILE";
+export const HQ_FLEET_CONFIG_ENV = "HQ_FLEET_CONFIG_FILE";
 /**
- * The agents-v2 runtime (hermes) config whose `hooks:` block wires the on-box
- * adapter into every lifecycle event — the env override, else `~/.hermes/config.yaml`
+ * The agents-v2 runtime (hq-fleet) config whose `hooks:` block wires the on-box
+ * adapter into every lifecycle event — the env override, else `~/.hq-fleet/config.yaml`
  * (where `provision/render-config.sh` renders it). Mirrors the shell's
- * `HQ_HERMES_CONFIG_FILE="${HQ_HERMES_CONFIG_FILE:-$HOME/.hermes/config.yaml}"`.
+ * `HQ_FLEET_CONFIG_FILE="${HQ_FLEET_CONFIG_FILE:-$HOME/.hq-fleet/config.yaml}"`.
  */
-export function resolveHermesConfigPath(env = process.env) {
-    const override = env[HQ_HERMES_CONFIG_ENV]?.trim();
+export function resolveHqFleetConfigPath(env = process.env) {
+    const override = env[HQ_FLEET_CONFIG_ENV]?.trim();
     if (override)
         return override;
-    return path.join(os.homedir(), ".hermes", "config.yaml");
+    return path.join(os.homedir(), ".hq-fleet", "config.yaml");
 }
 /**
  * Whether the agents-v2 runtime actually wires the on-box hook adapter.
  *
  * The wiring lives in the RUNTIME's hook config, not `.claude/settings.json`. On
  * a real box the v2 runtime's shell-hook dispatcher (`agent/shell_hooks.py`)
- * reads a `hooks:` block from `~/.hermes/config.yaml` with one entry per
+ * reads a `hooks:` block from `~/.hq-fleet/config.yaml` with one entry per
  * lifecycle event, each invoking `hq-agents-v2-hook-adapter.sh`; the adapter in
  * turn READS `.claude/settings.json` (via `hook-adapter-core.sh`) to fan out to
  * the classic `.claude/hooks` set. So `.claude/settings.json` never NAMES the
  * adapter — it wires the classic `hook-gate.sh` hooks — and grepping it for the
  * adapter always fails on a real box (verified on the v2.17 canary
  * i-0277243ad3aed8109, 2026-09-05: settings.json had 0 adapter refs / 94
- * hook-gate.sh refs, while ~/.hermes/config.yaml wired the adapter across 7
+ * hook-gate.sh refs, while ~/.hq-fleet/config.yaml wired the adapter across 7
  * events). Require BOTH the adapter installed under the tree at
  * {@link AGENTS_V2_ADAPTER_RELPATH} AND the runtime config invoking it. Mirrors
  * `hq_runtime_config_wires_v2_adapter` in `check-hq-hooks.sh`.
@@ -201,7 +201,7 @@ export function runtimeConfigWiresV2Adapter(hqRoot, env = process.env) {
         return false;
     let raw;
     try {
-        raw = fs.readFileSync(resolveHermesConfigPath(env), "utf8");
+        raw = fs.readFileSync(resolveHqFleetConfigPath(env), "utf8");
     }
     catch {
         return false;
@@ -265,7 +265,7 @@ function ledgerDirHasFreshTxt(dir, cutoffMs) {
 }
 /**
  * All three agents-v2 self-attestation conditions. Used only to GRANT PASS to a
- * hermes box that host detection leaves platform-unknown; never to withhold it.
+ * hq-fleet box that host detection leaves platform-unknown; never to withhold it.
  * The exact conjunction of `agents_v2_attested` in `check-hq-hooks.sh`.
  */
 export function agentsV2Attested(opts) {
@@ -286,7 +286,7 @@ export function checkRuntimeProbe(context) {
     const checkId = `${RUNTIME_PROBE_PREFIX}.enforcement`;
     const target = POLICY_TRIGGER_LEDGER_RELPATH;
     const scope = sessionId ? ` for session ${sessionId}` : "";
-    // agents-v2 (hermes) self-attestation. hq doctor leaves the hermes host
+    // agents-v2 (hq-fleet) self-attestation. hq doctor leaves the hq-fleet host
     // platform-unknown and, on an unknown host, the probe would report UNKNOWN
     // below. But the on-box adapter provably wrote the ledger through the same
     // .claude hooks, so grant PASS — and report platform "agents-v2" — when, and

package/dist/lib/doctor/compat.d.ts

@@ -75,12 +75,12 @@ export interface DeriveVerdictOptions {
      */
     requireLedger?: boolean;
     /**
-     * Whether this is an attested agents-v2 (hermes) box: the runtime is
+     * Whether this is an attested agents-v2 (hq-fleet) box: the runtime is
      * agents-v2, `.claude/settings.json` wires the on-box adapter, and a
      * policy-trigger ledger exists (the exact session's when a session id is
      * given; otherwise a ledger fresh within the freshness window). When true,
      * OBSERVED is granted even though the doctor's runtime check did not report
-     * PASS — because hq doctor leaves the hermes host platform-unknown, yet the
+     * PASS — because hq doctor leaves the hq-fleet host platform-unknown, yet the
      * on-box adapter provably wrote the ledger through the same .claude hooks.
      *
      * This is the exact twin of the `agents_v2_attested` override in

package/dist/lib/doctor/compat.js

@@ -81,7 +81,7 @@ export function deriveCheckHqHooksVerdict(doc, options = {}) {
     // ledger" contract.
     const runtimeResult = doc.results.find((result) => result.checkId === RUNTIME_ENFORCEMENT_CHECK_ID);
     let runtime = observeRuntime(runtimeResult?.status, requireLedger);
-    // agents-v2 self-attestation: hq doctor leaves the hermes host
+    // agents-v2 self-attestation: hq doctor leaves the hq-fleet host
     // platform-unknown and so does not report the runtime check as PASS, but the
     // on-box adapter provably wrote the ledger through the same .claude hooks.
     // Grant the identical OBSERVED verdict rather than relaying the host-unknown

package/dist/startup-registration.d.ts

@@ -48,6 +48,8 @@ export interface RegisterRecoveryDeps {
     resolveInstall?: () => {
         packageRoot: string | null;
     };
+    /** Filesystem-free fallback root for the torn window (defaults to stringDerivedPackageRoot). */
+    deriveInstallRoot?: () => string | null;
     lockPath?: () => string;
     waitForSettled?: (args: WaitForInstallTreeSettledArgs) => Promise<WaitForInstallTreeSettledResult>;
     /** node flags to forward to the re-exec child (defaults to process.execArgv). */

package/dist/startup-registration.js

@@ -18,6 +18,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { resolveRunningInstall } from "./utils/version-gate.js";
+import { stringDerivedPackageRoot } from "./utils/hq-roots.js";
 import { updateLockPath } from "./utils/update-lock.js";
 import { classifyModuleNotFound, InstallTreeTornError, waitForInstallTreeSettled, } from "./utils/install-tree-torn.js";
 /**
@@ -122,13 +123,23 @@ export async function registerCommandsWithRecovery(args) {
         return { reexecStatus: child.status ?? 1 };
     }
 }
-/** Resolve the running install's package dir, tolerating any resolver failure. */
+/**
+ * Resolve the running install's package dir for the settle wait's manifest-health
+ * and retired-sibling guards. The on-disk resolver returns null in exactly the
+ * window this recovery targets — the package directory has been renamed aside, so
+ * it cannot be found by reading disk — which would leave readiness keyed on the
+ * single missing file alone and let a premature re-exec run against a still-
+ * incomplete tree. Fall back to the filesystem-free derived root so those guards
+ * stay active while npm is mid-extraction. Tolerates any resolver failure.
+ */
 function resolvePackageRoot(deps) {
+    let root;
     try {
-        return (deps.resolveInstall ?? resolveRunningInstall)().packageRoot;
+        root = (deps.resolveInstall ?? resolveRunningInstall)().packageRoot;
     }
     catch {
-        return null;
+        root = null;
     }
+    return root ?? (deps.deriveInstallRoot ?? stringDerivedPackageRoot)();
 }
 //# sourceMappingURL=startup-registration.js.map

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

@@ -61,6 +61,31 @@ export declare function createPackageRootResolver(options: PackageRootResolverOp
 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

@@ -191,6 +191,73 @@ export function __resetPackageRootCache() {
         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,6 +10,8 @@ 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. */
+export 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
@@ -24,9 +26,21 @@ export type PackageRootResolver = () => string | 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 = {
+    /** 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;
     esmLoaderFrame: boolean;
     code: string;
 };
@@ -42,21 +56,44 @@ export type IncompleteInstallBareDiagnostics = {
     requiringPackage: string;
     requirerDeclaresMissing: false;
 };
+/** The four lexical scopes a NOT-suppressed CJS relative requirer can fall into. */
+export type RelativeRequirerScope = "dist" | "assets" | "outside-root" | "unresolved-root";
 /**
- * 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
+ * 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`.
+ */
+export type IncompleteInstallRelativeDiagnostics = {
+    code: string;
+    relativeSpecifier: true;
+    packageRoot: string;
+    packageRootResolved: boolean;
+    resolver: PackageRootResolverSource;
+    requirerScope: RelativeRequirerScope;
+};
+/**
+ * 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>;
 /**
  * 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 };
+ *   - 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 };
  *   - 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,

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

@@ -63,7 +63,7 @@
 //      `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 { packageRoot, stringDerivedPackageRoot } from "./hq-roots.js";
 import { packageNameOf } from "./install-tree-torn.js";
 import { boundedDiagnosticValue } from "./package-root-diagnostics.js";
 /**
@@ -85,8 +85,16 @@ export const INCOMPLETE_INSTALL_REMEDY = "hq couldn't load part of its own insta
     "`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[\\/]/;
+/**
+ * The Node ESM loader's SOURCE-READ frame — `getSourceSync`/`defaultLoad` in
+ * `node:internal/modules/esm/load`. Requiring the `esm/load` module frame (not
+ * merely any frame under `modules/esm/`) proves the loader was READING the
+ * module's source. An ordinary `fs.openSync`/`readFileSync` ENOENT that merely
+ * ESCAPES a module's EVALUATION runs under `esm/module_job`, never `esm/load`,
+ * so it stays captured rather than suppressed. `load\b` excludes the sibling
+ * `esm/loader` module.
+ */
+const ESM_LOADER_FRAME = /node:internal[\\/]modules[\\/]esm[\\/]load\b/;
 const ROOT_DIAGNOSTIC_BYTES = 256;
 const CODE_DIAGNOSTIC_BYTES = 32;
 // Package names live inside hq-cli's own dependency graph, so their universe is
@@ -95,19 +103,42 @@ const PACKAGE_NAME_DIAGNOSTIC_BYTES = 128;
 /** The `<something>/node_modules/<something>` directory-boundary marker. */
 const NODE_MODULES_SEGMENT = "/node_modules/";
 /**
- * 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.
+ * Resolve the running install's root, trying the authoritative on-disk manifest
+ * walk first and falling back to the filesystem-free string derivation ONLY when
+ * it throws — the torn-tree case, where a concurrent global install has renamed
+ * the package directory aside so packageRoot() cannot read a manifest. Never
+ * throws; reports which strategy answered so a captured event is attributable.
+ *
+ * packageRoot() itself is deliberately NOT widened: resolveBundledAsset() and
+ * isWithinPackage() require a root that exists on disk, and handing them a
+ * string-derived phantom directory would break them. The fallback lives here,
+ * where the only consumer is classification (a lexical prefix test) that needs
+ * no live filesystem.
  */
-function safePackageRoot() {
+function resolvePackageRootWithSource() {
     try {
-        return packageRoot();
+        return { root: packageRoot(), source: "manifest-walk" };
     }
     catch {
-        return null;
+        const derived = stringDerivedPackageRoot();
+        return derived
+            ? { root: derived, source: "string-derivation" }
+            : { root: null, source: "unresolved" };
     }
 }
+/**
+ * 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. When the on-disk walk fails because
+ * a concurrent install renamed the package directory aside, the filesystem-free
+ * string derivation still supplies the root: that is the HQ-CLI-1M repair —
+ * the running install's root must be known even while its directory is
+ * momentarily gone.
+ */
+function safePackageRoot() {
+    return resolvePackageRootWithSource().root;
+}
 /** Call a (possibly injected) resolver without letting it throw. */
 function resolveRootSafely(resolve) {
     try {
@@ -137,16 +168,25 @@ function normalizeForCompare(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.
+ * True when `candidate` lives directly under `<root>/<subdir>/`. Anchored at a
+ * true directory boundary (`<root>` + sep + `<subdir>` + sep) so a sibling such
+ * as `<root>-old/<subdir>/...` can never match. `<subdir>` carries no separator,
+ * so this stays a single lexical prefix test that needs no live filesystem.
  */
-function isUnderNodeModules(candidate, root) {
+function isUnderSubdir(candidate, root, subdir) {
     if (!candidate || !root)
         return false;
-    const prefix = `${normalizeForCompare(root)}/node_modules/`;
+    const prefix = `${normalizeForCompare(root)}/${subdir}/`;
     return normalizeForCompare(candidate).startsWith(prefix);
 }
+/**
+ * True when `candidate` lives under `<root>/node_modules/`. Anchored at a true
+ * directory boundary so a sibling such as `<root>-old/node_modules/...` can
+ * never match.
+ */
+function isUnderNodeModules(candidate, root) {
+    return isUnderSubdir(candidate, root, "node_modules");
+}
 /** The failing specifier from a `Cannot find module '<spec>'` message, or null. */
 function parseMissingSpecifier(message) {
     if (typeof message !== "string")
@@ -392,13 +432,87 @@ function bareSpecifierCaptureContext(err, resolvePackageRoot, fileSystem) {
         },
     };
 }
+/**
+ * Classify a NOT-suppressed CJS relative requirer LEXICALLY against the resolved
+ * root — never emitting the path itself, only one of four fixed values. A
+ * requirer under `<root>/node_modules/` with a resolved root is ALWAYS suppressed
+ * upstream, so that scope is unreachable here and deliberately absent from the
+ * enum.
+ *   - root null (both resolvers failed)  → 'unresolved-root'
+ *   - under `<root>/dist/`               → 'dist'   (hq-cli's own shipped output)
+ *   - under `<root>/assets/`             → 'assets' (hq-cli's own bundled assets)
+ *   - anything else (a user project, a `<root>-old` sibling, …) → 'outside-root'
+ */
+function classifyRelativeRequirerScope(requiringFile, root) {
+    if (!root)
+        return "unresolved-root";
+    if (isUnderSubdir(requiringFile, root, "dist"))
+        return "dist";
+    if (isUnderSubdir(requiringFile, root, "assets"))
+        return "assets";
+    return "outside-root";
+}
+/**
+ * When a CJS RELATIVE-specifier miss (HQ-CLI-1N's shape) 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 — return a bounded `incomplete_install` block recording a
+ * four-value lexical scope so the next occurrence is attributable instead of
+ * bare; otherwise undefined. The suppression decision is delegated to
+ * incompleteInstallMessage against the SAME injected resolver, so a suppressed
+ * relative miss (requirer under `<root>/node_modules/` with a resolved root) is
+ * never double-attributed here. Never throws; never emits a path or the specifier.
+ */
+function relativeSpecifierCaptureContext(err, resolvePackageRoot, fileSystem) {
+    if (err === null || typeof err !== "object")
+        return undefined;
+    const record = err;
+    if (record.code !== "MODULE_NOT_FOUND")
+        return undefined;
+    const requireStack = record.requireStack;
+    if (!Array.isArray(requireStack) || typeof requireStack[0] !== "string")
+        return undefined;
+    const requiringFile = requireStack[0];
+    const specifier = parseMissingSpecifier(record.message);
+    if (specifier === null || !RELATIVE_SPECIFIER.test(specifier))
+        return undefined;
+    // Suppressed (requirer under <root>/node_modules with a resolved root) →
+    // printed-and-skipped, never captured. Delegated to the classifier against the
+    // SAME resolver so the two decisions can never diverge and nothing that would
+    // be suppressed is ever double-attributed.
+    if (incompleteInstallMessage(err, resolvePackageRoot, readFileFrom(fileSystem)) !== null) {
+        return undefined;
+    }
+    // Not suppressed: record which resolver answered and the lexical requirer scope.
+    const resolution = resolvePackageRoot === safePackageRoot
+        ? resolvePackageRootWithSource()
+        : {
+            root: resolveRootSafely(resolvePackageRoot),
+            source: "injected",
+        };
+    const root = resolution.root;
+    return {
+        incomplete_install: {
+            code: "MODULE_NOT_FOUND",
+            relativeSpecifier: true,
+            packageRoot: boundedDiagnosticValue(root ?? "<unresolved>", ROOT_DIAGNOSTIC_BYTES),
+            packageRootResolved: root !== null,
+            resolver: resolution.source,
+            requirerScope: classifyRelativeRequirerScope(requiringFile, root),
+        },
+    };
+}
 /**
  * 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 };
+ *   - 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 };
  *   - 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,
@@ -413,7 +527,11 @@ export function incompleteInstallCaptureContext(err, resolvePackageRoot = safePa
     const bare = bareSpecifierCaptureContext(err, resolvePackageRoot, fileSystem);
     if (bare)
         return bare;
-    // (B) HQ-CLI-1M — the path-less esm-loader ENOENT, unchanged.
+    // (B) HQ-CLI-1N — the not-suppressed CJS relative-sibling miss, made attributable.
+    const relative = relativeSpecifierCaptureContext(err, resolvePackageRoot, fileSystem);
+    if (relative)
+        return relative;
+    // (C) HQ-CLI-1M — the path-less esm-loader ENOENT, unchanged.
     if (!isEsmLoaderEnoent(err))
         return undefined;
     // Only instrument what we did NOT already confidently suppress: a path under
@@ -422,32 +540,40 @@ export function incompleteInstallCaptureContext(err, resolvePackageRoot = safePa
         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),
-        },
+    // The default resolver knows which strategy answered (manifest walk vs the
+    // string derivation that survives a torn tree); an injected resolver is
+    // opaque, so it is recorded as "injected" and its return used as the root.
+    const resolution = resolvePackageRoot === safePackageRoot
+        ? resolvePackageRootWithSource()
+        : {
+            root: resolveRootSafely(resolvePackageRoot),
+            source: "injected",
+        };
+    const root = resolution.root;
+    const diagnostics = {
+        packageRoot: boundedDiagnosticValue(root ?? "<unresolved>", ROOT_DIAGNOSTIC_BYTES),
+        packageRootResolved: root !== null,
+        resolver: resolution.source,
+        esmLoaderFrame: true,
+        code: boundedDiagnosticValue(code, CODE_DIAGNOSTIC_BYTES),
     };
+    // Report the existence booleans ONLY when a root was resolved. Reported for an
+    // unresolved root they were uninitialised `false`s indistinguishable from
+    // "resolved but missing" — the instrumentation defect the prior fix shipped.
+    if (root !== null) {
+        diagnostics.packageJsonExists = safeExistsSync(fileSystem, path.join(root, "package.json"));
+        diagnostics.nodeModulesExists = safeExistsSync(fileSystem, path.join(root, "node_modules"));
+    }
+    return { incomplete_install: diagnostics };
+}
+/** existsSync that never throws — any filesystem error reads as "absent". */
+function safeExistsSync(fileSystem, target) {
+    try {
+        return fileSystem.existsSync(target);
+    }
+    catch {
+        return false;
+    }
 }
 //# sourceMappingURL=incomplete-install-error.js.map

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

@@ -29,8 +29,12 @@
  * ../startup-registration.ts; version-gate.ts / self-update.ts / update-lock.ts
  * are only READ (their exported symbols), never modified.
  */
-/** The two loader-error `code`s that mean "a module could not be resolved". */
-export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND";
+/**
+ * The loader-error `code`s recovery classifies. The first two mean "a module
+ * could not be resolved"; `ENOENT` is the esm-loader dialect where a module was
+ * present at resolve and gone at read (HQ-CLI-1M) — see {@link ModuleErrorDialect}.
+ */
+export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "ENOENT";
 /**
  * The closed set of resolution-failure dialects, verified on Node v22.23.1 (the
  * @sentry/node import-in-the-middle hook does not change the shapes):
@@ -42,10 +46,13 @@ export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND";
  *                    '<abs>'` + `requireStack`.
  *   - `cjs-package`: CJS require of a bare specifier — `Cannot find module
  *                    '<name>'` + `requireStack`.
+ *   - `esm-enoent`:  ESM loader ENOENT (HQ-CLI-1M) — a module present at RESOLVE
+ *                    and gone at READ, so getSourceSync/openSync raises ENOENT
+ *                    (not ERR_MODULE_NOT_FOUND). `err.path` is the vanished file.
  *   - `unknown`:     a module-not-found whose message did not parse; recovery
  *                    still waits on the lock / retired-dir / quiet signals.
  */
-export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "unknown";
+export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "esm-enoent" | "unknown";
 /**
  * The missing thing, re-resolvable by the readiness probe:
  *   - `path`:    an absolute filesystem path (a `.js` file, or a package dir).
@@ -82,10 +89,11 @@ export declare function packageNameOf(specifier: string): string;
 /**
  * Classify a thrown value as a module-resolution failure and extract the missing
  * target, or return `null` for anything that is not one. The decision is
- * STRUCTURAL: `err.code` must be exactly `ERR_MODULE_NOT_FOUND` or
- * `MODULE_NOT_FOUND` — no argv, env, or free text is ever consulted, and any
- * other error (including an import-time throw of another class) returns `null`
- * so it is rethrown to the existing boundary unchanged.
+ * STRUCTURAL: `err.code` must be exactly `ERR_MODULE_NOT_FOUND`,
+ * `MODULE_NOT_FOUND`, or — for the esm-loader ENOENT dialect — `ENOENT` under
+ * the full conjunction below. No argv, env, or free text is ever consulted, and
+ * any other error (including an import-time throw of another class) returns
+ * `null` so it is rethrown to the existing boundary unchanged.
  */
 export declare function classifyModuleNotFound(err: unknown): ClassifiedModuleError | null;
 /** The filesystem surface the probe and wait use, injectable for hermetic tests. */

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

@@ -42,6 +42,16 @@ const PACKAGE_ROOT_BYTES = 256;
 const ESM_PACKAGE_RE = /^Cannot find package '([^']+)' imported from (.+)$/s;
 const CJS_MODULE_RE = /^Cannot find module '([^']+)'/s;
 const ESM_MODULE_IMPORTED_RE = /^Cannot find module '([^']+)' imported from (.+)$/s;
+/**
+ * The Node ESM loader's SOURCE-READ frame — `getSourceSync`/`defaultLoad` in
+ * `node:internal/modules/esm/load`. Requiring the `esm/load` module frame (not
+ * merely any frame under `modules/esm/`) is what proves the loader was READING
+ * the module's source, so an ordinary `fs.openSync`/`readFileSync` ENOENT that
+ * merely ESCAPES a module's EVALUATION — which runs under `esm/module_job`,
+ * never `esm/load` — is NOT misclassified as a torn install and does not trigger
+ * the settle wait. `load\b` also excludes the sibling `esm/loader` module.
+ */
+const ESM_LOADER_FRAME = /node:internal[\\/]modules[\\/]esm[\\/]load\b/;
 /**
  * Reduce a bare specifier to its PACKAGE name: `@scope/name/sub` → `@scope/name`,
  * `name/sub` → `name`, `name` → `name`. This is the unit the readiness probe
@@ -57,16 +67,40 @@ export function packageNameOf(specifier) {
 /**
  * Classify a thrown value as a module-resolution failure and extract the missing
  * target, or return `null` for anything that is not one. The decision is
- * STRUCTURAL: `err.code` must be exactly `ERR_MODULE_NOT_FOUND` or
- * `MODULE_NOT_FOUND` — no argv, env, or free text is ever consulted, and any
- * other error (including an import-time throw of another class) returns `null`
- * so it is rethrown to the existing boundary unchanged.
+ * STRUCTURAL: `err.code` must be exactly `ERR_MODULE_NOT_FOUND`,
+ * `MODULE_NOT_FOUND`, or — for the esm-loader ENOENT dialect — `ENOENT` under
+ * the full conjunction below. No argv, env, or free text is ever consulted, and
+ * any other error (including an import-time throw of another class) returns
+ * `null` so it is rethrown to the existing boundary unchanged.
  */
 export function classifyModuleNotFound(err) {
     if (err === null || typeof err !== "object")
         return null;
     const record = err;
     const code = record.code;
+    // (0) esm-loader ENOENT (HQ-CLI-1M): a module present at RESOLVE and gone at
+    // READ, so Node's ESM loader raises ENOENT from getSourceSync/openSync rather
+    // than ERR_MODULE_NOT_FOUND at resolve. Gated on the FULL conjunction — code
+    // ENOENT AND syscall 'open' AND an esm-loader stack frame AND a string path —
+    // so an ordinary fs.readFileSync/openSync ENOENT written by hq's own code (no
+    // loader frame) cannot enter it. The vanished file IS the re-resolvable target
+    // the settle wait polls; recovery then waits and re-execs exactly as for the
+    // other dialects.
+    if (code === "ENOENT") {
+        if (record.syscall === "open" &&
+            typeof record.path === "string" &&
+            typeof record.stack === "string" &&
+            ESM_LOADER_FRAME.test(record.stack)) {
+            return {
+                code,
+                dialect: "esm-enoent",
+                specifier: record.path,
+                importer: "",
+                target: { kind: "path", path: record.path },
+            };
+        }
+        return null;
+    }
     if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND")
         return null;
     const message = typeof record.message === "string" ? record.message : "";

package/dist/utils/people.d.ts

@@ -22,6 +22,9 @@ export interface PersonRecord {
     name: string;
     /** Contact email, when recorded. */
     email?: string;
+    /** Canonical identity from authoritative company membership, never local YAML. */
+    personUid?: string;
+    companyUid?: string;
     /** "internal" (team member) | "external" (client, vendor, …). */
     type?: string;
     /** Role/title inside (or relative to) the company. */

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

@@ -31,11 +31,6 @@ export interface EntitlementEntry {
 export interface EntitlementListResponse {
     entitlements: EntitlementEntry[];
 }
-export interface EntitlementCheckResponse {
-    entitled: boolean;
-    tier?: string;
-    expires_at?: string;
-}
 export interface DownloadResponse {
     url: string;
     sha256: string;
@@ -59,7 +54,6 @@ export declare class RegistryClient {
     }): Promise<PackageListResponse>;
     getPackage(slug: string): Promise<PackageResponse>;
     getMyEntitlements(): Promise<EntitlementListResponse>;
-    checkEntitlement(slug: string): Promise<EntitlementCheckResponse>;
     getDownloadUrl(slug: string, version?: string): Promise<DownloadResponse>;
 }
 //# sourceMappingURL=registry-client.d.ts.map

package/dist/utils/registry-client.js

@@ -88,9 +88,6 @@ export class RegistryClient {
             auth: true,
         });
     }
-    async checkEntitlement(slug) {
-        return this.request('GET', `/entitlements/${encodeURIComponent(slug)}`, { auth: true });
-    }
     async getDownloadUrl(slug, version) {
         const params = new URLSearchParams();
         if (version)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.109.6",
-  "description": "HQ by Indigo management CLI — modules and cloud sync",
+  "version": "5.109.8",
+  "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
     "hq": "dist/index.js",
@@ -26,7 +26,8 @@
     "coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary",
     "vitest": "vitest",
     "clean": "rm -rf dist",
-    "prepare": "husky || true"
+    "prepare": "husky || true",
+    "check:no-hermes": "bash scripts/check-no-hermes.sh"
   },
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",