hoi4-agent-tools 4.0.0 → 4.0.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 4.0.1 - 2026-10-12
+
+- Clean temporary test fixtures after each test, suite teardown and normal process exit. Reject fixture truncation above a 256 MiB aggregate disk budget before Windows allocates the file.
+- Recover stale reference-source and random-name event-evaluation scratch on startup after three hours, with local process leases, lock and canonical-path checks. Evict dead owners oldest first under a 256 MiB scratch cap; preserve live owners and dated benchmark evidence.
+- Document the leak's test-fixture origin. MCP reference lookup already reads configured sources directly and uses the shared persistent analysis cache; it does not copy a source tree per call or process.
+- Describe modding tasks in plain language across the README, guides, package metadata and MCP tool descriptions.
+
+### GUI render
+
+- Decode uncompressed 16-bit RGB DDS portraits, including the 5:5:5 format used by vanilla leaders; truncated pixel data remains unsupported.
+- Preserve declared font colours when a same-name bitmap atlas is loaded, including the dark super-event description font. Atlas metadata no longer outranks a named font declaration, and source links retain that declaration.
+- `hoi4.gui_render` and `hoi4.gui_inspect` model the engine-controlled branches of `countrypoliticsview` instead of drawing all of them: no faction, faction leader, faction member and balance of power are chosen from the scenario country (`tag`, `ideology`, `faction`, `balanceOfPower`, or its `history/countries` facts at the scenario date), and `pol_faction_icon` follows the ruling ideology instead of its static frame. Explicit scenario visibility, values and selected frames still win.
+- GUI text keys are matched without regard to case, so a window that spells `buttontext` in lower case (the vanilla trade window) shows its localised label instead of the key.
+- Element visibility honours `show` as well as `visible`, `hide` and `hidden`, and scenario `name.visible` values may be yes/no words or 1/0 as well as booleans.
+
+### Job workers
+
+- Uncaught worker failures log only a bounded diagnostic code; exception messages, stacks and thrown values are excluded to protect source text and credentials.
+- A worker that stops without a result is now reported by its real cause. The host keeps each worker's exit code, signal and last standard error and fails the job with `JOB_WORKER_EXIT` naming a V8 heap limit (with its size), a native out-of-memory, a native crash, an external termination, a stop by the server's own deadline, or an uncaught job error with its error code. Earlier releases discarded this and always suggested that memory ran out. Logs of workers that ended unexpectedly are kept, newest ten, in `job-workers/logs` under the server state root.
+- Workers start with a V8 heap ceiling of a quarter of physical memory, between 2,048 and 8,192 MiB, when `jobWorkerMaxHeapMiB` is not set. Node's own default tops out near 4.5 GB, which a large GUI render on a big mod can approach.
+- `hoi4.gui_render` rasterizes its derived variants, the comparison renders and the galleries one at a time instead of together, which lowers the peak native memory of a render.
+
 ## 4.0.0 - 2026-10-10
 
 ### Known mistakes

package/README.md

@@ -1,32 +1,26 @@
 # HOI4 Agent Tools
 
