@openclaw/matrix 2026.9.6 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock.js

@@ -0,0 +1,282 @@
+import fsSync from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { removeSidecarLockIfUnchanged, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
+import { acquireSidecarLock } from "./sidecar-lock-acquire.js";
+import { createHeldSidecarLockHandle, stopSidecarLockMonitoring } from "./sidecar-lock-handle.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { ensureSidecarLockCleanupRegistered } from "./sidecar-lock-registration.js";
+const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
+const GLOBAL_CLEANUP_KEY = Symbol.for("fsSafe.sidecarLockCleanupRegistered");
+const GLOBAL_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.sidecarLockCleanupHandler");
+const GLOBAL_CLEANUP_REGISTRATION_KEY = Symbol.for("fsSafe.sidecarLockCleanupRegistration");
+const GLOBAL_BEFORE_EXIT_KEY = Symbol.for("fsSafe.sidecarLockBeforeExitCleanup");
+const GLOBAL_BEFORE_EXIT_HANDLER_KEY = Symbol.for("fsSafe.sidecarLockBeforeExitCleanupHandler");
+const GLOBAL_BEFORE_EXIT_REGISTRATION_KEY = Symbol.for("fsSafe.sidecarLockBeforeExitCleanupRegistration");
+// Set by copies whose exit handlers honor retainOnExit. When an older package
+// copy registered the handlers first, this marker stays absent and retained
+// acquisitions must fail closed rather than silently lose the guarantee.
+const GLOBAL_RETAIN_AWARE_KEY = Symbol.for("fsSafe.sidecarLockRetainAwareCleanup");
+function getGlobalManagers() {
+    const globalWithState = globalThis;
+    if (!globalWithState[GLOBAL_STATE_KEY]) {
+        globalWithState[GLOBAL_STATE_KEY] = new Map();
+    }
+    return globalWithState[GLOBAL_STATE_KEY];
+}
+function resolveManagerState(key) {
+    const managers = getGlobalManagers();
+    let state = managers.get(key);
+    if (!state) {
+        state = {
+            cleanupRegistered: false,
+            held: new Map(),
+            admissions: new Map(),
+            reclaimCleanupRegistered: false,
+            reclaimGuards: new Set(),
+        };
+        managers.set(key, state);
+    }
+    else {
+        // The global manager symbol is shared across package copies and hot reloads.
+        // Backfill state created by fs-safe versions that predate admission tokens
+        // or reclaim guards without placing an incomplete value in the held map.
+        state.admissions ??= new Map();
+        state.reclaimCleanupRegistered ??= false;
+        state.reclaimGuards ??= new Set();
+    }
+    return state;
+}
+function snapshotMatchesSync(lockPath, observed) {
+    let fd;
+    try {
+        const beforeStat = fsSync.lstatSync(lockPath, { bigint: true });
+        if (!beforeStat.isFile()) {
+            return false;
+        }
+        const openFlags = fsSync.constants.O_RDONLY |
+            (process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
+                ? fsSync.constants.O_NOFOLLOW
+                : 0) |
+            (typeof fsSync.constants.O_NONBLOCK === "number" ? fsSync.constants.O_NONBLOCK : 0);
+        fd = fsSync.openSync(lockPath, openFlags);
+        const openedStat = fsSync.fstatSync(fd, { bigint: true });
+        // Token-owned files can have different descriptor/path identities on VirtioFS.
+        // Require a known descriptor identity without rejecting that supported drift.
+        if (!openedStat.isFile() || !sameFileIdentityForCleanup(openedStat, openedStat)) {
+            return false;
+        }
+        if (observed.raw !== undefined && openedStat.size !== BigInt(Buffer.byteLength(observed.raw))) {
+            return false;
+        }
+        const raw = fsSync.readFileSync(fd, "utf8");
+        const afterStat = fsSync.lstatSync(lockPath, { bigint: true });
+        if (!afterStat.isFile() || !sameFileIdentityForCleanup(beforeStat, afterStat)) {
+            return false;
+        }
+        return sidecarLockSnapshotMatches({ raw, payload: null, stat: afterStat }, observed);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fsSync.closeSync(fd);
+            }
+            catch {
+                // Best-effort process-exit cleanup.
+            }
+        }
+    }
+}
+function releaseAllReclaimGuardsSync(state) {
+    // Exit cleanup also visits managers created by older copies and never reopened here.
+    for (const reclaimGuardPath of state.reclaimGuards ?? []) {
+        try {
+            fsSync.rmdirSync(reclaimGuardPath);
+            state.reclaimGuards.delete(reclaimGuardPath);
+        }
+        catch {
+            // Best-effort process-exit cleanup. A surviving guard fails closed.
+        }
+    }
+}
+function releaseAllLocksSync(state, options) {
+    for (const [normalizedTargetPath, held] of state.held) {
+        stopSidecarLockMonitoring(held);
+        void held.handle.close().catch(() => undefined);
+        try {
+            const retained = options?.preserveRetained === true && held.retainOnExit;
+            if (!retained && !held.lockRoot && snapshotMatchesSync(held.lockPath, held.snapshot)) {
+                fsSync.rmSync(held.lockPath, { force: true });
+            }
+        }
+        catch {
+            // Best-effort process-exit cleanup.
+        }
+        state.held.delete(normalizedTargetPath);
+    }
+    state.admissions?.clear();
+    releaseAllReclaimGuardsSync(state);
+}
+function ensureGlobalExitCleanupRegistered() {
+    const cleanup = () => {
+        for (const state of getGlobalManagers().values()) {
+            releaseAllLocksSync(state, { preserveRetained: true });
+        }
+    };
+    ensureSidecarLockCleanupRegistered({
+        event: "exit",
+        registered: GLOBAL_CLEANUP_KEY,
+        registering: GLOBAL_CLEANUP_REGISTRATION_KEY,
+        handler: GLOBAL_CLEANUP_HANDLER_KEY,
+        retainAware: GLOBAL_RETAIN_AWARE_KEY,
+        reentryError: () => new FsSafeError("helper-unavailable", "sidecar lock exit cleanup registration is already in progress"),
+    }, cleanup, true);
+}
+/** True when a retain-unaware package copy registered the process-exit handlers first. */
+export function exitCleanupCannotRetain() {
+    const globalWithCleanup = globalThis;
+    return globalWithCleanup[GLOBAL_CLEANUP_KEY] === true && globalWithCleanup[GLOBAL_RETAIN_AWARE_KEY] !== true;
+}
+function ensureGlobalBeforeExitCleanupRegistered() {
+    // Independent of the exit registration, which an older package copy may own.
+    const lifecycle = { armed: false };
+    const cleanup = () => {
+        if (!lifecycle.armed)
+            return;
+        // Cleanup itself schedules I/O; retry only after another acquisition.
+        lifecycle.armed = false;
+        for (const state of getGlobalManagers().values()) {
+            for (const [normalizedTargetPath, held] of Array.from(state.held.entries())) {
+                if (held.lockRoot && !held.retainOnExit) {
+                    void releaseHeldLock(state, normalizedTargetPath, held, { force: true }).catch(() => undefined);
+                }
+            }
+        }
+    };
+    return ensureSidecarLockCleanupRegistered({
+        event: "beforeExit",
+        registered: GLOBAL_BEFORE_EXIT_KEY,
+        registering: GLOBAL_BEFORE_EXIT_REGISTRATION_KEY,
+        handler: GLOBAL_BEFORE_EXIT_HANDLER_KEY,
+        reentryError: () => new FsSafeError("helper-unavailable", "sidecar lock before-exit cleanup registration is already in progress"),
+    }, cleanup, lifecycle);
+}
+async function releaseHeldLock(state, normalizedTargetPath, held, options = {}) {
+    const current = state.held.get(normalizedTargetPath);
+    if (current !== held) {
+        return false;
+    }
+    if (held.releasePromise) {
+        await held.releasePromise;
+        return true;
+    }
+    // Older package copies can add holders after this manager was constructed.
+    held.refCount ??= 1;
+    if (options.force) {
+        held.refCount = 0;
+    }
+    else if (!options.retry && held.refCount > 0) {
+        held.refCount -= 1;
+    }
+    if (held.refCount > 0) {
+        return false;
+    }
+    held.releasePromise = (async () => {
+        await held.handle.close().catch(() => undefined);
+        await removeSidecarLockIfUnchanged(held.lockPath, held.snapshot, {
+            lockRoot: held.lockRoot,
+            parsePayload: held.parsePayload,
+        });
+        if (state.held.get(normalizedTargetPath) === held) {
+            state.held.delete(normalizedTargetPath);
+        }
+        stopSidecarLockMonitoring(held);
+    })();
+    try {
+        await held.releasePromise;
+        return true;
+    }
+    finally {
+        held.releasePromise = undefined;
+    }
+}
+function handleForHeldLock(state, normalizedTargetPath, held) {
+    return createHeldSidecarLockHandle({
+        normalizedTargetPath,
+        held,
+        release: async (options) => await releaseHeldLock(state, normalizedTargetPath, held, { retry: options?.retry }),
+    });
+}
+export function createSidecarLockManager(key) {
+    const state = resolveManagerState(key);
+    function ensureExitCleanupRegistered() {
+        ensureGlobalExitCleanupRegistered();
+        const lifecycle = ensureGlobalBeforeExitCleanupRegistered();
+        state.cleanupRegistered = true;
+        state.reclaimCleanupRegistered = true;
+        return lifecycle;
+    }
+    function armExitCleanup(lifecycle) {
+        lifecycle.armed = true;
+    }
+    function assertRetainOnExitSupported(retainOnExit) {
+        if (retainOnExit !== true || !exitCleanupCannotRetain())
+            return;
+        throw new FsSafeError("helper-unavailable", "retainOnExit requires this process's exit handlers to be retain-aware; an older package copy registered them first");
+    }
+    async function acquire(options) {
+        return await acquireSidecarLock(options, {
+            held: state.held,
+            admissions: state.admissions,
+            reclaimGuards: state.reclaimGuards,
+            ensureExitCleanupRegistered,
+            armExitCleanup,
+            assertRetainOnExitSupported,
+            handleForHeldLock: (normalizedTargetPath, held) => handleForHeldLock(state, normalizedTargetPath, held),
+        });
+    }
+    async function withLock(options, fn) {
+        const lock = await acquire(options);
+        let result;
+        try {
+            result = await fn();
+        }
+        catch (bodyError) {
+            try {
+                await lock.release();
+            }
+            catch (releaseError) {
+                throw createSuppressedError(releaseError, bodyError, "file lock callback and release both failed");
+            }
+            throw bodyError;
+        }
+        await lock.release();
+        return result;
+    }
+    async function drain() {
+        for (const [normalizedTargetPath, held] of Array.from(state.held.entries())) {
+            await releaseHeldLock(state, normalizedTargetPath, held, { force: true }).catch(() => undefined);
+        }
+    }
+    function reset() {
+        releaseAllLocksSync(state);
+    }
+    function heldEntries() {
+        return Array.from(state.held.entries()).map(([normalizedTargetPath, held]) => ({
+            normalizedTargetPath,
+            lockPath: held.lockPath,
+            acquiredAt: held.acquiredAt,
+            metadata: held.metadata,
+            forceRelease: () => releaseHeldLock(state, normalizedTargetPath, held, { force: true }),
+        }));
+    }
+    return { acquire, withLock, drain, reset, heldEntries };
+}
+export async function withSidecarLock(targetPath, options, fn) {
+    const manager = createSidecarLockManager(options.managerKey ?? `fs-safe.sidecar-lock:${targetPath}`);
+    const { managerKey: _managerKey, ...acquireOptions } = options;
+    return await manager.withLock({ ...acquireOptions, targetPath }, fn);
+}

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

