hoi4-agent-tools 3.6.0 → 3.8.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 3.8.0 - 2026-10-04
+
+- Rank documentation with field-weighted BM25 over identifier-aware terms, cite identifier table rows as exact one-line sections, return each result's best-matching `matchLine`, and split sections by CommonMark fences.
+- Locate a source position with `hoi4.source_lookup` `path` and `line`: return its layer, the containing definitions, the enclosing assignment chain, and a `keyPath` that navigates back to it.
+- Suggest indexed identifiers within three edits when `hoi4.source_lookup` finds no definition.
+- Layer installed `dlc/` and `integrated_dlc/` folders between the base game and mods in internal-ID order, so source lookups, renders, and analyses find DLC sprites, interfaces, and portraits; `includeGameDlc: false` opts out.
+- Apply `replace_path` entries from mod and dependency descriptors in addition to configured replace paths.
+- Check province terrain and continents against the active `common/terrain` categories and `continent.txt`, accept any water terrain for seas and lakes, check strategic-region `naval_terrain`, and report adjacency rows after the `-1` terminator or a missing terminator.
+- Search unresolved GUI asset names in grouped wildcard patterns, so windows with hundreds of missing textures render within the wildcard-pattern ceiling.
+- Retry transient Windows sharing violations on job records and capacity leases, release record handles before parsing, bound delete-pending capacity slots by elapsed time, and report worker coordination failures with a fixed stage and allowlisted native code.
+- Keep every production dependency inside its declared range in the published shrinkwrap, so `npm ls` succeeds in consumer installs; the `@hono/node-server` override is no longer needed.
+
+## 3.7.0 - 2026-10-04
+
+- Publish an `npm-shrinkwrap.json` so every install reproduces the reviewed dependency closure, including all platforms' optional Sharp binaries (about 300 MB installed).
+- Navigate exact nested source assignments and page through bounded child structure, including repeated keys and same-line blocks.
+- Limit definition-only event/helper lookups to their source family and reuse semantic reference analysis for unchanged snapshots.
+- Check snippet syntax, native command kinds, and declared scopes against cited installed or explicitly selected generated documentation, with unresolved coverage reported separately.
+- Verify source files in bounded parallel batches, reject changing or replaced paths, and bound optional cache persistence without truncating analysis.
+- Load isolated workers' domain modules after authenticating the job, preserving exact operation admission and recorded write policies.
+- Filter reference scans by authority, reuse citation hints, decode supported reference encodings, and preserve byte-bounded continuations and explicit omission counts.
+- Replace the unpatched globbing dependency chain and update vulnerable transitive pins, preserving relative-path, symlink, literal-filename and pattern-complexity checks.
+
 ## 3.6.0 - 2026-09-27
 
 - Preview immediate tooltip text from source localisation with declared position, width and padding, using the source tooltip sprite and font.

package/README.md

@@ -1,7 +1,8 @@
 # HOI4 Agent Tools
 
-Give your coding agent tools for Hearts of Iron IV modding.
-Read mod files, find the right documentation, preview trees and interfaces, and make focused changes to focus trees, GUIs and maps.
+Give your coding agent one MCP server for Hearts of Iron IV modding.
+It can find local documentation and vanilla examples, inspect a mod, render its trees and interfaces, compare source behavior, and make focused edits to focus trees, GUIs and maps.
+The pictures below use real Chaos Redux or installed HOI4 files; click any image for the full-size version.
 
 ## Get started
 
