@openclaw/signal 2026.9.5 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/archive-durability.js

@@ -0,0 +1,180 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import fsSync from "node:fs";
+import path from "node:path";
+import { ownExtractionDestinationMutation } from "./archive-deadline.js";
+import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createArchiveSymlinkTraversalError, } from "./archive-staging.js";
+import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
+import { pinDirectory, syncDirectory } from "./directory-durability.js";
+import { syncFileBestEffort } from "./file-sync.js";
+import { normalizePinnedWriteError } from "./root-errors.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+import { FsSafeError } from "./errors.js";
+export async function finalizeArchivePublication(params) {
+    const check = () => params.deadline?.check();
+    const assertGuards = async (guards) => {
+        for (const guard of [params.destinationGuard, ...guards, params.sourceGuard]) {
+            await assertDirectoryIdentityGuard(guard);
+            check();
+        }
+    };
+    await ownExtractionDestinationMutation(params.deadline, async () => {
+        if (params.durable) {
+            // Join every active sync before propagating failure or starting another batch.
+            for (let offset = 0; offset < params.files.length; offset += 8) {
+                check();
+                const results = await Promise.allSettled(params.files.slice(offset, offset + 8).map(async (file) => {
+                    const env_1 = { stack: [], error: void 0, hasError: false };
+                    try {
+                        await assertGuards(file.guards);
+                        const opened = __addDisposableResource(env_1, await params.targetRoot.open(file.relativePath, { hardlinks: "reject", symlinks: "reject" })
+                            .catch((error) => {
+                            if (error instanceof FsSafeError && (error.code === "hardlink" || error.code === "path-alias")) {
+                                throw createArchiveSymlinkTraversalError(file.relativePath);
+                            }
+                            throw error;
+                        }), true);
+                        check();
+                        await inspectFileIdentity(() => fsSync.fstatSync(opened.handle.fd, { bigint: true }), file.identity);
+                        check();
+                        await syncFileBestEffort(opened.handle).catch((error) => { throw normalizePinnedWriteError(error); });
+                        check();
+                        await assertGuards(file.guards);
+                        await inspectFileIdentity(async () => {
+                            const stat = fsSync.lstatSync(opened.realPath, { bigint: true });
+                            if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink > 1n) {
+                                throw new FsSafeError("path-mismatch", "archive file changed during durability pass");
+                            }
+                            return stat;
+                        }, file.identity);
+                        check();
+                    }
+                    catch (e_1) {
+                        env_1.error = e_1;
+                        env_1.hasError = true;
+                    }
+                    finally {
+                        const result_1 = __disposeResources(env_1);
+                        if (result_1)
+                            await result_1;
+                    }
+                }));
+                const failure = results.find((result) => result.status === "rejected");
+                if (failure?.status === "rejected")
+                    throw failure.reason;
+            }
+        }
+        // Leave working modes intact until file syncing finishes. Re-pin one directory
+        // at a time against its original guard, so wide archives do not exhaust fds.
+        const directories = [...params.directories].sort((a, b) => b.guard.dir.split(path.sep).length - a.guard.dir.split(path.sep).length);
+        for (const directory of directories) {
+            const guards = [...directory.parents, directory.guard];
+            await assertGuards(guards);
+            const owner = await pinNodeDirectoryForMode(directory.guard.dir);
+            let pinned;
+            try {
+                check();
+                await assertGuards(guards);
+                if (params.durable && process.platform !== "win32") {
+                    // An existing search-only directory may become readable in its final mode.
+                    try {
+                        pinned = await pinDirectory(directory.guard.dir);
+                    }
+                    catch (error) {
+                        if (error.code !== "EACCES")
+                            throw error;
+                    }
+                    check();
+                }
+                await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("chmod", directory.guard.dir);
+                check();
+                await assertGuards(guards);
+                await owner.apply(directory.mode, { check, beforeChmod: async () => {
+                        await assertGuards(guards);
+                        await assertResolvedInsideDestination({ destinationRealDir: params.destinationGuard.realPath,
+                            targetPath: directory.guard.dir, originalPath: path.relative(params.targetRoot.rootDir, directory.guard.dir) });
+                        check();
+                    } });
+                check();
+                await assertGuards(guards);
+                if (params.durable) {
+                    if (process.platform === "win32") {
+                        await syncDirectory(directory.guard.dir).catch((error) => { throw normalizePinnedWriteError(error); });
+                    }
+                    else {
+                        pinned ??= await pinDirectory(directory.guard.dir);
+                        check();
+                        await pinned.sync().catch((error) => { throw normalizePinnedWriteError(error); });
+                    }
+                    check();
+                    await assertGuards(guards);
+                }
+            }
+            finally {
+                try {
+                    await pinned?.close();
+                }
+                finally {
+                    await owner.close();
+                }
+            }
+        }
+        if (params.durable) {
+            await assertGuards([]);
+            await syncDirectory(params.destinationGuard.realPath).catch((error) => { throw normalizePinnedWriteError(error); });
+            check();
+            await assertGuards([]);
+        }
+    });
+}

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

