foxclaw 0.1.0 → 0.1.3

package/python/tests/test_negotiation.py

@@ -0,0 +1,136 @@
+"""智能体层深化·跨域协商闭环:被守门人拒 → 发起方降标准重报 → 再裁决。
+
+原缺口:cross_request 是**一次性**的(路由→拿裁决→return)。「下周去上海出差」→ 行程排程
+→ 财务守门人预算不足 → rejected → **到此为止**,用户只拿到一句"被拒绝"。
+
+安全不变量(比功能更重要):
+  · 裁决权仍在目标 Agent 的守门人,协商**不得成为绕过手段**
+  · 协商失败**维持 rejected**,绝不降级成 needs_confirmation(否则等于开了个点穿守门人的口子)
+  · 有界 + 必须真让步(否则无限贴红线试探)
+"""
+import os, sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+def test_negotiation():
+    os.environ["HKC_EMBEDDING"] = "stub"
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+
+    from foxclaw.orchestration import CrossAgentRequest, Orchestrator
+
+    print("=" * 60); print("跨域协商闭环验证"); print("=" * 60)
+
+
+    class _Gate:
+        """假目标 Agent:预算 <= limit 才批(模拟财务守门人)。"""
+        def __init__(self, limit): self.limit = limit; self.seen = []
+        def handle_cross_request(self, req):
+            amt = float(req.payload.get("amount", 0))
+            self.seen.append(amt)
+            if amt <= self.limit:
+                req.status = "approved"; req.verdict = f"预算 {amt:.0f} 在额度内"
+            else:
+                req.status = "rejected"; req.verdict = f"预算不足:申请 {amt:.0f} > 可用 {self.limit:.0f}"
+
+
+    class _Requester:
+        """假发起方:每轮降 25%,夹到原始的 floor 倍;到底则认输(与 AdminAgent.concede 同款)。"""
+        def __init__(self, floor=0.6): self.floor = floor; self.calls = 0
+        def concede(self, req, verdict):
+            self.calls += 1
+            amt = float(req.payload.get("amount", 0))
+            orig = float(req.payload.get("_original_amount") or amt)
+            new = max(round(amt * 0.75), round(orig * self.floor))
+            if new <= 0 or new >= amt:
+                return None
+            p = dict(req.payload); p["amount"] = new; p["_original_amount"] = orig
+            return p
+
+
+    class _Caps:
+        """假能力注册中枢:Orchestrator 经它惰性解析 agents(P1-3 打断对象环)。"""
+        def __init__(self, agents): self._a = agents
+        def get(self, name): return self._a if name == "agents" else None
+
+
+    def _orch(agents):
+        return Orchestrator(_Caps(agents))
+
+
+    def _req(amount=8000):
+        return CrossAgentRequest(from_agent="admin", to_agent="finance",
+                                 request_type="budget_request", payload={"amount": amount})
+
+
+    gate = _Gate(limit=5000); r = _orch({"finance": gate, "admin": _Requester()})
+    req = r.negotiate(_req(8000))
+    assert req.status == "approved", (req.status, req.verdict)
+    assert req.payload["amount"] <= 5000, req.payload
+    assert len(req.negotiation) >= 2, "应发生过至少一轮让步"
+    assert gate.seen[0] == 8000 and gate.seen[-1] <= 5000, gate.seen
+    print(f"[1] 被拒→让步→通过({' → '.join(str(int(a)) for a in gate.seen)})OK")
+
+    n = req.negotiation
+    assert n[0]["status"] == "rejected" and "conceded_to" in n[0], n[0]
+    assert n[-1]["status"] == "approved", n[-1]
+    print(f"[2] 协商日志可追溯({len(n)} 轮,含每轮裁决与让步)OK")
+
+    gate2 = _Gate(limit=100); r2 = _orch({"finance": gate2, "admin": _Requester()})
+    req2 = r2.negotiate(_req(8000))
+    assert req2.status == "rejected", f"协商失败必须维持 rejected,不得降级: {req2.status}"
+    print("[3] 让无可让 → 维持 rejected(不给点穿守门人的口子)OK")
+
+    gate3 = _Gate(limit=1); r3 = _orch({"finance": gate3, "admin": _Requester(floor=0.0)})
+    req3 = r3.negotiate(_req(8000), max_rounds=3)
+    assert len(gate3.seen) <= 3, f"轮数应有界: {gate3.seen}"
+    assert req3.status == "rejected"
+    print(f"[4] 有界协商(裁决 {len(gate3.seen)} 次 ≤ max_rounds=3)OK")
+
+    class _NoOp:
+        def concede(self, req, verdict): return dict(req.payload)
+    gate4 = _Gate(limit=1); r4 = _orch({"finance": gate4, "admin": _NoOp()})
+    r4.negotiate(_req(8000), max_rounds=5)
+    assert len(gate4.seen) == 1, f"无实质让步应只裁决一次: {gate4.seen}"
+    print("[5] 假让步(payload 无变化)→ 立即停,不重复轰炸守门人 OK")
+
+    class _Silent:
+        def concede(self, req, verdict): return None
+    gate5 = _Gate(limit=1); r5 = _orch({"finance": gate5, "admin": _Silent()})
+    req5 = r5.negotiate(_req(8000))
+    assert len(gate5.seen) == 1 and req5.status == "rejected"
+    print("[6] 未实现让步的 Agent → 只跑一轮(零行为变更)OK")
+
+    class _Boom:
+        def concede(self, req, verdict): raise RuntimeError("concede 崩了")
+    gate6 = _Gate(limit=1); r6 = _orch({"finance": gate6, "admin": _Boom()})
+    req6 = r6.negotiate(_req(8000))
+    assert req6.status == "rejected", "发起方 concede 崩溃不得影响裁决"
+    assert any("concede_error" in x for x in req6.negotiation)
+    print("[7] 让步逻辑崩溃 → 维持 rejected + 记录错误 OK")
+
+    from foxclaw.agents.agents import OfficeAgent
+    adm = OfficeAgent.__new__(OfficeAgent)
+
+    p = adm.concede(_req(1000), "预算不足")
+    assert p and p["amount"] == 750 and "降标准" in p["_concession"], p
+    seq, cur = [1000], _req(1000).payload
+    while True:
+        nxt = adm.concede(_req(0).__class__(from_agent="admin", to_agent="finance",
+                                            request_type="budget_request", payload=dict(cur)), "拒")
+        if nxt is None:
+            break
+        assert nxt["amount"] < cur["amount"], "让步必须单调下降"
+        cur = nxt; seq.append(cur["amount"])
+        assert len(seq) < 20, "让步链必须终止"
+    assert seq[-1] == 600, f"应走到下限 600(原始 1000 的 60%),实际 {seq}"
+    print(f"[8] OfficeAgent 让步链 {seq} → 到下限认输(单调下降·必然终止)OK")
+
+    other = CrossAgentRequest(from_agent="admin", to_agent="office",
+                              request_type="knowledge_request", payload={"q": "x"})
+    assert adm.concede(other, "拒") is None
+    print("[9] 非 budget_request → 不插手(回退默认)OK")
+
+    print("\n跨域协商闭环验证全部通过")
+
+if __name__ == "__main__":
+    test_negotiation()

