@furongjun1999/dsh-memory 0.5.0 → 0.5.1

package/md_cg/mcp_server.py

@@ -59,10 +59,11 @@ def _s(_desc, **props):
 
 
 # 生效条件：始终返回 {"type":t,"description":desc}，仅当 req 为真值时该字典额外含 "_req": True。
-def _p(t, desc, req=False):
+def _p(t, desc, req=False, **extra):
     d = {"type": t, "description": desc}
     if req:
         d["_req"] = True
+    d.update(extra)   # P2-22 前置（批次 24）：node_id 等可传 pattern/maxLength
     return d
 
 
@@ -106,7 +107,9 @@ TOOLS = [
                        "适用于写入情景层记忆时的筛选（未指定 layer 时默认 contextual）。"
                        "写入恒带会话身份（session）以区分不同会话的记忆；省略则归因到"
                        "进程/环境身份。",
-        "inputSchema": _s("", node_id=_p("string", "节点 id（省略则自动生成）"),
+        "inputSchema": _s("", node_id=_p("string", "节点 id（省略则自动生成）",
+                                         pattern="^[A-Za-z0-9_.@\u4e00-\u9fff,-]{1,128}$",
+                                         maxLength=128),
                           content=_p("string", "节点内容", True),
                           layer=_p("string", "层：anchor|structural|knowledge|contextual|self"),
                           role=_p("string", "角色：knowledge|user|assistant|tool-output|command|edit"
@@ -179,7 +182,10 @@ TOOLS = [
     },
     {
         "name": "mdcg_get",
-        "description": "按 id 读取一个记忆节点（frontmatter + content）。",
+        "description": "按 id 读取一个记忆节点（frontmatter + content）。"
+                       "id 不存在或密级不可读时返回 {ok:false, error:'not_found', "
+                       "readable_sensitivities, hint}（不再返回裸 null——"
+                       "调用方须能区分「没有」与「读不到」）。",
         "inputSchema": _s("", node_id=_p("string", "节点 id", True)),
     },
     {
@@ -191,10 +197,13 @@ TOOLS = [
     {
         "name": "mdcg_verify",
         "description": "验证单元：对节点做外部裁决 confirmed/weakened/falsified"
-                       "（falsified 会移入 rejected/ 负记忆）。",
+                       "（falsified 会移入 rejected/ 负记忆；受保护节点"
+                       " self/anchor 层、protected 标记、importance≥0.7 不可"
+                       "一键证伪删除，需显式 override=true，旧版本自动快照+留痕）。",
         "inputSchema": _s("", node_id=_p("string", "节点 id", True),
                           evidence=_p("string", "证据", True),
-                          verdict=_p("string", "confirmed|weakened|falsified", True)),
+                          verdict=_p("string", "confirmed|weakened|falsified", True),
+                          override=_p("boolean", "受保护节点需显式 true 才可证伪删除")),
     },
     {
         "name": "mdcg_flywheel",
@@ -233,7 +242,9 @@ TOOLS = [
     },
     {
         "name": "mdcg_review_decide",
-        "description": "审核裁决：accept / reject / edit / merge / noop（merge 需 merge_into）。"
+        "description": "审核裁决：accept / reject / edit / merge / noop（merge 需 merge_into；"
+                       "merge 与 add 同受写保护——目标层须可写，self/anchor/immutable "
+                       "目标需显式 override=true）。"
                        "noop=已评估、判定不改变任何现有记忆：只留痕并关闭提案，"
                        "不落业务节点、不进负记忆（与 reject 的区别是语义而非路径）。"
                        "redteam.verdict=reject 不落库，转 needs_reapproval，"
@@ -243,7 +254,8 @@ TOOLS = [
                           edits=_p("object", "edit 时的覆盖字段"), merge_into=_p("string", "merge 目标节点 id"),
                           reason=_p("string", "裁决理由"),
                           redteam=_p("object", "红队裁决 {verdict:pass|reject, issues:[], round:n}"),
-                          issues=_p("array", "问题清单（打回理由）")),
+                          issues=_p("array", "问题清单（打回理由）"),
+                          override=_p("boolean", "merge 进受保护目标需显式 true")),
     },
     {
         "name": "mdcg_review_records",
@@ -1084,6 +1096,15 @@ def _trust_state(fm):
         return None
 
 
+# 生效条件：cg 具有 whoami() 且其返回 dict 含 readable_sensitivities 时返回该值；cg 无该方法或抛异常时返回 None（不编造、不抛）。
+def _readable_sensitivities(cg):
+    """当前身份可读密级（whoami 同源；取不到返回 None，不编造）。"""
+    try:
+        return (cg.whoami() or {}).get("readable_sensitivities")
+    except Exception:
+        return None
+
+
 def _node_view(node, offset: int = 0):
     if not node:
         return None
@@ -2021,6 +2042,10 @@ def _cg_dispatch(cg, a):
                 limit=int(a.get("limit") or a.get("k") or 100))
         if act in ("export", "evidence_export"):
             from . import evidence as _ev
+            from .security import check_path_root
+            # P1-4（批次 26）：证据包写/读路径根约束（报告点名的
+            # 「link export 不经 require_admin → 任意文件写」缺口）
+            check_path_root(a.get("out"), "MDCG_EXPORT_ROOT", "link/export")
             subs = a.get("subjects") or a.get("subject")
             if isinstance(subs, str):
                 subs = [subs]
@@ -2034,6 +2059,9 @@ def _cg_dispatch(cg, a):
             return res
         if act in ("import", "evidence_import"):
             from . import evidence as _ev
+            from .security import check_path_root
+            check_path_root(a.get("path") or a.get("pack"),
+                            "MDCG_EXPORT_ROOT", "link/import")
             src = a.get("path") or a.get("pack")
             if isinstance(src, str) and src.lstrip().startswith("{"):
                 src = json.loads(src)
@@ -2123,7 +2151,9 @@ def _cg_dispatch(cg, a):
             return _node_view(cg.get(a["node_id"]),
                               offset=int(a.get("offset") or 0))
         q = a.get("query") or a.get("intent") or ""
-        if a.get("budget_tokens"):
+        # 显式 0 也是「显式」（2026-09-24 修复）：旧写法 `if a.get("budget_tokens")`
+        # 把 0 当没传，静默换成 1200 —— 调用方以为「零预算」拿到的是满预算结果。
+        if a.get("budget_tokens") is not None:
             return cg.recall(q, budget_tokens=int(a["budget_tokens"]),
                              k=int(a.get("k") or 20), context=a.get("context"),
                              goal_text=a.get("goal"),
@@ -2185,7 +2215,8 @@ def _cg_dispatch(cg, a):
 
     if op == "verify":
         return cg.verify(a.get("node_id", ""), a.get("evidence", ""),
-                         a.get("verdict", ""))
+                         a.get("verdict", ""),
+                         override=bool(a.get("override")))
 
     if op == "review":
         act = (a.get("action") or "list").strip().lower()
@@ -2205,7 +2236,8 @@ def _cg_dispatch(cg, a):
         return cg.review_decide(a.get("pid", ""), a.get("decision", ""),
                                 edits=a.get("edits"), merge_into=a.get("merge_into"),
                                 reason=a.get("reason", ""),
-                                redteam=a.get("redteam"), issues=a.get("issues"))
+                                redteam=a.get("redteam"), issues=a.get("issues"),
+                                override=bool(a.get("override")))
 
     if op == "forget":
         if (a.get("action") or "forget").strip().lower() == "restore":
@@ -2248,7 +2280,12 @@ def _cg_dispatch(cg, a):
 
     if op == "index_code":
         from . import refindex
+        from .security import check_path_root
         root = a.get("path") or cg.root
+        # P1-X：path 是模型可控输入——索引会读取目录下全部
+        # 命中文件。根白名单与 ingest 的 P1-4 同语义：显式 path 越界即拒；
+        # 未传（回落服务器侧 cg.root）不校验，默认部署行为不变。
+        check_path_root(a.get("path"), "MDCG_INGEST_ROOT", "index_code")
         if not os.path.isdir(root):
             return {"ok": False, "error": f"目录不存在：{root}"}
         items, errors, stats = refindex.index_dir(
@@ -2280,7 +2317,11 @@ def _cg_dispatch(cg, a):
 
     if op == "index_doc":
         from . import refindex
+        from .security import check_path_root
         root = a.get("path") or cg.root
+        # P1-X：与 index_code 同族——path 模型可控，根白名单
+        # 越界即拒；未传（回落 cg.root）不校验，默认部署行为不变。
+        check_path_root(a.get("path"), "MDCG_INGEST_ROOT", "index_doc")
         if not os.path.isdir(root):
             return {"ok": False, "error": f"目录不存在：{root}"}
         layer = a.get("layer") or "knowledge"
@@ -2542,7 +2583,9 @@ def _session_call(cg, a):
         return cg.session_recall(
             session=a.get("session"), limit=int(a.get("limit") or 5),
             recent_limit=int(a.get("recent_limit") or 10),
-            budget_tokens=int(a.get("budget_tokens") or 1200),
+            # `is not None`：显式 0 不再被吞成默认 1200（2026-09-24 修复）
+            budget_tokens=int(a["budget_tokens"])
+            if a.get("budget_tokens") is not None else 1200,
             include_state=bool(a.get("include_state", True)))
     if act == "compact":
         if a.get("note") and principal is not None \
@@ -2594,7 +2637,7 @@ def _skip_dirs_report(stats, limit=20):
     return out
 
 
-# 生效条件：act=(a.get("action") or "stat").strip().lower()；act 属 ("file","dir","jsonl") 且 principal 非 None 且其 can_write 为假时先 require_admin(f"ingest_{act}")，随后以 action=act 及各透传参数调 sources.run 并返回。
+# 生效条件：先经 check_path_root(a.get("path"), "MDCG_INGEST_ROOT", "ingest")（env 未设置或 path 空时放行，越界抛 PermissionError）；act=(a.get("action") or "stat").strip().lower()；act 属 ("file","dir","jsonl") 且 principal 非 None 且其 can_write 为假时先 require_admin(f"ingest_{act}")，随后以 action=act 及各透传参数调 sources.run 并返回。
 def _ingest_call(cg, a):
     """文件摄取分派（P0）：file / dir / jsonl / stat。
 
@@ -2602,7 +2645,11 @@ def _ingest_call(cg, a):
     支持 dry_run 预演（对应计划「可预演」要求）。
     """
     from . import sources
+    from .security import check_path_root
     act = (a.get("action") or "stat").strip().lower()
+    # P1-4（批次 26）：ingest 的 path 是模型可控输入——根白名单约束
+    # （MDCG_INGEST_ROOT 设置时越界即拒；未设置保持现状）
+    check_path_root(a.get("path"), "MDCG_INGEST_ROOT", "ingest")
     principal = getattr(cg, "principal", None)
     if act in ("file", "dir", "jsonl") and principal is not None \
             and not getattr(principal, "can_write", False):
@@ -2615,17 +2662,20 @@ def _ingest_call(cg, a):
         max_events=a.get("max_events"))
 
 
-# 生效条件：act=(a.get("action") or "stat").strip().lower()；principal 非 None 时一律先 require_admin(f"export_{act}")，随后以 include_content=True if a.get("include_content") is None else bool(a.get("include_content")) 等参数调 _ex.run 并返回。
+# 生效条件：先经 require_admin("export_{act}")（principal 非 None 时）与 check_path_root(a.get("out"), "MDCG_EXPORT_ROOT", "export")（env 未设置或 out 空时放行，越界抛 PermissionError）；act=(a.get("action") or "stat").strip().lower()；principal 非 None 时一律先 require_admin(f"export_{act}")，随后以 include_content=True if a.get("include_content") is None else bool(a.get("include_content")) 等参数调 _ex.run 并返回。
 def _export_call(cg, a):
     """全库导出（P0）：graph / nodes / slice / stat。
 
     导出整库属**管理操作** → 一律 require_admin（designer 专属）。
     """
     from . import export as _ex
+    from .security import check_path_root
     act = (a.get("action") or "stat").strip().lower()
     principal = getattr(cg, "principal", None)
     if principal is not None:
         principal.require_admin(f"export_{act}")
+    # P1-4（批次 26）：export 的 out 是写路径——根白名单约束
+    check_path_root(a.get("out"), "MDCG_EXPORT_ROOT", "export")
     inc = a.get("include_content")
     return _ex.run(
         cg, action=act, out=a.get("out"), ids=a.get("ids"),
@@ -2851,6 +2901,17 @@ def _ref_call(cg, a):
     if not ref:
         return {"ok": False,
                 "error": "该节点没有 code_ref/doc_ref（不是索引节点）"}
+    # P1-X（两份独立报告合并）：ref 回读是任意文件读原语——
+    # 自报 root、inline ref 自带的 root/path 均模型可控，probe_ref 直接
+    # os.path.join 后 open 全文回读（绝对 path 丢弃 root、'..' 上跳同漏）。
+    # 按最终将打开的完整路径过根白名单：env 未设置=放开（部署开关，与
+    # P1-4 的 ingest/export/link 同语义）；设置了=realpath 落根内否则拒
+    # （fail-closed），上跳与绝对路径在 realpath 归一后自然涵盖。
+    from .security import check_path_root
+    check_path_root(
+        os.path.join(a.get("root") or ref.get("root") or "",
+                     ref.get("path") or ""),
+        "MDCG_INGEST_ROOT", "ref")
     out = refindex.read_ref(ref, root=a.get("root"), ref_kind=ref_kind)
     out["node_id"] = nid or None
     return out
@@ -2942,17 +3003,17 @@ def call_tool(cg, name, args):
             scope = narrowed_principal(p, unit)
         except TokenError as e:
             return {"ok": False, "error": f"as_unit 非法：{e}"}
-    if sess:
-        import copy
-        scope = copy.copy(scope)     # 浅拷贝：会话只在本调用内生效，不污染共享 Principal
-        scope.session = sess
-    if scope is p:
+    # 请求级 session 只做**归因**（cg.session，写入归属/_attribution 取它），
+    # **不**改 principal.session——绑定档（private/secret）的读授权锚定连接级
+    # 身份（issue #35 会话隔离定稿：调用方自报的会话不得成为看他人 private
+    # 的授权；与上方「session 不参与任何 ops 裁决」的原设计意图一致）。
+    if scope is p and not sess:
         return _dispatch(cg, name, a)
     saved_p, saved_s = cg.principal, getattr(cg, "session", None)
     had_s = hasattr(cg, "session")
     cg.principal = scope             # 单线程 stdin 循环：无并发竞争
     if had_s:
-        cg.session = scope.session
+        cg.session = sess or scope.session
     try:
         return _dispatch(cg, name, a)
     finally:
@@ -2961,9 +3022,45 @@ def call_tool(cg, name, args):
             cg.session = saved_s
 
 
-# 生效条件：name 为已注册工具名之一（cg / stg / mdcg_whitebox / mdcg_service_info / mdcg_remember 等）；未识别的 name 返回含 error 的响应字典而不抛异常，进程不因此中断；
+# P1-1（批次 24，外部审查报告）：mdcg_* 工具的 op 要求映射——此前 require_op
+# 只在 _cg_dispatch（cg 工具）内生效，mdcg_* 分支直接落库层（只验
+# can_write/层/密级，不验 ops_allow）→「--ops-allow read」的只读令牌仍可经
+# mdcg_remember 写入，权限收窄形同虚设。映射用令牌签发域内的既有 op 词
+# （read/write/verify——tokens.ROLE_SPECS 全角色都含 read，写类角色含
+# write），ops_allow=None（不限）令牌零影响。
+_MDCG_OP_REQUIRE = {
+    # 写面
+    "mdcg_remember": "write", "mdcg_reflect": "write",
+    "mdcg_flywheel": "write", "mdcg_mine_fix_pairs": "write",
+    "mdcg_rejected": "write", "mdcg_unresolved": "write",
+    "mdcg_propose": "write", "mdcg_review_decide": "write",
+    "mdcg_forget": "write", "mdcg_restore": "write",
+    "mdcg_protect": "write", "mdcg_ingest": "write",
+    "mdcg_consistency": "write",
+    # 读面
+    "mdcg_recall": "read", "mdcg_search": "read", "mdcg_get": "read",
+    "mdcg_review_list": "read", "mdcg_review_records": "read",
+    "mdcg_forgetting_history": "read", "mdcg_identity": "read",
+    "mdcg_metacognition": "read", "mdcg_self_state": "read",
+    "mdcg_predict": "read", "mdcg_causal": "read",
+    "mdcg_evolution": "read", "mdcg_health": "read",
+    "mdcg_whoami": "read", "mdcg_watermarks": "read",
+    "mdcg_whitebox": "read",
+    # 裁决面（仅高权角色域含 verify）
+    "mdcg_verify": "verify",
+}
+
+
+# 生效条件：name 为已注册工具名之一（cg / stg / mdcg_whitebox / mdcg_service_info / mdcg_remember 等）；name 属 _MDCG_OP_REQUIRE 且 cg.principal 具 require_op 属性时先 require_op（越权抛 AccessDenied），principal 为 None 或无该方法时跳过；cg 走 _cg_call、stg 走 _stg_call、whitebox 走 _whitebox_call；未识别的 name 返回含 error 的响应字典而不抛异常，进程不因此中断；
 def _dispatch(cg, name, args):
     a = args or {}
+    # P1-1：mdcg_* 面的角色作用域闸（与 cg 工具的 require_op 同一语义——
+    # ops_allow=None 令牌不受影响；受限令牌越权即 AccessDenied）
+    _need_op = _MDCG_OP_REQUIRE.get(name)
+    if _need_op:
+        _p = getattr(cg, "principal", None)
+        if _p is not None and hasattr(_p, "require_op"):
+            _p.require_op(_need_op)
     if name == "cg":
         return _cg_call(cg, a)
     if name == "stg":
@@ -3037,7 +3134,9 @@ def _dispatch(cg, name, args):
         # 直接引用 mdcos.DEFAULT_MAX_ITEM_TOKENS 会 NameError —— 故此处按需导入）。
         from .mdcos import DEFAULT_MAX_ITEM_TOKENS as _DEFAULT_MAX_ITEM
         return cg.recall(a.get("query", ""),
-                         budget_tokens=int(a.get("budget_tokens") or 1200),
+                         # `is not None`：显式 0 不再被吞成默认 1200（2026-09-24 修复）
+                         budget_tokens=int(a["budget_tokens"])
+                         if a.get("budget_tokens") is not None else 1200,
                          max_item_tokens=int(a["max_item_tokens"])
                          if a.get("max_item_tokens") is not None
                          else _DEFAULT_MAX_ITEM,
@@ -3066,15 +3165,24 @@ def _dispatch(cg, name, args):
                             for n, s, q in res]}
 
     if name == "mdcg_get":
-        return _node_view(cg.get(a.get("node_id", "")),
-                          offset=int(a.get("offset") or 0))
+        _nid = a.get("node_id", "")
+        node = cg.get(_nid)
+        if not node:
+            # 裸 null 让调用方无从区分「id 不存在」与「密级不可读」（2026-09-24 修复）
+            return {"ok": False, "error": "not_found", "node_id": _nid,
+                    "readable_sensitivities": _readable_sensitivities(cg),
+                    "hint": "id 不存在（或已被清退/证伪移入 rejected），"
+                            "或该节点密级高于当前身份可读——whoami 可查 clearance"}
+        return _node_view(node, offset=int(a.get("offset") or 0))
 
     if name == "mdcg_reflect":
         res, _ = cg.search(a.get("query", ""), k=int(a.get("k") or 10), record=False)
         return cg.reflect(a.get("query", ""), res, a.get("feedback"))
 
     if name == "mdcg_verify":
-        return cg.verify(a.get("node_id", ""), a.get("evidence", ""), a.get("verdict", ""))
+        return cg.verify(a.get("node_id", ""), a.get("evidence", ""),
+                         a.get("verdict", ""),
+                         override=bool(a.get("override")))
 
     if name == "mdcg_flywheel":
         return cg.flywheel_step(a.get("error_report") or {})
@@ -3112,7 +3220,8 @@ def _dispatch(cg, name, args):
         return cg.review_decide(a.get("pid", ""), a.get("decision", ""),
                                 edits=a.get("edits"), merge_into=a.get("merge_into"),
                                 reason=a.get("reason", ""),
-                                redteam=a.get("redteam"), issues=a.get("issues"))
+                                redteam=a.get("redteam"), issues=a.get("issues"),
+                                override=bool(a.get("override")))
 
     if name == "mdcg_review_records":
         nid = a.get("node_id")
@@ -3163,6 +3272,12 @@ def _dispatch(cg, name, args):
     if name == "mdcg_ingest":
         from .sources import DSHSessionSource, JsonlSource, Ingestor
         src_arg = (a.get("source") or "auto").strip()
+        # P1-4（批次 26）：报告点名「mdcg_ingest 完全没有权限闸」——权限闸
+        # 已由批次 24 _MDCG_OP_REQUIRE（write）补上，此处补路径根约束；
+        # auto（自动发现 ~/.dsh/sessions）不经路径参数
+        from .security import check_path_root
+        if src_arg != "auto":
+            check_path_root(src_arg, "MDCG_INGEST_ROOT", "mdcg_ingest")
         ing = Ingestor(cg)
         picked, cands = None, []
         if src_arg == "auto":
@@ -3342,7 +3457,7 @@ def _apply_attribution(p):
         p.unit = unit
 
 
-# 生效条件：环境变量 MDCG_TOKEN 去空白后非空时经 verify_token(token, tenant=os.environ.get("MDCG_TENANT")) 构造——抛 TokenError 则返回 (None, f"令牌校验失败：{e}")，成功则返回 (_attach_theory(p), None)；否则 MDCG_LEGACY_ENV_AUTH 值为 "1"/"true"/"True" 时按 MDCG_CAN_ADMIN/MDCG_CAN_WRITE 落到 designer/recorder/output 角色的 legacy_env 身份，两者都不满足时构造 can_write=False、can_admin=False、auth_mode="anonymous" 的 guest 身份，后两条路径同样返回 (_attach_theory(p), None)；
+# 生效条件：环境变量 MDCG_TOKEN 去空白后非空时经 verify_token(token, tenant=os.environ.get("MDCG_TENANT")) 构造——抛 TokenError 则返回 (None, f"令牌校验失败：{e}")，成功则返回 (_attach_theory(p), None)；否则 MDCG_LEGACY_ENV_AUTH 值为 "1"/"true"/"True" 时按 MDCG_CAN_ADMIN/MDCG_CAN_WRITE 落角色（P1-5 批次 26：admin 需 MDCG_CAN_ADMIN 与 MDCG_LEGACY_ENV_ADMIN 同时为真，只设前者时降级 recorder 并写 stderr 提示），两者都不满足时构造 can_write=False、can_admin=False、auth_mode="anonymous" 的 guest 身份，后两条路径同样返回 (_attach_theory(p), None)；
 def _build_principal():
     """构造 Principal（令牌优先，fail-closed）。返回 (principal, error)。
 
@@ -3364,11 +3479,33 @@ def _build_principal():
             p = verify_token(token, tenant=os.environ.get("MDCG_TENANT"))
         except TokenError as e:
             return None, f"令牌校验失败：{e}"
+        # 密级口径冲突必须开口（2026-09-24 修复）：令牌优先时 MDCG_CLEARANCE
+        # **完全不参与**（令牌里冻结的 clearance 说了算），而插件侧
+        # config.mdcg.clearance 默认 'private'——配置写 private、实际 internal
+        # 会让 private/secret 节点静默读不到（本机实测：readable=[public,internal]）。
+        _want = (os.environ.get("MDCG_CLEARANCE") or "").strip()
+        if _want and _want != (p.clearance or ""):
+            sys.stderr.write(
+                f"[mdcg-mcp] ⚠ 密级配置被令牌覆盖：MDCG_CLEARANCE={_want} 但令牌"
+                f" clearance={p.clearance}（令牌优先，实际可读密级以令牌为准）。"
+                f"要让配置生效：用 --clearance {_want} 重新签发令牌，"
+                f"或删除 MDCG_TOKEN 走 legacy/env 身份。\n")
         _apply_attribution(p)
         return _attach_theory(p), None
 
     if os.environ.get("MDCG_LEGACY_ENV_AUTH", "0") in ("1", "true", "True"):
-        can_admin = os.environ.get("MDCG_CAN_ADMIN", "0") in ("1", "true", "True")
+        # P1-5（批次 26，外部审查报告）：legacy env 直连身份不再能给 admin——
+        # 「环境变量可达即 designer/can_admin」= 配置即提权后门。保留兼容但
+        # admin 需**显式二次开关** MDCG_LEGACY_ENV_ADMIN=1；只设 MDCG_CAN_ADMIN
+        # 时降级 recorder 并 stderr 提示（不静默）。
+        _want_admin = os.environ.get("MDCG_CAN_ADMIN", "0") in ("1", "true", "True")
+        can_admin = _want_admin and os.environ.get(
+            "MDCG_LEGACY_ENV_ADMIN", "0") in ("1", "true", "True")
+        if _want_admin and not can_admin:
+            sys.stderr.write(
+                "[mdcg-mcp] ⚠ MDCG_CAN_ADMIN=1 在 legacy env 身份下已不生效："
+                "管理员需要二次开关 MDCG_LEGACY_ENV_ADMIN=1（P1-5 收紧，防 env "
+                "注入自授 admin）。当前降级为 recorder。\n")
         can_write = os.environ.get("MDCG_CAN_WRITE", "1") not in ("0", "false", "False")
         role = "designer" if can_admin else ("recorder" if can_write else "output")
         spec = role_spec(role)
@@ -3407,8 +3544,96 @@ def _attach_theory(p):
 
 
 # 生效条件：环境变量 MDCG_ROOT 非空且其 os.path.abspath 规范化后的 basename 小写不以 "_md_cg_" 开头、且 _build_principal() 返回的 err 为空时，构造 MdCGSecure(root, principal=principal, autoflush=1) 并对 sys.stdin 逐行 method 分派（initialize 回 protocolVersion=PROTOCOL_VERSION 与 SERVER_NAME/SERVER_VERSION，tools/list 回 tools_for_surface()，tools/call 经 call_tool 后回 content，shutdown 跳出循环），遍历结束后调用 sustain.stop_all() 与 cg.close() 并返回 0；MDCG_ROOT 为空或 basename 命中 "_md_cg_" 前缀返回 2，令牌校验失败返回 3；
+# 生效条件：env 缺省取 os.environ；返回 (root, err)——MDCG_TENANT 已登记（登记表路径可经 MDCG_TENANT_REGISTRY 覆盖，缺省 ~/.mdcg/_tenants.json）时 root=登记根，与显式 MDCG_ROOT 冲突返回 (None, 冲突说明)；未登记租户回落 MDCG_ROOT；两者皆空返回 (None, None)；登记表损坏/不可读（TenantRegistry.load_error 留痕或读取抛异常，N124 2026-09-25）时向 stderr 写「登记根绑定失效回落 MDCG_ROOT」告警后按未登记同形回落（零闸变，只开口）。
+def _resolve_root(env=None):
+    """租户 × 认知图根解析（issue #35 接线，独立函数供守卫测试）。
+
+    口径：MDCG_TENANT 已登记 → 登记根；与显式 MDCG_ROOT 不一致 → 冲突
+    （fail-closed，由调用方拒启）；未登记租户 → 维持 MDCG_ROOT（零变更）。
+    登记表损坏/不可读 → 同未登记回落，但必须开口（N124）：静默回落会让
+    租户根物理隔离绑定无声消失、写入落进公共根，且下方冲突 fail-closed
+    检测连带失效。
+    """
+    env = env if env is not None else os.environ
+    root = env.get("MDCG_ROOT")
+    tenant = env.get("MDCG_TENANT")
+    if tenant:
+        t_root = None
+        reg_err = ""
+        try:
+            from .security import TenantRegistry
+            reg = TenantRegistry(env.get("MDCG_TENANT_REGISTRY") or None)
+            t_root = reg.root_of(tenant)
+            reg_err = getattr(reg, "load_error", "") or ""
+        except Exception as e:                           # noqa: BLE001
+            reg_err = f"{type(e).__name__}: {e}"
+            t_root = None
+        if reg_err:
+            # N124（2026-09-25 止血）：登记表损坏/不可读时隔离绑定无声消失，
+            # 对照 MDCG_CLEARANCE 覆盖告警同款口径——零闸变、只开口。
+            sys.stderr.write(
+                f"[mdcg-mcp] ⚠ 租户登记表损坏/不可读（{reg_err}）："
+                f"MDCG_TENANT={tenant} 的登记根绑定失效，本次回落 "
+                f"MDCG_ROOT={root or '(未设)'}；请修复登记表"
+                f"（MDCG_TENANT_REGISTRY，缺省 ~/.mdcg/_tenants.json）。\n")
+        if t_root:
+            if root and os.path.abspath(root) != os.path.abspath(t_root):
+                return None, (f"MDCG_TENANT={tenant} 已登记根 {t_root}，"
+                              f"与显式 MDCG_ROOT={root} 不一致（fail-closed）")
+            root = t_root
+    return root, None
+
+
+# 生效条件：sys.stdin/stdout/stderr 三个流逐个 reconfigure(encoding="utf-8", errors="replace")，
+# 流不支持 reconfigure（AttributeError，如被替换为非 TextIO 对象）或取值非法（ValueError）时静默跳过该流，无返回值。
+def _force_utf8_stdio():
+    """进程内强制 stdio 三流 = UTF-8（issue #39 纵深防线）。
+
+    MCP 协议是 UTF-8 JSON，但 Windows 控制台默认代码页（如 CP936/GBK）会让
+    stdio 管道跟随 locale——宿主按 UTF-8 发来的中文参数被按 GBK 解码：strict
+    下读侧直接 UnicodeDecodeError，surrogateescape 下解出代理对（\\udcXX），
+    ``_j()``（ensure_ascii=False）按 UTF-8 编码时即抛 ``UnicodeEncodeError:
+    surrogates not allowed``，整条请求失败（写英文正常，故用户难自查）。
+    桥层已在 ``src/lib/mdcg_client.ts`` 的 ``mdcgChildEnv()`` 注入
+    ``PYTHONUTF8=1``，但只覆盖 DSH 桥路径——Claude Code / code CLI 直接
+    mcp.json 接入不经桥，仍踩（issue #39）。进程内 reconfigure 是对桥层
+    防线的纵深补位；``errors="replace"`` 保证坏字节最多丢字符、不炸整条请求。
+    必须在 main() 首行调用：早于一切 stderr 中文写与 stdin 读取。
+    """
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+
+# 生效条件：_force_utf8_stdio() 先执行（stdio 三流强制 UTF-8，issue #39）；随后对 mdcg_root()/aux_root() 各探一次，抛 ValueError（Windows 保留设备名末段被 GetFullPathNameW 吞成设备路径，datapath._abs_host_path 守卫）时向 stderr 写一行含原始消息的告警并返回 2；此后 _resolve_root() 返回 err 非空时向 stderr 写冲突说明并返回 2；root 为空写缺少 MDCG_ROOT 并返回 2；root 的 basename 小写以 _md_cg_ 开头返回 2，令牌校验失败返回 3；其余构造 MdCGSecure 并进入 stdin 分派循环。
 def main():
-    root = os.environ.get("MDCG_ROOT")
+    _force_utf8_stdio()
+    # 启动早期承接受理（Windows 保留设备名守卫）：MDCG_ROOT/MDCG_AUX_ROOT/
+    # MDCG_DATA_ROOT 等覆盖值末段若是保留设备名（aux/con/nul/com1-9/lpt1-9…），
+    # ntpath.abspath 经 GetFullPathNameW 会把整个路径吞成设备命名空间形态
+    # （例 D:\sandbox\aux → \\.\aux），datapath._abs_host_path 即抛 ValueError。
+    # 此处先探一次 root/aux 解析，命中即拒绝启动（对照下方 `_md_cg_` 前缀守卫
+    # 先例「启动即拒绝，不带病运行」）——否则首个 aux 常量面（crypto/links/
+    # signer/theory/tokens/evidence 的模块级 aux_root()）会在下方 import 处
+    # 裸崩 traceback，密钥/令牌/信任面被指到不存在的设备路径。
+    try:
+        from .datapath import mdcg_root as _probe_root
+        from .datapath import aux_root as _probe_aux
+        _probe_root()
+        _probe_aux()
+    except ValueError as _ve:
+        sys.stderr.write(f"[mdcg-mcp] {_ve}\n"
+                         "[mdcg-mcp] 拒绝启动（fail-closed）：请把上述覆盖键"
+                         "改指向末段不含保留设备名的普通目录。\n")
+        return 2
+    root, _terr = _resolve_root()
+    if _terr:
+        sys.stderr.write(f"[mdcg-mcp] 租户根冲突：{_terr}。"
+                         "请二选一：清空 MDCG_ROOT 走租户登记根，或从登记表"
+                         "（~/.mdcg/_tenants.json）移除该租户。\n")
+        return 2
     if not root:
         sys.stderr.write("[mdcg-mcp] 缺少 MDCG_ROOT 环境变量\n")
         return 2
@@ -3444,6 +3669,15 @@ def main():
     except Exception as _mig_exc:       # 迁移故障不得影响服务可用性
         sys.stderr.write("[mdcg-mcp] 数据面迁移检查失败（不阻塞启动）: %r\n"
                          % (_mig_exc,))
+    # 两个根一并留痕（2026-09-24）：记忆真源与「身份/凭据根」**有意分离**
+    # （身份不随认知图迁移），但分居两处必须可见——历史事故多为「以为在一处」。
+    try:
+        from .datapath import aux_root as _aux_root
+        sys.stderr.write(
+            "[mdcg-mcp] 路径：记忆真源 root=%s · 身份/凭据根 aux=%s"
+            "（aux 可用 MDCG_AUX_ROOT 覆盖）\n" % (root, _aux_root()))
+    except Exception:                   # 仅日志：任何失败都不影响启动
+        pass
     principal, err = _build_principal()
     if err:
         sys.stderr.write(
@@ -3489,6 +3723,17 @@ def main():
     except Exception as _exc:         # 对账故障不得影响服务可用性
         sys.stderr.write("[mdcg-mcp] 两段式对账失败（不阻塞启动）: %r\n"
                          % (_exc,))
+    # ③' 启动对账 reconcile v0（v0.3 T9 自稳定定理落地，落地清单 P0-3）：两段式
+    # 清账只覆盖「有意图无结果的写入」，这里补全量 diff——索引（派生态）vs 盘面
+    # 真源：多/缺索引条目与内容哈希漂移三类，以盘面为真源**增量**修复索引面；
+    # 真源自身损坏只告警留痕不自动改写（T9 边界：结构合法≠内容正确）。告警与
+    # 留痕由模块发声（diff 非空才输出，干净库零噪声）；MDCG_RECONCILE=0 关闭
+    # （缺省开，开关真源 reconcile.enabled）。失败不阻塞启动，与③同风格。
+    try:
+        cg.reconcile_state()
+    except Exception as _exc:         # 对账故障不得影响服务可用性
+        sys.stderr.write("[mdcg-mcp] 启动对账 v0 失败（不阻塞启动）: %r\n"
+                         % (_exc,))
     # 进程自报（诊断设施，fail-safe）：把「md_cg 实际加载源 + render 契约代际」
     # 落成 `<tempdir>/md_cg_servers/<pid>.json`，供 `scripts/mdcg_stale_servers.py`
     # 机械判定**活进程代际**。根因（第4条取证）：原先只能比「进程启动时间 vs
@@ -3542,8 +3787,14 @@ def main():
                 _reply(rid, {"content": [{"type": "text", "text": _j(out)}],
                              "isError": False})
             except Exception as exc:      # noqa: BLE001 —— 工具错误以 MCP 结果返回
+                # issue #34：失败路径必须带「怎么办」——AccessDenied 的 hint
+                # （guest 配凭据 / 令牌补授权 / 过期重签）随结构化错误透出。
+                err = {"error": f"{type(exc).__name__}: {exc}"}
+                _hint = getattr(exc, "hint", None)
+                if _hint:
+                    err["hint"] = _hint
                 _reply(rid, {"content": [{"type": "text",
-                                          "text": _j({"error": f"{type(exc).__name__}: {exc}"})}],
+                                          "text": _j(err)}],
                              "isError": True})
         elif method == "shutdown":
             _reply(rid, {})