@furongjun1999/dsh-memory 0.7.3 → 0.7.5

package/md_cg/state_slots.py

@@ -0,0 +1,221 @@
+# -*- coding: utf-8 -*-
+"""状态槽位寄存器投影（L2「主体×谓词槽位」）——**事件是源、槽位是投影**。
+
+设计稿：`docs/plans/语义时空图补全_世界模型功能端_设计_v0.1.md` §2/§3（P2 批）。
+
+本模块是**投影，不是第二真源**：
+  · 源＝`md_cg/state_events.py` 的 append-only 台账 `<root>/_state_events.jsonl`；
+  · 查询时**现算**——不落盘、不建缓存、不写任何盘面文件；
+  · 台账追加一条，投影立刻随之变化（无缓存、无物化表 ⇒ 无第二真源、无漂移面）；
+  · 本模块**只读**台账（经 `state_events.read`；`append` 归 `state_events`）。
+
+投影单元字段（设计稿 §3 表逐字）：
+    subject / slot / value / state(active|retired) / t_from / t_to /
+    seq_from / seq_to / tier / alternatives / blindspots / history / event_count
+
+回放规则（分组键 `(subject, slot)`，组内按 `state_events.read()` 的**落盘序**）：
+  · `value` 自 None 起：事件 `new` 非空 → `value=new`；`new` 空（撤回）→ `value=None`
+    且 `state=retired`；其后带值事件自然复活（事件序自然处理，无特判分支）。
+  · `state`：**最后一个事件的形态**决定——`new` 空 → `'retired'`；否则 `'active'`。
+  · 区间（取值一律用事件行的 `t` 落账时间戳，不另算时间）：
+    `t_from`/`seq_from` ＝**最后产生当前值**的那条事件的 `t`/`seq`（retired 态＝
+    最后一个**有值**事件的）；`t_to`/`seq_to` ＝**覆盖它的下一条事件**的 `t`/`seq`
+    （不存在＝None，即「未闭合／仍有效」）；retired 态的覆盖者＝撤回事件（闭合点
+    ＝值作废时刻）。
+  · `tier` ＝最后有值事件的顶层 `tier` 透传（`append(extra=…)` 会把 extra 并入行
+    顶层，故「extra.tier」与「行顶层 tier」是同一处）；缺失（键不在或为 None）→
+    `TIER_UNSPECIFIED`——**不编造**。
+  · `alternatives` / `blindspots`：本批**结构在场、恒为空列表**——「同期未决值」与
+    「声明缺口」的判定口径**后置**（P1 事件行尚无该信号），**不得臆造填充**。
+  · `history` ＝该槽位全部事件原样（每条＝事件行的 `t/seq/old/new/kind/evidence/
+    actor` 七字段，值不改写；缺键取 None）；`history=False` 时**不带该键**。
+
+撤回判据取 **payload**（`new` 为空）而不是 `kind` 标签：台账口径是「撤回＝old 有值而
+new 为空」（`state_events` 模块头），且该模块明言「分类本身不进判据（记账不判语义）」
+——两者一致时等价；冲突时以 payload 为准（不按标签改写数据）。判据单点＝`_is_void`。
+
+过滤与排序：`subject`/`slot` 为 None 不加过滤（该过滤**委托** `state_events.read`，
+此处不写第二套条件解析）；`include_retired=False` 剔除 `state=='retired'` 的单元；
+结果按 `(subject, slot)` 字典序稳定排序。
+
+CLI（纯只读人工入口，**恒可用、无开关**）：
+    python -X utf8 -m md_cg.state_slots --status
+    python -X utf8 -m md_cg.state_slots --subject 鲸娘 [--slot 住所]
+数据根取 `MDCG_ROOT`（缺省走 `datapath.mdcg_root()`，与 `md_cg/sleep.py` 的
+`_main` 同形）。本面与 stg 的 `MDCG_STG_STATE` 开关**无关**：开关管的是 MCP 读面，
+CLI 是人工排查入口（只读、不改任何状态）。
+
+不适用条件：本模块**不判语义**——「不是事实」的言语（玩笑/元层/回忆转述）之消歧
+标记（`not_fact` 等）不在本批（P1 事件行无该信号）；`alternatives`/`blindspots` 的
+真值判定亦未落地（见上，恒空列表）。跨库/多租户合并不在此（单库＝单台账）。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from . import state_events
+
+#: 缺档位占位（台账未带 `tier` 时如实标注，不编造档位）。
+TIER_UNSPECIFIED = "unspecified"
+
+#: `history` 条目**必在**字段（单元 schema 逐字；缺键取 None，不改写数据）。
+_HIST_FIELDS = ("t", "seq", "old", "new", "kind", "evidence", "actor")
+
+
+# 生效条件：rec 为台账记录 dict——`rec.get("new")` 为 None 时返回 True（撤回/值作废），非 None 时返回 False；入参非 dict 时按 `.get` 抛 AttributeError（台账读面保证为 dict，不吞错）。
+def _is_void(rec) -> bool:
+    """撤回判据（单点）：`new` 为空＝值作废、无新值（口径见模块头）。"""
+    return rec.get("new") is None
+
+
+# 生效条件：rec 为一条台账记录 dict 时，返回含 _HIST_FIELDS 七键（缺键取 None）的新 dict——字段集＝单元 schema 的 history 条目逐字（不并入行内其余顶层键：新增键即「发明字段」，故限定枚举）；值原样不改写、不改写入参。
+def _hist_item(rec) -> dict:
+    """变迁史单条：单元 schema 的七字段原样（值不改写）。"""
+    return {k: rec.get(k) for k in _HIST_FIELDS}
+
+
+# 生效条件：subject/slot 为分组键、recs 为同组记录（**非空**，落盘序）、history 为真值时——按模块头回放规则返回单元 dict（含 history 键）；history 为假值时同一单元但不带 history 键；recs 为空时抛 IndexError（组由记录现场建成，恒非空，不吞错）。
+def _replay(subject, slot, recs, *, history=True) -> dict:
+    """单组回放：现值 / 档位 / 区间 / 变迁史（规则逐条见模块头）。"""
+    value = None
+    last_valued = None              # 最后**产生当前值**的事件下标（无则 None）
+    for i, rec in enumerate(recs):
+        if _is_void(rec):
+            value = None            # 撤回：值作废、无新值
+        else:
+            value = rec.get("new")
+            last_valued = i
+    last = recs[-1]
+    retired = _is_void(last)        # state：最后一个事件的形态决定
+    if last_valued is None:
+        # 全程无有值事件（孤立撤回）：起端无可溯源 ⇒ None（不编造）。
+        t_from, seq_from = None, None
+        tier = TIER_UNSPECIFIED
+    else:
+        lv = recs[last_valued]
+        t_from, seq_from = lv.get("t"), lv.get("seq")
+        tier = lv.get("tier")
+        if tier is None:
+            tier = TIER_UNSPECIFIED
+    # 覆盖者：retired 态＝撤回事件（最后一条，闭合点＝值作废时刻）；否则＝有值事件的
+    # **下一条**事件（存在则闭合，不存在＝None＝未闭合）；两者共用同一取舍。
+    nxt = (len(recs) - 1) if retired else (
+        None if last_valued is None else last_valued + 1)
+    if nxt is not None and 0 <= nxt < len(recs):
+        t_to, seq_to = recs[nxt].get("t"), recs[nxt].get("seq")
+    else:
+        t_to, seq_to = None, None
+    unit = {"subject": subject, "slot": slot, "value": value,
+            "state": "retired" if retired else "active",
+            "t_from": t_from, "t_to": t_to,
+            "seq_from": seq_from, "seq_to": seq_to,
+            "tier": tier,
+            # 结构在场、恒空：判定口径后置（模块头，不得臆造填充）。
+            "alternatives": [], "blindspots": [],
+            "event_count": len(recs)}
+    if history:
+        unit["history"] = [_hist_item(r) for r in recs]
+    return unit
+
+
+# 生效条件：recs 为台账记录序列（落盘序，可空）时——按 (subject, slot) 分组（组序＝首现序）后按 (str(subject), str(slot)) 字典序稳定排序，逐组经 _replay；include_retired 为假时剔除 state=='retired' 的单元，为真时全留；返回单元列表（recs 为空返回 []）；history 透传 _replay（假时不带 history 键）。
+def _project(recs, *, include_retired=False, history=True) -> list:
+    """记录序列 → 单元列表（project 与 status 共用的回放单点）。"""
+    groups = {}
+    for rec in recs:
+        key = (rec.get("subject"), rec.get("slot"))
+        groups.setdefault(key, []).append(rec)
+    # 排序键经 str() 归一：台账是外部可写面（append-only），非字符串 subject/slot 会让
+    # 裸元组比较抛 TypeError；字符串形态（正常）下与裸元组字典序逐位一致。
+    out = []
+    for key in sorted(groups, key=lambda k: (str(k[0]), str(k[1]))):
+        unit = _replay(key[0], key[1], groups[key], history=history)
+        if unit["state"] == "retired" and not include_retired:
+            continue
+        out.append(unit)
+    return out
+
+
+# 生效条件：cg 可解析出 root（经 state_events.ledger_path）时——以 state_events.read(cg, subject=subject, slot=slot) 为源（subject/slot 非 None 才过滤，空串亦为合法过滤值）、现算回放，返回单元列表；include_retired=False 剔除 state=='retired' 的单元；history=False 时单元不带 history 键；台账缺失/为空返回 []（不报错）。**零落盘、零缓存**——同一调用序列中台账追加一条，下一次调用结果即变。
+def project(cg, subject=None, slot=None, include_retired=False,
+            history=True) -> list:
+    """槽位寄存器投影（查询时现算）：list[dict]（单元字段见模块头）。
+
+    纯读函数：不改台账、不写盘、不缓存；过滤委托 `state_events.read`（单点），
+    本模块不另写一套条件解析。
+    """
+    recs = state_events.read(cg, subject=subject, slot=slot)
+    return _project(recs, include_retired=include_retired, history=history)
+
+
+# 生效条件：cg 可解析出 root 时——一次 state_events.read(cg) 后返回只读统计 dict：events（台账记录总数）/ subjects（去重 subject 数）/ slots（去重 slot 数）/ retired（回放后 state=='retired' 的单元数）/ bad_rows（state_events.BAD_ROWS 累计值，坏行采样与告警由该模块负责）；台账缺失/为空时 events/subjects/slots/retired 皆 0。
+def status(cg) -> dict:
+    """台账与投影的只读读数（不计语义、不改任何状态）。
+
+    只读一次台账后回放：`bad_rows` 的口径是「累计**跳过动作次数**」（同一坏行每次
+    read 均计一次，见 `state_events`）——本函数每次调用只产生**一次** read。
+    `slots` 为去重**槽位名**数（同一槽位名挂在多个主体下只算一次）；
+    `retired` 为回放后退役单元数（值已作废、未复活）。
+    """
+    recs = state_events.read(cg)
+    units = _project(recs, include_retired=True, history=False)
+    return {"events": len(recs),
+            "subjects": len({r.get("subject") for r in recs}),
+            "slots": len({r.get("slot") for r in recs}),
+            "retired": sum(1 for u in units if u["state"] == "retired"),
+            "bad_rows": state_events.BAD_ROWS}
+
+
+# 生效条件：root 给定且 md_cg.mdcos 可导入时返回该 root 上的 MdCGOS 实例（形态同 md_cg/sleep.py:_open_cg）；导入失败抛原异常。
+def _open_cg(root: str):
+    from .mdcos import MdCGOS
+    return MdCGOS(root)
+
+
+# 生效条件：传入 argv（None 取 sys.argv）——--status 时打印 status(cg) 的 JSON 并返回 0；否则要求 --subject（可配 --slot）或 --slot 单用，打印 project(cg, subject, slot, include_retired, history) 的 JSON 并返回 0；两者皆缺时打印**全量投影**（含退役需显式 --include-retired）并返回 0；--root 缺省取 datapath.mdcg_root()（env MDCG_ROOT）；argparse 对未知参数照常以 SystemExit(2) 退出（不吞）。
+def _main(argv=None) -> int:
+    """只读人工入口：台账现状（--status）/ 槽位投影（--subject [--slot]）。
+
+    本入口**恒可用**（不受 `MDCG_STG_STATE` 开关约束——那把开关管的是 MCP 读面）；
+    全程只读：不 append、不落盘、不改任何状态。
+    """
+    ap = argparse.ArgumentParser(
+        description="状态槽位投影（只读）：台账现算，不落盘、不缓存")
+    ap.add_argument("--root", default=None, help="数据根（缺省 mdcg_root()）")
+    ap.add_argument("--status", action="store_true",
+                    help="只打印台账/投影统计（events/subjects/slots/retired/bad_rows）")
+    ap.add_argument("--subject", default=None, help="按主体过滤（省略＝不过滤）")
+    ap.add_argument("--slot", default=None, help="按槽位过滤（省略＝不过滤）")
+    ap.add_argument("--include-retired", dest="include_retired",
+                    action="store_true", help="含退役单元（缺省剔除）")
+    ap.add_argument("--no-history", dest="history", action="store_false",
+                    help="不带变迁史（history 键省略）")
+    a = ap.parse_args(argv)
+    try:
+        # 进程内调用（守卫/嵌入）会重定向 stdout：无 reconfigure 的流上跳过，
+        # 不改变任何输出内容。
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:                              # noqa: BLE001
+        pass
+    root = os.path.abspath(a.root or _default_root())
+    cg = _open_cg(root)
+    if a.status:
+        out = status(cg)
+    else:
+        out = project(cg, subject=a.subject, slot=a.slot,
+                      include_retired=a.include_retired, history=a.history)
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+# 生效条件：无入参；返回 datapath.mdcg_root()（env MDCG_ROOT 非空时取该值，否则 paths.json/缺省），失败时抛原异常（不吞）。
+def _default_root() -> str:
+    from .datapath import mdcg_root
+    return mdcg_root()
+
+
+if __name__ == "__main__":
+    sys.exit(_main())

package/md_cg/stg.py

@@ -12,6 +12,10 @@
     anchors(...)     落在给定时间窗 / 空间范围内的节点
     consistency()    时空字段自洽性检查
 
+第 5 op（本批）：`state_chain(cg, subject, slot, …)`——L2 **状态槽位投影**
+（某主体某槽位的现值/区间/变迁史；flag `MDCG_STG_STATE`，**默认关**）。语义单点
+在 `md_cg/state_slots.py`（投影不是第二真源：查询时从 append-only 台账现算）。
+
 **分层（issue #52 线）**：
   · 第 1/2 层（已收口）：条件先于限额 + 截断可观测——`_scan` 只做「遍历 +
     layer/可见性过滤」，条件过滤与 `_cap_hits` 截断归各接口。
@@ -28,6 +32,7 @@ from __future__ import annotations
 
 import os
 
+from . import lifecycle
 from . import stgidx
 from . import trust
 
@@ -130,7 +135,7 @@ def _node(cg, node_id):
             "content": n.get("content") or ""}
 
 
-# 生效条件：nid/e 为一条快照条目、layer 为层过滤值时——layer 为真值且 e.get("layer") != layer 即返回 None；cg 带可调用的 _readable（MdCGSecure）且判不可见即返回 None；e 含 "temporal" 或 "spatial" 键时以快照字段构造 frontmatter，否则调用 cg._read(e) 且在 fm 为 None 时返回 None；返回 {"id","frontmatter","layer","path"}。
+# 生效条件：nid/e 为一条快照条目、layer 为层过滤值时——layer 为真值且 e.get("layer") != layer 即返回 None；lifecycle.is_archived(e) 为真即返回 None（退役不参与默认检索，判据单点在 lifecycle.py）；cg 带可调用的 _readable（MdCGSecure）且判不可见即返回 None；e 含 "temporal" 或 "spatial" 键时以快照字段构造 frontmatter，否则调用 cg._read(e) 且在 fm 为 None 时返回 None；返回 {"id","frontmatter","layer","path"}。
 def _scan_one(cg, nid, e, layer=None):
     """单条目 → 候选条目（`_scan` 的逐条实现**单点**：全量遍历与索引子集共用）。
 
