opencode-agora 0.1.0__py3-none-any.whl

agorad/core/recover.py

@@ -0,0 +1,83 @@
+"""崩溃恢复协调（F6，设计 §4.6）：启动复查重注入、死 worker 自愈原语。
+
+startup：State 构造已恢复末行快照，此处对 in-flight 任务探活，仅
+dispatched/running 重建 worker 会话（终态/blocked/verify_failed 等续修态
+复查后一律不注入）。reinject：oc.create 同 BOOT 语义（任务页＋环境＋行为
+合同），新 sid 覆写 worker_sid；旧 worker 牌经 auth.rebind 改绑新 sid
+（token 本体不变、identify 归新会话）并随 dispatch 同形送达凭据（直投失败经
+注入的 router 落库兜底）；审计一行 reinjected。任何失败返回 False 不抛：先
+create 成功才覆写行，不半写。core 只 import stdlib，依赖全构造注入。
+"""
+import time
+
+_REINJECTABLE = {"dispatched", "running"}
+# 未结案嵌套子任务均随父 worker 改绑；todo 虽尚未派发，也不能在恢复后丢失所有权。
+_NESTED_OPEN = {"todo", "dispatched", "running", "done", "verify_failed", "reopened", "blocked"}
+
+EV_REINJECTED = "reinjected"
+
+
+class Recover:
+    """startup 由 main 装配期调用一次；reinject 供 health.tick 与启动共用。"""
+
+    def __init__(self, state, oc, gitx, store, auth, router=None):
+        self._state, self._oc, self._gitx = state, oc, gitx
+        self._store, self._auth, self._router = store, auth, router
+
+    def startup(self):
+        """启动复查重注入；先清残留门闩——门线程不跨进程存活，kill -9 残闩必清。"""
+        self._state.clear_gate_latches()
+        for tid, t in self._state.snapshot()["tasks"].items():
+            if t["state"] not in _REINJECTABLE or not t.get("worker_sid"):
+                continue
+            try:
+                alive = self._oc.alive(t["worker_sid"])
+            except Exception:  # oc 不可达≠会话死：本轮免判，tick 再兜
+                continue
+            if not alive:
+                self.reinject(tid)
+
+    def reinject(self, tid) -> bool:
+        """死 worker 重建：成功 True；复查不通过/创建失败一律 False。"""
+        try:
+            t = self._state.get(tid)
+        except KeyError:
+            return False
+        if t["state"] not in _REINJECTABLE or not t.get("env_dir"):
+            return False  # 复查：终态/blocked/verify_failed(等续修) 不重注入
+        try:
+            self._gitx.head(t["env_dir"])  # 环境在册探针：worktree 已失不盲注
+            wsid = self._oc.create(t["env_dir"], self._boot(tid, t))
+        except Exception:
+            return False
+        old_wsid = t.get("worker_sid")
+        self._state.set_fields(tid, worker_sid=wsid)  # 新 sid 覆写
+        for cid, child in self._state.snapshot()["tasks"].items():
+            if (child.get("dispatcher_sid") == old_wsid
+                    and child["state"] in _NESTED_OPEN):
+                self._state.set_fields(cid, dispatcher_sid=wsid)
+                self._store.append_event(
+                    {"ts": time.time(), "actor": "agorad",
+                     "event": "dispatcher_rebind", "task": cid,
+                     "from": old_wsid, "to": wsid})
+        tok = self._auth.rebind(old_wsid, wsid)  # 旧牌改绑新会话
+        self._store.append_event({"ts": time.time(), "actor": "agorad",
+                                  "event": EV_REINJECTED, "task": tid,
+                                  "worker": wsid})
+        if tok:  # 凭据随 dispatch 同形送达（签牌文本 inject 进新会话）
+            text = f"[agora] credential {tid}\ntoken: {tok}"
+            try:
+                ok = self._oc.inject(wsid, text)
+            except Exception:  # oc 抖动同死会话口径：走落库兜底
+                ok = False
+            if not ok and self._router is not None:  # 直投失败落库：补拉可取回
+                self._router.post(t["dispatcher_sid"], ("down", tid),
+                                  "credential", text)
+        return True
+
+    def _boot(self, tid, t):
+        page = self._store.home / "wiki" / "tasks" / f"{tid}.md"
+        return (f"[agora] {tid}: {t.get('title', tid)} (reinject)\npage: {page}\n"
+                f"env: {t['env_dir']}\n"
+                "contract: 会话曾死亡已重建——先 check_mail 补拉断点上下文，"
+                "继续任务页目标；结论经 post(done) 回填")

