@openclaw/feishu 2026.9.8 → 2026.10.1-beta.1

package/dist/.setup/accounts-wRqItHug.mjs

@@ -1,206 +0,0 @@
-import { s as __exportAll } from "./doctor-contract-3XC0vbIw.mjs";
-import { DEFAULT_ACCOUNT_ID, createAccountListHelpers, hasConfiguredAccountValue, normalizeAccountId, normalizeOptionalAccountId } from "openclaw/plugin-sdk/account-resolution";
-import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
-import { coerceSecretRef } from "openclaw/plugin-sdk/provider-auth";
-import { canResolveEnvSecretRefInReadOnlyPath } from "openclaw/plugin-sdk/secret-ref-readonly";
-//#region extensions/feishu/src/accounts.ts
-var accounts_exports = /* @__PURE__ */ __exportAll({
-	FeishuSecretRefUnavailableError: () => FeishuSecretRefUnavailableError,
-	inspectFeishuCredentials: () => inspectFeishuCredentials,
-	listEnabledFeishuAccounts: () => listEnabledFeishuAccounts,
-	listFeishuAccountIds: () => listFeishuAccountIds,
-	mergeFeishuAccountConfig: () => mergeFeishuAccountConfig,
-	resolveDefaultFeishuAccountId: () => resolveDefaultFeishuAccountId,
-	resolveDefaultFeishuAccountSelection: () => resolveDefaultFeishuAccountSelection,
-	resolveFeishuAccount: () => resolveFeishuAccount,
-	resolveFeishuCredentials: () => resolveFeishuCredentials,
-	resolveFeishuRuntimeAccount: () => resolveFeishuRuntimeAccount
-});
-const { listAccountIds: listFeishuAccountIds, resolveDefaultAccountId: resolveDefaultFeishuAccountId, resolveAccountConfig: resolveMergedFeishuAccountConfig } = createAccountListHelpers("feishu", {
-	allowUnlistedDefaultAccount: true,
-	omitKeys: ["defaultAccount"],
-	nestedObjectKeys: ["tools"],
-	hasImplicitDefaultAccount: (cfg) => {
-		const feishu = cfg.channels?.feishu;
-		return hasConfiguredAccountValue(feishu?.appId) && hasConfiguredAccountValue(feishu?.appSecret);
-	}
-});
-function formatSecretRefLabel(ref) {
-	return `${ref.source}:${ref.provider}:${ref.id}`;
-}
-var FeishuSecretRefUnavailableError = class extends Error {
-	constructor(path, ref) {
-		super(`${path}: unresolved SecretRef "${formatSecretRefLabel(ref)}". Resolve this command against an active gateway runtime snapshot before reading it.`);
-		this.name = "FeishuSecretRefUnavailableError";
-		this.path = path;
-	}
-};
-function resolveFeishuSecretLike(params) {
-	const asString = normalizeOptionalString(params.value);
-	if (asString) return asString;
-	const ref = coerceSecretRef(params.value, params.cfg?.secrets?.defaults);
-	if (!ref) return;
-	if (params.mode === "inspect") {
-		if (ref.source === "env" && canResolveEnvSecretRefInReadOnlyPath({
-			cfg: params.cfg,
-			provider: ref.provider,
-			id: ref.id
-		})) return normalizeOptionalString(process.env[ref.id]);
-		return;
-	}
-	throw new FeishuSecretRefUnavailableError(params.path, ref);
-}
-function resolveFeishuBaseCredentials(cfg, mode, rootConfig) {
-	const appId = resolveFeishuSecretLike({
-		cfg: rootConfig,
-		value: cfg?.appId,
-		path: "channels.feishu.appId",
-		mode
-	});
-	const appSecret = resolveFeishuSecretLike({
-		cfg: rootConfig,
-		value: cfg?.appSecret,
-		path: "channels.feishu.appSecret",
-		mode
-	});
-	if (!appId || !appSecret) return null;
-	return {
-		appId,
-		appSecret,
-		domain: cfg?.domain?.replace(/^https:/i, "https:") ?? "feishu"
-	};
-}
-function resolveFeishuEventSecrets(cfg, mode, rootConfig) {
-	return {
-		encryptKey: (cfg?.connectionMode ?? "websocket") === "webhook" ? resolveFeishuSecretLike({
-			cfg: rootConfig,
-			value: cfg?.encryptKey,
-			path: "channels.feishu.encryptKey",
-			mode
-		}) : normalizeOptionalString(cfg?.encryptKey),
-		verificationToken: resolveFeishuSecretLike({
-			cfg: rootConfig,
-			value: cfg?.verificationToken,
-			path: "channels.feishu.verificationToken",
-			mode
-		})
-	};
-}
-/**
-* Resolve the default account selection and its source.
-*/
-function resolveDefaultFeishuAccountSelection(cfg) {
-	const preferred = normalizeOptionalAccountId((cfg.channels?.feishu)?.defaultAccount);
-	if (preferred) return {
-		accountId: preferred,
-		source: "explicit-default"
-	};
-	const ids = listFeishuAccountIds(cfg);
-	if (ids.includes(DEFAULT_ACCOUNT_ID)) return {
-		accountId: DEFAULT_ACCOUNT_ID,
-		source: "mapped-default"
-	};
-	return {
-		accountId: ids[0] ?? DEFAULT_ACCOUNT_ID,
-		source: "fallback"
-	};
-}
-/**
-* Merge top-level config with account-specific config.
-* Account-specific fields override top-level fields.
-*/
-function mergeFeishuAccountConfig(cfg, accountId) {
-	const feishuCfg = cfg.channels?.feishu;
-	const merged = resolveMergedFeishuAccountConfig(cfg, accountId);
-	const topTools = feishuCfg?.tools;
-	if (merged.tools === void 0 && topTools !== void 0) return {
-		...merged,
-		tools: topTools
-	};
-	if (topTools?.bitable === false) return {
-		...merged,
-		tools: {
-			...merged.tools,
-			bitable: false
-		}
-	};
-	return merged;
-}
-/**
-* Resolve Feishu credentials from a config.
-*/
-function resolveFeishuCredentials(cfg, options) {
-	const mode = options?.mode ?? "strict";
-	const base = resolveFeishuBaseCredentials(cfg, mode, options?.rootConfig);
-	if (!base) return null;
-	const eventSecrets = resolveFeishuEventSecrets(cfg, mode, options?.rootConfig);
-	return {
-		...base,
-		...eventSecrets
-	};
-}
-function inspectFeishuCredentials(cfg, rootConfig) {
-	return resolveFeishuCredentials(cfg, {
-		mode: "inspect",
-		rootConfig
-	});
-}
-function buildResolvedFeishuAccount(params) {
-	const hasExplicitAccountId = typeof params.accountId === "string" && params.accountId.trim() !== "";
-	const defaultSelection = hasExplicitAccountId ? null : resolveDefaultFeishuAccountSelection(params.cfg);
-	const accountId = hasExplicitAccountId ? normalizeAccountId(params.accountId) : defaultSelection?.accountId ?? DEFAULT_ACCOUNT_ID;
-	const selectionSource = hasExplicitAccountId ? "explicit" : defaultSelection?.source ?? "fallback";
-	const baseEnabled = (params.cfg.channels?.feishu)?.enabled !== false;
-	const merged = mergeFeishuAccountConfig(params.cfg, accountId);
-	const accountEnabled = merged.enabled !== false;
-	const enabled = baseEnabled && accountEnabled;
-	const baseCreds = resolveFeishuBaseCredentials(merged, params.baseMode, params.cfg);
-	const eventSecrets = resolveFeishuEventSecrets(merged, params.eventSecretMode, params.cfg);
-	const accountName = merged.name;
-	return {
-		accountId,
-		selectionSource,
-		enabled,
-		configured: Boolean(baseCreds),
-		name: typeof accountName === "string" ? accountName.trim() || void 0 : void 0,
-		appId: baseCreds?.appId,
-		appSecret: baseCreds?.appSecret,
-		encryptKey: eventSecrets.encryptKey,
-		verificationToken: eventSecrets.verificationToken,
-		domain: baseCreds?.domain ?? "feishu",
-		config: merged
-	};
-}
-/**
-* Resolve a read-only Feishu account snapshot for CLI/config surfaces.
-* Unresolved SecretRefs are treated as unavailable instead of throwing.
-*/
-function resolveFeishuAccount(params) {
-	return buildResolvedFeishuAccount({
-		...params,
-		baseMode: "inspect",
-		eventSecretMode: "inspect"
-	});
-}
-/**
-* Resolve a runtime Feishu account.
-* Required app credentials stay strict; event-only secrets can be required by callers.
-*/
-function resolveFeishuRuntimeAccount(params, options) {
-	return buildResolvedFeishuAccount({
-		...params,
-		baseMode: "strict",
-		eventSecretMode: options?.requireEventSecrets ? "strict" : "inspect"
-	});
-}
-/**
-* List all enabled and configured accounts.
-*/
-function listEnabledFeishuAccounts(cfg) {
-	return listFeishuAccountIds(cfg).map((accountId) => resolveFeishuAccount({
-		cfg,
-		accountId
-	})).filter((account) => account.enabled && account.configured);
-}
-//#endregion
-export { mergeFeishuAccountConfig as a, resolveFeishuRuntimeAccount as c, listFeishuAccountIds as i, inspectFeishuCredentials as n, resolveDefaultFeishuAccountId as o, listEnabledFeishuAccounts as r, resolveFeishuAccount as s, accounts_exports as t };

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