@@ -0,0 +1,13 @@
+export declare function isWindowsDrivePath(value: string): boolean;
+export declare function normalizeArchiveEntryPath(raw: string): string;
+export declare function validateArchiveEntryPath(entryPath: string, params?: {
+    escapeLabel?: string;
+}): void;
+export declare function stripArchivePath(entryPath: string, stripComponents: number): string | null;
+export declare function createArchiveOutputPathTracker(): (entryPath: string, originalPath: string) => void;
+export declare function resolveArchiveOutputPath(params: {
+    rootDir: string;
+    relPath: string;
+    originalPath: string;
+    escapeLabel?: string;
+}): string;

package/node_modules/@openclaw/fs-safe/dist/archive-entry.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { ArchiveSecurityError } from "./archive-errors.js";
+import { isWindowsReservedDeviceName } from "./device-path.js";
+import { formatErrorDetail } from "./error-detail.js";
+import { resolveSafeBaseDir } from "./path.js";
+import { lowerCaseNfc, maxNormalizedUtf8Bytes } from "./unicode-path.js";
+export function isWindowsDrivePath(value) {
+    return /(?:^|\/)[a-zA-Z]:/.test(normalizeArchiveEntryPath(value));
+}
+export function normalizeArchiveEntryPath(raw) {
+    return raw.replaceAll("\\", "/");
+}
+export function validateArchiveEntryPath(entryPath, params) {
+    if (!entryPath || entryPath === "." || entryPath === "./") {
+        return;
+    }
+    if (isWindowsDrivePath(entryPath)) {
+        throw new ArchiveSecurityError("entry-path", `archive entry uses a drive path: ${formatErrorDetail(entryPath)}`);
+    }
+    if (entryPath.includes("\0")) {
+        throw new ArchiveSecurityError("entry-path", `archive entry contains a NUL byte: ${formatErrorDetail(entryPath)}`);
+    }
+    const slashNormalized = normalizeArchiveEntryPath(entryPath);
+    const rawSegments = slashNormalized.split("/");
+    if (process.platform === "win32" &&
+        rawSegments.some((segment) => segment.includes(":"))) {
+        throw new ArchiveSecurityError("entry-path", `archive entry uses a Windows alternate data stream path: ${formatErrorDetail(entryPath)}`);
+    }
+    if (process.platform === "win32" &&
+        rawSegments.some((segment) => isWindowsReservedDeviceName(segment))) {
+        throw new ArchiveSecurityError("entry-path", `archive entry uses a reserved device path: ${formatErrorDetail(entryPath)}`);
+    }
+    const normalized = path.posix.normalize(slashNormalized);
+    if (normalized.split("/").some((segment) => maxNormalizedUtf8Bytes(segment) > 255)) {
+        throw new ArchiveSecurityError("entry-path", `archive entry has an overlong path component: ${formatErrorDetail(entryPath)}`);
+    }
+    const escapeLabel = params?.escapeLabel ?? "destination";
+    if (normalized === ".." || normalized.startsWith("../")) {
+        throw new ArchiveSecurityError("entry-path", `archive entry escapes ${escapeLabel}: ${formatErrorDetail(entryPath)}`);
+    }
+    if (path.posix.isAbsolute(normalized) || normalized.startsWith("//")) {
+        throw new ArchiveSecurityError("entry-path", `archive entry is absolute: ${formatErrorDetail(entryPath)}`);
+    }
+    if (rawSegments.includes("..")) {
+        throw new ArchiveSecurityError("entry-path", `archive entry contains a parent segment: ${formatErrorDetail(entryPath)}`);
+    }
+}
+// Validate raw paths first. Zero stripping gives the canonical policy identity.
+export function stripArchivePath(entryPath, stripComponents) {
+    const raw = normalizeArchiveEntryPath(entryPath);
+    if (!raw || raw === "." || raw === "./") {
+        return null;
+    }
+    const parts = raw.split("/").filter((part) => part.length > 0 && part !== ".");
+    const strip = Math.max(0, Math.floor(stripComponents));
+    const stripped = strip === 0 ? parts.join("/") : parts.slice(strip).join("/");
+    const result = path.posix.normalize(stripped);
+    if (!result || result === "." || result === "./") {
+        return null;
+    }
+    return result;
+}
+export function createArchiveOutputPathTracker() {
+    const seen = new Set();
+    return (entryPath, originalPath) => {
+        const normalized = path.posix.normalize(normalizeArchiveEntryPath(entryPath));
+        // Archive policy must not depend on the destination volume's case or
+        // Unicode-normalization behavior. Otherwise the JavaScript and native
+        // writers can disagree about which of two colliding entries wins.
+        const collisionKey = lowerCaseNfc(normalized);
+        if (seen.has(collisionKey)) {
+            throw new ArchiveSecurityError("entry-path", `archive entries collide at output path ${formatErrorDetail(normalized)}: ${formatErrorDetail(originalPath)}`);
+        }
+        seen.add(collisionKey);
+    };
+}
+export function resolveArchiveOutputPath(params) {
+    const safeBase = resolveSafeBaseDir(params.rootDir);
+    const outPath = path.resolve(params.rootDir, params.relPath);
+    const escapeLabel = params.escapeLabel ?? "destination";
+    if (!outPath.startsWith(safeBase)) {
+        throw new ArchiveSecurityError("entry-path", `archive entry escapes ${escapeLabel}: ${formatErrorDetail(params.originalPath)}`);
+    }
+    return outPath;
+}

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