@@ -140,6 +145,16 @@ def _scan_one(cg, nid, e, layer=None):
     """
     if layer and e.get("layer") != layer:
         return None
+    if lifecycle.is_archived(e):
+        return None  # lifecycle.py:42 标称兑现：archived 不参与默认检索。
+                     # 本处是 **stg 扫描面单点**（`_scan`(:172) 的全量遍历与
+                     # 索引子集两条分支都经本函数逐条实现）——timeline /
+                     # anchors / consistency 三 op 的候选面同点覆盖；第 5 op
+                     # `state_chain` 走 append-only 台账、不经节点扫描，不受影响；
+                     # `relation` 面是显式 id 直读（`_node`→`cg.get`），也不经此。
+                     # 判据单点在 lifecycle.is_archived（fail-open：缺键=active
+                     # 照常；只剔 archived——converged/demoted 是降权轴仍参与）。
+                     # 直读/审计/恢复面不经本函数：退役不删除、可显式恢复。
     _sec = getattr(cg, "_readable", None)
     if _sec is not None and not _sec(e):
         return None
@@ -164,7 +179,7 @@ def _scan_one(cg, nid, e, layer=None):
             "path": e.get("path")}
 
 
-# 生效条件：nodes 为 None 时**逐条**遍历 cg.index["nodes"] 全部条目（不按索引序切片、不读正文）；nodes 为 (nid, entry) 对的序列时只遍历该序列（第 3 层索引子集，序由调用方保证=索引物理序）；两种形态都逐条经 _scan_one（layer 过滤 + 可见性 + 条目化同一单点）；返回 out 列表（全部 layer/可见性命中，**不做截断**——截断由各接口在条件过滤之后经 _cap_hits 执行，issue #52）；
+# 生效条件：nodes 为 None 时**逐条**遍历 cg.index["nodes"] 全部条目（不按索引序切片、不读正文）；nodes 为 (nid, entry) 对的序列时只遍历该序列（第 3 层索引子集，序由调用方保证=索引物理序）；两种形态都逐条经 _scan_one（layer 过滤 + 退役剔除 + 可见性 + 条目化同一单点）；返回 out 列表（全部 layer/可见性命中，**不做截断**——截断由各接口在条件过滤之后经 _cap_hits 执行，issue #52）；
 def _scan(cg, layer=None, nodes=None):
     """遍历节点：时空字段直接读索引快照（不读文件，O(1)/节点）。
 