@@ -0,0 +1,27 @@
+import { type BigIntStats, type Stats } from "node:fs";
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { NativeBinding } from "./native-binding.js";
+import { type MutationDirectoryObservation, type MutationDirectoryObserver } from "./pinned-mutation-observation.js";
+import type { StagedFileReceipt } from "./staged-file-types.js";
+export type StagedDirectorySnapshot = StagedFileReceipt["directory"];
+export type PolicyStagedDirectory = Readonly<{
+    directory: StagedDirectorySnapshot;
+    observation: MutationDirectoryObservation;
+    stat: BigIntStats;
+    observeCurrent?: MutationDirectoryObserver;
+    disposeObservation?(): void;
+}>;
+export declare function exactIdentityMatches(expected: FileIdentityStat, actual: Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>): boolean;
+export declare function describeStagedDirectory(fd: number, pathname: string): StagedDirectorySnapshot;
+export declare function assertStagedDirectoryCurrent(receipt: StagedDirectorySnapshot): BigIntStats;
+export declare function describePolicyStagedDirectory(fd: number, pathname: string, binding?: NativeBinding): PolicyStagedDirectory;
+export declare function assertPolicyStagedDirectoryCurrent(captured: PolicyStagedDirectory): BigIntStats;
+export declare function refreshPolicyStagedDirectoryObservation(captured: PolicyStagedDirectory): MutationDirectoryObservation;
+export declare function openStagedDirectory(directory: string | DirectoryReceipt<Stats | BigIntStats>): {
+    fd: number;
+    receipt: StagedDirectorySnapshot;
+};

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

