@aexol/spectral 0.9.205 → 0.9.206

package/dist/agent/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/agent/agents.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AACrD,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAC/C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;IAChD,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EAyCtC,CAAC;AA0DF,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAO3E;AACD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,yEAAyE;IACzE,YAAY,EAAE,IAAI,CAAC;IACnB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG;IACF,YAAY,EAAE,KAAK,CAAC;IACpB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA6EnC;AAkBD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,oBAAoB,CAmBtB;AACD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,UAAmB,EAC1B,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,GAAG,IAAI,CAepB;AACD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACvC,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,GAAG,IAAI,CAgBpB;AACD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,YAAY,EAAE,IAAI,CAChB,WAAW,EACX,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAC7D,GAAG,IAAI,GACP,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,IAAI,CACT,WAAW,EACX,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAC7D,GAAG,IAAI,GACP,MAAM,CAgBR"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/agent/agents.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AACrD,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAC/C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;IAChD,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EAmDtC,CAAC;AA0DF,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAO3E;AACD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,yEAAyE;IACzE,YAAY,EAAE,IAAI,CAAC;IACnB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG;IACF,YAAY,EAAE,KAAK,CAAC;IACpB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA6EnC;AAkBD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,oBAAoB,CAmBtB;AACD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,UAAmB,EAC1B,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,GAAG,IAAI,CAepB;AACD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACvC,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,GAAG,IAAI,CAgBpB;AACD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,YAAY,EAAE,IAAI,CAChB,WAAW,EACX,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAC7D,GAAG,IAAI,GACP,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,IAAI,CACT,WAAW,EACX,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAC7D,GAAG,IAAI,GACP,MAAM,CAgBR"}

package/dist/agent/agents.js

@@ -6,9 +6,9 @@ import { classifyGraphqlError, createBackendClient, graphqlErrorMessage, scalars
 export const SYSTEM_AGENTS = [
     {
         name: "ghost",
-        description: "Built-in orchestrator primary agent that delegates work to researcher, executor, and reviewer subagents.",
+        description: "Built-in orchestrator primary agent that delegates work to researcher, executor, reviewer, and fork subagents.",
         mode: "primary",
-        systemPrompt: "You are ghost, the built-in system orchestrator. Plan the work, then delegate by calling the `subagent` tool with one of your subagents, then integrate the results into a coherent outcome.\n\nYour subagents (call them via the `subagent` tool, e.g. subagent(agent=\"researcher\", task=\"...\")):\n- `researcher` — investigate the codebase, read code and documentation, and report precise, cited findings without making changes.\n- `executor` — implement the requested changes minimally and safely, run verification, and report exactly what changed with evidence.\n- `reviewer` — review proposed or implemented changes for correctness, edge cases, security, and consistency with the codebase.\n\nDelegate the actual work to the appropriate subagent instead of doing it yourself; use `researcher` for research/investigation, `executor` for implementation, and `reviewer` for review.",
+        systemPrompt: "You are ghost, the built-in system orchestrator. Plan the work, then delegate by calling the `subagent` tool with one of your subagents, then integrate the results into a coherent outcome.\n\nYour subagents (call them via the `subagent` tool, e.g. subagent(agent=\"researcher\", task=\"...\")):\n- `researcher` — investigate the codebase, read code and documentation, and report precise, cited findings without making changes.\n- `executor` — implement the requested changes minimally and safely, run verification, and report exactly what changed with evidence.\n- `reviewer` — review proposed or implemented changes for correctness, edge cases, security, and consistency with the codebase.\n- `fork` — a generalist worker with the same broad capabilities as the main thread; give it a self-contained task and it carries it end-to-end.\n\nTry to delegate most of the work to your subagents: use `researcher` for research/investigation, `executor` for implementation, `reviewer` for review, and `fork` for generalist tasks that don't fit the other three.",
         source: "system",
         filePath: "system:ghost",
     },
@@ -36,6 +36,14 @@ export const SYSTEM_AGENTS = [
         source: "system",
         filePath: "system:reviewer",
     },
+    {
+        name: "fork",
+        description: "Built-in system generalist subagent — works like the main thread on a delegated task.",
+        mode: "subagent",
+        systemPrompt: "You are the fork subagent for ghost — a generalist with the same broad capabilities as the main thread. Own the delegated task end-to-end: investigate what you need, do the work, verify the result, and report the outcome with evidence.",
+        source: "system",
+        filePath: "system:fork",
+    },
 ];
 function loadAgentsFromDir(dir, source) {
     const agents = [];

package/dist/mcp/npx-resolver.d.ts

@@ -3,5 +3,34 @@ export interface NpxResolution {
     extraArgs: string[];
     isJs: boolean;
 }
-export declare function resolveNpxBinary(command: string, args: string[]): Promise<NpxResolution | null>;
+export interface ResolveOptions {
+    /** Override for the global node_modules root (tests / custom environments). */
+    globalRoot?: string | null;
+    /** Override for the npm cache dir (tests / custom environments). */
+    npmCacheDir?: string | null;
+    /** Override for the registry "latest version" lookup (tests / offline). */
+    latestVersionFetcher?: (packageName: string) => Promise<string | null>;
+    /** Override for the npx-cache population step (tests). */
+    forceInstall?: () => Promise<void>;
+}
+interface ParsedInvocation {
+    packageSpec: string;
+    binName?: string;
+    extraArgs: string[];
+}
+export declare function resolveNpxBinary(command: string, args: string[], options?: ResolveOptions): Promise<NpxResolution | null>;
+export declare function parseNpxArgs(args: string[]): ParsedInvocation | null;
+export declare function parseNpmExecArgs(args: string[]): ParsedInvocation | null;
+export declare function extractPackageName(spec: string): string | null;
+/**
+ * A "floating" spec is one without a version pin: bare name, `@latest` or `@*`.
+ * Only floating specs may resolve from the global tree and only they get the
+ * registry freshness check — a pinned spec must match its exact version.
+ */
+export declare function isFloatingSpec(spec: string): boolean;
+/** Reset per-process memoizations (used by tests). */
+export declare function resetNpxResolverCachesForTests(): void;
+/** Semver-ish comparison; release beats prerelease, identifiers compare numerically when both numeric. */
+export declare function compareVersions(a: string, b: string): number;
+export {};
 //# sourceMappingURL=npx-resolver.d.ts.map

package/dist/mcp/npx-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"npx-resolver.d.ts","sourceRoot":"","sources":["../../src/mcp/npx-resolver.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;CACf;AAQD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAgC/B"}
+{"version":3,"file":"npx-resolver.d.ts","sourceRoot":"","sources":["../../src/mcp/npx-resolver.ts"],"names":[],"mappings":"AAqCA,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,2EAA2E;IAC3E,oBAAoB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACvE,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,UAAU,gBAAgB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CA0D/B;AAMD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,gBAAgB,GAAG,IAAI,CAkDpE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,gBAAgB,GAAG,IAAI,CAmCxE;AAqKD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc9D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKpD;AAqED,sDAAsD;AACtD,wBAAgB,8BAA8B,IAAI,IAAI,CAGrD;AA+GD,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAW5D"}

package/dist/mcp/npx-resolver.js

@@ -1,11 +1,26 @@
 // npx-resolver.ts - Resolve npx/npm exec binaries to avoid npm parent processes
+//
+// Resolution order (mirrors `npm exec` semantics, minus the local project tree):
+//   1. Global install (`<prefix>/lib/node_modules/<pkg>`) — beats the npx cache,
+//      so `npm i -g pkg@latest` takes effect on the next server (re)connect.
+//      Pinned specs (`pkg@1.2.3`) never resolve from global.
+//   2. Own resolution cache (`~/.spectral/agent/mcp-npx-cache.json`, 24h TTL) —
+//      hot path, no registry traffic.
+//   3. npx cache scan (`~/.npm/_npx/*`); floating specs (`pkg`, `pkg@latest`,
+//      `pkg@*`) get a registry freshness check once per TTL window and the
+//      cache is refreshed via `npm exec` when a newer version exists.
+//   4. Slow path: force-populate the npx cache, then re-scan.
 import { existsSync, readFileSync, realpathSync, readdirSync, statSync, writeFileSync, renameSync, mkdirSync, openSync, readSync, closeSync } from "node:fs";
 import { join, dirname, extname, resolve, sep } from "node:path";
 import { getAgentPath } from "./agent-dir.js";
 import spawn from "cross-spawn";
 const CACHE_VERSION = 1;
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
-export async function resolveNpxBinary(command, args) {
+const CACHE_PRUNE_MS = 30 * 24 * 60 * 60 * 1000;
+const REGISTRY_CHECK_TIMEOUT_MS = 10_000;
+const GLOBAL_ROOT_TIMEOUT_MS = 5_000;
+const FORCE_CACHE_TIMEOUT_MS = 30_000;
+export async function resolveNpxBinary(command, args, options = {}) {
     const parsed = command === "npx"
         ? parseNpxArgs(args)
         : command === "npm"
@@ -16,24 +31,52 @@ export async function resolveNpxBinary(command, args) {
     const cacheKey = JSON.stringify([command, ...args]);
     const cache = loadCache();
     const cached = cache?.entries?.[cacheKey];
+    // 1. Global install wins (npm exec semantics: global tree beats npx cache).
+    const global = resolveFromGlobal(parsed.packageSpec, parsed.binName, options.globalRoot);
+    if (global) {
+        if (!cached || cached.resolvedBin !== global.resolvedBin) {
+            saveCacheEntry(cacheKey, global);
+        }
+        return toResolution(global, parsed.extraArgs);
+    }
+    // 2. Own resolution cache (hot path — no registry traffic, TTL-governed).
     if (cached && Date.now() - cached.resolvedAt < CACHE_TTL_MS && existsSync(cached.resolvedBin)) {
-        return { binPath: cached.resolvedBin, extraArgs: parsed.extraArgs, isJs: cached.isJs };
+        return toResolution(cached, parsed.extraArgs);
+    }
+    // 3. npx cache scan; floating specs get a registry freshness check on refresh.
+    const scanned = resolveFromNpmCache(parsed.packageSpec, parsed.binName, options.npmCacheDir);
+    if (scanned && isFloatingSpec(parsed.packageSpec) && scanned.packageVersion) {
+        const fetcher = options.latestVersionFetcher ?? fetchLatestVersion;
+        const packageName = extractPackageName(parsed.packageSpec) ?? parsed.packageSpec;
+        const latest = await fetcher(packageName);
+        if (latest && compareVersions(latest, scanned.packageVersion) > 0) {
+            const force = options.forceInstall ?? (() => forceNpxCache(parsed.packageSpec));
+            await force();
+            const refreshed = resolveFromNpmCache(parsed.packageSpec, parsed.binName, options.npmCacheDir);
+            if (refreshed) {
+                saveCacheEntry(cacheKey, refreshed);
+                return toResolution(refreshed, parsed.extraArgs);
+            }
+        }
     }
-    const resolved = resolveFromNpmCache(parsed.packageSpec, parsed.binName);
-    if (resolved) {
-        saveCacheEntry(cacheKey, resolved);
-        return { binPath: resolved.resolvedBin, extraArgs: parsed.extraArgs, isJs: resolved.isJs };
+    if (scanned) {
+        saveCacheEntry(cacheKey, scanned);
+        return toResolution(scanned, parsed.extraArgs);
     }
-    // Slow path: force npx cache population
-    await forceNpxCache(parsed.packageSpec);
-    const resolvedAfterInstall = resolveFromNpmCache(parsed.packageSpec, parsed.binName);
+    // 4. Slow path: force npx cache population.
+    const force = options.forceInstall ?? (() => forceNpxCache(parsed.packageSpec));
+    await force();
+    const resolvedAfterInstall = resolveFromNpmCache(parsed.packageSpec, parsed.binName, options.npmCacheDir);
     if (resolvedAfterInstall) {
         saveCacheEntry(cacheKey, resolvedAfterInstall);
-        return { binPath: resolvedAfterInstall.resolvedBin, extraArgs: parsed.extraArgs, isJs: resolvedAfterInstall.isJs };
+        return toResolution(resolvedAfterInstall, parsed.extraArgs);
     }
     return null;
 }
-function parseNpxArgs(args) {
+function toResolution(entry, extraArgs) {
+    return { binPath: entry.resolvedBin, extraArgs, isJs: entry.isJs };
+}
+export function parseNpxArgs(args) {
     const separatorIndex = args.indexOf("--");
     const before = separatorIndex >= 0 ? args.slice(0, separatorIndex) : args;
     const after = separatorIndex >= 0 ? args.slice(separatorIndex + 1) : [];
@@ -87,7 +130,7 @@ function parseNpxArgs(args) {
     const extraArgs = positionals.slice(1).concat(after);
     return { packageSpec: packagePositional, extraArgs };
 }
-function parseNpmExecArgs(args) {
+export function parseNpmExecArgs(args) {
     if (args[0] !== "exec")
         return null;
     const execArgs = args.slice(1);
@@ -128,8 +171,65 @@ function parseNpmExecArgs(args) {
     const extraArgs = after.slice(1);
     return { packageSpec, binName, extraArgs };
 }
-function resolveFromNpmCache(packageSpec, binName) {
-    const cacheDir = getNpmCacheDir();
+function pickBinEntry(binField, packageName, explicitBin) {
+    if (typeof binField === "string") {
+        return { name: defaultBinName(packageName), rel: binField };
+    }
+    for (const candidate of buildBinCandidates(packageName, explicitBin)) {
+        if (binField[candidate]) {
+            return { name: candidate, rel: binField[candidate] };
+        }
+    }
+    const firstEntry = Object.entries(binField)[0];
+    if (firstEntry) {
+        return { name: firstEntry[0], rel: firstEntry[1] };
+    }
+    return null;
+}
+/**
+ * Resolve the package from the npm global install tree. Global beats the npx
+ * cache, but only floating specs (`pkg`, `pkg@latest`, `pkg@*`) may resolve
+ * from global — a pinned spec must match its exact version.
+ */
+function resolveFromGlobal(packageSpec, binName, globalRootOverride) {
+    if (!isFloatingSpec(packageSpec))
+        return null;
+    const packageName = extractPackageName(packageSpec);
+    if (!packageName)
+        return null;
+    const root = globalRootOverride ?? getGlobalRoot();
+    if (!root)
+        return null;
+    const pkgDir = join(root, ...packageName.split("/"));
+    const packageJsonPath = join(pkgDir, "package.json");
+    if (!existsSync(packageJsonPath))
+        return null;
+    let pkg = null;
+    try {
+        pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    const binField = pkg?.bin;
+    if (!binField)
+        return null;
+    const picked = pickBinEntry(binField, packageName, binName);
+    if (!picked)
+        return null;
+    const resolvedBin = resolve(pkgDir, picked.rel);
+    if (!existsSync(resolvedBin))
+        return null;
+    return {
+        resolvedBin,
+        resolvedAt: Date.now(),
+        packageVersion: pkg?.version,
+        isJs: detectJsBinary(resolvedBin),
+        source: "global",
+    };
+}
+function resolveFromNpmCache(packageSpec, binName, cacheDirOverride) {
+    const cacheDir = cacheDirOverride ?? getNpmCacheDir();
     if (!cacheDir)
         return null;
     const packageName = extractPackageName(packageSpec);
@@ -151,59 +251,36 @@ function resolveFromNpmCache(packageSpec, binName) {
     const binField = pkg?.bin;
     if (!binField)
         return null;
-    const candidates = buildBinCandidates(packageName, binName);
-    let chosenBinName;
-    let binRel;
-    if (typeof binField === "string") {
-        chosenBinName = defaultBinName(packageName);
-        binRel = binField;
-    }
-    else {
-        for (const candidate of candidates) {
-            if (binField[candidate]) {
-                chosenBinName = candidate;
-                binRel = binField[candidate];
-                break;
-            }
-        }
-        if (!binRel) {
-            const firstEntry = Object.entries(binField)[0];
-            if (firstEntry) {
-                chosenBinName = firstEntry[0];
-                binRel = firstEntry[1];
-            }
-        }
-    }
-    if (!binRel)
+    const picked = pickBinEntry(binField, packageName, binName);
+    if (!picked)
         return null;
     const nodeModulesDir = findNodeModulesDir(packageDir);
-    const binLink = chosenBinName ? join(nodeModulesDir, ".bin", chosenBinName) : null;
-    let resolvedBin = binLink && existsSync(binLink) ? safeRealpath(binLink) : "";
+    const binLink = join(nodeModulesDir, ".bin", picked.name);
+    let resolvedBin = existsSync(binLink) ? safeRealpath(binLink) : "";
     if (!resolvedBin) {
-        resolvedBin = resolve(packageDir, binRel);
+        resolvedBin = resolve(packageDir, picked.rel);
         if (!existsSync(resolvedBin))
             return null;
     }
-    const isJs = detectJsBinary(resolvedBin);
     return {
         resolvedBin,
         resolvedAt: Date.now(),
         packageVersion: pkg?.version,
-        isJs,
+        isJs: detectJsBinary(resolvedBin),
+        source: "npx-cache",
     };
 }
-const FORCE_CACHE_TIMEOUT_MS = 30_000;
 async function forceNpxCache(packageSpec) {
     try {
-        await new Promise((resolve, reject) => {
+        await new Promise((resolvePromise, rejectPromise) => {
             const proc = spawn("npm", ["exec", "--yes", "--package", packageSpec, "--", "node", "-e", "1"], { stdio: "ignore" });
             const timer = setTimeout(() => {
                 proc.kill();
-                reject(new Error("timeout"));
+                rejectPromise(new Error("timeout"));
             }, FORCE_CACHE_TIMEOUT_MS);
             timer.unref();
-            proc.on("close", () => { clearTimeout(timer); resolve(); });
-            proc.on("error", (err) => { clearTimeout(timer); reject(err); });
+            proc.on("close", () => { clearTimeout(timer); resolvePromise(); });
+            proc.on("error", (err) => { clearTimeout(timer); rejectPromise(err); });
         });
     }
     catch {
@@ -221,13 +298,15 @@ function buildBinCandidates(packageName, explicitBin) {
             candidates.push(namePart);
         if (scopePart && namePart)
             candidates.push(`${scopePart}-${namePart}`);
+        if (scopePart)
+            candidates.push(scopePart);
     }
     else {
         candidates.push(packageName);
     }
     return [...new Set(candidates.filter(Boolean))];
 }
-function extractPackageName(spec) {
+export function extractPackageName(spec) {
     const trimmed = spec.trim();
     if (!trimmed)
         return null;
@@ -244,6 +323,18 @@ function extractPackageName(spec) {
     const atIndex = trimmed.indexOf("@");
     return atIndex >= 0 ? trimmed.slice(0, atIndex) : trimmed;
 }
+/**
+ * A "floating" spec is one without a version pin: bare name, `@latest` or `@*`.
+ * Only floating specs may resolve from the global tree and only they get the
+ * registry freshness check — a pinned spec must match its exact version.
+ */
+export function isFloatingSpec(spec) {
+    const name = extractPackageName(spec);
+    if (!name)
+        return false;
+    const trimmed = spec.trim();
+    return trimmed === name || trimmed === `${name}@latest` || trimmed === `${name}@*`;
+}
 function defaultBinName(packageName) {
     if (packageName.startsWith("@")) {
         const parts = packageName.split("/");
@@ -265,7 +356,9 @@ function findCachedPackageDir(cacheDir, packageName) {
         const mtime = safeStatMtime(full);
         return { name: entry.name, mtime };
     })
-        .sort((a, b) => b.mtime - a.mtime);
+        // Newest first; on equal mtimes fall back to a stable name order so
+        // resolution is deterministic.
+        .sort((a, b) => (b.mtime - a.mtime) || a.name.localeCompare(b.name));
     for (const entry of candidates) {
         const pkgDir = join(npxDir, entry.name, "node_modules", ...packagePathParts);
         if (existsSync(join(pkgDir, "package.json"))) {
@@ -303,6 +396,12 @@ function detectJsBinary(binPath) {
     }
 }
 let npmCacheDirCached;
+let globalRootCached;
+/** Reset per-process memoizations (used by tests). */
+export function resetNpxResolverCachesForTests() {
+    npmCacheDirCached = undefined;
+    globalRootCached = undefined;
+}
 function getNpmCacheDir() {
     if (npmCacheDirCached !== undefined)
         return npmCacheDirCached;
@@ -325,6 +424,155 @@ function getNpmCacheDir() {
     npmCacheDirCached = null;
     return null;
 }
+/**
+ * Resolve the global node_modules root (e.g.
+ * `<prefix>/lib/node_modules` on unix, `<prefix>/node_modules` on Windows).
+ * Derived from the running node binary to avoid spawning npm on the hot path;
+ * falls back to `npm root -g` when the derived path does not exist.
+ */
+function getGlobalRoot() {
+    if (globalRootCached !== undefined)
+        return globalRootCached;
+    const derived = deriveGlobalRoot();
+    if (derived && existsSync(derived)) {
+        globalRootCached = derived;
+        return globalRootCached;
+    }
+    globalRootCached = discoverGlobalRootViaNpm();
+    return globalRootCached;
+}
+function deriveGlobalRoot() {
+    const prefix = process.env.NPM_CONFIG_PREFIX?.trim() || process.env.npm_config_prefix?.trim() || "";
+    const base = prefix || dirname(dirname(process.execPath));
+    if (!base)
+        return null;
+    return join(base, process.platform === "win32" ? "node_modules" : join("lib", "node_modules"));
+}
+function discoverGlobalRootViaNpm() {
+    try {
+        const result = spawn.sync("npm", ["root", "-g"], {
+            encoding: "utf-8",
+            timeout: GLOBAL_ROOT_TIMEOUT_MS,
+        });
+        if (result.status === 0) {
+            const path = String(result.stdout).trim();
+            if (path)
+                return path;
+        }
+    }
+    catch {
+        // Ignore — global resolution simply stays unavailable.
+    }
+    return null;
+}
+/**
+ * Registry "latest" lookup for floating specs. Returns null on any failure
+ * (offline, timeout) so resolution degrades to the local state.
+ */
+async function fetchLatestVersion(packageName) {
+    return new Promise((resolvePromise) => {
+        let settled = false;
+        let timer;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolvePromise(value);
+        };
+        try {
+            const proc = spawn("npm", ["view", packageName, "version", "--json"], {
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            let out = "";
+            timer = setTimeout(() => {
+                proc.kill();
+                done(null);
+            }, REGISTRY_CHECK_TIMEOUT_MS);
+            timer.unref();
+            proc.stdout?.on("data", (chunk) => {
+                out += chunk.toString("utf-8");
+            });
+            proc.on("close", () => done(parseLatestVersionOutput(out)));
+            proc.on("error", () => done(null));
+        }
+        catch {
+            done(null);
+        }
+    });
+}
+function parseLatestVersionOutput(out) {
+    const raw = out.trim();
+    if (!raw)
+        return null;
+    let value = raw;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "string")
+            value = parsed;
+    }
+    catch {
+        value = raw.replace(/^["']|["']$/g, "");
+    }
+    return /^v?\d+\.\d+\.\d+/.test(value) ? value : null;
+}
+/** Semver-ish comparison; release beats prerelease, identifiers compare numerically when both numeric. */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (!pa || !pb) {
+        // Unparseable — fall back to lexicographic so the comparison stays total.
+        return a < b ? -1 : a > b ? 1 : 0;
+    }
+    for (const key of ["major", "minor", "patch"]) {
+        if (pa[key] !== pb[key])
+            return pa[key] < pb[key] ? -1 : 1;
+    }
+    return comparePrerelease(pa.prerelease, pb.prerelease);
+}
+function parseVersion(v) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim());
+    if (!m)
+        return null;
+    return {
+        major: Number(m[1]),
+        minor: Number(m[2]),
+        patch: Number(m[3]),
+        prerelease: m[4] ? m[4].split(".") : null,
+    };
+}
+function comparePrerelease(a, b) {
+    if (!a && !b)
+        return 0;
+    if (!a)
+        return 1;
+    if (!b)
+        return -1;
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const ai = a[i];
+        const bi = b[i];
+        if (ai === undefined)
+            return -1;
+        if (bi === undefined)
+            return 1;
+        const an = /^\d+$/.test(ai);
+        const bn = /^\d+$/.test(bi);
+        if (an && bn) {
+            const diff = Number(ai) - Number(bi);
+            if (diff !== 0)
+                return diff < 0 ? -1 : 1;
+        }
+        else if (an !== bn) {
+            return an ? -1 : 1;
+        }
+        else if (ai !== bi) {
+            return ai < bi ? -1 : 1;
+        }
+    }
+    return 0;
+}
 function getNpxCachePath() {
     return getAgentPath("mcp-npx-cache.json");
 }
@@ -350,7 +598,7 @@ function saveCacheEntry(key, entry) {
     const cachePath = getNpxCachePath();
     const dir = dirname(cachePath);
     mkdirSync(dir, { recursive: true });
-    let merged = { version: CACHE_VERSION, entries: {} };
+    const merged = { version: CACHE_VERSION, entries: {} };
     try {
         if (existsSync(cachePath)) {
             const existing = JSON.parse(readFileSync(cachePath, "utf-8"));
@@ -362,6 +610,13 @@ function saveCacheEntry(key, entry) {
     catch {
         // Ignore parse errors
     }
+    // Prune entries that have not been re-resolved for 30 days.
+    const cutoff = Date.now() - CACHE_PRUNE_MS;
+    for (const [existingKey, existingEntry] of Object.entries(merged.entries)) {
+        if (existingEntry.resolvedAt < cutoff) {
+            delete merged.entries[existingKey];
+        }
+    }
     merged.entries[key] = entry;
     const tmpPath = `${cachePath}.${process.pid}.tmp`;
     writeFileSync(tmpPath, JSON.stringify(merged, null, 2), "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.205",
+  "version": "0.9.206",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,