hoi4-agent-tools 3.8.1 → 3.10.0

package/CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
-## Unreleased
+## 3.10.0 - 2026-10-06
+
+- Rebuild a workspace index after an edit from the previous index, parsing and indexing only changed files, and keep the latest scan of each pattern set and each GUI graph scope instead of one per workspace. A repeated GUI preview of a large, actively edited mod took 64 s instead of 244 s.
+- Admit parsed documents to a full cache only on their second miss and only in place of entries never read, so scans larger than the cache no longer serialize and evict every document; build scripted-localisation definitions only for windows that show scripted localisation.
+- List every server process sharing a server state root, with its memory, last client activity and execution limits, in the `hoi4-agent://server/status` resource of local stdio connections.
+- Refuse an `hoi4.event_compare` or `hoi4.tech_compare` call without references before scanning when no earlier revision is cached, instead of after a full scan.
+- Report a `hoi4.tech_render` folder view without `folderId` as a readable argument error instead of a raw validation dump.
+- Ship `proxy-addr` 2.0.8, which fixes IP spoofing through IPv4-mapped IPv6 trust subnets (GHSA-jqcg-44mw-7w3h); the HTTP server sets no `trust proxy`, so earlier releases did not reach the affected code.
+
+## 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/http.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { canonicalJson } from '../hoi4_agent_tools/core/canonical.js';
+import { ServerRegistry } from '../hoi4_agent_tools/core/server-registry.js';
 import { createMcpServer } from '../hoi4_agent_tools/mcp/server/create.js';
 import { startHttpServer } from '../hoi4_agent_tools/mcp/transports/http.js';
 import { createEngine } from '../hoi4_agent_tools/runtime.js';
 async function main() {
     const engine = await createEngine();
     const handle = await startHttpServer(engine, engine.resolver.config(), createMcpServer);
+    new ServerRegistry(engine.resolver, 'http').start();
     const shutdown = async () => {
         await handle.close();
         process.exit(0);

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,23 @@
 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 { ServerRegistry } from '../hoi4_agent_tools/core/server-registry.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 +36,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 +62,9 @@ async function main() {
                 registerLegacy: (server) => chaosxTools.registerChaosxTools(server, engine, {}),
             }),
     });
+    closeTransport = () => transport.close();
+    lifetime.start();
+    new ServerRegistry(engine.resolver, 'stdio', () => lifetime.lastActivity()).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/engine.js

@@ -9,6 +9,12 @@ import { TransactionManager, transactionRootFingerprint } from './transactions.j
 import { RequestScheduler } from './request-scheduler.js';
 import { SharedRequestCapacity } from './shared-request-capacity.js';
 import { JobStore } from './job-store.js';
+/**
+ * Completed scans kept per workspace. One tool call often scans several pattern sets (a GUI
+ * preview scans layouts, linked definitions and localisation), so a single slot made every
+ * repeat call rescan and reindex each set.
+ */
+const SCAN_CACHE_ENTRIES_PER_WORKSPACE = 4;
 const RECOVERY_TTL_SECONDS = 3_600;
 const RECOVERY_MAX_BYTES = 536_870_912;
 const RECOVERY_MAX_RECORDS = 128;
