hoi4-agent-tools 3.9.0 → 4.0.0

package/dist/hoi4_agent_tools/core/canonical.js

@@ -16,10 +16,24 @@ export function canonicalize(value) {
         return value.map(canonicalize);
     if (typeof value === 'object') {
         const object = value;
-        return Object.fromEntries(Object.keys(object)
-            .sort(compareCodeUnits)
-            .filter((key) => object[key] !== undefined)
-            .map((key) => [key, canonicalize(object[key])]));
+        // Filling the copy directly avoids an entry array per member; a plain object lists integer
+        // keys first and the rest in insertion (here code unit) order, the same as before.
+        const copy = {};
+        for (const key of Object.keys(object).sort(compareCodeUnits)) {
+            const member = object[key];
+            if (member === undefined)
+                continue;
+            if (key === '__proto__')
+                Object.defineProperty(copy, key, {
+                    value: canonicalize(member),
+                    enumerable: true,
+                    writable: true,
+                    configurable: true,
+                });
+            else
+                copy[key] = canonicalize(member);
+        }
+        return copy;
     }
     throw new TypeError(`Canonical JSON cannot contain ${typeof value}`);
 }

package/dist/hoi4_agent_tools/core/configuration.js

@@ -155,6 +155,11 @@ export const serverConfigurationSchema = z
     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(),
+    /**
+     * A job worker stays warm this many seconds after a job, so the next job reuses its loaded
+     * indexes instead of scanning cold; 0 starts a fresh worker for every job.
+     */
+    jobWorkerIdleSeconds: z.number().int().min(0).max(3_600).default(180),
     scanMaxBytes: z
         .number()
         .int()
@@ -182,6 +187,8 @@ export const serverConfigurationSchema = z
         .default(134_217_728),
     modRoots: z.array(z.string().min(1)).max(WORKSPACE_MAX_SOURCE_ROOTS).default([]),
     gameRoot: z.string().min(1).optional(),
+    /** The game's user-data folder holding logs/ and mod/; derived from the mod folder when unset. */
+    gameUserRoot: z.string().min(1).optional(),
     workspaceStorageRoot: z.string().min(1).optional(),
     storageRoots: z.array(z.string().min(1)).max(WORKSPACE_MAX_SOURCE_ROOTS).default([]),
     workspaces: z.array(workspaceRegistrationSchema).max(WORKSPACE_MAX_REGISTRATIONS).default([]),

package/dist/hoi4_agent_tools/core/domain-scan-patterns.js

@@ -78,6 +78,18 @@ export function countryAssetDiscoveryPatterns(workspace) {
         ...under(roots.gfx, '**/*.gfx'),
     ]);
 }
