@openclaw/signal 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/native-staged-symlink.js

@@ -0,0 +1,303 @@
+import fs, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { captureNativeFdClose } from "./native-binding.js";
+import { requireNativeBinding } from "./native.js";
+import { classifyNativeRenameFailure } from "./native-rename-outcome.js";
+import { assertStagedDirectoryCurrent, openStagedDirectory } from "./staged-directory.js";
+import { createStagedFileReceipt } from "./staged-file-settlement.js";
+const NOT_PUBLISHED = Object.freeze({ status: "not-published" });
+function basename(name) {
+    if (typeof name !== "string" || !name || name === "." || name === ".." ||
+        /[/\\:\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(name)) {
+        throw new FsSafeError("invalid-path", "staged symlinks require a direct-child basename");
+    }
+}
+function failure(error, details) {
+    let code = "helper-failed";
+    try {
+        code = error instanceof FsSafeError ? error.code
+            : error?.code === "EEXIST" ? "already-exists" : "helper-failed";
+    }
+    catch {
+        // Uninspectable error metadata must not interrupt terminal settlement.
+    }
+    return new FsSafeError(code, `staged symlink ${details.phase} failed`, { cause: error, details });
+}
+function assertAuthority(assertion) {
+    assertSynchronousCallbackResult(assertion(), "assertBeforeMutation");
+}
+function expectedIdentity(stat, expected) {
+    return stat.isSymbolicLink() && stat.nlink === 1n &&
+        stat.dev === expected.dev && stat.ino === expected.ino &&
+        stat.uid === BigInt(expected.uid) && stat.gid === BigInt(expected.gid) &&
+        stat.ctimeNs === expected.ctimeNs;
+}
+class NativeStagedSymlink {
+    #publication = NOT_PUBLISHED;
+    #closed;
+    #removal;
+    #busy = false;
+    #receipt;
+    #binding;
+    #parentFd;
+    #linkFd;
+    #closeLink;
+    #assertion;
+    constructor(receipt, binding, parentFd, linkFd, closeLink, assertion) {
+        this.#receipt = receipt;
+        this.#binding = binding;
+        this.#parentFd = parentFd;
+        this.#linkFd = linkFd;
+        this.#closeLink = closeLink;
+        this.#assertion = assertion;
+    }
+    get receipt() { return this.#receipt; }
+    #idle() {
+        if (this.#busy)
+            throw new FsSafeError("helper-failed", "reentrant symlink operation");
+    }
+    #open() {
+        if (this.#closed)
+            throw new FsSafeError("helper-failed", "staged symlink is closed");
+    }
+    #matches(name) {
+        if (!this.#binding.stagedSymlinkMatches(this.#parentFd, name, this.#linkFd))
+            return false;
+        const stat = fs.fstatSync(this.#linkFd, { bigint: true });
+        const identity = this.#receipt.identity;
+        // ctime changes on rename; identity, ownership, mode and target do not.
+        return stat.dev === identity.dev && stat.ino === identity.ino &&
+            stat.uid === BigInt(identity.uid) && stat.gid === BigInt(identity.gid) &&
+            Number(stat.mode & 4095n) === identity.mode && stat.nlink === 1n &&
+            this.#binding.stagedSymlinkTarget(this.#parentFd, name, this.#linkFd) === this.#receipt.target;
+    }
+    #assertNamed(name) {
+        if (!this.#matches(name))
+            throw new FsSafeError("path-mismatch", "symlink no longer names the retained object");
+    }
+    #assertCurrent() {
+        this.#open();
+        if (this.#publication.status !== "not-published") {
+            throw new FsSafeError("helper-failed", "symlink publication has already been attempted");
+        }
+        assertStagedDirectoryCurrent(this.#receipt.directory);
+        this.#assertNamed(this.#receipt.temporaryBasename);
+    }
+    async assertCurrent() { this.#idle(); this.#assertCurrent(); }
+    async publish(name) {
+        this.#idle();
+        this.#busy = true;
+        try {
+            basename(name);
+            if (name === this.#receipt.temporaryBasename) {
+                throw new FsSafeError("invalid-path", "publication requires a distinct basename");
+            }
+            this.#assertCurrent();
+            assertAuthority(this.#assertion);
+            // A synchronous caller assertion can itself change either pathname.
+            this.#assertCurrent();
+            try {
+                this.#binding.publishStagedSymlink(this.#parentFd, this.#receipt.temporaryBasename, this.#linkFd, name);
+            }
+            catch (error) {
+                let outcome = "indeterminate";
+                try {
+                    outcome = classifyNativeRenameFailure(error);
+                }
+                catch {
+                    // Unreadable diagnostics cannot prove that the rename was uncommitted.
+                }
+                if (outcome === "indeterminate") {
+                    this.#publication = Object.freeze({ status: "indeterminate", basename: name, overwrite: false });
+                }
+                throw error;
+            }
+            const published = Object.freeze({
+                status: "published", staged: this.#receipt, basename: name, overwrite: false,
+            });
+            // Record dispatch success before any fallible post-observation.
+            this.#publication = published;
+            this.#assertNamed(name);
+            assertStagedDirectoryCurrent(this.#receipt.directory);
+            return published;
+        }
+        catch (error) {
+            throw failure(error, { phase: "publish", publication: this.#publication });
+        }
+        finally {
+            this.#busy = false;
+        }
+    }
+    #publishedName() {
+        this.#open();
+        if (this.#publication.status !== "published" || this.#removal) {
+            throw new FsSafeError("helper-failed", "no unsettled published symlink");
+        }
+        return this.#publication.basename;
+    }
+    async assertPublished() {
+        this.#idle();
+        const name = this.#publishedName();
+        assertStagedDirectoryCurrent(this.#receipt.directory);
+        this.#assertNamed(name);
+    }
+    #remove(name) {
+        try {
+            if (!this.#matches(name))
+                return "preserved";
+        }
+        catch (error) {
+            let missing = false;
+            try {
+                missing = error?.code === "ENOENT";
+            }
+            catch {
+                // Even a failed errno inspection must retain the original cause.
+            }
+            if (missing)
+                return "name-absent";
+            throw error;
+        }
+        assertAuthority(this.#assertion);
+        // Recheck after application code and immediately before guarded native unlink.
+        if (!this.#matches(name))
+            return "preserved";
+        return this.#binding.removeStagedSymlink(this.#parentFd, name, this.#linkFd);
+    }
+    async removePublished() {
+        this.#idle();
+        this.#open();
+        if (this.#removal) {
+            if (this.#removal.error)
+                throw this.#removal.error;
+            return this.#removal.receipt;
+        }
+        const name = this.#publishedName();
+        this.#busy = true;
+        try {
+            const receipt = this.#remove(name);
+            this.#removal = { receipt };
+            return receipt;
+        }
+        catch (error) {
+            const wrapped = failure(error, { phase: "remove-published", publication: this.#publication });
+            // A failed unlink is not safe to retry automatically.
+            this.#removal = { error: wrapped };
+            throw wrapped;
+        }
+        finally {
+            this.#busy = false;
+        }
+    }
+    async cleanup() {
+        this.#idle();
+        if (this.#closed) {
+            if (this.#closed.error)
+                throw this.#closed.error;
+            return this.#closed.receipt;
+        }
+        this.#busy = true;
+        let status = "not-needed";
+        const errors = [];
+        if (this.#publication.status === "indeterminate")
+            status = "preserved";
+        else if (this.#publication.status === "not-published") {
+            try {
+                status = this.#remove(this.#receipt.temporaryBasename);
+            }
+            catch (error) {
+                status = "failed";
+                errors.push(error);
+            }
+        }
+        let resources = "closed";
+        for (const close of [() => this.#closeLink(this.#linkFd), () => fs.closeSync(this.#parentFd)]) {
+            try {
+                close();
+            }
+            catch (error) {
+                resources = "close-failed";
+                errors.push(error);
+            }
+        }
+        const receipt = Object.freeze({
+            temporaryBasename: this.#receipt.temporaryBasename,
+            publication: this.#publication, status, resources,
+        });
+        const error = errors.length ? failure(errors.length === 1 ? errors[0] : new AggregateError(errors, "symlink settlement failed"), { phase: "cleanup", publication: this.#publication, cleanup: receipt }) : undefined;
+        this.#closed = { receipt, error };
+        this.#busy = false;
+        if (error)
+            throw error;
+        return receipt;
+    }
+    async [Symbol.asyncDispose]() {
+        const cleanup = await this.cleanup();
+        if (cleanup.status === "preserved") {
+            throw new FsSafeError("not-removable", "symlink settlement preserved an unverified entry", {
+                details: { phase: "cleanup", publication: this.#publication, cleanup },
+            });
+        }
+    }
+}
+/**
+ * Admit an existing staged symlink against caller-captured identity and retain
+ * its no-follow descriptor. Admission never creates, adopts by target, or unlinks.
+ */
+export async function retainSymlinkInDirectory(options) {
+    if (process.platform !== "linux" && process.platform !== "darwin") {
+        throw new FsSafeError("unsupported-platform", "retained symlinks require Linux or macOS");
+    }
+    const native = requireNativeBinding();
+    if ([
+        native.closeOwnedFd, native.openStagedSymlink, native.stagedSymlinkTarget,
+        native.stagedSymlinkMatches, native.publishStagedSymlink, native.removeStagedSymlink,
+    ].some((fn) => typeof fn !== "function")) {
+        throw new FsSafeError("helper-unavailable", "native retained symlink support is unavailable");
+    }
+    const binding = native;
+    const name = options.basename;
+    basename(name);
+    const expected = Object.freeze({ ...options.expected });
+    const assertion = options.assertBeforeMutation;
+    if (typeof assertion !== "function" || typeof expected.dev !== "bigint" ||
+        typeof expected.ino !== "bigint" || typeof expected.ctimeNs !== "bigint" ||
+        !Number.isSafeInteger(expected.uid) || expected.uid < 0 ||
+        !Number.isSafeInteger(expected.gid) || expected.gid < 0 ||
+        typeof expected.target !== "string" || !expected.target || expected.target.includes("\0")) {
+        throw new FsSafeError("invalid-path", "exact symlink identity, target and synchronous authority are required");
+    }
+    const closeLink = captureNativeFdClose(binding);
+    const parent = openStagedDirectory(options.directory);
+    let fd;
+    try {
+        fd = binding.openStagedSymlink(parent.fd, name);
+        const stat = fs.fstatSync(fd, { bigint: true });
+        if (!expectedIdentity(stat, expected) ||
+            binding.stagedSymlinkTarget(parent.fd, name, fd) !== expected.target) {
+            throw new FsSafeError("path-mismatch", "staged symlink does not match the supplied identity");
+        }
+        const receipt = Object.freeze({
+            ...createStagedFileReceipt(parent.receipt, name, stat), target: expected.target,
+        });
+        assertAuthority(assertion);
+        const owner = new NativeStagedSymlink(receipt, binding, parent.fd, fd, closeLink, assertion);
+        await owner.assertCurrent();
+        return owner;
+    }
+    catch (error) {
+        const errors = [error];
+        for (const close of [() => { if (fd !== undefined)
+                closeLink(fd); }, () => fs.closeSync(parent.fd)]) {
+            try {
+                close();
+            }
+            catch (closeError) {
+                errors.push(closeError);
+            }
+        }
+        // Until admission succeeds, the caller retains every namespace cleanup duty.
+        throw failure(errors.length === 1 ? error : new AggregateError(errors, "symlink admission and close failed"), { phase: "prepare", publication: NOT_PUBLISHED });
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/native.d.ts

@@ -0,0 +1,13 @@
+import { type NativeBinding } from "./native-binding.js";
+export type { NativeBinding } from "./native-binding.js";
+export declare function __loadBundledNativeForTest(): NativeBinding;
+export declare function __nativeLoaderDetectorsForTest(): {
+    report: boolean | undefined;
+    filesystem: boolean | undefined;
+    elfInterpreter: boolean | undefined;
+};
+export declare function __nativeTargetForTest(platform: NodeJS.Platform, arch: string, musl?: boolean): string | undefined;
+export declare function getNativeBinding(): NativeBinding | undefined;
+export declare function requireNativeBinding(): NativeBinding;
+export declare function __setNativeLoaderForTest(loader: () => NativeBinding): void;
+export declare function __resetNativeLoaderForTest(): void;

package/node_modules/@openclaw/fs-safe/dist/native.js

@@ -0,0 +1,209 @@
+import { closeSync, openSync, readSync, readdirSync, } from "node:fs";
+import { createRequire } from "node:module";
+import { FsSafeError } from "./errors.js";
+import { captureNativeFdClose } from "./native-binding.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+const require = createRequire(import.meta.url);
+let binding;
+let loadError;
+let attempted = false;
+let loadBinding = loadBundledBinding;
+function isMuslFilename(file) {
+    return file.includes("libc.musl-") || file.includes("ld-musl-");
+}
+function isMuslFromReport() {
+    try {
+        if (!process.report || typeof process.report.getReport !== "function")
+            return undefined;
+        const report = process.report.getReport();
+        if (report.header?.glibcVersionRuntime)
+            return false;
+        if (report.sharedObjects?.some(isMuslFilename))
+            return true;
+    }
+    catch {
+        // Continue with ELF and filesystem inspection.
+    }
+    return undefined;
+}
+function isMuslFromFilesystem() {
+    for (const directory of ["/lib", "/usr/lib"]) {
+        try {
+            if (readdirSync(directory).some(isMuslFilename))
+                return true;
+        }
+        catch {
+            // A missing or unreadable conventional library directory is inconclusive.
+        }
+    }
+    return undefined;
+}
+function readUInt(buffer, offset, bytes, littleEndian) {
+    if (offset < 0 || offset + bytes > buffer.length)
+        return undefined;
+    if (bytes === 2)
+        return littleEndian ? buffer.readUInt16LE(offset) : buffer.readUInt16BE(offset);
+    if (bytes === 4)
+        return littleEndian ? buffer.readUInt32LE(offset) : buffer.readUInt32BE(offset);
+    const value = littleEndian ? buffer.readBigUInt64LE(offset) : buffer.readBigUInt64BE(offset);
+    return value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : undefined;
+}
+function isMuslFromElfInterpreter() {
+    let fd;
+    try {
+        fd = openSync(process.execPath, "r");
+        const header = Buffer.alloc(64);
+        if (readSync(fd, header, 0, header.length, 0) < 52)
+            return undefined;
+        if (!header.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
+            return undefined;
+        const elfClass = header[4];
+        const dataEncoding = header[5];
+        if ((elfClass !== 1 && elfClass !== 2) || (dataEncoding !== 1 && dataEncoding !== 2)) {
+            return undefined;
+        }
+        const littleEndian = dataEncoding === 1;
+        const is64Bit = elfClass === 2;
+        const tableOffset = readUInt(header, is64Bit ? 32 : 28, is64Bit ? 8 : 4, littleEndian);
+        const entrySize = readUInt(header, is64Bit ? 54 : 42, 2, littleEndian);
+        const entryCount = readUInt(header, is64Bit ? 56 : 44, 2, littleEndian);
+        if (tableOffset === undefined ||
+            entrySize === undefined ||
+            entryCount === undefined ||
+            entrySize < (is64Bit ? 56 : 32) ||
+            entryCount > 1024) {
+            return undefined;
+        }
+        const programHeader = Buffer.alloc(entrySize);
+        for (let index = 0; index < entryCount; index += 1) {
+            const offset = tableOffset + index * entrySize;
+            if (readSync(fd, programHeader, 0, entrySize, offset) !== entrySize)
+                return undefined;
+            if (readUInt(programHeader, 0, 4, littleEndian) !== 3)
+                continue;
+            const interpreterOffset = readUInt(programHeader, is64Bit ? 8 : 4, is64Bit ? 8 : 4, littleEndian);
+            const interpreterSize = readUInt(programHeader, is64Bit ? 32 : 16, is64Bit ? 8 : 4, littleEndian);
+            if (interpreterOffset === undefined ||
+                interpreterSize === undefined ||
+                interpreterSize < 1 ||
+                interpreterSize > 4096) {
+                return undefined;
+            }
+            const interpreter = Buffer.alloc(interpreterSize);
+            if (readSync(fd, interpreter, 0, interpreterSize, interpreterOffset) !== interpreterSize) {
+                return undefined;
+            }
+            return isMuslFilename(interpreter.toString("utf8"));
+        }
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Best-effort detection must never turn close failure into import failure.
+            }
+        }
+    }
+    return undefined;
+}
+function isMusl() {
+    if (process.platform !== "linux")
+        return false;
+    for (const detector of [isMuslFromReport, isMuslFromElfInterpreter, isMuslFromFilesystem]) {
+        const result = detector();
+        if (result !== undefined)
+            return result;
+    }
+    // Unknown Linux libc: try the glibc binary and let its require fail normally.
+    return false;
+}
+function targetFor(platform, arch, musl) {
+    if (platform === "win32" && arch === "x64")
+        return "win32-x64-msvc";
+    if (platform === "darwin" && arch === "x64")
+        return "darwin-x64";
+    if (platform === "darwin" && arch === "arm64")
+        return "darwin-arm64";
+    if (platform === "linux" && (arch === "x64" || arch === "arm64")) {
+        return `linux-${arch}-${musl ? "musl" : "gnu"}`;
+    }
+    return undefined;
+}
+function bundledTarget() {
+    return targetFor(process.platform, process.arch, isMusl());
+}
+function nativePackageForTarget(target) {
+    return `@openclaw/fs-safe-${target}`;
+}
+function loadBundledBinding() {
+    const target = bundledTarget();
+    if (!target) {
+        throw new Error(`Unsupported OS or architecture: ${process.platform}-${process.arch}`);
+    }
+    const loaded = require(nativePackageForTarget(target));
+    captureNativeFdClose(loaded);
+    return loaded;
+}
+export function __loadBundledNativeForTest() {
+    return loadBundledBinding();
+}
+export function __nativeLoaderDetectorsForTest() {
+    return {
+        report: isMuslFromReport(),
+        filesystem: isMuslFromFilesystem(),
+        elfInterpreter: isMuslFromElfInterpreter(),
+    };
+}
+export function __nativeTargetForTest(platform, arch, musl = false) {
+    return targetFor(platform, arch, musl);
+}
+export function getNativeBinding() {
+    const { mode } = getFsSafeNativeConfig();
+    if (mode === "off")
+        return undefined;
+    if (!attempted) {
+        attempted = true;
+        try {
+            const loaded = loadBinding();
+            captureNativeFdClose(loaded);
+            binding = loaded;
+        }
+        catch (error) {
+            loadError = error;
+        }
+    }
+    if (binding)
+        return binding;
+    if (mode === "require") {
+        throw new FsSafeError("helper-unavailable", "native fs-safe helper is unavailable", {
+            cause: loadError,
+        });
+    }
+    return undefined;
+}
+export function requireNativeBinding() {
+    const native = getNativeBinding();
+    if (!native) {
+        throw new FsSafeError("helper-unavailable", "native fs-safe helper is unavailable", {
+            cause: loadError,
+        });
+    }
+    return native;
+}
+export function __setNativeLoaderForTest(loader) {
+    binding = undefined;
+    loadError = undefined;
+    attempted = false;
+    loadBinding = loader;
+}
+export function __resetNativeLoaderForTest() {
+    binding = undefined;
+    loadError = undefined;
+    attempted = false;
+    loadBinding = loadBundledBinding;
+}

package/node_modules/@openclaw/fs-safe/dist/opened-file-failure.d.ts

@@ -0,0 +1,7 @@
+import { type BigIntStats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+export declare function recordFileOpenFailure(error: unknown, filePath: string): never;
+export declare function recordExclusiveCreateFailure(error: unknown, filePath: string): never;
+export declare function openedPathResolutionError(error?: Error): Error;
+export declare function recordPreOpenFileChange(error: unknown, handle: FileHandle, filePath: string, before: BigIntStats | undefined, opened: BigIntStats | undefined): Promise<void>;
+export declare function recordOpenedFileFailure(error: unknown, handle: FileHandle, filePath: string, identity: BigIntStats): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/opened-file-failure.js

@@ -0,0 +1,46 @@
+import fsSync, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { isFileObservationFailure, recordFileObservationFailure } from "./file-observation.js";
+export function recordFileOpenFailure(error, filePath) {
+    recordFileObservationFailure(error, `open:${filePath}`);
+    throw error;
+}
+export function recordExclusiveCreateFailure(error, filePath) {
+    recordFileObservationFailure(error, `exclusive-create:${filePath}`);
+    throw error;
+}
+export function openedPathResolutionError(error = new FsSafeError("path-mismatch", "unable to resolve opened file path")) {
+    recordFileObservationFailure(error, "resolution");
+    return error;
+}
+export async function recordPreOpenFileChange(error, handle, filePath, before, opened) {
+    if (!isFileObservationFailure(error, "identity") || !before?.isFile() || !opened?.isFile() ||
+        ![0n, 1n].includes(before.nlink) || ![0n, 1n].includes(opened.nlink))
+        return;
+    try {
+        await inspectFileIdentity(async () => before);
+        const current = await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), opened);
+        if (current.isFile() && [0n, 1n].includes(current.nlink) &&
+            (before.dev !== current.dev || before.ino !== current.ino)) {
+            // A stale pathname sample is not proof that its former inode was unlinked.
+            recordFileObservationFailure(error, `changed:${filePath}`);
+        }
+    }
+    catch {
+        // Unknown, changed, or closed descriptor evidence never permits a discard.
+    }
+}
+export async function recordOpenedFileFailure(error, handle, filePath, identity) {
+    if ((!isFileObservationFailure(error, "resolution") && !isFileObservationFailure(error, "identity")) ||
+        !identity.isFile() || identity.nlink > 1n)
+        return;
+    try {
+        const current = await inspectFileIdentity(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity);
+        if (current.isFile() && current.nlink === 0n)
+            recordFileObservationFailure(error, `unlinked:${filePath}`);
+    }
+    catch {
+        // A closed, changed, or unknown descriptor provides no retry evidence.
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/opened-realpath.d.ts

@@ -0,0 +1,15 @@
+import type { BigIntStats, Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import { type FileIdentityStat } from "./file-identity.js";
+export declare function resolveOpenedFileRealPathForHandle(handle: FileHandle, ioPath: string): Promise<string>;
+export declare function resolveOpenedFileRealPathForFd(fd: number, handleStat: {
+    dev: bigint;
+    ino: bigint;
+}, ioPath: string): Promise<{
+    realPath: string;
+    stat: BigIntStats;
+}>;
+export declare function resolveOpenedFileRealPathForFd(fd: number, handleStat: FileIdentityStat, ioPath: string): Promise<{
+    realPath: string;
+    stat: Stats | BigIntStats;
+}>;