@@ -13,40 +14,135 @@ hoi4-agent-tools-setup --print-client-config
 ```
 
 Add the printed configuration to your MCP client and open your mod as its workspace.
+The install is about 280 MiB, because npm fetches the image library's binaries for every platform to keep each install identical.
 Keep an installed copy of HOI4 available for vanilla examples, artwork and fonts.
 The [setup guide](docs/setup.md) covers connecting your agent and choosing game or mod paths.
 
-Then try:
+Ask your agent to find a focus tree and render it, locate the installed documentation for a script command, or preview a scripted GUI at different UI scales.
+The examples below show the results.
 
-> Render this mod's focus trees and show which prerequisites are alternatives.
+## Examples
 
-> Find the installed documentation for `save_event_target_as`, read the relevant section, and show a vanilla example.
+[Focus trees](#focus-trees-and-alternative-prerequisites) · [Technology folders](#technology-folders-and-card-artwork) · [Interfaces](#scripted-interfaces) · [Maps and events](#maps-and-event-chains) · [Local rules and AI](#local-rules-and-ai-weights) · [All tools](#complete-tool-list)
 
-> Preview this scripted GUI at 100% and 125% UI scale and check for clipped text or overlapping controls.
+### Focus trees and alternative prerequisites
 
-## What you can do
+| Focus tree  | Supplied in-game capture                                                                                                    | MCP source preview                                                                                                    |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| 52 focuses  | [![Medium focus tree in game](docs/images/comparisons/fury-ingame.png)](docs/images/comparisons/fury-ingame.png)            | [![Medium focus tree preview](docs/images/comparisons/fury-mcp.png)](docs/images/comparisons/fury-mcp.png)            |
+| 111 focuses | [![Large focus tree in game](docs/images/comparisons/holy-realm-ingame.png)](docs/images/comparisons/holy-realm-ingame.png) | [![Large focus tree preview](docs/images/comparisons/holy-realm-mcp.png)](docs/images/comparisons/holy-realm-mcp.png) |
+| 124 focuses | [![Branching focus tree in game](docs/images/comparisons/utopia-ingame.png)](docs/images/comparisons/utopia-ingame.png)     | [![Branching focus tree preview](docs/images/comparisons/utopia-mcp.png)](docs/images/comparisons/utopia-mcp.png)     |
 
-| Task                                                                 | Guide                                                                    |
-| -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| Find the right wiki section, game documentation or source definition | [Local references](docs/reference.md)                                    |
-| Inspect, preview, create or reorganize a focus tree                  | [Focus trees](docs/focus.md)                                             |
-| Trace event chains, decisions, costs and dependencies                | [Events](docs/events.md) · [Decisions](docs/analysis.md)                 |
-| Preview technology and doctrine trees                                | [Technology trees](docs/technology.md)                                   |
-| Inspect and repair scripted interfaces                               | [Scripted GUIs](docs/gui.md)                                             |
-| Find states and provinces, preview maps and edit connected map data  | [Maps](docs/map.md)                                                      |
-| Compare AI weights and test declared mechanic scenarios              | [AI analysis](docs/probability.md) · [Mechanic tests](docs/mechanics.md) |
-
-## Real examples
-
-These previews were rendered from Chaos Redux and installed HOI4 files.
-Click an image to open it at full size.
-
-| Fury focus tree                                                                                  | Vanilla Options interface                                                                                                    |
-| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
-| [![Fury focus tree](docs/images/comparisons/fury-mcp.png)](docs/images/comparisons/fury-mcp.png) | [![Options interface](docs/images/comparisons/gui/options-video-mcp.png)](docs/images/comparisons/gui/options-video-mcp.png) |
-
-Follow the [examples guide](docs/examples.md) for useful prompts and expected results.
-See [focus and technology comparisons](docs/visual-comparisons.md) and [interface comparisons](docs/gui-comparisons.md) for supplied in-game captures beside the renders.
+Dotted connectors in the MCP preview mark focuses where either preceding focus satisfies one prerequisite group.
+The tree previews show route structure; the game's focus screen has different framing, labels and icons.
+The [focus guide](docs/focus.md) explains inspection, rendering and edits, and the [comparison details](docs/visual-comparisons.md#focus-trees) retain source revisions.
+
+### Technology folders and card artwork
+
+> Render a technology folder. Check card sizes, artwork, links and missing placements.
+
+| Folder           | Supplied in-game capture                                                                                                                   | MCP source preview                                                                                                                           |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Vanilla infantry | [![Infantry folder in game](docs/images/comparisons/infantry-ingame.png)](docs/images/comparisons/infantry-ingame.png)                     | [![Infantry technology folder](docs/images/comparisons/infantry-mcp.png)](docs/images/comparisons/infantry-mcp.png)                          |
+| Mod wide cards   | [![Mod technology folder in game](docs/images/comparisons/chemical-recent-ingame.png)](docs/images/comparisons/chemical-recent-ingame.png) | [![Mod technology folder preview](docs/images/comparisons/chemical-historical-mcp.png)](docs/images/comparisons/chemical-historical-mcp.png) |
+
+The mod folder preview uses the source revision recorded with its screenshot and includes wide equipment cards.
+Armored-car artwork that installed DLC folders provide appears in the infantry preview.
+The [technology comparison](docs/visual-comparisons.md#technology-folders) records its source revision, and the [technology guide](docs/technology.md) covers inspection and doctrine paths.
+
+### Scripted interfaces
+
+> Preview an interface with its game assets and fonts. Check states, text clipping and clickable areas at 100% and 125% UI scale.
+
+| Interface              | Supplied in-game capture                                                                                                                  | MCP source preview                                                                                                                  |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Vanilla video options  | [![Options in game](docs/images/comparisons/gui/options-video-ingame.png)](docs/images/comparisons/gui/options-video-ingame.png)          | [![Options preview](docs/images/comparisons/gui/options-video-mcp.png)](docs/images/comparisons/gui/options-video-mcp.png)          |
+| Vanilla priority panel | [![Priority panel in game](docs/images/comparisons/gui/skoda-priority-ingame.png)](docs/images/comparisons/gui/skoda-priority-ingame.png) | [![Priority panel preview](docs/images/comparisons/gui/skoda-priority-mcp.png)](docs/images/comparisons/gui/skoda-priority-mcp.png) |
+| Mod management window  | [![Management window in game](docs/images/comparisons/gui/tag-manager-ingame.png)](docs/images/comparisons/gui/tag-manager-ingame.png)    | [![Management window preview](docs/images/comparisons/gui/tag-manager-mcp.png)](docs/images/comparisons/gui/tag-manager-mcp.png)    |
+
+The management window capture comes from an older layout.
+The video options preview has no observed gamma value, and the priority panel's capture frames its background differently.
+
+| Mod event log                                                                                                        | Mod status panel                                                                                                                        | Mod status panel, second tab                                                                                                            |
+| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| [![Event Log preview](docs/images/comparisons/gui/event-log-mcp.png)](docs/images/comparisons/gui/event-log-mcp.png) | [![Chaos Meter status](docs/images/comparisons/gui/chaos-meter-status-mcp.png)](docs/images/comparisons/gui/chaos-meter-status-mcp.png) | [![Chaos Meter deaths](docs/images/comparisons/gui/chaos-meter-deaths-mcp.png)](docs/images/comparisons/gui/chaos-meter-deaths-mcp.png) |
+
+| Vanilla decisions                                                                                                                                        | Vanilla occupation                                                                                                                                             |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [![Decision window](docs/images/comparisons/native-ui/countrydecisionview-window.png)](docs/images/comparisons/native-ui/countrydecisionview-window.png) | [![Occupation window](docs/images/comparisons/native-ui/countryoccupationview-window.png)](docs/images/comparisons/native-ui/countryoccupationview-window.png) |
+
+The event log, status panel, decision and occupation previews use declared states or positions for layout review.
+They are source previews, not observations of a running campaign.
+See the [interface gallery](docs/gui-comparisons.md) for full images and fidelity notes, and the [GUI guide](docs/gui.md) for scenario inputs.
+
+### Maps and event chains
+
+> Find Brandenburg on the map, inspect its provinces and neighbours, and show the affected source files before a change.
+
+> Trace an event's options and follow-up events. Point out unresolved calls and link each route to its source.
+
+| Source map                                                                                                                      | Mod event chain                                                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [![Map rendered from installed source](docs/images/comparisons/source/map-mcp.png)](docs/images/comparisons/source/map-mcp.png) | [![Chaos Redux event options](docs/images/comparisons/source/event-chain-mcp.png)](docs/images/comparisons/source/event-chain-mcp.png) |
+
+The [map guide](docs/map.md) covers connected province, state, supply and railway data.
+The [event guide](docs/events.md) covers routes, scope, timing and unresolved references.
+
+### Local rules and AI weights
+
+> Find the installed documentation for `save_event_target_as`, read the relevant section, and show a vanilla usage with file and line references.
+
+> Compare this decision's `ai_will_do` score before and after a change in peace and war. List missing conditions separately from known results.
+
+The [reference example](docs/research/reference-benchmark.md) found the installed effect documentation first and read its relevant 12-line section instead of loading whole wiki pages.
+The [AI guide](docs/probability.md) covers supported weights, chance and timing models; a source score alone does not establish an AI click probability.
+The [examples guide](docs/examples.md) has more prompt details.
+
+## Complete tool list
+
+The default server exposes 35 tools.
+Your agent can select them from ordinary language; use the live tool schema for call parameters.
+
+| Tool                        | Purpose                                                                                                          |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `hoi4.focus_inspect`        | Read focus trees, continuous-focus placement, and structural or reference problems.                              |
+| `hoi4.focus_render`         | Produce fast HTML, SVG, JSON, and source-linked layout artifacts.                                                |
+| `hoi4.focus_raster`         | Produce a PNG preview with decoded source icons.                                                                 |
+| `hoi4.focus_rewrite`        | Create or update a focus tree.                                                                                   |
+| `hoi4.gui_inspect`          | Read a scripted GUI and its linked assets and logic.                                                             |
+| `hoi4.gui_render`           | Render generated and explicit GUI scenarios, states, resolutions, and layout diagnostics.                        |
+| `hoi4.gui_rewrite`          | Create or update a GUI source package.                                                                           |
+| `hoi4.map_inspect`          | Search, click, navigate, and inspect the complete rendered map and its linked data.                              |
+| `hoi4.map_render`           | Render full-map layers, overlays, names, IDs, coordinates, and source-linked catalogs.                           |
+| `hoi4.map_rewrite`          | Create or update states, provinces, IDs, networks, positions, and connected map data.                            |
+| `hoi4.reference_context`    | Get compact, cited wiki and installed documentation pointers for a modding surface.                              |
+| `hoi4.reference_search`     | Search local documentation in plain words or script names; each result names its answering line.                 |
+| `hoi4.reference_read`       | Read one revision-bound section, with line continuation.                                                         |
+| `hoi4.source_lookup`        | Find exact definitions, overrides and usages across game, DLC and mod, or the definition containing a file line. |
+| `hoi4.script_validate`      | Check snippet syntax, native command kinds, and declared scopes against local documentation.                     |
+| `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                                         |
+| `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.                          |
+| `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                                                  |
+| `hoi4.impact_inspect`       | Trace symbol and changed-file consumers across source systems and compare proposals.                             |
+| `hoi4.decision_inspect`     | Inventory and evaluate decisions or missions under declared scenarios and source changes.                        |
+| `hoi4.mechanic_test`        | Execute bounded source effects on a copied declared scenario and check assertions.                               |
+| `hoi4.package_check`        | Check declarative package definitions, calls, registrations, assets, and case links.                             |
+| `hoi4.scenario_test`        | Run named source and domain cases in resumable, revision-bound batches.                                          |
+| `hoi4.job_inspect`          | Inspect durable background work or retrieve its completed tool result.                                           |
+| `hoi4.job_cancel`           | Durably request cancellation of authorized background work.                                                      |
+| `hoi4.tech_inspect`         | Scan, trace, explain, lint, and assess technology and doctrine systems.                                          |
+| `hoi4.tech_render`          | Render source layouts with real item sizes and year guides, plus dependencies and assets.                        |
+| `hoi4.tech_compare`         | Compare technology graphs, placements, references, diagnostics, and source overlays.                             |
+| `hoi4.probability_inspect`  | Locate weighted logic and discover compatible adapters, candidates, and required inputs.                         |
+| `hoi4.probability_evaluate` | Evaluate supported weights, probability and timing models, and missing inputs.                                   |
+| `hoi4.probability_sweep`    | Find sensitivity, breakpoints, cliffs, and rank reversals across declared ranges.                                |
+| `hoi4.probability_simulate` | Run deterministic sampled analysis with confidence and convergence data.                                         |
+| `hoi4.probability_sequence` | Analyze declared recovery, caps, cooldowns, resets, timers, and terminal states.                                 |
+| `hoi4.probability_compare`  | Attribute AI-weight and MTTH changes between real or proposed source.                                            |
+| `hoi4.probability_render`   | Render cached rankings, matrices, timing, sensitivity, sequence, and comparisons.                                |
+
+Set `HOI4_AGENT_TOOLS_CHAOSX=1` to expose two optional Chaos Redux workflow tools: `chaosx.focus_country_assets` and `chaosx.visual_revision`.
+The [tool guide](docs/tools.md) explains results, linked artifacts and long operations.
 
 ## How it fits your workflow
 