@@ -0,0 +1,148 @@
+import fs, {} from "node:fs";
+import path from "node:path";
+import { directoryReceiptAuthority, ownDirectoryReceipt } from "./directory-receipt.js";
+import { FsSafeError } from "./errors.js";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { nativePolicyDirectoryObserver, NativePolicyDirectoryMismatch } from "./native-policy-directory-observation.js";
+import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
+import { realpathSync } from "./realpath.js";
+import { resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
+export function exactIdentityMatches(expected, actual) {
+    return ["dev", "ino"].every((key) => {
+        const value = expected[key];
+        return (typeof value === "bigint" || Number.isSafeInteger(value)) && BigInt(value) === actual[key];
+    });
+}
+export function describeStagedDirectory(fd, pathname) {
+    const identity = fs.fstatSync(fd, { bigint: true });
+    if (!identity.isDirectory()) {
+        throw new FsSafeError("not-file", "staging parent must be a directory");
+    }
+    const receipt = Object.freeze({
+        path: resolvePathPreservingWindowsRoot(pathname),
+        realPath: realpathSync(pathname),
+        identity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
+    });
+    assertStagedDirectoryCurrent(receipt);
+    return receipt;
+}
+export function assertStagedDirectoryCurrent(receipt) {
+    const current = fs.lstatSync(receipt.path, { bigint: true });
+    if (!current.isDirectory() || !exactIdentityMatches(receipt.identity, current) ||
+        realpathSync(receipt.path) !== receipt.realPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+    return current;
+}
+function sameDirectoryMetadata(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        left.nlink === right.nlink;
+}
+// The policy hot path is Node/POSIX-only. It deliberately uses native
+// canonicalization so a successful capture contains no JS realpath work.
+export function describePolicyStagedDirectory(fd, pathname, binding) {
+    const resolved = path.resolve(pathname);
+    const descriptor = fs.fstatSync(fd, { bigint: true });
+    if (!descriptor.isDirectory()) {
+        throw new FsSafeError("not-file", "staging parent must be a directory");
+    }
+    const observeCurrent = nativePolicyDirectoryObserver(binding, fd, resolved);
+    const observed = observeCurrent?.();
+    if (observed) {
+        if (!sameDirectoryMetadata(descriptor, observed.identity)) {
+            throw new NativePolicyDirectoryMismatch();
+        }
+        const directory = Object.freeze({
+            path: resolved,
+            realPath: observed.canonicalPath,
+            identity: Object.freeze({ dev: descriptor.dev, ino: descriptor.ino }),
+        });
+        return Object.freeze({
+            directory,
+            observation: checkedMutationDirectory(resolved, observed.canonicalPath, observed.identity, observeCurrent),
+            stat: descriptor,
+            observeCurrent,
+            disposeObservation: observeCurrent.dispose,
+        });
+    }
+    const before = inspectDirectoryIdentitySync(resolved);
+    const canonicalPath = path.resolve(realpathSync.native(resolved));
+    const after = inspectDirectoryIdentitySync(resolved, descriptor);
+    if (canonicalPath !== resolved || !sameDirectoryMetadata(descriptor, before) ||
+        !sameDirectoryMetadata(descriptor, after) ||
+        path.resolve(realpathSync.native(resolved)) !== canonicalPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+    const directory = Object.freeze({
+        path: resolved,
+        realPath: canonicalPath,
+        identity: Object.freeze({ dev: descriptor.dev, ino: descriptor.ino }),
+    });
+    return Object.freeze({
+        directory,
+        observation: checkedMutationDirectory(resolved, canonicalPath, after),
+        stat: after,
+    });
+}
+export function assertPolicyStagedDirectoryCurrent(captured) {
+    const observed = captured.observeCurrent?.();
+    if (observed) {
+        if (!sameDirectoryMetadata(captured.stat, observed.identity) ||
+            observed.canonicalPath !== captured.directory.realPath) {
+            throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+        }
+        return captured.stat;
+    }
+    const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
+    if (!sameDirectoryMetadata(captured.stat, current) ||
+        path.resolve(realpathSync.native(captured.directory.path)) !== captured.directory.realPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+    return current;
+}
+export function refreshPolicyStagedDirectoryObservation(captured) {
+    const observed = captured.observeCurrent?.();
+    if (observed) {
+        if (!exactIdentityMatches(captured.directory.identity, observed.identity) ||
+            observed.canonicalPath !== captured.directory.realPath) {
+            throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+        }
+        return checkedMutationDirectory(captured.directory.path, observed.canonicalPath, observed.identity, captured.observeCurrent);
+    }
+    const current = inspectDirectoryIdentitySync(captured.directory.path, captured.directory.identity);
+    const canonicalPath = path.resolve(realpathSync.native(captured.directory.path));
+    if (canonicalPath !== captured.directory.realPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+    return checkedMutationDirectory(captured.directory.path, canonicalPath, current);
+}
+export function openStagedDirectory(directory) {
+    const expected = typeof directory === "string"
+        ? undefined
+        : directoryReceiptAuthority(ownDirectoryReceipt(directory));
+    const pathname = resolvePathPreservingWindowsRoot(typeof directory === "string" ? directory : expected.path);
+    const before = fs.lstatSync(pathname, { bigint: true });
+    if (!before.isDirectory()) {
+        throw new FsSafeError("not-file", "staging parent must be a real directory");
+    }
+    if (expected && (!exactIdentityMatches(expected.identity, before) || realpathSync(pathname) !== expected.realPath)) {
+        throw new FsSafeError("path-mismatch", "stale staging directory receipt");
+    }
+    const fd = fs.openSync(pathname, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    try {
+        const receipt = describeStagedDirectory(fd, pathname);
+        if (!exactIdentityMatches(before, receipt.identity)) {
+            throw new FsSafeError("path-mismatch", "staging directory changed while opening");
+        }
+        return { fd, receipt };
+    }
+    catch (error) {
+        try {
+            fs.closeSync(fd);
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], "staging directory admission and close failed");
+        }
+        throw error;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/staged-file-settlement.d.ts

@@ -0,0 +1,16 @@
+import type { BigIntStats } from "node:fs";
+import { FsSafeError } from "./errors.js";
+import type { StagedFileCleanupReceipt, StagedFileFailureDetails, StagedFilePublication, StagedFileReceipt } from "./staged-file-types.js";
+export declare function createStagedFileReceipt(directory: StagedFileReceipt["directory"], temporaryBasename: string, stat: BigIntStats): StagedFileReceipt;
+export declare function stagedFileFailure(error: unknown, details: StagedFileFailureDetails): FsSafeError;
+/** Finish owned cleanup and every close before surfacing publication evidence. */
+export declare function settleStagedFile(params: {
+    temporaryBasename: string;
+    publication: StagedFilePublication;
+    phase: StagedFileFailureDetails["phase"];
+    failure?: {
+        error: unknown;
+    };
+    cleanup: () => Promise<StagedFileCleanupReceipt["status"]>;
+    close: readonly (() => Promise<void> | void)[];
+}): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/staged-file-settlement.js

@@ -0,0 +1,57 @@
+import { FsSafeError } from "./errors.js";
+export function createStagedFileReceipt(directory, temporaryBasename, stat) {
+    return Object.freeze({
+        directory,
+        temporaryBasename,
+        identity: Object.freeze({
+            dev: stat.dev, ino: stat.ino, mode: Number(stat.mode & 4095n),
+            nlink: stat.nlink, size: stat.size, uid: Number(stat.uid), gid: Number(stat.gid),
+            mtimeNs: stat.mtimeNs, ctimeNs: stat.ctimeNs,
+        }),
+    });
+}
+export function stagedFileFailure(error, details) {
+    const code = error instanceof FsSafeError
+        ? error.code
+        : error?.code === "EEXIST" ? "already-exists" : "helper-failed";
+    return new FsSafeError(code, `staged file ${details.phase} failed`, { cause: error, details });
+}
+/** Finish owned cleanup and every close before surfacing publication evidence. */
+export async function settleStagedFile(params) {
+    const errors = params.failure ? [params.failure.error] : [];
+    let status;
+    try {
+        status = await params.cleanup();
+    }
+    catch (error) {
+        status = "failed";
+        errors.push(error);
+    }
+    let resources = "closed";
+    for (const close of params.close) {
+        try {
+            await close();
+        }
+        catch (error) {
+            resources = "close-failed";
+            errors.push(error);
+        }
+    }
+    const incomplete = status === "failed" || status === "preserved" || resources === "close-failed";
+    // A settled pre-publication failure retains the producer/authority rejection exactly.
+    if (!incomplete && (!params.failure || params.publication.status === "not-published"))
+        return;
+    const error = errors.length > 1 ? new AggregateError(errors, "staged operation and settlement failed")
+        : errors.length === 1 ? errors[0] : new FsSafeError("not-removable", "staged cleanup preserved an unverified entry");
+    const cleanup = Object.freeze({
+        temporaryBasename: params.temporaryBasename,
+        publication: params.publication,
+        status,
+        resources,
+    });
+    throw stagedFileFailure(error, {
+        phase: params.failure ? params.phase : "cleanup",
+        publication: params.publication,
+        cleanup,
+    });
+}

package/node_modules/@openclaw/fs-safe/dist/staged-file-types.d.ts

@@ -0,0 +1,55 @@
+export type StagedFileReceipt = Readonly<{
+    directory: Readonly<{
+        path: string;
+        realPath: string;
+        identity: Readonly<{
+            dev: bigint;
+            ino: bigint;
+        }>;
+    }>;
+    temporaryBasename: string;
+    /** Preparation-time metadata of the private stage, not a final-file fingerprint. */
+    identity: Readonly<{
+        dev: bigint;
+        ino: bigint;
+        mode: number;
+        nlink: bigint;
+        size: bigint;
+        uid: number;
+        gid: number;
+        mtimeNs: bigint;
+        ctimeNs: bigint;
+    }>;
+}>;
+export type PublishedFileReceipt = Readonly<{
+    status: "published";
+    staged: StagedFileReceipt;
+    basename: string;
+    overwrite: boolean;
+}>;
+export type StagedFilePublication = Readonly<{
+    status: "not-published";
+}> | PublishedFileReceipt | Readonly<{
+    status: "indeterminate";
+    basename: string;
+    overwrite: boolean;
+}>;
+export type StagedFileCleanupReceipt = Readonly<{
+    temporaryBasename: string;
+    publication: StagedFilePublication;
+    status: "removed" | "name-absent" | "preserved" | "failed" | "not-needed";
+    resources: "closed" | "close-failed";
+}>;
+export type StagedFileFailureDetails = Readonly<{
+    phase: "prepare" | "publish" | "cleanup";
+    publication: StagedFilePublication;
+    cleanup?: StagedFileCleanupReceipt;
+}>;
+export interface StagedFile extends AsyncDisposable {
+    readonly receipt: StagedFileReceipt;
+    assertCurrent(): Promise<void>;
+    publish(basename: string, options: {
+        overwrite: boolean;
+    }): Promise<PublishedFileReceipt>;
+    cleanup(): Promise<StagedFileCleanupReceipt>;
+}

package/node_modules/@openclaw/fs-safe/dist/staged-file-types.js

@@ -0,0 +1 @@
+export {};

package/node_modules/@openclaw/fs-safe/dist/staged-symlink-types.d.ts

@@ -0,0 +1,39 @@
+import type { PublishedFileReceipt, StagedFileCleanupReceipt, StagedFileReceipt } from "./staged-file-types.js";
+/** Caller-captured admission evidence, never a same-target ownership heuristic. */
+export type StagedSymlinkExpected = Readonly<Pick<StagedFileReceipt["identity"], "dev" | "ino" | "uid" | "gid" | "ctimeNs"> & {
+    target: string;
+}>;
+export type StagedSymlinkReceipt = StagedFileReceipt & Readonly<{
+    target: string;
+}>;
+export type PublishedSymlinkReceipt = Readonly<Pick<PublishedFileReceipt, "status" | "basename"> & {
+    staged: StagedSymlinkReceipt;
+    overwrite: false;
+}>;
+export type StagedSymlinkPublication = Readonly<{
+    status: "not-published";
+}> | PublishedSymlinkReceipt | Readonly<{
+    status: "indeterminate";
+    basename: string;
+    overwrite: false;
+}>;
+export type StagedSymlinkRemoval = "removed" | "name-absent" | "preserved";
+export type StagedSymlinkCleanupReceipt = Readonly<Pick<StagedFileCleanupReceipt, "temporaryBasename" | "status" | "resources"> & {
+    publication: StagedSymlinkPublication;
+}>;
+export type StagedSymlinkFailureDetails = Readonly<{
+    phase: "prepare" | "publish" | "remove-published" | "cleanup";
+    publication: StagedSymlinkPublication;
+    cleanup?: StagedSymlinkCleanupReceipt;
+}>;
+export interface StagedSymlink extends AsyncDisposable {
+    readonly receipt: StagedSymlinkReceipt;
+    assertCurrent(): Promise<void>;
+    publish(basename: string): Promise<PublishedSymlinkReceipt>;
+    /** Check the published name against the still-retained original symlink. */
+    assertPublished(): Promise<void>;
+    /** Explicit recovery only. Never removes an observed foreign replacement. */
+    removePublished(): Promise<StagedSymlinkRemoval>;
+    /** Closes the owner; only an unattempted, still-owned stage is removed. */
+    cleanup(): Promise<StagedSymlinkCleanupReceipt>;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,10 @@
+import type { BigIntStats, Stats } from "node:fs";
+export type ExactStatIdentity = Pick<BigIntStats, "dev" | "ino">;
+export type StatObservationReceipt = {
+    stat: Stats | BigIntStats;
+    identity: ExactStatIdentity;
+};
+/** Operation-local metadata plus exact identity; never use projected PathStat IDs. */
+export declare function inspectStatObservationSync(inspect: (bigint: boolean) => Stats | BigIntStats, expected?: ExactStatIdentity, initial?: Stats | BigIntStats, platform?: NodeJS.Platform): StatObservationReceipt;
+/** Revalidate an exact identity without allocating a receipt that the caller will discard. */
+export declare function assertStatObservationSync(inspect: (bigint: boolean) => Stats | BigIntStats, expected: ExactStatIdentity, initial?: Stats | BigIntStats, platform?: NodeJS.Platform): Stats | BigIntStats;