@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/lib/argent_filelock.py

@@ -0,0 +1,507 @@
+#!/usr/bin/env python3
+"""argent_filelock —— **跨平台排他文件锁的唯一真源**（POSIX `fcntl.flock` / Windows `msvcrt.locking`）。
+
+## 为什么有它（2026-10-09，Windows 可移植性）
+引擎里的"加锁"此前各写各的，两种坏法：
+  · 三个脚本**顶层** `import fcntl` ⇒ Windows 上 `ModuleNotFoundError` ⇒
+    认领 / 台账 / 遥测**整个不可用**（与定时方案无关，换任何调度都绕不过）；
+  · 编排器里 10 处 `import fcntl` 在**函数内 + `except: pass`** ⇒ Windows 上锁**静默变 no-op**
+    （并发下重复执行同一件工作），而且在 macOS 上把真实错误一起吃掉。
+⇒ 收敛成这一个文件：**同一套 API、两种后端、零静默降级**。
+
+## 为什么叫 `argent_filelock`（不是 `filelock`）
+PyPI 上有一个**同名且极常见**的包 `filelock`（很多工具链的传递依赖），且它在 Windows 上也有
+一个 `WindowsFileLock` 类。模块名撞车时，**谁的路径在前谁赢** —— 一旦 `scripts/lib/` 不在
+`sys.path` 最前（诊断脚本、半装机器、`python -c` 探针），`import filelock` 会静默拿到那个第三方包
+（其 `FileLock` 没有 `try_acquire`/`best_effort`，行为与语义都不是本引擎的）。
+2026-10-09 在真机（Windows）上**实测命中**该撞名（探针拿到的就是第三方类的 `AttributeError`）
+⇒ 按仓库既有惯例（`argent_datadir.py` 同理）加前缀，让"导入到哪一个"不再有歧义。
+
+## API
+    lk = FileLock(path_or_file, blocking=True)   # 阻塞拿锁（等到拿到为止）
+    lk = FileLock(path_or_file, timeout=0.5)     # 最多等 0.5s，拿不到 ⇒ acquire() 返回 False
+    ok = lk.try_acquire()                        # 非阻塞试一次；拿不到 ⇒ False（**绝不**抛"忙"）
+    ok = lk.acquire(timeout=2.0)                 # 同上，可带超时
+    lk.release()                                 # 解锁（路径模式：连 fd 一起关）
+    with FileLock(path, blocking=True):  ...      # 拿不到 ⇒ 抛 LockTimeout / LockError
+    with best_effort(f, site="…") as lk: ...      # 策略(b)：拿不到 ⇒ 响亮告警后**无锁继续**
+`acquire()` / `try_acquire()` 的三种结果**互相区分**（这是本文件的核心契约）：
+  · `True`  = 拿到了；
+  · `False` = **没拿到**（别人持有 / 等超时）—— 明确的返回值，不是异常；
+  · 抛异常  = **锁本身不可用**（没有后端、锁文件建不出来、后端报非"忙"的错）⇒ `LockError`。
+⛔ **"锁不可用"绝不等于"拿到了锁"**：调用方必须显式选策略（见下），不许 `except: pass`。
+
+## 语义（**与 POSIX 现状逐字等价** ⇒ 迁移后 macOS 行为零变化）
+· **排他 + 阻塞可配**：`blocking=True` 时 POSIX 直接调 `flock(fd, LOCK_EX)` —— **与旧代码同一次
+  系统调用**（内核阻塞，不轮询）；非阻塞用 `LOCK_EX | LOCK_NB`（也与旧代码同）。
+· **不缓存、不共享 fd**：每次 `acquire()` 都**重新 `open()`** 再上锁 ⇒ 与 `fcntl.flock` 的
+  "锁挂在打开文件描述（open file description）上"完全一致：**同一进程里两次 open 也互斥**
+  （既有回归 `scripts/tests/store-executor-lock.test.py` 正是这么断言的）。
+· **同一实例重复 `acquire()` 幂等**（`_held` 短路，不重复系统调用）—— 与"同一 fd 上重复
+  `flock(LOCK_EX)` 成功"一致。
+· **锁的生命周期 = fd 的生命周期**：`release()` / 关文件 / 进程退出都会释放（两种后端都如此）
+  ⇒ 不留"死锁等人清"。
+· **锁文件路径约定不变**：调用方给什么就用什么 —— ① **专用锁文件**（如
+  `$ARGENT_LOCK_DIR/<name>.lock`、数据目录里的 `flow-claim-<flow>.lock`）：传路径；
+  ② **就地锁数据文件**（台账 / outbox 这类"锁自己"的）：传**已打开的文件对象**，锁的是同一个 fd。
+  两种都不新造文件。
+  路径模式下本对象自己 `open()`，**编码固定 UTF-8 + LF**（锁文件内容是诊断用的持有者 JSON，
+  非数据契约；macOS 上 locale 本就是 UTF-8 ⇒ 与旧行为逐字节一致，Windows 中文 locale 下不再
+  因 GBK 写中文而炸）。
+
+## 后端差异（照实写，不粉饰）
+| 维度 | POSIX（fcntl.flock） | Windows（msvcrt.locking） |
+|---|---|---|
+| 阻塞等待 | 内核阻塞，0 轮询 | `LK_NBLCK` + 轮询（`LK_LOCK` 重试约 10s 就放弃 ⇒ **不能**当无限等待用） |
+| 加锁区间 | 整个文件（flock 的粒度就是文件） | **第 2^40 字节起 1 字节**（区间长度恒为 1；`LK_UNLCK` 必须同区间 ⇒ 加/解锁前都 `lseek` 到该偏移，前后恢复原位置）。位置**故意在文件内容之外**：Windows 锁是强制式的，锁第 0 字节会让别的进程**读不了整个文件**（台账/outbox 的读者会 `PermissionError`，2026-10-09 真机实测） |
+| 锁的性质 | 劝告式（advisory） | **强制式（mandatory）**：别人**读**被锁的字节会报错 ⇒ 读锁文件里的持有者要跳过第 0 字节（见 `read_lock_holder`） |
+| 0 字节文件 | 可锁 | 可锁（`LockFile` 允许锁到 EOF 之外）⇒ **不写填充字节**，不污染被就地锁的数据文件 |
+
+## 降级策略（本文件只提供**手段**；策略由调用方**显式**选，判据 = "丢了锁会不会让两方跑同一件工作"）
+· **(a) fail-closed**：直接用 `FileLock` 并自己处理 `LockError`（拿不到 ⇒ **明确失败**，绝不无锁继续）。
+  用于**互斥**语义的锁（认领临界区、同店执行者、同记录、同店步骤互斥、全局端口差集）。
+· **(b) 响亮降级**：用 `best_effort(...)`（拿不到 ⇒ **每次计数 + 每进程每 site 喊一次** stderr，然后无锁继续）。
+  只用于"追加 / 审计写"这类**自身约定就是"不阻断主流程"**的场景。
+· `ARGENT_LOCK_STRICT=1` ⇒ 把 (b) **升级**成 (a)（CI / 生产可要求"绝不允许降级"）。
+· ⛔ 任何情况下都**不存在**"没拿到锁但一声不吭"的路径（旧实现的 `except: pass` 已全部拆除）。
+
+## 自检
+`python3 scripts/lib/argent_filelock.py --probe <锁文件>`（非阻塞试一次；0=拿到 / 3=被别人持有 / 2=不可用）
+`python3 scripts/lib/argent_filelock.py --hold <锁文件> <秒>`（持有若干秒，供**两进程抢锁**验证；
+`--backend` / `--version` 可打印后端与是否为 Windows 分支）。完整回归见
+`scripts/tests/filelock.test.py`。
+"""
+from __future__ import annotations
+
+import errno
+import os
+import sys
+import time
+from contextlib import contextmanager
+from typing import Any, Dict, Iterator, Optional, Set, Union
+
+__all__ = [
+    "FileLock", "LockError", "LockBackendUnavailable", "LockTimeout",
+    "backend_name", "is_windows", "read_lock_holder", "best_effort",
+    "warn_degraded", "degraded_counts", "reset_degraded", "strict_mode",
+]
+
+# ── 后端探测（**导入期绝不抛**）──────────────────────────────────────────────
+# 缺后端要在"上锁那一刻"以**明确异常**暴露，而不是让 `import` 整个炸掉 ——
+# 后者正是本次要修的缺陷形态（顶层 import fcntl ⇒ Windows 上三个脚本全不可用）。
+_fcntl: Any = None
+_msvcrt: Any = None
+if os.name == "nt":
+    try:
+        import msvcrt as _msvcrt
+    except Exception:                                            # noqa: BLE001
+        _msvcrt = None
+else:
+    try:
+        import fcntl as _fcntl
+    except Exception:                                            # noqa: BLE001
+        _fcntl = None
+    if _fcntl is None:
+        # POSIX 上正常没有 msvcrt；这一支留给两处：① 夹具注入假 msvcrt 走 Windows 分支的回归；
+        # ② "fcntl 被裁掉的半坏环境"仍有一线可用后端（拿不到才明确失败）。
+        try:
+            import msvcrt as _msvcrt
+        except Exception:                                        # noqa: BLE001
+            _msvcrt = None
+
+_BACKEND: Optional[str] = ("msvcrt" if (os.name == "nt" and _msvcrt is not None)
+                           else "fcntl" if _fcntl is not None
+                           else "msvcrt" if _msvcrt is not None else None)
+_POLL_SEC = 0.05                       # 只用于"有限超时"与 Windows 分支（POSIX 阻塞路径零轮询）
+_LOCK_BYTES = 1                        # Windows：锁区间**固定 1 字节**（跨进程可见）
+# Windows：锁区间放在**文件内容之外**的第 2^40 字节起 1 字节（`LockFile` 允许锁到 EOF 之外，
+# 且**不分配、不改文件大小**）。为什么不锁第 0 字节（2026-10-09 真机实测）：Windows 的字节区间锁是
+# **强制式**的 ⇒ 锁住第 0 字节会让**别的进程连整个文件都读不了**（`flow_ledger.read()` 当场
+# `PermissionError: [Errno 13]`）—— 而台账/outbox 是"就地锁数据文件"的用法，读者遍地都是
+# （分诊/工作台/遥测 `--status`）。挪到内容之外后：锁照样互斥，**读者一个都不受影响**。
+_WIN_LOCK_OFFSET = 1 << 40
+_BUSY_ERRNOS = frozenset(
+    int(e) for e in (getattr(errno, n, None) for n in
+                     ("EACCES", "EAGAIN", "EWOULDBLOCK", "EDEADLK", "EDEADLOCK"))
+    if isinstance(e, int))
+_BUSY_WINERRORS = frozenset((33, 36))  # ERROR_LOCK_VIOLATION / ERROR_SHARING_BUFFER_EXCEEDED
+
+
+class LockError(Exception):
+    """锁**不可用**（≠"被别人占用"）：无后端、锁文件打不开、后端报了非"忙"的错。"""
+
+
+class LockBackendUnavailable(LockError):
+    """本机没有任何可用后端（既无 `fcntl` 也无 `msvcrt`）⇒ 无法保证互斥。"""
+
+
+class LockTimeout(LockError):
+    """上下文管理器在超时内没拿到锁（`acquire` / `try_acquire` 走返回值，不抛这个）。"""
+
+
+def is_windows() -> bool:
+    """当前生效的后端是不是 Windows 分支（夹具注入 msvcrt 时为 True）。"""
+    return _BACKEND == "msvcrt"
+
+
+def backend_name() -> Optional[str]:
+    """当前生效的后端名：`'fcntl'` / `'msvcrt'` / `None`（无后端）。"""
+    return _BACKEND
+
+
+def _is_busy(exc: BaseException) -> bool:
+    """"被别人持有"的判定 —— 与"后端坏了"分开，后者必须冒出来。"""
+    if getattr(exc, "errno", None) in _BUSY_ERRNOS:
+        return True
+    return getattr(exc, "winerror", None) in _BUSY_WINERRORS
+
+
+# ── 降级告警（响亮 + 去重 + 计数；`ARGENT_LOCK_STRICT=1` 升级为失败）──────────────
+_DEGRADED: Dict[str, int] = {}
+_WARNED: Set[str] = set()
+
+
+def strict_mode() -> bool:
+    """`ARGENT_LOCK_STRICT=1` ⇒ 拒绝任何降级（把策略 (b) 升级成 (a)）。"""
+    return str(os.environ.get("ARGENT_LOCK_STRICT") or "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _warn(msg: str, dedup: Optional[str] = None) -> None:
+    if dedup is not None:
+        if dedup in _WARNED:
+            return
+        _WARNED.add(dedup)
+    try:
+        print(f"[filelock] {msg}", file=sys.stderr)
+    except Exception:                                            # noqa: BLE001
+        pass                                                 # 连 stderr 都写不了时也只能算了
+
+
+def warn_degraded(site: str, exc: Optional[BaseException] = None, note: str = "") -> None:
+    """**响亮但去重**的降级告警：同一 site 每进程喊一次，**每次都计数**（`degraded_counts()`）。
+
+    `ARGENT_LOCK_STRICT=1` ⇒ 改为抛 `LockError`（调用方由此得到 fail-closed 语义）。
+    """
+    key = "%s:%s" % (site or "?", type(exc).__name__ if exc is not None else "-")
+    _DEGRADED[key] = _DEGRADED.get(key, 0) + 1
+    msg = ("⚠️ 锁不可用 ⇒ **降级为无锁** [%s]（第 %d 次）%s%s"
+           % (site or "?", _DEGRADED[key], ("：" + note) if note else "",
+              ("：" + str(exc)) if exc is not None else ""))
+    if strict_mode():
+        raise LockError(msg + "（ARGENT_LOCK_STRICT=1 ⇒ 拒绝降级）")
+    _warn(msg, dedup=key)
+
+
+def degraded_counts() -> Dict[str, int]:
+    """各 site 的降级次数（测试与排障用）。"""
+    return dict(_DEGRADED)
+
+
+def reset_degraded() -> None:
+    _DEGRADED.clear()
+    _WARNED.clear()
+
+
+# ── Windows 分支的小工具 ────────────────────────────────────────────────────
+def _fd_tell(fd: int) -> Optional[int]:
+    try:
+        return os.lseek(fd, 0, os.SEEK_CUR)
+    except OSError:
+        return None
+
+
+def _fd_restore(fd: int, pos: Optional[int]) -> None:
+    if pos is None:
+        return
+    try:
+        os.lseek(fd, pos, os.SEEK_SET)
+    except OSError:
+        pass
+
+
+def read_lock_holder(path: Union[str, "os.PathLike[str]"]) -> str:
+    """读锁文件里的"持有者"文本（诊断用；**任何失败都返回空串**，绝不抛）。
+
+    锁区间在**文件内容之外**（`_WIN_LOCK_OFFSET`）⇒ 两种后端下这个读都畅通：
+    POSIX 的 `flock` 本来就劝告式（不挡读），Windows 锁的也不是内容区。
+    ⛔ 若将来有人把 `_WIN_LOCK_OFFSET` 改回 0，这个函数会立刻在 Windows 上失效（强制锁挡读）——
+    真机实测见常量处的说明。
+    """
+    try:
+        with open(os.fspath(path), "r", encoding="utf-8", errors="replace") as f:
+            return f.read().strip()
+    except OSError:
+        return ""
+
+
+# ── 锁本体 ──────────────────────────────────────────────────────────────────
+class FileLock:
+    """排他文件锁（POSIX `flock` / Windows `msvcrt.locking`）。
+
+    `target` 可以是**路径**（本对象负责 open/close）或**已打开的文件对象**（借用其 fd，不关它）。
+    `blocking` 只在 `timeout is None` 时有意义（True=等到拿到为止，False=只试一次）；
+    给了 `timeout` 就统一按"最多等这么久"处理（与 `blocking` 无关）。
+    """
+
+    def __init__(self, target: Any, *, blocking: bool = False, timeout: Optional[float] = None,
+                 mode: str = "a+", encoding: Optional[str] = "utf-8", site: str = "") -> None:
+        self._is_path = isinstance(target, (str, bytes, os.PathLike))
+        self._target = target
+        self._mode = mode
+        self._encoding = encoding
+        self._borrowed = None if self._is_path else target
+        self.blocking = bool(blocking)
+        self.timeout = timeout
+        self.site = site or ""
+        self.path = os.fspath(target) if self._is_path else str(getattr(target, "name", "") or "")
+        self._fp = None
+        self._owned = False
+        self._held = False
+        self.last_error: Optional[BaseException] = None
+
+    # ── 只读视图 ──
+    @property
+    def held(self) -> bool:
+        return self._held
+
+    @property
+    def fp(self) -> Any:
+        """底层文件对象（路径模式下 acquire 前为 None）——持有者信息等诊断写入口。"""
+        return self._fp if self._is_path else self._borrowed
+
+    def fileno(self) -> int:
+        fp = self.fp
+        try:
+            return int(fp.fileno())
+        except Exception:                                        # noqa: BLE001
+            return -1
+
+    def __repr__(self) -> str:                                   # pragma: no cover - 诊断用
+        return "<FileLock %s backend=%s held=%s site=%s>" % (
+            self.path or "-", _BACKEND, self._held, self.site or "-")
+
+    # ── 打开 / 关闭 ──
+    def _ensure_open(self) -> int:
+        if not self._is_path:
+            fp = self._borrowed
+            if fp is None or getattr(fp, "closed", False):
+                raise LockError("借用的文件对象已关闭，无法上锁：%s" % (self.path or "-"))
+            try:
+                return int(fp.fileno())
+            except Exception as exc:                             # noqa: BLE001
+                raise LockError("借用的对象没有可用 fd：%s" % exc) from exc
+        if self._fp is None:
+            try:
+                # newline="\n" ⇒ 与 POSIX 现状逐字节一致（Windows 上不会因 os.linesep 变 CRLF）
+                self._fp = open(self._target, self._mode, encoding=self._encoding, newline="\n")
+            except OSError as exc:
+                raise LockError("打不开锁文件 %s：%s" % (self.path or "-", exc)) from exc
+            self._owned = True
+        return int(self._fp.fileno())
+
+    def close(self) -> None:
+        """关掉**本对象自己打开**的 fd（借用模式只解锁，绝不关别人的文件）。"""
+        if self._owned and self._fp is not None:
+            try:
+                self._fp.close()
+            except Exception as exc:                             # noqa: BLE001
+                self.last_error = exc
+                _warn("关闭锁文件失败（%s）：%s" % (self.path or "-", exc),
+                      dedup="close:%s" % self.path)
+            self._fp = None
+            self._owned = False
+
+    # ── 加锁 / 解锁 ──
+    def _try_once(self, fd: int) -> bool:
+        if _BACKEND == "fcntl":
+            try:
+                _fcntl.flock(fd, _fcntl.LOCK_EX | _fcntl.LOCK_NB)
+                return True
+            except OSError as exc:
+                if _is_busy(exc):
+                    return False
+                raise LockError("fcntl.flock(LOCK_EX|LOCK_NB) 失败（%s）：%s" % (self.path or "-", exc)) from exc
+        pos = _fd_tell(fd)
+        try:
+            os.lseek(fd, _WIN_LOCK_OFFSET, os.SEEK_SET)             # 内容之外（见常量处的实测说明）
+            try:
+                _msvcrt.locking(fd, _msvcrt.LK_NBLCK, _LOCK_BYTES)   # 非阻塞；区间固定 1 字节
+                return True
+            except OSError as exc:
+                if _is_busy(exc):
+                    return False
+                raise LockError("msvcrt.locking(LK_NBLCK) 失败（%s）：%s" % (self.path or "-", exc)) from exc
+        finally:
+            _fd_restore(fd, pos)
+
+    def _acquire_forever(self, fd: int) -> bool:
+        """阻塞直到拿到（与旧实现同语义）。POSIX 走内核阻塞；Windows 只能轮询。"""
+        if _BACKEND == "fcntl":
+            try:
+                _fcntl.flock(fd, _fcntl.LOCK_EX)                 # ← 与旧代码**同一次**系统调用
+                return True
+            except OSError as exc:
+                raise LockError("fcntl.flock(LOCK_EX) 失败（%s）：%s" % (self.path or "-", exc)) from exc
+        while True:
+            if self._try_once(fd):
+                return True
+            time.sleep(_POLL_SEC)
+
+    def _acquire_deadline(self, fd: int, wait: float) -> bool:
+        deadline = time.monotonic() + max(0.0, float(wait))
+        while True:
+            if self._try_once(fd):
+                return True
+            now = time.monotonic()
+            if now >= deadline:
+                return False
+            time.sleep(min(_POLL_SEC, max(0.0, deadline - now)))
+
+    def acquire(self, timeout: Optional[float] = None) -> bool:
+        """拿锁。返回 False = **没拿到**（被别人持有 / 等超时）；抛 `LockError` = **锁不可用**。"""
+        if self._held:
+            return True                                          # 同实例重复拿 = 幂等（同 fd 重复 flock）
+        if _BACKEND is None:
+            raise LockBackendUnavailable(
+                "本机没有可用的文件锁后端（既无 fcntl 也无 msvcrt）⇒ 无法保证互斥；"
+                "如需显式降级请用 best_effort（会响亮告警）")
+        fd = self._ensure_open()
+        wait = self.timeout if timeout is None else timeout
+        if wait is None:
+            if self.blocking:
+                self._held = bool(self._acquire_forever(fd))
+            else:
+                self._held = bool(self._acquire_deadline(fd, 0.0))
+        else:
+            self._held = bool(self._acquire_deadline(fd, float(wait)))
+        return self._held
+
+    def try_acquire(self, timeout: float = 0.0) -> bool:
+        """非阻塞试一次（`timeout>0` 则最多等这么久）。拿不到 ⇒ False。"""
+        return self.acquire(timeout=timeout)
+
+    def _unlock(self) -> None:
+        fp = self.fp
+        if fp is None:
+            return
+        fd = int(fp.fileno())
+        if _BACKEND == "fcntl":
+            _fcntl.flock(fd, _fcntl.LOCK_UN)                     # ← 与旧代码**同一次**系统调用
+            return
+        pos = _fd_tell(fd)
+        try:
+            os.lseek(fd, _WIN_LOCK_OFFSET, os.SEEK_SET)
+            _msvcrt.locking(fd, _msvcrt.LK_UNLCK, _LOCK_BYTES)    # 必须与加锁**同区间**
+        finally:
+            _fd_restore(fd, pos)
+
+    def release(self) -> None:
+        """解锁；路径模式再关掉自己的 fd。**不抛**，但失败会响亮出声（`last_error` 也留证）。
+
+        为什么敢不抛：两种后端都保证"fd 关闭 / 进程退出即释放"，所以"解锁调用失败"不等于
+        "锁没放掉"；在这个位置上抛异常只会把调用方真正要看的错误盖掉（旧实现是 `except: pass`，
+        连声音都没有 —— 这里至少喊一声）。
+        """
+        was_held, self._held = self._held, False
+        if was_held and self.fp is not None:
+            try:
+                self._unlock()
+            except Exception as exc:                             # noqa: BLE001
+                self.last_error = exc
+                _warn("解锁失败（%s）：%s —— 随后的 close()/进程退出会释放该锁"
+                      % (self.path or "-", exc), dedup="unlock:%s" % self.path)
+        self.close()
+
+    # ── 上下文管理器 ──
+    def __enter__(self) -> "FileLock":
+        if not self.acquire():
+            raise LockTimeout("未在超时内拿到锁：%s（site=%s）" % (self.path or "-", self.site or "-"))
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        self.release()
+        return False                                             # 绝不吞调用方的异常
+
+
+@contextmanager
+def best_effort(target: Any, site: str = "", note: str = "", **kw: Any) -> Iterator[Optional[FileLock]]:
+    """**策略 (b)**：锁不可用 ⇒ 响亮告警（每次计数 / 每进程每 site 喊一次）后**无锁继续**。
+
+    只给"追加 / 审计写"这类**自身约定就是不阻断主流程**的场景用；互斥类锁一律直接用 `FileLock`
+    走策略 (a) fail-closed。拿到锁时 `yield` 锁对象，降级时 `yield None`；两种都在退出时释放。
+    `ARGENT_LOCK_STRICT=1` ⇒ 不降级，直接抛 `LockError`。
+    """
+    # ⚠️ **默认阻塞**（= 旧实现的 `fcntl.flock(LOCK_EX)`）：追加写必须**排队**，不能"试一次就算了"。
+    # 2026-10-09 真机（Windows）实测教训：这里若走非阻塞，`.append()` 会在别人持锁时**直接无锁写** ⇒
+    # Windows 的 `_O_APPEND`（seek-to-EOF + write 非原子）**丢行**（3 进程 ×15 条只活下 42 条），
+    # 而 POSIX 的 `O_APPEND` 原子性**恰好掩盖**这个问题（本地全绿）⇒ 必须由"持锁期间写入"来保证。
+    kw.setdefault("blocking", True)
+    lk = FileLock(target, site=site, **kw)
+    try:
+        got = lk.acquire()
+    except LockError as exc:
+        warn_degraded(site, exc, note)                            # strict 模式下这里会抛
+        try:
+            yield None
+        finally:
+            lk.release()
+        return
+    if not got:
+        # 只有调用方**显式给了 timeout** 才可能走到这里（默认阻塞路径不会）：同样按策略 (b) 处理，
+        # 但**绝不静默** —— 也绝不假装"拿到了"。
+        warn_degraded(site, None, note or "未在超时内拿到锁 ⇒ 无锁继续")
+        try:
+            yield None
+        finally:
+            lk.release()
+        return
+    try:
+        yield lk
+    finally:
+        lk.release()
+
+
+# ── 自检 CLI（诊断/真机验证用；不参与业务）────────────────────────────────────
+def _main(argv: list) -> int:
+    def usage() -> int:
+        print(__doc__.split("## 自检")[1].strip(), file=sys.stderr)
+        return 2
+    if not argv or argv[0] in ("-h", "--help"):
+        return usage()
+    if argv[0] == "--backend":
+        print("backend=%s windows=%s" % (_BACKEND or "none", is_windows()))
+        return 0
+    if argv[0] == "--version":
+        print("filelock (Argent engine, cross-platform exclusive file lock)")
+        return 0
+    if argv[0] == "--probe" and len(argv) >= 2:
+        try:
+            lk = FileLock(argv[1], site="cli.probe")
+            ok = lk.try_acquire()
+        except LockError as exc:
+            print("⚠️ 锁不可用：%s" % exc, file=sys.stderr)
+            return 2
+        if not ok:
+            holder = read_lock_holder(argv[1])
+            print("busy（被别人持有）%s" % (("：" + holder[:200]) if holder else ""))
+            lk.release()
+            return 3
+        print("acquired（%s，backend=%s）" % (argv[1], _BACKEND))
+        lk.release()
+        print("released")
+        return 0
+    if argv[0] == "--hold" and len(argv) >= 3:
+        secs = float(argv[2])
+        lk = FileLock(argv[1], blocking=True, site="cli.hold")
+        lk.acquire()
+        print("holding %s for %ss (pid=%d, backend=%s)" % (argv[1], secs, os.getpid(), _BACKEND))
+        sys.stdout.flush()
+        time.sleep(secs)
+        lk.release()
+        print("released")
+        return 0
+    return usage()
+
+
+if __name__ == "__main__":                                       # pragma: no cover
+    raise SystemExit(_main(sys.argv[1:]))