+<!-- TODO-VIDEO-LINK: replace with the promo video URL -->
+
+[![Watch the HOI4 Agent Tools demo](docs/images/agent-tools-demo-thumbnail.png)](https://www.youtube.com/@ChaosRedux)
+
 [![npm](https://img.shields.io/npm/v/hoi4-agent-tools)](https://www.npmjs.com/package/hoi4-agent-tools)
 [![Node.js](https://img.shields.io/node/v/hoi4-agent-tools)](https://nodejs.org/)
 [![License](https://img.shields.io/npm/l/hoi4-agent-tools)](LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/rAXesGcT2t)
+[![YouTube](https://img.shields.io/badge/YouTube-Chaos%20Redux-ff0000?logo=youtube&logoColor=white)](https://www.youtube.com/@ChaosRedux)
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support%20the%20Project-ff5e5b?logo=kofi&logoColor=white)](https://ko-fi.com/klimpaskov)
+[![Download](https://img.shields.io/github/v/release/klimPaskov/hoi4-agent-tools?label=Release&logo=github&color=2ea44f)](https://github.com/klimPaskov/hoi4-agent-tools/releases/latest)
+[![Issues](https://img.shields.io/badge/Bugs%20%26%20Ideas-Issues-24292f?logo=github&logoColor=white)](https://github.com/klimPaskov/hoi4-agent-tools/issues)
 
-An [MCP](https://modelcontextprotocol.io/) server that lets a coding agent such as Claude Code, Codex or Cursor read, preview, analyse and safely edit a Hearts of Iron IV mod.
-Your agent gets cited answers from the game's own documentation, pictures of focus trees, technology folders, interfaces and maps, and checks that catch load errors before you launch the game.
-
-[![A large focus tree rendered from mod source](docs/images/comparisons/holy-realm-mcp.png)](docs/images/comparisons/holy-realm-mcp.png)
+An [MCP](https://modelcontextprotocol.io/) server that helps coding agents build and edit Hearts of Iron IV mods.
+Make focus trees, events and decisions. Edit maps and generate a new world. Preview windows, trees and maps, find the right rule in the docs, fix broken script and balance AI choices.
 
 ## What it does
 
-| Area                   | Ask your agent, for example                                                                                |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
-| Find the rule          | "Find the installed documentation for `save_event_target_as` and show a vanilla usage with file and line." |
-| Check before launch    | "Check `events/my_events.txt` for scope errors, then group the last `error.log` by category."              |
-| See the tree           | "Render this mod's largest focus tree and list focuses with missing icons."                                |
-| Preview the window     | "Preview this scripted GUI at 100% and 125% UI scale and check for clipped text."                          |
-| Read the map           | "Find Brandenburg, list its provinces and neighbours, and show the files a change would touch."            |
-| Reshape the map        | "Split Brandenburg in two and update every event and focus that names it."                                 |
-| Build a new world      | "Create a 2048x1024 world with six countries, then list what still needs hand-made content."               |
-| Follow the events      | "Trace this event's options and follow-up events and point out unresolved calls."                          |
-| Weigh the AI           | "Show the AI weights of event `my_mod.12`'s options, then compare them before and after my change."        |
-| Plan new content       | "Give me the next free event ID in my namespace and summarize what the mod defines."                       |
-| Edit with a safety net | "Add a new branch to this focus tree" — the edit is validated before anything is written.                  |
-
-The server never launches the game.
-Previews and tests are built from source files, so they show what the source says, not what a running campaign did.
+Your agent can build and edit focus trees, events, decisions and maps, and generate a new world.
+It previews focus trees, technology folders, windows and maps, finds the right rule in the game's documentation, fixes broken script and tunes AI choices.
+You describe what you want; the agent picks the right tools.
 
 ## Quick start
 
@@ -45,14 +39,17 @@ Previews and tests are built from source files, so they show what the source say
 
    Paste the `globalInstall` block into a JSON client such as Claude Code, Claude Desktop or Cursor, or the `codexTomlGlobal` block into Codex's `config.toml`.
 
-4. Open your mod folder as the agent's workspace and try: "Render this mod's largest focus tree."
+4. Open your mod folder as the agent's workspace and tell it what you want to build or fix.
 
 The [setup guide](docs/setup.md) covers several mods, explicit game paths, local wiki snapshots and troubleshooting with `--discover` and `--diagnose`.
 
-[Watch the Agent Tools demo](https://github.com/klimPaskov/Agentic-HOI4-Modding/releases/latest/download/hoi4_agent_tools_promo.mp4) or use [HOI4 Mod Setup](https://github.com/klimPaskov/HOI4-Mod-Setup/releases/latest) to install and register the verified server for your mod.
+[Watch the Agent Tools demo](https://github.com/klimPaskov/Agentic-HOI4-Modding/releases/latest/download/hoi4_agent_tools_promo.mp4) or use [HOI4 Mod Setup](https://github.com/klimPaskov/HOI4-Mod-Setup/releases/latest) to install and connect the server for your mod.
+Part of the HOI4 modding toolkit with [Agentic HOI4 Modding](https://github.com/klimPaskov/Agentic-HOI4-Modding) (skills and instructions for your agent) and [HOI4 Live Tools](https://github.com/klimPaskov/HOI4-Live-Tools) (testing in the running game).
 
 ## Examples
 
+[![A large focus tree rendered from mod source](docs/images/comparisons/holy-realm-mcp.png)](docs/images/comparisons/holy-realm-mcp.png)
+
 Each pair shows a capture from the game next to the server's preview of the same source.
 
 | In game                                                                                                                                | Server preview                                                                                                                   |
@@ -61,40 +58,19 @@ Each pair shows a capture from the game next to the server's preview of the same
 | [![Infantry technology folder in game](docs/images/comparisons/infantry-ingame.png)](docs/images/comparisons/infantry-ingame.png)      | [![Infantry technology folder preview](docs/images/comparisons/infantry-mcp.png)](docs/images/comparisons/infantry-mcp.png)      |
 | [![Video options in game](docs/images/comparisons/gui/options-video-ingame.png)](docs/images/comparisons/gui/options-video-ingame.png) | [![Video options preview](docs/images/comparisons/gui/options-video-mcp.png)](docs/images/comparisons/gui/options-video-mcp.png) |
 
-In focus previews, dotted lines mark alternative prerequisites: any one of them unlocks the focus.
-The focus screen in the game has its own framing, labels and icons, and the video options preview has no observed gamma value.
-More comparisons, with their source revisions and fidelity notes, are in the [focus and technology gallery](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/visual-comparisons.md), the [interface gallery](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/gui-comparisons.md) and the [examples guide](docs/examples.md), which also shows map and event renders.
+See more in the [examples gallery](docs/examples.md).
 
 ## Tools
 
-The default server has 28 tools.
-Agents pick them from ordinary language, so you rarely need their names.
-
-| Area                        | Tools                                                                                                                   | Writes                  |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| References and source       | `reference_context`, `reference_search`, `reference_read`, `source_lookup`, `script_validate`, `error_log`, `mod_index` | —                       |
-| Focus trees                 | `focus_inspect`, `focus_render`, `focus_rewrite`                                                                        | review files; mod files |
-| Scripted GUIs               | `gui_inspect`, `gui_render`, `gui_rewrite`                                                                              | review files; mod files |
-| Maps                        | `map_inspect`, `map_rewrite`                                                                                            | review files; mod files |
-| Events                      | `event_inspect`, `event_render`                                                                                         | —                       |
-| Technology and doctrines    | `tech_inspect`, `tech_render`                                                                                           | —                       |
-| AI weights and timing       | `probability_inspect`, `probability_analyze`                                                                            | —                       |
-| Decisions, impact and tests | `impact_inspect`, `decision_inspect`, `mechanic_test`, `package_check`, `scenario_test`                                 | —                       |
-| Background jobs             | `job_inspect`, `job_cancel`                                                                                             | job state               |
-
-Every name starts with `hoi4.`.
-"Review files" are images and reports in the server's own storage; only the three `*_rewrite` tools change mod files.
-The [tool reference](docs/tools.md) gives each tool's purpose, prompts, resources and long-running behaviour.
-
-## Safety and limits
-
-- The server reads the mod, its dependencies, the installed game, local reference folders and the game's error log.
-- Inspection and rendering never change mod files.
-  The focus, GUI and map rewrite tools validate a proposed edit before writing it and write it as a journaled transaction, so an interrupted write is restored rather than left half-applied.
-- Large renders and reports are stored as linked files, and documentation is returned as cited sections rather than whole manuals.
-- The server does not launch or control the game.
-  Previews and source tests cannot prove live clicks, AI choices or engine timing; a source score alone does not establish an AI click probability.
-- Your repository instructions and review process still apply.
+The server gives your agent previews, documentation, script analysis and editing tools.
+The agent combines them with its file editor to build events and decisions, repair scripts and adjust AI weights.
+The [tool reference](docs/tools.md) lists exact names, arguments and results for integrations.
+
+## FAQ
+
+**Where do edits go?** Changes are written to your mod folder; use Git to review or undo them.
+
+**Does it run the game?** No. Previews come from mod source; test gameplay in HOI4 to see live clicks, AI choices and timing.
 
 ## Configuration
 

package/dist/hoi4_agent_tools/core/condition-evaluator.js

@@ -176,6 +176,24 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
         const malformed = malformedBlock(assignment.value, candidate);
         if (malformed !== undefined)
             return malformed;
+        if (key === 'has_country_flag' || key === 'has_global_flag' || key === 'has_state_flag') {
+            // The block form tests a flag's stored value. A scenario declares that value as a number
+            // under `flag.<name>` (or `global_flag.<name>` for global flags).
+            const flag = firstScalar(assignment.value, 'flag')?.value;
+            const expected = firstScalar(assignment.value, 'value')?.value;
+            if (flag !== undefined) {
+                const names = key === 'has_global_flag' ? [`global_flag.${flag}`, `flag.${flag}`] : [`flag.${flag}`];
+                for (const name of names) {
+                    const declared = scopeStateValue(scenario, name, scopeContext);
+                    if (typeof declared === 'number' && expected !== undefined)
+                        return { state: declared === Number(expected) ? 'true' : 'false', unresolved: [] };
+                    if (typeof declared === 'boolean' && expected === undefined)
+                        return { state: declared ? 'true' : 'false', unresolved: [] };
+                }
+                if (expected !== undefined)
+                    return unresolved(assignment, candidate, `Scenario does not declare the value of flag ${flag}`, `flag.${flag}`);
+            }
+        }
         if (key === 'AND' ||
             key === 'hidden_trigger' ||
             key === 'custom_trigger_tooltip' ||

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

@@ -1,5 +1,7 @@
 import { spawn } from 'node:child_process';
+import { closeSync, fstatSync, openSync, readSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
 import { JobService } from './job-service.js';
@@ -9,11 +11,15 @@ import { SharedRequestCapacity } from './shared-request-capacity.js';
 import { containedGeneratedPath } from './workspace.js';
 import { ServiceError } from './result.js';
 import { isDomainToolName } from './domain-tools.js';
+import { classifyWorkerExit, defaultWorkerHeapMiB, } from './worker-exit.js';
 const maximumCheckpointRecoveries = 2;
 const maximumPreDispatchRecoveries = 2;
-/** An exit with no outcome is most often the worker running out of memory on a large mod. */
-const WORKER_EXIT_HINT = '; if the mod is large the worker may have run out of memory, so retry the call or raise jobWorkerMaxHeapMiB';
-const WORKER_EXIT_MESSAGE = `The worker stopped without publishing a terminal job outcome${WORKER_EXIT_HINT}`;
+/** Used only when the exit status of the worker is unknown to this process. */
+const WORKER_EXIT_MESSAGE = 'The worker stopped without publishing a terminal job outcome; its exit status is not available to this server, so retry the call';
+/** Bytes of a worker's standard error read back when it exits unexpectedly. */
+const STDERR_TAIL_BYTES = 16_384;
+/** Standard-error logs of workers that exited unexpectedly kept for diagnosis. */
+const RETAINED_STDERR_LOGS = 10;
 // Native and IPC codes are fixed vocabulary. Error messages can contain paths or source
 // text, so only an allowlisted code and the fixed coordination stage are reported.
 const nativeFailureCodes = new Set([
@@ -62,13 +68,68 @@ export function workerFailure(error, stage) {
         };
 }
 /** Stop a supervised worker and wait, bounded, until the operating system reports its exit. */
-async function stopChild(child) {
+async function stopChild(child, stopped) {
     if (child.exitCode !== null || child.signalCode !== null)
         return;
+    stopped?.add(child);
     const exited = new Promise((resolve) => child.once('exit', () => resolve()));
     child.kill('SIGKILL');
     await Promise.race([exited, delay(10_000)]);
 }
+/** Read the last bytes of a worker's standard-error log; empty when it cannot be read. */
+function readTail(file) {
+    try {
+        const fd = openSync(file, 'r');
+        try {
+            const size = fstatSync(fd).size;
+            const length = Math.min(size, STDERR_TAIL_BYTES);
+            const buffer = Buffer.alloc(length);
+            readSync(fd, buffer, 0, length, size - length);
+            return buffer.toString('utf8');
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return '';
+    }
+}
+/** Keep only the newest few worker logs; the rest are older diagnostics. */
+function pruneWorkerLogs(logRoot) {
+    try {
+        const logs = readdirSync(logRoot)
+            .filter((name) => name.startsWith('worker-') && name.endsWith('.log'))
+            .map((name) => ({ name, modified: statSync(path.join(logRoot, name)).mtimeMs }))
+            .sort((left, right) => right.modified - left.modified);
+        // A recent log may belong to a worker that is still running, so only older ones go.
+        const cutoff = Date.now() - 10 * 60_000;
+        for (const { name, modified } of logs.slice(RETAINED_STDERR_LOGS))
+            if (modified < cutoff)
+                rmSync(path.join(logRoot, name), { force: true });
+    }
+    catch {
+        // Diagnostics are best effort and must never change a job outcome.
+    }
+}
+/**
+ * Remove the log of a worker that ended normally or because the host stopped it. Keep the
+ * newest few logs of workers that ended unexpectedly, because their stack is the evidence.
+ */
+function retainOrRemoveLog(file, evidence, logRoot) {
+    try {
+        const unexpected = !evidence.stoppedByHost &&
+            (evidence.signal !== null || (evidence.code !== null && evidence.code !== 0));
+        if (!unexpected) {
+            rmSync(file, { force: true });
+            return;
+        }
+        pruneWorkerLogs(logRoot);
+    }
+    catch {
+        // Diagnostics are best effort and must never change a job outcome.
+    }
+}
 /**
  * Bounded, fixed-entry child execution. Client disconnection never kills a worker; an
  * overdue or unresponsive cancelled read-only worker is stopped by its supervising host.
@@ -78,12 +139,14 @@ export class JobWorkerHost {
     jobs;
     capacity;
     scheduler;
+    logRoot;
     owner = {};
-    constructor(engine, jobs, capacity, scheduler) {
+    constructor(engine, jobs, capacity, scheduler, logRoot) {
         this.engine = engine;
         this.jobs = jobs;
         this.capacity = capacity;
         this.scheduler = scheduler;
+        this.logRoot = logRoot;
     }
     static async create(engine, jobs) {
         const state = engine.resolver.serverState();
@@ -91,8 +154,11 @@ export class JobWorkerHost {
             throw new ServiceError('JOB_STORAGE_UNAVAILABLE', 'Workers require persistent server state');
         const root = await containedGeneratedPath(state.root, 'job-workers');
         await mkdir(root, { recursive: true, mode: 0o700 });
+        const logRoot = path.join(root, 'logs');
+        await mkdir(logRoot, { recursive: true, mode: 0o700 });
+        pruneWorkerLogs(logRoot);
         const config = engine.resolver.config();
-        return new JobWorkerHost(engine, jobs ?? (await JobService.create(engine.resolver)), new SharedRequestCapacity(root, config.maxSharedTools), new RequestScheduler(config.maxConcurrentTools));
+        return new JobWorkerHost(engine, jobs ?? (await JobService.create(engine.resolver)), new SharedRequestCapacity(root, config.maxSharedTools), new RequestScheduler(config.maxConcurrentTools), logRoot);
     }
     async run(workspaceId, id, principal) {
         const initial = await this.jobs.get(workspaceId, id, principal);
@@ -153,7 +219,7 @@ export class JobWorkerHost {
             if (liveness !== 'alive')
                 throw new ServiceError(liveness === 'unknown' ? 'JOB_OWNER_UNRESOLVED' : 'JOB_WORKER_EXIT', liveness === 'unknown'
                     ? 'The replacement execution owner cannot be verified on this host'
-                    : `The replacement worker stopped without publishing a terminal job outcome${WORKER_EXIT_HINT}`);
+                    : `The replacement worker stopped without publishing a terminal job outcome; its exit status belongs to the server that started it, so retry the call`);
             await delay(100);
         }
     }
@@ -206,7 +272,7 @@ export class JobWorkerHost {
             if (reused !== undefined && error instanceof ServiceError)
                 throw new ServiceError('REQUEST_LEASE_HANDOFF_LOST', 'The warm worker stopped before it received the job');
             if (reused === undefined)
-                await stopChild(child);
+                await stopChild(child, this.stoppedByHost);
             throw error;
         }
         progress.stage = 'dispatch';
@@ -240,7 +306,7 @@ export class JobWorkerHost {
                 const unresponsive = cancellationSeenAt !== undefined &&
                     Date.now() - cancellationSeenAt > jobCancelGraceSeconds * 1000;
                 if (overdue || unresponsive) {
-                    await stopChild(child);
+                    await stopChild(child, this.stoppedByHost);
                     await this.jobs.failInterrupted(workspaceId, id, {
                         code: 'JOB_DEADLINE_EXCEEDED',
                         message: `The job ran longer than ${jobDeadlineSeconds} seconds and was stopped; narrow its selector or limits, or raise jobDeadlineSeconds`,
@@ -248,18 +314,17 @@ export class JobWorkerHost {
                     return;
                 }
             }
-            if (child.pid !== undefined) {
-                try {
-                    process.kill(child.pid, 0);
-                }
-                catch (error) {
-                    if (error.code === 'ESRCH')
-                        throw new ServiceError('JOB_WORKER_EXIT', WORKER_EXIT_MESSAGE);
-                }
+            if (child.exitCode !== null || child.signalCode !== null) {
+                const evidence = await this.exits.get(child);
+                throw new ServiceError('JOB_WORKER_EXIT', evidence === undefined ? WORKER_EXIT_MESSAGE : classifyWorkerExit(evidence).message);
             }
             await delay(100);
         }
     }
+    /** Workers this host stopped itself, so their exit is not reported as a fault. */
+    stoppedByHost = new WeakSet();
+    /** Settles with the exit status and last standard error of each worker this host started. */
+    exits = new WeakMap();
     /** Idle warm workers of this host, most recently used last. */
     idleWorkers = [];
     /**
@@ -268,6 +333,7 @@ export class JobWorkerHost {
      */
     reportedIdle = new WeakSet();
     watched = new WeakSet();
+    workerSequence = 0;
     watchIdle(child) {
         if (this.watched.has(child))
             return;
@@ -302,16 +368,38 @@ export class JobWorkerHost {
     async startWorker(maxHeapMiB) {
         const sourceMode = import.meta.url.endsWith('.ts');
         const entry = fileURLToPath(new URL(sourceMode ? './job-worker.ts' : './job-worker.js', import.meta.url));
-        const child = spawn(process.execPath, [
-            ...(maxHeapMiB === undefined ? [] : [`--max-old-space-size=${maxHeapMiB}`]),
-            ...(sourceMode ? ['--import', import.meta.resolve('tsx')] : []),
-            entry,
-        ], {
-            detached: true,
-            cwd: process.cwd(),
-            stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
-            windowsHide: true,
-        });
+        const heapLimitMiB = maxHeapMiB ?? defaultWorkerHeapMiB();
+        const stderrLog = path.join(this.logRoot, `worker-${process.pid}-${++this.workerSequence}.log`);
+        const stderrFd = openSync(stderrLog, 'w', 0o600);
+        let child;
+        try {
+            child = spawn(process.execPath, [
+                `--max-old-space-size=${heapLimitMiB}`,
+                ...(sourceMode ? ['--import', import.meta.resolve('tsx')] : []),
+                entry,
+            ], {
+                detached: true,
+                cwd: process.cwd(),
+                stdio: ['ignore', 'ignore', stderrFd, 'ipc'],
+                windowsHide: true,
+            });
+        }
+        finally {
+            closeSync(stderrFd);
+        }
+        this.exits.set(child, new Promise((resolve) => {
+            child.once('exit', (code, signal) => {
+                const evidence = {
+                    code,
+                    signal,
+                    stderrTail: readTail(stderrLog),
+                    stoppedByHost: this.stoppedByHost.has(child),
+                    heapLimitMiB,
+                };
+                retainOrRemoveLog(stderrLog, evidence, this.logRoot);
+                resolve(evidence);
+            });
+        }));
         try {
             await new Promise((resolve, reject) => {
                 const onExit = (code, signal) => reject(new ServiceError('JOB_WORKER_STARTUP_EXIT', `The worker exited before completing its startup handshake (phase waiting_for_ready, exit ${code ?? 'none'}, signal ${signal ?? 'none'})`));

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

@@ -8,6 +8,7 @@ import { JobExecutor } from './job-executor.js';
 import { JobService } from './job-service.js';
 import { WorkspaceResolver } from './workspace.js';
 import { registerWorkerOperations, workerDomain } from './job-operation-registration.js';
+import { workerErrorMarker } from './worker-exit.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.
 //
@@ -32,9 +33,11 @@ let started = false;
 let idleTimer;
 /** Share of the heap limit a worker may still hold after a job and a full collection. */
 const WARM_HEAP_SHARE = 0.4;
+/** Absolute ceiling on that retained heap, so a large heap limit does not keep gigabytes idle. */
+const WARM_HEAP_MAXIMUM_BYTES = 1_536 * 1024 * 1024;
 /** Whether the heap, after a full collection, is small enough to serve another job. */
 function heapAllowsReuse() {
-    const limit = getHeapStatistics().heap_size_limit * WARM_HEAP_SHARE;
+    const limit = Math.min(getHeapStatistics().heap_size_limit * WARM_HEAP_SHARE, WARM_HEAP_MAXIMUM_BYTES);
     if (getHeapStatistics().used_heap_size <= limit)
         return true;
     try {
@@ -105,7 +108,9 @@ process.on('message', (value) => {
     if (idleTimer !== undefined)
         clearTimeout(idleTimer);
     void runJob(value)
-        .catch(() => {
+        .catch((error) => {
+        // The host reads this line back to tell an uncaught job error from a memory failure.
+        process.stderr.write(workerErrorMarker(error));
         process.exitCode = 1;
     })
         .finally(() => {