@@ -174,6 +189,10 @@ def _scan(cg, layer=None, nodes=None):
     时逐条过读可见性——密级 × 会话绑定档在此与 _candidates 同口径，
     stg 各 op（timeline/relation/anchors）不得成为绕过路径。可见性判定
     **先于一切**（含截断）：不可见节点既不进候选、也不占 kept 名额。
+    退役单点（本轮）：`lifecycle.is_archived` 为真的节点同样不进候选
+    （判据单点在 lifecycle.py，与 cg 读面 `MdCGOS._candidates` 共引一份），
+    两个分支共用的逐条实现单点即 `_scan_one`——flag 开（索引子集）/关
+    （全量遍历）逐位一致，不因取数面不同而漏一次过滤。
 
     issue #52（条件先行于限额）：旧实现在此处 `list(index["nodes"].items())[:max_scan]`
     ——按 id 字典序在**条件过滤之前**砍尾巴，库超 max_scan 后（a）本会话记忆等条件
@@ -269,6 +288,8 @@ def _with_scan_reads(out, *, scanned, hits, kept, truncated, max_scan,
 _INDEX_ENV = "MDCG_STG_INDEX"
 #: 条件资格首验开关（只上报不过滤）。
 _QUALIFY_ENV = "MDCG_STG_QUALIFY"
+#: 状态槽位投影开关（第 5 op；与上两把同纪律：**默认关**，探针全绿后逐档开）。
+_STATE_ENV = "MDCG_STG_STATE"
 
 
 # 生效条件：环境变量 name 取值属 ("1","true","True") 时返回 True，其余（含未设/其它值）返回 False——默认关的开关一律走本判据（与 MDCG_LEGACY_ENV_AUTH 同形）。
@@ -699,4 +720,48 @@ def consistency(cg, layer=None, limit=50, max_scan=5000, time_axis="observed"):
     return _with_scan_reads(
         {"issues": len(issues), "limit": limit, "items": issues[:limit]},
         scanned=scanned, hits=scanned, kept=kept, truncated=truncated,
-        max_scan=max_scan, index_meta=imeta)
+        max_scan=max_scan, index_meta=imeta)
+
+
+# ---------------------------------------------------------------------------
+# 第 5 op：状态槽位投影（flag MDCG_STG_STATE，默认关）
+# ---------------------------------------------------------------------------
+
+# 生效条件：_flag_on(_STATE_ENV) 为假（含未设）时恒返回 {"error":"disabled","hint":…}（不抛异常、不静默降级、不触台账）；为真时以 state_slots.project(cg, subject, slot, include_retired, history) 为 items 全量（查询时现算，零落盘零缓存），limit 经 int() 归一（负数归 0）后取前 limit 条，返回含 count（命中总数，截断前）/subject/slot/include_retired/limit/items/truncated（count > kept）/kept（len(items)）的 dict；project 抛异常时**不吞**（原样上抛）。
+def state_chain(cg, subject=None, slot=None, include_retired=False, history=True,
+                limit=50):
+    """状态槽位投影（第 5 op）：某主体某槽位的**现值 / 区间 / 变迁史**。
+
+    语义单点在 `md_cg/state_slots.py`（**投影不是第二真源**：查询时从 append-only
+    台账 `<root>/_state_events.jsonl` 现算，不落盘、不缓存）——本函数只做开关与
+    返回体成形，不复制任何回放逻辑（改投影只改那一处）。
+
+    开关（`MDCG_STG_STATE`，**默认关**，与 `MDCG_STG_INDEX`/`MDCG_STG_QUALIFY`
+    同纪律）：关臂返回 `{"error": "disabled", "hint": …}`——**不是异常**，是「本面
+    未启用」的如实答复；不静默降级成空结果（「没开」与「没命中」必须可分辨）。
+
+    返回体沿 stg 既有口径（issue #52：截断可观测）：`count` 为**条件命中总数**
+    （截断前，不受 limit 影响）、`items` 为前 `limit` 条、`kept` 为实际返回条数、
+    `truncated` 为 `count > kept`（limit=0 ⇒ items 空、truncated 随 count 真值）。
+
+    不适用条件：`time_axis` 不适用于本 op（台账事件行只有落账时间戳 `t`，无
+    双轴端点——本面**不伪造**第二轴；需要轴语义请走 timeline/relation/anchors）；
+    `alternatives`/`blindspots` 本批恒空列表（判定口径后置，见 `state_slots` 模块头）。
+    """
+    if not _flag_on(_STATE_ENV):
+        return {"error": "disabled",
+                "hint": "本面默认关：设 MDCG_STG_STATE=1 显式启用"
+                        "（与 MDCG_STG_INDEX/MDCG_STG_QUALIFY 同纪律）"}
+    from . import state_slots
+    units = state_slots.project(cg, subject=subject, slot=slot,
+                                include_retired=include_retired,
+                                history=history)
+    total = len(units)
+    cap = int(limit) if limit is not None else 0
+    if cap < 0:
+        cap = 0
+    items = units[:cap]
+    return {"count": total, "subject": subject, "slot": slot,
+            "include_retired": include_retired, "limit": limit,
+            "items": items, "truncated": total > len(items),
+            "kept": len(items)}

