@nanhara/hara 0.122.0 → 0.122.2

package/dist/gateway/discord.js

@@ -4,8 +4,6 @@
 // the cross-platform gateway plumbing (send_file, in-chat system context, stuck-guard, image attach/describe)
 // works unchanged. NOTE: receiving message text needs the privileged "Message Content Intent" enabled for the
 // bot in the Discord developer portal.
-import { readFileSync } from "node:fs";
-import { basename } from "node:path";
 import { InboundMediaBudget, savePrivateResponse } from "./media.js";
 import { chunkText } from "./telegram.js";
 const REST = "https://discord.com/api/v10";
@@ -75,10 +73,10 @@ export function discordAdapter(token) {
                 }).catch(() => { });
             }
         },
-        async sendFile(chatId, filePath) {
+        async sendFile(chatId, file) {
             const form = new FormData();
             form.append("payload_json", JSON.stringify({}));
-            form.append("files[0]", new Blob([readFileSync(filePath)]), basename(filePath));
+            form.append("files[0]", new Blob([new Uint8Array(file.bytes)]), file.safeName);
             await fetch(`${REST}/channels/${chatId}/messages`, { method: "POST", headers: auth, body: form }).catch(() => { });
         },
         async start(onMessage, signal, shouldDownload) {

package/dist/gateway/feishu.js

@@ -8,8 +8,6 @@
 // every binaries release fail. This form works under both resolutions.
 import * as larkNs from "@larksuiteoapi/node-sdk";
 const lark = (larkNs.default ?? larkNs);
-import { createReadStream } from "node:fs";
-import { basename } from "node:path";
 import { chunkText } from "./telegram.js";
 import { InboundMediaBudget, cleanupTransientMedia, savePrivateMedia } from "./media.js";
 /** Normalize a Feishu message's parsed content by type → text + any media keys (pure; download done by caller). */
@@ -203,18 +201,18 @@ export function feishuAdapter(appId, appSecret) {
                 /* best-effort cleanup — an unrecallable message just stays */
             }
         },
-        async sendFile(chatId, filePath) {
-            const name = basename(filePath);
+        async sendFile(chatId, file) {
+            const name = file.safeName;
             const isImg = /\.(png|jpe?g|gif|webp)$/i.test(name);
             if (isImg) {
-                const up = await client.im.image.create({ data: { image_type: "message", image: createReadStream(filePath) } });
+                const up = await client.im.image.create({ data: { image_type: "message", image: file.bytes } });
                 const key = up?.image_key ?? up?.data?.image_key;
                 if (!key)
                     throw new Error("Feishu image upload returned no image_key");
                 await sendMsg(chatId, "image", { image_key: key });
             }
             else {
-                const up = await client.im.file.create({ data: { file_type: "stream", file_name: name, file: createReadStream(filePath) } });
+                const up = await client.im.file.create({ data: { file_type: "stream", file_name: name, file: file.bytes } });
                 const key = up?.file_key ?? up?.data?.file_key;
                 if (!key)
                     throw new Error("Feishu file upload returned no file_key");

package/dist/gateway/flows-pending.js

@@ -22,6 +22,7 @@ import { createOpenAIProvider } from "../providers/openai.js";
 import { getValidQwenAuth } from "../providers/qwen-oauth.js";
 import { resolvePlatform } from "../providers/registry.js";
 import { validateAgainstSchema } from "../agent/structured.js";
+import { terminateSubprocessTree } from "../security/subprocess-env.js";
 const FILE = () => join(homedir(), ".hara", "flows-pending.json");
 const LOCK = () => FILE() + ".lock";
 const sleepCell = new Int32Array(new SharedArrayBuffer(4));
@@ -387,18 +388,6 @@ function boundedProcessDuration(value, fallback, max) {
 export function approvedOrgTimeoutMs(value = process.env.HARA_GATEWAY_ORG_TIMEOUT_MS) {
     return boundedProcessDuration(value, DEFAULT_APPROVED_ORG_TIMEOUT_MS, MAX_APPROVED_ORG_TIMEOUT_MS);
 }
-function signalChildGroup(child, signal) {
-    try {
-        if (process.platform !== "win32" && child.pid) {
-            process.kill(-child.pid, signal);
-            return true;
-        }
-        return child.kill(signal);
-    }
-    catch {
-        return false;
-    }
-}
 /** Run an approved delegation as one bounded process group. Exported for lifecycle regression tests. */
 export function runApprovedOrgProcess(command, args, options = {}) {
     if (options.signal?.aborted) {
@@ -425,10 +414,13 @@ export function runApprovedOrgProcess(command, args, options = {}) {
         let code = null;
         let exitSignal = null;
         let stopReason;
-        let killTimer;
         let drainTimer;
-        let forceTimer;
+        let forceIssued = false;
+        let terminationError;
+        let cancelTermination;
         const cap = (data) => {
+            if (settled || stopReason)
+                return;
             output = (output + data.toString()).slice(-8_000);
         };
         child.stdout?.on("data", cap);
@@ -441,43 +433,58 @@ export function runApprovedOrgProcess(command, args, options = {}) {
                 return;
             settled = true;
             clearTimeout(timeoutTimer);
-            if (killTimer)
-                clearTimeout(killTimer);
             if (drainTimer)
                 clearTimeout(drainTimer);
-            if (forceTimer)
-                clearTimeout(forceTimer);
+            // Preserve an already-scheduled force signal when the direct child closed after TERM. See the shared
+            // helper: close cancels only its API fallback, never the process-group SIGKILL.
+            cancelTermination?.();
             options.signal?.removeEventListener("abort", abortRun);
             child.stdout?.destroy();
             child.stderr?.destroy();
             resolveResult({ output, code, signal: exitSignal, ...(stopReason ? { stopReason } : {}), ...extra });
         };
-        const finishFromExit = () => finish();
+        const finishFromExit = () => {
+            if (stopReason && !forceIssued)
+                return;
+            finish(terminationError ? { error: terminationError } : {});
+        };
         const terminate = (reason) => {
-            if (settled)
+            if (settled || cancelTermination)
                 return;
             stopReason ??= reason;
-            if (exited)
-                return finishFromExit();
-            signalChildGroup(child, "SIGTERM");
-            killTimer = setTimeout(() => {
-                if (settled || exited)
-                    return;
-                signalChildGroup(child, "SIGKILL");
-                forceTimer = setTimeout(finishFromExit, 250);
-            }, killGraceMs);
+            cancelTermination = terminateSubprocessTree(child, {
+                processGroup: process.platform !== "win32",
+                graceMs: killGraceMs,
+                fallbackMs: 250,
+                onForce: () => {
+                    forceIssued = true;
+                    if (exited)
+                        finishFromExit();
+                },
+                onFallback: finishFromExit,
+            });
         };
         const abortRun = () => terminate("shutdown");
         const timeoutTimer = setTimeout(() => terminate("timeout"), timeoutMs);
         options.signal?.addEventListener("abort", abortRun, { once: true });
         if (options.signal?.aborted)
             abortRun();
-        child.once("error", (error) => finish({ error: error.message }));
+        child.once("error", (error) => {
+            if (!stopReason)
+                return finish({ error: error.message });
+            terminationError = error.message;
+            exited = true;
+            if (forceIssued)
+                finishFromExit();
+        });
         child.once("exit", (nextCode, nextSignal) => {
             exited = true;
             code = nextCode;
             exitSignal = nextSignal;
-            drainTimer = setTimeout(finishFromExit, 100);
+            if (stopReason)
+                finishFromExit();
+            else
+                drainTimer = setTimeout(finishFromExit, 100);
         });
         child.once("close", (nextCode, nextSignal) => {
             exited = true;

package/dist/gateway/matrix.js

@@ -7,8 +7,6 @@
 // LIMITATION (v1): NO end-to-end encryption. Encrypted rooms (m.room.encrypted events) are skipped — only
 // plaintext rooms work. E2EE would need libolm + a crypto store (see hermes' matrix-nio adapter), which breaks
 // the zero-dep constraint. Invite this bot into UNENCRYPTED rooms only.
-import { readFileSync } from "node:fs";
-import { basename } from "node:path";
 import { InboundMediaBudget, savePrivateResponse } from "./media.js";
 import { chunkText } from "./telegram.js";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -159,15 +157,15 @@ export function matrixAdapter(homeserver, token, selfUserId) {
                 }).catch(() => { });
             }
         },
-        async sendFile(chatId, filePath) {
-            const name = basename(filePath);
+        async sendFile(chatId, file) {
+            const name = file.safeName;
             const mime = mimeFromExt(name);
             try {
                 // 1) upload bytes → content_uri (mxc://)
                 const up = await fetch(`${base}/_matrix/media/v3/upload?filename=${encodeURIComponent(name)}`, {
                     method: "POST",
                     headers: { ...auth, "content-type": mime },
-                    body: readFileSync(filePath),
+                    body: new Uint8Array(file.bytes),
                 });
                 if (!up.ok)
                     return;

package/dist/gateway/mattermost.js

@@ -4,8 +4,6 @@
 // allow users via HARA_GATEWAY_ALLOWED (Mattermost user ids). Same ChatAdapter shape as Telegram/Discord, so all
 // the cross-platform gateway plumbing (send_file, in-chat system context, stuck-guard, image attach/describe)
 // works unchanged. Auth is a WS "authentication_challenge" rather than an HTTP header.
-import { readFileSync } from "node:fs";
-import { basename } from "node:path";
 import { InboundMediaBudget, savePrivateResponse } from "./media.js";
 import { chunkText } from "./telegram.js";
 const WSImpl = globalThis.WebSocket;
@@ -85,11 +83,11 @@ export function mattermostAdapter(serverUrl, token) {
                 }).catch(() => { });
             }
         },
-        async sendFile(chatId, filePath) {
+        async sendFile(chatId, file) {
             // upload the file (multipart) → get a file_id, then create a post referencing it
             const form = new FormData();
             form.append("channel_id", String(chatId));
-            form.append("files", new Blob([readFileSync(filePath)]), basename(filePath));
+            form.append("files", new Blob([new Uint8Array(file.bytes)]), file.safeName);
             const up = await fetch(`${api}/files`, { method: "POST", headers: auth, body: form }).catch(() => null);
             if (!up || !up.ok)
                 return;

package/dist/gateway/outbound-files.js

@@ -0,0 +1,379 @@
+// Immutable, owner-only snapshots for files leaving the machine through a gateway adapter. `send_file`
+// runs in a child process and the adapter sends later in the daemon; queueing an original pathname would
+// leave a TOCTOU window where that pathname could be exchanged for a symlink or a different file.
+import { randomUUID } from "node:crypto";
+import { chmodSync, constants, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, rmdirSync, unlinkSync, } from "node:fs";
+import { open } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { openVerifiedRegularFileNoFollow, verifyOpenedRegularFileSync } from "../fs-read.js";
+export const OUTBOUND_FILE_MAX_BYTES = 20 * 1024 * 1024;
+export const OUTBOUND_BATCH_MAX_BYTES = 20 * 1024 * 1024;
+export const OUTBOUND_BATCH_MAX_FILES = 4;
+const OUTBOX_MAX_BYTES = 256 * 1024;
+const UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+const OWNED_SNAPSHOT = new RegExp(`^(?:\\.${UUID}\\.part|[a-z0-9][a-z0-9_-]{0,48}-${UUID}(?:\\.[a-z0-9]{1,12})?)$`, "i");
+const SNAPSHOT_SUFFIX = new RegExp(`-${UUID}(?=\\.|$)`, "i");
+// Cleanup receives only the cleanup-only path from serve.ts. Remember the identity that produced its payload so
+// a later path replacement is never mistaken for the consumed snapshot.
+const consumedSnapshotIdentities = new Map();
+const outboundQueueLocks = new Map();
+export function outboundSnapshotDir(outbox) {
+    return `${resolve(outbox)}.files`;
+}
+function ownedByProcess(path) {
+    if (typeof process.getuid !== "function")
+        return true;
+    return lstatSync(path).uid === process.getuid();
+}
+function ensureSnapshotDir(outbox) {
+    const dir = outboundSnapshotDir(outbox);
+    try {
+        mkdirSync(dir, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error?.code !== "EEXIST")
+            throw error;
+    }
+    const info = lstatSync(dir);
+    if (!info.isDirectory() || info.isSymbolicLink() || !ownedByProcess(dir)) {
+        throw new Error(`unsafe gateway snapshot directory: ${dir}`);
+    }
+    chmodSync(dir, 0o700);
+    return dir;
+}
+function safeExtension(source) {
+    const extension = extname(basename(source)).toLowerCase();
+    return /^\.[a-z0-9]{1,12}$/.test(extension) ? extension : "";
+}
+function safeStem(source) {
+    const extension = extname(basename(source));
+    const raw = basename(source, extension)
+        .normalize("NFKD")
+        .replace(/[^a-z0-9_-]+/gi, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    return raw || "attachment";
+}
+function existingBatchUsage(dir) {
+    let bytes = 0;
+    let files = 0;
+    for (const name of readdirSync(dir)) {
+        if (!OWNED_SNAPSHOT.test(name))
+            continue;
+        const path = join(dir, name);
+        const info = lstatSync(path);
+        if (!info.isFile() || info.isSymbolicLink() || info.nlink > 1 || !ownedByProcess(path)) {
+            throw new Error(`unsafe gateway snapshot entry: ${path}`);
+        }
+        files++;
+        bytes += info.size;
+        if (!Number.isSafeInteger(bytes))
+            throw new Error("gateway send batch size is invalid");
+    }
+    return { bytes, files };
+}
+async function appendOutbox(outbox, snapshot) {
+    const path = resolve(outbox);
+    let before;
+    try {
+        before = lstatSync(path);
+        if (!before.isFile() || before.isSymbolicLink() || before.nlink > 1 || !ownedByProcess(path)) {
+            throw new Error(`unsafe gateway outbox: ${outbox}`);
+        }
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+    const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+    const handle = await open(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | noFollow, 0o600);
+    try {
+        const info = await handle.stat();
+        const current = lstatSync(path);
+        if (!info.isFile()
+            || info.nlink > 1
+            || current.isSymbolicLink()
+            || current.dev !== info.dev
+            || current.ino !== info.ino
+            || (before && (before.dev !== info.dev || before.ino !== info.ino))
+            || !ownedByProcess(path))
+            throw new Error(`unsafe gateway outbox: ${outbox}`);
+        await handle.chmod(0o600);
+        await handle.writeFile(snapshot + "\n", "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+/** Copy a verified source fd to a private immutable snapshot, then append only that snapshot to the queue. */
+async function queueOutboundSnapshotLocked(sourcePath, outbox) {
+    const source = resolve(sourcePath);
+    const verified = await openVerifiedRegularFileNoFollow(source, {
+        action: "send",
+        rejectHardLinks: true,
+        protectSensitive: true,
+    });
+    let destination;
+    let temporary;
+    let snapshot;
+    let published = false;
+    try {
+        if (verified.info.size > OUTBOUND_FILE_MAX_BYTES) {
+            throw new Error(`file exceeds the ${OUTBOUND_FILE_MAX_BYTES}-byte gateway send limit`);
+        }
+        const dir = ensureSnapshotDir(outbox);
+        const usage = existingBatchUsage(dir);
+        if (usage.files >= OUTBOUND_BATCH_MAX_FILES) {
+            throw new Error(`gateway send batch exceeds the ${OUTBOUND_BATCH_MAX_FILES}-file limit`);
+        }
+        if (verified.info.size > OUTBOUND_BATCH_MAX_BYTES - usage.bytes) {
+            throw new Error(`gateway send batch exceeds the ${OUTBOUND_BATCH_MAX_BYTES}-byte limit`);
+        }
+        const id = randomUUID();
+        temporary = join(dir, `.${id}.part`);
+        // Keep a recognizable, sanitized stem for a friendlier attachment name while the UUID preserves uniqueness.
+        snapshot = join(dir, `${safeStem(source)}-${id}${safeExtension(source)}`);
+        destination = await open(temporary, "wx", 0o600);
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let position = 0;
+        while (position < verified.info.size) {
+            const want = Math.min(buffer.length, verified.info.size - position);
+            const { bytesRead } = await verified.handle.read(buffer, 0, want, position);
+            if (bytesRead <= 0)
+                throw new Error(`source changed while snapshotting ${source}`);
+            let written = 0;
+            while (written < bytesRead) {
+                const result = await destination.write(buffer, written, bytesRead - written, position + written);
+                if (result.bytesWritten <= 0)
+                    throw new Error("failed to write gateway snapshot");
+                written += result.bytesWritten;
+            }
+            position += bytesRead;
+        }
+        const latest = await verified.handle.stat();
+        verifyOpenedRegularFileSync(source, latest, {
+            action: "send",
+            rejectHardLinks: true,
+            protectSensitive: true,
+        });
+        if (latest.dev !== verified.info.dev
+            || latest.ino !== verified.info.ino
+            || latest.size !== verified.info.size
+            || latest.mtimeMs !== verified.info.mtimeMs
+            || latest.ctimeMs !== verified.info.ctimeMs)
+            throw new Error(`source changed while snapshotting ${source}`);
+        await destination.sync();
+        await destination.chmod(0o600);
+        await destination.close();
+        destination = undefined;
+        renameSync(temporary, snapshot);
+        published = true;
+        await appendOutbox(outbox, snapshot);
+        return snapshot;
+    }
+    catch (error) {
+        if (published && snapshot) {
+            try {
+                unlinkSync(snapshot);
+            }
+            catch { /* best-effort cleanup */ }
+        }
+        if (temporary) {
+            try {
+                unlinkSync(temporary);
+            }
+            catch { /* best-effort cleanup */ }
+        }
+        throw error;
+    }
+    finally {
+        await destination?.close().catch(() => { });
+        await verified.handle.close().catch(() => { });
+    }
+}
+/** Serialize admissions for one outbox so parallel send_file calls cannot race past the aggregate budget. */
+export async function queueOutboundSnapshot(sourcePath, outbox) {
+    const key = resolve(outbox);
+    const previous = outboundQueueLocks.get(key) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolveGate) => { release = resolveGate; });
+    const current = previous.then(() => gate, () => gate);
+    outboundQueueLocks.set(key, current);
+    await previous.catch(() => { });
+    try {
+        return await queueOutboundSnapshotLocked(sourcePath, outbox);
+    }
+    finally {
+        release();
+        if (outboundQueueLocks.get(key) === current)
+            outboundQueueLocks.delete(key);
+    }
+}
+async function readOutbox(outbox) {
+    let verified;
+    try {
+        verified = await openVerifiedRegularFileNoFollow(resolve(outbox), {
+            action: "read gateway outbox",
+            rejectHardLinks: true,
+            protectSensitive: false,
+        });
+        if (verified.info.size > OUTBOX_MAX_BYTES)
+            throw new Error("gateway outbox is too large");
+        const bytes = Buffer.alloc(verified.info.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const { bytesRead } = await verified.handle.read(bytes, offset, bytes.length - offset, offset);
+            if (!bytesRead)
+                break;
+            offset += bytesRead;
+        }
+        return bytes.subarray(0, offset).toString("utf8").split("\n").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        await verified?.handle.close().catch(() => { });
+        try {
+            const current = lstatSync(resolve(outbox));
+            if (verified && !current.isSymbolicLink() && current.dev === verified.info.dev && current.ino === verified.info.ino) {
+                unlinkSync(resolve(outbox));
+            }
+        }
+        catch { /* missing or replaced outbox is left alone */ }
+    }
+}
+function attachmentName(snapshotPath) {
+    return basename(snapshotPath).replace(SNAPSHOT_SUFFIX, "") || "attachment";
+}
+/**
+ * Drain an outbox and materialize only verified snapshots owned by this queue. The returned bytes are the
+ * security boundary: adapters never reopen `snapshotPath`, so replacing it after this function returns cannot
+ * alter or disclose what is uploaded. Per-file, batch-byte, and file-count caps bound the in-memory payload.
+ */
+export async function consumeOutboundSnapshots(outbox) {
+    const dir = outboundSnapshotDir(outbox);
+    const queued = await readOutbox(outbox); // always drain/unlink the outbox, even if its snapshot dir is absent
+    let dirReal;
+    try {
+        const info = lstatSync(dir);
+        if (!info.isDirectory() || info.isSymbolicLink() || !ownedByProcess(dir))
+            return [];
+        dirReal = realpathSync.native(dir);
+    }
+    catch {
+        return [];
+    }
+    const accepted = [];
+    let acceptedBytes = 0;
+    for (const raw of queued) {
+        if (accepted.length >= OUTBOUND_BATCH_MAX_FILES || acceptedBytes >= OUTBOUND_BATCH_MAX_BYTES)
+            break;
+        const candidate = resolve(raw);
+        if (dirname(candidate) !== dir || !OWNED_SNAPSHOT.test(basename(candidate)))
+            continue;
+        let verified;
+        try {
+            verified = await openVerifiedRegularFileNoFollow(candidate, {
+                action: "send gateway snapshot",
+                rejectHardLinks: true,
+                protectSensitive: false,
+            });
+            if (dirname(verified.canonicalPath) !== dirReal
+                || verified.info.size > OUTBOUND_FILE_MAX_BYTES
+                || verified.info.size > OUTBOUND_BATCH_MAX_BYTES - acceptedBytes
+                || !ownedByProcess(candidate))
+                continue;
+            const bytes = Buffer.allocUnsafe(verified.info.size);
+            let offset = 0;
+            while (offset < bytes.length) {
+                const { bytesRead } = await verified.handle.read(bytes, offset, bytes.length - offset, offset);
+                if (!bytesRead)
+                    break;
+                offset += bytesRead;
+            }
+            if (offset !== bytes.length)
+                continue;
+            const latest = await verified.handle.stat();
+            verifyOpenedRegularFileSync(candidate, latest, {
+                action: "send gateway snapshot",
+                rejectHardLinks: true,
+                protectSensitive: false,
+            });
+            if (latest.dev !== verified.info.dev
+                || latest.ino !== verified.info.ino
+                || latest.size !== verified.info.size
+                || latest.mtimeMs !== verified.info.mtimeMs
+                || latest.ctimeMs !== verified.info.ctimeMs)
+                continue;
+            consumedSnapshotIdentities.set(candidate, { dev: latest.dev, ino: latest.ino });
+            accepted.push({ snapshotPath: candidate, safeName: attachmentName(candidate), bytes });
+            acceptedBytes += bytes.length;
+        }
+        catch {
+            /* malformed/replaced queue entry is never delivered */
+        }
+        finally {
+            await verified?.handle.close().catch(() => { });
+        }
+    }
+    return accepted;
+}
+/** Remove only files in this queue's private snapshot directory, never arbitrary outbox entries. */
+export function cleanupOutboundSnapshots(outbox, preserve = []) {
+    const dir = outboundSnapshotDir(outbox);
+    const keep = new Set(preserve.map((path) => resolve(path)));
+    try {
+        const info = lstatSync(dir);
+        if (!info.isDirectory() || info.isSymbolicLink() || !ownedByProcess(dir))
+            return;
+        for (const name of readdirSync(dir)) {
+            if (!OWNED_SNAPSHOT.test(name))
+                continue;
+            const path = join(dir, name);
+            if (keep.has(resolve(path)))
+                continue;
+            try {
+                const entry = lstatSync(path);
+                if ((entry.isFile() || entry.isSymbolicLink()) && ownedByProcess(path))
+                    unlinkSync(path);
+            }
+            catch {
+                /* raced cleanup is harmless */
+            }
+        }
+        rmdirSync(dir);
+    }
+    catch {
+        /* best-effort cleanup */
+    }
+}
+/** Delete one previously verified delivered snapshot and remove its now-empty queue directory. */
+export function cleanupOutboundSnapshot(path) {
+    const candidate = resolve(path);
+    const expected = consumedSnapshotIdentities.get(candidate);
+    consumedSnapshotIdentities.delete(candidate);
+    const dir = dirname(candidate);
+    if (!dir.endsWith(".files") || !OWNED_SNAPSHOT.test(basename(candidate)))
+        return;
+    try {
+        const parent = lstatSync(dir);
+        if (!parent.isDirectory() || parent.isSymbolicLink() || !ownedByProcess(dir))
+            return;
+        const entry = lstatSync(candidate);
+        if (expected
+            && entry.isFile()
+            && !entry.isSymbolicLink()
+            && entry.nlink === 1
+            && entry.dev === expected.dev
+            && entry.ino === expected.ino
+            && ownedByProcess(candidate))
+            unlinkSync(candidate);
+        if (readdirSync(dir).length === 0)
+            rmdirSync(dir);
+    }
+    catch {
+        /* already removed or raced cleanup */
+    }
+}