@@ -0,0 +1,12 @@
+export type ArchiveFormatErrorCode = "archive-header-invalid";
+export type ArchiveSecurityErrorCode = "destination-not-directory" | "destination-symlink" | "destination-symlink-traversal" | "entry-filtered" | "entry-link" | "entry-path";
+export declare class ArchiveSecurityError extends Error {
+    readonly code: ArchiveSecurityErrorCode;
+    constructor(code: ArchiveSecurityErrorCode, message: string, options?: ErrorOptions);
+}
+export declare class ArchiveFormatError extends Error {
+    readonly code: ArchiveFormatErrorCode;
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function isArchiveFormatErrorMessage(message: string): boolean;
+export declare function isArchiveTarPathErrorMessage(message: string): boolean;

package/node_modules/@openclaw/fs-safe/dist/archive-errors.js

@@ -0,0 +1,23 @@
+export class ArchiveSecurityError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "ArchiveSecurityError";
+    }
+}
+export class ArchiveFormatError extends Error {
+    code;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ArchiveFormatError";
+        this.code = "archive-header-invalid";
+    }
+}
+export function isArchiveFormatErrorMessage(message) {
+    return (message.includes("archive-header-invalid") ||
+        message.includes("archive entry size did not match its manifest"));
+}
+export function isArchiveTarPathErrorMessage(message) {
+    return message.includes("archive-gnu-path-invalid") || message.includes("archive-entry-path-invalid");
+}

package/node_modules/@openclaw/fs-safe/dist/archive-gzip-tail.d.ts