package/md_cg/sustain.py

@@ -71,6 +71,17 @@ DEFAULT_SCRUB_INTERVAL = 3600.0   # 记忆自净（抽查/去污染/校准）1h
 DEFAULT_EVOLVE_INTERVAL = 7200.0  # 演化巡检（固化/重要性候选盘点）2h；只读
 DEFAULT_TIDY_INTERVAL = 21600.0   # 整理巡检（contextual 同构组聚合）6h
 
+#: 六档 tick 的（档名 → interval 属性名）映射——进度面与 stale 阈值的取值面，
+#: 顺序即 `SustainLoop._run()` 的执行序（单一真源：改档名/加点只改这里）。
+TICK_INTERVAL_ATTRS = (("beat", "beat_interval"), ("heal", "heal_interval"),
+                       ("scrub", "scrub_interval"), ("evolve", "evolve_interval"),
+                       ("tidy", "tidy_interval"), ("sleep", "sleep_interval"))
+#: 活体进度面的 stale 阈值下限（秒）——issue #63：某档 tick 运行超过
+#: `max(2×该档 interval, TICK_STALE_MIN_S)` 时，状态面显式给 `stale_tick`
+#: 告警。**只上报，不杀线程**（线程不可安全强杀；处置=人工重启常驻进程，
+#: 见 `docs/mdcg/睡眠周期_运维前提与维护指南_v1.0.md`）。
+TICK_STALE_MIN_S = 1800.0
+
 # ---- 四档 `auto_*` 缺省的**单一真源**（P0-2，2026-10-01）--------------------
 # 为什么要有这张表：同一组缺省此前在**三处**各写一份——op 路径
 # （mcp_server.py 的 `_sustain_call` start 分支）、env 路径（`_start_sustain`）
