hoi4-agent-tools 3.9.0 → 3.10.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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.

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/stdio.js

@@ -2,6 +2,7 @@
 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';
 /**
@@ -63,6 +64,7 @@ async function main() {
     });
     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/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/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`,
+            },
+        ],
+    };
+}

package/dist/hoi4_agent_tools/core/source/cache.js

@@ -27,29 +27,50 @@ function decodedDocument(encoded, expected) {
         throw new Error('Persistent source document does not match its source identity');
     return value;
 }
-/** Process-local parsed facts; serialized entries cannot be mutated by their consumers. */
+/** Puts between halvings of every entry's hit count, so entries no longer read become evictable. */
+const HIT_AGING_INTERVAL = 4096;
+/** Keys of documents turned away from a full cache, remembered so a repeat can be admitted. */
+const DOORKEEPER_KEYS = 16_384;
+/**
+ * Process-local parsed facts; serialized entries cannot be mutated by their consumers.
+ *
+ * A workspace scan often parses more source than the cache holds. Plain LRU then evicts
+ * every document before its next use and pays serialization for nothing. A full cache
+ * therefore turns a document away the first time, remembering only its key, and admits it
+ * on a later miss by displacing entries that were never read; a rejected document is not
+ * serialized. Repeated scans keep what fits and hit it. Hit counts age, so documents that
+ * stop being read become evictable again.
+ */
 export class SourceDocumentCache {
     maxBytes;
     #entries = new Map();
     #bytes = 0;
+    /** Bytes held by entries without hits, which a new document may displace. */
+    #coldBytes = 0;
+    #puts = 0;
     #hits = 0;
     #misses = 0;
     #evictions = 0;
+    #rejections = 0;
+    #doorkeeper = new Set();
     constructor(maxBytes = 64 * 1024 * 1024) {
         this.maxBytes = maxBytes;
         if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
             throw new RangeError('Source cache size must be a non-negative integer');
     }
     get(key) {
-        const encoded = this.#entries.get(key);
-        if (encoded === undefined) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined) {
             this.#misses += 1;
             return undefined;
         }
         this.#hits += 1;
+        if (entry.hits === 0)
+            this.#coldBytes -= entrySize(key, entry.encoded);
+        entry.hits += 1;
         this.#entries.delete(key);
-        this.#entries.set(key, encoded);
-        return decodedDocument(encoded);
+        this.#entries.set(key, entry);
+        return decodedDocument(entry.encoded);
     }
     /** Availability check without deserialization or cache-hit accounting. */
     has(key) {
@@ -61,8 +82,19 @@ export class SourceDocumentCache {
         const estimatedBytes = document.bytes.length * 12 + document.tokens.length * 512 + key.length * 2 + 128;
         if (this.maxBytes === 0 || estimatedBytes > this.maxBytes)
             return;
-        const encoded = serialize(document);
-        this.retain(key, encoded);
+        this.#age();
+        const previous = this.#entries.get(key);
+        const reusable = previous === undefined ? 0 : entrySize(key, previous.encoded);
+        const free = this.maxBytes - this.#bytes + reusable;
+        if (estimatedBytes > free) {
+            // Only a document missed before may displace entries, and only entries never read.
+            if (!this.#doorkeeper.delete(key) || estimatedBytes > free + this.#coldBytes) {
+                this.#remember(key);
+                this.#rejections += 1;
+                return;
+            }
+        }
+        this.retain(key, serialize(document));
     }
     /** Import one authenticated same-runtime entry without counting it as a process-local hit. */
     importEncoded(key, encoded, expected) {
@@ -70,42 +102,79 @@ export class SourceDocumentCache {
         this.retain(key, Buffer.from(encoded));
     }
     exportEncoded(key) {
-        const encoded = this.#entries.get(key);
-        return encoded === undefined ? undefined : Buffer.from(encoded);
+        const entry = this.#entries.get(key);
+        return entry === undefined ? undefined : Buffer.from(entry.encoded);
     }
     retain(key, encoded) {
-        const size = encoded.length + key.length * 2 + 128;
+        const size = entrySize(key, encoded);
         if (size > this.maxBytes)
             return;
-        const previous = this.#entries.get(key);
-        if (previous !== undefined)
-            this.#bytes -= previous.length + key.length * 2 + 128;
-        this.#entries.delete(key);
-        while (this.#bytes + size > this.maxBytes) {
-            const oldest = this.#entries.entries().next().value;
-            if (oldest === undefined)
+        this.#remove(key);
+        // Displace the oldest entries that were never read again; read entries stay.
+        for (const [oldKey, entry] of this.#entries) {
+            if (this.#bytes + size <= this.maxBytes)
                 break;
-            this.#entries.delete(oldest[0]);
-            this.#bytes -= oldest[1].length + oldest[0].length * 2 + 128;
+            if (entry.hits > 0)
+                continue;
+            this.#remove(oldKey);
             this.#evictions += 1;
         }
-        this.#entries.set(key, encoded);
+        if (this.#bytes + size > this.maxBytes) {
+            this.#rejections += 1;
+            return;
+        }
+        this.#entries.set(key, { encoded, hits: 0 });
         this.#bytes += size;
+        this.#coldBytes += size;
+    }
+    #remember(key) {
+        this.#doorkeeper.delete(key);
+        this.#doorkeeper.add(key);
+        if (this.#doorkeeper.size > DOORKEEPER_KEYS)
+            this.#doorkeeper.delete(this.#doorkeeper.values().next().value);
+    }
+    #remove(key) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined)
+            return;
+        const size = entrySize(key, entry.encoded);
+        this.#entries.delete(key);
+        this.#bytes -= size;
+        if (entry.hits === 0)
+            this.#coldBytes -= size;
+    }
+    #age() {
+        this.#puts += 1;
+        if (this.#puts % HIT_AGING_INTERVAL !== 0)
+            return;
+        for (const [key, entry] of this.#entries) {
+            if (entry.hits === 0)
+                continue;
+            entry.hits = Math.floor(entry.hits / 2);
+            if (entry.hits === 0)
+                this.#coldBytes += entrySize(key, entry.encoded);
+        }
     }
     clear() {
         this.#entries.clear();
+        this.#doorkeeper.clear();
         this.#bytes = 0;
+        this.#coldBytes = 0;
     }
     statistics() {
         return {
             hits: this.#hits,
             misses: this.#misses,
             evictions: this.#evictions,
+            rejections: this.#rejections,
             retainedBytes: this.#bytes,
             retainedDocuments: this.#entries.size,
         };
     }
 }
+function entrySize(key, encoded) {
+    return encoded.length + key.length * 2 + 128;
+}
 // All domains call the same parser; cache keys include both bytes and source location.
 // Authorization remains in workspace reads, before any document reaches this cache.
 export const sourceDocuments = new SourceDocumentCache();

package/dist/hoi4_agent_tools/event/service.js

@@ -1308,6 +1308,13 @@ export class EventChainViewer {
         input.signal?.throwIfAborted();
         if (input.proposedSources !== undefined)
             assertProposedSourceBounds(input.proposedSources);
+        // Without references the comparison uses the previous cached revision; with none cached,
+        // say so before scanning the workspace.
+        if (input.before === undefined &&
+            input.after === undefined &&
+            input.proposedSources === undefined &&
+            (this.#state.history.get(input.workspaceId)?.size ?? 0) === 0)
+            throw new ServiceError('EVENT_COMPARISON_BASELINE_REQUIRED', 'Provide a cached revision, graph artifact, or proposed source overlay');
         const refresh = input.refresh ??
             (input.proposedSources !== undefined ||
                 input.before === undefined ||

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

@@ -477,24 +477,32 @@ function scriptedImageTokens(scripted) {
  * 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()) {
+export function resolveScenarioScriptedLocalisation(graph, windowName, base, 
+/** Built only when the window shows scripted localisation; building scans every helper. */
+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 names = new Set(graph.scriptedLocalisation.map(({ name }) => name));
+    const shown = (token) => names.has(token.slice(token.lastIndexOf('.') + 1));
+    const imageTokens = scriptedImageTokens(scripted);
+    if (![...textual, ...imageTokens].some(shown))
+        return base;
+    const evaluation = definitions();
     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, []);
+        : scriptedLocalisationValue(graph, key, base.language, kind, explicitValues, base, evaluation, []);
     for (const key of textual) {
         const template = evaluate(key, 'text');
         if (template !== undefined)
             templates.set(key, template);
     }
-    for (const key of scriptedImageTokens(scripted)) {
+    for (const key of imageTokens) {
         const sprite = evaluate(key, 'image');
         if (sprite !== undefined)
             values[key] = sprite;