+/**
+ * The changed files of a map rewrite plus the province definitions they refer to. A state file
+ * lists provinces that `map/definition.csv` defines, usually in the base game, so a scan of the
+ * changed files alone would report every listed province as unresolved.
+ */
+export function mapChangeScanPatterns(relativePaths) {
+    return uniquePatterns([
+        ...exactChangedFilePatterns(relativePaths),
+        'map/default.map',
+        'map/*.csv',
+    ]);
+}
 export function exactChangedFilePatterns(relativePaths) {
     return uniquePatterns(relativePaths.map((relativePath) => relativePath.replaceAll('\\', '/').replace(/^\.\//u, '')));
 }

package/dist/hoi4_agent_tools/core/domain-tools.js

@@ -0,0 +1,65 @@
+import { decisionInspectRequestSchema, impactInspectRequestSchema } from '../schemas/analysis.js';
+import { eventInspectRequestSchema, eventRenderRequestSchema } from '../schemas/event.js';
+import { focusInspectRequestSchema, focusRenderRequestSchema, focusRewriteRequestSchema, } from '../schemas/focus-requests.js';
+import { guiInspectRequestSchema, guiRenderRequestSchema, guiRewriteRequestSchema, } from '../schemas/gui-requests.js';
+import { mapInspectRequestSchema, mapRewriteRequestSchema } from '../schemas/map-requests.js';
+import { probabilityAnalyzeRequestSchema, probabilityInspectRequestSchema, } from '../schemas/probability-requests.js';
+import { mechanicTestRequestSchema, packageCheckRequestSchema, scenarioTestRequestSchema, } from '../schemas/scenarios.js';
+import { technologyInspectRequestSchema, technologyRenderRequestSchema, } from '../schemas/technology.js';
+/**
+ * The single list of domain tools that run as durable jobs. Task routing, worker admission,
+ * request lifecycles and job validation all read this list, so adding, merging or removing a
+ * domain tool happens in one place.
+ */
+export const DOMAIN_TOOL_NAMES = [
+    'hoi4.impact_inspect',
+    'hoi4.decision_inspect',
+    'hoi4.mechanic_test',
+    'hoi4.package_check',
+    'hoi4.scenario_test',
+    'hoi4.event_inspect',
+    'hoi4.event_render',
+    'hoi4.tech_inspect',
+    'hoi4.tech_render',
+    'hoi4.probability_inspect',
+    'hoi4.probability_analyze',
+    'hoi4.map_inspect',
+    'hoi4.map_rewrite',
+    'hoi4.gui_inspect',
+    'hoi4.gui_render',
+    'hoi4.gui_rewrite',
+    'hoi4.focus_inspect',
+    'hoi4.focus_render',
+    'hoi4.focus_rewrite',
+];
+export const DOMAIN_TOOL_ARGUMENT_SCHEMAS = {
+    'hoi4.impact_inspect': impactInspectRequestSchema,
+    'hoi4.decision_inspect': decisionInspectRequestSchema,
+    'hoi4.mechanic_test': mechanicTestRequestSchema,
+    'hoi4.package_check': packageCheckRequestSchema,
+    'hoi4.scenario_test': scenarioTestRequestSchema,
+    'hoi4.event_inspect': eventInspectRequestSchema,
+    'hoi4.event_render': eventRenderRequestSchema,
+    'hoi4.tech_inspect': technologyInspectRequestSchema,
+    'hoi4.tech_render': technologyRenderRequestSchema,
+    'hoi4.probability_inspect': probabilityInspectRequestSchema,
+    'hoi4.probability_analyze': probabilityAnalyzeRequestSchema,
+    'hoi4.map_inspect': mapInspectRequestSchema,
+    'hoi4.map_rewrite': mapRewriteRequestSchema,
+    'hoi4.gui_inspect': guiInspectRequestSchema,
+    'hoi4.gui_render': guiRenderRequestSchema,
+    'hoi4.gui_rewrite': guiRewriteRequestSchema,
+    'hoi4.focus_inspect': focusInspectRequestSchema,
+    'hoi4.focus_render': focusRenderRequestSchema,
+    'hoi4.focus_rewrite': focusRewriteRequestSchema,
+};
+const domainToolNames = new Set(DOMAIN_TOOL_NAMES);
+export function isDomainToolName(name) {
+    return domainToolNames.has(name);
+}
+/** Domain tools that change mod source. */
+export const MUTATION_TOOL_NAMES = new Set([
+    'hoi4.gui_rewrite',
+    'hoi4.map_rewrite',
+    'hoi4.focus_rewrite',
+]);

package/dist/hoi4_agent_tools/core/domain-validation.js

@@ -1,6 +1,6 @@
 import { boundedSourceHashEvidence, publicArtifactLink } from './artifacts.js';
 import { canonicalJson } from './canonical.js';
-import { exactChangedFilePatterns, focusDomainScanPatterns } from './domain-scan-patterns.js';
+import { exactChangedFilePatterns, focusDomainScanPatterns, mapChangeScanPatterns, } from './domain-scan-patterns.js';
 import { parseClausewitz } from './source/index.js';
 import { TRANSACTION_MAX_DIAGNOSTICS } from './transaction-limits.js';
 import { importContinuousFocusPalettes, importFocusTrees, layoutFocusTreeAsync, lintContinuousFocusPalette, lintFocusTree, } from '../focus/index.js';
@@ -31,10 +31,13 @@ export async function postValidateTransaction(engine, transaction, principal, si
     const workspace = engine.resolver.get(transaction.workspaceId, principal);
     const focusTransaction = transaction.operationKind === 'focus-plan-changes' ||
         transaction.operationKind === 'continuous-focus-plan-changes';
+    const changedPaths = transaction.files.map(({ relativePath }) => relativePath);
     const snapshot = await engine.scan(transaction.workspaceId, {
         patterns: focusTransaction
             ? focusDomainScanPatterns(workspace)
-            : exactChangedFilePatterns(transaction.files.map(({ relativePath }) => relativePath)),
+            : transaction.operationKind === 'agent-nudger-map-changes'
+                ? mapChangeScanPatterns(changedPaths)
+                : exactChangedFilePatterns(changedPaths),
     }, principal, signal);
     const changed = new Set(transaction.files.map(({ relativePath }) => sourcePathComparisonKey(relativePath)));
     const diagnostics = snapshot.diagnostics.filter(({ location }) => {

package/dist/hoi4_agent_tools/core/engine.js

@@ -9,6 +9,13 @@ 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';
+import { ServiceError } from './result.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;
@@ -124,8 +131,21 @@ export class CoreEngine {
     }
     async initialize() {
         for (const workspace of this.resolver.list()) {
-            // Recovery repairs an interrupted internal rewrite before the workspace is exposed.
-            await this.transactions.recover(workspace.id);
+            // Recovery repairs an interrupted internal rewrite before the workspace is exposed. A
+            // journal that cannot be recovered blocks rewrites of its own workspace, not the server.
+            try {
+                await this.transactions.recover(workspace.id);
+            }
+            catch (error) {
+                this.transactions.recordRecoveryFailure(workspace.id, error);
+                process.stderr.write(`${JSON.stringify({
+                    level: 'error',
+                    event: 'transaction_recovery_blocked',
+                    workspaceId: workspace.id,
+                    code: error instanceof ServiceError ? error.code : 'TRANSACTION_RECOVERY_FAILED',
+                    message: error instanceof Error ? error.message : String(error),
+                })}\n`);
+            }
         }
     }
     status(workspaceId, principal) {
@@ -154,6 +174,7 @@ export class CoreEngine {
     }
     async scan(workspaceId, options = {}, principal, signal) {
         signal?.throwIfAborted();
+        await this.resolver.refreshDescriptors(workspaceId, principal);
         const workspace = this.resolver.get(workspaceId, principal);
         const patterns = options.patterns ?? defaultPatterns(workspace);
         const ignore = options.ignore;
@@ -167,9 +188,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 +211,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 +223,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 +241,30 @@ 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);
+                        // Snapshots hold every file's bytes; keep all of them within twice one scan's limit.
+                        const limit = this.resolver.config().scanMaxBytes * 2;
+                        const bytes = (cached) => cached.files.reduce((sum, { size }) => sum + size, 0);
+                        let retainedBytes = [...this.#scanCache.values()].reduce((sum, cached) => sum + bytes(cached), 0);
+                        for (const [key, cached] of this.#scanCache) {
+                            if (retainedBytes <= limit)
+                                break;
+                            if (key === cacheKey)
+                                continue;
+                            this.#scanCache.delete(key);
+                            retainedBytes -= bytes(cached);
+                        }
                     }
                     return snapshot;
                 });
@@ -384,7 +429,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: 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: this.diagnostics.slice(diagnostics),
+        });
+        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-executor.js

@@ -67,7 +67,12 @@ export class JobExecutor {
         this.jobs = jobs;
         this.operations = operations;
     }
-    async run(workspaceId, id, principal) {
+    /**
+     * `deadlineMs` (epoch milliseconds) stops a read-only operation that is still running then
+     * and records JOB_DEADLINE_EXCEEDED as the job's owner. An operation that never yields cannot
+     * observe it; its supervising host stops the process instead.
+     */
+    async run(workspaceId, id, principal, options = {}) {
         const initial = await this.jobs.get(workspaceId, id, principal);
         if (['completed', 'failed', 'cancelled'].includes(initial.status))
             return initial;
@@ -101,6 +106,12 @@ export class JobExecutor {
         const controller = new AbortController();
         const watchStop = new AbortController();
         let watchFailure;
+        const deadlineTimer = options.deadlineMs === undefined || operation.mutation
+            ? undefined
+            : setTimeout(() => {
+                watchFailure = new ServiceError('JOB_DEADLINE_EXCEEDED', 'The job ran past its deadline and was stopped; narrow its selector or limits, or raise jobDeadlineSeconds');
+                controller.abort(watchFailure);
+            }, Math.max(0, options.deadlineMs - Date.now()));
         const watch = (async () => {
             while (!watchStop.signal.aborted) {
                 const current = await this.jobs.get(workspaceId, id, principal);
@@ -183,6 +194,8 @@ export class JobExecutor {
             });
         }
         finally {
+            if (deadlineTimer !== undefined)
+                clearTimeout(deadlineTimer);
             watchStop.abort();
             await watch;
         }

package/dist/hoi4_agent_tools/core/job-operation-registration.js

@@ -1,5 +1,19 @@
 import { JobOperations } from './job-executor.js';
 import { ServiceError } from './result.js';
+const analysisTools = [
+    'hoi4.impact_inspect',
+    'hoi4.decision_inspect',
+    'hoi4.mechanic_test',
+    'hoi4.package_check',
+    'hoi4.scenario_test',
+];
+/** The domain whose registration serves a tool, so a warm worker registers each domain once. */
+export function workerDomain(toolName) {
+    if (analysisTools.includes(toolName))
+        return 'analysis';
+    const match = /^hoi4\.([a-z]+)_/u.exec(toolName);
+    return match?.[1] ?? toolName;
+}
 /** Load one trusted domain after the authenticated job identifies its operation. */
 export async function registerWorkerOperations(engine, toolName) {
     const operations = new JobOperations();
@@ -15,13 +29,7 @@ export async function registerWorkerOperations(engine, toolName) {
         (await import('../probability/job-operations.js')).registerProbabilityJobs(operations, engine);
     else if (toolName.startsWith('hoi4.tech_'))
         (await import('../technology/job-operations.js')).registerTechnologyJobs(operations, engine);
-    else if ([
-        'hoi4.impact_inspect',
-        'hoi4.decision_inspect',
-        'hoi4.mechanic_test',
-        'hoi4.package_check',
-        'hoi4.scenario_test',
-    ].includes(toolName))
+    else if (analysisTools.includes(toolName))
         (await import('./analysis-job-operations.js')).registerAnalysisJobs(operations, engine);
     else
         throw new ServiceError('JOB_OPERATION_UNAVAILABLE', 'No trusted worker domain matches this job');

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

@@ -251,6 +251,8 @@ export async function publishJobRecord(temporary, target, options = {}) {
     const { publish = rename, ...retry } = options;
     await retryWindowsSharing(() => publish(temporary, target), retry);
 }
+const JOB_STORE_LOCK_WAIT_MS = 120_000;
+const JOB_STORE_LEASE_MAX_AGE_MS = 600_000;
 /** Internal durable job records. Callers must obtain scopes from the authorized workspace resolver. */
 export class JobStore {
     state;
@@ -263,6 +265,22 @@ export class JobStore {
         this.lock = lock;
         this.maxRecordBytes = maxRecordBytes;
     }
+    /**
+     * Run under the store lock, waiting at most JOB_STORE_LOCK_WAIT_MS for it. A lock left by a
+     * crashed process whose pid was reused looks held forever; a bounded wait reports it instead
+     * of hanging every job operation. The wait bound never interrupts the locked action.
+     */
+    async locked(signal, action) {
+        const bounded = AbortSignal.any([signal, AbortSignal.timeout(JOB_STORE_LOCK_WAIT_MS)]);
+        try {
+            return await this.lock.run(bounded, action);
+        }
+        catch (error) {
+            if (bounded.aborted && !signal.aborted)
+                throw new ServiceError('JOB_STORE_BUSY', `The job store lock stayed held for ${JOB_STORE_LOCK_WAIT_MS / 1000} seconds; a crashed server process may still hold it`);
+            throw error;
+        }
+    }
     static async create(state, maxRecordBytes = 4 * 1024 * 1024) {
         if (!Number.isSafeInteger(maxRecordBytes) || maxRecordBytes < 1024)
             throw new RangeError('Job record budget must be an integer of at least 1024 bytes');
@@ -271,7 +289,10 @@ export class JobStore {
         await mkdir(root, { recursive: true, mode: 0o700 });
         await assertUnlinked(path.join(state.root, 'jobs'));
         await containedGeneratedPath(state.root, 'jobs');
-        return new JobStore(state, root, new SharedRequestCapacity(root, 1), maxRecordBytes);
+        return new JobStore(state, root, 
+        // Store operations hold the lock briefly, so an old lease is a crashed holder's even
+        // when its pid now belongs to another process.
+        new SharedRequestCapacity(root, 1, { leaseMaxAgeMs: JOB_STORE_LEASE_MAX_AGE_MS }), maxRecordBytes);
     }
     async submit(scopeInput, requestInput, signal = new AbortController().signal) {
         const scope = scopeSchema.parse(scopeInput);
@@ -287,7 +308,7 @@ export class JobStore {
         const legacyId = request.requestKey === undefined
             ? undefined
             : `job_${hashCanonical({ scope, key: request.requestKey })}`;
-        return this.lock.run(signal, async () => {
+        return this.locked(signal, async () => {
             const current = await this.read(scope, id);
             // Never lose an authenticated retry receipt merely because its identifier predates
             // secret-derived IDs. Read both under the publication lock and fail closed on damage.
@@ -351,7 +372,7 @@ export class JobStore {
     async removeTerminal(scopeInput, idInput, signal = new AbortController().signal) {
         const scope = scopeSchema.parse(scopeInput);
         const id = jobId.parse(idInput);
-        return this.lock.run(signal, async () => {
+        return this.locked(signal, async () => {
             const record = await this.read(scope, id);
             if (record === undefined)
                 return false;
@@ -372,7 +393,7 @@ export class JobStore {
     /** Claim execution once; an interrupted owner must be proven dead, never merely slow. */
     async claim(scope, id, ownerInput, signal = new AbortController().signal) {
         const owner = ownerSchema.parse(ownerInput);
-        return this.lock.run(signal, async () => {
+        return this.locked(signal, async () => {
             const current = await this.get(scope, id, signal);
             if (!['queued', 'running', 'reconciling'].includes(current.status))
                 throw new ServiceError('JOB_TERMINAL', 'The job already has a terminal outcome');
@@ -458,7 +479,7 @@ export class JobStore {
     }
     async update(scope, id, expectedRevision, update, signal = new AbortController().signal) {
         const patch = updateSchema.parse(update);
-        return this.lock.run(signal, async () => {
+        return this.locked(signal, async () => {
             const current = await this.get(scope, id, signal);
             if (current.revision !== expectedRevision)
                 throw new ServiceError('JOB_REVISION_CONFLICT', 'Job state changed; retrieve its current revision before updating');
@@ -490,6 +511,58 @@ export class JobStore {
         });
     }
     /** Operator-internal eviction guard; never returns another principal's job data. */
+    /**
+     * Remove expired, finished read-only records across every scope, inspecting at most
+     * `limit` directory entries. Records are otherwise removed only when they are read again,
+     * so results nobody polls would accumulate without bound.
+     */
+    async sweepExpired(limit = 5_000, signal = new AbortController().signal) {
+        let inspected = 0;
+        let removed = 0;
+        const terminal = (record) => record !== undefined &&
+            !record.request.mutation &&
+            ['completed', 'cancelled', 'failed'].includes(record.status) &&
+            jobRetentionExpired(record);
+        await assertUnlinked(this.root);
+        for await (const directory of await opendir(this.root)) {
+            if (++inspected > limit)
+                break;
+            signal.throwIfAborted();
+            if (directory.name === 'request-capacity' ||
+                directory.isSymbolicLink() ||
+                !directory.isDirectory() ||
+                !digest.safeParse(directory.name).success)
+                continue;
+            const scopeRoot = await containedGeneratedPath(this.root, directory.name);
+            for await (const entry of await opendir(scopeRoot)) {
+                if (++inspected > limit)
+                    break;
+                const id = entry.name.replace(/\.json$/u, '');
+                if (!entry.isFile() || !entry.name.endsWith('.json') || !jobId.safeParse(id).success)
+                    continue;
+                const file = await containedGeneratedPath(scopeRoot, entry.name);
+                const read = () => this.readEnvelope(file, id, directory.name).catch(() => undefined);
+                if (!terminal(await read()))
+                    continue;
+                const deleted = await this.locked(signal, async () => {
+                    if (!terminal(await read()))
+                        return false;
+                    try {
+                        await retryWindowsSharing(() => unlink(file), { signal });
+                        return true;
+                    }
+                    catch (error) {
+                        if (error.code === 'ENOENT')
+                            return false;
+                        throw error;
+                    }
+                });
+                if (deleted)
+                    removed += 1;
+            }
+        }
+        return removed;
+    }
     async checkpointResources(workspace, signal) {
         const resources = new Set();
         let inspected = 0;