@@ -1077,6 +1088,13 @@ class SustainLoop:
         self.tidys = []
         # 数据健康不变量断言集结论（Pi⑤）：与 tidy 同节奏，只取结论不落盘
         self.last_conformance = None
+        # 活体进度面（issue #63）：当前档 / 上一档完成 / 上一档错误——
+        # 写点 = 既有心跳戳（见 `_progress_fields` / `_flush_progress`），
+        # **不造第二套状态文件**。
+        self.current_tick = None
+        self.last_tick_done = None
+        self.last_tick_error = None
+        self._ticks_wrapped = False          # 六档进度面包装的幂等标记
         self._started_at = None
         self._th = None
         self._stop = threading.Event()
@@ -1084,18 +1102,126 @@ class SustainLoop:
 
     # ---- 心跳 ----
 
-# 生效条件：task_running 非 None 时先置 self.task_running=bool(task_running)，再 write_stamp(self.name, self.d, task_running=self.task_running, root=self.cg.root, uptime=... if self._started_at else 0.0)，beats 自增并记 last_beat=rec["ts"]，返回该 rec；
+# 生效条件：task_running 非 None 时先置 self.task_running=bool(task_running)，再 write_stamp(self.name, self.d, task_running=self.task_running, root=self.cg.root, uptime=... if self._started_at else 0.0, **进度三字段)，beats 自增并记 last_beat=rec["ts"]，返回该 rec；
     def beat(self, task_running: bool = None) -> dict:
         if task_running is not None:
             self.task_running = bool(task_running)
         rec = write_stamp(
             self.name, self.d, task_running=self.task_running, root=self.cg.root,
             uptime=round(time.time() - self._started_at, 3)
-            if self._started_at else 0.0)
+            if self._started_at else 0.0,
+            **self._progress_fields())          # 进度面随心跳同落（单点状态面）
         self.beats += 1
         self.last_beat = rec["ts"]
         return rec
 