@@ -1,6 +0,0 @@
-import { type RootContext } from "./root-context.js";
-import type { NativeWatchBatch } from "./watch-native.js";
-import type { WatchSnapshot } from "./watch-scan.js";
-import type { WatchChange, WatchScope } from "./watch-types.js";
-/** Resolve native spelling aliases without treating case folding as identity. */
-export declare function admittedNativeChanges(root: RootContext, scopes: readonly WatchScope[], before: WatchSnapshot | undefined, after: WatchSnapshot, batch: NativeWatchBatch, signal: AbortSignal, limit: number): Promise<WatchChange[] | undefined>;

package/node_modules/@openclaw/fs-safe/dist/watch-alias.js

@@ -1,88 +0,0 @@
-import path from "node:path";
-import { FsSafeError } from "./errors.js";
-import { isNotFoundPathError } from "./path.js";
-import { assertRootIdentityCurrent, resolvePathInRoot } from "./root-context.js";
-import { createRootDirectoryObservationGuard, assertRootDirectoryObservationGuard } from "./root-directory-list.js";
-import { lookupRootDirectoryEntry } from "./root-directory-entry.js";
-import { excludedWatchPath, nativeChanges, scopedChanges } from "./watch-hints.js";
-/** Resolve native spelling aliases without treating case folding as identity. */
-export async function admittedNativeChanges(root, scopes, before, after, batch, signal, limit) {
-    if (!nativeChanges(scopes, before, batch, limit, after))
-        return undefined;
-    const result = new Map();
-    const candidates = new Map([...before?.targets ?? [], ...after.targets, ...after.directories]);
-    const add = (change) => {
-        if (!result.has(change.path) && result.size >= limit)
-            return false;
-        const prior = result.get(change.path);
-        result.set(change.path, prior?.type === "structural" ? prior : change);
-        return true;
-    };
-    for (const hint of batch.hints) {
-        signal.throwIfAborted();
-        const name = hint.name; // nativeChanges rejected unknown or non-literal names.
-        let parent = hint.directory;
-        const relative = parent ? path.join(parent, name) : name;
-        if (excludedWatchPath(before, relative) || excludedWatchPath(after, relative))
-            continue;
-        let guard;
-        let expected = after.directories.get(parent);
-        if (!expected) {
-            // Native recursion observes one Root handle and may report descendants of
-            // unselected/entry-only directories. Admit a parent alias by exact identity,
-            // not by lowercasing, and do not turn unselected descendants into events.
-            try {
-                const resolved = await resolvePathInRoot(root, parent ? "./" + parent : ".", { rejectSymlinks: true });
-                guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
-            }
-            catch (error) {
-                await assertRootIdentityCurrent(root);
-                if (isNotFoundPathError(error) || (error instanceof FsSafeError && ["not-found", "path-alias", "outside-workspace", "symlink", "not-file"].includes(error.code)))
-                    continue;
-                throw error;
-            }
-            const admitted = [...after.directories].find(([, identity]) => identity.dev === guard.stat.dev && identity.ino === guard.stat.ino);
-            if (!admitted)
-                continue;
-            [parent, expected] = admitted;
-        }
-        const candidate = parent ? path.join(parent, name) : name;
-        if (excludedWatchPath(before, candidate) || excludedWatchPath(after, candidate))
-            continue;
-        const selected = scopedChanges(scopes, { path: candidate,
-            type: hint.event === "change" && before?.entries.get(candidate)?.startsWith("file:") ? "content" : "structural" });
-        if (selected.length) {
-            for (const change of selected)
-                if (!add(change))
-                    return undefined;
-            continue;
-        }
-        if (!guard) {
-            const resolved = await resolvePathInRoot(root, parent ? "./" + parent : ".", { rejectSymlinks: true });
-            guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
-        }
-        if (guard.stat.dev !== expected.dev || guard.stat.ino !== expected.ino) {
-            throw new FsSafeError("path-mismatch", "watch hint parent changed during reconciliation");
-        }
-        const found = await lookupRootDirectoryEntry(root, guard, name);
-        signal.throwIfAborted();
-        // A missing unselected sibling is not evidence of lost selected detail.
-        // Previously observed selected deletions remain visible in the snapshot diff;
-        // an unseen, already-gone name has no identity proving a selected alias.
-        if (!found)
-            continue;
-        for (const [relative, identity] of candidates) {
-            if (!relative || (path.dirname(relative) === "." ? "" : path.dirname(relative)) !== parent)
-                continue;
-            if (identity.dev !== found.identity.dev || identity.ino !== found.identity.ino)
-                continue;
-            for (const change of scopedChanges(scopes, { path: relative, type: "structural" }))
-                if (!add(change))
-                    return undefined;
-        }
-        await assertRootDirectoryObservationGuard(root, guard);
-    }
-    await assertRootIdentityCurrent(root);
-    signal.throwIfAborted();
-    return [...result.values()];
-}

