Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(storage): 用文件锁替代本地存储 PID 检查 (#5159)
Qin Haojief316f2756916
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 482a1c17a..c78ea01f0 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -1035,7 +1035,7 @@ Storage configuration for context data, including file storage (RAGFS) and vecto| Parameter | Type | Description | Default ||-----------|------|-------------|---------|| `workspace` | str | Local data storage path (main configuration) | "./data" |-| `skip_process_lock` | bool | Whether to skip the startup process-lock check for `storage.workspace`. When enabled, OpenViking will not check or create the `.openviking.pid` lock file. | `false` |+| `skip_process_lock` | bool | Skip the exclusive `.openviking.lock` file lock on `storage.workspace` for embedded vector backends (`local`, `cuvs`). Other backends do not acquire this lock. Skipping it does not make embedded vector storage safe for multiple processes. | `false` || `agfs` | object | RAGFS (Rust-based AGFS) configuration | {} || `vectordb` | object | Vector database storage configuration | {} |diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.mdindex 3fde1fefb..e9f90cb10 100644--- a/docs/en/guides/03-deployment.md+++ b/docs/en/guides/03-deployment.md@@ -281,10 +281,16 @@ After startup, you can access:### Multi-instance notes+With an embedded vector backend (`local` or `cuvs`), OpenViking holds an exclusive OS file lock on `storage.workspace` by default. The `.openviking.lock` file remains on disk; its presence does not mean a server is running. The OS releases the lock when the server closes it or the process terminates. Do not manually delete a running server's lock file.++Remote vector backends (`http`, `volcengine`, `vikingdb`) do not acquire this workspace lock, including when files are stored on a shared NAS. They do not require `storage.skip_process_lock=true`. Placing an embedded vector database on NAS does not make it safe to share between processes.++For embedded vector backends, when upgrading from a version that uses `.openviking.pid`, stop all older servers using the workspace before starting the new version. The new version does not use leftover PIDs to determine ownership; the two locking protocols cannot be mixed.+For multi-instance deployments, prefer these settings:- Set `server.temp_upload.default_mode` to `"shared"` so uploaded temporary files can be consumed by a different replica.-- Only set `storage.skip_process_lock` to `true` when multiple instances intentionally share the same `storage.workspace`. When enabled, OpenViking will no longer check or create `.openviking.pid`.+- Use a remote vector backend for shared storage. The existing `storage.skip_process_lock` option only disables the embedded-backend startup guard; it does not add multi-process support to embedded vector storage.- For QueueFS, prefer an explicit per-instance local SQLite path via `storage.agfs.queuefs.db_path`. If usage audit is enabled, prefer an explicit per-instance local SQLite path via `server.observability.usage_audit.sqlite_path` instead of mixing these files into a shared workspace volume.Example:@@ -297,12 +303,15 @@ Example:}},"storage": {- "skip_process_lock": true+ "vectordb": {+ "backend": "http",+ "url": "http://vector-db:5000"+ }}}```-This example only applies when multiple instances intentionally share the same `workspace`. If each instance has its own local `workspace`, do not enable `skip_process_lock`.+This example uses a remote HTTP vector service. Replace its URL with your deployment's vector-service address, or configure a `volcengine` or `vikingdb` backend.Example with explicit local SQLite paths for QueueFS and usage audit:@@ -319,7 +328,10 @@ Example with explicit local SQLite paths for QueueFS and usage audit:}},"storage": {- "skip_process_lock": true,+ "vectordb": {+ "backend": "http",+ "url": "http://vector-db:5000"+ },"agfs": {"queuefs": {"db_path": "/var/lib/openviking-local/queue.db"diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex a7d1f389e..f68e2d09f 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -1003,7 +1003,7 @@ Glob 引擎配置,用于路径模式匹配。这些设置为服务端配置,| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|| `workspace` | str | 本地数据存储路径(主要配置) | "./data" |-| `skip_process_lock` | bool | 是否跳过 `storage.workspace` 的启动进程锁检查。启用后,OpenViking 不会检查或创建 `.openviking.pid` 锁文件。 | `false` |+| `skip_process_lock` | bool | 是否跳过本地向量后端(`local`、`cuvs`)对 `storage.workspace` 的 `.openviking.lock` 独占文件锁。其他后端不会获取此锁。跳过检查不代表本地向量存储支持多进程共享。 | `false` || `agfs` | object | RAGFS(Rust 实现的 AGFS)配置 | {} || `vectordb` | object | 向量库存储配置 | {} |diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.mdindex 9dff06169..8dbe4253b 100644--- a/docs/zh/guides/03-deployment.md+++ b/docs/zh/guides/03-deployment.md@@ -279,10 +279,16 @@ docker compose up -d### 多实例部署注意事项+使用本地向量后端(`local` 或 `cuvs`)时,OpenViking 默认通过操作系统文件锁独占 `storage.workspace`。`.openviking.lock` 文件会保留在磁盘上,文件存在不代表服务正在运行;正常关闭或进程终止后,操作系统会释放锁。不要手动删除运行中服务的锁文件。++远程向量后端(`http`、`volcengine`、`vikingdb`)不会获取此 workspace 锁,包括文件存放在共享 NAS 上的情况,无需设置 `storage.skip_process_lock=true`。把本地向量数据库放在 NAS 上,并不会使它支持多进程共享。++使用本地向量后端从 `.openviking.pid` 旧版本升级时,必须先停止所有使用该 workspace 的旧版服务,再启动新版。新版不再根据遗留 PID 判断目录是否被占用,新旧锁机制不支持混用。+多实例部署时,通常建议注意这几项配置:- 把 `server.temp_upload.default_mode` 设为 `"shared"`,这样临时上传文件可以被其他副本消费。-- 只有在多个实例明确共享同一个 `storage.workspace` 时,才考虑把 `storage.skip_process_lock` 设为 `true`。启用后,OpenViking 不会再检查或创建 `.openviking.pid`。+- 共享存储应使用远程向量后端。保留的 `storage.skip_process_lock` 开关只关闭本地后端的启动保护,不会使本地向量存储支持多进程共享。- 对 QueueFS,建议通过 `storage.agfs.queuefs.db_path` 显式指定实例本地的 SQLite 路径。如果启用了 usage audit,建议通过 `server.observability.usage_audit.sqlite_path` 显式指定实例本地的 SQLite 路径,不要默认和共享 workspace 卷混用。示例:@@ -295,12 +301,15 @@ docker compose up -d}},"storage": {- "skip_process_lock": true+ "vectordb": {+ "backend": "http",+ "url": "http://vector-db:5000"+ }}}```-这个示例只适用于多个实例明确共享同一个 `workspace` 的场景。如果每个实例都有自己的本地 `workspace`,不要开启 `skip_process_lock`。+这个示例使用远程 HTTP 向量服务。请将 URL 替换为实际的向量服务地址,或配置 `volcengine`、`vikingdb` 后端。如果你还需要为 QueueFS 和 usage audit 显式指定本地 SQLite 路径,可以参考:@@ -317,7 +326,10 @@ docker compose up -d}},"storage": {- "skip_process_lock": true,+ "vectordb": {+ "backend": "http",+ "url": "http://vector-db:5000"+ },"agfs": {"queuefs": {"db_path": "/var/lib/openviking-local/queue.db"diff --git a/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.md b/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.mdindex 275e4c92e..abec61d5d 100644--- a/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.md+++ b/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.md@@ -94,7 +94,7 @@ Work top-down; fix the first ✗ and rerun before chasing the next.| `recall is pinned to the legacy /search/recall endpoint` | One 4xx mentioning "mode" pins recall for 6h | `rm ~/.openviking/state/context-face.json`. || `no hook log … debug is on but no hook has run` | Hooks are not being spawned at all | Registration/enablement/node problem, not a server problem. || `ov.conf has a top-level '<harness>' block` / `server.url is rejected` | Plugin-only keys in the server's own config — a top-level block named after any harness (`claude_code`, `codex`, `cursor`, `trae`, `trae_cn`, `zcode`, `opencode`, `dsh`, `pi`) plus `server.url`; the server refuses to start at its next restart (`Unknown config field` / `Extra inputs are not permitted`) | Move them to ovcli.conf (`plugin.<harness>`, `url`) and delete them from ov.conf. Ignore only if this ov.conf never starts a server. |-| `nothing listens on port … — the server is not running` | Server down or never started; a stale `.openviking.pid` means it died | Start it (`openviking-server`; first time `openviking-server init`) in a terminal and read the startup output. Ask before restarting a server the user runs. |+| `nothing listens on port … — the server is not running` | Server down or never started; the presence of `.openviking.lock` does not indicate whether the server is running | Start it (`openviking-server`; first time `openviking-server init`) in a terminal and read the startup output. Ask before restarting a server the user runs. || `/ready: embedding → error …` | The running server cannot call its embedding provider: recall searches nothing, commits extract nothing | Fix `embedding.*` (api_key/api_base/model) in ov.conf and restart; `openviking-server doctor` prints the provider's reply. || `/ready: vectordb → …` / `/ready: agfs → …` | Storage broken: disk full, two servers on one workspace, corrupted index | Server log; stop the duplicate; free disk. || `server is still initializing (503 /ready)` | First start downloads a local embedding model, or init is slow | Wait and rerun; if it never finishes, the server log. |diff --git a/examples/claude-code-memory-plugin/skills/ov-memory-doctor/reference.md b/examples/claude-code-memory-plugin/skills/ov-memory-doctor/reference.mdindex 6b33ca6a7..d363dcaf2 100644--- a/examples/claude-code-memory-plugin/skills/ov-memory-doctor/reference.md+++ b/examples/claude-code-memory-plugin/skills/ov-memory-doctor/reference.md@@ -174,7 +174,7 @@ Startup failures (printed by the server; exit 1 unless noted):| `Unknown config field '…' in OpenVikingConfig` / `Extra inputs are not permitted` | Unknown key — including a top-level block named after any harness (`claude_code`, `codex`, `cursor`, `trae`, `trae_cn`, `zcode`, `opencode`, `dsh`, `pi`) and `server.url`, which only the plugins read || `SECURITY: server.auth_mode='dev' requires server.host to be localhost` | Dev mode (no `auth_mode`, no `root_api_key`) on a non-loopback bind || `Invalid server.root_api_key: empty string is not allowed` | `""` instead of `null` |-| `Another OpenViking process (PID n) is already using the data directory` | Two servers on one workspace (exit 3, `Application startup failed. Exiting.`) |+| `Another OpenViking process is already using the data directory` | Two servers on one workspace (exit 3, `Application startup failed. Exiting.`) || `EmbeddingRebuildRequiredError` / `embedding dimension (…) does not match current configuration` | Embedding model changed on an existing workspace (exit 3) || `[Errno 48] / [Errno 98] Address already in use` | Port taken — `lsof -nP -iTCP:1933 -sTCP:LISTEN` || `FATAL: AUTHENTICATION HEALTH CHECK FAILED` | OIDC/LDAP backend unreachable |diff --git a/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md b/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.mdindex c2276e994..1386c3825 100644--- a/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md+++ b/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md@@ -101,7 +101,7 @@ Work top-down; fix the first ✗ and rerun before chasing the next.| `no session has ever captured a turn` / idle sessions piling up | Stop hook runs but writes fail, or commits fail | Fix the Connection findings; state files are kept and replay when the server is back. || `MCP proxy last started against <other url>` | The proxy is a long-lived process; a changed url only takes effect after restart | Restart Codex. || `ov.conf has a top-level '<harness>' block` / `server.url is rejected` | Plugin-only keys in the server's own config — a top-level block named after any harness (`claude_code`, `codex`, `cursor`, `trae`, `trae_cn`, `zcode`, `opencode`, `dsh`, `pi`) plus `server.url`; the server refuses to start at its next restart (`Unknown config field` / `Extra inputs are not permitted`) | Move them to ovcli.conf (`plugin.<harness>`, `url`) and delete them from ov.conf. Ignore only if this ov.conf never starts a server. |-| `nothing listens on port … — the server is not running` | Server down or never started; a stale `.openviking.pid` means it died | Start it (`openviking-server`; first time `openviking-server init`) in a terminal and read the startup output. Ask before restarting a server the user runs. |+| `nothing listens on port … — the server is not running` | Server down or never started; the presence of `.openviking.lock` does not indicate whether the server is running | Start it (`openviking-server`; first time `openviking-server init`) in a terminal and read the startup output. Ask before restarting a server the user runs. || `/ready: embedding → error …` | The running server cannot call its embedding provider: recall searches nothing, commits extract nothing | Fix `embedding.*` (api_key/api_base/model) in ov.conf and restart; `openviking-server doctor` prints the provider's reply. || `/ready: vectordb → …` / `/ready: agfs → …` | Storage broken: disk full, two servers on one workspace, corrupted index | Server log; stop the duplicate; free disk. || `server is still initializing (503 /ready)` | First start downloads a local embedding model, or init is slow | Wait and rerun; if it never finishes, the server log. |diff --git a/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md b/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.mdindex c929cb9b4..1ce749321 100644--- a/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md+++ b/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md@@ -167,7 +167,7 @@ Startup failures (printed by the server; exit 1 unless noted):| `Unknown config field '…' in OpenVikingConfig` / `Extra inputs are not permitted` | Unknown key — including a top-level block named after any harness (`claude_code`, `codex`, `cursor`, `trae`, `trae_cn`, `zcode`, `opencode`, `dsh`, `pi`) and `server.url`, which only the plugins read || `SECURITY: server.auth_mode='dev' requires server.host to be localhost` | Dev mode (no `auth_mode`, no `root_api_key`) on a non-loopback bind || `Invalid server.root_api_key: empty string is not allowed` | `""` instead of `null` |-| `Another OpenViking process (PID n) is already using the data directory` | Two servers on one workspace (exit 3, `Application startup failed. Exiting.`) |+| `Another OpenViking process is already using the data directory` | Two servers on one workspace (exit 3, `Application startup failed. Exiting.`) || `EmbeddingRebuildRequiredError` / `embedding dimension (…) does not match current configuration` | Embedding model changed on an existing workspace (exit 3) || `[Errno 48] / [Errno 98] Address already in use` | Port taken — `lsof -nP -iTCP:1933 -sTCP:LISTEN` || `FATAL: AUTHENTICATION HEALTH CHECK FAILED` | OIDC/LDAP backend unreachable |diff --git a/openviking/service/core.py b/openviking/service/core.pyindex 413ec0047..455833441 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -129,8 +129,7 @@ class OpenVikingService:# Stateself._initialized = False- # Acquire the data-dir lock before encryption bootstrap so first-run root-key creation is- # serialized with storage initialization across processes.+ # Acquire local-storage exclusivity before encryption and storage initialization.self._ensure_data_dir_lock_acquired()# Resolve encryption config (root_key) BEFORE building the agfs client, so the binding@@ -227,19 +226,23 @@ class OpenVikingService:)def _ensure_data_dir_lock_acquired(self) -> None:- """Acquire the process-level data directory lock once for this service instance."""+ """Protect embedded vector storage from concurrent processes in one workspace."""if self._data_dir_lock_acquired:return- # contention (see https://github.com/volcengine/OpenViking/issues/473).- if not self._config.storage.skip_process_lock:+ storage = self._config.storage+ if storage.vectordb.backend not in {"local", "cuvs"}:+ return++ if not storage.skip_process_lock:from openviking.utils.process_lock import acquire_data_dir_lock- self._data_dir_lock_path = acquire_data_dir_lock(self._config.storage.workspace)+ self._data_dir_lock_path = acquire_data_dir_lock(storage.workspace)else:logger.warning(- "Skipping workspace process lock for '%s'; multi-process access may corrupt data",- self._config.storage.workspace,+ "Skipping workspace process lock for '%s'; multi-process access may corrupt "+ "embedded vector storage",+ storage.workspace,)self._data_dir_lock_acquired = True@@ -610,9 +613,8 @@ class OpenVikingService:if get_service_or_none() is self:set_service(None)- # The PID lock protects every live workspace resource above. If any- # cleanup step failed or was cancelled, keep the lock so another- # process cannot enter while this service may still own storage state.+ # Keep embedded storage exclusive until cleanup succeeds. If cleanup+ # fails or is cancelled, this service may still own live storage state.self._release_data_dir_lock()logger.info("OpenVikingService closed")diff --git a/openviking/utils/process_lock.py b/openviking/utils/process_lock.pyindex 288f1c677..ee8ebe052 100644--- a/openviking/utils/process_lock.py+++ b/openviking/utils/process_lock.py@@ -1,12 +1,12 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: AGPL-3.0-"""PID-based advisory lock for data directory exclusivity.+"""OS-backed file lock for exclusive access to a workspace.-Prevents multiple OpenViking processes from contending for the same data-directory, which causes silent failures in AGFS and VectorDB.+The file stays on disk; only the held OS lock indicates ownership. All instances+must use this protocol: stop older PID-lock-based servers before upgrading."""-import atexit+import errnoimport osimport sysimport threading@@ -15,171 +15,89 @@ from openviking_cli.utils import get_loggerlogger = get_logger(__name__)-LOCK_FILENAME = ".openviking.pid"+LOCK_FILENAME = ".openviking.lock"-# A PID file protects the whole process, while multiple service instances may-# legitimately share that process and workspace. Keep process-local ownership-# counts so closing one service cannot expose another live service to a second-# process. The file remains the cross-process source of truth.+# Multiple services in one process can share a workspace. Hold one descriptor+# until the last service closes; process exit also closes it, including crashes._LOCK_STATE_GUARD = threading.Lock()-_LOCK_REF_COUNTS: dict[str, int] = {}-_ATEXIT_REGISTERED: set[str] = set()+_LOCKS: dict[str, tuple[int, int]] = {} # normalized path -> (descriptor, references)class DataDirectoryLocked(RuntimeError):- """Raised when another OpenViking process holds the data directory lock."""+ """Raised when another OpenViking process holds the workspace lock."""-def _normalize_lock_path(lock_path: str) -> str:- """Return one process-local identity for aliases of the same PID file."""- return os.path.realpath(os.path.abspath(lock_path))---def _read_pid_file(lock_path: str) -> int:- """Read PID from lock file. Returns 0 if unreadable."""- try:- with open(lock_path) as f:- return int(f.read().strip())- except (OSError, ValueError):- return 0---def _is_pid_alive(pid: int) -> bool:- """Check whether a process with the given PID is still running."""- if pid <= 0:- return False- if sys.platform == "win32":- import _winapi-- # Unlike POSIX, os.kill(pid, 0) sends CTRL_C_EVENT on Windows.- try:- handle = _winapi.OpenProcess(_winapi.SYNCHRONIZE, False, pid)- except OSError as exc:- # ERROR_INVALID_PARAMETER confirms there is no such PID. Access- # denied and other query failures must not discard a live lock.- return exc.winerror != 87- try:- return _winapi.WaitForSingleObject(handle, 0) != _winapi.WAIT_OBJECT_0- except OSError:- return True- finally:- _winapi.CloseHandle(handle)-- try:- os.kill(pid, 0)- except ProcessLookupError:- return False- except PermissionError:- # Process exists but we can't signal it.- pass-- # PID exists, but on Linux PIDs are recycled. Verify this is actually- # an OpenViking process by checking /proc/{pid}/cmdline to avoid false- # positives from PID reuse (see issue #1088).- if sys.platform.startswith("linux"):- try:- with open(f"/proc/{pid}/cmdline", "rb") as f:- cmdline = f.read().decode("utf-8", errors="replace").lower()- if "openviking" not in cmdline and "openviking-server" not in cmdline:- logger.info(- "PID %d is alive but not an OpenViking process (cmdline: %.100s). "- "Assuming stale lock from recycled PID.",- pid,- cmdline[:100],- )- return False- except OSError:- # /proc not available or process exited between kill and open- pass-- return True---def _remove_owned_lock(lock_path: str, owner_pid: int) -> None:- """Remove *lock_path* only while it still belongs to *owner_pid*."""- try:- if os.path.isfile(lock_path) and _read_pid_file(lock_path) == owner_pid:- os.remove(lock_path)- except OSError:- pass---def release_data_dir_lock(lock_path: str, *, pid: int | None = None) -> None:- """Release a data-directory lock when it is still owned by *pid*.-- The ownership check keeps a delayed cleanup callback from removing a lock- that a replacement process has already acquired.- """- owner_pid = os.getpid() if pid is None else pid- normalized_path = _normalize_lock_path(lock_path)-+def release_data_dir_lock(lock_path: str) -> None:+ """Release this process's lock after its last workspace user has closed."""+ lock_path = os.path.realpath(lock_path)with _LOCK_STATE_GUARD:- holder_count = _LOCK_REF_COUNTS.get(normalized_path, 0)- if holder_count > 1:- _LOCK_REF_COUNTS[normalized_path] = holder_count - 1+ held = _LOCKS.get(lock_path)+ if held is None:+ return+ descriptor, references = held+ if references > 1:+ _LOCKS[lock_path] = (descriptor, references - 1)return- if holder_count == 1:- _LOCK_REF_COUNTS.pop(normalized_path, None)- # A zero count is retained as a compatibility path for callers that- # acquired the lock before this module state was initialized/reloaded.- _remove_owned_lock(normalized_path, owner_pid)+ del _LOCKS[lock_path]+ try:+ if sys.platform == "win32":+ import msvcrt+ msvcrt.locking(descriptor, msvcrt.LK_UNLCK, 1)+ finally:+ os.close(descriptor)+ # Never unlink the file: contenders must all lock the same file, even+ # when one has opened it before the previous owner releases its lock.-def acquire_data_dir_lock(data_dir: str) -> str:- """Acquire an advisory PID lock on *data_dir*.- Returns the path to the lock file on success.+def acquire_data_dir_lock(data_dir: str) -> str:+ """Hold an exclusive, non-blocking OS lock until release or process exit.- Raises ``DataDirectoryLocked`` if another live process already holds the- lock, with a message that explains the situation and suggests HTTP mode.- Raises ``OSError`` when the PID file cannot be created or updated; callers- must never continue as if an exclusivity lock had been acquired.+ Returns the lock path. Contention raises ``DataDirectoryLocked``; filesystem+ or unsupported-lock errors propagate instead of allowing an unlocked start."""- normalized_data_dir = os.path.realpath(os.path.abspath(data_dir))- lock_path = _normalize_lock_path(os.path.join(normalized_data_dir, LOCK_FILENAME))- my_pid = os.getpid()-+ data_dir = os.path.realpath(data_dir)+ lock_path = os.path.realpath(os.path.join(data_dir, LOCK_FILENAME))with _LOCK_STATE_GUARD:- existing_pid = _read_pid_file(lock_path)- if existing_pid and existing_pid != my_pid and _is_pid_alive(existing_pid):- raise DataDirectoryLocked(- f"Another OpenViking process (PID {existing_pid}) is already using "- f"the data directory '{data_dir}'. Running multiple OpenViking "- f"instances on the same data directory causes silent storage "- f"contention and data corruption.\n\n"- f"To fix this, use one of these approaches:\n"- f" 1. Start a single OpenViking server and connect clients over HTTP "- f"(recommended for multi-session hosts)\n"- f" 2. Use separate data directories for each instance\n"- f" 3. Stop the other process (PID {existing_pid}) first"- )-- # Write our PID (overwrites stale lock from a dead process). Reentrant- # acquisitions still refresh the file in case an external actor- # removed it while this process remained alive.+ held = _LOCKS.get(lock_path)+ if held is not None:+ descriptor, references = held+ _LOCKS[lock_path] = (descriptor, references + 1)+ return lock_path++ os.makedirs(data_dir, exist_ok=True)+ # os.open creates a non-inheritable descriptor, so exec/spawn children+ # cannot keep the workspace locked after this server exits.+ descriptor = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)try:- os.makedirs(normalized_data_dir, exist_ok=True)- with open(lock_path, "w") as f:- f.write(str(my_pid))- except OSError as exc:- logger.warning("Could not write PID lock %s: %s", lock_path, exc)- raise-- _LOCK_REF_COUNTS[lock_path] = _LOCK_REF_COUNTS.get(lock_path, 0) + 1+ if sys.platform == "win32":+ import msvcrt- # One force-cleanup callback per path is enough. At interpreter exit- # every in-process holder is terminal, so refcounts must not prevent- # cleanup.- if lock_path not in _ATEXIT_REGISTERED:+ # Windows can lock a byte beyond EOF; no file content is needed.+ msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1)+ else:+ import fcntl- def _cleanup(*_args: object) -> None:- with _LOCK_STATE_GUARD:- _LOCK_REF_COUNTS.pop(lock_path, None)- _remove_owned_lock(lock_path, my_pid)+ fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)+ except OSError as exc:+ os.close(descriptor)+ if exc.errno not in (errno.EACCES, errno.EAGAIN):+ raise+ raise DataDirectoryLocked(+ f"Another OpenViking process is already using the data directory '{data_dir}'. "+ "Running multiple OpenViking instances on the same data directory causes "+ "storage contention and data corruption.\n\n"+ "To fix this, use one of these approaches:\n"+ " 1. Start a single OpenViking server and connect clients over HTTP\n"+ " 2. Use separate data directories for each instance\n"+ " 3. Stop the other OpenViking process first"+ ) from exc+ except BaseException:+ os.close(descriptor)+ raise- atexit.register(_cleanup)- _ATEXIT_REGISTERED.add(lock_path)+ _LOCKS[lock_path] = (descriptor, 1)- logger.debug("Acquired data directory lock: %s (PID %d)", lock_path, my_pid)+ logger.debug("Acquired data directory lock: %s", lock_path)return lock_pathdiff --git a/openviking_cli/utils/config/storage_config.py b/openviking_cli/utils/config/storage_config.pyindex 2c10cf20e..4f447e1f4 100644--- a/openviking_cli/utils/config/storage_config.py+++ b/openviking_cli/utils/config/storage_config.py@@ -26,8 +26,9 @@ class StorageConfig(BaseModel):skip_process_lock: bool = Field(default=False,description=(- "Skip the startup PID lock for the workspace directory. Use only when you "- "explicitly accept the risk of multi-process storage contention."+ "Skip the workspace file lock for embedded vector backends ('local', 'cuvs'). "+ "Other backends do not acquire this lock. Use only when you explicitly accept "+ "the risk of multi-process contention on embedded vector storage."),)diff --git a/tests/misc/test_process_lock.py b/tests/misc/test_process_lock.pydeleted file mode 100644index 8fbbf5a36..000000000--- a/tests/misc/test_process_lock.py+++ /dev/null@@ -1,61 +0,0 @@-"""Tests for PID-based advisory lock on data directories."""--import os-import tempfile--from openviking.utils.process_lock import (- LOCK_FILENAME,- DataDirectoryLocked,- acquire_data_dir_lock,-)---class TestProcessLock:- def test_acquires_lock_on_empty_dir(self):- with tempfile.TemporaryDirectory() as tmpdir:- lock_path = acquire_data_dir_lock(tmpdir)- assert os.path.isfile(lock_path)- with open(lock_path) as f:- assert int(f.read().strip()) == os.getpid()-- def test_same_pid_can_reacquire(self):- with tempfile.TemporaryDirectory() as tmpdir:- acquire_data_dir_lock(tmpdir)- # Should not raise when same process re-acquires.- acquire_data_dir_lock(tmpdir)-- def test_stale_lock_is_replaced(self):- with tempfile.TemporaryDirectory() as tmpdir:- lock_path = os.path.join(tmpdir, LOCK_FILENAME)- # Write a PID that does not exist (very high number).- with open(lock_path, "w") as f:- f.write("999999999")- # Should succeed because the PID is dead.- acquire_data_dir_lock(tmpdir)- with open(lock_path) as f:- assert int(f.read().strip()) == os.getpid()-- def test_live_pid_blocks_acquisition(self):- with tempfile.TemporaryDirectory() as tmpdir:- lock_path = os.path.join(tmpdir, LOCK_FILENAME)- # PID 1 (init/launchd) is always alive.- with open(lock_path, "w") as f:- f.write("1")- try:- acquire_data_dir_lock(tmpdir)- raise AssertionError("Should have raised DataDirectoryLocked")- except DataDirectoryLocked as exc:- assert "PID 1" in str(exc)- assert "connect clients over HTTP" in str(exc)-- def test_error_message_includes_remediation(self):- with tempfile.TemporaryDirectory() as tmpdir:- lock_path = os.path.join(tmpdir, LOCK_FILENAME)- with open(lock_path, "w") as f:- f.write("1")- try:- acquire_data_dir_lock(tmpdir)- except DataDirectoryLocked as exc:- msg = str(exc)- assert "OpenViking server" in msg- assert "separate data directories" in msgdiff --git a/tests/unit/service/test_core_encryption_startup.py b/tests/unit/service/test_core_encryption_startup.pyindex 539200de8..0d0ba20c5 100644--- a/tests/unit/service/test_core_encryption_startup.py+++ b/tests/unit/service/test_core_encryption_startup.py@@ -11,6 +11,7 @@ import pytestfrom openviking.service.core import OpenVikingServicefrom openviking.utils.agfs_utils import RagfsBindingConfig+from openviking.utils.process_lock import LOCK_FILENAMEclass _FakeCacheConfig:@@ -100,19 +101,24 @@ async def test_build_ragfs_binding_config_works_inside_running_event_loop(monkeyassert isinstance(service._encryptor, _FakeEncryptor)-def test_ensure_data_dir_lock_acquired_once(monkeypatch, tmp_path):[email protected]("backend", ["local", "cuvs"])+def test_ensure_data_dir_lock_acquired_once(monkeypatch, tmp_path, backend):"""Acquire the data-dir lock once before startup encryption bootstrap."""calls = []def _acquire(path: str) -> str:calls.append(path)- return str(tmp_path / ".openviking.pid")+ return str(tmp_path / LOCK_FILENAME)monkeypatch.setattr("openviking.utils.process_lock.acquire_data_dir_lock", _acquire)service = OpenVikingService.__new__(OpenVikingService)service._config = SimpleNamespace(- storage=SimpleNamespace(workspace=str(tmp_path), skip_process_lock=False)+ storage=SimpleNamespace(+ workspace=str(tmp_path),+ skip_process_lock=False,+ vectordb=SimpleNamespace(backend=backend),+ ))service._data_dir_lock_acquired = Falseservice._data_dir_lock_path = None@@ -121,36 +127,41 @@ def test_ensure_data_dir_lock_acquired_once(monkeypatch, tmp_path):service._ensure_data_dir_lock_acquired()assert calls == [str(tmp_path)]- assert service._data_dir_lock_path == str(tmp_path / ".openviking.pid")+ assert service._data_dir_lock_path == str(tmp_path / LOCK_FILENAME)-def test_ensure_data_dir_lock_respects_skip_process_lock(monkeypatch, tmp_path):- """Skip lock acquisition entirely when storage.skip_process_lock is enabled."""-- calls = []+ "backend,skip_process_lock",+ [("local", True), ("cuvs", True), ("http", False), ("volcengine", False), ("vikingdb", False)],+)+def test_ensure_data_dir_lock_skips_shared_backends_and_explicit_opt_out(+ monkeypatch, tmp_path, backend, skip_process_lock+):+ """Shared backends and explicit opt-out must never attempt a workspace lock."""def _acquire(path: str) -> str:- calls.append(path)- return str(tmp_path / ".openviking.pid")+ pytest.fail("Shared backends and explicit opt-out must not access the workspace lock")monkeypatch.setattr("openviking.utils.process_lock.acquire_data_dir_lock", _acquire)service = OpenVikingService.__new__(OpenVikingService)service._config = SimpleNamespace(- storage=SimpleNamespace(workspace=str(tmp_path), skip_process_lock=True)+ storage=SimpleNamespace(+ workspace=str(tmp_path),+ skip_process_lock=skip_process_lock,+ vectordb=SimpleNamespace(backend=backend),+ ))service._data_dir_lock_acquired = Falseservice._data_dir_lock_path = Noneservice._ensure_data_dir_lock_acquired()- assert calls == []- assert service._data_dir_lock_acquired is Trueassert service._data_dir_lock_path is Nonedef test_release_data_dir_lock_resets_service_state(monkeypatch, tmp_path):calls = []- lock_path = str(tmp_path / ".openviking.pid")+ lock_path = str(tmp_path / LOCK_FILENAME)monkeypatch.setattr("openviking.utils.process_lock.release_data_dir_lock", calls.append)service = OpenVikingService.__new__(OpenVikingService)service._data_dir_lock_acquired = Truediff --git a/tests/unit/test_process_lock.py b/tests/unit/test_process_lock.pyindex 42848815e..bd4700a14 100644--- a/tests/unit/test_process_lock.py+++ b/tests/unit/test_process_lock.py@@ -1,13 +1,13 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: AGPL-3.0-"""Tests for PID-based process lock utility."""+"""Workspace exclusivity and recovery contracts, exercised with real processes."""+import errno+import multiprocessingimport os+import subprocessimport sys-from pathlib import Path-from types import SimpleNamespace-from unittest.mock import Mockimport pytest@@ -15,390 +15,156 @@ import openviking.utils.process_lock as process_lock_modulefrom openviking.utils.process_lock import (LOCK_FILENAME,DataDirectoryLocked,- _is_pid_alive,- _read_pid_file,acquire_data_dir_lock,release_data_dir_lock,)-class TestReadPidFile:- """Test _read_pid_file function."""-- def test_read_valid_pid(self, tmp_path: Path):- """Test reading a valid PID from file."""- lock_file = tmp_path / LOCK_FILENAME- lock_file.write_text("12345")-- pid = _read_pid_file(str(lock_file))- assert pid == 12345-- def test_read_nonexistent_file(self, tmp_path: Path):- """Test reading from nonexistent file returns 0."""- lock_file = tmp_path / "nonexistent.pid"-- pid = _read_pid_file(str(lock_file))- assert pid == 0-- def test_read_invalid_pid(self, tmp_path: Path):- """Test reading invalid PID returns 0."""- lock_file = tmp_path / LOCK_FILENAME- lock_file.write_text("not_a_number")-- pid = _read_pid_file(str(lock_file))- assert pid == 0-- def test_read_empty_file(self, tmp_path: Path):- """Test reading empty file returns 0."""- lock_file = tmp_path / LOCK_FILENAME- lock_file.write_text("")-- pid = _read_pid_file(str(lock_file))- assert pid == 0-- def test_read_pid_with_whitespace(self, tmp_path: Path):- """Test reading PID with leading/trailing whitespace."""- lock_file = tmp_path / LOCK_FILENAME- lock_file.write_text(" 12345 \n")-- pid = _read_pid_file(str(lock_file))- assert pid == 12345-- def test_read_pid_with_newline(self, tmp_path: Path):- """Test reading PID with newline."""- lock_file = tmp_path / LOCK_FILENAME- lock_file.write_text("12345\n")-- pid = _read_pid_file(str(lock_file))- assert pid == 12345---class TestIsPidAlive:- """Test _is_pid_alive function."""-- def test_current_pid_is_alive(self):- """Test that current process PID is detected as alive."""- current_pid = os.getpid()- assert _is_pid_alive(current_pid) is True-- def test_pid_1_is_alive(self):- """Test that PID 1 (init) is typically alive."""- # PID 1 is usually init process on Linux- assert _is_pid_alive(1) is True-- def test_nonexistent_pid_not_alive(self):- """Test that nonexistent PID is not alive."""- # Use a very high PID that's unlikely to exist- assert _is_pid_alive(999999) is False-- def test_pid_zero_not_alive(self):- """Test that PID 0 is not alive."""- assert _is_pid_alive(0) is False-- def test_negative_pid_not_alive(self):- """Test that negative PID is not alive."""- assert _is_pid_alive(-1) is False-- @pytest.mark.parametrize(- "open_error, wait_result, wait_error, expected",+def _probe_lock(workspace):+ return subprocess.run([- (None, 258, None, True), # WAIT_TIMEOUT: still running- (None, 0, None, False), # WAIT_OBJECT_0: exited- (87, None, None, False), # no such PID- (5, None, None, True), # access denied- (6, None, None, True), # unknown query failure- (None, None, OSError("wait failed"), True),+ sys.executable,+ "-c",+ "import sys\n"+ "from openviking.utils.process_lock import (\n"+ " acquire_data_dir_lock, release_data_dir_lock, DataDirectoryLocked)\n"+ "try:\n"+ " path = acquire_data_dir_lock(sys.argv[1])\n"+ "except DataDirectoryLocked as exc:\n"+ " print(exc)\n"+ " sys.exit(2)\n"+ "release_data_dir_lock(path)\n",+ str(workspace),],+ capture_output=True,+ text=True,+ timeout=20,)- def test_windows_probe_never_signals(- self, monkeypatch, open_error, wait_result, wait_error, expected- ):- api = SimpleNamespace(- SYNCHRONIZE=0x100000,- WAIT_OBJECT_0=0,- OpenProcess=Mock(return_value=123),- WaitForSingleObject=Mock(return_value=wait_result, side_effect=wait_error),- CloseHandle=Mock(),- )- if open_error is not None:- error = OSError("open failed")- error.winerror = open_error- api.OpenProcess.side_effect = error- with monkeypatch.context() as patch:- patch.setattr(process_lock_module.sys, "platform", "win32")- patch.setitem(sys.modules, "_winapi", api)- patch.setattr(os, "kill", Mock(side_effect=AssertionError("must not signal")))- assert _is_pid_alive(os.getpid()) is expected- api.OpenProcess.assert_called_once_with(api.SYNCHRONIZE, False, os.getpid())- if open_error is None:- api.WaitForSingleObject.assert_called_once_with(123, 0)- api.CloseHandle.assert_called_once_with(123)- else:- api.WaitForSingleObject.assert_not_called()- api.CloseHandle.assert_not_called()-- @pytest.mark.skipif(sys.platform != "win32", reason="requires native Windows APIs")- def test_windows_native_current_pid_never_signals(self, monkeypatch):- monkeypatch.setattr(os, "kill", Mock(side_effect=AssertionError("must not signal")))- assert _is_pid_alive(os.getpid()) is True-- def test_non_windows_system_error_bubbles_up(self, monkeypatch):- """Non-Windows should not downgrade unexpected SystemError values."""- def _raise_system_error(_pid: int, _sig: int) -> None:- raise SystemError("unexpected failure")- monkeypatch.setattr(process_lock_module.sys, "platform", "linux")- monkeypatch.setattr(process_lock_module.os, "kill", _raise_system_error)-- with pytest.raises(SystemError):- _is_pid_alive(12345)+def _contend_for_lock(workspace, start, release, results):+ start.wait(timeout=20)+ try:+ lock_path = acquire_data_dir_lock(workspace)+ except DataDirectoryLocked:+ results.put((os.getpid(), "locked"))+ return+ try:+ results.put((os.getpid(), "acquired"))+ if not release.poll(30):+ raise TimeoutError("lock owner was not released")+ release.recv()+ finally:+ release.close()+ release_data_dir_lock(lock_path)class TestAcquireDataDirLock:- """Test acquire_data_dir_lock function."""-- def test_acquire_creates_lock_file(self, tmp_path: Path):- """Test acquiring lock creates lock file."""- lock_path = acquire_data_dir_lock(str(tmp_path))-- assert lock_path == str(tmp_path / LOCK_FILENAME)- assert (tmp_path / LOCK_FILENAME).exists()-- def test_acquire_writes_current_pid(self, tmp_path: Path):- """Test lock file contains current PID."""- acquire_data_dir_lock(str(tmp_path))- my_pid = os.getpid()-- stored_pid = int((tmp_path / LOCK_FILENAME).read_text().strip())- assert stored_pid == my_pid-- def test_acquire_same_pid_succeeds(self, tmp_path: Path):- """Test acquiring lock with same PID succeeds."""- my_pid = os.getpid()- (tmp_path / LOCK_FILENAME).write_text(str(my_pid))-- # Should succeed since it's our own PID- lock_path = acquire_data_dir_lock(str(tmp_path))- assert lock_path == str(tmp_path / LOCK_FILENAME)-- def test_acquire_with_stale_lock_succeeds(self, tmp_path: Path):- """Test acquiring lock with stale (dead process) lock succeeds."""- # Write a PID that doesn't exist- (tmp_path / LOCK_FILENAME).write_text("999999")-- lock_path = acquire_data_dir_lock(str(tmp_path))- assert lock_path == str(tmp_path / LOCK_FILENAME)-- def test_acquire_with_live_process_raises(self, tmp_path: Path):- """Test acquiring lock with live process raises DataDirectoryLocked."""- # Use PID 1 (init) which is typically alive- (tmp_path / LOCK_FILENAME).write_text("1")-- with pytest.raises(DataDirectoryLocked) as exc_info:- acquire_data_dir_lock(str(tmp_path))-- assert "Another OpenViking process" in str(exc_info.value)- assert "PID 1" in str(exc_info.value)-- def test_acquire_creates_directory(self, tmp_path: Path):- """Test acquiring lock creates directory if it doesn't exist."""- new_dir = tmp_path / "new_subdir"-- acquire_data_dir_lock(str(new_dir))- assert new_dir.exists()- assert (new_dir / LOCK_FILENAME).exists()-- def test_acquire_write_failure_is_not_reported_as_success(self, tmp_path: Path, monkeypatch):- """A failed PID-file write must fail closed instead of claiming exclusivity."""-- def _deny_makedirs(*_args, **_kwargs) -> None:- raise PermissionError("read-only workspace")-- workspace = tmp_path / "missing"- monkeypatch.setattr(process_lock_module.os, "makedirs", _deny_makedirs)-- with pytest.raises(PermissionError, match="read-only workspace"):- acquire_data_dir_lock(str(workspace))-- assert not (workspace / LOCK_FILENAME).exists()-- def test_error_message_suggests_http_server(self, tmp_path: Path):- """Test error message suggests using one HTTP server."""- (tmp_path / LOCK_FILENAME).write_text("1")-- with pytest.raises(DataDirectoryLocked) as exc_info:- acquire_data_dir_lock(str(tmp_path))-- error_msg = str(exc_info.value)- assert "OpenViking server" in error_msg- assert "connect clients over HTTP" in error_msg-- def test_error_message_shows_pid(self, tmp_path: Path):- """Test error message shows conflicting PID."""- (tmp_path / LOCK_FILENAME).write_text("1")-- with pytest.raises(DataDirectoryLocked) as exc_info:- acquire_data_dir_lock(str(tmp_path))-- error_msg = str(exc_info.value)- assert "PID 1" in error_msg+ @pytest.mark.parametrize("failure", ["open", "lock"])+ def test_filesystem_errors_fail_acquisition(self, tmp_path, monkeypatch, failure):+ """Filesystem permission and unsupported-lock errors must fail startup."""+ error = PermissionError(errno.EACCES, "read-only workspace")+ if failure == "open":+ target, name = process_lock_module.os, "open"+ else:+ error = OSError(errno.ENOTSUP, "locking unsupported")+ if sys.platform == "win32":+ import msvcrt- def test_error_message_shows_directory(self, tmp_path: Path):- """Test error message shows directory path."""- (tmp_path / LOCK_FILENAME).write_text("1")+ target, name = msvcrt, "locking"+ else:+ import fcntl- with pytest.raises(DataDirectoryLocked) as exc_info:- acquire_data_dir_lock(str(tmp_path))+ target, name = fcntl, "flock"- error_msg = str(exc_info.value)- assert str(tmp_path) in error_msg+ def fail(*args, **kwargs):+ raise error- @pytest.mark.parametrize("winerror", [87, 5])- def test_windows_lock_reclaimed_only_for_missing_pid(self, tmp_path, monkeypatch, winerror):- lock_file = tmp_path / LOCK_FILENAME- lock_file.write_text("12345")- error = OSError("process query failed")- error.winerror = winerror- api = SimpleNamespace(SYNCHRONIZE=0x100000, OpenProcess=Mock(side_effect=error))with monkeypatch.context() as patch:- patch.setattr(process_lock_module.sys, "platform", "win32")- patch.setitem(sys.modules, "_winapi", api)- patch.setattr(os, "kill", Mock(side_effect=AssertionError("must not signal")))- if winerror == 87:+ patch.setattr(target, name, fail)+ with pytest.raises(OSError) as raised:acquire_data_dir_lock(str(tmp_path))- assert int(lock_file.read_text()) == os.getpid()- else:- with pytest.raises(DataDirectoryLocked):- acquire_data_dir_lock(str(tmp_path))- assert lock_file.read_text() == "12345"---class TestAcquireDataDirLockEdgeCases:- """Test edge cases for acquire_data_dir_lock."""-- def test_acquire_nested_directory(self, tmp_path: Path):- """Test acquiring lock in nested directory."""- nested = tmp_path / "a" / "b" / "c"-- acquire_data_dir_lock(str(nested))- assert nested.exists()- assert (nested / LOCK_FILENAME).exists()-- def test_acquire_overwrites_stale_lock(self, tmp_path: Path):- """Test that acquiring overwrites stale lock with current PID."""- my_pid = os.getpid()- (tmp_path / LOCK_FILENAME).write_text("999999")+ assert raised.value is error- acquire_data_dir_lock(str(tmp_path))-- stored_pid = int((tmp_path / LOCK_FILENAME).read_text().strip())- assert stored_pid == my_pid-- def test_lock_filename_constant(self):- """Test LOCK_FILENAME constant is correct."""- assert LOCK_FILENAME == ".openviking.pid"-- def test_acquire_with_pathlib_path(self, tmp_path: Path):- """Test acquiring with pathlib.Path instead of string."""+ # Failed acquisition must not leave a process-local owner behind.lock_path = acquire_data_dir_lock(str(tmp_path))- assert lock_path == str(tmp_path / LOCK_FILENAME)-- def test_acquire_permissions_on_readonly_parent(self, tmp_path: Path):- """Test handling when parent directory is read-only."""- # This test may not work on all systems- # Just verify it doesn't crash- lock_path = acquire_data_dir_lock(str(tmp_path))- assert lock_path.endswith(LOCK_FILENAME)+ try:+ result = _probe_lock(tmp_path)+ assert result.returncode == 2, result.stderr+ finally:+ release_data_dir_lock(lock_path)+ assert _probe_lock(tmp_path).returncode == 0class TestReleaseDataDirLock:- """Test explicit process-lock release used by service shutdown."""-- def test_release_removes_owned_lock(self, tmp_path: Path):- lock_path = acquire_data_dir_lock(str(tmp_path))-- release_data_dir_lock(lock_path)-- assert not (tmp_path / LOCK_FILENAME).exists()-- def test_release_preserves_replacement_owner(self, tmp_path: Path):- lock_path = acquire_data_dir_lock(str(tmp_path))- (tmp_path / LOCK_FILENAME).write_text("999999")-- release_data_dir_lock(lock_path)-- assert (tmp_path / LOCK_FILENAME).read_text() == "999999"-- def test_release_is_idempotent(self, tmp_path: Path):- lock_path = acquire_data_dir_lock(str(tmp_path))-- release_data_dir_lock(lock_path)- release_data_dir_lock(lock_path)-- assert not (tmp_path / LOCK_FILENAME).exists()-- def test_release_keeps_lock_until_last_same_process_holder(self, tmp_path: Path):- lock_path = acquire_data_dir_lock(str(tmp_path))- assert acquire_data_dir_lock(str(tmp_path)) == lock_path-- release_data_dir_lock(lock_path)-- assert (tmp_path / LOCK_FILENAME).read_text() == str(os.getpid())-- release_data_dir_lock(lock_path)-- assert not (tmp_path / LOCK_FILENAME).exists()-- def test_symlink_alias_shares_the_same_process_local_refcount(self, tmp_path: Path):- """Workspace aliases must not let one service release another's PID lock."""+ @pytest.mark.parametrize("use_alias", [False, True])+ def test_symlink_alias_shares_the_same_process_local_refcount(self, tmp_path, use_alias):workspace = tmp_path / "workspace"workspace.mkdir()- alias = tmp_path / "workspace-alias"- try:- alias.symlink_to(workspace, target_is_directory=True)- except OSError as exc:- pytest.skip(f"directory symlinks are unavailable: {exc}")+ alias = workspace+ if use_alias:+ alias = tmp_path / "alias"+ try:+ alias.symlink_to(workspace, target_is_directory=True)+ except OSError as exc:+ pytest.skip(f"directory symlinks are unavailable: {exc}")lock_path = acquire_data_dir_lock(str(workspace))- assert acquire_data_dir_lock(str(alias)) == lock_path-- release_data_dir_lock(lock_path)- assert (workspace / LOCK_FILENAME).read_text() == str(os.getpid())+ try:+ assert acquire_data_dir_lock(str(alias)) == lock_path+ release_data_dir_lock(lock_path)+ result = _probe_lock(workspace)+ assert result.returncode == 2, result.stderr+ assert "connect clients over HTTP" in result.stdout+ assert str(workspace) in result.stdout+ finally:+ release_data_dir_lock(lock_path)+ release_data_dir_lock(lock_path)- release_data_dir_lock(lock_path)- assert not (workspace / LOCK_FILENAME).exists()+ assert (workspace / LOCK_FILENAME).exists()+ assert _probe_lock(workspace).returncode == 0class TestProcessLockIntegration:- """Integration tests for process lock."""-- def test_multiple_acquires_same_process(self, tmp_path: Path):- """Test multiple acquires from same process."""- lock_path1 = acquire_data_dir_lock(str(tmp_path))- lock_path2 = acquire_data_dir_lock(str(tmp_path))-- assert lock_path1 == lock_path2-- def test_lock_file_cleanup_on_exit_simulation(self, tmp_path: Path):- """Test that lock file would be cleaned up on exit."""- acquire_data_dir_lock(str(tmp_path))- assert (tmp_path / LOCK_FILENAME).exists()-- # Note: Actual cleanup happens via atexit, which we can't easily test- # in unit tests without process termination-- def test_reentrant_lock_same_pid(self, tmp_path: Path):- """Test that same PID can re-acquire lock."""- my_pid = os.getpid()-- # First acquire- lock_path1 = acquire_data_dir_lock(str(tmp_path))-- # Write PID again- (tmp_path / LOCK_FILENAME).write_text(str(my_pid))-- # Second acquire should succeed- lock_path2 = acquire_data_dir_lock(str(tmp_path))-- assert lock_path1 == lock_path2+ @pytest.mark.parametrize("crash", [False, True])+ def test_concurrent_start_and_exit_release_lock(self, tmp_path, crash):+ """Only one simultaneous starter enters; graceful exit and kill release it."""+ ctx = multiprocessing.get_context("spawn")+ start, results = ctx.Barrier(4), ctx.Queue()+ pipes = [ctx.Pipe(duplex=False) for _ in range(4)]+ processes = [+ ctx.Process(target=_contend_for_lock, args=(str(tmp_path), start, reader, results))+ for reader, _ in pipes+ ]+ try:+ for process in processes:+ process.start()+ outcomes = [results.get(timeout=20) for _ in processes]+ owners = [pid for pid, status in outcomes if status == "acquired"]+ assert len(owners) == 1, outcomes+ assert sum(status == "locked" for _, status in outcomes) == 3+ owner_index = next(i for i, process in enumerate(processes) if process.pid == owners[0])+ owner = processes[owner_index]+ if crash:+ owner.kill()+ else:+ pipes[owner_index][1].send(None)+ for process in processes:+ process.join(timeout=20)+ assert not process.is_alive()+ if not crash or process is not owner:+ assert process.exitcode == 0+ assert (tmp_path / LOCK_FILENAME).exists()+ result = _probe_lock(tmp_path)+ assert result.returncode == 0, result.stderr+ finally:+ for process in processes:+ if process.pid is not None:+ if process.is_alive():+ process.kill()+ process.join(timeout=5)+ for reader, writer in pipes:+ reader.close()+ writer.close()+ results.close()+ results.join_thread()diff --git a/tests/utils/test_process_lock.py b/tests/utils/test_process_lock.pyindex 8e7f2bb42..4f84a86f8 100644--- a/tests/utils/test_process_lock.py+++ b/tests/utils/test_process_lock.py@@ -12,16 +12,18 @@ import timeimport pytest-from openviking.utils.process_lock import acquire_data_dir_lock+from openviking.utils.process_lock import acquire_data_dir_lock, release_data_dir_lockdef test_acquire_does_not_override_sigterm_handler(tmp_path):"""Uvicorn must retain ownership of SIGTERM for graceful lifespan shutdown."""original_handler = signal.getsignal(signal.SIGTERM)- acquire_data_dir_lock(str(tmp_path))-- assert signal.getsignal(signal.SIGTERM) is original_handler+ lock_path = acquire_data_dir_lock(str(tmp_path))+ try:+ assert signal.getsignal(signal.SIGTERM) is original_handler+ finally:+ release_data_dir_lock(lock_path)@pytest.mark.skipif(sys.platform == "win32", reason="SIGTERM lifecycle is POSIX-specific")@@ -87,6 +89,7 @@ def test_uvicorn_sigterm_runs_lifespan_and_releases_process_lock(tmp_path):assert process.returncode in {0, -signal.SIGTERM}, outputassert "Application shutdown complete" in outputassert "Finished server process" in output- assert not (workspace / ".openviking.pid").exists()+ lock_path = acquire_data_dir_lock(str(workspace))+ release_data_dir_lock(lock_path)assert "SystemExit" not in outputassert "CancelledError" not in output