@@ -0,0 +1,20 @@
+import { Writable } from "node:stream";
+import type { Gunzip } from "node:zlib";
+export declare function isGzipBuffer(input: Uint8Array): boolean;
+/** Validate the same physical suffix when admission owns an in-memory input. */
+export declare function validateGzipBufferTail(input: Buffer, consumed: number, signal?: AbortSignal): Promise<void>;
+/** Track physical input, not the sum of bytes consumed across separate writes:
+ * gunzip can resume on a later chunk after leaving an earlier padding gap. */
+export declare class GzipInput extends Writable {
+    private readonly decoder;
+    private position;
+    private firstUnused;
+    constructor(decoder: Gunzip);
+    get tailOffset(): number;
+    _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
+    _final(callback: (error?: Error | null) => void): void;
+    _destroy(error: Error | null, callback: (error: Error | null) => void): void;
+}
+/** Check the immutable staged suffix from the first unused physical byte,
+ * including later chunks the decoder may have consumed, before returning. */
+export declare function validateGzipContainerTail(filePath: string, consumed: number, signal?: AbortSignal): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/archive-gzip-tail.js

@@ -0,0 +1,99 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { Writable } from "node:stream";
+import { ArchiveFormatError } from "./archive-errors.js";
+const PADDING_WINDOW_BYTES = 65536;
+let zeroPadding;
+function assertZeroPadding(bytes) {
+    zeroPadding ??= Buffer.alloc(PADDING_WINDOW_BYTES);
+    if (!bytes.equals(zeroPadding.subarray(0, bytes.length))) {
+        throw new ArchiveFormatError("nonzero gzip container padding");
+    }
+}
+export function isGzipBuffer(input) {
+    return input[0] === 31 && input[1] === 139;
+}
+function assertConsumedBoundary(consumed, size) {
+    if (!Number.isSafeInteger(consumed) || consumed <= 0 || consumed > size) {
+        throw new ArchiveFormatError("invalid gzip consumed-input boundary");
+    }
+}
+/** Validate the same physical suffix when admission owns an in-memory input. */
+export async function validateGzipBufferTail(input, consumed, signal) {
+    signal?.throwIfAborted();
+    assertConsumedBoundary(consumed, input.length);
+    for (let position = consumed; position < input.length; position += PADDING_WINDOW_BYTES) {
+        signal?.throwIfAborted();
+        assertZeroPadding(input.subarray(position, position + PADDING_WINDOW_BYTES));
+        if (position + PADDING_WINDOW_BYTES < input.length)
+            await new Promise(resolve => setImmediate(resolve));
+    }
+    signal?.throwIfAborted();
+}
+/** Track physical input, not the sum of bytes consumed across separate writes:
+ * gunzip can resume on a later chunk after leaving an earlier padding gap. */
+export class GzipInput extends Writable {
+    decoder;
+    position = 0;
+    firstUnused;
+    constructor(decoder) {
+        super({ highWaterMark: 65536 });
+        this.decoder = decoder;
+    }
+    get tailOffset() {
+        return this.firstUnused ?? this.position;
+    }
+    _write(chunk, _encoding, callback) {
+        const before = this.decoder.bytesWritten;
+        this.decoder.write(chunk, (error) => {
+            if (error) {
+                callback(error);
+                return;
+            }
+            const used = this.decoder.bytesWritten - before;
+            if (!Number.isSafeInteger(used) || used < 0 || used > chunk.length ||
+                !Number.isSafeInteger(this.position + chunk.length)) {
+                callback(new ArchiveFormatError("invalid gzip consumed-input boundary"));
+                return;
+            }
+            if (used < chunk.length)
+                this.firstUnused ??= this.position + used;
+            this.position += chunk.length;
+            callback();
+        });
+    }
+    _final(callback) {
+        this.decoder.end(callback);
+    }
+    _destroy(error, callback) {
+        if (error || !this.writableFinished)
+            this.decoder.destroy(error ?? undefined);
+        callback(error);
+    }
+}
+/** Check the immutable staged suffix from the first unused physical byte,
+ * including later chunks the decoder may have consumed, before returning. */
+export async function validateGzipContainerTail(filePath, consumed, signal) {
+    signal?.throwIfAborted();
+    const handle = await fs.open(filePath, "r");
+    try {
+        const { size } = fsSync.fstatSync(handle.fd);
+        assertConsumedBoundary(consumed, size);
+        if (consumed === size)
+            return;
+        const buffer = Buffer.allocUnsafe(PADDING_WINDOW_BYTES);
+        let position = consumed;
+        while (position < size) {
+            signal?.throwIfAborted();
+            const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, size - position), position);
+            signal?.throwIfAborted();
+            if (bytesRead === 0)
+                throw new ArchiveFormatError("truncated gzip container padding");
+            assertZeroPadding(buffer.subarray(0, bytesRead));
+            position += bytesRead;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { FileHandle } from "node:fs/promises";
+import type { ExtractionDeadline } from "./archive-deadline.js";
+import { type ResolvedArchiveExtractLimits } from "./archive-limits.js";
+export type StagedArchiveFile = {
+    path: string;
+    cleanup: () => Promise<void>;
+};
+export declare function writeFileHandleFully(params: {
+    handle: FileHandle;
+    buffer: Buffer;
+    bytes: number;
+    deadline: ExtractionDeadline;
+}): Promise<void>;
+export declare function stageArchiveFileForExtraction(params: {
+    archivePath: string;
+    limits: ResolvedArchiveExtractLimits;
+    deadline: ExtractionDeadline;
+}): Promise<StagedArchiveFile>;

package/node_modules/@openclaw/fs-safe/dist/archive-input.js

@@ -0,0 +1,98 @@
+import fsSync, { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, } from "./archive-limits.js";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { tempFile } from "./temp-target.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+async function closeFileHandle(handle) {
+    if (handle)
+        await handle.close().catch(() => undefined);
+}
+export async function writeFileHandleFully(params) {
+    let offset = 0;
+    while (offset < params.bytes) {
+        params.deadline.check();
+        const { bytesWritten } = await params.handle.write(params.buffer, offset, params.bytes - offset);
+        if (bytesWritten <= 0) {
+            throw new Error("archive staging write made no progress");
+        }
+        offset += bytesWritten;
+    }
+}
+export async function stageArchiveFileForExtraction(params) {
+    params.deadline.check();
+    const archivePath = params.archivePath;
+    assertNoWindowsPathAlias(archivePath);
+    const sourcePath = path.resolve(archivePath);
+    assertNoWindowsPathAlias(sourcePath);
+    const initialStat = await inspectFileIdentity(async () => {
+        const stat = fsSync.lstatSync(sourcePath, { bigint: true });
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw new Error(`archive is not a regular file: ${archivePath}`);
+        }
+        return stat;
+    });
+    if (initialStat.size > params.limits.maxArchiveBytes) {
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+    }
+    const handle = await fs.open(sourcePath, resolveReadOpenFlags());
+    let staged;
+    let output;
+    try {
+        staged = await tempFile({
+            prefix: "fs-safe-archive-input",
+            fileName: path.basename(sourcePath),
+        });
+        const opened = await inspectFileIdentity(async () => {
+            const stat = fsSync.fstatSync(handle.fd, { bigint: true });
+            if (!stat.isFile())
+                throw new Error("archive changed during validation");
+            return stat;
+        }, initialStat);
+        await inspectFileIdentity(async () => {
+            const stat = fsSync.lstatSync(sourcePath, { bigint: true });
+            if (stat.isSymbolicLink() || !stat.isFile())
+                throw new Error("archive changed during validation");
+            return stat;
+        }, opened);
+        const flags = fsConstants.O_WRONLY |
+            fsConstants.O_CREAT |
+            fsConstants.O_EXCL |
+            (process.platform !== "win32" && "O_NOFOLLOW" in fsConstants
+                ? fsConstants.O_NOFOLLOW
+                : 0);
+        output = await fs.open(staged.path, flags, 0o600);
+        const buffer = Buffer.allocUnsafe(Math.min(512 * 1024, Math.max(64 * 1024, Number(opened.size)), params.limits.maxArchiveBytes + 1));
+        let written = 0;
+        while (true) {
+            params.deadline.check();
+            const length = Math.min(buffer.length, params.limits.maxArchiveBytes - written + 1);
+            const { bytesRead } = await handle.read(buffer, 0, length, null);
+            params.deadline.check();
+            if (bytesRead === 0)
+                break;
+            written += bytesRead;
+            if (written > params.limits.maxArchiveBytes) {
+                throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+            }
+            await writeFileHandleFully({ handle: output, buffer, bytes: bytesRead, deadline: params.deadline });
+        }
+        await output.close();
+        output = undefined;
+        return staged;
+    }
+    catch (error) {
+        await closeFileHandle(output);
+        await staged?.cleanup().catch(() => undefined);
+        if (error instanceof FsSafeError && error.code === "path-mismatch") {
+            throw new FsSafeError("path-mismatch", "archive changed during validation", { cause: error });
+        }
+        throw error;
+    }
+    finally {
+        await closeFileHandle(handle);
+    }
+}

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

