hoi4-agent-tools 3.10.0 → 4.0.1

package/dist/hoi4_agent_tools/core/persistent-analysis-cache.js

@@ -11,7 +11,7 @@ const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
 const entryKindSchema = z.enum(['source-document', 'index-segment']);
 const unsignedEntrySchema = z
     .object({
-    version: z.literal(1),
+    version: z.literal(2),
     kind: entryKindSchema,
     scopeHash: digestSchema,
     address: digestSchema,
@@ -23,6 +23,15 @@ const unsignedEntrySchema = z
     .strict();
 const entrySchema = unsignedEntrySchema.extend({ authenticationTag: digestSchema }).strict();
 const entryFilePattern = /^(?<address>[a-f0-9]{64})\.json$/u;
+/**
+ * What the authentication tag covers: every field but the payload bytes, which the tag binds
+ * through their SHA-256. A reader hashes the payload once and compares it, so the megabytes of
+ * a parsed document do not pass through canonical JSON and the HMAC as well.
+ */
+function entryIdentity(entry) {
+    const { payload: _payload, ...identity } = entry;
+    return { kind: 'analysis-cache-entry.v2', entry: identity };
+}
 function sourceAddress(key) {
     return hashCanonical({
         version: 'persistent-source-document.v1',
@@ -114,10 +123,7 @@ export class PersistentAnalysisCache {
                 const payload = await this.read(scopeHash, 'source-document', documentAddress, signal);
                 if (payload !== undefined) {
                     try {
-                        documents.importEncoded(key, payload, {
-                            bytes: file.bytes,
-                            sourcePath: file.displayPath,
-                        });
+                        documents.importEncoded(key, payload);
                     }
                     catch {
                         this.#invalidEntries += 1;
@@ -172,22 +178,23 @@ export class PersistentAnalysisCache {
                 }
                 const key = sourceDocumentCacheKey(file.bytes, file.displayPath);
                 const documentAddress = sourceAddress(key);
-                const document = documents.exportEncoded(key);
-                if (document !== undefined &&
-                    (!sourceEntries.has(documentAddress) ||
-                        this.#invalidAddresses.has(`${scopeHash}\0source-document\0${documentAddress}`))) {
-                    if (await retain('source-document', documentAddress, document)) {
+                // Stored entries are skipped before their payload is exported, which copies it.
+                if (!sourceEntries.has(documentAddress) ||
+                    this.#invalidAddresses.has(`${scopeHash}\0source-document\0${documentAddress}`)) {
+                    const document = documents.exportEncoded(key);
+                    if (document !== undefined &&
+                        (await retain('source-document', documentAddress, document))) {
                         sourceEntries.add(documentAddress);
                     }
                 }
                 for (const provinceDefinition of [false, true]) {
                     const address = indexSegmentAddress(file, provinceDefinition);
-                    const segment = segments.exportEncoded(address);
-                    if (segment === undefined ||
-                        (indexEntries.has(address) &&
-                            !this.#invalidAddresses.has(`${scopeHash}\0index-segment\0${address}`)))
+                    if (indexEntries.has(address) &&
+                        !this.#invalidAddresses.has(`${scopeHash}\0index-segment\0${address}`))
                         continue;
-                    if (await retain('index-segment', address, Buffer.from(segment))) {
+                    const segment = segments.exportEncoded(address);
+                    if (segment !== undefined &&
+                        (await retain('index-segment', address, Buffer.from(segment)))) {
                         indexEntries.add(address);
                     }
                 }
@@ -254,7 +261,7 @@ export class PersistentAnalysisCache {
             if (entry.scopeHash !== scopeHash ||
                 entry.kind !== kind ||
                 entry.address !== address ||
-                !this.state.verifyJournal({ kind: 'analysis-cache-entry.v1', entry }, authenticationTag))
+                !this.state.verifyJournal(entryIdentity(entry), authenticationTag))
                 throw new Error('Persistent analysis cache authentication or identity is invalid');
             const payload = Buffer.from(entry.payload, 'base64');
             if (payload.length > this.maxSingleBytes || sha256Bytes(payload) !== entry.payloadHash)
@@ -289,7 +296,7 @@ export class PersistentAnalysisCache {
         const target = await containedGeneratedPath(directory, `${digestSchema.parse(address)}.json`);
         const invalidAddress = `${scopeHash}\0${kind}\0${address}`;
         const unsigned = {
-            version: 1,
+            version: 2,
             kind,
             scopeHash,
             address,
@@ -300,10 +307,7 @@ export class PersistentAnalysisCache {
         };
         const bytes = Buffer.from(canonicalJson({
             ...unsigned,
-            authenticationTag: this.state.authenticateJournal({
-                kind: 'analysis-cache-entry.v1',
-                entry: unsigned,
-            }),
+            authenticationTag: this.state.authenticateJournal(entryIdentity(unsigned)),
         }));
         if (bytes.length > Math.ceil((this.maxSingleBytes * 4) / 3) + 4096) {
             this.#oversized += 1;

package/dist/hoi4_agent_tools/core/server-registry.js

@@ -11,6 +11,7 @@ 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 ABANDONED_MS = 24 * STALE_MS;
 const recordSchema = z
     .object({
     pid: z.number().int().positive(),
@@ -78,8 +79,13 @@ export class ServerRegistry {
         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);
+            try {
+                await writeFile(temporary, `${JSON.stringify(this.current())}\n`);
+                await rename(temporary, file);
+            }
+            catch {
+                await unlink(temporary).catch(() => undefined);
+            }
         })
             .catch(() => undefined);
         beat();
@@ -109,9 +115,14 @@ export class ServerRegistry {
         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);
+            const entries = await readdir(root).catch(() => []);
+            // Temporary heartbeat files left by a failed rename.
+            for (const name of entries) {
+                const temporary = /^\d+\.json\.(\d+)\.tmp$/u.exec(name);
+                if (temporary !== null && Date.now() - Number(temporary[1]) > STALE_MS)
+                    await unlink(path.join(root, name)).catch(() => undefined);
+            }
+            const names = entries.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')
@@ -128,6 +139,12 @@ export class ServerRegistry {
                     continue;
                 }
                 const age = Date.now() - Date.parse(record.updatedAt);
+                // A record silent for this long belongs to an exited process whose pid was reused.
+                if (age > ABANDONED_MS) {
+                    removed += 1;
+                    await unlink(file).catch(() => undefined);
+                    continue;
+                }
                 servers.push({ ...record, state: age > STALE_MS ? 'stale' : 'live' });
             }
         }

package/dist/hoi4_agent_tools/core/shared-request-capacity.js

@@ -20,11 +20,13 @@ export class SharedRequestCapacity {
     stateRoot;
     capacity;
     deletePendingLimitMs;
+    leaseMaxAgeMs;
     now;
     constructor(stateRoot, capacity = 4, options = {}) {
         this.stateRoot = stateRoot;
         this.capacity = capacity;
         this.deletePendingLimitMs = options.deletePendingLimitMs ?? 60_000;
+        this.leaseMaxAgeMs = options.leaseMaxAgeMs;
         this.now = options.now ?? Date.now;
     }
     async run(signal, action) {
@@ -34,6 +36,7 @@ export class SharedRequestCapacity {
                 handoffToProcess: () => {
                     return Promise.reject(new ServiceError('REQUEST_LEASE_STORAGE_REQUIRED', 'Worker ownership transfer requires persistent capacity storage'));
                 },
+                reclaimFromProcess: () => Promise.resolve(),
             });
         const root = await containedGeneratedPath(await canonicalPath(this.stateRoot, signal), 'request-capacity', sha256Bytes(hostname().toLowerCase()).slice(0, 16));
         await mkdir(root, { recursive: true });
@@ -112,6 +115,14 @@ export class SharedRequestCapacity {
                             owner = next;
                             transferredPid = pid;
                         },
+                        reclaimFromProcess: async () => {
+                            if (transferredPid === undefined)
+                                return;
+                            const next = path.join(slot, `${process.pid}-${randomUUID()}.lease`);
+                            await retryWindowsSharing(() => rename(owner, next));
+                            owner = next;
+                            transferredPid = undefined;
+                        },
                     });
                 }
                 finally {
@@ -137,6 +148,18 @@ export class SharedRequestCapacity {
             await delay(sharingRetryDelay(waits) * (0.75 + Math.random() / 2), undefined, { signal });
         }
     }
+    async leaseExpired(lease) {
+        if (this.leaseMaxAgeMs === undefined)
+            return false;
+        try {
+            return this.now() - (await lstat(lease)).mtimeMs > this.leaseMaxAgeMs;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }
     async reap(slot) {
         try {
             const metadata = await lstat(slot);
@@ -150,7 +173,9 @@ export class SharedRequestCapacity {
             else {
                 for (const name of owners) {
                     const match = /^([1-9][0-9]*)-[0-9a-f-]{36}\.lease$/u.exec(name);
-                    if (match === null || processAlive(Number(match[1])))
+                    if (match === null)
+                        return;
+                    if (processAlive(Number(match[1])) && !(await this.leaseExpired(path.join(slot, name))))
                         return;
                     // Unique owner names prevent a concurrent reaper from deleting a new lease.
                     await unlink(path.join(slot, name)).catch((error) => {

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

@@ -3,7 +3,7 @@ import { sha256Bytes } from '../canonical.js';
 export function sourceDocumentCacheKey(bytes, sourcePath) {
     return `${sha256Bytes(bytes)}:${sourcePath}`;
 }
-function decodedDocument(encoded, expected) {
+function decodedDocument(encoded) {
     const value = deserialize(encoded);
     if (value === null ||
         typeof value !== 'object' ||
@@ -20,11 +20,6 @@ function decodedDocument(encoded, expected) {
         !('bytes' in value) ||
         !(value.bytes instanceof Uint8Array))
         throw new Error('Persistent source document is structurally invalid');
-    if (expected !== undefined &&
-        (value.path !== expected.sourcePath ||
-            value.sourceRevision !== sha256Bytes(expected.bytes) ||
-            !Buffer.from(value.bytes).equals(Buffer.from(expected.bytes))))
-        throw new Error('Persistent source document does not match its source identity');
     return value;
 }
 /** Puts between halvings of every entry's hit count, so entries no longer read become evictable. */
@@ -64,13 +59,23 @@ export class SourceDocumentCache {
             this.#misses += 1;
             return undefined;
         }
+        let document;
+        try {
+            document = decodedDocument(entry.encoded);
+        }
+        catch {
+            // An imported entry is decoded here, on first use; one that cannot be decoded is a miss.
+            this.#remove(key);
+            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, entry);
-        return decodedDocument(entry.encoded);
+        return document;
     }
     /** Availability check without deserialization or cache-hit accounting. */
     has(key) {
@@ -96,9 +101,14 @@ export class SourceDocumentCache {
         }
         this.retain(key, serialize(document));
     }
-    /** Import one authenticated same-runtime entry without counting it as a process-local hit. */
-    importEncoded(key, encoded, expected) {
-        decodedDocument(encoded, expected);
+    /**
+     * Import one authenticated same-runtime entry without counting it as a process-local hit.
+     * The caller has verified the entry against the key's source bytes (the key is their hash and
+     * the path), so the document is decoded when it is first read instead of for every file at
+     * load, which cost as much as parsing the files again; `get` treats an undecodable entry as
+     * a miss.
+     */
+    importEncoded(key, encoded) {
         this.retain(key, Buffer.from(encoded));
     }
     exportEncoded(key) {

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

@@ -1,4 +1,12 @@
 import { SOURCE_LINE_LIMIT, SOURCE_TOKEN_LIMIT, SourceDiagnosticCollector } from './limits.js';
+const unicodeSpace = /\s/u;
+/** The same characters as the `\s` class; the regular expression only runs for non-ASCII text. */
+function isSpace(character) {
+    const code = character.charCodeAt(0);
+    if (code < 128)
+        return code === 32 || (code >= 9 && code <= 13);
+    return code > 159 && unicodeSpace.test(character);
+}
 const operatorStarts = new Set(['=', '<', '>', '!']);
 function startsOperator(text, index) {
     const character = text[index] ?? '';
@@ -141,8 +149,8 @@ export function lexClausewitz(text, sourcePath, options = {}) {
         const startLine = line;
         const startColumn = column;
         const current = text[index] ?? '';
-        if (/\s/u.test(current)) {
-            while (index < text.length && /\s/u.test(text[index] ?? ''))
+        if (isSpace(current)) {
+            while (index < text.length && isSpace(text[index] ?? ''))
                 advance();
             add('whitespace', start, startLine, startColumn);
             continue;
@@ -236,7 +244,7 @@ export function lexClausewitz(text, sourcePath, options = {}) {
         }
         while (index < text.length) {
             const character = text[index] ?? '';
-            if (/\s/u.test(character) ||
+            if (isSpace(character) ||
                 character === '#' ||
                 character === '{' ||
                 character === '}' ||

package/dist/hoi4_agent_tools/core/temporary-directories.js

@@ -0,0 +1,293 @@
+import { randomUUID } from 'node:crypto';
+import { lstatSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { lstat, open, readFile, readdir, realpath, rm } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import path from 'node:path';
+import { z } from 'zod/v4';
+const OWNER_FILE = '.hoi4-temp-owner.json';
+const SWEEP_LOCK = '.hoi4-temp-sweep.lock';
+export const TEMPORARY_MAX_BYTES = 256 * 1024 * 1024;
+export const TEMPORARY_STALE_MS = 3 * 60 * 60 * 1000;
+// Dated event evaluation directories contain retained benchmark evidence, not scratch files.
+const scratchName = /^hoi4-(?:reference-source|event-eval)-[A-Za-z0-9]{6}$/u;
+const ownerSchema = z
+    .object({
+    version: z.literal(1),
+    pid: z.number().int().positive(),
+    host: z.string().min(1).max(256),
+    token: z.uuid(),
+})
+    .strict();
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+async function owner(directory, name = OWNER_FILE) {
+    const file = path.join(directory, name);
+    try {
+        const metadata = await lstat(file);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > 4096)
+            return undefined;
+        const result = ownerSchema.safeParse(JSON.parse(await readFile(file, 'utf8')));
+        return result.success ? result.data : undefined;
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? null : undefined;
+    }
+}
+async function inventory(directory) {
+    const result = { bytes: 0, modified: 0, locked: false };
+    const pending = [directory];
+    let entries = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const metadata = await lstat(current);
+        if (++entries > 100_000)
+            throw new Error('Temporary directory inventory limit exceeded');
+        result.modified = Math.max(result.modified, metadata.mtimeMs, metadata.birthtimeMs);
+        if (metadata.isSymbolicLink())
+            continue;
+        if (metadata.isFile())
+            result.bytes += metadata.size;
+        else if (metadata.isDirectory()) {
+            for (const name of await readdir(current)) {
+                if (name === OWNER_FILE)
+                    continue;
+                if (/\.(?:lock|lease)$/u.test(name))
+                    result.locked = true;
+                pending.push(path.join(current, name));
+            }
+        }
+    }
+    return result;
+}
+function overlaps(left, right) {
+    const normalize = (value) => process.platform === 'win32' ? path.resolve(value).toLowerCase() : path.resolve(value);
+    const a = normalize(left);
+    const b = normalize(right);
+    const contains = (parent, child) => {
+        const relative = path.relative(parent, child);
+        return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    };
+    return contains(a, b) || contains(b, a);
+}
+/** Trusted startup maintenance only; never follows a junction or accepts an MCP path. */
+export async function sweepTemporaryDirectories(parent, options = {}) {
+    const now = options.now ?? Date.now();
+    const staleMs = options.staleMs ?? TEMPORARY_STALE_MS;
+    const maxBytes = options.maxBytes ?? TEMPORARY_MAX_BYTES;
+    const currentUid = options.currentUid ?? (process.platform === 'win32' ? undefined : process.geteuid?.());
+    if (!Number.isFinite(now) ||
+        !Number.isSafeInteger(staleMs) ||
+        staleMs < 0 ||
+        !Number.isSafeInteger(maxBytes) ||
+        maxBytes < 0 ||
+        (currentUid !== undefined && (!Number.isSafeInteger(currentUid) || currentUid < 0)))
+        throw new RangeError('Invalid temporary storage limits');
+    const root = await realpath(parent);
+    // A Windows runner reaches %TEMP% through an 8.3 alias; match protected roots by both spellings.
+    const protectedRoots = (await Promise.all((options.protectedRoots ?? []).map(async (protectedRoot) => {
+        try {
+            return [protectedRoot, await realpath(protectedRoot)];
+        }
+        catch {
+            return [protectedRoot];
+        }
+    }))).flat();
+    const candidates = [];
+    for (const name of (await readdir(root)).filter((name) => scratchName.test(name)).sort()) {
+        const directory = path.join(root, name);
+        if (protectedRoots.some((protectedRoot) => overlaps(directory, protectedRoot)))
+            continue;
+        try {
+            const metadata = await lstat(directory);
+            if (!metadata.isDirectory() ||
+                metadata.isSymbolicLink() ||
+                (currentUid !== undefined && metadata.uid !== currentUid) ||
+                (await realpath(directory)) !== directory)
+                continue;
+            const record = await owner(directory);
+            // An interrupted sweep must not leave a permanent lock. Malformed or live locks
+            // stay protected; only a confirmed dead local owner can relinquish its lock.
+            const previousSweep = await owner(directory, SWEEP_LOCK);
+            const deadSweep = previousSweep?.host === hostname() &&
+                !(options.isAlive ?? alive)(previousSweep.pid) &&
+                (await owner(directory, SWEEP_LOCK))?.token === previousSweep.token;
+            if (deadSweep)
+                await rm(path.join(directory, SWEEP_LOCK));
+            const data = await inventory(directory);
+            const dead = record?.host === hostname() && !(options.isAlive ?? alive)(record.pid);
+            candidates.push({
+                directory,
+                ...data,
+                eligible: !data.locked && (dead || deadSweep || (record === null && now - data.modified > staleMs)),
+            });
+        }
+        catch {
+            // Sharing violations, malformed leases and incomplete inventories fail closed.
+        }
+    }
+    let retainedBytes = candidates.reduce((sum, entry) => sum + entry.bytes, 0);
+    let removed = 0;
+    candidates.sort((a, b) => a.modified - b.modified || (a.directory < b.directory ? -1 : 1));
+    for (const entry of candidates) {
+        if (!entry.eligible || (now - entry.modified <= staleMs && retainedBytes <= maxBytes))
+            continue;
+        const lockPath = path.join(entry.directory, SWEEP_LOCK);
+        let lock;
+        let claimed = false;
+        const token = randomUUID();
+        try {
+            lock = await open(lockPath, 'wx', 0o600);
+            claimed = true;
+            await lock.writeFile(JSON.stringify({ version: 1, pid: process.pid, host: hostname(), token }));
+            const record = await owner(entry.directory);
+            if (record === undefined ||
+                (record !== null && (record.host !== hostname() || (options.isAlive ?? alive)(record.pid))))
+                continue;
+            // Check containment again immediately before recursive removal.
+            if ((await lstat(entry.directory)).isSymbolicLink() ||
+                (await realpath(entry.directory)) !== entry.directory)
+                continue;
+            if ((await owner(entry.directory, SWEEP_LOCK))?.token !== token)
+                continue;
+            await lock.close();
+            lock = undefined;
+            await rm(entry.directory, { recursive: true, force: true });
+            retainedBytes -= entry.bytes;
+            removed += 1;
+        }
+        catch {
+            // Windows may still hold a file open. Leave it for a later sweep.
+        }
+        finally {
+            await lock?.close().catch(() => undefined);
+            if (claimed && (await owner(entry.directory, SWEEP_LOCK))?.token === token)
+                await rm(lockPath, { force: true }).catch(() => undefined);
+        }
+    }
+    return { removed, retainedBytes };
+}
+/** Own only directories allocated by this process; exit cleanup never uses a prefix sweep. */
+export class TemporaryDirectoryLifetime {
+    maxBytes;
+    #owned = new Map();
+    #reservedFiles = new Map();
+    #reservedBytes = 0;
+    #onExit = () => this.disposeSync();
+    constructor(maxBytes = TEMPORARY_MAX_BYTES) {
+        this.maxBytes = maxBytes;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+            throw new RangeError('Invalid temporary storage budget');
+        process.once('exit', this.#onExit);
+    }
+    /** Reject an oversized fixture before truncate allocates its disk blocks on Windows. */
+    assertFileSize(file, bytes) {
+        const requested = path.resolve(file);
+        // Fixture paths are canonical, so resolve an aliased parent before matching them.
+        let absolute = requested;
+        try {
+            absolute = path.join(realpathSync.native(path.dirname(requested)), path.basename(requested));
+        }
+        catch {
+            // A file in a directory that does not exist yet cannot be inside an owned fixture.
+        }
+        if (!this.paths().some((directory) => absolute.startsWith(`${directory}${path.sep}`)))
+            return;
+        if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > this.maxBytes)
+            throw new RangeError('Temporary fixture exceeds the disk budget; use a small injected limit');
+        const previous = this.#reservedFiles.get(absolute) ?? 0;
+        if (this.#reservedBytes - previous + bytes > this.maxBytes)
+            throw new RangeError('Temporary fixtures exceed the disk budget');
+        // Reserve before the caller writes, so concurrent allocations cannot oversubscribe.
+        // Failed writes remain reserved until teardown, which fails safely rather than undercounts.
+        this.#reservedBytes += bytes - previous;
+        this.#reservedFiles.set(absolute, bytes);
+    }
+    async own(directory) {
+        const canonical = await realpath(directory);
+        // The parent may be reached through an alias, such as a Windows 8.3 short name for the user
+        // profile; the fixture directory itself must be a real directory, not a link.
+        const resolved = path.resolve(directory);
+        const viaParent = path.join(await realpath(path.dirname(resolved)), path.basename(resolved));
+        if ((await lstat(directory)).isSymbolicLink() || canonical !== viaParent)
+            throw new Error('Temporary directory must be canonical and unlinked');
+        const sweepLock = path.join(canonical, SWEEP_LOCK);
+        if (await lstat(sweepLock).catch(() => undefined))
+            throw new Error('Temporary directory is being swept');
+        const token = randomUUID();
+        const handle = await open(path.join(canonical, OWNER_FILE), 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify({ version: 1, pid: process.pid, host: hostname(), token }));
+            this.#owned.set(canonical, token);
+            if (await lstat(sweepLock).catch(() => undefined))
+                throw new Error('Temporary directory is being swept');
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    paths() {
+        return [...this.#owned.keys()];
+    }
+    async release(requested) {
+        let directory = requested;
+        if (!this.#owned.has(directory)) {
+            // Owned paths are canonical; a caller may still hold an 8.3 or symlinked spelling.
+            try {
+                directory = await realpath(requested);
+            }
+            catch {
+                return;
+            }
+        }
+        const token = this.#owned.get(directory);
+        if (token === undefined)
+            return;
+        if ((await owner(directory))?.token !== token) {
+            this.#owned.delete(directory);
+            this.#forgetFiles(directory);
+            return;
+        }
+        if ((await lstat(directory)).isSymbolicLink() || (await realpath(directory)) !== directory)
+            throw new Error('Temporary directory changed before cleanup');
+        await rm(directory, { recursive: true, force: true });
+        this.#owned.delete(directory);
+        this.#forgetFiles(directory);
+    }
+    #forgetFiles(directory) {
+        for (const [file, bytes] of this.#reservedFiles)
+            if (file.startsWith(`${directory}${path.sep}`)) {
+                this.#reservedBytes -= bytes;
+                this.#reservedFiles.delete(file);
+            }
+    }
+    async dispose() {
+        for (const directory of this.paths())
+            await this.release(directory);
+        process.removeListener('exit', this.#onExit);
+    }
+    disposeSync() {
+        for (const [directory, token] of this.#owned) {
+            try {
+                if (lstatSync(directory).isSymbolicLink() || realpathSync.native(directory) !== directory)
+                    continue;
+                const parsed = ownerSchema.safeParse(JSON.parse(readFileSync(path.join(directory, OWNER_FILE), 'utf8')));
+                if (parsed.success && parsed.data.token === token)
+                    rmSync(directory, { recursive: true, force: true });
+            }
+            catch {
+                // A crash or sharing violation is recovered by the next stale sweep.
+            }
+        }
+        this.#owned.clear();
+        this.#reservedFiles.clear();
+        this.#reservedBytes = 0;
+        process.removeListener('exit', this.#onExit);
+    }
+}