@furongjun1999/dsh-memory 0.7.5 → 0.8.1

package/md_cg/test_p6_consolidate.py

@@ -1,7 +1,8 @@
 # -*- coding: utf-8 -*-
 """md_cg · P6 验收：离线固化（反思单元 → 白箱闸门 → 验证单元 → 固化）
 
-运行：python -m md_cg.test_p6_consolidate
+运行：python -X utf8 -m md_cg.test_p6_consolidate                     # 正常跑（含 R 组）
+      python -X utf8 -m md_cg.test_p6_consolidate --mutation-baseline # R 组定点变异自证
 
 验证口径（对齐工作纪律第 3/5 条「不猜测、未经验证不固化」）：
   1. 候选解析：JSON 容错 + 字段别名（子内容→子功能）
@@ -14,22 +15,31 @@
   8. 幂等 + 不覆盖人工既有字段
   9. 验证单元不可用 → DEFER（不写盘）；--no-verify 降级可跑通
  10. 验证方式补全（零 LLM）+ 与生产 _path_semantic 的一致性回归
+ 11. （R 组）issue #64 修复守卫：replay_check 撤销「负条件一票否决」、consolidate
+     主流程「负条件两态拦截」（neg_absent / neg_dropped_all）、CLI 两角色
+     max-tokens/timeout 单设——附定点变异自证（`--mutation-baseline`）。
 """
 from __future__ import annotations
 
+import contextlib
+import inspect
+import io
 import json
 import os
 import shutil
+import subprocess
 import sys
 import tempfile
 
+from . import consolidate as _consolidate_mod
 from . import nodefile
-from .consolidate import (BASIS_TEMPLATE, REFLECT_ROLE, VERIFY_ROLE, body_text,
-                          consolidate, existing_fields, fill_verification_basis,
-                          grounding_filter, grounding_score, narrow_by_verdict,
-                          parse_candidate, parse_verdict, replay_check,
-                          role_config)
-from .mdcos import MdCGOS
+from .consolidate import (BASIS_TEMPLATE, REFLECT_ROLE, VERIFY_ROLE, _cli,
+                          body_text, consolidate, existing_fields,
+                          fill_verification_basis, grounding_filter,
+                          grounding_score, narrow_by_verdict, parse_candidate,
+                          parse_verdict, replay_check, role_config)
+from .mdcg import expand_query_terms_weighted
+from .mdcos import MdCGOS, _neg_hit, _weighted_coverage
 
 PASS = FAIL = 0
 FAILS = []
@@ -101,7 +111,375 @@ def new_root(n=1):
     return root, rel
 
 