package/python/tests/test_orchestration.py

@@ -0,0 +1,109 @@
+"""
+主管编排测试 — 全局态势 + 跨 Agent 编排
+核心场景:行程 Agent 规划出差 → 主管发起差旅预算申请 →
+         财务守门人裁决(够不够/要不要确认/否决)。
+这把三个独立内核真正串成一个有机系统。
+"""
+import sys, os, tempfile
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+os.environ["FOXCLAW_SHADOW_ROUNDS"] = "50"
+
+import asyncio
+from foxclaw import Foxclaw
+
+
+def check(cond, msg):
+    if not cond:
+        raise AssertionError(f"✗ {msg}")
+    print(f"  ✓ {msg}")
+
+
+async def main():
+    print("=" * 60)
+    print("主管编排 · 全局态势 + 跨 Agent 协调")
+    print("=" * 60)
+    _data = tempfile.mkdtemp(prefix="foxclaw_orch_")
+    os_ = Foxclaw(data_dir=_data, shadow_rounds=50)
+
+    fin = os_.finance_runtime
+    fin.set_budget("travel", 3000)
+    fin.set_balance("default", 5000)
+    fin.import_csv(str(Path(__file__).parent.parent / "examples" / "sample_transactions.csv"))
+
+    learn = os_.learning_runtime
+    learn.import_csv(str(Path(__file__).parent.parent / "examples" / "sample_knowledge.csv"))
+
+    itin = os_.itinerary_runtime
+    itin.import_csv(str(Path(__file__).parent.parent / "examples" / "sample_itinerary.csv"))
+
+    print("\n【1】主管全局态势(驾驶舱视图)")
+    sit = os_.supervisor.global_situation()
+    print(f"  财务: {sit['finance']}")
+    print(f"  学习: {sit['learning']}")
+    print(f"  行程: {sit['itinerary']}")
+    print(f"  跨域告警 {len(sit['alerts'])} 条:")
+    for a in sit["alerts"][:5]:
+        print(f"    [{a['severity']}] ({a['domain']}) {a['msg']}")
+    check(sit["finance"]["transactions"] == 13, f"财务态势反映 13 笔导入交易(实为 {sit['finance']['transactions']})")
+    check(sit["learning"]["total_items"] == 8, f"学习态势反映 8 个知识点(实为 {sit['learning']['total_items']})")
+    check(sit["itinerary"]["waypoints"] == 5, f"行程态势反映 5 个行程点(实为 {sit['itinerary']['waypoints']})")
+    sev = {a["severity"] for a in sit["alerts"]}
+    check(len(sit["alerts"]) >= 2 and "critical" in sev,
+          f"跨域告警被汇总且含 critical(实为 {sorted(sev)})")
+
+    print("\n【2】跨 Agent 编排:行程→财务 差旅预算申请(小额)")
+    r1 = os_.supervisor.cross_request(
+        from_agent="admin", to_agent="finance", request_type="budget_request",
+        payload={"amount": 150, "category": "travel", "entity": "高铁票", "account": "default"},
+        reason="出差北京高铁票")
+    print(f"  申请: 差旅 150 元 → 状态【{r1['status']}】")
+    print(f"  财务裁决: {r1['verdict']}")
+    check(r1["status"] == "approved",
+          f"小额(150)且在预算内 → 直接批准(实为 {r1['status']})")
+
+    print("\n【3】跨 Agent 编排:大额差旅(触发守门人)")
+    r2 = os_.supervisor.cross_request(
+        from_agent="admin", to_agent="finance", request_type="budget_request",
+        payload={"amount": 680, "category": "travel", "entity": "商务酒店", "account": "default"},
+        reason="出差住宿3晚")
+    print(f"  申请: 差旅 680 元 → 状态【{r2['status']}】")
+    print(f"  财务裁决: {r2['verdict']}")
+    check(r2["status"] == "needs_confirmation",
+          f"大额(680>500) → 转人工确认(实为 {r2['status']})")
+    check(r1["status"] != r2["status"], "金额不同 → 裁决结论确实不同(150 批准 / 680 待确认)")
+
+    print("\n【4】跨 Agent 编排:日程占用申请→行政检查冲突")
+    r3 = os_.supervisor.cross_request(
+        from_agent="assistant", to_agent="admin", request_type="schedule_request",
+        payload={"start_time": "2026-06-10T10:30:00", "title": "临时电话会"},
+        reason="客户临时约电话会")
+    print(f"  申请: 10:30 电话会 → 状态【{r3['status']}】")
+    print(f"  行政裁决: {r3['verdict']}")
+    check(r3["status"] == "needs_confirmation",
+          f"与既有行程时段冲突 → 转人工确认(实为 {r3['status']})")
+
+    print("\n【5】目标 Agent 不存在 → 必须转人工(不得默认放行)")
+    r4 = os_.supervisor.cross_request(
+        from_agent="admin", to_agent="不存在的Agent", request_type="budget_request",
+        payload={"amount": 1, "category": "travel", "entity": "x", "account": "default"},
+        reason="路由到不存在的目标")
+    print(f"  申请 → 状态【{r4['status']}】")
+    print(f"  裁决: {r4['verdict']}")
+    check(r4["status"] == "needs_confirmation",
+          f"目标不存在 → needs_confirmation 而非默认放行(实为 {r4['status']})")
+
+    import shutil
+    shutil.rmtree(_data, ignore_errors=True)
+
+    print("\n" + "=" * 60)
+    print("✓ 主管编排验证完成:全局态势 + 跨 Agent 守门人协调成立")
+    print("=" * 60)
+
+
+def test_orchestration():
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/python/tests/test_orchestration_decoupled.py

