hoi4-agent-tools 3.8.1 → 3.9.0

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## Unreleased
+## 3.9.0 - 2026-10-06
+
+- Exit a stdio server whose launching process has exited, and add `stdioIdleExitMinutes` so clients that keep idle per-subagent connections no longer accumulate servers.
+- Stop a read-only job whose worker outlives `jobDeadlineSeconds` (`JOB_DEADLINE_EXCEEDED`) or ignores cancellation for `jobCancelGraceSeconds`, so a blocked worker can no longer hang a workflow.
+- Stop an orphaned read-only job worker at `jobDeadlineSeconds` even after its dispatching server has exited, and add `jobWorkerMaxHeapMiB` to bound each worker's heap.
+- Check a whole mod file with `hoi4.script_validate` `path`: every event, decision, focus, scripted helper, and on-action body with the scope its structure fixes, the mod's own scripted helpers as known commands, and building, ideology, and resource trigger keys.
+- Report a dynamic variable compared as a trigger (`SCRIPT_DYNAMIC_VARIABLE_AS_TRIGGER`) and a scope link outside its documented source scopes (`SCRIPT_SCOPE_LINK_WRONG_SCOPE`), and enter `owner`, `controller`, `capital_scope`, `overlord`, and `faction_leader` blocks with their target scope.
+- Check player-facing text in `hoi4.script_validate` file mode: colour codes in news and report events, including through scripted localisation, development wording in shown text, and unlocalised flags in decision and focus requirement tooltips.
+- Report visible events fired inside `every_*` loops that reach one player once per iteration, either through a fixed recipient or as a major event (`SCRIPT_EVENT_POPUP_REPEATED`).
+- Publish the GUI scenario shape on `hoi4.gui_inspect`, `hoi4.gui_render`, and `hoi4.gui_rewrite`, with `id` required, so clients can build a valid scenario from discovery.
+- Add `closedFlags` to GUI scenarios: undeclared flags are unset, as in the game, so flag-driven tab pages and panels render one at a time.
+- Resolve a window's scripted localisation exactly under the supplied scenario wherever its flags, variables, and values decide the branch; undecided tokens still render as `[dynamic_loc]`.
+- Warn with `GUI_UNRESOLVED_VISIBILITY_OVERLAP` when overlapping elements are drawn together because the scenario does not decide which one is visible.
+- Warn with `GUI_NEAR_CENTRE_OFFSET` when an element sits a few pixels from its parent's horizontal centre.
+- Add `background: "transparent"` to GUI scenarios for renders without the preview backdrop.
 
 ## 3.8.1 - 2026-10-05
 

package/README.md

@@ -119,7 +119,7 @@ Your agent can select them from ordinary language; use the live tool schema for
 | `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.script_validate`      | Check a snippet or a whole mod file for syntax, command kinds, and 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.                                                  |

package/dist/bin/setup.js

@@ -225,8 +225,11 @@ function printClientConfig(configPath) {
         args: [],
         ...(useDefaultConfiguration ? {} : { env: { HOI4_AGENT_CONFIG: absolute } }),
     };