package/node_modules/@openclaw/fs-safe/docs/mutation-policy-proof.md

@@ -1,69 +0,0 @@
-# Hosted mutation-policy proof
-
-The `mutation policy public behavior proof` workflow builds the exact event-head
-package and host addon on Node 24 Linux, macOS, and Windows. Each case executes in
-a fresh process, uses a private temporary fixture, and emits only a bounded,
-canonical receipt. POSIX workers require both real and effective non-root UIDs.
-
-Receipt schema `fs-safe-mutation-policy-proof-v2` deliberately does not describe
-final directory emptiness as a mutation-dispatch count. Root replacement records
-the unchanged contents of the original and replacement parent; denied redirect
-records rejection and unchanged denied/displaced parents. The existing JS mkdir
-counters name their exact child or next component. None counts native syscalls
-or excludes transient mutations that leave no final trace.
-
-## Additional hosted cases
-
-Each POSIX write/create/copy worker, under both native-off and native-require,
-performs an eligible success control, an exact deeper-parent denial after an
-earlier parent is created, a denied redirect after preflight, and a stale-parent
-replacement at the public pre-mkdir authority boundary. Exact directory listings
-and sentinels verify that denied/current/displaced parents contain no prohibited
-child, target, or stage. Copy sources must retain their original bytes.
-
-Redirect injection uses the existing public `@openclaw/fs-safe/test-hooks` subpath
-from `dist`, not a mocked native binding. Only these isolated workers enable
-`NODE_ENV=test`. The exact target and single hook visit are required. The hook is
-after policy preflight but before parent admission; it must not be described as
-a post-parent-admission hook. Stale replacement instead uses the public authority
-callback after child-create policy admission, with an existing sentinel parent
-and a still-missing child. Both implementation files that enforce the following
-freshness check are hash-bound. No unchecked callback ordinal chooses a fault.
-
-Representative POSIX `Root.write` workers refuse authority before the first mkdir,
-after one parent has been created and before the next mkdir, before staging, and
-immediately before publication. Epoch selection uses actual fixture state. The
-publication refusal requires a real single-link, caller-owned mode-0600 stage
-containing the complete payload while the destination still contains its original
-sentinel. The same rejection object must escape, no callback may follow refusal,
-and the owned stage must be gone before fixture teardown.
-
-Windows workers exercise buffer `Root.write` through a stable final-file symlink,
-then refuse before stage creation for a missing destination, before publishing a
-complete stage to that still-missing destination, and before publishing to an
-existing symlink-selected destination. Missing destinations must remain absent at
-every authority callback and after refusal. The workers verify alias binding,
-destination preservation, complete single-link stages, and cleanup before fixture
-teardown. The default native-off and explicit
-`verify-content-with-lock` native-require configurations both select the existing
-Windows JS buffer writer. In native-require mode, the compatibility route loads
-the addon to publish its retained sidecar lock through `Root.create`; the payload
-writer remains JS. The receipt does not mislabel this as native payload
-publication or evidence that content-verification fallback or lock contention
-was exercised.
-
-## Bounds and interpretation
-
-The receipt remains below 32 KiB, each worker has a 15-second process timeout and
-4-KiB stdout limit, and the proof step has a six-minute outer timeout. Worker I/O
-and cleanup retain their existing deadlines. The canonical pending/failed receipt
-is preserved if setup, a worker, provenance validation, or emission fails.
-Source, built modules, the public test seam, harness helper, contract tests, and
-host addon are hashed and checked again after workers.
-
-These are deterministic representative observations, not an exhaustive race proof
-or syscall audit. Existing hash-bound internal tests remain complementary for
-other awaited-admission, receipt-refresh, and observation-failure interleavings.
-Windows root replacement and POSIX-specific pinned routes are not claimed on
-Windows. Hosted CI and exact artifact inspection are required before relying on
-new receipts; the proof supplies no performance release clearance.