@@ -0,0 +1,103 @@
+"""
+编排层去领域硬编码(P3)测试 —— 全离线。
+
+审计:Orchestrator 的 _handle_budget_request/_handle_schedule_request + gather_situation
+硬编码了 finance/learning/itinerary 内核内部 API(SRP 违反,编排层懂领域)。
+修复:领域知识下沉到各领域 Agent(situation()/handle_cross_request()),编排层只做
+通用聚合(逐个 agent.situation())+ 通用路由(dispatch 到 target.handle_cross_request())。
+
+覆盖:
+  1. 结构去耦:Orchestrator 删除 _handle_* 领域方法;编排层源码零领域内核 API 引用
+  2. 领域逻辑归属 Agent:finance/admin 有 handle_cross_request,base 默认放行
+  3. 行为保持:态势聚合 + 小额批准/大额确认/日程冲突确认(裁决与原一致)
+  4. 通用性:路由到不存在的 Agent → 转人工确认(P1-0 修 fail-open,仍不崩)
+"""
+import os, sys, asyncio, tempfile, shutil
+from pathlib import Path
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+os.environ["FOXCLAW_EMBEDDING_MODEL"] = "foxclaw-nonexistent-fast"
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+def test_structural_decoupling():
+    print("\n【1】结构去耦:编排层无领域方法/无领域内核 API 引用")
+    from foxclaw.orchestration import Orchestrator
+    assert not hasattr(Orchestrator, "_handle_budget_request"), "编排层不应再有 _handle_budget_request"
+    assert not hasattr(Orchestrator, "_handle_schedule_request"), "编排层不应再有 _handle_schedule_request"
+    src = Path("foxclaw/orchestration/__init__.py").read_text(encoding="utf-8")
+    for banned in ("budget_status", "detect_conflicts", "due_items", "Transaction",
+                   ".waypoints", ".policy", "review_states"):
+        assert banned not in src, f"编排层仍引用领域内核 API: {banned}"
+    print("  ✓ 删除 _handle_*;源码零领域内核 API 引用")
+
+
+def test_domain_logic_in_agents():
+    print("\n【2】领域逻辑归属 Agent(situation / handle_cross_request)")
+    from foxclaw.agents.agents import FinanceAgent, OfficeAgent
+    from foxclaw.agents.base import CognitiveAgent
+    assert FinanceAgent.handle_cross_request is not CognitiveAgent.handle_cross_request
+    assert OfficeAgent.handle_cross_request is not CognitiveAgent.handle_cross_request
+    assert FinanceAgent.situation is not CognitiveAgent.situation
+    assert OfficeAgent.situation is not CognitiveAgent.situation
+    print("  ✓ finance/admin 覆盖 handle_cross_request;finance/admin/office 覆盖 situation")
+
+
+def test_behavior_and_generic_routing():
+    print("\n【3】行为保持 + 通用路由")
+    d = tempfile.mkdtemp(prefix="p3_")
+    try:
+        from foxclaw import Foxclaw
+        os_ = Foxclaw(data_dir=d, shadow_rounds=50)
+        fin = os_.finance_runtime
+        fin.set_budget("travel", 3000); fin.set_balance("default", 5000)
+        fin.import_csv(str(Path("examples/sample_transactions.csv")))
+        os_.learning_runtime.import_csv(str(Path("examples/sample_knowledge.csv")))
+        os_.itinerary_runtime.import_csv(str(Path("examples/sample_itinerary.csv")))
+
+        sit = os_.supervisor.global_situation()
+        assert set(sit["finance"]) >= {"transactions"} and "total_items" in sit["learning"]
+        assert "waypoints" in sit["itinerary"]
+        print(f"  ✓ 态势聚合: fin={sit['finance']}, learn.items={sit['learning']['total_items']}, "
+              f"itin.wp={sit['itinerary']['waypoints']}, alerts={len(sit['alerts'])}")
+
+        r_small = os_.supervisor.cross_request("admin", "finance", "budget_request",
+            {"amount": 150, "category": "travel", "entity": "高铁", "account": "default"}, "小额")
+        r_big = os_.supervisor.cross_request("admin", "finance", "budget_request",
+            {"amount": 680, "category": "travel", "entity": "酒店", "account": "default"}, "大额")
+        r_sched = os_.supervisor.cross_request("assistant", "admin", "schedule_request",
+            {"start_time": "2026-06-10T10:30:00", "title": "电话会"}, "占日程")
+        assert r_small["status"] == "approved", r_small
+        assert r_big["status"] in ("needs_confirmation", "rejected"), r_big
+        assert r_sched["status"] in ("needs_confirmation", "approved"), r_sched
+        print(f"  ✓ 小额={r_small['status']} 大额={r_big['status']} 日程={r_sched['status']}(委托目标守门人)")
+
+        r_unknown = os_.supervisor.cross_request("x", "nonexistent", "budget_request", {}, "未知目标")
+        assert r_unknown["status"] == "needs_confirmation", r_unknown
+        assert "不存在" in r_unknown["verdict"]
+        print(f"  ✓ 路由到不存在 Agent → {r_unknown['status']}(不再 fail-open 放行,仍不崩)")
+
+        r_bad = os_.supervisor.cross_request("x", "admin", "schedule_request",
+            {"start_time": "不是合法时间"}, "畸形时间")
+        assert r_bad["status"] == "needs_confirmation", f"裁决崩溃应 fail-safe,实得 {r_bad}"
+        assert "转人工" in r_bad["verdict"]
+        print(f"  ✓ 畸形 payload 让守门人裁决崩溃 → {r_bad['status']}(fail-safe,不 fail-open 放行)")
+        asyncio.run(os_.aclose())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def main():
+    print("=" * 60)
+    print("编排层去领域硬编码 · 改委托(P3)")
+    print("=" * 60)
+    test_structural_decoupling()
+    test_domain_logic_in_agents()
+    test_behavior_and_generic_routing()
+    print("\n" + "=" * 60)
+    print("✓ P3 验证完成:编排层通用聚合/路由,领域知识归属领域 Agent")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_p3_p5_hardening.py