-    const npxToml = `[mcp_servers.hoi4_agent_tools]\ncommand = "${command}"\nargs = ["-y", "hoi4-agent-tools@${PACKAGE_VERSION}"]${useDefaultConfiguration ? '' : `\nenv = { HOI4_AGENT_CONFIG = ${JSON.stringify(absolute)} }`}`;
-    const globalToml = `[mcp_servers.hoi4_agent_tools]\ncommand = "${installedCommand}"${useDefaultConfiguration ? '' : `\nenv = { HOI4_AGENT_CONFIG = ${JSON.stringify(absolute)} }`}`;
+    // Codex keeps a server per subagent connected after the subagent finishes, so its servers
+    // exit after half an hour without traffic instead of accumulating.
+    const codexEnv = `\nenv = { ${useDefaultConfiguration ? '' : `HOI4_AGENT_CONFIG = ${JSON.stringify(absolute)}, `}HOI4_AGENT_STDIO_IDLE_EXIT_MINUTES = "30" }`;
+    const npxToml = `[mcp_servers.hoi4_agent_tools]\ncommand = "${command}"\nargs = ["-y", "hoi4-agent-tools@${PACKAGE_VERSION}"]${codexEnv}`;
+    const globalToml = `[mcp_servers.hoi4_agent_tools]\ncommand = "${installedCommand}"${codexEnv}`;
     process.stdout.write(`${JSON.stringify({
         note: 'Review and paste one example into your MCP client; this utility does not edit client settings.',
         generic: { mcpServers: { hoi4_agent_tools: common } },

package/dist/bin/stdio.js

@@ -2,7 +2,22 @@
 import { canonicalJson } from '../hoi4_agent_tools/core/canonical.js';
 import { StdioFrameLimitError, StdioInvalidMessageError, StdioInvalidUtf8Error, } from '../hoi4_agent_tools/mcp/transports/bounded-stdio.js';
 import { serveNegotiatedStdio } from '../hoi4_agent_tools/mcp/transports/negotiated-stdio.js';
+import { StdioLifetime } from '../hoi4_agent_tools/mcp/transports/stdio-lifetime.js';
 import { createEngine } from '../hoi4_agent_tools/runtime.js';
+/**
+ * A client registration can set its own idle limit, because the server configuration is shared
+ * by every client: clients that keep idle per-subagent connections opt in without affecting a
+ * long-lived interactive session.
+ */
+function idleExitMinutes(configured) {
+    const override = process.env.HOI4_AGENT_STDIO_IDLE_EXIT_MINUTES;
+    if (override === undefined || override.trim() === '')
+        return configured;
+    const minutes = Number(override);
+    if (!Number.isInteger(minutes) || minutes < 0 || minutes > 10_080)
+        throw new Error('HOI4_AGENT_STDIO_IDLE_EXIT_MINUTES must be a whole number from 0 to 10080');
+    return minutes;
+}
 async function main() {
     const engine = await createEngine();
     const chaosxTools = process.env.HOI4_AGENT_TOOLS_CHAOSX === '1'
@@ -20,8 +35,17 @@ async function main() {
             message: error.message,
         })}\n`);
     };
