hoi4-agent-tools 3.6.0 → 3.7.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 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
 
@@ -16,37 +17,130 @@ Add the printed configuration to your MCP client and open your mod as its worksp
 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
+| Tree or branch   | Supplied in-game capture                                                                                              | MCP source preview                                                                                                 |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Fury             | [![Fury in game](docs/images/comparisons/fury-ingame.png)](docs/images/comparisons/fury-ingame.png)                   | [![Fury focus tree](docs/images/comparisons/fury-mcp.png)](docs/images/comparisons/fury-mcp.png)                   |
+| Holy Realm       | [![Holy Realm in game](docs/images/comparisons/holy-realm-ingame.png)](docs/images/comparisons/holy-realm-ingame.png) | [![Holy Realm focus tree](docs/images/comparisons/holy-realm-mcp.png)](docs/images/comparisons/holy-realm-mcp.png) |
+| Utopia Manifesto | [![Utopia in game](docs/images/comparisons/utopia-ingame.png)](docs/images/comparisons/utopia-ingame.png)             | [![Utopia focus tree](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                                                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Infantry         | [![Infantry 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)                    |
+| Chemical warfare | [![Chemical folder in game](docs/images/comparisons/chemical-recent-ingame.png)](docs/images/comparisons/chemical-recent-ingame.png) | [![Chemical folder preview](docs/images/comparisons/chemical-historical-mcp.png)](docs/images/comparisons/chemical-historical-mcp.png) |
+
+The chemical comparison uses the source revision recorded with the screenshot and includes wide equipment cards.
+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                                                                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| 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)          |
+| Škoda Priority          | [![Škoda Priority in game](docs/images/comparisons/gui/skoda-priority-ingame.png)](docs/images/comparisons/gui/skoda-priority-ingame.png) | [![Škoda Priority preview](docs/images/comparisons/gui/skoda-priority-mcp.png)](docs/images/comparisons/gui/skoda-priority-mcp.png) |
+| Chaos Redux Tag Manager | [![Tag Manager in game](docs/images/comparisons/gui/tag-manager-ingame.png)](docs/images/comparisons/gui/tag-manager-ingame.png)          | [![Tag Manager preview](docs/images/comparisons/gui/tag-manager-mcp.png)](docs/images/comparisons/gui/tag-manager-mcp.png)          |
+
+The Tag Manager screenshot comes from an older layout.
+The Options preview has no observed gamma value, and Škoda's game capture frames its background differently.
+
+| Event Log                                                                                                            | Chaos Meter: status                                                                                                                     | Chaos Meter: deaths                                                                                                                     |
+| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| [![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, Chaos Meter, 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                                                                                                                      | Chaos Redux 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 bounded local documentation sections.                                                 |
+| `hoi4.reference_read`       | Read one revision-bound section, with line continuation.                                     |
+| `hoi4.source_lookup`        | Find exact definitions, overrides, usages, and narrow source blocks.                         |
+| `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/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-worker-host.js

@@ -149,9 +149,11 @@ export class JobWorkerHost {
             stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
             windowsHide: true,
         });
+        let phase = 'waiting_for_ready';
+        let acknowledgmentTimer;
         const initialized = new Promise((resolve, reject) => {
             child.once('error', reject);
-            child.once('exit', () => reject(new ServiceError('JOB_WORKER_STARTUP_EXIT', 'The worker exited before completing its readiness handshake')));
+            child.once('exit', (code, signal) => reject(new ServiceError('JOB_WORKER_STARTUP_EXIT', `The worker exited before completing its startup handshake (phase ${phase}, exit ${code ?? 'none'}, signal ${signal ?? 'none'})`)));
             child.once('message', (value) => {
                 void (async () => {
                     if (typeof value !== 'object' ||
@@ -162,7 +164,23 @@ export class JobWorkerHost {
                         throw new ServiceError('JOB_WORKER_PROTOCOL', 'The worker did not provide its readiness handshake');
                     await lease.handoffToProcess(child.pid);
                     await new Promise((resolve, reject) => {
-                        child.once('disconnect', resolve);
+                        phase = 'waiting_for_acceptance';
+                        acknowledgmentTimer = setTimeout(() => reject(new ServiceError('JOB_WORKER_ACCEPT_TIMEOUT', 'The worker did not acknowledge receipt within its startup window')), 30_000);
+                        child.once('message', (accepted) => {
+                            if (typeof accepted !== 'object' ||
+                                accepted === null ||
+                                !('type' in accepted) ||
+                                accepted.type !== 'accepted') {
+                                reject(new ServiceError('JOB_WORKER_PROTOCOL', 'The worker did not acknowledge the dispatched job'));
+                                return;
+                            }
+                            phase = 'accepted';
+                            // Only close IPC after the child confirms receipt. The persistent job,
+                            // rather than the launcher's lifetime, owns execution after this point.
+                            if (child.connected)
+                                child.disconnect();
+                            resolve();
+                        });
                         child.send({
                             configuration: {
                                 ...configuration,
@@ -178,14 +196,7 @@ export class JobWorkerHost {
                             jobId: id,
                             ...(principal === undefined ? {} : { principal }),
                         }, (error) => {
-                            if (error === null) {
-                                // IPC is startup-only. Closing it after dispatch prevents launcher
-                                // lifetime from becoming an implicit cancellation channel.
-                                if (child.connected)
-                                    child.disconnect();
-                                resolve();
-                            }
-                            else
+                            if (error !== null)
                                 reject(error);
                         });
                     });
@@ -199,7 +210,12 @@ export class JobWorkerHost {
                 });
             });
         });
-        await initialized;
+        try {
+            await initialized;
+        }
+        finally {
+            clearTimeout(acknowledgmentTimer);
+        }
         for (;;) {
             const record = await this.jobs.get(workspaceId, id, principal);
             if (['completed', 'failed', 'cancelled'].includes(record.status))

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

@@ -1,16 +1,10 @@
 import { z } from 'zod/v4';
 import { serverConfigurationSchema } from './configuration.js';
 import { CoreEngine } from './engine.js';
-import { JobExecutor, JobOperations } from './job-executor.js';
+import { JobExecutor } from './job-executor.js';
 import { JobService } from './job-service.js';
 import { WorkspaceResolver } from './workspace.js';
-import { registerEventJobs } from '../event/job-operations.js';
-import { registerFocusJobs } from '../focus/job-operations.js';
-import { registerGuiJobs } from '../gui/job-operations.js';
-import { registerMapJobs } from '../map/job-operations.js';
-import { registerProbabilityJobs } from '../probability/job-operations.js';
-import { registerTechnologyJobs } from '../technology/job-operations.js';
-import { registerAnalysisJobs } from './analysis-job-operations.js';
+import { registerWorkerOperations } from './job-operation-registration.js';
 // Fixed internal process entry point. It accepts only a trusted host's structured IPC
 // message, never a script path, module name, callback, command, or transport request.
 const inputSchema = z
@@ -38,19 +32,17 @@ process.once('message', (value) => {
     clearTimeout(startup);
     void (async () => {
         const input = inputSchema.parse(value);
+        // The send callback confirms enqueueing, not receipt. Acknowledge before the host
+        // disconnects; losing that channel after receipt never cancels durable execution.
+        if (process.connected)
+            process.send?.({ type: 'accepted' }, () => undefined);
         const resolver = await WorkspaceResolver.create(input.configuration);
         const engine = new CoreEngine(resolver);
         // Recovery is targeted by the job executor. Do not sweep or interfere with
         // unrelated live rewrite journals when a worker starts.
         const jobs = await JobService.create(resolver);
-        const operations = new JobOperations();
-        registerEventJobs(operations, engine);
-        registerAnalysisJobs(operations, engine);
-        registerTechnologyJobs(operations, engine);
-        registerProbabilityJobs(operations, engine);
-        registerMapJobs(operations, engine);
-        registerGuiJobs(operations, engine);
-        registerFocusJobs(operations, engine);
+        const record = await jobs.get(input.workspaceId, input.jobId, input.principal);
+        const operations = await registerWorkerOperations(engine, record.request.toolName);
         await new JobExecutor(engine, jobs, operations).run(input.workspaceId, input.jobId, input.principal);
     })()
         .catch(() => {