+    # ---- 活体进度面（issue #63）----
+    #
+    # 为什么有这一段：`_run()` 单线程串行六档，任一档**无界阻塞**即全循环停摆
+    # （实测停 9.5 小时：心跳/自愈/巡检/演化/整理/睡眠全停）。卡住期间外部
+    # **无法知道卡在哪档**——tick 台账在 run_cycle **返回后**才写。故：
+    #   · 进入/退出每档各刷一次**既有状态面**（心跳戳）——不造第二套状态文件；
+    #   · `current_tick` 给出「此刻在哪档、已跑多久」，`stale_tick` 超限告警；
+    #   · 六档异常**不再静默**（容忍≠静默）：`last_tick_error` 记类名 + 摘要。
+    # 形态：全部经 `_wrap_ticks()` **单点包装**——`_run` 的六档 try/except 逐字
+    # 未改（`md_cg/test_sleep_p1.py` G3a 把它钉死；包装让异常在进入 `_run` 的
+    # except 之前就已被记录，那边的 `pass` 保留为兜底）。
+
+# 生效条件：无入参；返回进度三字段 dict（current_tick / last_tick_done / last_tick_error；None 值由 write_stamp 丢弃）——写戳与 status 读取的唯一取值面。
+    def _progress_fields(self) -> dict:
+        """进度三字段（写点与读取的**单一取值面**）。"""
+        return {"current_tick": self.current_tick,
+                "last_tick_done": self.last_tick_done,
+                "last_tick_error": self.last_tick_error}
+
+# 生效条件：以 write_stamp(self.name, self.d, task_running=self.task_running, root=self.cg.root, uptime=... if self._started_at else 0.0, **进度三字段) 刷新既有心跳戳（原子替换）；写失败静默（与心跳同纪律）——进度面缺失是已知边界（写失败时 status 的当前档读数退化为 null）。
+    def _flush_progress(self):
+        """把进度面刷新进**既有状态面**（心跳戳）——不新建状态文件。
+
+        为什么**进入**档时就要刷：卡死场景下「没有下一次写」正是常态——进度
+        必须在进入时就落盘，否则观测面恰好缺了要观测的那一刻。写失败静默
+        （与 `beat()` 同纪律），但失败即拉不到进度，属已知边界。
+        """
+        try:
+            write_stamp(self.name, self.d, task_running=self.task_running,
+                        root=self.cg.root,
+                        uptime=round(time.time() - self._started_at, 3)
+                        if self._started_at else 0.0,
+                        **self._progress_fields())
+        except Exception:                            # noqa: BLE001
+            pass                                     # 进度面刷新失败不拖垮常驻
+
+# 生效条件：无入参；把六档 tick 方法（beat / _tick_heal / _tick_scrub / _tick_evolve / _tick_tidy / _tick_sleep）就地包上 _wrap_tick（幂等：_ticks_wrapped 为真即直接返回 self）；返回 self。
+    def _wrap_ticks(self):
+        """把六档 tick 包上进度面（幂等）——**不改 `_run` 的逐字形态**。
+
+        为什么用包装而不是改 `_run` 的六档结构：`_run` 的六档 try/except 形态
+        被既有守卫**逐字**钉死（`md_cg/test_sleep_p1.py` G3a「第六档形态与
+        既有五档逐字同构（try/except 吞异常 + 末尾 _stop.wait(_POLL)）」），
+        而 issue #63 要求的「进/出留读数 + 异常不静默」是**每档同款**动作——
+        单点包装既保住既有形态（六档语义与顺序一字不动），又免六处重复
+        （改档名/加点只动 `TICK_INTERVAL_ATTRS`）。
+        """
+        if getattr(self, "_ticks_wrapped", False):
+            return self
+        for name, _attr in TICK_INTERVAL_ATTRS:
+            meth = "_tick_" + name if name != "beat" else "beat"
+            setattr(self, meth, self._wrap_tick(name, getattr(self, meth)))
+        self._ticks_wrapped = True
+        return self
+
+# 生效条件：name 为该档名、fn 为该档可调用；返回包装函数 wrapped——调用时先写 current_tick={name, started_at, pid} 并刷新戳，调 fn(*a, **kw)，异常记入 last_tick_error={name, error: 类名+摘要（截 200 字符）, t} 并**不重抛**（容忍≠静默；`_run` 的既有 except 保留为兜底），随后清 current_tick、记 last_tick_done={name, t, ok} 并再刷新戳。
+    def _wrap_tick(self, name: str, fn):
+        """单档 tick 的**进度面包裹**（issue #63）：进/出各留读数，异常不静默。
+
+        「容忍 ≠ 静默」：六档的 except 面此前只有 `pass`——失败的档在外部
+        读不到。现在失败一律进 `last_tick_error`（类名 + 摘要）；卡住靠
+        `current_tick` 的年龄与 `stale_tick` 告警判（不杀线程）。
+        """
+        def wrapped(*a, **kw):
+            self.current_tick = {"name": name, "started_at": time.time(),
+                                 "pid": os.getpid()}
+            self._flush_progress()
+            ok_ = True
+            try:
+                fn(*a, **kw)
+            except Exception as e:                   # noqa: BLE001
+                ok_ = False
+                self.last_tick_error = {"name": name, "t": time.time(),
+                                        "error": "%s: %s" % (type(e).__name__,
+                                                             str(e)[:200])}
+            self.current_tick = None
+            self.last_tick_done = {"name": name, "t": time.time(), "ok": ok_}
+            self._flush_progress()
+            return ok_
+        wrapped.__name__ = "wrapped_%s_tick" % name
+        return wrapped
+
+# 生效条件：ct 为 current_tick 形态（含 name 与 started_at）且 name 在 TICK_INTERVAL_ATTRS 内时，以该档 interval 算 lim=max(2×interval, TICK_STALE_MIN_S)，年龄（now-started_at）超 lim 返回 {tick, age_s, limit_s, alert}（alert 文案含档名与已运行时长）；未超或形态不符返回 None。
+    def _stale_tick(self, ct):
+        """`current_tick` 的 stale 判定：年龄 > `max(2×该档 interval, 1800s)`。
+
+        超限**只告警不杀线程**（线程不可安全强杀；处置=人工重启常驻进程，
+        见运维指南「常驻循环的卡死防护与观测」一节）。
+        """
+        if not isinstance(ct, dict):
+            return None
+        name = ct.get("name")
+        attr = dict(TICK_INTERVAL_ATTRS).get(name)
+        if attr is None:
+            return None
+        try:
+            lim = max(2.0 * float(getattr(self, attr)), TICK_STALE_MIN_S)
+            age = max(0.0, time.time() - float(ct.get("started_at") or 0.0))
+        except (TypeError, ValueError):
+            return None
+        if age <= lim:
+            return None
+        return {"tick": name, "age_s": round(age, 1), "limit_s": round(lim, 1),
+                "alert": ("档 %s 已运行 %.0fs（阈值 %.0fs = max(2×间隔, %.0fs)）"
+                          "——疑似卡死；不自动杀线程，处置=人工重启常驻进程"
+                          % (name, age, lim, TICK_STALE_MIN_S))}
+
     # ---- 生命周期 ----
 
 # 生效条件：不适用（无必需形参与模块级常量）