+# ==========================================================================
+# R 组：issue #64 修复守卫（2026-10-06）
+# ==========================================================================
+#
+# 缺陷（外部报告 angel12538 对 v0.7.5 实测；编排侧隔离库独立复现）：
+#   A 类① `consolidate.replay_check` 的 pos_recall 带 `and not _neg_hit(tw_pos, neg_terms)`
+#         ——「生效条件任一词整词出现在不适用条件里」一票判负。而负条件描述的是
+#         **邻近易混情境**，与生效条件共享领域主题词是结构必然（不共享主题词就
+#         谈不上「邻近」）⇒ 合格负条件被大量误杀。自否定职责已由 no_conflict
+#         （覆盖率口径，<0.5 才算互相覆盖）承担——两者同意图而前者更严。
+#   B 类   `consolidate` 主流程把 grounding 删光后的空 neg 交给 replay_check，命中其
+#         `else: neg_separated = True` 短路 ⇒「负条件被删光/未产出」被翻译成「通过」
+#         ⇒ 缺「不适用条件」要素的节点落盘并携带 verification_basis 声明。
+#
+# 定点变异自证（`python -X utf8 -m md_cg.test_p6_consolidate --mutation-baseline`，
+# 与 test_neg_condition_hits 同口径）：每一处修复判据都必须有变异把它打红，且
+# **红项数恰好等于** _MUTATIONS 登记的预期数（多红说明断言串扰、少红说明该判据
+# 无判别力——两种都判 FAIL）。变异锚点为**本文件内联的源码文本**，不读 git HEAD
+# （基线绑提交即失效，本仓已有两次教训）。锚点漂移（实现改了而本表未同步）→
+# 报 ANCHOR-MISS，退出码 2（fail-closed）——守卫静默失效比守卫失败更危险。
+# R6 走 subprocess 跑**盘上模块**的 `--help`，内存态变异打不到它，故不登记变异腿；
+# 其判别力由「四个参数名逐一断言」承担（删任一参数即红）。
+
+# R1/R2 样本（A 类①）：读数经编排侧探针独立标定——
+#   ② 负条件对正文覆盖率 = 0.402、③ 生效条件对负条件文本覆盖率 = 0.37（均 < 0.5，
+#   未触发），① 一票否决为唯一杀手；撤销前 replay_check 判 {pos_recall: False, ok: False}。
+R_POS = ["海边甜品店 招牌蛋糕 做法"]
+R_NEG = ["海边甜品店 的其它蛋糕 冷藏流程"]
+R_BODY = "海边甜品店招牌蛋糕做法：奶油打发后低温烘焙，成品当日冷藏保存。"
+
+# R2 自否定样本：生效条件与不适用条件整条互相覆盖 → no_conflict 必须拦住
+R_POS2 = ["海边甜品店 招牌蛋糕"]
+R_NEG2 = ["海边甜品店 招牌蛋糕"]
+
+# R3/R4 打桩候选：负条件域外（与正文零 bigram 支撑 → grounding 全删）
+R_CAND_DROP = {
+    "生效条件": ["微分方程", "数值方法"],
+    "子功能": ["建模", "求解"],
+    "执行": "使用数值方法迭代求解",
+    "不适用条件": ["量子色动力学格点规范场论"],
+}
+R_CAND_ABSENT = {k: v for k, v in R_CAND_DROP.items() if k != "不适用条件"}
+
+
+def _legacy_pos_recall(pos_terms, neg_terms, body):
+    """A 类① 撤销**前**的 pos_recall 原文（issue #64 前）——仅用于「样本确实踩中
+    旧缺陷」的红基线自证，不参与生产：生产判据单点在 consolidate.replay_check。"""
+    pos_text = " ".join(pos_terms or [])
+    tw_pos = expand_query_terms_weighted(pos_text) if pos_text else {}
+    return bool(pos_text) and _weighted_coverage(tw_pos, body) > 0.0 \
+        and not _neg_hit(tw_pos, neg_terms)
+
+
+def _const_reflect(cand):
+    """打桩反思单元：恒返回同一候选（隔离「负条件两态」这一变量）。"""
+    return lambda prompt: json.dumps(cand, ensure_ascii=False)
+
+
+class _HttpSpy:
+    """打桩 http_llm：记录两角色**实收**的 (max_tokens, timeout) 并返回可解析输出。
+
+    用于 R6 的透传行为面：CLI 参数是否真被喂到 reflect/verify 两侧（而不只是
+    出现在 --help 文本里）。
+    """
+
+    def __init__(self, cand):
+        self.calls = []
+        self.cand = cand
+
+    def __call__(self, prompt, model=None, base=None, key=None, role=None,
+                 timeout=120, max_tokens=None):
+        self.calls.append({"role": role, "max_tokens": max_tokens,
+                           "timeout": timeout})
+        if role == VERIFY_ROLE:
+            return "{}"
+        return json.dumps(self.cand, ensure_ascii=False)
+
+
+def _swap_http_llm(fake):
+    """把 http_llm 换成打桩替身，返回还原函数。
+
+    同时覆盖两个全局面：模块面，以及**当前 _cli**（可能是内存变异版）的
+    __globals__——变异版的命名空间是 exec 快照，只 patch 模块属性它看不到，
+    会漏到真网络调用。
+    """
+    holders = [vars(_consolidate_mod)]
+    g = getattr(globals().get("_cli"), "__globals__", None)
+    if isinstance(g, dict) and g is not vars(_consolidate_mod):
+        holders.append(g)
+    saved = [(h, h.get("http_llm")) for h in holders]
+    for h in holders:
+        h["http_llm"] = fake
+
+    def restore():
+        for h, old in saved:
+            h["http_llm"] = old
+    return restore
+
+
+def _r_run(verbose=True):
+    """跑 R1-R6，返回失败项名单。verbose=False 时静默（变异自证复用，不污染全局计数）。"""
+    fails = []
+
+    def ck(name, cond, detail=""):
+        if not cond:
+            fails.append(name)
+        if verbose:
+            check(name, cond, detail)
+
+    def sec(title):
+        if verbose:
+            print(title)
+
+    # ---- R1 撤销负条件一票否决（A 类①复现样本）----
+    sec("\n== R1 撤销负条件一票否决（A 类①复现样本）==")
+    r1 = replay_check(R_POS, R_NEG, R_BODY)
+    ck("R1a 复现样本 pos_recall=True（恢复一票否决因子即转 False）",
+       r1.get("pos_recall") is True, str(r1))
+    ck("R1b 复现样本 ok=True（②=0.402 / ③=0.37 均未触发，①原为唯一杀手）",
+       r1.get("ok") is True, str(r1))
+    ck("R1c 红基线可复现：同一输入在撤销前的 pos_recall 原文下判负（样本有效性）",
+       _legacy_pos_recall(R_POS, R_NEG, R_BODY) is False)
+
+    # ---- R2 自否定职责由 no_conflict 承担（③兜底不退化）----
+    sec("\n== R2 自否定由 no_conflict 承担（撤销①不得放宽自否定）==")
+    r2 = replay_check(R_POS2, R_NEG2, R_BODY)
+    ck("R2a 生效条件整条覆盖不适用条件 → no_conflict=False",
+       r2.get("no_conflict") is False, str(r2))
+    ck("R2b 自否定样本 ok=False（撤销①不等于放过自否定）",
+       r2.get("ok") is False, str(r2))
+    ck("R2c 自否定样本 pos_recall 仍成立（召回不再被负条件一票否决，由③兜底）",
+       r2.get("pos_recall") is True, str(r2))
+
+    # ---- R3 态1：负条件被 grounding 删光 → 全链 REJECT ----
+    sec("\n== R3 态1（neg_dropped_all）：负条件被 grounding 删光 → 全链 REJECT ==")
+    root, rel = new_root(1)
+    try:
+        p = os.path.join(root, rel["n1"])
+        before = open(p, encoding="utf-8").read()
+        rep = consolidate(root, apply=True, reflect_fn=_const_reflect(R_CAND_DROP),
+                          verify_fn=lambda prompt: "{}", require_verify=True)
+        fm, content = nodefile.loads(open(p, encoding="utf-8").read())
+        ck("R3a 删光态 → rejected=1（修复前 accepted=1 直接落盘）",
+           rep["rejected"] == 1, str(rep["reasons"]))
+        ck("R3b reasons 记 neg_dropped_all=1",
+           rep["reasons"].get("neg_dropped_all") == 1, str(rep["reasons"]))
+        ck("R3c 不写盘（written=0 且盘上内容逐字未变）",
+           rep["written"] == 0 and open(p, encoding="utf-8").read() == before,
+           "written=%s" % rep["written"])
+        ck("R3d 盘上节点无 llm_consolidation 键（未携带 grounding/replay 声明落盘）",
+           "llm_consolidation" not in fm, str(sorted(fm)))
+        smp = (rep["samples"] or [{}])[0]
+        ck("R3e samples 带 reason=neg_dropped_all 且 replay=None（可观测面）",
+           smp.get("reason") == "neg_dropped_all" and smp.get("replay") is None,
+           str(smp))
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+    # ---- R4 态2：候选未产出负条件 → 全链 REJECT ----
+    sec("\n== R4 态2（neg_absent）：候选无「不适用条件」键 → 全链 REJECT ==")
+    root, rel = new_root(1)
+    try:
+        p = os.path.join(root, rel["n1"])
+        before = open(p, encoding="utf-8").read()
+        rep = consolidate(root, apply=True, reflect_fn=_const_reflect(R_CAND_ABSENT),
+                          verify_fn=lambda prompt: "{}", require_verify=True)
+        fm, content = nodefile.loads(open(p, encoding="utf-8").read())
+        ck("R4a 未产出态 → rejected=1（修复前 accepted=1 直接落盘）",
+           rep["rejected"] == 1, str(rep["reasons"]))
+        ck("R4b reasons 记 neg_absent=1",
+           rep["reasons"].get("neg_absent") == 1, str(rep["reasons"]))
+        ck("R4c 不写盘（written=0 且盘上内容逐字未变）",
+           rep["written"] == 0 and open(p, encoding="utf-8").read() == before,
+           "written=%s" % rep["written"])
+        ck("R4d 盘上节点无 llm_consolidation 键",
+           "llm_consolidation" not in fm, str(sorted(fm)))
+        smp = (rep["samples"] or [{}])[0]
+        ck("R4e samples 带 reason=neg_absent 且 replay=None（可观测面）",
+           smp.get("reason") == "neg_absent" and smp.get("replay") is None, str(smp))
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+    # ---- R5 不误伤：合法候选（含域外负条件）照常 ACCEPT ----
+    sec("\n== R5 不误伤：合法候选全链照常 ACCEPT ==")
+    root, rel = new_root(1)
+    try:
+        p = os.path.join(root, rel["n1"])
+        rep = consolidate(root, apply=True, reflect_fn=fake_reflect,
+                          verify_fn=fake_verify, reflect_model=REFLECT_MODEL,
+                          verify_model=VERIFY_MODEL, verification_basis=BASIS)
+        fm, content = nodefile.loads(open(p, encoding="utf-8").read())
+        ck("R5a 合法候选 → accepted=1 / written=1",
+           rep["accepted"] == 1 and rep["written"] == 1, str(rep["reasons"]))
+        ck("R5b 合法候选 replay.ok=True（两态拦截不误伤合格负条件）",
+           ((fm.get("llm_consolidation") or {}).get("replay") or {}).get("ok") is True,
+           str((fm.get("llm_consolidation") or {}).get("replay")))
+        ck("R5c 负条件照常落盘（正文含「# 不适用条件」行）", "# 不适用条件" in content)
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+    # ---- R6 CLI：两角色 max-tokens/timeout 可分别单设 ----
+    sec("\n== R6 CLI：--reflect/--verify-max-tokens、--reflect/--verify-timeout ==")
+    env = dict(os.environ)
+    env["PYTHONUTF8"] = "1"
+    repo_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    proc = subprocess.run(
+        [sys.executable, "-X", "utf8", "-m", "md_cg.consolidate", "--help"],
+        capture_output=True, text=True, encoding="utf-8", errors="replace",
+        cwd=repo_root, env=env)
+    flat = (proc.stdout or "") + (proc.stderr or "")
+    ck("R6a `python -m md_cg.consolidate --help` 退出码 0",
+       proc.returncode == 0, "rc=%s :: %s" % (proc.returncode, flat[:120]))
+    for flag in ("--reflect-max-tokens", "--verify-max-tokens",
+                 "--reflect-timeout", "--verify-timeout"):
+        ck("R6 帮助含参数 %s" % flag, flag in flat)
+
+    # 透传行为面（打桩 http_llm 记录两角色实收参数）：单设优先、缺省回落共用值
+    spy = _HttpSpy(CAND)
+    restore_http = _swap_http_llm(spy)
+    saved_keys = {k: os.environ.get(k)
+                  for k in ("MDCG_REFLECT_KEY", "MDCG_VERIFY_KEY")}
+    root, rel = new_root(1)
+    try:
+        os.environ["MDCG_REFLECT_KEY"] = "k-reflect"
+        os.environ["MDCG_VERIFY_KEY"] = "k-verify"
+        with contextlib.redirect_stdout(io.StringIO()):
+            _cli(["--root", root, "--max-tokens", "5000", "--timeout", "7",
+                  "--reflect-max-tokens", "7000", "--reflect-timeout", "3",
+                  "--verify-max-tokens", "6000", "--verify-timeout", "9"])
+        by_role = {c["role"]: c for c in spy.calls}
+        ck("R6b 反思单元实收单设预算/超时（--reflect-max-tokens=7000 / --reflect-timeout=3）",
+           by_role.get(REFLECT_ROLE, {}).get("max_tokens") == 7000
+           and by_role.get(REFLECT_ROLE, {}).get("timeout") == 3.0, str(spy.calls))
+        ck("R6c 验证单元实收单设预算/超时（--verify-max-tokens=6000 / --verify-timeout=9）",
+           by_role.get(VERIFY_ROLE, {}).get("max_tokens") == 6000
+           and by_role.get(VERIFY_ROLE, {}).get("timeout") == 9.0, str(spy.calls))
+        spy.calls.clear()
+        with contextlib.redirect_stdout(io.StringIO()):
+            _cli(["--root", root, "--max-tokens", "5000", "--timeout", "7"])
+        fell = {c["role"]: c for c in spy.calls}
+        ck("R6d 角色级参数缺省回落共用缺省（两角色都实收 5000 / 7.0）",
+           fell.get(REFLECT_ROLE, {}).get("max_tokens") == 5000
+           and fell.get(REFLECT_ROLE, {}).get("timeout") == 7.0
+           and fell.get(VERIFY_ROLE, {}).get("max_tokens") == 5000
+           and fell.get(VERIFY_ROLE, {}).get("timeout") == 7.0, str(spy.calls))
+    finally:
+        restore_http()
+        for k, v in saved_keys.items():
+            if v is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = v
+        shutil.rmtree(root, ignore_errors=True)
+
+    return fails
+
+
+# 定点变异表：逐处把本轮修复的判据改坏/改回，R 组必须转红且**红项数恰好等于**
+# 登记值（多红 = 断言串扰、少红 = 判据无判别力，两者都判 FAIL）。锚点 = 源码文本
+# （内联基线，不读 git HEAD）；锚点缺失/不唯一 → ANCHOR-MISS → 退出码 2。
+# 预期红项数 = 实跑登记（2026-10-06 首跑，R 组子项名）：
+#   ① → R1a、R1b、R2c（3 项：撤销判据的直接面）
+#   ②a → R4b、R4e（2 项：neg_absent 专属计数与可观测面）
+#   ②b → R3a、R3b、R3c、R3d、R3e（5 项：neg_dropped_all 全链不落盘）
+#   ②ab（两态全删）→ R3 五项 + R4 五项（10 项：两态各自失守）
+#   ③a → R6b（1 项：反思侧透传面）
+#   ③b → R6c（1 项：验证侧透传面）
+# 登记值是**锁**：实测多红（断言串扰）或少红（判据无判别力）都判 FAIL。
+_MUTATIONS = (
+    ("① 恢复负条件一票否决（replay_check.pos_recall）", "replay_check", (
+        ("pos_recall = bool(pos_text) and _weighted_coverage(tw_pos, body) > 0.0",
+         "pos_recall = bool(pos_text) and _weighted_coverage(tw_pos, body) > 0.0 \\\n"
+         "        and not _neg_hit(tw_pos, neg_terms)"),
+    ), 3),
+    ("②a neg_absent 两态拦截失效（consolidate）", "consolidate", (
+        ("if not neg_cand:", "if False:"),
+    ), 2),
+    ("②b neg_dropped_all 两态拦截失效（consolidate）", "consolidate", (
+        ("if not neg:", "if False:"),
+    ), 5),
+    ("②ab 两态拦截整体删除（consolidate）", "consolidate", (
+        ("if not neg_cand:", "if False:"),
+        ("if not neg:", "if False:"),
+    ), 10),
+    ("③a 反思单元未透传单设预算/超时（_cli 回落共用值）", "_cli", (
+        ("max_tokens=refl_mt, timeout=refl_to",
+         "max_tokens=a.max_tokens, timeout=a.timeout"),
+    ), 1),
+    ("③b 验证单元未透传单设预算/超时（_cli 回落共用值）", "_cli", (
+        ("max_tokens=ver_mt, timeout=ver_to",
+         "max_tokens=a.max_tokens, timeout=a.timeout"),
+    ), 1),
+)
+
+
+def _anchor_report():
+    """检查所有变异锚点在实现源码中是否**唯一**存在；返回问题描述清单（空 = 全在）。
+
+    锚点漂移（实现改了而本表未同步）意味着变异腿空转 ⇒ 守卫判别力静默失效，
+    故调用方以退出码 2 fail-closed。
+    """
+    bad = []
+    for name, fn_name, pairs, _expect in _MUTATIONS:
+        src = inspect.getsource(getattr(_consolidate_mod, fn_name))
+        for old, _new in pairs:
+            n = src.count(old)
+            if n != 1:
+                bad.append("%s :: 锚点出现 %d 次（应为 1）:: %r"
+                           % (name, n, old[:60]))
+    return bad
+
+
+def _mutate(fn_name, pairs):
+    """把 fn_name 的源码按 pairs 替换后 exec 出新函数（只在内存里，不落任何文件）。"""
+    mod = _consolidate_mod
+    src = inspect.getsource(getattr(mod, fn_name))
+    for old, new in pairs:
+        src = src.replace(old, new, 1)
+    ns = dict(vars(mod))
+    exec(compile(src, "<mut_%s>" % fn_name, "exec"), ns)
+    return ns[fn_name]
+
+
+def _mutation_baseline() -> int:
+    """定点变异自证：逐处变异本轮修复的判据，R 组必须转红且红项数恰等于登记值。"""
+    print("!! 定点变异自证：逐处变异本轮修复的判据，R 组应当转红"
+          "（红项数须恰好等于登记值）\n")
+    with contextlib.redirect_stdout(io.StringIO()):
+        base = _r_run(verbose=False)
+    print("  未变异基线：红项=%d%s" % (len(base), ("（须为 0）" + "、".join(base)) if base else "（须为 0）"))
+    bad = []
+    if base:
+        bad.append("未变异基线即红")
+    for name, fn_name, pairs, expect in _MUTATIONS:
+        old_live = globals()[fn_name]
+        globals()[fn_name] = _mutate(fn_name, pairs)
+        try:
+            with contextlib.redirect_stdout(io.StringIO()):
+                fails = _r_run(verbose=False)
+        finally:
+            globals()[fn_name] = old_live
+        if len(fails) == expect:
+            verdict = "一致（有判别力）"
+        elif not fails:
+            verdict = "**仍全绿 = 该判据无判别力**"
+        else:
+            verdict = "**红项数不符（实测 %d ≠ 登记 %d）**" % (len(fails), expect)
+        print("  变异「%s」→ 红项=%d（登记 %d）%s：%s"
+              % (name, len(fails), expect, verdict, "、".join(fails)))
+        if len(fails) != expect:
+            bad.append(name)
+    print("\n定点变异自证：%s"
+          % ("PASS（每处判据都有变异把它打红）" if not bad else "FAIL —— " + "、".join(bad)))
+    return 0 if not bad else 1
+
+
 def main():