package/dist/hoi4_agent_tools/core/configuration.js

@@ -81,6 +81,8 @@ export const workspaceRegistrationSchema = z
     root: z.string().min(1),
     kind: z.enum(['mod', 'game', 'dependency']).default('mod'),
     gameRoot: z.string().min(1).optional(),
+    /** Layer installed `dlc/` and `integrated_dlc/` folders between the game and mods. */
+    includeGameDlc: z.boolean().default(true),
     dependencyRoots: z.array(z.string().min(1)).max(WORKSPACE_MAX_SOURCE_ROOTS).default([]),
     dependencies: z.array(dependencyRegistrationSchema).max(WORKSPACE_MAX_SOURCE_ROOTS).default([]),
     replacePaths: z.array(relativeRootPathSchema).max(WORKSPACE_MAX_PATHS).default([]),

package/dist/hoi4_agent_tools/core/engine.js

@@ -182,13 +182,6 @@ export class CoreEngine {
                         signal: controller.signal,
                     });
                     controller.signal.throwIfAborted();
-                    const persistentAnalysisCache = await this.persistentAnalysisCache;
-                    const analysisScope = {
-                        workspaceIdentity: workspace.workspaceIdentity,
-                        rootFingerprint: transactionRootFingerprint(workspace),
-                        principal: principal ?? null,
-                    };
-                    await persistentAnalysisCache?.hydrate(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
                     const revision = hashCanonical(files.map(({ absolutePath, displayPath, relativePath, rootKind, loadOrder, shadowedBy, sha256, }) => ({
                         absolutePath,
                         displayPath,
@@ -202,6 +195,13 @@ export class CoreEngine {
                     const cached = this.#scanCache.get(cacheKey);
                     if (cached !== undefined)
                         return cached;
+                    const persistentAnalysisCache = await this.persistentAnalysisCache;
+                    const analysisScope = {
+                        workspaceIdentity: workspace.workspaceIdentity,
+                        rootFingerprint: transactionRootFingerprint(workspace),
+                        principal: principal ?? null,
+                    };
+                    await persistentAnalysisCache?.hydrate(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
                     const index = await SymbolIndex.buildAsync(files, controller.signal, this.indexSegments);
                     await persistentAnalysisCache?.persist(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
                     const snapshot = {

package/dist/hoi4_agent_tools/core/file-glob.js

@@ -0,0 +1,164 @@
+import path from 'node:path';
+import { escape, globIterate, hasMagic, Ignore, unescape } from 'glob';
+import { lstat, readdir } from 'node:fs/promises';
+import { ServiceError } from './result.js';
+function validatePatterns(patterns) {
+    if (patterns.length > 8192)
+        throw new ServiceError('SCAN_PATTERN_LIMIT', 'Too many source glob patterns');
+    let wildcardCount = 0;
+    for (const pattern of patterns) {
+        if (Buffer.byteLength(pattern, 'utf8') > 4096)
+            throw new ServiceError('SCAN_PATTERN_LIMIT', 'Source glob pattern exceeds its byte limit');
+        if (pattern.startsWith('/') ||
+            /^[A-Za-z]:/u.test(pattern) ||
+            pattern.split('/').includes('..') ||
+            pattern.includes('\0'))
+            throw new ServiceError('SCAN_PATTERN_ESCAPE', 'Source glob patterns must stay relative to the authorized root');
+        let depth = 0;
+        const groups = [];
+        let expansions = 1;
+        for (let index = 0; index < pattern.length; index++) {
+            const character = pattern[index];
+            if (character === '\\') {
+                index++;
+                continue;
+            }
+            if (character === '{') {
+                if (++depth > 8)
+                    throw new ServiceError('SCAN_PATTERN_LIMIT', 'Source glob brace nesting exceeds its limit');
+                groups.push({ start: index + 1, choices: 1 });
+            }
+            if (character === ',' && groups.length > 0)
+                groups.at(-1).choices++;
+            if (character === '}') {
+                depth = Math.max(0, depth - 1);
+                const group = groups.pop();
+                if (group === undefined)
+                    continue;
+                const range = /^(-?\d+|[A-Za-z])\.\.(-?\d+|[A-Za-z])(?:\.\.(-?\d+))?$/u.exec(pattern.slice(group.start, index));
+                if (range !== null) {
+                    const first = /^-?\d+$/u.test(range[1]) ? Number(range[1]) : range[1].charCodeAt(0);
+                    const last = /^-?\d+$/u.test(range[2]) ? Number(range[2]) : range[2].charCodeAt(0);
+                    const step = Math.abs(Number(range[3] ?? 1));
+                    group.choices = Math.floor(Math.abs(last - first) / step) + 1;
+                }
+                expansions *= group.choices;
+                if (!Number.isSafeInteger(expansions) || expansions > 128)
+                    throw new ServiceError('SCAN_PATTERN_LIMIT', 'Source glob expansion exceeds its limit');
+            }
+        }
+        // Validate brace complexity before invoking the glob parser, which can expand braces.
+        if (hasMagic(pattern, { magicalBraces: true }) && ++wildcardCount > 512)
+            throw new ServiceError('SCAN_PATTERN_LIMIT', 'Too many wildcard source glob patterns');
+    }
+}
+/** Relative, cancellable enumeration without traversing symbolic-link directories. */
+export async function* iterateFiles(patterns, options) {
+    validatePatterns(patterns);
+    validatePatterns(options.ignore ?? []);
+    options.signal?.throwIfAborted();
+    const nocase = options.caseSensitive === false;
+    const excluded = new Ignore([...(options.ignore ?? [])], { nocase });
+    const seen = new Set();
+    const allowedPatterns = [];
+    for (const pattern of new Set(patterns)) {
+        let current = options.cwd;
+        let allowed = true;
+        let literal = true;
+        let finalIsFile = false;
+        for (const part of pattern.split('/')) {
+            if (hasMagic(part, { magicalBraces: true })) {
+                literal = false;
+                break;
+            }
+            let name = unescape(part);
+            let candidate = path.resolve(current, name);
+            const relative = path.relative(options.cwd, candidate).replaceAll('\\', '/');
+            if (relative === '..' || relative.startsWith('../') || path.isAbsolute(relative))
+                throw new ServiceError('SCAN_PATTERN_ESCAPE', 'Literal glob prefix escaped its authorized root');
+            let metadata;
+            try {
+                metadata = await lstat(candidate);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT' &&
+                    error.code !== 'ENOTDIR')
+                    throw error;
+                if (!nocase) {
+                    allowed = false;
+                    break;
+                }
+                try {
+                    name =
+                        (await readdir(current)).find((entry) => entry.toLowerCase() === name.toLowerCase()) ??
+                            name;
+                    candidate = path.resolve(current, name);
+                    metadata = await lstat(candidate);
+                }
+                catch {
+                    allowed = false;
+                    break;
+                }
+            }
+            if (metadata.isSymbolicLink()) {
+                allowed = false;
+                break;
+            }
+            finalIsFile = metadata.isFile();
+            current = candidate;
+        }
+        if (!allowed)
+            continue;
+        if (literal) {
+            if (!finalIsFile)
+                continue;
+            const relative = path.relative(options.cwd, current).replaceAll('\\', '/');
+            if (excluded.relative.some((rule) => rule.match(relative)) ||
+                excluded.absolute.some((rule) => rule.match(current)))
+                continue;
+            options.signal?.throwIfAborted();
+            if (!seen.has(relative)) {
+                seen.add(relative);
+                yield relative;
+            }
+        }
+        else
+            allowedPatterns.push(pattern);
+    }
+    if (allowedPatterns.length === 0)
+        return;
+    const matches = globIterate(allowedPatterns, {
+        cwd: options.cwd,
+        withFileTypes: true,
+        nodir: true,
+        dot: false,
+        follow: false,
+        nocase,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ignore: {
+            ignored: (entry) => entry.isSymbolicLink() || excluded.ignored(entry),
+            childrenIgnored: (entry) => entry.isSymbolicLink() || excluded.childrenIgnored(entry),
+        },
+    });
+    for await (const entry of matches) {
+        options.signal?.throwIfAborted();
+        if (!entry.isFile() || entry.isSymbolicLink())
+            continue;
+        const relative = path.relative(options.cwd, entry.fullpath()).replaceAll('\\', '/');
+        if (relative === '..' || relative.startsWith('../') || path.isAbsolute(relative))
+            throw new ServiceError('SCAN_PATTERN_ESCAPE', 'Glob result escaped its authorized root');
+        if (!seen.has(relative)) {
+            seen.add(relative);
+            yield relative;
+        }
+    }
+}
+export async function globFiles(patterns, options) {
+    const files = [];
+    for await (const file of iterateFiles(patterns, options))
+        files.push(file);
+    return files;
+}
+export function escapeFileGlob(relativePath) {
+    return escape(relativePath, { magicalBraces: true });
+}

package/dist/hoi4_agent_tools/core/index-segments.js

@@ -38,6 +38,10 @@ export class IndexSegmentCache {
         this.#entries.set(address, entry);
         return JSON.parse(entry.encoded);
     }
+    /** Availability check without decoding or cache-hit accounting. */
+    has(address) {
+        return this.#entries.has(address);
+    }
     /** Import one authenticated canonical entry without counting it as a process-local hit. */
     importEncoded(address, encoded) {
         const segment = JSON.parse(encoded);

package/dist/hoi4_agent_tools/core/job-operation-registration.js

@@ -0,0 +1,31 @@
+import { JobOperations } from './job-executor.js';
+import { ServiceError } from './result.js';
+/** Load one trusted domain after the authenticated job identifies its operation. */
+export async function registerWorkerOperations(engine, toolName) {
+    const operations = new JobOperations();
+    if (toolName.startsWith('hoi4.event_'))
+        (await import('../event/job-operations.js')).registerEventJobs(operations, engine);
+    else if (toolName.startsWith('hoi4.focus_'))
+        (await import('../focus/job-operations.js')).registerFocusJobs(operations, engine);
+    else if (toolName.startsWith('hoi4.gui_'))
+        (await import('../gui/job-operations.js')).registerGuiJobs(operations, engine);
+    else if (toolName.startsWith('hoi4.map_'))
+        (await import('../map/job-operations.js')).registerMapJobs(operations, engine);
+    else if (toolName.startsWith('hoi4.probability_'))
+        (await import('../probability/job-operations.js')).registerProbabilityJobs(operations, engine);
+    else if (toolName.startsWith('hoi4.tech_'))
+        (await import('../technology/job-operations.js')).registerTechnologyJobs(operations, engine);
+    else if ([
+        'hoi4.impact_inspect',
+        'hoi4.decision_inspect',
+        'hoi4.mechanic_test',
+        'hoi4.package_check',
+        'hoi4.scenario_test',
+    ].includes(toolName))
+        (await import('./analysis-job-operations.js')).registerAnalysisJobs(operations, engine);
+    else
+        throw new ServiceError('JOB_OPERATION_UNAVAILABLE', 'No trusted worker domain matches this job');
+    // A matching prefix never authorizes an unknown suffix or a client-selected module.
+    operations.get(toolName);
+    return operations;
+}

package/dist/hoi4_agent_tools/core/job-store.js

@@ -1,10 +1,10 @@
 import { lstat, mkdir, open, opendir, rename, unlink } from 'node:fs/promises';
 import path from 'node:path';
 import { hostname } from 'node:os';
-import { setTimeout as delay } from 'node:timers/promises';
 import { z } from 'zod/v4';
 import { canonicalJson, hashCanonical, secureId } from './canonical.js';
 import { ServiceError } from './result.js';
+import { retryWindowsSharing } from './windows-sharing.js';
 import { SharedRequestCapacity } from './shared-request-capacity.js';
 import { containedGeneratedPath } from './workspace.js';
 import { PACKAGE_VERSION } from '../version.js';
@@ -248,26 +248,8 @@ async function assertUnlinked(file) {
 }
 /** Atomic replacement with a finite retry for Windows sharing violations. */
 export async function publishJobRecord(temporary, target, options = {}) {
-    const platform = options.platform ?? process.platform;
-    const publish = options.publish ?? rename;
-    const wait = options.wait ?? delay;
-    const maxAttempts = options.maxAttempts ?? 100;
-    if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1)
-        throw new RangeError('Job record publication attempts must be a positive integer');
-    for (let attempt = 1;; attempt += 1) {
-        try {
-            await publish(temporary, target);
-            return;
-        }
-        catch (error) {
-            const code = error.code ?? '';
-            if (platform !== 'win32' ||
-                !['EPERM', 'EBUSY', 'EACCES'].includes(code) ||
-                attempt >= maxAttempts)
-                throw error;
-            await wait(10);
-        }
-    }
+    const { publish = rename, ...retry } = options;
+    await retryWindowsSharing(() => publish(temporary, target), retry);
 }
 /** Internal durable job records. Callers must obtain scopes from the authorized workspace resolver. */
 export class JobStore {
@@ -376,22 +358,14 @@ export class JobStore {
             if (!['completed', 'cancelled', 'failed'].includes(record.status))
                 throw new ServiceError('JOB_STATE_CONFLICT', 'Only a terminal job record can be removed by retention cleanup');
             const file = await this.recordPath(scope, id);
-            for (let attempt = 1;; attempt += 1) {
-                signal.throwIfAborted();
-                try {
-                    await unlink(file);
-                    return true;
-                }
-                catch (error) {
-                    const code = error.code ?? '';
-                    if (code === 'ENOENT')
-                        return false;
-                    if (process.platform !== 'win32' ||
-                        !['EPERM', 'EBUSY', 'EACCES'].includes(code) ||
-                        attempt >= 100)
-                        throw error;
-                    await delay(10);
-                }
+            try {
+                await retryWindowsSharing(() => unlink(file), { signal });
+                return true;
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return false;
+                throw error;
             }
         });
     }
@@ -573,11 +547,16 @@ export class JobStore {
     async readEnvelope(file, id, scopeHash) {
         let handle;
         try {
-            handle = await open(file, 'r');
+            // A record being replaced is briefly delete-pending on Windows. Release the
+            // handle before parsing so a slow reader never blocks a concurrent publication.
+            handle = await retryWindowsSharing(() => open(file, 'r'));
             const metadata = await handle.stat();
             if (!metadata.isFile() || metadata.size > this.maxRecordBytes)
                 throw new ServiceError('JOB_RECORD_INVALID', 'Persistent job record exceeds its storage budget or is not a file');
-            const parsed = envelopeSchema.safeParse(JSON.parse(await handle.readFile('utf8')));
+            const text = await handle.readFile('utf8');
+            await handle.close();
+            handle = undefined;
+            const parsed = envelopeSchema.safeParse(JSON.parse(text));
             if (!parsed.success ||
                 parsed.data.record.id !== id ||
                 hashCanonical(parsed.data.record.scope) !== scopeHash ||
@@ -632,7 +611,7 @@ export class JobStore {
         }
         finally {
             await handle?.close();
-            await unlink(temporary).catch((error) => {
+            await retryWindowsSharing(() => unlink(temporary)).catch((error) => {
                 if (error.code !== 'ENOENT')
                     throw error;
             });