@@ -1119,8 +1245,9 @@ class SustainLoop:
         clear_stamp(self.name, self.d)
         return self
 
-# 生效条件：self._stop 未置位期间轮询，按 beat_interval/heal_interval/scrub_interval/evolve_interval/tidy_interval/**sleep_interval（第六档）** 到期分别执行 beat 与 _tick_heal/_tick_scrub/_tick_evolve/_tick_tidy/_tick_sleep，各 tick 抛出的异常被吞掉不中断循环，末尾以 _stop.wait(_POLL) 休眠；
+# 生效条件：self._stop 未置位期间轮询（**先调 _wrap_ticks 给六档包上进度面，幂等**），按 beat_interval/heal_interval/scrub_interval/evolve_interval/tidy_interval/**sleep_interval（第六档）** 到期分别执行 beat 与 _tick_heal/_tick_scrub/_tick_evolve/_tick_tidy/_tick_sleep（六档调用形态与既有五档逐字同构：try/except 吞异常 + `_stop.wait(_POLL)` 收尾；进/出读数与异常记录由包装单点提供——issue #63）；
     def _run(self):
+        self._wrap_ticks()               # issue #63：六档包上进度面（幂等，形态不变）
         next_beat = time.time() + self.beat_interval
         next_heal = time.time() + self.heal_interval
         next_scrub = time.time() + self.scrub_interval