agorad/core/report.py

@@ -0,0 +1,189 @@
+"""状态视图（F10，设计 §4.1）：五桶/链视图/明细/doctor/HTML——纯函数集。
+
+snap/store 进来、dict/list/str 出去，零状态零副作用（store 仅读原语）。
+五桶机械口径：已合并=merged+closed（closed 是合并后唯一后继）；在飞=其余
+非终态全部（含 todo 未派、done 待并；verify_failed/reopened 是续修态归在飞）；
+失败=空集保留位——v2 状态集无独立"失败"终态（质量败走 verify_failed 续修，
+3 连败自动 blocked 归阻塞桶）；阻塞=blocked；已取消=cancelled。
+"""
+import html
+import os
+import time
+from pathlib import Path
+
+_MERGED = {"merged", "closed"}
+_STALE_AFTER = 1200
+# 僵态候选口径（F5 决策记录 2026-10-28）：blocked 已属失控拍过人、终态与 todo
+# 无 worker 活动面——均排除。
+_STALE_STATES = {"dispatched", "running", "done", "verify_failed", "reopened"}
+
+
+def _env_activity(env_dir):
+    """env 工作区文件活性（F15）：目录树最新 mtime（含目录）——worker 原生干活期
+    不碰工具面，文件在写即活着；缺失/不可读返 0.0。纯 stdlib（core 勿 import access）。
+    """
+    if not env_dir:
+        return 0.0
+    latest = 0.0
+    for root, _dirs, files in os.walk(env_dir):
+        for p in [root, *(os.path.join(root, f) for f in files)]:
+            try:
+                latest = max(latest, os.stat(p).st_mtime)
+            except OSError:
+                pass
+    return latest
+
+
+def _stale_baseline(t):
+    """僵态活性基线（F15）：max(last_seen or created, env 活性）——文件持续在写＝活着。"""
+    return max(t.get("last_seen") or t.get("created", 0.0),
+               _env_activity(t.get("env_dir")))
+
+
+def buckets(snap):
+    """五桶汇总：桶名→任务 id 列表（失败桶恒空，口径见模块 docstring）。"""
+    out = {"已合并": [], "在飞": [], "失败": [], "阻塞": [], "已取消": []}
+    for tid, t in sorted(snap["tasks"].items()):
+        s = t["state"]
+        if s in _MERGED:
+            out["已合并"].append(tid)
+        elif s == "blocked":
+            out["阻塞"].append(tid)
+        elif s == "cancelled":
+            out["已取消"].append(tid)
+        else:
+            out["在飞"].append(tid)
+    return out
+
+
+def chain_view(snap, dispatcher_sid):
+    """链级视图：该会话直接派的任务＋其 worker 再派的下级（逐跳传递展开）。
+
+    seen 集合防环（账本行语义上无环，但环行入账时 /view 不得挂死）兼去重。
+    """
+    out, frontier, seen = [], [dispatcher_sid], {dispatcher_sid}
+    while frontier:
+        sid = frontier.pop(0)
+        for tid, t in sorted(snap["tasks"].items()):
+            if t.get("dispatcher_sid") == sid:
+                out.append(tid)
+                w = t.get("worker_sid")
+                if w and w not in seen:
+                    seen.add(w)
+                    frontier.append(w)
+    return out
+
+
+def _layer_key(tasks):
+    """同层排序键（gt-c05d6e）：created 降序（近者在前）；缺失/0 兜底 tid 字典序垫底（稳定）。"""
+    def key(tid):
+        c = tasks[tid].get("created")
+        return (1, tid) if not c else (-c, tid)
+    return key
+
+
+def forest_view(snap):
+    """全局链森林（gt-6def73）：父子边仍按 worker_sid↔dispatcher_sid 上溯，
+    但在全任务集找父；根＝全任务集内无父的任务。输出 DFS 子树聚簇序 tid 列表
+    （同层按 created 降序近者在前，缺失兜底 tid 序，稳定可测）；显式栈防递归，
+    seen 集环防护有界（环岛 DFS 不可达，按同键序尾附兜底，全员在列）。
+    """
+    tasks = snap["tasks"]
+    parent = {tid: next((p for p in sorted(tasks)
+                         if tasks[p].get("worker_sid")
+                         == t.get("dispatcher_sid")), None)
+              for tid, t in tasks.items()}
+    rank = _layer_key(tasks)
+    kids, roots = {tid: [] for tid in tasks}, []
+    for tid in sorted(tasks, key=rank):
+        p = parent[tid]
+        (roots if p is None else kids[p]).append(tid)
+    out, seen, stack = [], set(), roots[::-1]
+    while stack:
+        tid = stack.pop()
+        if tid in seen:
+            continue
+        seen.add(tid)
+        out.append(tid)
+        stack.extend(reversed(kids[tid]))
+    return out + [tid for tid in sorted(tasks, key=rank) if tid not in seen]
+
+
+def detail(snap, store, tid):
+    """单任务明细三件套：全字段行＋事件链＋done 正文（最新一条＝当前结论）。
+
+    F15 增 env_active_seconds_ago：env 在盘时 now-最新 mtime（int 秒）；回收/缺失省略。
+    """
+    done = [m for m in store.read_messages()
+            if m.get("task") == tid and m.get("kind") == "done"]
+    out = {"task": dict(snap["tasks"][tid]), "events": store.read_events(tid),
+           "done_body": done[-1]["body"] if done else None}
+    env = out["task"].get("env_dir")
+    if env and Path(env).is_dir():
+        act = _env_activity(env)
+        if act > 0.0:  # is_dir 后被并发回收→walk 空，省略而非输出 1.7e9 假值
+            out["env_active_seconds_ago"] = int(time.time() - act)
+    return out
+
+
+def stale_candidates(snap, now, base=None):
+    """僵态候选公开口径（F5；F15 融 env 活性）：[[tid, 基线ts],...] 基线升序（最僵在前）。
+
+    在飞口径状态（_STALE_STATES）且 now-_stale_baseline(t)>_STALE_AFTER，
+    基线＝max(last_seen or created, env 文件活性)；health tick 构造注入复用同一口径。
+    base＝doctor_view 预计算基线 map（评审环 round1：免同请求二遍全树 walk），缺省现算。
+    """
+    cand = []
+    for tid, t in snap["tasks"].items():
+        # shortcut: 门线程挂死（verify 永不返回）随 in_gate 永久免检，门故障类报警另立，when: 出现首例门挂死
+        if t["state"] in _STALE_STATES and not t.get("in_gate"):
+            b = base.get(tid) if base is not None else None
+            if b is None:
+                b = _stale_baseline(t)
+            if now - b > _STALE_AFTER:
+                cand.append([tid, b])
+    cand.sort(key=lambda kv: kv[1])
+    return cand
+
+
+def doctor_view(snap, store_home, now=None):
+    """账本侧事实：任务年龄/最后活动排行＋僵态候选＋env_dir 在盘性（盘上孤儿扫描属②期）。
+
+    排行活性基线（F15）：age_rank/last_seen_rank 同取 _stale_baseline（与
+    stale_candidates 同口径），字段名不变、值改为融合基线的 now- 差与原值。
+    僵态候选（F5）：同 stale_candidates 口径，纯显示，处置归上级判断。
+    """
+    now = time.time() if now is None else now
+    home, tasks = Path(store_home), snap["tasks"]
+    base = {tid: _stale_baseline(t) for tid, t in tasks.items()}
+    ranked = sorted(tasks, key=lambda tid: base[tid])
+    cand = stale_candidates(snap, now, base=base)
+    env = []
+    for tid, t in sorted(tasks.items()):
+        e = t.get("env_dir")
+        if not e:
+            continue
+        p = Path(e)
+        env.append({"tid": tid, "env_dir": e,
+                    "on_disk": (p if p.is_absolute() else home / p).exists()})
+    return {"age_rank": [[tid, now - base[tid]] for tid in ranked],
+            "last_seen_rank": [[tid, base[tid]] for tid in ranked],
+            "stale_candidates": cand,
+            "env": env}
+
+
+def view_html(snap):
+    """/view 最小页：五桶计数明细＋链表（dispatcher→worker 链边）。"""
+    esc = lambda v: html.escape(str(v))
+    parts = ["<html><body><h1>agora board</h1>"]
+    for name, tids in buckets(snap).items():
+        parts.append(f"<h2>{name} {len(tids)}</h2><ul>")
+        parts.extend(f"<li>{esc(i)}</li>" for i in tids)
+        parts.append("</ul>")
+    parts.append("<h2>链</h2><ul>")
+    for tid, t in sorted(snap["tasks"].items()):
+        parts.append(f"<li>{esc(tid)}: {esc(t['state'])} "
+                     f"{esc(t.get('dispatcher_sid'))}→{esc(t.get('worker_sid'))} "
+                     f"{esc(t.get('title', ''))}</li>")
+    parts.append("</ul></body></html>")
+    return "".join(parts)