@@ -167,9 +173,6 @@ export class CoreEngine {
         })}`;
         let flight = this.#scanFlights.get(requestKey);
         if (flight === undefined) {
-            for (const key of this.#scanCache.keys())
-                if (key.startsWith(`${workspaceId}:`) && !key.startsWith(`${requestKey}:`))
-                    this.#scanCache.delete(key);
             const controller = new AbortController();
             const promise = (async () => {
                 return this.withScanAdmission(controller.signal, async () => {
@@ -193,8 +196,11 @@ export class CoreEngine {
                     })));
                     const cacheKey = `${requestKey}:${revision}`;
                     const cached = this.#scanCache.get(cacheKey);
-                    if (cached !== undefined)
+                    if (cached !== undefined) {
+                        this.#scanCache.delete(cacheKey);
+                        this.#scanCache.set(cacheKey, cached);
                         return cached;
+                    }
                     const persistentAnalysisCache = await this.persistentAnalysisCache;
                     const analysisScope = {
                         workspaceIdentity: workspace.workspaceIdentity,
@@ -202,7 +208,12 @@ export class CoreEngine {
                         principal: principal ?? null,
                     };
                     await persistentAnalysisCache?.hydrate(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
-                    const index = await SymbolIndex.buildAsync(files, controller.signal, this.indexSegments);
+                    // The previous revision of the same request still holds every unchanged file's
+                    // records, so only edited files are parsed and indexed again.
+                    const previous = [...this.#scanCache]
+                        .filter(([key]) => key.startsWith(`${requestKey}:`))
+                        .at(-1)?.[1].index;
+                    const index = await SymbolIndex.buildAsync(files, controller.signal, this.indexSegments, previous);
                     await persistentAnalysisCache?.persist(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
                     const snapshot = {
                         workspaceId,
@@ -215,11 +226,18 @@ export class CoreEngine {
                         diagnostics: index.diagnostics,
                     };
                     if ((this.#scanGenerations.get(workspaceId) ?? 0) === generation) {
+                        // Replace this request's earlier revision and drop earlier generations; keep the
+                        // most recent other requests of this workspace.
                         for (const key of this.#scanCache.keys()) {
-                            if (key.startsWith(`${workspaceId}:`))
+                            if (key.startsWith(`${requestKey}:`) ||
+                                (key.startsWith(`${workspaceId}:`) &&
+                                    !key.startsWith(`${workspaceId}:${generation}:`)))
                                 this.#scanCache.delete(key);
                         }
                         this.#scanCache.set(cacheKey, snapshot);
+                        const retained = [...this.#scanCache.keys()].filter((key) => key.startsWith(`${workspaceId}:`));
+                        for (const key of retained.slice(0, -SCAN_CACHE_ENTRIES_PER_WORKSPACE))
+                            this.#scanCache.delete(key);
                     }
                     return snapshot;
                 });
@@ -384,7 +402,8 @@ export class CoreEngine {
             request.run();
         }
     }
-    indexFiles(files) {
-        return SymbolIndex.build(files, this.indexSegments);
+    /** `previous` supplies unchanged files' records from an earlier index of the same sources. */
+    indexFiles(files, previous) {
+        return SymbolIndex.build(files, this.indexSegments, previous);
     }
 }

package/dist/hoi4_agent_tools/core/index.js

@@ -1,7 +1,7 @@
 import { compareCodeUnits } from './canonical.js';
 import path from 'node:path';
 import { sortDiagnostics } from './diagnostics.js';
-import { indexSegmentAddress } from './index-segments.js';
+import { indexSegmentAddress, } from './index-segments.js';
 import { parseClausewitz, parseLocalisation, assignments, childBlocks, firstScalar, locationFor, sourcePartialLimitDiagnostics, SOURCE_MAX_BYTES, SOURCE_MAX_NESTING, nodeLocation, } from './source/index.js';
 const spriteDefinitionKeys = new Set([
     'spritetype',
@@ -261,6 +261,11 @@ export class SymbolIndex {
     files = new Map();
     #active = new Map();
     #definitionFiles = new Set();
+    /**
+     * Where each completely indexed file's records sit in this index, by segment address, so a
+     * rebuild after an edit reuses unchanged files instead of parsing and indexing them again.
+     */
+    #fileRanges = new Map();
     #indexNestingBlocked = new Set();
     #skippedSourcePaths = new Set();
     #skippedPossibleSymbolKinds = new Set();
@@ -271,7 +276,7 @@ export class SymbolIndex {
     #referenceLimitReported = false;
     #diagnosticsTruncated = false;
     #indexTableBlocked = new Set();
-    static build(files, segments) {
+    static build(files, segments, previous) {
         const index = new SymbolIndex();
         const definitionSelection = selectedDefinitionFiles(files);
         for (const displayPath of definitionSelection.selected)
@@ -281,13 +286,13 @@ export class SymbolIndex {
         }
         for (const file of [...files].sort((a, b) => a.loadOrder - b.loadOrder || compareCodeUnits(a.displayPath, b.displayPath))) {
             index.files.set(file.displayPath, file);
-            index.indexFileWithSegments(file, segments);
+            index.indexFileWithSegments(file, segments, previous);
         }
         index.finalize();
         return index;
     }
     /** Yield between source files so protocol cancellation and progress remain responsive. */
-    static async buildAsync(files, signal, segments) {
+    static async buildAsync(files, signal, segments, previous) {
         signal?.throwIfAborted();
         const index = new SymbolIndex();
         const definitionSelection = selectedDefinitionFiles(files);
@@ -300,7 +305,7 @@ export class SymbolIndex {
         for (const file of [...files].sort((a, b) => a.loadOrder - b.loadOrder || compareCodeUnits(a.displayPath, b.displayPath))) {
             signal?.throwIfAborted();
             index.files.set(file.displayPath, file);
-            index.indexFileWithSegments(file, segments);
+            index.indexFileWithSegments(file, segments, previous);
             if (performance.now() - yieldedAt >= 20) {
                 await new Promise((resolve) => setImmediate(resolve));
                 signal?.throwIfAborted();
@@ -437,31 +442,50 @@ export class SymbolIndex {
         for (const diagnostic of diagnostics)
             this.addDiagnostic(diagnostic);
     }
-    indexFileWithSegments(file, cache) {
-        if (cache === undefined) {
+    /** The records one completely indexed file contributed to this index, if it was recorded. */
+    #segmentAt(address) {
+        const range = this.#fileRanges.get(address);
+        if (range === undefined)
+            return undefined;
+        return {
+            symbols: this.symbols.slice(...range.symbols),
+            references: this.references.slice(...range.references),
+            diagnostics: this.diagnostics.slice(...range.diagnostics),
+            complete: true,
+        };
+    }
+    indexFileWithSegments(file, cache, previous) {
+        if (cache === undefined && previous === undefined) {
             this.indexFile(file);
             return;
         }
         const address = indexSegmentAddress(file, this.#definitionFiles.has(file.displayPath));
-        const cached = cache.get(address);
-        if (cached?.complete === true &&
-            this.symbols.length + cached.symbols.length <= INDEX_RECORD_LIMIT &&
-            this.references.length + cached.references.length <= INDEX_RECORD_LIMIT &&
-            this.diagnostics.length + cached.diagnostics.length <= INDEX_DIAGNOSTIC_LIMIT) {
+        const symbols = this.symbols.length;
+        const references = this.references.length;
+        const diagnostics = this.diagnostics.length;
+        const record = () => this.#fileRanges.set(address, {
+            symbols: [symbols, this.symbols.length],
+            references: [references, this.references.length],
+            diagnostics: [diagnostics, this.diagnostics.length],
+        });
+        const reused = (previous === undefined ? undefined : previous.#segmentAt(address)) ?? cache?.get(address);
+        if (reused?.complete === true &&
+            this.symbols.length + reused.symbols.length <= INDEX_RECORD_LIMIT &&
+            this.references.length + reused.references.length <= INDEX_RECORD_LIMIT &&
+            this.diagnostics.length + reused.diagnostics.length <= INDEX_DIAGNOSTIC_LIMIT) {
             this.#currentFileShadowed = file.shadowedBy !== undefined;
-            for (const symbol of cached.symbols)
+            for (const symbol of reused.symbols)
                 this.addSymbol(symbol);
-            for (const reference of cached.references)
+            for (const reference of reused.references)
                 this.addReference(reference);
-            this.addDiagnostics(cached.diagnostics);
+            this.addDiagnostics(reused.diagnostics);
+            if (!this.#diagnosticsTruncated)
+                record();
             return;
         }
-        const symbols = this.symbols.length;
-        const references = this.references.length;
-        const diagnostics = this.diagnostics.length;
         this.indexFile(file);
         // Incomplete files and aggregate ceilings retain the full builder's exact diagnostic
-        // ordering and coverage bookkeeping. They are never cached as complete segments.
+        // ordering and coverage bookkeeping. They are never reused as complete segments.
         if (this.#indexTableBlocked.has(file.displayPath) ||
             this.#skippedSourcePaths.has(file.displayPath) ||
             this.#indexNestingBlocked.has(file.displayPath) ||
@@ -469,7 +493,8 @@ export class SymbolIndex {
             this.#referenceLimitReported ||
             this.#diagnosticsTruncated)
             return;
-        cache.put(address, {
+        record();
+        cache?.put(address, {
             symbols: this.symbols.slice(symbols),
             references: this.references.slice(references),
             diagnostics: this.diagnostics.slice(diagnostics),

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/core/server-registry.js

@@ -0,0 +1,138 @@
+import { unlinkSync } from 'node:fs';
+import { mkdir, readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod/v4';
+import { PACKAGE_VERSION } from '../version.js';
+/**
+ * Every server process sharing a server state root records a small heartbeat, so one status
+ * read shows how many servers and workers a machine runs and how much memory each holds.
+ */
+const HEARTBEAT_MS = 60_000;
+/** A record this old without an update belongs to a process that is blocked or gone. */
+const STALE_MS = 5 * HEARTBEAT_MS;
+const MAX_RECORDS = 512;
+const recordSchema = z
+    .object({
+    pid: z.number().int().positive(),
+    version: z.string().max(64),
+    transport: z.enum(['stdio', 'http']),
+    startedAt: z.string().max(64),
+    updatedAt: z.string().max(64),
+    lastActivityAt: z.string().max(64).optional(),
+    rssBytes: z.number().int().min(0),
+    heapUsedBytes: z.number().int().min(0),
+})
+    .strict();
+function directory(resolver) {
+    const state = resolver.serverState();
+    return state === undefined ? undefined : path.join(state.root, 'servers');
+}
+/** 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';
+    }
+}
+/** The registry of this server process, or a status-only one when no server started it. */
+export function serverRegistry(resolver) {
+    return ServerRegistry.active ?? new ServerRegistry(resolver, 'stdio');
+}
+export class ServerRegistry {
+    resolver;
+    transport;
+    lastActivity;
+    /** The registry whose heartbeats this process writes. */
+    static active;
+    #startedAt = new Date().toISOString();
+    #timer;
+    constructor(resolver, transport, lastActivity = () => undefined) {
+        this.resolver = resolver;
+        this.transport = transport;
+        this.lastActivity = lastActivity;
+    }
+    current() {
+        const memory = process.memoryUsage();
+        const activity = this.lastActivity();
+        return {
+            pid: process.pid,
+            version: PACKAGE_VERSION,
+            transport: this.transport,
+            startedAt: this.#startedAt,
+            updatedAt: new Date().toISOString(),
+            ...(activity === undefined ? {} : { lastActivityAt: new Date(activity).toISOString() }),
+            rssBytes: memory.rss,
+            heapUsedBytes: memory.heapUsed,
+        };
+    }
+    /** Start heartbeats; the record is removed when the process exits normally. */
+    start() {
+        ServerRegistry.active = this;
+        const root = directory(this.resolver);
+        if (root === undefined)
+            return;
+        const file = path.join(root, `${process.pid}.json`);
+        const beat = () => void mkdir(root, { recursive: true })
+            .then(async () => {
+            const temporary = `${file}.${Date.now()}.tmp`;
+            await writeFile(temporary, `${JSON.stringify(this.current())}\n`);
+            await rename(temporary, file);
+        })
+            .catch(() => undefined);
+        beat();
+        this.#timer = setInterval(beat, HEARTBEAT_MS);
+        this.#timer.unref();
+        process.once('exit', () => {
+            try {
+                unlinkSync(file);
+            }
+            catch {
+                // A record left behind is removed by the next status read once the pid is gone.
+            }
+        });
+    }
+    async status() {
+        const current = this.current();
+        const config = this.resolver.config();
+        const limits = {
+            maxConcurrentTools: config.maxConcurrentTools,
+            maxSharedTools: config.maxSharedTools,
+            jobDeadlineSeconds: config.jobDeadlineSeconds,
+            jobCancelGraceSeconds: config.jobCancelGraceSeconds,
+            stdioIdleExitMinutes: config.stdioIdleExitMinutes,
+            jobWorkerMaxHeapMiB: config.jobWorkerMaxHeapMiB,
+        };
+        const root = directory(this.resolver);
+        const servers = [];
+        let removed = 0;
+        if (root !== undefined) {
+            const names = (await readdir(root).catch(() => []))
+                .filter((name) => /^\d+\.json$/u.test(name))
+                .slice(0, MAX_RECORDS);
+            for (const name of names) {
+                const file = path.join(root, name);
+                const parsed = recordSchema.safeParse(await readFile(file, 'utf8')
+                    .then((text) => JSON.parse(text))
+                    .catch(() => undefined));
+                if (!parsed.success)
+                    continue;
+                const record = parsed.data;
+                if (record.pid === process.pid)
+                    continue;
+                if (!processAlive(record.pid)) {
+                    removed += 1;
+                    await unlink(file).catch(() => undefined);
+                    continue;
+                }
+                const age = Date.now() - Date.parse(record.updatedAt);
+                servers.push({ ...record, state: age > STALE_MS ? 'stale' : 'live' });
+            }
+        }
+        servers.push({ ...current, state: 'live' });
+        servers.sort((left, right) => right.rssBytes - left.rssBytes || left.pid - right.pid);
+        return { current, servers, removed, limits };
+    }
+}

package/dist/hoi4_agent_tools/core/server-status-resource.js

@@ -0,0 +1,22 @@
+import { canonicalJson } from './canonical.js';
+import { serverRegistry } from './server-registry.js';
+/** A fixed, listed resource: every server process sharing this server state and its memory. */
+export const serverStatusResource = {
+    uri: 'hoi4-agent://server/status',
+    name: 'server-status',
+    title: 'HOI4 Agent Tools server status',
+    description: 'Live server processes sharing this server state, with memory, last client activity and execution limits.',
+    mimeType: 'application/json',
+};
+export async function readServerStatus(engine) {
+    const status = await serverRegistry(engine.resolver).status();
+    return {
+        contents: [
+            {
+                uri: serverStatusResource.uri,
+                mimeType: serverStatusResource.mimeType,
+                text: `${canonicalJson(status)}\n`,
+            },
+        ],
+    };
+}