package/node_modules/@openclaw/fs-safe/docs/private-file-store.md

@@ -1,68 +0,0 @@
-# Private file-store mode
-
-Private state is not a separate store family. Use `fileStore({ private: true })`
-when a directory holds credentials, tokens, auth profiles, or other private
-JSON/text state.
-
-```ts
-import { fileStore } from "@openclaw/fs-safe/store";
-
-const store = fileStore({ rootDir: "/var/lib/app", private: true });
-
-await store.writeJson("state.json", state);
-const loaded = await store.readJsonIfExists<State>("state.json");
-```
-
-## Behavior
-
-- Writes create parent directories at `0o700` and files at `0o600` unless you
-  pass stricter `dirMode` / `mode` options.
-- Async private-mode writes route through the secret-file atomic path, which refuses
-  symlink parent components and re-asserts mode after rename. Existing directories
-  must already have the requested mode; writes do not repair their permissions.
-  New-directory initialization requires guarded descriptor authority and may
-  fail closed under restrictive platform/umask combinations; see the
-  [secret-directory policy](secret-file.md#parameters).
-- Locked JSON mutations prepare private directories before acquiring their
-  sidecar and bind the lock to the admitted parent identity. Lock normalization
-  is read-only: a deleted or replaced admitted parent is rejected, not recreated.
-  The writer still revalidates directory admission afterward; reads do not create
-  directories.
-- `readText()` and `readJson()` are strict and throw on missing files.
-- `readTextIfExists()` and `readJsonIfExists()` return `null` on missing files.
-- `write()`, `writeText()`, `writeJson()`, `writeStream()`, and `copyIn()` all
-  keep the same root-relative `FileStore` shape.
-
-## Sync writes
-
-Use `fileStoreSync({ private: true })` for boot paths or sync-only integration
-points:
-
-```ts
-import { fileStoreSync } from "@openclaw/fs-safe/store";
-
-fileStoreSync({ rootDir: "/var/lib/app", private: true }).writeJson("config.json", config);
-```
-
-The sync store intentionally exposes a smaller surface: path resolution,
-lenient reads, and atomic text/JSON writes.
-
-Sync directory modes remain repair-compatible on POSIX, but repairs are applied
-only through an exact-identity, no-follow directory descriptor after the store
-root and admitted parent name are revalidated. Root or component swaps fail
-without chmodding the substituted directory. Matching modes take the no-open
-fast path. Windows uses its existing `mkdir` mode request plus exact directory
-identity checks and never falls back to pathname chmod.
-
-On Linux, Node offers no portable search-only descriptor that can also be
-`fchmod`ed. A mismatched directory without effective read access—including one
-created under an owner-read-removing umask—fails closed with
-`permission-unverified`. Supported macOS x64/arm64 hosts additionally try
-`O_SEARCH` when the directory remains searchable; an inaccessible directory
-still fails rather than restoring the pathname race.
-
-## See also
-
-- [`fileStore`](file-store.md) — full store API.
-- [Secret files](secret-file.md) — standalone credential file reads and writes.
-- [JSON files](json.md) — strict/lenient JSON helpers without a bound store.

package/node_modules/@openclaw/fs-safe/docs/test-hooks.md

@@ -1,110 +0,0 @@
----
-title: Test hooks
-description: "Internal-only injection hooks used by the fs-safe test suite. Active only when NODE_ENV=test or VITEST=true."
----
-
-# `@openclaw/fs-safe/test-hooks`
-
-Internal injection points the `fs-safe` test suite uses to deterministically reproduce open/lstat races. They are exposed as a public subpath so downstream test suites can reuse the same harness, but they are **not** part of the supported runtime API.
-
-```ts
-import {
-  getFsSafeTestHooks,
-  __setFsSafeTestHooksForTest,
-  type FsSafeTestHooks,
-} from "@openclaw/fs-safe/test-hooks";
-```
-
-## When the hooks are active
-
-Hooks are only honored when one of the following is true:
-
-- `process.env.NODE_ENV === "test"`
-- `process.env.VITEST === "true"`
-
-Calling `__setFsSafeTestHooksForTest(hooks)` outside of those environments throws. `getFsSafeTestHooks()` returns `undefined` when no hooks are registered, regardless of the environment.
-
-## Shape
-
-```ts
-type FsSafeTestHooks = {
-  afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
-  beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
-  afterOpen?: (filePath: string, handle: FileHandle) => Promise<void> | void;
-  afterOpenedPathIdentityCheck?: (filePath: string, handle: FileHandle) => Promise<void> | void;
-  afterRootReadPathResolution?: (filePath: string) => Promise<void> | void;
-  beforeRootReadFinalFence?: (filePath: string, handle: FileHandle) => Promise<void> | void;
-  afterRootReadFinalPathIdentityCheck?: (filePath: string, handle: FileHandle) => void;
-  beforeArchiveOutputMutation?: (operation: "mkdir" | "chmod", targetPath: string) => Promise<void> | void;
-  beforeFileStorePruneDescend?: (dirPath: string) => Promise<void> | void;
-  beforeFileStoreSyncPrivateWrite?: (filePath: string) => void;
-  beforeRootFallbackMutation?: (operation: "mkdir" | "move" | "remove", targetPath: string) => Promise<void> | void;
-  beforeRootStatObservation?: (targetPath: string) => Promise<void> | void;
-  beforeRootStatInitialObservation?: (targetPath: string) => Promise<void> | void;
-  beforeRootListObservation?: (directoryPath: string, withFileTypes: boolean) => Promise<void> | void;
-  afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
-  beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
-  beforeSidecarLockSnapshotOpen?: (lockPath: string) => Promise<void> | void;
-  beforeTrashMove?: (targetPath: string, destPath: string) => void;
-  afterPublishTargetCreated?: (method, targetPath, identity) => Promise<void> | void;
-  beforePublishDirectorySync?: (method, targetPath, identity) => Promise<void> | void;
-};
-```
-
-| Hook | Fires when |
-|---|---|
-| `afterPreOpenLstat` | A pre-open `lstat` has just resolved. Use this to swap a path between validation and open. |
-| `beforeOpen` | The library is about to call `open(path, flags)`. Use this to inject a TOCTOU window. |
-| `afterOpen` | An open just succeeded. Use this to mutate state before the post-open identity check runs. |
-| `afterOpenedPathIdentityCheck` | A standalone local-file or absolute copy-source descriptor matches its pathname and the generic opened-path resolver is about to run. Root reads use their final admission hooks instead. |
-| `afterRootReadPathResolution` | A Root read path was resolved and has not yet entered local-file open admission. |
-| `beforeRootReadFinalFence` | A Root read descriptor passed pre-open/descriptor identity and hardlink checks and is about to enter its single final root/path/canonical-path/root admission fence. |
-| `afterRootReadFinalPathIdentityCheck` | The final pathname-to-descriptor comparison passed and the second root check has not run. This hook is synchronous-only. |
-| `beforeArchiveOutputMutation` | Archive staging is about to create a directory or apply a mode. |
-| `beforeFileStorePruneDescend` | File-store pruning is about to descend into a directory. |
-| `beforeFileStoreSyncPrivateWrite` | A synchronous private-store write is about to mutate its target. |
-| `beforeRootFallbackMutation` | A guarded JS root fallback is about to mkdir, move, or remove. |
-| `beforeRootStatObservation` | `Root.stat()` admitted its exact target and parent and is about to collect returned metadata. |
-| `beforeRootStatInitialObservation` | `Root.stat()` admitted its exact parent and is about to inspect the target for the first time. |
-| `beforeRootListObservation` | `Root.list()` admitted its exact selected directory and is about to collect names and optional metadata. |
-| `afterPinnedWriteFallbackRename` | A fallback rename committed and post-commit identity checks have not run yet. |
-| `beforeSiblingTempWrite` | A sibling temp file exists and its writer is about to run. |
-| `beforeSidecarLockSnapshotOpen` | A sidecar lock was inspected and is about to be opened for a bounded snapshot read. |
-| `beforeTrashMove` | Trash handling is about to move the target. |
-| `afterPublishTargetCreated` | Exclusive publication created its target and final fences have not run yet. |
-| `beforePublishDirectorySync` | Publication verified the target and is about to sync its parent directory. |
-
-Hooks typed `Promise<void> | void` may be sync or async and are awaited.
-Hooks used by synchronous code paths are typed `void` and must not return a
-promise.
-
-## Usage
-
-```ts
-import { afterEach, beforeEach } from "vitest";
-import { __setFsSafeTestHooksForTest } from "@openclaw/fs-safe/test-hooks";
-
-beforeEach(() => {
-  __setFsSafeTestHooksForTest({
-    beforeOpen: async (filePath) => {
-      // swap a victim file with a symlink right before fs-safe opens it
-      await replaceWithSymlink(filePath);
-    },
-  });
-});
-
-afterEach(() => {
-  __setFsSafeTestHooksForTest(undefined);
-});
-```
-
-Always clear the hooks in `afterEach` so a stuck hook does not leak across tests.
-
-## Stability
-
-The shape can grow new optional fields between minor versions. Treat the surface as test-only and do not rely on it from production code.
-
-## Related pages
-
-- [Testing](testing.md) — broader notes on testing against `fs-safe`.
-- [Security model](security-model.md) — the races these hooks help reproduce.