@@ -1309,12 +1436,25 @@ class SustainLoop:
 
     # ---- 状态 ----
 
-# 生效条件：以 read_stamp(self.name, self.d) 判定 state（有戳走 judge(age, interval=self.beat_interval, task_running=...)，无戳为 "stopped"），返回含 name/running/pid/uptime（无 _started_at 时为 0.0）/beats/last_beat/各 interval 与 auto_* 开关/heals[-5:]/evolves[-5:]/tidys[-5:]/peers(self.d)/ledger.summary() 的 dict；
+# 生效条件：以 read_stamp(self.name, self.d) 判定 state（有戳走 judge(age, interval=self.beat_interval, task_running=...)，无戳为 "stopped"）；进度面（issue #63）同进程内存优先、跨进程回落戳内字段，current_tick 附 running_s（已运行秒数）；stale_tick 在 current_tick 年龄超 max(2×该档 interval, 1800s) 时给出告警（含档名与时长）；返回含 name/running/pid/uptime（无 _started_at 时为 0.0）/beats/last_beat/各 interval 与 auto_* 开关/heals[-5:]/evolves[-5:]/tidys[-5:]/current_tick/last_tick_done/last_tick_error/stale_tick/peers(self.d)/ledger.summary() 的 dict；
     def status(self) -> dict:
         st = read_stamp(self.name, self.d)
         state = (judge(st["age"], interval=self.beat_interval,
                        task_running=bool(st.get("task_running")))
                  if st else "stopped")
+        # 进度面（issue #63）：同进程内存优先（最实时），跨进程回落戳内字段
+        # ——戳是**既有状态面**（不造第二套状态文件）；外部 `action=beat`
+        # 覆盖戳时内存侧不受影响。
+        cur = self.current_tick or (st or {}).get("current_tick")
+        if isinstance(cur, dict):
+            cur = dict(cur)
+            try:
+                cur["running_s"] = round(max(
+                    0.0, time.time() - float(cur.get("started_at") or 0.0)), 1)
+            except (TypeError, ValueError):
+                cur["running_s"] = None
+        last_done = self.last_tick_done or (st or {}).get("last_tick_done")
+        last_err = self.last_tick_error or (st or {}).get("last_tick_error")
         return {"name": self.name, "running": bool(self._th
                                                    and self._th.is_alive()),
                 "pid": os.getpid(),
@@ -1344,6 +1484,12 @@ class SustainLoop:
                 "last_sleep": self.last_sleep,
                 "sleeps": self.sleeps[-5:],
                 "last_conformance": self.last_conformance,
+                # 活体进度面（issue #63）：此刻在哪档 / 上一档完成 / 上一档错误
+                # / 超限告警（只上报，不杀线程）。
+                "current_tick": cur,
+                "last_tick_done": last_done,
+                "last_tick_error": last_err,
+                "stale_tick": self._stale_tick(cur),
                 "peers": peers(self.d),
                 "sessions": self.ledger.summary()}