@indigoai-us/hq-cli 5.345.5 → 5.345.7

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [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.
 

package/dist/commands/login.js

@@ -9,7 +9,7 @@ import { cognitoConfigForLoginProvider } from '../utils/login-provider.js';
 import * as readline from "node:readline/promises";
 import { listActiveMembershipCompanies } from "../lib/mesh/api.js";
 import { retainUsageAttributionForPerson, setDefaultCompany } from "../lib/work-context/config.js";
-import { personUidFromTokens } from "../lib/work-context/person-identity.js";
+import { cognitoSubFromTokens } from "../lib/work-context/person-identity.js";
 import { ensureDefaultCompany } from "../lib/work-context/default-company.js";
 import { workContextRoot } from "../lib/work-context/paths.js";
 function peekIdToken(idToken) {
@@ -66,7 +66,7 @@ export function registerLoginCommand(program) {
         try {
             // The usage-attribution opt-in belongs to the person who gave it. A
             // different (or unknown) account signing in on this OS user drops it.
-            retainUsageAttributionForPerson(personUidFromTokens(loadCachedTokens()), {
+            retainUsageAttributionForPerson(cognitoSubFromTokens(loadCachedTokens()), {
                 root: workContextRoot(),
             });
         }

package/dist/commands/mesh.js

@@ -20,7 +20,7 @@ import { buildPreflightFixtures } from "../lib/work-context/preflight-contract.j
 import { createCandidatesFetcher, createMigratePoster, createOrganizePoster, createWorkSessionDeliverer, fetchCompanyLive, formatCompanyLiveTable, openMeshTransport, probeMigrationCapabilityForMemberships, requireToken, } from "../lib/mesh/client.js";
 import { clearDefaultCompany, effectiveUsageAttribution, isDefaultCompanyDisabled, readDeviceConfig, recordMigrationCapabilitySnapshot, setRepairHeldWithDefault, setDefaultCompany, setUsageAttribution, } from "../lib/work-context/config.js";
 import { ensureDefaultCompany } from "../lib/work-context/default-company.js";
-import { personUidFromTokens } from "../lib/work-context/person-identity.js";
+import { cognitoSubFromTokens } from "../lib/work-context/person-identity.js";
 import { DefaultCompanyUnavailableError, WorkContextError, } from "../lib/work-context/errors.js";
 import { isValidSessionId } from "../lib/mesh/live/session-identity.js";
 import { flushSessionEvents } from "../lib/mesh/live/flush.js";
@@ -1212,17 +1212,17 @@ export async function askYesNo(question, io = {}) {
         rl.close();
     }
 }
-/** The signed-in person's prs_ uid from the cached Cognito session, or null. */
-function currentPersonUid() {
+/** The signed-in person's Cognito sub from the cached session, or null. */
+function currentCognitoSub() {
     try {
-        return personUidFromTokens(loadCachedTokens());
+        return cognitoSubFromTokens(loadCachedTokens());
     }
     catch {
         return null;
     }
 }
-function usageAttributionJson(cfg, personUid) {
-    const effective = effectiveUsageAttribution(cfg, personUid);
+function usageAttributionJson(cfg, cognitoSub) {
+    const effective = effectiveUsageAttribution(cfg, cognitoSub);
     return { countUsage: effective !== null, usageAttribution: effective };
 }
 async function runContextDefaultGet(opts) {
@@ -1244,7 +1244,7 @@ async function runContextDefaultGet(opts) {
             needsChoice: !current && !disabled && memberships.length > 1,
             memberships,
             repairHeldWithDefault: cfg.repairHeldWithDefault === true,
-            ...usageAttributionJson(cfg, currentPersonUid()),
+            ...usageAttributionJson(cfg, currentCognitoSub()),
         }, null, 2));
         return;
     }
@@ -1257,7 +1257,7 @@ async function runContextDefaultGet(opts) {
         return;
     }
     console.log(`Default company: ${current.slug}${current.uid ? ` (${current.uid})` : ""} enabled=${current.enabled} source=${source}`);
-    console.log(effectiveUsageAttribution(cfg, currentPersonUid())
+    console.log(effectiveUsageAttribution(cfg, currentCognitoSub())
         ? usageCountedLine(current.slug)
         : usageNotCountedLine(current.slug));
 }
@@ -1269,8 +1269,8 @@ async function runContextDefaultSet(slug, opts, promptDeps = {}) {
         : opts.countUsage === false
             ? "opt-out"
             : "keep-if-same";
-    const personUid = currentPersonUid();
-    const priorOptIn = effectiveUsageAttribution(readDeviceConfig({ root }), personUid);
+    const cognitoSub = currentCognitoSub();
+    const priorOptIn = effectiveUsageAttribution(readDeviceConfig({ root }), cognitoSub);
     let token;
     try {
         token = await requireToken();
@@ -1311,7 +1311,7 @@ async function runContextDefaultSet(slug, opts, promptDeps = {}) {
             root,
             migrationCapability,
             usageAttribution: usageChoice,
-            personUid,
+            cognitoSub,
             validateMembership: async (candidate) => {
                 if (!token) {
                     throw new DefaultCompanyUnavailableError(`Cannot verify membership for company "${candidate}" (no Cognito session; offline or not logged in)`);
@@ -1340,7 +1340,7 @@ async function runContextDefaultSet(slug, opts, promptDeps = {}) {
                 ok: true,
                 config: configured,
                 migrationWarning,
-                ...usageAttributionJson(configured, personUid),
+                ...usageAttributionJson(configured, cognitoSub),
             }, null, 2));
             return;
         }
@@ -1352,8 +1352,8 @@ async function runContextDefaultSet(slug, opts, promptDeps = {}) {
             (() => isInteractiveTerminal()))();
         if (usageChoice === "keep-if-same" &&
             interactive &&
-            personUid &&
-            !effectiveUsageAttribution(configured, personUid) &&
+            cognitoSub &&
+            !effectiveUsageAttribution(configured, cognitoSub) &&
             stored?.uid?.startsWith("cmp_")) {
             console.error(usageOptInExplainer(company));
             let yes = false;
@@ -1364,9 +1364,9 @@ async function runContextDefaultSet(slug, opts, promptDeps = {}) {
                 yes = false;
             }
             if (yes)
-                configured = setUsageAttribution({ companyUid: stored.uid, personUid }, { root });
+                configured = setUsageAttribution({ companyUid: stored.uid, cognitoSub }, { root });
         }
-        console.log(effectiveUsageAttribution(configured, personUid)
+        console.log(effectiveUsageAttribution(configured, cognitoSub)
             ? usageCountedLine(company)
             : usageNotCountedLine(company));
         if (migrationWarning)
@@ -1503,7 +1503,7 @@ async function runContextDefaultClear(opts) {
     const hadOptIn = readDeviceConfig({ root }).usageAttribution !== undefined;
     const cfg = clearDefaultCompany({ root });
     if (opts.json) {
-        console.log(JSON.stringify({ ok: true, config: cfg, ...usageAttributionJson(cfg, currentPersonUid()) }, null, 2));
+        console.log(JSON.stringify({ ok: true, config: cfg, ...usageAttributionJson(cfg, currentCognitoSub()) }, null, 2));
         return;
     }
     console.log("Default company cleared.");

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/lib/work-context/config.d.ts

@@ -56,15 +56,16 @@ export interface UsageAttributionOptIn {
     mode: "default-company";
     companyUid: string;
     /**
-     * The signed-in person who consented: the `custom:entityUid` claim (prs_...)
-     * of the cached Cognito person session. Consent never carries to another
-     * account on the same OS user.
+     * The signed-in person who consented: the Cognito `sub` claim of the cached
+     * person session. Consent never carries to another account on the same OS
+     * user. Older records that carry only `personUid` are treated as not opted
+     * in (fail closed).
      */
-    personUid: string;
+    cognitoSub: string;
     optedInAt: string;
 }
-/** A person principal uid, as carried in the `custom:entityUid` token claim. */
-export declare function isPersonUid(value: unknown): value is string;
+/** A Cognito `sub` claim: any non-empty string (after trimming). */
+export declare function isCognitoSub(value: unknown): value is string;
 /** How `setDefaultCompany` treats the usage-attribution opt-in. */
 export type UsageAttributionChoice = 
 /** Write an opt-in for the newly set company (requires its uid). */
@@ -113,10 +114,10 @@ export interface DeviceConfigDeps {
      */
     usageAttribution?: UsageAttributionChoice;
     /**
-     * The signed-in person (prs_...). Required to write an opt-in; an existing
+     * The signed-in person (Cognito `sub`). Required to write an opt-in; an existing
      * opt-in is kept only when it was given by this person.
      */
-    personUid?: string | null;
+    cognitoSub?: string | null;
 }
 /** Acquire an interprocess config lock; exported for direct lock regression tests. */
 export declare function acquireDeviceConfigLock(root: string, options?: {
@@ -130,7 +131,7 @@ export declare function sanitizeUsageAttribution(raw: unknown): UsageAttribution
  * default company, and given by the signed-in person. Mirrors the hq-cloud
  * reader. No signed-in person means no opt-in.
  */
-export declare function effectiveUsageAttribution(cfg: Pick<WorkContextDeviceConfig, "defaultCompany" | "usageAttribution">, personUid: string | null | undefined): UsageAttributionOptIn | null;
+export declare function effectiveUsageAttribution(cfg: Pick<WorkContextDeviceConfig, "defaultCompany" | "usageAttribution">, cognitoSub: string | null | undefined): UsageAttributionOptIn | null;
 /** Injection points for assertSafeConfigPath (tests only). */
 export interface SafeConfigPathIo {
     platform?: NodeJS.Platform;
@@ -162,14 +163,14 @@ export declare function setDefaultCompany(slug: string, deps: DeviceConfigDeps):
  */
 export declare function setUsageAttribution(optIn: {
     companyUid: string;
-    personUid: string;
+    cognitoSub: string;
 } | null, deps: Pick<DeviceConfigDeps, "root" | "now">): WorkContextDeviceConfig;
 /**
- * Drop the usage-attribution opt-in unless it was given by `personUid`. Called
+ * Drop the usage-attribution opt-in unless it was given by `cognitoSub`. Called
  * on login (identity may have changed) and logout (null: always drop). A
  * config with no opt-in, or one already matching, is left untouched.
  */
-export declare function retainUsageAttributionForPerson(personUid: string | null | undefined, deps: Pick<DeviceConfigDeps, "root" | "now">): boolean;
+export declare function retainUsageAttributionForPerson(cognitoSub: string | null | undefined, deps: Pick<DeviceConfigDeps, "root" | "now">): boolean;
 export declare function clearDefaultCompany(deps: DeviceConfigDeps): WorkContextDeviceConfig;
 /**
  * Read the persisted company mapping for a repo identity key (gap 4).

package/dist/lib/work-context/config.js

@@ -9,9 +9,9 @@ import { DefaultCompanyUnavailableError, UnsafeConfigPathError, WorkContextError
 import { workContextConfigPath } from "./paths.js";
 import { assertWindowsOwnerOnlyAcl } from "./windows-acl.js";
 const DEVICE_CONFIG_SCHEMA_VERSION = 1;
-/** A person principal uid, as carried in the `custom:entityUid` token claim. */
-export function isPersonUid(value) {
-    return typeof value === "string" && /^prs_[A-Za-z0-9]+$/.test(value);
+/** A Cognito `sub` claim: any non-empty string (after trimming). */
+export function isCognitoSub(value) {
+    return typeof value === "string" && value.trim().length > 0;
 }
 const CONFIG_LOCK_TIMEOUT_MS = 5_000;
 const CONFIG_LOCK_RETRY_MS = 10;
@@ -158,24 +158,24 @@ export function sanitizeUsageAttribution(raw) {
     if (v.mode !== "default-company")
         return undefined;
     const companyUid = typeof v.companyUid === "string" ? v.companyUid.trim() : "";
-    const personUid = typeof v.personUid === "string" ? v.personUid.trim() : "";
+    const cognitoSub = typeof v.cognitoSub === "string" ? v.cognitoSub.trim() : "";
     const optedInAt = typeof v.optedInAt === "string" ? v.optedInAt.trim() : "";
     if (!companyUid.startsWith("cmp_") ||
-        !isPersonUid(personUid) ||
+        !isCognitoSub(cognitoSub) ||
         !optedInAt ||
         !Number.isFinite(Date.parse(optedInAt))) {
         return undefined;
     }
-    return { mode: "default-company", companyUid, personUid, optedInAt };
+    return { mode: "default-company", companyUid, cognitoSub, optedInAt };
 }
 /**
  * The opt-in that is in effect: present, for the uid of the current enabled
  * default company, and given by the signed-in person. Mirrors the hq-cloud
  * reader. No signed-in person means no opt-in.
  */
-export function effectiveUsageAttribution(cfg, personUid) {
+export function effectiveUsageAttribution(cfg, cognitoSub) {
     const opt = cfg.usageAttribution;
-    if (!opt || !isPersonUid(personUid) || opt.personUid !== personUid)
+    if (!opt || !isCognitoSub(cognitoSub) || opt.cognitoSub !== cognitoSub)
         return null;
     const def = cfg.defaultCompany;
     if (!opt || !def || def.enabled !== true || def.source === "disabled")
@@ -332,27 +332,27 @@ export async function setDefaultCompany(slug, deps) {
             defaultCompany.uid = resolvedUid;
         const choice = deps.usageAttribution ?? "keep-if-same";
         let usageAttribution;
-        const personUid = isPersonUid(deps.personUid) ? deps.personUid : undefined;
+        const cognitoSub = isCognitoSub(deps.cognitoSub) ? deps.cognitoSub : undefined;
         if (choice === "opt-in") {
             if (!resolvedUid?.startsWith("cmp_")) {
                 throw new WorkContextError("UsageAttributionUnavailable", `Cannot count usage toward "${trimmed}": its company uid is unknown`);
             }
-            if (!personUid) {
+            if (!cognitoSub) {
                 throw new WorkContextError("UsageAttributionUnavailable", `Cannot count usage toward "${trimmed}": the signed-in person could not be determined`);
             }
             usageAttribution = {
                 mode: "default-company",
                 companyUid: resolvedUid,
-                personUid,
+                cognitoSub,
                 optedInAt: now().toISOString(),
             };
         }
         else if (choice === "keep-if-same") {
             usageAttribution =
                 resolvedUid &&
-                    personUid &&
+                    cognitoSub &&
                     prior.usageAttribution?.companyUid === resolvedUid &&
-                    prior.usageAttribution.personUid === personUid
+                    prior.usageAttribution.cognitoSub === cognitoSub
                     ? prior.usageAttribution
                     : undefined;
         }
@@ -388,13 +388,13 @@ export function setUsageAttribution(optIn, deps) {
                 def.source !== "chosen" ||
                 !def.uid?.startsWith("cmp_") ||
                 def.uid !== optIn.companyUid ||
-                !isPersonUid(optIn.personUid)) {
+                !isCognitoSub(optIn.cognitoSub)) {
                 throw new WorkContextError("UsageAttributionUnavailable", "Usage can only be counted toward a default company you chose on this device");
             }
             usageAttribution = {
                 mode: "default-company",
                 companyUid: def.uid,
-                personUid: optIn.personUid,
+                cognitoSub: optIn.cognitoSub,
                 optedInAt: now().toISOString(),
             };
         }
@@ -413,11 +413,11 @@ export function setUsageAttribution(optIn, deps) {
     });
 }
 /**
- * Drop the usage-attribution opt-in unless it was given by `personUid`. Called
+ * Drop the usage-attribution opt-in unless it was given by `cognitoSub`. Called
  * on login (identity may have changed) and logout (null: always drop). A
  * config with no opt-in, or one already matching, is left untouched.
  */
-export function retainUsageAttributionForPerson(personUid, deps) {
+export function retainUsageAttributionForPerson(cognitoSub, deps) {
     if (!fs.existsSync(workContextConfigPath(deps.root)))
         return false;
     return withDeviceConfigLock(deps.root, () => {
@@ -425,7 +425,7 @@ export function retainUsageAttributionForPerson(personUid, deps) {
         const opt = prior.usageAttribution;
         if (!opt)
             return false;
-        if (isPersonUid(personUid) && opt.personUid === personUid)
+        if (isCognitoSub(cognitoSub) && opt.cognitoSub === cognitoSub)
             return false;
         const now = deps.now ?? (() => new Date());
         const { usageAttribution: _dropped, ...rest } = prior;

package/dist/lib/work-context/person-identity.d.ts

@@ -2,14 +2,18 @@
  * Signed-in person identity for the usage-attribution opt-in.
  *
  * Source: the cached Cognito person session (`~/.hq/cognito-tokens.json`,
- * read through `loadCachedTokens`). The person uid is the `custom:entityUid`
- * claim of the ID token (falling back to the access token), and only a
- * `prs_` value counts. Agent (`agt_`) or unknown identities return null, so
- * no opt-in is written or kept for them. Claims are read without
- * verification; this decides only whether local consent belongs to the
- * account that is signed in, never authorization.
+ * read through `loadCachedTokens`). The identity key is the Cognito `sub`
+ * claim of the ID token (falling back to the access token); it must be a
+ * non-empty string. Human sessions carry no `custom:entityUid` claim (hq-pro
+ * sets it only on agent and outpost machine identities), so it is not used.
+ * An agent or outpost session has its own Cognito user and therefore a
+ * different `sub`, so it could never match a person's opt-in; a token that
+ * names a machine identity (`custom:entityType` agent/outpost, or a
+ * non-`prs_` `custom:entityUid`) is refused outright. Claims are read
+ * without verification; this decides only whether local consent belongs to
+ * the account that is signed in, never authorization.
  */
-export declare function personUidFromTokens(tokens: {
+export declare function cognitoSubFromTokens(tokens: {
     idToken?: string;
     accessToken?: string;
 } | null | undefined): string | null;

package/dist/lib/work-context/person-identity.js

@@ -2,14 +2,18 @@
  * Signed-in person identity for the usage-attribution opt-in.
  *
  * Source: the cached Cognito person session (`~/.hq/cognito-tokens.json`,
- * read through `loadCachedTokens`). The person uid is the `custom:entityUid`
- * claim of the ID token (falling back to the access token), and only a
- * `prs_` value counts. Agent (`agt_`) or unknown identities return null, so
- * no opt-in is written or kept for them. Claims are read without
- * verification; this decides only whether local consent belongs to the
- * account that is signed in, never authorization.
+ * read through `loadCachedTokens`). The identity key is the Cognito `sub`
+ * claim of the ID token (falling back to the access token); it must be a
+ * non-empty string. Human sessions carry no `custom:entityUid` claim (hq-pro
+ * sets it only on agent and outpost machine identities), so it is not used.
+ * An agent or outpost session has its own Cognito user and therefore a
+ * different `sub`, so it could never match a person's opt-in; a token that
+ * names a machine identity (`custom:entityType` agent/outpost, or a
+ * non-`prs_` `custom:entityUid`) is refused outright. Claims are read
+ * without verification; this decides only whether local consent belongs to
+ * the account that is signed in, never authorization.
  */
-import { isPersonUid } from "./config.js";
+import { isCognitoSub } from "./config.js";
 function claimsOf(token) {
     if (typeof token !== "string")
         return null;
@@ -26,13 +30,22 @@ function claimsOf(token) {
         return null;
     }
 }
-export function personUidFromTokens(tokens) {
+export function cognitoSubFromTokens(tokens) {
     if (!tokens)
         return null;
     for (const token of [tokens.idToken, tokens.accessToken]) {
-        const uid = claimsOf(token)?.["custom:entityUid"];
-        if (isPersonUid(uid))
-            return uid;
+        const claims = claimsOf(token);
+        if (!claims)
+            continue;
+        const entityType = claims["custom:entityType"];
+        const entityUid = claims["custom:entityUid"];
+        if (entityType === "agent" || entityType === "outpost")
+            return null;
+        if (typeof entityUid === "string" && !entityUid.startsWith("prs_"))
+            return null;
+        const sub = claims.sub;
+        if (isCognitoSub(sub))
+            return sub.trim();
     }
     return null;
 }

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.5",
+  "version": "5.345.7",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {