hoi4-agent-tools 2.8.10 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 No unreleased changes.
 
+## 3.0.0 - 2026-08-31
+
+- Promote the complete focus, GUI, map, event, technology, and probability MCP surface to the stable 3.0 release line after full synthetic, installed-game, external-workspace, transport, package, Inspector, and Registry qualification.
+- Render installed HOI4 bitmap fonts and language overrides from their native atlases with deterministic metrics, borders, crisp scaling, and localisation colours; keep the exhaustive installed-font audit as a release regression gate.
+- Resolve scenario and dynamic-list country scopes into real ideology-aware flags using each masked-shield definition's own asset dimensions, and render inline HOI4 text icons that appear only after dynamic text substitution.
+- Keep large legitimate event and technology workspaces complete and support scenario-resolved dynamic weighted pools without automatic partial-analysis fallbacks.
+- Keep explicit-file probability inspection narrow, bound retained source and immutable-game scan caches, and avoid full-workspace rescans when rendering inline or declared custom-pool analyses.
+- Build event graphs from one merged source index, retain raw comparison sources instead of parsed scan snapshots, and route selector-scoped inspection and rendering through the focused event graph.
+- Keep the public repository focused on the supported release by using one maintained branch and manually reviewed dependency updates.
+
+## 2.8.11 - 2026-08-30
+
+- Render vanilla HOI4 bitmap fonts with their native atlas masks, legacy page fallbacks, inverted-mask handling, declared glyph channels, crisp scaled sampling, borders, and localisation colours; qualify every shipped descriptor and base font family.
+- Keep large event and technology workspaces complete by separating game and mod scans, accepting large legitimate Clausewitz sources, retaining large state-access inventories, and removing automatic focused-analysis fallbacks.
+- Inspect, evaluate, and compare complete declared dynamic weighted pools with scenario-resolved candidate weights, eligibility, exact probabilities, and complete candidate inventories.
+- Authenticate GitHub release-state API checks so release publication does not fail on anonymous API limits.
+
 ## 2.8.10 - 2026-08-30
 
 - Fix vanilla BMFont corruption by following declared face and outline channel coverage directly instead of guessing polarity independently for each glyph.

package/README.md

@@ -1,17 +1,45 @@
 # HOI4 Agent Tools
 
-HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron IV event chains, technology systems, AI weights, and MTTH timing and to inspect, create, or clean up focus trees, scripted GUIs, and maps. Start it in a mod folder and it works there immediately, with offline renders for review.
+HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron IV event chains, technology systems, AI weights, and MTTH timing and to inspect, create, or clean up focus trees, scripted GUIs, and maps. It produces source-linked structural and visual evidence that agents can use inside a larger modding workflow.
 
 ## What it does
 
 - Focus trees: inspect structure and references, render layouts, create trees, and reorganize existing branches.
-- Scripted GUIs: trace GUI, GFX, scripted-GUI, and localisation links; render value-driven variants, states, resolutions, hierarchy, and click regions; diagnose alignment, visibility, clipping, panel containment, and button-label centering; create or repair interface source.
+- Scripted GUIs: trace GUI, GFX, scripted-GUI, and localisation links; render value-driven variants, dynamic country flags, inline text icons, states, resolutions, hierarchy, and click regions; diagnose alignment, visibility, clipping, panel containment, and button-label centering; create or repair interface source.
 - Maps: navigate the complete rendered map by ID or localised name; inspect provinces, states, regions, adjacency, supply, railways, and positions; create states and provinces; change IDs; and repair connected map data.
 - Event chains: scan definitions and call sites, trace routes and state flow, lint references, render graphs, and compare revisions without editing event source.
 - Technology trees: reconstruct technology and doctrine paths, folder layouts, unlocks, bonuses, grants, metadata, assets, and structural changes.
 - AI and MTTH: evaluate weighted choices and timing across explicit scenarios, bind special scope chains, enumerate dynamic target pools, sweep uncertain inputs, simulate distributions, compare patches, and analyze declared stateful pools.
 
-## Setup
+## Real results
+
+The GUI renderer resolves the mod and installed-game sources, fonts, localisation colours, sprites, scripted visibility, dynamic values, lists, controls, and panel composition. These pairs show the in-game surface beside the MCP result.
+
+| Communist Insurgency in game                                                        | Communist Insurgency from MCP                                                                |
+| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| ![Communist Insurgency in game](docs/images/readme/communist-insurgency-ingame.png) | ![Communist Insurgency rendered by the MCP](docs/images/readme/communist-insurgency-mcp.png) |
+
+| Chaos Meter in game                                               | Chaos Meter from MCP                                                       |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| ![Chaos Meter in game](docs/images/readme/chaos-meter-ingame.png) | ![Chaos Meter rendered by the MCP](docs/images/readme/chaos-meter-mcp.png) |
+
+The same scenario-aware renderer can select mutually exclusive settings panes and populate plausible runtime values.
+
+| Trigger Events settings                                                                    | Advanced settings                                                                      |
+| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| ![Trigger Events settings rendered by the MCP](docs/images/readme/settings-events-mcp.png) | ![Advanced settings rendered by the MCP](docs/images/readme/settings-advanced-mcp.png) |
+
+The other workbenches return complete source-linked layouts and catalogs rather than prose-only summaries.
+
+| Focus tree                                                                     | Technology tree                                                                    |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| ![Large focus tree rendered by the MCP](docs/images/readme/focus-tree-mcp.png) | ![Technology tree rendered by the MCP](docs/images/readme/technology-tree-mcp.png) |
+
+| Map                                                             | Event chain                                                                | Probability ranking                                                                |
+| --------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| ![Full map rendered by the MCP](docs/images/readme/map-mcp.png) | ![Event chain rendered by the MCP](docs/images/readme/event-chain-mcp.png) | ![Probability ranking rendered by the MCP](docs/images/readme/probability-mcp.png) |
+
+## Use from a coding agent
 
 Requires Node.js 22.19 or later in the Node 22 line, or Node.js 24.
 
@@ -19,15 +47,12 @@ Requires Node.js 22.19 or later in the Node 22 line, or Node.js 24.
 npm install --global hoi4-agent-tools@latest
 ```
 
-Start the MCP with its working directory set to the mod you are editing. No config or per-mod registration is required: the server finds that mod automatically. Run `hoi4-agent-tools-setup --init` only when you want persistent discovery for several mod roots, a custom game path, or a remote deployment; see [Setup](docs/setup.md).
-
-## Connect your agent
-
-```bash
-hoi4-agent-tools-setup --print-client-config
+```toml
+[mcp_servers.hoi4_agent_tools]
+command = "hoi4-agent-tools.cmd"
 ```
 
-Paste the printed Codex or generic global-install entry into your MCP client, then restart it. The utility prints the correct command for the current operating system.
+On non-Windows systems, use `hoi4-agent-tools` as the command. Agentic HOI4 repositories can include these steps in their agent template so the coding agent installs and registers the server itself; manual installation is not required in that workflow. Once connected, the server follows the active mod supplied by the client and the agent can call its HOI4 tools directly.
 
 ## Tools
 

package/dist/bin/stdio.js

@@ -8,10 +8,6 @@ async function main() {
     const engine = await createEngine();
     const context = {};
     const server = createMcpServer(engine, context);
-    if (process.env.HOI4_AGENT_TOOLS_CHAOSX === '1') {
-        const { registerChaosxTools } = await import('../hoi4_agent_tools/mcp/tools/chaosx.js');
-        registerChaosxTools(server, engine, context);
-    }
     server.server.onerror = (error) => {
         const fatalInputError = error instanceof StdioFrameLimitError || error instanceof StdioInvalidUtf8Error;
         const rejectedMessage = error instanceof StdioInvalidMessageError;

package/dist/hoi4_agent_tools/core/configuration.js

@@ -10,6 +10,9 @@ export const HTTP_DEFAULT_SESSION_EVENT_BYTES = 2_097_152;
 export const WORKSPACE_MAX_REGISTRATIONS = 1_000;
 const WORKSPACE_MAX_SOURCE_ROOTS = 16;
 const WORKSPACE_MAX_PATHS = 1_000;
+export const DEFAULT_SCAN_MAX_FILES = 100_000;
+export const DEFAULT_SCAN_MAX_BYTES = 268_435_456;
+export const DEFAULT_SCAN_MAX_FILE_BYTES = 67_108_864;
 const allowedOriginSchema = z.url().refine((value) => {
     const parsed = new URL(value);
     return ((parsed.protocol === 'http:' || parsed.protocol === 'https:') &&
@@ -128,9 +131,19 @@ export const serverConfigurationSchema = z
         message: 'Server state root must be an absolute private path',
     })
         .optional(),
-    scanMaxFiles: z.number().int().min(1).max(1_000_000).default(20_000),
-    scanMaxBytes: z.number().int().min(1_048_576).max(Number.MAX_SAFE_INTEGER).default(134_217_728),
-    scanMaxFileBytes: z.number().int().min(65_536).max(Number.MAX_SAFE_INTEGER).default(67_108_864),
+    scanMaxFiles: z.number().int().min(1).max(1_000_000).default(DEFAULT_SCAN_MAX_FILES),
+    scanMaxBytes: z
+        .number()
+        .int()
+        .min(1_048_576)
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(DEFAULT_SCAN_MAX_BYTES),
+    scanMaxFileBytes: z
+        .number()
+        .int()
+        .min(65_536)
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(DEFAULT_SCAN_MAX_FILE_BYTES),
     artifactMaxBytes: z
         .number()
         .int()

package/dist/hoi4_agent_tools/core/domain-scan-patterns.js

@@ -8,6 +8,14 @@ function uniquePatterns(patterns) {
 function englishLocalisationPatterns(roots) {
     return [...under(roots, 'english/**/*.{yml,yaml}'), ...under(roots, '*.{yml,yaml}')];
 }
+export function probabilitySharedDefinitionPatterns() {
+    return uniquePatterns([
+        'common/scripted_effects/**/*.txt',
+        'common/scripted_triggers/**/*.txt',
+        'common/script_constants/**/*.txt',
+        'common/mtth/**/*.txt',
+    ]);
+}
 /** Sources required to import, link, lint, render, and rewrite focus content. */
 export function focusDomainScanPatterns(workspace) {
     const roots = workspace.registration.roots;
@@ -32,8 +40,9 @@ export function focusDomainScanPatterns(workspace) {
 export function probabilityDomainScanPatterns(workspace, sourcePaths = []) {
     const roots = workspace.registration.roots;
     const normalizedSourcePaths = sourcePaths.map((sourcePath) => sourcePath.replace(/^.*?:/u, '').replaceAll('\\', '/').replace(/^\.\//u, ''));
+    if (normalizedSourcePaths.length > 0)
+        return uniquePatterns([...normalizedSourcePaths, ...probabilitySharedDefinitionPatterns()]);
     return uniquePatterns([
-        ...normalizedSourcePaths,
         ...under(roots.focus, '**/*.txt'),
         'common/decisions/**/*.txt',
         'common/technologies/**/*.txt',
@@ -49,18 +58,6 @@ export function probabilityDomainScanPatterns(workspace, sourcePaths = []) {
         'events/**/*.txt',
     ]);
 }
-/** Text sources needed to discover country flags and leader portraits. */
-export function countryAssetDiscoveryPatterns(workspace) {
-    const roots = workspace.registration.roots;
-    return uniquePatterns([
-        'history/countries/**/*.txt',
-        'common/characters/**/*.txt',
-        'common/scripted_effects/**/*.txt',
-        'events/**/*.txt',
-        ...under(roots.interface, '**/*.gfx'),
-        ...under(roots.gfx, '**/*.gfx'),
-    ]);
-}
 export function exactChangedFilePatterns(relativePaths) {
     return uniquePatterns(relativePaths.map((relativePath) => relativePath.replaceAll('\\', '/').replace(/^\.\//u, '')));
 }

package/dist/hoi4_agent_tools/core/engine.js

@@ -139,6 +139,9 @@ export class CoreEngine {
         })}`;
         let flight = this.#scanFlights.get(requestKey);
         if (flight === undefined) {
+            for (const key of this.#scanCache.keys())
+                if (key.startsWith(`${workspaceId}:`) && !key.startsWith(`${requestKey}:`))
+                    this.#scanCache.delete(key);
             const controller = new AbortController();
             const promise = (async () => {
                 return this.withScanAdmission(controller.signal, async () => {

package/dist/hoi4_agent_tools/core/scanner.js

@@ -1,7 +1,8 @@
 import { open } from 'node:fs/promises';
 import path from 'node:path';
 import fg from 'fast-glob';
-import { compareCodeUnits, sha256Bytes } from './canonical.js';
+import { compareCodeUnits, hashCanonical, sha256Bytes } from './canonical.js';
+import { DEFAULT_SCAN_MAX_BYTES, DEFAULT_SCAN_MAX_FILE_BYTES, DEFAULT_SCAN_MAX_FILES, } from './configuration.js';
 import { ServiceError } from './result.js';
 function normalizeRelative(value) {
     return value.replaceAll('\\', '/').replace(/^\.\//u, '');
@@ -26,13 +27,14 @@ export class WorkspaceScanner {
     serverMaxBytes;
     serverMaxFileBytes;
     #sourceCache = new Map();
+    #gameScanCache = new Map();
     #sourceCacheBytes = 0;
     #sourceCacheMaxBytes;
-    constructor(serverMaxFiles = 20_000, serverMaxBytes = 134_217_728, serverMaxFileBytes = 67_108_864) {
+    constructor(serverMaxFiles = DEFAULT_SCAN_MAX_FILES, serverMaxBytes = DEFAULT_SCAN_MAX_BYTES, serverMaxFileBytes = DEFAULT_SCAN_MAX_FILE_BYTES) {
         this.serverMaxFiles = serverMaxFiles;
         this.serverMaxBytes = serverMaxBytes;
         this.serverMaxFileBytes = serverMaxFileBytes;
-        this.#sourceCacheMaxBytes = Math.max(serverMaxFileBytes, Math.min(536_870_912, serverMaxBytes * 2));
+        this.#sourceCacheMaxBytes = Math.max(serverMaxFileBytes, Math.min(134_217_728, serverMaxBytes));
     }
     cacheKey(absolutePath) {
         const resolved = path.resolve(absolutePath);
@@ -53,6 +55,24 @@ export class WorkspaceScanner {
             this.#sourceCacheBytes -= oldest[1].bytes.length;
         }
     }
+    gameScanKey(workspace, root, options) {
+        return hashCanonical({
+            workspaceId: workspace.id,
+            root: root.path,
+            patterns: [...options.patterns].sort(compareCodeUnits),
+            ignore: [...(options.ignore ?? ['**/.hoi4-agent/**'])].sort(compareCodeUnits),
+        });
+    }
+    retainGameScan(key, files) {
+        this.#gameScanCache.delete(key);
+        this.#gameScanCache.set(key, files.map((file) => ({ ...file })));
+        while (this.#gameScanCache.size > 8) {
+            const oldest = this.#gameScanCache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#gameScanCache.delete(oldest);
+        }
+    }
     async scan(workspace, options) {
         options.signal?.throwIfAborted();
         const maxFiles = options.maxFiles ?? this.serverMaxFiles;
@@ -77,6 +97,29 @@ export class WorkspaceScanner {
         let enumeratedFiles = 0;
         for (const root of roots) {
             options.signal?.throwIfAborted();
+            const gameScanKey = root.kind === 'game' ? this.gameScanKey(workspace, root, options) : undefined;
+            const cachedGameFiles = gameScanKey === undefined ? undefined : this.#gameScanCache.get(gameScanKey);
+            if (cachedGameFiles !== undefined && gameScanKey !== undefined) {
+                this.#gameScanCache.delete(gameScanKey);
+                this.#gameScanCache.set(gameScanKey, cachedGameFiles);
+                enumeratedFiles += cachedGameFiles.length;
+                if (enumeratedFiles > maxFiles)
+                    throw new ServiceError('SCAN_FILE_LIMIT', 'Scan exceeds the configured file limit', {
+                        files: enumeratedFiles,
+                        limit: maxFiles,
+                    });
+                for (const file of cachedGameFiles) {
+                    totalBytes += file.size;
+                    if (totalBytes > maxBytes)
+                        throw new ServiceError('SCAN_BYTE_LIMIT', 'Scan exceeds the configured byte limit', {
+                            bytes: totalBytes,
+                            limit: maxBytes,
+                        });
+                    result.push({ ...file });
+                }
+                continue;
+            }
+            const rootFiles = [];
             const matches = fg.stream(options.patterns, {
                 cwd: root.path,
                 onlyFiles: true,
@@ -89,7 +132,10 @@ export class WorkspaceScanner {
                 options.signal?.throwIfAborted();
                 enumeratedFiles += 1;
                 if (enumeratedFiles > maxFiles) {
-                    throw new ServiceError('SCAN_FILE_LIMIT', 'Scan exceeds the configured file limit');
+                    throw new ServiceError('SCAN_FILE_LIMIT', 'Scan exceeds the configured file limit', {
+                        files: enumeratedFiles,
+                        limit: maxFiles,
+                    });
                 }
                 const relativePath = normalizeRelative(String(match));
                 if (hiddenByReplacePath(workspace, root, relativePath))
@@ -103,7 +149,13 @@ export class WorkspaceScanner {
                         continue;
                     const remaining = maxBytes - totalBytes;
                     if (metadata.size > remaining || metadata.size > this.serverMaxFileBytes) {
-                        throw new ServiceError('SCAN_BYTE_LIMIT', 'Scan exceeds the configured byte limit');
+                        throw new ServiceError('SCAN_BYTE_LIMIT', 'Scan exceeds the configured byte limit', {
+                            file: relativePath,
+                            fileBytes: metadata.size,
+                            bytes: totalBytes,
+                            limit: maxBytes,
+                            perFileLimit: this.serverMaxFileBytes,
+                        });
                     }
                     const cached = this.#sourceCache.get(cacheKey);
                     const retained = cached?.size === metadata.size &&
@@ -124,7 +176,7 @@ export class WorkspaceScanner {
                         bytes,
                     });
                     totalBytes += bytes.length;
-                    result.push({
+                    const scanned = {
                         absolutePath,
                         displayPath: `${rootLabel(root)}:${relativePath}`,
                         relativePath,
@@ -134,12 +186,16 @@ export class WorkspaceScanner {
                         modifiedMs: metadata.mtimeMs,
                         sha256,
                         bytes,
-                    });
+                    };
+                    result.push(scanned);
+                    rootFiles.push(scanned);
                 }
                 finally {
                     await handle.close();
                 }
             }
+            if (gameScanKey !== undefined)
+                this.retainGameScan(gameScanKey, rootFiles);
         }
         result.sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.relativePath, right.relativePath));
         const groups = new Map();

package/dist/hoi4_agent_tools/core/source/limits.js

@@ -1,12 +1,11 @@
 export const SOURCE_DIAGNOSTIC_LIMIT = 100;
 export const SOURCE_MAX_NESTING = 256;
-export const SOURCE_MAX_BYTES = 8_388_608;
-// Large authored HOI4 focus and scripted-effect files can exceed 250k tokens while remaining well
-// below the byte and nesting ceilings. Keep enough room for those files without allowing an
-// unbounded token inventory.
-export const SOURCE_TOKEN_LIMIT = 1_000_000;
-export const SOURCE_ENTRY_LIMIT = 100_000;
-export const SOURCE_LINE_LIMIT = 250_000;
+// This is a parser ceiling, not the aggregate workspace-scan or remote request ceiling. Large
+// generated focus, event, and scripted-effect sources routinely exceed 8 MiB in real agentic mods.
+export const SOURCE_MAX_BYTES = 33_554_432;
+export const SOURCE_TOKEN_LIMIT = 4_000_000;
+export const SOURCE_ENTRY_LIMIT = 1_000_000;
+export const SOURCE_LINE_LIMIT = 2_000_000;
 /**
  * Parser ceilings that intentionally return no document or a structurally partial document.
  * Broad inventories may skip these sources, but targeted reads and rewrites must continue to

package/dist/hoi4_agent_tools/event/graph.js

@@ -1604,10 +1604,9 @@ export function buildEventGraph(snapshot, options = {}) {
     assertGraphLimit(graph.unresolved.length, EVENT_GRAPH_MAX_UNRESOLVED, 'EVENT_UNRESOLVED_LIMIT', 'unresolved-analysis count');
     budget.check();
     const diagnostics = sortDiagnostics([...snapshot.diagnostics, ...partial.diagnostics]);
-    const complete = !focused &&
-        snapshot.complete &&
-        graph.unresolved.length === 0 &&
-        !graph.issues.some(({ classification, severity }) => classification === 'unresolved_analysis' || severity === 'blocker');
+    // Coverage completeness is independent from defects discovered in the source. A full,
+    // untruncated analysis remains complete when it correctly reports missing or dynamic links.
+    const complete = !focused && snapshot.complete;
     const nodes = sortNodes(graph.nodes);
     const edges = stableUnique(graph.edges);
     const stateAccesses = stableUnique(graph.stateAccesses);

package/dist/hoi4_agent_tools/event/limits.js

@@ -1,9 +1,9 @@
 import { ServiceError } from '../core/result.js';
 export const EVENT_GRAPH_MAX_NODES = 250_000;
 export const EVENT_GRAPH_MAX_EDGES = 500_000;
-export const EVENT_GRAPH_MAX_STATE_ACCESSES = 250_000;
-export const EVENT_GRAPH_MAX_STATE_LINKS = 250_000;
-export const EVENT_GRAPH_MAX_STATE_LINK_CANDIDATES = 500_000;
+export const EVENT_GRAPH_MAX_STATE_ACCESSES = 1_000_000;
+export const EVENT_GRAPH_MAX_STATE_LINKS = 1_000_000;
+export const EVENT_GRAPH_MAX_STATE_LINK_CANDIDATES = 2_000_000;
 // Installed-game scans can legitimately produce more than twenty thousand source-linked
 // findings before an agent narrows the query. Keep the graph bounded, but do not reject a
 // complete large workspace merely because its diagnostics are numerous.
@@ -13,7 +13,7 @@ export const EVENT_GRAPH_MAX_HELPER_DEPTH = 64;
 export const EVENT_GRAPH_MAX_HELPER_PROJECTIONS = 200_000;
 export const EVENT_GRAPH_MAX_HELPER_STATE_PROJECTIONS = 50_000;
 export const EVENT_GRAPH_MAX_CONDITION_TEXT = 16_384;
-export const EVENT_GRAPH_WORK_LIMIT = 5_000_000;
+export const EVENT_GRAPH_WORK_LIMIT = 10_000_000;
 export const EVENT_FRAGMENT_CACHE_MAX_ENTRIES = 10_000;
 export const EVENT_FRAGMENT_CACHE_MAX_SOURCE_BYTES = 134_217_728;
 export const EVENT_PROPOSED_SOURCE_MAX_FILES = 64;

package/dist/hoi4_agent_tools/event/service.js

@@ -45,16 +45,12 @@ class BoundedEventFragmentCache {
 function eventGraphCacheKey(workspaceId, projectHelpers, analysisMode = 'full') {
     return `${workspaceId}\0${projectHelpers ? 'expanded' : 'structural'}\0${analysisMode}`;
 }
-function isGameBackedWorkspace(workspace) {
-    return workspace.roots.some(({ kind }) => kind === 'game');
-}
 const serviceState = new WeakMap();
 const EVENT_GRAPH_ARTIFACT_MAX_BYTES = 67_108_864;
 const EVENT_GRAPH_ARTIFACT_MAX_CHUNKS = 1_024;
 const EVENT_SCAN_FULL_GRAPH_RECORD_LIMIT = 100_000;
 const EVENT_SCAN_SUMMARY_SAMPLE_LIMIT = 100;
 const EVENT_FOCUSED_EVIDENCE_LIMIT = 2_000;
-const EVENT_FOCUSED_GRAPH_FILE_THRESHOLD = 1_000;
 const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
 const graphHashCache = new WeakMap();
 function groupedCounts(values, key) {
@@ -179,19 +175,21 @@ function eventScanPatterns(workspace, focused = false) {
         ...under(roots.localisation, '*.{yml,yaml}'),
     ].sort(compareCodeUnits);
 }
-async function scanEventSources(engine, workspaceId, workspace, focused = false, principal, signal) {
+async function scanEventSources(engine, workspaceId, workspace, focused = false, signal) {
     const patterns = eventScanPatterns(workspace, focused);
     const gamePatterns = eventScanPatterns(workspace, focused);
     const sourceKinds = ['mod', 'dependency', 'fixture'];
-    const scans = await Promise.all([
-        engine.scan(workspaceId, { patterns, rootKinds: sourceKinds }, principal, signal),
-        ...(workspace.roots.some(({ kind }) => kind === 'game')
-            ? [
-                engine.scan(workspaceId, { patterns: gamePatterns, rootKinds: ['game'] }, principal, signal),
-            ]
-            : []),
-    ]);
-    const files = scans.flatMap(({ files }) => files.map((file) => ({ ...file })));
+    const files = await engine.scanner.scan(workspace, {
+        patterns,
+        rootKinds: sourceKinds,
+        ...(signal === undefined ? {} : { signal }),
+    });
+    if (workspace.roots.some(({ kind }) => kind === 'game'))
+        files.push(...(await engine.scanner.scan(workspace, {
+            patterns: gamePatterns,
+            rootKinds: ['game'],
+            ...(signal === undefined ? {} : { signal }),
+        })));
     recomputeShadowing(files);
     files.sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
     const index = engine.indexFiles(files);
@@ -200,10 +198,10 @@ async function scanEventSources(engine, workspaceId, workspace, focused = false,
         revision: snapshotRevision(files),
         files,
         index,
-        complete: scans.every(({ complete }) => complete) && index.complete,
+        complete: index.complete,
         skippedSourceCount: index.skippedSourceCount,
         skippedSources: index.skippedSources,
-        diagnostics: [...scans.flatMap(({ diagnostics }) => diagnostics), ...index.diagnostics],
+        diagnostics: index.diagnostics,
     };
 }
 function rememberGraph(state, workspaceId, graph) {
@@ -704,29 +702,25 @@ export class EventChainViewer {
         const generation = engineGeneration(this.engine, workspaceId);
         const requestedProjectHelpers = options.projectHelpers ?? true;
         const requestedAnalysisMode = options.analysisMode ?? 'full';
-        const autoFocused = isGameBackedWorkspace(workspace) && requestedAnalysisMode === 'full';
-        const cacheAnalysisMode = autoFocused ? 'focused' : requestedAnalysisMode;
+        const cacheAnalysisMode = requestedAnalysisMode;
         const cacheProjectHelpers = cacheAnalysisMode === 'focused' ? false : requestedProjectHelpers;
         const cacheKey = eventGraphCacheKey(workspaceId, cacheProjectHelpers, cacheAnalysisMode);
         const cached = this.#state.current.get(cacheKey);
         if (options.refresh !== true && cached?.generation === generation) {
             return cached.graph;
         }
-        const sibling = this.#state.current.get(eventGraphCacheKey(workspaceId, !cacheProjectHelpers, cacheAnalysisMode)) ??
-            this.#state.current.get(eventGraphCacheKey(workspaceId, requestedProjectHelpers, requestedAnalysisMode)) ??
-            this.#state.current.get(eventGraphCacheKey(workspaceId, !requestedProjectHelpers)) ??
-            this.#state.current.get(eventGraphCacheKey(workspaceId, requestedProjectHelpers));
-        const scanFocused = autoFocused || requestedAnalysisMode === 'focused';
-        const snapshot = options.refresh !== true && sibling?.generation === generation
-            ? sibling.snapshot
-            : await scanEventSources(this.engine, workspaceId, workspace, scanFocused, options.principal, options.signal);
+        if (options.refresh !== true && requestedAnalysisMode === 'focused') {
+            const fullSibling = this.#state.current.get(eventGraphCacheKey(workspaceId, cacheProjectHelpers, 'full')) ??
+                this.#state.current.get(eventGraphCacheKey(workspaceId, !cacheProjectHelpers, 'full'));
+            if (fullSibling?.generation === generation)
+                return fullSibling.graph;
+        }
+        const scanFocused = requestedAnalysisMode === 'focused';
+        const snapshot = await scanEventSources(this.engine, workspaceId, workspace, scanFocused, options.signal);
         options.signal?.throwIfAborted();
-        if (cached?.snapshot.revision === snapshot.revision && cached.generation === generation) {
+        if (cached?.graph.revision === snapshot.revision && cached.generation === generation)
             return cached.graph;
-        }
-        const buildAnalysisMode = autoFocused || snapshot.files.length > EVENT_FOCUSED_GRAPH_FILE_THRESHOLD
-            ? 'focused'
-            : 'full';
+        const buildAnalysisMode = requestedAnalysisMode;
         const projectHelpers = buildAnalysisMode === 'focused' ? false : requestedProjectHelpers;
         const graph = buildEventGraph(snapshot, {
             ...(options.signal === undefined ? {} : { signal: options.signal }),
@@ -735,13 +729,17 @@ export class EventChainViewer {
             projectHelpers,
             analysisMode: buildAnalysisMode,
         });
-        this.#state.current.set(cacheKey, { generation, snapshot, graph });
+        this.#state.current.set(cacheKey, { generation, files: snapshot.files, graph });
         if (buildAnalysisMode === 'full')
             rememberGraph(this.#state, workspaceId, graph);
         return graph;
     }
     async inspect(input) {
         input.signal?.throwIfAborted();
+        const focused = input.mode === 'trace' ||
+            input.mode === 'explain_path' ||
+            (input.selector !== undefined &&
+                (input.mode === 'scan' || input.mode === 'roots' || input.mode === 'lint'));
         const scannedGraph = await this.scan(input.workspaceId, {
             refresh: input.refresh ?? input.mode === 'scan',
             // Focused routes traverse helper nodes directly and collapse only the
@@ -750,15 +748,11 @@ export class EventChainViewer {
                 input.mode !== 'roots' &&
                 input.mode !== 'trace' &&
                 input.mode !== 'explain_path',
-            ...(input.mode === 'trace' || input.mode === 'explain_path'
-                ? { analysisMode: 'focused' }
-                : {}),
+            analysisMode: focused ? 'focused' : 'full',
             ...(input.principal === undefined ? {} : { principal: input.principal }),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         });
-        // Keep the service result's graph identity distinct from a prior scan while
-        // reusing its structural cache and avoiding a second large graph build.
-        const graph = input.mode === 'trace' || input.mode === 'explain_path' ? { ...scannedGraph } : scannedGraph;
+        const graph = scannedGraph;
         const maxDepth = input.maxDepth ?? 8;
         const maxNodes = input.maxNodes ?? 500;
         const maxEdges = input.maxEdges ?? 2_000;
@@ -935,6 +929,7 @@ export class EventChainViewer {
         const graph = await this.scan(input.workspaceId, {
             ...(input.refresh === undefined ? {} : { refresh: input.refresh }),
             projectHelpers: true,
+            analysisMode: input.selector === undefined ? 'full' : 'focused',
             ...(input.principal === undefined ? {} : { principal: input.principal }),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         });
@@ -1147,7 +1142,7 @@ export class EventChainViewer {
         if (new Set(paths.map((value) => value.toLowerCase())).size !== paths.length) {
             throw new ServiceError('EVENT_PROPOSED_PATH_DUPLICATE', 'Proposed source paths must be unique');
         }
-        const files = cached.snapshot.files.map((file) => ({
+        const files = cached.files.map((file) => ({
             ...file,
             bytes: Buffer.from(file.bytes),
         }));