+    # ANCHOR-MISS 预检（fail-closed）：变异锚点是 R 组判别力的底座——实现漂移而
+    # 基线表未同步时守卫会静默失效；故先检锚点，漂移即以退出码 2 失败，不静默。
+    miss = _anchor_report()
+    if miss:
+        print("ANCHOR-MISS：守卫变异锚点在实现源码中缺失或不唯一"
+              "（实现已漂移，本守卫基线表未同步）——fail-closed，退出码 2：")
+        for m in miss:
+            print("  · " + m)
+        return 2
+    if "--mutation-baseline" in sys.argv:
+        return _mutation_baseline()
+
     # ---------------- 1. 候选解析 ----------------
     print("\n【1】候选解析（JSON 容错 + 字段别名）")
     c = parse_candidate("```json\n" + CAND_JSON + "\n```")
@@ -428,6 +806,10 @@ def main():
                                          "message": {"content": "ok"}}]},
                            "m", 999) == "ok")
 
+    # ---------------- R. issue #64 修复守卫 ----------------
+    print("\n【R】issue #64 修复守卫（replay_check 撤销一票否决 / 负条件两态拦截 / CLI 参数）")
+    _r_run(verbose=True)
+
     print("\n" + "=" * 68)
     print(f"通过 {PASS} / 失败 {FAIL}")
     if FAILS:

package/md_cg/test_sleep_gitlock.py

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+"""test_sleep_gitlock · 影子仓 git 残留锁**有界自清**守卫（2026-10-06 落地 issue #63 待裁项）。
+
+契约（`md_cg/sleep.py::_clear_git_lock` 三闸口径）：
+  ① 范围＝仅睡眠影子仓的 `index.lock`（本模块单属仓）；
+  ② `force=True` 仅在本模块刚 kill 掉自己超时的 git 后调用（此刻仓内锁只可能
+     是被 kill 进程的残留）；非 force（`_git` 调用前置巡检）只在锁 mtime 距今
+     ≥ `_GIT_LOCK_STALE_S`（300s，≫ 全部调用的 120s 超时上界）时清理（崩溃残留）；
+  ③ 其余一律不动（返回 "left"，人工核删指引保留）；清理动作记一行
+     `git_lock_cleared` 台账。
+
+断言（S1–S8）：
+  S1 无锁 → "absent"；S2 **新锁未超龄 → "left" 且文件完好（防一刀切）**；
+  S3 超龄锁 → "cleared" 且文件删除；S4 force 对新锁 → 立清（超时 kill 时机）；
+  S5 台账两行 `git_lock_cleared` 可读、含 age_s/force；
+  S6 `_git` 前置巡检清超龄锁（走公共出口）；S7 前置巡检不误删新锁；
+  S8 超时路径：`subprocess.run` 抛 `TimeoutExpired`（monkeypatch）→ 抛
+     `SleepGitTimeout`、消息带「已自动清理」读数、先前新锁已被 force 清。
+
+隔离：`MDCG_STATE_ROOT`/`MDCG_ROOT`/`MDCG_AUX_ROOT` 全指临时目录（台账亦落
+临时根，绝不触在役状态面）；monkeypatch 在 finally 里还原。
+运行：python -X utf8 -m md_cg.test_sleep_gitlock
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+
+from . import sleep as S
+
+_saved = {}
+_ok = 0
+_fail = []
+
+
+def _sandbox():
+    for k in ("MDCG_STATE_ROOT", "MDCG_ROOT", "MDCG_AUX_ROOT"):
+        _saved[k] = os.environ.get(k)
+    gen = tempfile.mkdtemp(prefix="mdcg_gitlock_")
+    os.environ["MDCG_STATE_ROOT"] = os.path.join(gen, "state")
+    os.environ["MDCG_ROOT"] = os.path.join(gen, "root")
+    os.environ["MDCG_AUX_ROOT"] = os.path.join(gen, "aux")
+    return gen
+
+
+def _restore():
+    for k, v in _saved.items():
+        if v is None:
+            os.environ.pop(k, None)
+        else:
+            os.environ[k] = v
+
+
+def check(name, cond, detail=""):
+    global _ok
+    if cond:
+        _ok += 1
+        print("[ok] " + name)
+    else:
+        _fail.append(name)
+        print("[FAIL] %s  · %s" % (name, str(detail)[:240]))
+
+
+def _put_lock(d, age_s=0.0):
+    p = os.path.join(d, S._GIT_LOCK_NAME)
+    with open(p, "w", encoding="utf-8") as f:
+        f.write("")
+    if age_s:
+        t = time.time() - age_s
+        os.utime(p, (t, t))
+    return p
+
+
+gen = _sandbox()
+gdir = os.path.join(gen, "gitdir")
+os.makedirs(gdir)
+try:
+    check("S1 无锁 → absent", S._clear_git_lock(gdir) == "absent")
+
+    p2 = _put_lock(gdir)
+    check("S2 新锁未超龄 → left 且保持在场（防一刀切）",
+          S._clear_git_lock(gdir) == "left" and os.path.exists(p2))
+
+    p3 = _put_lock(gdir, age_s=S._GIT_LOCK_STALE_S + 60)
+    check("S3 超龄锁 → cleared 且文件删除",
+          S._clear_git_lock(gdir) == "cleared" and not os.path.exists(p3))
+
+    p4 = _put_lock(gdir)
+    check("S4 force 对新锁立清（超时 kill 后时机）",
+          S._clear_git_lock(gdir, force=True) == "cleared"
+          and not os.path.exists(p4))
+
+    rows = [r for r in S.read_ledger() if r.get("event") == "git_lock_cleared"]
+    check("S5 台账两行 git_lock_cleared（age_s/force 在场）",
+          len(rows) == 2 and all("age_s" in r and "force" in r for r in rows),
+          rows)
+
+    p6 = _put_lock(gdir, age_s=S._GIT_LOCK_STALE_S + 60)
+    S._git(gdir, gen, "rev-parse", "--git-dir")     # rc 不论；重点＝前置巡检
+    check("S6 _git 前置巡检清超龄锁（公共出口生效）", not os.path.exists(p6))
+
+    p7 = _put_lock(gdir)
+    S._git(gdir, gen, "rev-parse", "--git-dir")
+    check("S7 _git 前置巡检不误删新锁（年龄闸）", os.path.exists(p7))
+
+    real_run = subprocess.run
+
+    def _boom(*a, **kw):
+        raise subprocess.TimeoutExpired(cmd="git boom",
+                                        timeout=S._GIT_TIMEOUT_S)
+
+    subprocess.run = _boom
+    msg = ""
+    try:
+        S._git(gdir, gen, "status")
+    except S.SleepGitTimeout as e:
+        msg = str(e)
+    finally:
+        subprocess.run = real_run
+    check("S8 超时→SleepGitTimeout；消息带处置读数且新锁被 force 清",
+          "残留锁处置" in msg and "已自动清理" in msg and not os.path.exists(p7),
+          msg)
+finally:
+    _restore()
+    shutil.rmtree(gen, ignore_errors=True)
+
+print("=" * 58)
+print("test_sleep_gitlock: %d 通过 / %d 失败" % (_ok, len(_fail)))
+if _fail:
+    print("失败项：" + "、".join(_fail))
+raise SystemExit(1 if _fail else 0)