@openclaw/fs-safe 0.18.2 → 0.20.0

package/dist/publish-copy-stage.js

@@ -22,6 +22,10 @@ export function publishCopyStage(params) {
     // Caller authority checks can synchronously replace a parent or staged entry.
     if (params.assertBeforeMutation)
         assertCurrent();
+    // An observed collision needs no dispatch; errno after a link attempt remains ambiguous.
+    if (fs.lstatSync(targetPath, { throwIfNoEntry: false })) {
+        throw new FsSafeError("already-exists", "destination already exists");
+    }
     params.onPublicationAttempt?.();
     fs.linkSync(temporaryPath, targetPath);
     let observerRejected = false;

package/dist/read-opened-file.d.ts

@@ -7,12 +7,9 @@ export type ReadResult = {
     realPath: string;
     stat: Stats;
 };
-type OpenedFile = {
+type OpenedFile = Omit<ReadResult & {
     handle: FileHandle;
-    containment: ContainmentGuarantee;
-    realPath: string;
-    stat: Stats;
-};
+}, "buffer">;
 export declare function readOpenedFileSafely(params: {
     opened: OpenedFile;
     maxBytes?: number;

package/dist/regular-file.js

@@ -208,10 +208,10 @@ function inspectAppendPath(filePath) {
 }
 function prepareRegularAppend(filePath, rejectSymlinkParents) {
     if (rejectSymlinkParents === true) {
-        const resolvedDir = resolvePathPreservingWindowsRoot(path.dirname(filePath));
+        const unresolvedDir = path.dirname(filePath);
         assertNoSymlinkParentsSync({
-            rootDir: path.parse(resolvedDir).root,
-            targetPath: resolvedDir,
+            rootDir: path.parse(resolvePathPreservingWindowsRoot(unresolvedDir)).root,
+            targetPath: unresolvedDir,
             allowMissing: false,
             allowRootChildSymlink: true,
             requireDirectories: true,

package/dist/replace-file-copy-fallback.d.ts

@@ -9,9 +9,8 @@ type AsyncFallbackFs = {
     lstat: typeof import("node:fs/promises").lstat;
     open: typeof import("node:fs/promises").open;
     rm: typeof import("node:fs/promises").rm;
-    unlink: typeof import("node:fs/promises").unlink;
 };
-type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "unlinkSync" | "writeSync">;
+type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "writeSync">;
 export declare function assertDestinationHardlinkPolicy(fsModule: AsyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): Promise<void>;
 export declare function assertDestinationHardlinkPolicySync(fsModule: SyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): void;
 export declare function copyFallbackReplace(params: {

package/dist/root-context.js

@@ -107,7 +107,7 @@ export function rootRelativeReadPath(root, filePath) {
                 resolveCandidateRoot: base === root.rootDir && root.rootDir !== root.rootReal,
             });
             if (admitted)
-                return admitted.relativePath;
+                return `.${path.sep}${admitted.relativePath}`;
             continue;
         }
         const prefix = ensureTrailingSep(base);
@@ -116,7 +116,8 @@ export function rootRelativeReadPath(root, filePath) {
             let start = prefix.length;
             while (raw[start] === path.sep)
                 start += 1;
-            return raw.slice(start);
+            // An admitted absolute tail stays literal, including a leading home marker.
+            return `.${path.sep}${raw.slice(start)}`;
         }
     }
     return raw;

package/dist/root-impl.js

@@ -798,7 +798,6 @@ async function mkdirPathInRoot(root, params) {
     const prepared = policy && resolved.relativePosix !== ""
         ? await preparePinnedWriteMutationAdmission({
             rootReal: resolved.rootReal,
-            rootWithSep: ensureTrailingSep(resolved.rootReal),
             rootIdentity: root.rootIdentity,
             resolvedTargetPath: resolved.resolved,
             originalPath: params.relativePath,
@@ -1045,10 +1044,8 @@ async function resolvePinnedRootPathInRoot(root, params) {
             throw err;
         throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
     }
-    const rootWithSep = ensureTrailingSep(resolved.rootCanonicalPath);
     return {
         rootReal: resolved.rootCanonicalPath,
-        rootWithSep,
         canonicalPath: resolved.canonicalPath,
     };
 }

package/dist/root-move-noreplace.d.ts

@@ -1,13 +1,8 @@
 import { type BigIntStats, type Stats } from "node:fs";
-import { type DenyMutationPolicy } from "./deny-mutations.js";
+import type { RootMoveOptions } from "./root-options.js";
 import { type RootContext } from "./root-context.js";
-import { type MutationSymlinkPolicy } from "./root-symlink-policy.js";
 export declare function admitMoveSourceStat<T extends Stats | BigIntStats>(stat: T, overwrite?: boolean): T;
-export declare function movePathNoReplaceNative(root: RootContext, params: {
-    assertBeforeMutation?: () => void;
-    denyMutations?: DenyMutationPolicy;
-    mutationSymlinks?: MutationSymlinkPolicy;
-}, paths: {
+export declare function movePathNoReplaceNative(root: RootContext, params: Pick<RootMoveOptions, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">, paths: {
     sourcePath: string;
     sourceParentPath: string;
     targetPath: string;

package/dist/root-observed-path.d.ts

@@ -1,7 +1,6 @@
 import { type RootPathObservationKind, type RootPathObservationReceipt } from "./root-path.js";
 import { type RootContext } from "./root-context.js";
 export type PinnedObservedPath = {
-    rootReal: string;
     resolved: string;
     receipt?: RootPathObservationReceipt;
 };

package/dist/root-observed-path.js

@@ -63,7 +63,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
         // A receipt is emitted only for the straight traversal whose lexical and
         // canonical cursors stayed identical and inside the checked boundary.
         return {
-            rootReal: resolved.rootCanonicalPath,
             resolved: resolved.canonicalPath,
             receipt: observed.receipt,
         };
@@ -71,7 +70,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
     const relativeResolved = path.relative(resolved.rootCanonicalPath, resolved.canonicalPath);
     if (relativeResolved === "" || relativeResolved === ".") {
         return {
-            rootReal: resolved.rootCanonicalPath,
             resolved: resolved.canonicalPath,
         };
     }
@@ -87,7 +85,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
     if (!admittedCanonicalPath)
         throw outsideWorkspaceError();
     return {
-        rootReal: resolved.rootCanonicalPath,
         resolved: admittedCanonicalPath.path,
     };
 }

package/dist/root-path-observation.d.ts

@@ -7,14 +7,11 @@ export type RootPathObservationKind = "stat" | "directory";
 export type RootPathDirectoryObservationGuard = DirectoryObservationGuard | NativeDirectoryObservationGuard;
 export type RootPathTargetObservation = StatObservationReceipt | NativeDirectoryObservationGuard;
 /** An exact receipt owned by one stat/list operation. Never cache it. */
-export type RootPathObservationReceipt = {
-    kind: RootPathObservationKind;
-    rootGuard: DirectoryObservationGuard;
+export type RootPathObservationReceipt = Pick<RootPathObservationRequest & {
     directoryGuard: RootPathDirectoryObservationGuard;
-    directoryObserver?: NativeDirectoryObservationBackend;
     targetPath: string;
     target: RootPathTargetObservation;
-};
+}, "kind" | "rootGuard" | "directoryGuard" | "directoryObserver" | "targetPath" | "target">;
 /** A failed initial target lookup must not discard its already admitted parent. */
 export type RootPathParentObservationReceipt = Omit<RootPathObservationReceipt, "kind" | "target"> & {
     kind: "stat-parent";
@@ -24,16 +21,12 @@ export type RootPathObservationRequest = {
     rootGuard: DirectoryObservationGuard;
     directoryObserver?: NativeDirectoryObservationBackend;
 };
-export type RootPathTraversalObservation = {
+export type RootPathTraversalObservation = Omit<Partial<RootPathObservationReceipt> & {
     enabled: boolean;
     request: RootPathObservationRequest;
     targetIndex: number;
     directoryIndex: number;
-    directoryGuard?: RootPathDirectoryObservationGuard;
-    directoryObserver?: NativeDirectoryObservationBackend;
-    targetPath?: string;
-    target?: RootPathTargetObservation;
-};
+}, "kind" | "rootGuard">;
 export type RootPathObservedTraversalEntry = StatObservationReceipt | {
     stat: fs.Stats | BigIntStats;
     identity?: undefined;

package/dist/root-path.js

@@ -214,8 +214,8 @@ function finalizeLexicalResolution(context, kind) {
         rootPath: context.rootPath,
         rootCanonicalPath: context.rootCanonicalPath,
         relativePath: relativeInsideRoot(context.rootCanonicalPath, context.state.canonicalCursor),
-        exists: kind.exists,
-        kind: kind.kind,
+        exists: kind !== "missing",
+        kind,
     };
 }
 function applyResolvedSymlinkHop(context, linkCanonical) {
@@ -374,12 +374,9 @@ function traverseRootPath(params, { mode = "native", observation: observationOut
     const completeObservation = observation?.enabled === true && observation.directoryGuard !== undefined &&
         observation.targetPath === state.canonicalCursor && observation.target !== undefined;
     const kind = completeObservation
-        ? {
-            exists: true,
-            kind: isNativeDirectoryObservationGuard(observation.target)
-                ? "directory"
-                : toResolvedKind(observation.target.stat),
-        }
+        ? isNativeDirectoryObservationGuard(observation.target)
+            ? "directory"
+            : toResolvedKind(observation.target.stat)
         : getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
     if (completeObservation && observationOutput) {
         observationOutput.receipt = {
@@ -399,11 +396,11 @@ function getPathKindSync(absolutePath, preserveFinalSymlink) {
         const stat = preserveFinalSymlink
             ? fs.lstatSync(operationPath)
             : fs.statSync(operationPath);
-        return { exists: true, kind: toResolvedKind(stat) };
+        return toResolvedKind(stat);
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
-            return { exists: false, kind: "missing" };
+            return "missing";
         }
         throw error;
     }

package/dist/root-paths.d.ts

@@ -1,3 +1,4 @@
+import { type ResolvePathWithinRootParams } from "./path-scope-lexical.js";
 import { type DirectoryResult } from "./root-directory.js";
 export { resolvePathWithinRoot } from "./root-paths-lexical.js";
 export { ensureDirectoryWithinRoot } from "./root-directory.js";
@@ -44,12 +45,7 @@ export type PathScope = {
         mode?: number;
     }): Promise<DirectoryResult>;
 };
-export declare function resolveWritablePathWithinRoot(params: {
-    rootDir: string;
-    requestedPath: string;
-    scopeLabel: string;
-    defaultFileName?: string;
-}): Promise<{
+export declare function resolveWritablePathWithinRoot(params: ResolvePathWithinRootParams): Promise<{
     ok: true;
     path: string;
 } | {

package/dist/root-remove-identity.d.ts

@@ -1,9 +1,7 @@
 import type { BigIntStats } from "node:fs";
 type ExactDirectoryIdentity = Readonly<Pick<BigIntStats, "dev" | "ino">>;
-export type RemovalDirectoryAssertion = Readonly<{
+export type RemovalDirectoryAssertion = ExactDirectoryIdentity & Readonly<{
     path: string;
-    dev: bigint;
-    ino: bigint;
     numericDev?: number;
     numericIno?: number;
     platform: NodeJS.Platform;

package/dist/root-walk.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
+import { expandRelativePathWithHome } from "./root-context.js";
 import { resolveRootPath, ROOT_PATH_ALIAS_POLICIES } from "./root-path.js";
 import { createSuppressedError } from "./suppressed-error.js";
 function validateBudget(name, value) {
@@ -65,9 +66,10 @@ export async function* walkRoot(root, relativePath, options) {
         options.signal?.throwIfAborted();
         let listing;
         try {
+            const expandedDirectory = depth === 0 ? await expandRelativePathWithHome(directory) : directory;
             const skipChildSymlinks = depth > 0 && options.symlinkPolicy === "skip";
             const resolvedDirectory = await resolveRootPath({
-                absolutePath: path.resolve(root.rootReal, directory),
+                absolutePath: path.resolve(root.rootReal, expandedDirectory),
                 rootPath: root.rootReal,
                 rootCanonicalPath: root.rootReal,
                 boundaryLabel: "root walk",
@@ -87,7 +89,10 @@ export async function* walkRoot(root, relativePath, options) {
                 .relative(root.rootReal, resolvedDirectory.canonicalPath)
                 .split(path.sep)
                 .join(path.posix.sep);
-            listing = await root.list(listingDirectory, {
+            if (depth === 0 && expandedDirectory !== directory)
+                directory = listingDirectory;
+            // Resolved filesystem names are literal, not caller home-directory shorthand.
+            listing = await root.list(`./${listingDirectory}`, {
                 order: options.order ?? "sorted",
                 signal: options.signal,
                 snapshot: maxEntries === Number.POSITIVE_INFINITY,
@@ -139,7 +144,7 @@ export async function* walkRoot(root, relativePath, options) {
                     if (!resolved.exists) {
                         continue;
                     }
-                    const target = await root.stat(path.relative(root.rootReal, resolved.canonicalPath));
+                    const target = await root.stat(`./${path.relative(root.rootReal, resolved.canonicalPath)}`);
                     kind = target.isDirectory ? "directory" : target.isFile ? "file" : "other";
                     size = target.size;
                 }

package/dist/root-write-admission.js

@@ -14,7 +14,7 @@ import { mutationSymlinkResolution, } from "./root-symlink-policy.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { realpathSync } from "./realpath.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { assertPreparedRootWriteParentCurrent, } from "./root-write-complete-parent.js";
+import { assertPreparedRootWriteParentCurrent, writeSelectionChanged, } from "./root-write-complete-parent.js";
 export function createRootWriteSelectionForFd(selection, fd) {
     const stat = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }));
     return Object.freeze({
@@ -22,9 +22,6 @@ export function createRootWriteSelectionForFd(selection, fd) {
         identity: Object.freeze({ dev: stat.dev, ino: stat.ino }),
     });
 }
-function writeSelectionChanged(cause) {
-    return new FsSafeError("path-mismatch", "write target changed during operation", errorCauseOptions(cause));
-}
 function inspectRegularSelectionPath(pathname, expected, follow) {
     let observed;
     try {
@@ -204,7 +201,6 @@ export async function resolveGuardedWriteTargetInRoot(root, params) {
     const relativeParent = path.relative(resolvedPath.rootReal, path.dirname(resolvedPath.resolved));
     const prepared = await preparePinnedWriteMutationAdmission({
         rootReal: resolvedPath.rootReal,
-        rootWithSep: resolvedPath.rootWithSep,
         rootIdentity: root.rootIdentity,
         resolvedTargetPath: resolvedPath.resolved,
         originalPath: params.relativePath,
@@ -291,7 +287,6 @@ export async function resolvePinnedWriteTargetInRoot(root, relativePath, request
     if (policy) {
         ({ relativeParentPath, mutationAdmission } = await preparePinnedWriteMutationAdmission({
             rootReal,
-            rootWithSep,
             rootIdentity: root.rootIdentity,
             resolvedTargetPath: resolved,
             originalPath: relativePath,

package/dist/root-write-complete-parent.d.ts

@@ -1,5 +1,6 @@
 import type { BigIntStats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
 import type { RootContext } from "./root-context.js";
 import type { GuardedRootWriteTarget } from "./root-write-admission.js";
 type PreparedWriteTargetObservation = Readonly<{
@@ -36,6 +37,7 @@ export type SharedRootWriteTarget = Readonly<{
     mutationAdmission: GuardedRootWriteTarget["mutationAdmission"];
     preparedParent?: PreparedRootWriteParent;
 }>;
+export declare function writeSelectionChanged(cause?: unknown): FsSafeError;
 export declare function assertPreparedRootWriteParentCurrent(prepared: PreparedRootWriteParent, verifyTarget?: boolean): void;
 export declare function prepareSharedRootWriteTarget(root: RootContext, params: SharedRootWriteTargetParams): Promise<SharedRootWriteTarget>;
 export {};

package/dist/root-write-complete-parent.js

@@ -12,7 +12,7 @@ import { errorCauseOptions } from "./root-errors.js";
 import { canReuseParentWithMutationAssertion } from "./root-write-lock-binding.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-function writeSelectionChanged(cause) {
+export function writeSelectionChanged(cause) {
     return new FsSafeError("path-mismatch", "write target changed during operation", errorCauseOptions(cause));
 }
 function ordinarySharedWriteRoute(root, relativePath, operationTargetPath) {

package/dist/safe-path-segment.d.ts

@@ -7,5 +7,6 @@ export declare function assertNoDriveRelativePathSegments(value: string, label:
 export declare function trimHyphenEdges(value: string): string;
 export declare function isSafePathSegment(segment: string, options?: SafePathSegmentOptions): boolean;
 export declare function assertSafePathSegment(segment: string, options?: SafePathSegmentOptions): string;
+export declare function normalizeSafePathSegment(value: string): string;
 export declare function sanitizeSafePathSegment(value: string): string | undefined;
 export declare function assertSafePathPrefix(prefix: string, options?: SafePathSegmentOptions): string;

package/dist/safe-path-segment.js

@@ -1,3 +1,4 @@
+import { isWindowsReservedDeviceName } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 const SAFE_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
 const SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
@@ -34,6 +35,8 @@ export function isSafePathSegment(segment, options = {}) {
         !segment.includes("/") &&
         !segment.includes("\\") &&
         !segment.includes("\0") &&
+        // Segments are portable identifiers: CON.json and CON.<pid>.tmp name devices on Windows.
+        !isWindowsReservedDeviceName(segment) &&
         (options.allowDotPrefix === true || !segment.startsWith(".")) &&
         (options.allowDotPrefix === true
             ? SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN.test(segment)
@@ -47,13 +50,16 @@ export function assertSafePathSegment(segment, options = {}) {
     }
     return segment;
 }
-export function sanitizeSafePathSegment(value) {
+export function normalizeSafePathSegment(value) {
     const sanitized = value
         .trim()
         .replace(/[\\/]+/g, "-")
         .replace(/\0/g, "")
         .replace(/[^A-Za-z0-9._-]+/g, "-");
-    const trimmed = trimHyphenEdges(sanitized);
+    return trimHyphenEdges(sanitized);
+}
+export function sanitizeSafePathSegment(value) {
+    const trimmed = normalizeSafePathSegment(value);
     return isSafePathSegment(trimmed, { allowDotPrefix: true }) ? trimmed : undefined;
 }
 export function assertSafePathPrefix(prefix, options = {}) {

package/dist/secret-file.d.ts

@@ -13,7 +13,11 @@ type SecretFileWriteParams = {
     dirMode?: number;
     durable?: boolean;
 };
-export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParams, "content">): Promise<{
+type SecretFileCreateParams = Omit<SecretFileWriteParams, "durable"> & {
+    /** "file" requires file synchronization; directory synchronization remains best effort. */
+    durable?: boolean | "file";
+};
+export declare function prepareSecretFileWrite(params: Pick<SecretFileWriteParams, "rootDir" | "filePath" | "mode" | "dirMode">): Promise<{
     mode: number;
     rootGuard: AsyncDirectoryGuard<BigIntStats>;
     parentGuard: AsyncDirectoryGuard<BigIntStats>;
@@ -21,5 +25,5 @@ export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParam
     finalFilePath: string;
 }>;
 export declare function writeSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
-export declare function createSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
+export declare function createSecretFileAtomic(params: SecretFileCreateParams): Promise<void>;
 export {};

package/dist/secret-file.js

@@ -285,6 +285,7 @@ async function materializeSecretFileAtomic(params, createOnly) {
         mode,
         verifyPosixMode: true,
         sync: params.durable !== false,
+        strictFileSync: createOnly && params.durable === "file",
         overwrite: !createOnly,
         input: { kind: "buffer", data: typeof params.content === "string" ? params.content : Buffer.from(params.content) },
         rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },

package/dist/secure-file-windows.js

@@ -1,15 +1,11 @@
-import { FsSafeError } from "./errors.js";
 import { fileIdentityMismatchError } from "./strict-file-identity.js";
 import { getNativeBinding } from "./native.js";
 import { getFsSafeNativeConfig } from "./native-config.js";
 import { warnNativeFallback } from "./native-fallback-warning.js";
 import { inspectWindowsDescriptorCommand } from "./windows-security-command.js";
-import { validateSecureWindowsSecurityFacts } from "./windows-security-facts.js";
+import { unverified as permissionUnverified, validateSecureWindowsSecurityFacts } from "./windows-security-facts.js";
 const IDENTITY_RE = /^([0-9a-f]{8}):([0-9a-f]{16})$/;
 const TRUSTED_OWNER_CLASSES = new Set(["current-user", "system", "administrators"]);
-function permissionUnverified(message, cause) {
-    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }

package/dist/secure-file.js

@@ -202,7 +202,8 @@ function inspectOpenedPermissions(stat, platform) {
         groupReadable: isGroupReadable(bits),
     };
 }
-async function assertSecurePermissions(options, stat, realPath, identity, fd) {
+async function assertSecurePermissions(options, opened, fd) {
+    const { pathStat: stat, realPath, identity } = opened;
     if (options.permissions?.allowInsecure) {
         return undefined;
     }
@@ -282,7 +283,7 @@ export async function readSecureFile(options) {
     const opened = await openSecureHandle(options, maxBytes);
     try {
         assertTrustedDirs(options, opened.realPath);
-        const permissions = await assertSecurePermissions(options, opened.pathStat, opened.realPath, opened.identity, opened.handle.fd);
+        const permissions = await assertSecurePermissions(options, opened, opened.handle.fd);
         const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs, maxBytes);
         const finalIdentity = inspectFileIdentitySync(() => fsSync.fstatSync(opened.handle.fd, { bigint: true }), opened.identity);
         if (!finalIdentity.isFile()) {

package/dist/sidecar-lock-admission-parser.d.ts

@@ -1,7 +1,7 @@
 import type { Root } from "./root-impl.js";
 import type { HeldSidecarLock } from "./sidecar-lock-admission.js";
 import { readSidecarLockRawSnapshot, type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
-type SidecarAdmissionRunner = {
+export type SidecarAdmissionRunner = {
     hasToken(): boolean;
     run<T>(callback: () => T): T;
 };
@@ -39,4 +39,3 @@ export declare function observeHeldSidecarParser(params: {
     parserAccessor(): ((raw: string) => unknown) | undefined;
     isTransientDenial(error: unknown): boolean;
 }): Promise<HeldSidecarParserObservation>;
-export {};

package/dist/sidecar-lock-handle.d.ts

@@ -1,5 +1,4 @@
-import type { Root } from "./root-impl.js";
-import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+import type { HeldSidecarLock } from "./sidecar-lock-admission.js";
 import type { SidecarLockHandle } from "./sidecar-lock-types.js";
 export declare function stopSidecarLockMonitoring(held: {
     compromiseTimer?: NodeJS.Timeout;
@@ -14,12 +13,7 @@ export declare function createSidecarLockHandle(params: {
 }): SidecarLockHandle;
 export declare function createHeldSidecarLockHandle(params: {
     normalizedTargetPath: string;
-    held: {
-        lockPath: string;
-        snapshot: SidecarLockSnapshot;
-        lockRoot?: Root;
-        parsePayload?: (raw: string) => unknown;
-    };
+    held: Pick<HeldSidecarLock, "lockPath" | "snapshot" | "lockRoot" | "parsePayload">;
     release: (options?: {
         retry?: boolean;
     }) => Promise<unknown>;

package/dist/sidecar-lock-policy.d.ts

@@ -1,4 +1,4 @@
-import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
+import type { SidecarLockReclaimParams, SidecarLockRetryOptions } from "./sidecar-lock-types.js";
 export declare function validateSidecarLockRetryOptions(retry: SidecarLockRetryOptions): void;
 export declare function validateSidecarLockTimeoutMs(timeoutMs: number | undefined): void;
 export declare function validateSidecarLockStaleMs(staleMs: number | undefined): void;
@@ -11,9 +11,4 @@ export declare function sidecarLockRetryDelay(retry: SidecarLockRetryOptions, ti
 export declare const maxTransientLockDenials = 8;
 export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;
 export declare function sidecarLockPayloadCreatedAtMs(payload: unknown): number | null;
-export declare function defaultSidecarLockShouldReclaim(params: {
-    lockPath: string;
-    payload: unknown;
-    staleMs: number;
-    nowMs: number;
-}): Promise<boolean>;
+export declare function defaultSidecarLockShouldReclaim(params: Pick<SidecarLockReclaimParams, "lockPath" | "payload" | "staleMs" | "nowMs">): Promise<boolean>;

package/dist/sidecar-lock-stale-admission.d.ts

@@ -1,11 +1,7 @@
 import { type SidecarReclaimGuard } from "./sidecar-lock-reclaim.js";
-import { type SidecarLockParserState } from "./sidecar-lock-admission-parser.js";
+import { type SidecarLockParserState, type SidecarAdmissionRunner } from "./sidecar-lock-admission-parser.js";
 import type { Root } from "./root-impl.js";
 import type { SidecarLockAcquireOptions } from "./sidecar-lock-types.js";
-type SidecarAdmissionRunner = {
-    hasToken(): boolean;
-    run<T>(callback: () => T): T;
-};
 type StaleOptions = Pick<SidecarLockAcquireOptions<Record<string, unknown>>, "shouldReclaim" | "shouldRemoveStaleLock" | "staleRecovery">;
 export type SidecarLockStaleOptionsState = {
     shouldReclaimObserved?: boolean;

package/dist/sidecar-lock.js

@@ -1,6 +1,6 @@
 import fsSync from "node:fs";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.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";
@@ -61,7 +61,9 @@ function snapshotMatchesSync(lockPath, observed) {
             (typeof fsSync.constants.O_NONBLOCK === "number" ? fsSync.constants.O_NONBLOCK : 0);
         fd = fsSync.openSync(lockPath, openFlags);
         const openedStat = fsSync.fstatSync(fd);
-        if (!openedStat.isFile()) {
+        // 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 !== Buffer.byteLength(observed.raw)) {
@@ -69,7 +71,7 @@ function snapshotMatchesSync(lockPath, observed) {
         }
         const raw = fsSync.readFileSync(fd, "utf8");
         const afterStat = fsSync.lstatSync(lockPath);
-        if (!afterStat.isFile() || !sameFileIdentity(beforeStat, afterStat)) {
+        if (!afterStat.isFile() || !sameFileIdentityForCleanup(beforeStat, afterStat)) {
             return false;
         }
         return sidecarLockSnapshotMatches({ raw, payload: null, stat: afterStat }, observed);

package/dist/staged-symlink-types.d.ts

@@ -0,0 +1,49 @@
+import type { StagedFileReceipt } from "./staged-file-types.js";
+/** Caller-captured admission evidence, never a same-target ownership heuristic. */
+export type StagedSymlinkExpected = Readonly<{
+    dev: bigint;
+    ino: bigint;
+    uid: number;
+    gid: number;
+    ctimeNs: bigint;
+    target: string;
+}>;
+export type StagedSymlinkReceipt = StagedFileReceipt & Readonly<{
+    target: string;
+}>;
+export type PublishedSymlinkReceipt = Readonly<{
+    status: "published";
+    staged: StagedSymlinkReceipt;
+    basename: string;
+    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<{
+    temporaryBasename: string;
+    publication: StagedSymlinkPublication;
+    status: StagedSymlinkRemoval | "failed" | "not-needed";
+    resources: "closed" | "close-failed";
+}>;
+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/dist/staged-symlink-types.js

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