@@ -0,0 +1,324 @@
+"""批次 7 · P3 收尾 + P4/P5 小项测试
+
+  [1] P3-1:_constant_time_eq 行为(等/不等/空/None 兜底)
+  [2] P3-8:_is_guarded_path 行为
+  [3] P3-1+P3-8 接线防退化:两个中间件 + WS 端点统一走辅助函数(源码级)
+  [4] P3-7:knowledge_ability 异常分类——isinstance 精确 / 真 HKC 异常证据 gate / 回退鸭子判断
+  [5] P3-5:blocked 任务只留审计 trace + truth.skipped,不发 truth.appended、不沉淀(含正常对照)
+  [6] P3-0:真值沉淀 agent_id="system" + origin tag 追溯
+  [7] P3-6/P4-1:SystemBus exact 订阅/前缀默认/history exact + TruthPipeline 不被前缀事件干扰
+  [8] P5-3:ProcessManager._transition 终态守卫(幂等忽略不重复 -1;非终态非法跳转仍抛)
+  [9] P5-1:PermissionDecision.reason_code 五码分类 + 非 ask 留空 + to_dict 携带
+"""
+import asyncio
+import inspect
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+FAILS = []
+
+
+def check(cond, label):
+    if cond:
+        print(f"  ✓ {label}")
+    else:
+        FAILS.append(label)
+        print(f"  ✗ {label}")
+
+
+os.environ["FOXCLAW_SKIP_DOTENV"] = "1"
+os.environ.setdefault("FOXCLAW_EMBEDDING_MODEL", "foxclaw-nonexistent-fast")
+os.environ["FOXCLAW_DATA_DIR"] = tempfile.mkdtemp(prefix="foxclaw_b7_")
+for _k in ("DEEPSEEK_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY",
+           "GOOGLE_API_KEY", "DASHSCOPE_API_KEY", "FOXCLAW_API_KEY"):
+    os.environ[_k] = ""
+
+
+def test_helpers():
+    print("\n【1】P3-1:_constant_time_eq 常量时间比较")
+    from foxclaw.api import _constant_time_eq, _is_guarded_path
+    check(_constant_time_eq("abc", "abc") is True, "相同字符串相等")
+    check(_constant_time_eq("abc", "abd") is False, "末位不同不等")
+    check(_constant_time_eq("abc", "abcd") is False, "长度不同不等")
+    check(_constant_time_eq("", "") is True, "双空相等")
+    check(_constant_time_eq("", "abc") is False, "空与非空不等")
+    check(_constant_time_eq(None, "abc") is False, "None 由 or '' 兜底(不崩)")
+    check(_constant_time_eq("密钥含中文", "密钥含中文") is True,
+          "非 ASCII(utf-8 编码后比较)可用")
+
+    print("\n【2】P3-8:_is_guarded_path 受保护路径判断")
+    check(_is_guarded_path("/api/status") is True, "/api/* 受保护")
+    check(_is_guarded_path("/knowledge/graph") is True, "/knowledge/* 受保护")
+    check(_is_guarded_path("/health") is False, "/health 探针不受保护")
+    check(_is_guarded_path("/") is False, "/ 前端不受保护")
+    check(_is_guarded_path("/docs") is False, "/docs 不受保护")
+
+
+def test_wiring_source():
+    print("\n【3】P3-1+P3-8 接线防退化:中间件/WS 统一走辅助函数(源码级断言)")
+    import foxclaw.api as api_mod
+
+    src_guard = inspect.getsource(api_mod._api_key_guard)
+    check("_is_guarded_path(path)" in src_guard, "_api_key_guard 用 _is_guarded_path")
+    check("_constant_time_eq(" in src_guard, "_api_key_guard 用 _constant_time_eq")
+    check('startswith("/api")' not in src_guard, "_api_key_guard 无残留 startswith 直写")
+
+    src_gw = inspect.getsource(api_mod._gateway_mw)
+    check("_is_guarded_path(path)" in src_gw, "_gateway_mw 用 _is_guarded_path")
+    check("_constant_time_eq(hdr, valid)" in src_gw, "_gateway_mw 客户识别用常量时间比较")
+    check("hdr == valid" not in src_gw, "_gateway_mw 无残留普通 ==")
+
+    src_trace = inspect.getsource(api_mod._trace_mw)
+    check("_is_guarded_path(path)" in src_trace, "_trace_mw 用 _is_guarded_path")
+
+    src_ws = inspect.getsource(api_mod.harness_websocket)
+    check("_constant_time_eq(" in src_ws, "WS 端点鉴权用 _constant_time_eq")
+    check("provided != api_key" not in src_ws, "WS 端点无残留 !=")
+
+
+def _run_ability_with(exc):
+    """用抛指定异常的假 HKC 驱动 knowledge_ability 端点,返回 (status, body)。"""
+    import foxclaw.api as api_mod
+    from types import SimpleNamespace
+
+    class _Client:
+        def compile_ability(self, key):
+            raise exc
+
+    fake_hkc = SimpleNamespace(available=True, client=_Client())
+    old_os = api_mod._state.current_os()
+    api_mod._state.set_os_instance(SimpleNamespace(hkc=fake_hkc))
+    try:
+        try:
+            body = asyncio.run(api_mod.knowledge_ability("any_key"))
+            return 200, body
+        except Exception as e:
+            from fastapi import HTTPException
+            if isinstance(e, HTTPException):
+                return e.status_code, {"detail": e.detail}
+            raise
+    finally:
+        api_mod._state.set_os_instance(old_os)
+
+
+def test_ability_isinstance():
+    print("\n【4】P3-7:knowledge_ability 异常分类(isinstance 精确 + 回退)")
+    import foxclaw.api as api_mod
+
+    check(api_mod._HKCInsuffCov is not None, "vendor 下 hkc_sdk.exceptions 可 import")
+
+    from hkc_sdk.exceptions import HKCInsufficientCoverage
+    try:
+        raise HKCInsufficientCoverage("覆盖不足测试")
+    except HKCInsufficientCoverage as e:
+        if not hasattr(e, "missing_skills"):
+            e.missing_skills = ["s1"]
+        if not hasattr(e, "coverage"):
+            e.coverage = {"a": 0.5}
+        status, body = _run_ability_with(e)
+    check(status == 200 and body.get("sufficient") is False,
+          f"真 HKC 覆盖不足 → 证据 gate(实为 {status}: {str(body)[:80]})")
+
+    class _FakeInsuff(Exception):
+        def __init__(self):
+            super().__init__("鸭子异常")
+            self.missing_skills = ["s1"]
+            self.coverage = {}
+
+    status, body = _run_ability_with(_FakeInsuff())
+    check(status == 404,
+          f"isinstance 模式:鸭子异常不再误判为覆盖不足(实为 {status})")
+
+    old = api_mod._HKCInsuffCov
+    api_mod._HKCInsuffCov = None
+    try:
+        status, body = _run_ability_with(_FakeInsuff())
+        check(status == 200 and body.get("sufficient") is False,
+              f"import 失败回退 hasattr → 证据 gate(实为 {status})")
+        status2, _ = _run_ability_with(RuntimeError("普通错误"))
+        check(status2 == 404, "回退模式下普通异常仍 404")
+    finally:
+        api_mod._HKCInsuffCov = old
+
+
+class _MockHMR:
+    def __init__(self):
+        self.calls = []
+
+    def ingest(self, content, **kw):
+        self.calls.append((content, kw))
+
+
+def _make_pipeline():
+    from foxclaw.core.system_bus import SystemBus
+    from foxclaw.core.truth_pipeline import TruthPipeline
+    bus = SystemBus()
+    events = []
+    for ch in ("trace.recorded", "truth.appended", "truth.skipped", "memory.updated"):
+        bus.subscribe(ch, lambda m, _c=ch: events.append(_c))
+    hmr = _MockHMR()
+    TruthPipeline(bus, hmr=hmr)
+    return bus, events, hmr
+
+
+def test_truth_blocked_skipped():
+    print("\n【5】P3-5:blocked 任务不进真值链")
+    bus, events, hmr = _make_pipeline()
+    bus.publish("execution.completed", {"agent_id": "finance", "task": "危险操作",
+                                        "result": "x", "blocked": True})
+    check("trace.recorded" in events, "blocked 仍发 trace.recorded(审计留痕)")
+    check("truth.skipped" in events, "blocked 发 truth.skipped(可观测)")
+    check("truth.appended" not in events, "blocked 不发 truth.appended(不进真值链)")
+    check("memory.updated" not in events, "blocked 不发 memory.updated")
+    check(hmr.calls == [], "blocked 不沉淀 HMR")
+
+    print("  —— 正常任务对照 ——")
+    bus2, events2, hmr2 = _make_pipeline()
+    bus2.publish("execution.completed", {"agent_id": "finance", "task": "正常任务",
+                                         "result": "ok", "blocked": False})
+    check("truth.appended" in events2, "正常任务发 truth.appended")
+    check("truth.skipped" not in events2, "正常任务不发 truth.skipped")
+    check(len(hmr2.calls) == 1, "正常任务沉淀 HMR ×1")
+
+
+def test_truth_system_attribution():
+    print("\n【6】P3-0:真值沉淀系统级归因")
+    bus, events, hmr = _make_pipeline()
+    bus.publish("execution.completed", {"agent_id": "finance", "task": "预算分析",
+                                        "result": "正常", "blocked": False})
+    check(len(hmr.calls) == 1, "真值沉淀 1 次")
+    kw = hmr.calls[0][1]
+    check(kw.get("agent_id") == "system",
+          f"写共享层 agent_id=system(实为 {kw.get('agent_id')!r})")
+    check("origin:finance" in (kw.get("tags") or []),
+          "来源 Agent 保留在 origin tag")
+    check("truth_pipeline" in (kw.get("tags") or []),
+          "truth_pipeline facet 保留(策略豁免通道)")
+    check(kw.get("shared") is True, "仍写共享层")
+
+
+def test_system_bus_exact():
+    print("\n【7】P3-6/P4-1:SystemBus exact 参数")
+    from foxclaw.core.system_bus import SystemBus
+
+    bus = SystemBus()
+    received = []
+    bus.subscribe("execution.completed", lambda m: received.append(m.topic), exact=True)
+    bus.publish("execution.completed", {})
+    bus.publish("execution.completed.extra", {})
+    bus.publish("execution.failed", {})
+    check(received == ["execution.completed"],
+          f"exact=True 只收精确 topic(实为 {received})")
+
+    bus2 = SystemBus()
+    received2 = []
+    bus2.subscribe("execution", lambda m: received2.append(m.topic))
+    bus2.publish("execution.completed", {})
+    bus2.publish("execution.failed", {})
+    check(set(received2) == {"execution.completed", "execution.failed"},
+          "默认前缀匹配(行为不变)")
+
+    bus3 = SystemBus()
+    bus3.publish("execution.completed", {})
+    bus3.publish("execution.completed.extra", {})
+    bus3.publish("execution.failed", {})
+    h = bus3.history("execution.completed", exact=True)
+    topics = [(e.get("topic") or e.get("channel")) for e in h]
+    check(topics == ["execution.completed"],
+          f"history exact=True 只回精确项(实为 {topics})")
+    h2 = bus3.history("execution.completed")
+    check(len(h2) == 2, "history 默认前缀匹配(含 .extra)")
+
+    print("  —— TruthPipeline 抗前缀干扰 ——")
+    bus4, events4, hmr4 = _make_pipeline()
+    bus4.publish("execution.completed.extra", {"task": "x", "result": "y"})
+    bus4.publish("execution.completed", {"agent_id": "t", "task": "t",
+                                         "result": "ok", "blocked": False})
+    check(len(hmr4.calls) == 1,
+          f"前缀事件 execution.completed.extra 不触发真值链(沉淀 {len(hmr4.calls)} 次)")
+
+
+def test_transition_terminal_guard():
+    print("\n【8】P5-3:ProcessManager._transition 终态守卫")
+    from foxclaw.kernel.process_manager import ProcessManager
+    pm = ProcessManager()
+    rec = pm.create("t1", agent_id="test")
+    pm.mark_running(rec.process_id)
+    pm.mark_completed(rec.process_id)
+    n = pm.active_count()
+    pm._transition(rec, "failed")
+    check(rec.state == "completed", "终态再流转 → 状态不变")
+    check(pm.active_count() == n, "终态再流转 → 活跃计数不重复 -1")
+    check(rec.state_history.count("completed") == 1, "终态再流转 → 历史不追加")
+    rec2 = pm.create("t2")
+    rec2.state = "created"
+    try:
+        pm._transition(rec2, "completed")
+        check(False, "非终态非法跳转应仍抛 ValueError")
+    except ValueError:
+        check(True, "非终态非法跳转(created→completed)仍抛 ValueError")
+
+
+def test_reason_code():
+    print("\n【9】P5-1:PermissionDecision.reason_code 分类")
+    from foxclaw.skills import SkillSpec
+    from foxclaw.skills.permission import (
+        evaluate, PermissionRules, MISSING_PARAMS, DESTRUCTIVE_CONFIRM,
+        SIDE_EFFECT_CONFIRM, ASK_RULE, EXTERNAL_CONFIRM)
+
+    def _mk(**kw):
+        base = dict(id="s1", name="s", description="d", kind="local",
+                    side_effect="read", handler=lambda: {})
+        base.update(kw)
+        return SkillSpec(**base)
+
+    d = evaluate(_mk(params={"q": {"required": True}}), {})
+    check(d.decision == "ask" and d.reason_code == MISSING_PARAMS,
+          f"缺必填参数 → ask + MISSING_PARAMS(实为 {d.reason_code!r})")
+
+    d = evaluate(_mk(destructive=True), {})
+    check(d.decision == "ask" and d.reason_code == DESTRUCTIVE_CONFIRM,
+          f"destructive → DESTRUCTIVE_CONFIRM(实为 {d.reason_code!r})")
+
+    d = evaluate(_mk(side_effect="write"), {})
+    check(d.decision == "ask" and d.reason_code == SIDE_EFFECT_CONFIRM,
+          f"write 副作用 → SIDE_EFFECT_CONFIRM(实为 {d.reason_code!r})")
+
+    d = evaluate(_mk(), {}, rules=PermissionRules(ask=["s1"]))
+    check(d.decision == "ask" and d.reason_code == ASK_RULE,
+          f"命中 ask 规则 → ASK_RULE(实为 {d.reason_code!r})")
+
+    d = evaluate(_mk(external=True), {})
+    check(d.decision == "ask" and d.reason_code == EXTERNAL_CONFIRM,
+          f"外部调用 → EXTERNAL_CONFIRM(实为 {d.reason_code!r})")
+
+    d = evaluate(_mk(), {})
+    check(d.decision == "allow" and d.reason_code == "",
+          "allow 侧 reason_code 留空(文稿未定义,不扩大枚举面)")
+    d = evaluate(_mk(), {}, rules=PermissionRules(deny=["s1"]))
+    check(d.decision == "deny" and d.reason_code == "",
+          "deny 侧 reason_code 留空(deny 语义已由 decision+stage 表达)")
+    d = evaluate(_mk(params={"q": {"required": True}}), {})
+    check(d.to_dict().get("reason_code") == MISSING_PARAMS, "to_dict 携带 reason_code")
+
+
+if __name__ == "__main__":
+    test_helpers()
+    test_wiring_source()
+    test_ability_isinstance()
+    test_truth_blocked_skipped()
+    test_truth_system_attribution()
+    test_system_bus_exact()
+    test_transition_terminal_guard()
+    test_reason_code()
+    print("\n" + "=" * 60)
+    if FAILS:
+        print(f"✗ 批次7 共 {len(FAILS)} 项失败:")
+        for f in FAILS:
+            print(f"  - {f}")
+        sys.exit(1)
+    print("✓ 批次7 P3 收尾 + P4/P5 小项全部通过")