@@ -0,0 +1,7 @@
+export type ArchiveKind = "tar" | "tar-bzip2" | "tar-zstd" | "zip";
+export declare function resolveArchiveKind(filePath: string): ArchiveKind | null;
+type ResolvePackedRootDirOptions = {
+    rootMarkers?: string[];
+};
+export declare function resolvePackedRootDir(extractDir: string, options?: ResolvePackedRootDirOptions): Promise<string>;
+export {};

package/node_modules/@openclaw/fs-safe/dist/archive-kind.js

@@ -0,0 +1,71 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getNativeBinding } from "./native.js";
+import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
+const TAR_SUFFIXES = [".tgz", ".tar.gz", ".tar"];
+const COMPRESSED_TAR_SUFFIXES = [
+    { suffixes: [".tbz2", ".tbz", ".tar.bz2"], kind: "tar-bzip2" },
+    { suffixes: [".tzst", ".tar.zst", ".tar.zstd"], kind: "tar-zstd" },
+];
+export function resolveArchiveKind(filePath) {
+    const lower = normalizeLowercaseStringOrEmpty(filePath);
+    if (lower.endsWith(".zip")) {
+        return "zip";
+    }
+    for (const { suffixes, kind } of COMPRESSED_TAR_SUFFIXES) {
+        if (suffixes.some((suffix) => lower.endsWith(suffix))) {
+            // Preserve strict require diagnostics even when only resolving a suffix.
+            getNativeBinding();
+            return kind;
+        }
+    }
+    if (TAR_SUFFIXES.some((suffix) => lower.endsWith(suffix))) {
+        return "tar";
+    }
+    return null;
+}
+async function hasPackedRootMarker(extractDir, rootMarkers) {
+    for (const marker of rootMarkers) {
+        const trimmed = marker.trim();
+        if (!trimmed) {
+            continue;
+        }
+        try {
+            fsSync.statSync(path.join(extractDir, trimmed));
+            return true;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return false;
+}
+export async function resolvePackedRootDir(extractDir, options) {
+    const direct = path.join(extractDir, "package");
+    try {
+        const stat = fsSync.statSync(direct);
+        if (stat.isDirectory()) {
+            return direct;
+        }
+    }
+    catch {
+        // ignore
+    }
+    if ((options?.rootMarkers?.length ?? 0) > 0) {
+        const hasMarker = await hasPackedRootMarker(extractDir, options?.rootMarkers ?? []);
+        if (hasMarker) {
+            return extractDir;
+        }
+    }
+    const entries = await fs.readdir(extractDir, { withFileTypes: true });
+    const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    if (dirs.length !== 1) {
+        throw new Error(`unexpected archive layout (dirs: ${dirs.join(", ")})`);
+    }
+    const onlyDir = dirs[0];
+    if (!onlyDir) {
+        throw new Error("unexpected archive layout (no package dir found)");
+    }
+    return path.join(extractDir, onlyDir);
+}