-    await serveNegotiatedStdio(engine, {
+    let closeTransport = () => Promise.resolve();
+    const lifetime = new StdioLifetime({
+        idleExitMinutes: idleExitMinutes(engine.resolver.config().stdioIdleExitMinutes),
+        onExit: (reason) => {
+            process.stderr.write(`${canonicalJson({ level: 'info', event: 'stdio_exit', reason })}\n`);
+            void closeTransport().finally(() => setTimeout(() => process.exit(0), 250).unref());
+        },
+    });
+    const transport = await serveNegotiatedStdio(engine, {
         onerror,
+        observer: lifetime,
         onFailure: (error) => {
             process.exitCode = 1;
             process.stderr.write(`${canonicalJson({
@@ -37,6 +61,8 @@ async function main() {
                 registerLegacy: (server) => chaosxTools.registerChaosxTools(server, engine, {}),
             }),
     });
+    closeTransport = () => transport.close();
+    lifetime.start();
 }
 main().catch((error) => {
     process.stderr.write(`${canonicalJson({

package/dist/hoi4_agent_tools/core/configuration.js

@@ -147,6 +147,14 @@ export const serverConfigurationSchema = z
     scanMaxFiles: z.number().int().min(1).max(1_000_000).default(DEFAULT_SCAN_MAX_FILES),
     maxConcurrentTools: z.number().int().min(1).max(32).default(2),
     maxSharedTools: z.number().int().min(1).max(128).default(4),
+    /** A read-only job still running after this many seconds is stopped and fails. */
+    jobDeadlineSeconds: z.number().int().min(1).max(86_400).default(1_800),
+    /** A read-only job that has not stopped this long after cancellation is stopped. */
+    jobCancelGraceSeconds: z.number().int().min(1).max(600).default(10),
+    /** A stdio server with no client traffic or open request for this long exits; 0 never. */
+    stdioIdleExitMinutes: z.number().int().min(0).max(10_080).default(0),
+    /** V8 heap ceiling for each job worker in MiB; unset keeps Node's default. */
+    jobWorkerMaxHeapMiB: z.number().int().min(256).max(65_536).optional(),
     scanMaxBytes: z
         .number()
         .int()

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

@@ -57,7 +57,18 @@ export function workerFailure(error, stage) {
             message: `Worker coordination could not complete (${nativeCode}, stage ${stage}); inspect the retained job outcome`,
         };
 }
-/** Bounded, fixed-entry child execution; client cancellation/disconnection never kills a worker. */
+/** Stop a supervised worker and wait, bounded, until the operating system reports its exit. */
+async function stopChild(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    const exited = new Promise((resolve) => child.once('exit', () => resolve()));
+    child.kill('SIGKILL');
+    await Promise.race([exited, delay(10_000)]);
+}
+/**
+ * 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.
+ */
 export class JobWorkerHost {
     engine;
     jobs;
@@ -189,7 +200,13 @@ export class JobWorkerHost {
             }
             : grant;
         progress.stage = 'startup';
-        const child = spawn(process.execPath, [...(sourceMode ? ['--import', import.meta.resolve('tsx')] : []), entry], {
+        const child = spawn(process.execPath, [
+            ...(configuration.jobWorkerMaxHeapMiB === undefined
+                ? []
+                : [`--max-old-space-size=${configuration.jobWorkerMaxHeapMiB}`]),
+            ...(sourceMode ? ['--import', import.meta.resolve('tsx')] : []),
+            entry,
+        ], {
             detached: true,
             cwd: process.cwd(),
             stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
@@ -265,6 +282,9 @@ export class JobWorkerHost {
             clearTimeout(acknowledgmentTimer);
         }
         progress.stage = 'supervision';
+        const { jobDeadlineSeconds, jobCancelGraceSeconds } = this.engine.resolver.config();
+        const supervisedSince = Date.now();
+        let cancellationSeenAt;
         for (;;) {
             const record = await this.jobs.get(workspaceId, id, principal);
             if (['completed', 'failed', 'cancelled'].includes(record.status))
@@ -273,6 +293,24 @@ export class JobWorkerHost {
                 if (jobOwnerLiveness(record.owner) === 'alive')
                     return;
             }
+            // A worker blocked in synchronous analysis never reaches its own cancellation check,
+            // so this process enforces the deadline and cancellation through the child handle.
+            // Rewrites are never stopped here: their transaction journal owns write recovery.
+            if (!record.request.mutation) {
+                if (record.cancelRequested)
+                    cancellationSeenAt ??= Date.now();
+                const overdue = Date.now() - supervisedSince > jobDeadlineSeconds * 1000;
+                const unresponsive = cancellationSeenAt !== undefined &&
+                    Date.now() - cancellationSeenAt > jobCancelGraceSeconds * 1000;
+                if (overdue || unresponsive) {
+                    await stopChild(child);
+                    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`,
+                    }, principal);
+                    return;
+                }
+            }
             if (child.pid !== undefined) {
                 try {
                     process.kill(child.pid, 0);

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

@@ -42,6 +42,20 @@ process.once('message', (value) => {
         // unrelated live rewrite journals when a worker starts.
         const jobs = await JobService.create(resolver);
         const record = await jobs.get(input.workspaceId, input.jobId, input.principal);
+        if (!record.request.mutation) {
+            // The host enforces the deadline while it lives; a worker whose host has gone stops
+            // itself, so an orphaned read-only analysis never holds memory indefinitely.
+            const { jobDeadlineSeconds } = resolver.config();
+            setTimeout(() => {
+                void jobs
+                    .failInterrupted(input.workspaceId, input.jobId, {
+                    code: 'JOB_DEADLINE_EXCEEDED',
+                    message: `The job ran longer than ${jobDeadlineSeconds} seconds and was stopped; narrow its selector or limits, or raise jobDeadlineSeconds`,
+                }, input.principal)
+                    .catch(() => undefined)
+                    .finally(() => process.exit(1));
+            }, jobDeadlineSeconds * 1000).unref();
+        }
         const operations = await registerWorkerOperations(engine, record.request.toolName);
         await new JobExecutor(engine, jobs, operations).run(input.workspaceId, input.jobId, input.principal);
     })()

package/dist/hoi4_agent_tools/core/scenario-model.js

@@ -56,7 +56,7 @@ export function scenarioFromGui(base, values = base.values) {
         ...(base.controls === undefined ? {} : { controls: { ...base.controls } }),
         state,
         scopes,
-        closedFlags: false,
+        closedFlags: base.closedFlags === true,
         ...(typeof actor === 'string' ? { actor } : {}),
     };
 }

package/dist/hoi4_agent_tools/gui/renderer.js

@@ -456,6 +456,12 @@ function overlayToSvg(scene, variant) {
         .join('');
     return `<svg xmlns="http://www.w3.org/2000/svg" width="${scene.resolution.width}" height="${scene.resolution.height}" viewBox="0 0 ${scene.resolution.width} ${scene.resolution.height}"><defs>${toolText.definitions()}</defs>${overlays}</svg>`;
 }
+/** The preview backdrop; a transparent scenario leaves uncovered pixels fully transparent. */
+function backdrop(scene, viewBox) {
+    return scene.scenario.background === 'transparent'
+        ? ''
+        : `<rect ${rectAttributes(viewBox)} fill="#17202a"/>`;
+}
 export function sceneToSvg(scene, variant) {
     const view = viewFor(scene, variant);
     assertRenderDimensions(view.width, view.height, `GUI ${variant} SVG`);
@@ -470,7 +476,7 @@ export function sceneToSvg(scene, variant) {
         .map((element) => renderOverlay(element, variant, toolText))
         .join('');
     const fidelity = escapeXml(canonicalJson(scene.fidelity));
-    return `<svg xmlns="http://www.w3.org/2000/svg" width="${view.width}" height="${view.height}" viewBox="${finite(view.viewBox.x)} ${finite(view.viewBox.y)} ${finite(view.viewBox.width)} ${finite(view.viewBox.height)}"><metadata data-renderer="hoi4-agent-tools" data-mode="offline">${fidelity}</metadata><defs>${clipDefinitions.join('')}${sceneGlyphDefinitions(scene)}${toolText.definitions()}</defs><rect ${rectAttributes(view.viewBox)} fill="#17202a"/>${body}${overlays}</svg>`;
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${view.width}" height="${view.height}" viewBox="${finite(view.viewBox.x)} ${finite(view.viewBox.y)} ${finite(view.viewBox.width)} ${finite(view.viewBox.height)}"><metadata data-renderer="hoi4-agent-tools" data-mode="offline">${fidelity}</metadata><defs>${clipDefinitions.join('')}${sceneGlyphDefinitions(scene)}${toolText.definitions()}</defs>${backdrop(scene, view.viewBox)}${body}${overlays}</svg>`;
 }
 async function cooperativeParts(values, render, signal) {
     const output = [];
@@ -494,7 +500,7 @@ async function sceneToSvgCooperative(scene, variant, signal) {
     const body = (await cooperativeParts(scene.elements, (element, index) => renderBaseElement(element, element.clipRect === undefined ? undefined : `clip-${index}`, toolText), signal)) + renderTooltipPreview(scene, toolText);
     const overlays = await cooperativeParts(scene.elements, (element) => renderOverlay(element, variant, toolText), signal);
     const fidelity = escapeXml(canonicalJson(scene.fidelity));
-    return `<svg xmlns="http://www.w3.org/2000/svg" width="${view.width}" height="${view.height}" viewBox="${finite(view.viewBox.x)} ${finite(view.viewBox.y)} ${finite(view.viewBox.width)} ${finite(view.viewBox.height)}"><metadata data-renderer="hoi4-agent-tools" data-mode="offline">${fidelity}</metadata><defs>${clipDefinitions}${sceneGlyphDefinitions(scene)}${toolText.definitions()}</defs><rect ${rectAttributes(view.viewBox)} fill="#17202a"/>${body}${overlays}</svg>`;
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${view.width}" height="${view.height}" viewBox="${finite(view.viewBox.x)} ${finite(view.viewBox.y)} ${finite(view.viewBox.width)} ${finite(view.viewBox.height)}"><metadata data-renderer="hoi4-agent-tools" data-mode="offline">${fidelity}</metadata><defs>${clipDefinitions}${sceneGlyphDefinitions(scene)}${toolText.definitions()}</defs>${backdrop(scene, view.viewBox)}${body}${overlays}</svg>`;
 }
 export function hierarchyToSvg(scene) {
     const rows = scene.elements.toSorted((left, right) => left.depth - right.depth || left.zIndex - right.zIndex || compareCodeUnits(left.id, right.id));

package/dist/hoi4_agent_tools/gui/scenario-generator.js

@@ -459,6 +459,54 @@ function generatedRows(count, random, options) {
         };
     });
 }
+/** Sprite tokens read by scripted GUI `image` properties of the window. */
+function scriptedImageTokens(scripted) {
+    const tokens = new Set();
+    for (const definition of scripted)
+        for (const property of definition.propertyDefinitions)
+            for (const [attribute, expression] of Object.entries(property.attributes)) {
+                const token = expressionToken(expression);
+                if (token !== undefined && attribute.toLocaleLowerCase('en-US') === 'image')
+                    tokens.add(token);
+            }
+    return tokens;
+}
+/**
+ * Resolve the window's scripted localisation exactly under a supplied scenario: a text or
+ * sprite token whose `defined_text` branch the scenario's flags, variables and values decide
+ * takes that branch. A token the scenario cannot decide is left out, so it still renders as
+ * `[dynamic_loc]`, and caller-supplied values always win.
+ */
+export function resolveScenarioScriptedLocalisation(graph, windowName, base, definitions = new ClausewitzEvaluationDefinitions()) {
+    if (graph.scriptedLocalisation.length === 0)
+        return base;
+    const scripted = relatedScriptedGuis(graph, windowName);
+    const elements = relevantElements(graph, windowName, scripted);
+    const textual = tokensIn(sourceTexts(graph, elements, base.language, scripted)).textual;
+    const explicitValues = guiExplicitConditionValues(base);
+    const values = { ...base.values };
+    const templates = new Map();
+    const evaluate = (key, kind) => explicitValues[key] !== undefined
+        ? undefined
+        : scriptedLocalisationValue(graph, key, base.language, kind, explicitValues, base, definitions, []);
+    for (const key of textual) {
+        const template = evaluate(key, 'text');
+        if (template !== undefined)
+            templates.set(key, template);
+    }
+    for (const key of scriptedImageTokens(scripted)) {
+        const sprite = evaluate(key, 'image');
+        if (sprite !== undefined)
+            values[key] = sprite;
+    }
+    // Branch texts can embed further tokens, including other resolved branches.
+    for (let pass = 0; pass < 3; pass += 1)
+        for (const [key, template] of templates)
+            values[key] = materializeDynamicText(template, { ...explicitValues, ...values });
+    return Object.keys(values).length === Object.keys(base.values).length
+        ? base
+        : { ...base, values };
+}
 export function generateGuiPreviewScenarios(graph, windowName, base, options, definitions = new ClausewitzEvaluationDefinitions()) {
     if (!options.enabled)
         return [];

package/dist/hoi4_agent_tools/gui/scenario.js

@@ -145,6 +145,8 @@ const GuiPreviewScenarioBodySchema = z
     conditionResults: z.array(ConditionResultSchema).max(10_000).optional(),
     variables: z.record(z.string(), z.number()).default({}),
     flags: z.record(z.string(), z.boolean()).default({}),
+    closedFlags: z.boolean().optional(),
+    background: z.enum(['scene', 'transparent']).optional(),
     lists: z.record(z.string(), z.array(objectSchema).max(10_000)).default({}),
     localisation: z.record(z.string(), z.string()).default({}),
     values: objectSchema.default({}),

package/dist/hoi4_agent_tools/gui/studio.js

@@ -21,7 +21,7 @@ import { projectGuiGraphForArtifact } from './inspection-artifact.js';
 import { buildGuiScene } from './layout.js';
 import { GUI_VALIDATION_MAX_DIAGNOSTICS } from './limits.js';
 import { compareGuiImages, galleryDimensions, renderGallerySvg, renderGuiScene, } from './renderer.js';
-import { generateGuiPreviewScenarios } from './scenario-generator.js';
+import { generateGuiPreviewScenarios, resolveScenarioScriptedLocalisation, } from './scenario-generator.js';
 import { parseGeneratedScenarioOptions, parsePreviewScenario } from './scenario.js';
 import { buildGuiSourceGraph } from './source-graph.js';
 import { assertGuiSourcePatchesSafe } from './source-patch.js';
@@ -1062,16 +1062,19 @@ export class ScriptedGuiStudio {
             ? undefined
             : parseGeneratedScenarioOptions(input.generatedScenarios);
         const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.textSamples), scenarioTemplateNames([placeholderScenario, ...explicitRelatedScenarios]), scenarioCountryFlagPatterns([placeholderScenario, ...explicitRelatedScenarios]), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]), [placeholderScenario, ...explicitRelatedScenarios].some(({ tooltip }) => tooltip !== undefined));
+        const evaluationDefinitions = ClausewitzEvaluationDefinitions.build(scanned);
+        const resolveLocalisation = (target) => resolveScenarioScriptedLocalisation(scanned.graph, input.windowName, target, evaluationDefinitions);
+        const suppliedScenario = resolveLocalisation(placeholderScenario);
         const generatedScenarios = generatedOptions === undefined
             ? []
-            : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, ClausewitzEvaluationDefinitions.build(scanned));
-        const scenario = generatedScenarios[0] ?? placeholderScenario;
+            : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, evaluationDefinitions);
+        const scenario = generatedScenarios[0] ?? suppliedScenario;
         const relatedScenarios = [
             ...(generatedOptions?.preservePlaceholder === true && generatedScenarios.length > 0
-                ? [placeholderScenario]
+                ? [suppliedScenario]
                 : []),
             ...generatedScenarios.slice(1),
-            ...explicitRelatedScenarios,
+            ...explicitRelatedScenarios.map(resolveLocalisation),
         ];
         assertUniqueScenarioIds([scenario, ...relatedScenarios]);
         const budget = new RenderBudget();
@@ -1157,16 +1160,19 @@ export class ScriptedGuiStudio {
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
         ].some(({ tooltip }) => tooltip !== undefined));
+        const evaluationDefinitions = ClausewitzEvaluationDefinitions.build(scanned);
+        const resolveLocalisation = (target) => resolveScenarioScriptedLocalisation(scanned.graph, input.windowName, target, evaluationDefinitions);
+        const suppliedScenario = resolveLocalisation(placeholderScenario);
         const generatedScenarios = generatedOptions === undefined
             ? []
-            : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, ClausewitzEvaluationDefinitions.build(scanned));
-        const scenario = generatedScenarios[0] ?? placeholderScenario;
+            : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, evaluationDefinitions);
+        const scenario = generatedScenarios[0] ?? suppliedScenario;
         const relatedScenarios = [
             ...(generatedOptions?.preservePlaceholder === true && generatedScenarios.length > 0
-                ? [placeholderScenario]
+                ? [suppliedScenario]
                 : []),
             ...generatedScenarios.slice(1),
-            ...explicitRelatedScenarios,
+            ...explicitRelatedScenarios.map(resolveLocalisation),
         ];
         assertUniqueScenarioIds([scenario, ...relatedScenarios]);
         const baselineScenario = requestedBaselineScenario ??

package/dist/hoi4_agent_tools/gui/validators.js

@@ -4,6 +4,9 @@ import { sha256Bytes } from '../core/canonical.js';
 import { assertRenderDimensions } from '../core/render-budget.js';
 import { GuiAssetCatalog } from './assets.js';
 import { GUI_GRAPH_MAX_EDGES, GUI_GRAPH_MAX_NODES, GUI_SCENE_MAX_ELEMENTS, GUI_VALIDATION_MAX_ANCESTOR_HOPS, GUI_VALIDATION_MAX_DIAGNOSTICS, GUI_VALIDATION_MAX_PAIR_COMPARISONS, } from './limits.js';
+/** Horizontal offsets from a parent's centre above rounding and up to a few pixels look accidental. */
+const NEAR_CENTRE_TOLERANCE_PX = 0.5;
+const NEAR_CENTRE_MAX_PX = 3;
 const allStates = [
     'normal',
     'hover',
@@ -435,6 +438,19 @@ function validateOverlapAndGeometry(scene, diagnostics, work) {
     const visible = scene.elements.filter((element) => element.visible && area(element.rect) > 0);
     const byId = new Map(scene.elements.map((element) => [element.id, element]));
     for (const element of scene.elements) {
+        // An element a few pixels from its parent's horizontal centre was almost always meant
+        // to be centred; larger offsets are deliberate placement.
+        const parent = element.parentId === undefined ? undefined : byId.get(element.parentId);
+        if (element.visible &&
+            parent?.visible === true &&
+            element.unclippedRect.width > 0 &&
+            element.unclippedRect.width < parent.unclippedRect.width - 2) {
+            const offset = element.unclippedRect.x +
+                element.unclippedRect.width / 2 -
+                (parent.unclippedRect.x + parent.unclippedRect.width / 2);
+            if (Math.abs(offset) > NEAR_CENTRE_TOLERANCE_PX && Math.abs(offset) <= NEAR_CENTRE_MAX_PX)
+                diagnostics.push(issue('GUI_NEAR_CENTRE_OFFSET', 'warning', 'layout', `${element.name} sits ${Math.abs(offset).toFixed(1)} px ${offset > 0 ? 'right' : 'left'} of the centre of ${parent.name}; centre it exactly or offset it clearly.`, element, { parent: parent.id, offset }));
+        }
         if (element.unclippedRect.width <= 0 || element.unclippedRect.height <= 0) {
             diagnostics.push(issue('GUI_INVALID_SIZE', 'warning', 'layout', `${element.name} has a non-positive ${element.unclippedRect.width}x${element.unclippedRect.height} size.`, element));
         }
@@ -477,6 +493,12 @@ function validateOverlapAndGeometry(scene, diagnostics, work) {
                 if (left.clickable && right.clickable && ratio > 0.02) {
                     diagnostics.push(issue('GUI_CONFLICTING_CLICK_REGIONS', 'error', 'design', `${left.name} and ${right.name} have overlapping click regions (${(ratio * 100).toFixed(1)}%).`, right, { left: left.id, right: right.id, ratio }));
                 }
+                // Tab pages and alternative panels overlap by design; the game shows one at a time.
+                // When the scenario cannot decide which, the preview draws them stacked.
+                if (left.depth === right.depth &&
+                    ratio > 0.2 &&
+                    (left.visibilityStatus === 'unresolved' || right.visibilityStatus === 'unresolved'))
+                    diagnostics.push(issue('GUI_UNRESOLVED_VISIBILITY_OVERLAP', 'warning', 'layout', `${left.name} and ${right.name} overlap and the scenario does not decide which is visible, so the preview draws both. Declare the flags or variables their visible triggers read, with closedFlags, to render one of them.`, right, { left: left.id, right: right.id, ratio }));
                 if (left.depth === right.depth && ratio > 0.2) {
                     diagnostics.push(issue('GUI_VISIBLE_OVERLAP', 'warning', 'layout', `${left.name} and ${right.name} overlap by ${(ratio * 100).toFixed(1)}% of the smaller element.`, right, { left: left.id, right: right.id, ratio }));
                 }

package/dist/hoi4_agent_tools/mcp/tools/reference.js

@@ -44,7 +44,7 @@ export const referenceTools = [
     {
         name: 'hoi4.script_validate',
         title: 'Check HOI4 script commands and scopes',
-        description: 'Check effect or trigger snippet syntax, native command kinds and declared scopes against cited installed documentation. Unknown helpers and native argument blocks remain explicit.',
+        description: 'Check an effect or trigger snippet (source, kind, scope) or a whole mod file (path) for syntax, native command kinds and scopes against cited installed documentation. Unknown helpers and native argument blocks remain explicit.',
         inputSchema: scriptValidateRequestSchema,
         outputSchema: strictOperationResultSchema(scriptValidateDataSchema),
         annotations: readOnly,

package/dist/hoi4_agent_tools/mcp/transports/negotiated-stdio.js

@@ -80,12 +80,21 @@ export async function serveNegotiatedStdio(engine, options) {
         reportedErrors.add(error);
         options.onerror(error);
     };
+    const observer = options.observer;
+    if (observer !== undefined) {
+        const send = physical.send.bind(physical);
+        physical.send = (message) => {
+            observer.sent(message);
+            return send(message);
+        };
+    }
     physical.onclose = () => pinned?.onclose();
     physical.onerror = (error) => {
         reportError(error);
         pinned?.onerror(error);
     };
     physical.onmessage = (message) => {
+        observer?.received(message);
         if (pinned === undefined) {
             pinned = new PinnedStdioTransport(physical, reportError);
             try {

package/dist/hoi4_agent_tools/mcp/transports/stdio-lifetime.js

@@ -0,0 +1,83 @@
+/**
+ * Ends a stdio server that no client can reach. A client normally closes stdin, which the
+ * transport turns into a clean exit. Two cases leave stdin open: the launching process
+ * (for example a `cmd.exe` shim that a client terminated) dies while the client keeps the
+ * pipe, and a client keeps an idle connection it will never use again. The first is detected
+ * by polling the parent process; the second by an optional idle limit.
+ */
+const PARENT_POLL_MS = 5_000;
+/** Whether a process exists; a permission refusal still proves it exists. */
+export function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+export class StdioLifetime {
+    #options;
+    #open = new Set();
+    #lastActivity;
+    #timer;
+    #stopped = false;
+    constructor(options) {
+        this.#options = {
+            parentPid: options.parentPid ?? process.ppid,
+            isAlive: options.isAlive ?? processAlive,
+            now: options.now ?? Date.now,
+            pollMs: options.pollMs ?? PARENT_POLL_MS,
+            idleExitMinutes: options.idleExitMinutes,
+            onExit: options.onExit,
+        };
+        this.#lastActivity = this.#options.now();
+    }
+    start() {
+        this.#timer = setInterval(() => this.check(), this.#options.pollMs);
+        // The poll never keeps an otherwise finished server alive.
+        this.#timer.unref();
+    }
+    stop() {
+        this.#stopped = true;
+        if (this.#timer !== undefined)
+            clearInterval(this.#timer);
+    }
+    /** A client message: a request opens until its response is sent. */
+    received(message) {
+        this.#lastActivity = this.#options.now();
+        const id = requestId(message, 'method');
+        if (id !== undefined)
+            this.#open.add(id);
+    }
+    /** A server message: a response closes its request. */
+    sent(message) {
+        this.#lastActivity = this.#options.now();
+        const id = requestId(message, 'result') ?? requestId(message, 'error');
+        if (id !== undefined)
+            this.#open.delete(id);
+    }
+    check() {
+        if (this.#stopped)
+            return;
+        const { parentPid, isAlive, idleExitMinutes, now, onExit } = this.#options;
+        // A parent pid of 0 or 1 means the server was already reparented at start.
+        if (parentPid > 1 && !isAlive(parentPid)) {
+            this.stop();
+            onExit('parent_exited');
+            return;
+        }
+        if (idleExitMinutes > 0 &&
+            this.#open.size === 0 &&
+            now() - this.#lastActivity > idleExitMinutes * 60_000) {
+            this.stop();
+            onExit('idle');
+        }
+    }
+}
+function requestId(message, field) {
+    if (typeof message !== 'object' || message === null || !(field in message))
+        return undefined;
+    const id = message.id;
+    return typeof id === 'string' || typeof id === 'number' ? id : undefined;
+}

package/dist/hoi4_agent_tools/reference/event-popups.js

@@ -0,0 +1,87 @@
+import { parseClausewitz } from '../core/source/index.js';
+const eventEffects = new Set(['country_event', 'news_event']);
+const eventTypes = new Set([
+    'country_event',
+    'news_event',
+    'state_event',
+    'unit_leader_event',
+    'operative_leader_event',
+]);
+/** Scopes that name the same target on every iteration of an enclosing loop. */
+const fixedScope = /^(?:root|from(?:\.from)*|prev(?:\.prev)*|global|event_target:.+|var:.+|[A-Z][A-Z0-9]{2})$/u;
+const notTags = new Set(['AND', 'NOT', 'NOR', 'XOR']);
+function assignmentsOf(block) {
+    return block.entries.filter((entry) => entry.type === 'assignment');
+}
+function scalar(block, key) {
+    const entry = assignmentsOf(block).find((child) => child.key.value === key);
+    return entry?.value.type === 'scalar' ? entry.value.value : undefined;
+}
+/** Event definitions of one events file, keyed by id. */
+export function eventPopupDefinitions(bytes, path) {
+    const definitions = new Map();
+    for (const event of assignmentsOf(parseClausewitz(bytes, path).root)) {
+        if (!eventTypes.has(event.key.value) || event.value.type !== 'block')
+            continue;
+        const id = scalar(event.value, 'id');
+        if (id === undefined)
+            continue;
+        definitions.set(id, {
+            hidden: scalar(event.value, 'hidden') === 'yes',
+            major: scalar(event.value, 'major') === 'yes',
+            fireOnlyOnce: scalar(event.value, 'fire_only_once') === 'yes',
+        });
+    }
+    return definitions;
+}
+/**
+ * Visible events fired inside an `every_*` loop that reach the same player once per
+ * iteration: a fixed recipient (ROOT, FROM, PREV, a tag, a target) receives one window per
+ * loop member, and a major event is shown to every country once per loop member.
+ */
+export function repeatedPopupFindings(document, events) {
+    const findings = [];
+    const visit = (block, loops, fixed) => {
+        for (const entry of assignmentsOf(block)) {
+            const key = entry.key.value;
+            if (key === 'limit')
+                continue;
+            if (eventEffects.has(key) && loops.length > 0) {
+                const id = entry.value.type === 'block' ? scalar(entry.value, 'id') : entry.value.value;
+                const definition = id === undefined ? undefined : events.get(id);
+                if (definition === undefined || definition.hidden)
+                    continue;
+                const loop = loops.join(' inside ');
+                if (fixed !== undefined)
+                    findings.push({
+                        code: 'SCRIPT_EVENT_POPUP_REPEATED',
+                        command: key,
+                        offset: entry.start,
+                        end: entry.end,
+                        message: `${id} is sent to ${fixed} once per member of ${loop}, so that player receives one window per iteration; fire it once outside the loop or mark it hidden`,
+                    });
+                else if (definition.major && !definition.fireOnlyOnce)
+                    findings.push({
+                        code: 'SCRIPT_EVENT_POPUP_REPEATED',
+                        command: key,
+                        offset: entry.start,
+                        end: entry.end,
+                        message: `${id} is a major event fired once per member of ${loop}, so every player receives one window per iteration; fire it once outside the loop`,
+                    });
+                continue;
+            }
+            if (entry.value.type !== 'block')
+                continue;
+            if (key.startsWith('every_'))
+                visit(entry.value, [...loops, key], undefined);
+            else if (loops.length > 0 &&
+                !notTags.has(key) &&
+                (fixedScope.test(key) || fixedScope.test(key.toLowerCase())))
+                visit(entry.value, loops, key);
+            else
+                visit(entry.value, loops, fixed);
+        }
+    };
+    visit(document.root, [], undefined);
+    return findings;
+}