agorad/core/state.py

@@ -0,0 +1,183 @@
+"""权威任务状态机＋内存快照＋fail_streak＋审计事件名（设计 §4.1/§4.8）。
+
+单写者内存直接迁移、无事件推导；每次迁移/计数变更 append 一行全量快照
+（含 mail_read 游标）；last_seen/mail_read 为内存态、崩溃回退接受；
+fail_streak 随快照行持久化，kill -9 不丢。Store 对象构造注入，零磁盘接触。
+三线程（httpd 消费/gate 门体/health 定时）并发 mutate＋append：内置锁使
+内存迁移与 append 同临界区（§4.8 防线）；cancel 排队（queue_cancel）与
+门尾消费（gate_tail）各为单一原子操作——pending_cancel 不悬挂。
+"""
+import copy
+import threading
+import time
+
+# 审计事件名常量：事件名＝里程碑迁移后的状态名（F8：迁移状态＋审计）
+EV_DISPATCHED = "dispatched"
+EV_RUNNING = "running"
+EV_DONE = "done"
+EV_VERIFY_FAILED = "verify_failed"
+EV_REOPENED = "reopened"
+EV_MERGED = "merged"
+EV_CLOSED = "closed"
+EV_BLOCKED = "blocked"
+EV_CANCELLED = "cancelled"
+
+# 迁移矩阵：主链 todo→dispatched→running→done→merged→closed；blocked 双出口
+# （cancel／对同任务再 dispatch）；done→verify_failed（verify 败）与 reopened
+# （集成败/非 ff）→running 续修再 done。verify_failed→blocked 不在此列——
+# 它只由 fail_streak≥3 自动触发，非手工边。
+LEGAL = {
+    "todo": {"dispatched", "cancelled"},
+    "dispatched": {"running", "cancelled"},
+    "running": {"done", "cancelled"},
+    "done": {"merged", "verify_failed", "reopened"},
+    "verify_failed": {"running", "cancelled"},
+    "reopened": {"running", "cancelled"},
+    "merged": {"closed"},
+    "blocked": {"cancelled", "dispatched"},
+    "cancelled": set(),
+    "closed": set(),
+}
+TERMINAL = {"cancelled", "closed"}
+
+
+class InvalidTransition(Exception):
+    def __init__(self, tid, frm, to, legal):
+        self.tid, self.frm, self.to, self.legal = tid, frm, to, legal
+        super().__init__(f"{tid}: {frm}->{to} 非法（合法后继：{sorted(legal)}）")
+
+
+class State:
+    """权威任务状态：内存迁移＋append_state 落盘；末行快照＝权威（重启 load 恢复）。
+
+    全部读写持内置锁（RLock：gate_tail 结算内重入迁移）；持久化在锁内完成，
+    快照行序＝迁移序（§4.8）。
+    """
+
+    def __init__(self, store):
+        self._store = store
+        self._lock = threading.RLock()
+        snap = store.load_state() or {}
+        self._tasks = {tid: dict(t) for tid, t in snap.get("tasks", {}).items()}
+        self._mail_read = dict(snap.get("mail_read", {}))
+
+    def get(self, tid):
+        with self._lock:
+            return copy.deepcopy(self._tasks[tid])
+
+    def add(self, tid, row):
+        """播种新任务行（task_create；行构造归调用方）——迁移矩阵只管既有行。"""
+        with self._lock:
+            self._tasks[tid] = dict(row)
+            self._persist()
+
+    def set_fields(self, tid, **fields):
+        """非迁移字段直改（verify 登记/pending-cancel）——不越迁移矩阵。"""
+        with self._lock:
+            self._tasks[tid].update(fields)
+            self._tasks[tid]["updated"] = time.time()
+            self._persist()
+
+    def snapshot(self):
+        with self._lock:
+            return self._snap()
+
+    def touch_mail(self, sid):
+        with self._lock:
+            self._mail_read[sid] = time.time()
+
+    def touch_seen(self, tid):
+        """last_seen 心跳只进内存（gt-a18ef6 写放大根因修复）：O(调用数) 全量
+        快照落盘曾致账本 4.4GB——追加仅随真实迁移；崩溃回退按模块头语义
+        接受（同 touch_mail 口径）。"""
+        with self._lock:
+            t = self._tasks.get(tid)
+            if t is not None:
+                t["last_seen"] = time.time()
+
+    def transition(self, tid, to, **fields):
+        with self._lock:
+            t = self._tasks[tid]
+            legal = LEGAL.get(t["state"], set())
+            if to not in legal:
+                raise InvalidTransition(tid, t["state"], to, legal)
+            t["state"] = to
+            t["updated"] = time.time()
+            t.update(fields)
+            if to == EV_DISPATCHED:
+                t["fail_streak"] = 0  # 对同任务再 dispatch 清零连败
+            self._persist()
+
+    def queue_cancel(self, tid, cancel_reason=None) -> bool:
+        """门临界段 cancel 排队（持锁判定＋置位一体）：True=待门尾消费。
+
+        done 一律排队（迁移矩阵 done 无 cancelled 出口，必经门尾）；与 gate_tail
+        同锁互斥——门尾结算前后到达的排队要么被取走、要么待下一门跑/重启重排
+        （F-4）消费，判定与置位不撕裂。
+        """
+        with self._lock:
+            t = self._tasks[tid]
+            if t["state"] != EV_DONE:
+                return False
+            t["pending_cancel"] = True
+            if cancel_reason is not None:
+                t["pending_cancel_reason"] = cancel_reason
+            else:
+                t.pop("pending_cancel_reason", None)  # 后来的主动取消覆盖自动停链原因
+            t["updated"] = time.time()
+            self._persist()
+            return True
+
+    def clear_gate_latches(self):
+        """启动清残留门闩：门线程不跨进程存活，kill -9 残闩是撒谎闩（二批决策）。"""
+        with self._lock:
+            for tid, t in self._tasks.items():
+                if t.get("in_gate"):
+                    t["in_gate"] = False
+                    self._store.append_event({"ts": time.time(), "actor": "agorad",
+                                              "event": "gate_latch_reset", "task": tid})
+            self._persist()
+
+    def gate_tail(self, tid) -> dict:
+        """门尾原子结算：pending 取走＋终态写入同临界区（cancel×门尾 TOCTOU 封闭）。
+
+        pending 且非 merged→cancelled；merged→closed（不逆转历史）；余者仅清
+        门闩。返回结算后行快照（含 env/会话指针，供门侧副作用）。
+        """
+        with self._lock:
+            t = self._tasks[tid]
+            pending = bool(t.pop("pending_cancel", False))
+            cancel_reason = t.pop("pending_cancel_reason", None)
+            if pending and t["state"] != EV_MERGED:
+                fields = {"cancel_reason": cancel_reason} if cancel_reason else {}
+                self.transition(tid, EV_CANCELLED, in_gate=False, **fields)
+            elif t["state"] == EV_MERGED:
+                self.transition(tid, EV_CLOSED, in_gate=False)
+            else:
+                t["in_gate"] = False
+                t["updated"] = time.time()
+                self._persist()
+            return copy.deepcopy(t)
+
+    def fail_streak_bump(self, tid):
+        with self._lock:
+            t = self._tasks[tid]
+            t["fail_streak"] = t.get("fail_streak", 0) + 1
+            t["updated"] = time.time()
+            if t["fail_streak"] >= 3 and t["state"] not in TERMINAL | {"blocked"}:
+                t["state"] = EV_BLOCKED  # 连续 3 次质量败→自动 blocked
+            self._persist()
+
+    def fail_streak_reset(self, tid):
+        with self._lock:
+            t = self._tasks[tid]
+            t["fail_streak"] = 0
+            t["updated"] = time.time()
+            self._persist()
+
+    def _snap(self):
+        return {"version": 1, "tasks": copy.deepcopy(self._tasks),
+                "mail_read": dict(self._mail_read)}
+
+    def _persist(self):
+        self._store.append_state(self._snap())  # 调用方持锁：迁移＋append 同临界区