foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/itinerary/runtime.py

@@ -0,0 +1,148 @@
+"""
+Foxclaw 行程子系统 — Itinerary Runtime
+行程行为操作系统:采集行程点 → 地理编码(高德或手动) → 路线优化 →
+冲突/可达检测 → 行程守门人。高德可用时自动用真实路线替换估算。
+"""
+
+import csv
+from pathlib import Path
+
+from .models import Waypoint, ItineraryVerdict
+from .reasoning import ItineraryReasoning
+from .amap_client import AMapClient
+
+
+class ItineraryRuntime:
+    """行政 Agent 的行程内核。"""
+
+    def __init__(self, amap_key: str = None, hmr=None):
+        self.waypoints: list = []
+        self.reasoning = ItineraryReasoning()
+        self.amap = AMapClient(amap_key)
+        self.hmr = hmr
+
+    @property
+    def amap_enabled(self) -> bool:
+        return self.amap.enabled
+
+    # ── 采集行程点 ────────────────────────────────────────
+    def add_waypoint(self, name: str, address: str = "", lng: float = None,
+                     lat: float = None, start_time: str = None,
+                     duration_min: int = 0, city: str = "") -> dict:
+        wp = Waypoint(name=name, address=address, lng=lng, lat=lat,
+                      start_time=start_time, duration_min=duration_min, city=city)
+        # 没坐标但有地址 → 尝试高德地理编码
+        if not wp.has_coord and address and self.amap_enabled:
+            geo = self.amap.geocode(address, city)
+            if geo:
+                wp.lng, wp.lat = geo
+        self.waypoints.append(wp)
+        if self.hmr:
+            try:
+                self.hmr.ingest(content=f"行程:{name} @ {address or wp.coord_str} "
+                                        f"{start_time or ''}",
+                                type="task", agent_id="office",
+                                title=f"行程_{name}", tags=["itinerary"])
+            except Exception:
+                pass
+        return wp.to_dict()
+
+    def import_csv(self, path: str) -> int:
+        """CSV 导入。列:name,address,lng,lat,start_time,duration_min,city"""
+        count = 0
+        with open(Path(path), encoding="utf-8") as f:
+            for row in csv.DictReader(f):
+                self.add_waypoint(
+                    name=row["name"], address=row.get("address", ""),
+                    lng=float(row["lng"]) if row.get("lng") else None,
+                    lat=float(row["lat"]) if row.get("lat") else None,
+                    start_time=row.get("start_time") or None,
+                    duration_min=int(row.get("duration_min") or 0),
+                    city=row.get("city", ""))
+                count += 1
+        return count
+
+    # ── 真实路线(高德优先,否则估算)─────────────────────
+    def real_leg(self, a: Waypoint, b: Waypoint, mode: str = "driving"):
+        """两点路线:高德可用且有坐标时用真实数据,否则直线估算。"""
+        if self.amap_enabled and a.has_coord and b.has_coord:
+            r = self.amap.route(a.coord_str, b.coord_str, mode, a.city)
+            if r:
+                from .models import RouteLeg
+                return RouteLeg(from_id=a.id, to_id=b.id, from_name=a.name,
+                                to_name=b.name, mode=mode,
+                                distance_km=r["distance_km"],
+                                duration_min=r["duration_min"], source="amap")
+        return self.reasoning.estimate_leg(a, b, mode)
+
+    # ── 综合分析(行政 Agent 核心输出)────────────────────
+    def plan(self, mode: str = "driving", optimize: bool = True) -> dict:
+        """完整行程规划:优化顺序 + 冲突检测 + 聚类 + 守门人裁决。"""
+        opt = (self.reasoning.optimize_order(self.waypoints, mode)
+               if optimize else None)
+        conflicts = self.reasoning.detect_conflicts(self.waypoints, mode)
+        clusters = self.reasoning.cluster_by_proximity(self.waypoints)
+        dens = self.reasoning.density(self.waypoints, mode)
+        verdicts = self._gatekeeper(conflicts, clusters, dens)
+        return {
+            "waypoint_count": len(self.waypoints),
+            "amap_enabled": self.amap_enabled,
+            "optimized_route": opt,
+            "conflicts": conflicts,
+            "proximity_clusters": clusters,
+            "density": dens,
+            "gatekeeper_verdicts": [v.to_dict() for v in verdicts],
+            "map_data": self._to_amap_mapdata(opt),
+        }
+
+    # ── 行程守门人 ────────────────────────────────────────
+    def _gatekeeper(self, conflicts, clusters, dens) -> list:
+        verdicts = []
+        for c in conflicts:
+            if c["type"] == "time_conflict":
+                verdicts.append(ItineraryVerdict(
+                    rule_id="time_conflict", action="time_conflict",
+                    severity="critical", message=c["reason"], waypoint_ids=c["ids"]))
+            elif c["type"] == "unreachable":
+                verdicts.append(ItineraryVerdict(
+                    rule_id="unreachable", action="unreachable",
+                    severity="critical", message=c["reason"], waypoint_ids=c["ids"]))
+        if dens["cross_city"]:
+            verdicts.append(ItineraryVerdict(
+                rule_id="cross_city", action="cross_city", severity="warn",
+                message=f"行程跨城市:{','.join(dens['cities'])},注意城际交通时间",
+                payload={"cities": dens["cities"]}))
+        if dens["total_commute_min"] > 180:
+            verdicts.append(ItineraryVerdict(
+                rule_id="too_dense", action="too_dense", severity="warn",
+                message=f"总通勤 {dens['total_commute_min']:.0f} 分钟过长,建议精简或分天",
+                payload=dens))
+        for cl in clusters:
+            verdicts.append(ItineraryVerdict(
+                rule_id="reorder", action="suggest_reorder", severity="info",
+                message=f"这几处相近,建议顺路一起办:{' · '.join(cl)}",
+                payload={"cluster": cl}))
+        return verdicts
+
+    # ── 导出高德可视化格式(MapTaskData)──────────────────
+    def _to_amap_mapdata(self, opt) -> list:
+        """转成高德 MapTaskData(POI + route),可喂给高德生成可视化地图。"""
+        data = []
+        for wp in self.waypoints:
+            if wp.has_coord:
+                data.append({"type": "poi", "lnglat": [wp.lng, wp.lat],
+                             "text": wp.name, "remark": wp.address or wp.note})
+        if opt and opt.get("legs"):
+            id2wp = {w.id: w for w in self.waypoints}
+            for leg in opt["legs"]:
+                a, b = id2wp.get(leg["from_id"]), id2wp.get(leg["to_id"])
+                if a and b and a.has_coord and b.has_coord:
+                    data.append({"type": "route", "routeType": leg["mode"],
+                                 "start": [a.lng, a.lat], "end": [b.lng, b.lat],
+                                 "remark": f"{a.name}→{b.name}"})
+        return data
+
+    def status(self) -> dict:
+        return {"waypoints": len(self.waypoints),
+                "amap_enabled": self.amap_enabled,
+                "with_coord": sum(1 for w in self.waypoints if w.has_coord)}

package/python/foxclaw/kernel/__init__.py

@@ -0,0 +1,13 @@
+"""Foxclaw 内核层:进程管理、调度、事件脊柱、能力注册等 OS 式抽象。"""
+from .process_manager import ProcessManager, ProcessRecord
+from .spine import EventSpine, Event
+from .capabilities import CapabilityRegistry
+from .scheduler import Scheduler
+from .policy_gate import PolicyGate, Verdict
+
+__all__ = [
+    "ProcessManager", "ProcessRecord",
+    "EventSpine", "Event",
+    "CapabilityRegistry", "Scheduler",
+    "PolicyGate", "Verdict",
+]

package/python/foxclaw/kernel/capabilities.py

@@ -0,0 +1,73 @@
+"""
+CapabilityRegistry —— 能力注册中枢(P1-3:God Object → Composition Root)。
+
+审计结论:Foxclaw.__init__ 是个 God Object,子系统之间还形成两处对象环
+(Supervisor⇄Orchestrator、agents⇄search_runtime⇄agent_port⇄agents)——组件直接
+互相持有具体引用,违反 Clean Architecture。
+
+方案:引入单一注册中枢。组件不再直接持有"同伴组件"的具体引用,而是持有本注册表、
+按名字**惰性解析**(依赖倒置:依赖注册表抽象,而非具体同伴)。于是:
+  · 直接的"A→B 且 B→A"互持消失(两处直接环被打断);
+  · 解析统一走一个 hub(Composition Root 模式),构造顺序不再产生初始化环;
+  · 支持 register_lazy:重/可选能力(HKC、SearchRuntime)首次被解析时才构造。
+
+注:hub 与组件之间仍是可达环(注册表持有组件、组件持有注册表),这是 Service Locator
+的固有形态,由 GC 正常回收;本次要消除的是"具体同伴之间的直接互持",而非对象图可达性。
+"""
+from __future__ import annotations
+import threading
+from typing import Any, Callable
+
+
+class CapabilityRegistry:
+    """按名字注册/解析能力。支持惰性(首次解析才构造)。线程安全。"""
+
+    def __init__(self):
+        self._caps: dict[str, Any] = {}
+        self._lazy: dict[str, Callable[[], Any]] = {}
+        self._lock = threading.RLock()             # 只护 _caps/_lazy 表(快照,持锁时间极短)
+        self._build_locks: dict[str, threading.Lock] = {}   # name -> 构造锁(per-name)
+
+    def register(self, name: str, handle: Any) -> None:
+        """注册一个已构造好的能力实例(覆盖同名)。"""
+        with self._lock:
+            self._caps[name] = handle
+
+    def register_lazy(self, name: str, factory: Callable[[], Any]) -> None:
+        """注册惰性能力:首次 get(name) 时调用 factory 构造并缓存。"""
+        with self._lock:
+            self._lazy[name] = factory
+
+    def get(self, name: str, default: Any = None) -> Any:
+        """解析能力。已注册直接返回;惰性则首次构造并缓存;都没有返回 default。
+
+        【F1 修复】慢惰性构造(如 search_runtime 首建要装 HKC+载模型)**不持全局锁**,
+        改用 per-name 构造锁:同一能力串行构造(只建一次、无双重构造),不同能力互不阻塞
+        (避免"首建 search 时,并发的 cross_request 解析 agents 被卡住")。factory 内部
+        可安全再 get 其它能力(全局锁此时未被本调用持有)。"""
+        with self._lock:
+            if name in self._caps:
+                return self._caps[name]
+            factory = self._lazy.get(name)
+            if factory is None:
+                return default
+            blk = self._build_locks.get(name)
+            if blk is None:
+                blk = self._build_locks[name] = threading.Lock()
+        # 出全局锁,用 per-name 锁串行化"同一能力"的构造
+        with blk:
+            with self._lock:
+                if name in self._caps:      # 双检:构造期间可能已被别的线程建好
+                    return self._caps[name]
+            inst = factory()                # 慢构造:不持全局锁,不阻塞其它能力解析
+            with self._lock:
+                self._caps[name] = inst
+                return inst
+
+    def has(self, name: str) -> bool:
+        with self._lock:
+            return name in self._caps or name in self._lazy
+
+    def names(self) -> list[str]:
+        with self._lock:
+            return sorted(set(self._caps) | set(self._lazy))

package/python/foxclaw/kernel/policy_gate.py

@@ -0,0 +1,114 @@
+"""
+PolicyGate —— 统一准入门(v2 ① Step4)。
+
+审计:系统有两个"门",分属不同策略域、返回不同裁决形状:
+  · Harness(推理漂移:语义/工具/范围)—— 内联在 _think,返回 HarnessResult(PASS/WARN/BLOCK);
+  · skill-guard(动作权限:destructive/trust/deny>ask>allow)—— 在 SkillAdapter.invoke,返回 PermissionDecision。
+
+PolicyGate 把它们统一到**一套 Verdict 词汇(allow/warn/deny/confirm)+ 一个接口**下:
+引擎实现不动(它们是策略实现),门面只做**归一化** + 动作路径的**统一 policy.decision 审计事件**。
+两条路都经门面走(pass-through:底层同一次 check/evaluate、同一结果 → 行为逐字不变)。
+
+不 import Harness/skills(避免 kernel→上层环):harness 作参数传入(鸭子类型);
+动作评估器 evaluate 由 Foxclaw **注入**。
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+from ..core.governance_audit import new_decision_id
+
+
+@dataclass
+class Verdict:
+    allowed: bool
+    level: str                 # allow | warn | deny | confirm
+    reason: str = ""
+    source: str = ""           # harness | permission
+    raw: Any = None            # 原始 HarnessResult / PermissionDecision(调用方按需取用)
+    # 【P3-4】每次裁决的唯一 ID(P1-2 治理审计的关联键)。放最后+默认值:既有位置参数
+    # 构造(如 Verdict(True,"allow",...,"permission",None))不受影响。
+    decision_id: str = field(default="")
+
+
+class PolicyGate:
+    def __init__(self, spine=None, action_evaluator: Optional[Callable] = None,
+                 auditor=None):
+        self._spine = spine
+        self._eval = action_evaluator   # skills.permission.evaluate,注入(避免 kernel→skills 环)
+        # 【P1-2】统一治理审计(可空:standalone 无审计)。鸭子类型注入,避免 kernel→core 之外
+        # 的装配环;core.governance_audit.GovernanceAuditor 是唯一预期实现。
+        self._auditor = auditor
+
+    @property
+    def auditor(self):
+        """SkillAdapter 经此取审计器,把执行终态关联到裁决 decision_id(P3-4 跨层关联)。"""
+        return self._auditor
+
+    # ── 推理准入(Harness)──────────────────────────────────────
+    def check_reasoning(self, harness, node) -> Verdict:
+        """经统一门做推理漂移准入。底层仍是那一次 harness.check(同一 HarnessResult),
+        Harness 自身已 emit harness_block/warn 事件,门面**不重复 emit**。行为一致。
+
+        【P1-2】非 allow(warn/deny)时另记一条 governance.decision(layer=harness)——
+        那是**统一审计流**的新增记录,不是重复 emit 既有 harness_* 事件;PASS 高频常态不记。"""
+        r = harness.check(node)
+        level = "deny" if r.is_blocked else ("warn" if r.is_warned else "allow")
+        v = Verdict(allowed=not r.is_blocked, level=level,
+                    reason=(r.reason or ""), source="harness", raw=r,
+                    decision_id=new_decision_id())
+        if level != "allow":
+            self._audit(v, actor=getattr(node, "agent_id", ""),
+                        action=f"reasoning:{getattr(node, 'type', '')}",
+                        detail={"node_id": getattr(node, "id", ""),
+                                "dominant_dim": getattr(r, "dominant_dim", "")})
+        return v
+
+    # ── 动作准入(skill-guard)──────────────────────────────────
+    def check_action(self, skill, args: dict, rules=None,
+                     confirmed: bool = False, mode: str = "strict",
+                     taint_level: int = 0, taint_threshold: int = 0) -> Verdict:
+        """经统一门做动作权限准入。底层仍是 permission.evaluate(同一 PermissionDecision);
+        归一化为 Verdict,并对**非 allow**发统一 policy.decision.* 审计事件(动作路径原本无统一事件)。
+
+        【P3-4】每次裁决都带 decision_id(allow 也带——调用方 SkillAdapter 拿它做执行审计的
+        correlation_id,把「谁批准的」与「执行结果」join 起来)。
+
+        【污点门槛透传】taint_level/threshold 原样交给评估器。此前门面没接这两个参数,导致
+        permission.evaluate 的 Stage 3.5(碰过敏感数据 → 外发/副作用须确认)只有工具路径能触发,
+        技能路径永不触发。注入的评估器(permission.evaluate / sentinel.evaluate)签名都带这两个
+        kwarg;默认 0 = 关闭,既有调用方行为不变。"""
+        if self._eval is None:
+            return Verdict(True, "allow", "无动作评估器(降级放行)", "permission", None,
+                           decision_id=new_decision_id())
+        d = self._eval(skill, args, rules=rules, confirmed=confirmed, mode=mode,
+                       taint_level=taint_level, taint_threshold=taint_threshold)
+        level = {"allow": "allow", "ask": "confirm", "deny": "deny"}.get(d.decision, "deny")
+        v = Verdict(allowed=(d.decision == "allow"), level=level,
+                    reason=(d.reason or ""), source="permission", raw=d,
+                    decision_id=new_decision_id())
+        if level != "allow":
+            self._emit(v, getattr(skill, "id", ""))
+            self._audit(v, actor="", action=f"action:{getattr(skill, 'id', '')}",
+                        detail={"stage": getattr(d, "stage", 0),
+                                "trust_downgrade": getattr(d, "trust_downgrade", False)})
+        return v
+
+    def _emit(self, v: Verdict, skill_id: str) -> None:
+        if self._spine is None:
+            return
+        try:
+            self._spine.publish(f"policy.decision.{v.level}", {
+                "source": v.source, "level": v.level,
+                "reason": v.reason, "skill": skill_id,
+                "decision_id": v.decision_id}, source="policy_gate")
+        except Exception:
+            pass
+
+    def _audit(self, v: Verdict, actor: str, action: str, detail: dict) -> None:
+        """记统一治理审计流(P1-2)。审计器可空;记录失败绝不影响裁决(审计器内部已兜)。"""
+        if self._auditor is None:
+            return
+        self._auditor.record(layer=v.source, actor=actor, action=action,
+                             verdict=v.level, reason=v.reason,
+                             detail=detail, decision_id=v.decision_id)

package/python/foxclaw/kernel/process_manager.py

@@ -0,0 +1,205 @@
+"""
+进程管理器 (ProcessManager)
+
+把每个任务建模成操作系统的"进程",管理其完整生命周期:
+  created → queued → scheduled → running → completed / failed
+
+借鉴 Codex 版 Foxclaw 的 ProcessManager,适配本项目:
+- 与认知调度器结合:进程携带调度决策(优先级/路由)
+- 与真值管线结合:状态变更可发事件
+- 保留 state_history:每个进程的完整状态轨迹可追溯(对齐可观测原则)
+
+这让"任务执行"从一次性函数调用,变成可观测、可追溯的"进程生命周期"。
+"""
+from __future__ import annotations
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+
+
+# 合法状态与允许的流转(状态机约束:防止非法跳转)
+_VALID_TRANSITIONS = {
+    "created":   {"queued", "failed"},
+    "queued":    {"scheduled", "failed"},
+    "scheduled": {"running", "failed"},
+    "running":   {"completed", "failed"},
+    "completed": set(),        # 终态
+    "failed":    set(),        # 终态
+}
+_TERMINAL = {"completed", "failed"}
+
+
+@dataclass
+class ProcessRecord:
+    task: str
+    agent_id: str = None
+    state: str = "created"
+    process_id: str = field(default_factory=lambda: f"proc_{uuid.uuid4().hex[:8]}")
+    priority: float = 0.0
+    route_hint: str = None
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    state_history: list = field(default_factory=list)
+    fail_reason: str = None
+
+    def to_dict(self) -> dict:
+        return {
+            "process_id": self.process_id, "task": self.task,
+            "agent_id": self.agent_id, "state": self.state,
+            "priority": self.priority, "route_hint": self.route_hint,
+            "state_history": self.state_history, "fail_reason": self.fail_reason,
+            "created_at": self.created_at, "updated_at": self.updated_at,
+        }
+
+
+class ProcessManager:
+    """进程生命周期管理。每个任务一个进程,状态受状态机约束。"""
+
+    def __init__(self, bus=None, history_limit: int = 1000):
+        self._processes: dict[str, ProcessRecord] = {}
+        self.bus = bus                      # 可选:状态变更发事件
+        self._history_limit = history_limit
+        # 【深审优化】活跃(非终态)进程数的 O(1) 增量计数:create 时 +1、进入终态时 -1
+        # (集中在 _transition)。供 CognitiveState 每次 lifecycle 事件 O(1) 取用,
+        # 免去原先每事件 stats() 遍历全部进程(O(n),n≤1000)。
+        self._active = 0
+        # 并行子 Agent 会让多个线程并发 create/mark_*/_evict 同一个 _processes dict,
+        # 且状态机流转是"读 state → 校验 → 写 state"的非原子序列。RLock 保证:
+        #   · dict 增删与遍历(list/stats/_evict)不撞"dict changed size";
+        #   · 同一进程的并发二次流转不会都通过终态校验后重复 transition。
+        # 可重入:_emit→bus.publish 的处理器可能回调 pm 的方法(同线程重入安全)。
+        self._lock = threading.RLock()
+
+    def create(self, task: str, agent_id: str = None,
+               schedule: dict = None) -> ProcessRecord:
+        """创建进程(任务进入系统)。携带调度决策。"""
+        rec = ProcessRecord(
+            task=task, agent_id=agent_id,
+            priority=(schedule or {}).get("priority", 0.0),
+            route_hint=(schedule or {}).get("route_hint"),
+        )
+        with self._lock:
+            rec.state_history.append("created")
+            # 创建后立即入队 → 已调度(调度决策此时已有)
+            self._transition(rec, "queued")
+            if schedule:
+                self._transition(rec, "scheduled")
+            self._processes[rec.process_id] = rec
+            self._active += 1              # 新进程为活跃(此刻处于 queued/scheduled 非终态)
+            self._evict_if_needed()
+            self._emit(rec)
+        return rec
+
+    def mark_running(self, process_id: str) -> ProcessRecord:
+        with self._lock:
+            rec = self._processes.get(process_id)
+            if rec is None:
+                return None
+            # 若仍在 queued(create 未带 schedule),先补 scheduled 再 running
+            if rec.state == "queued":
+                self._transition(rec, "scheduled")
+            return self._safe_transition(process_id, "running")
+
+    def mark_completed(self, process_id: str) -> ProcessRecord:
+        with self._lock:
+            return self._safe_transition(process_id, "completed")
+
+    def mark_failed(self, process_id: str, reason: str = "") -> ProcessRecord:
+        with self._lock:
+            rec = self._processes.get(process_id)
+            if rec is None:
+                return None
+            # 已是终态 → 幂等忽略(重试/并发下的二次标记不算错误,不崩溃)
+            if rec.state in _TERMINAL:
+                return rec
+            self._transition(rec, "failed")
+            rec.fail_reason = reason
+            self._emit(rec)
+            return rec
+
+    def get(self, process_id: str) -> ProcessRecord:
+        with self._lock:
+            return self._processes.get(process_id)
+
+    def list(self, state: str = None, limit: int = 50) -> list:
+        with self._lock:
+            items = list(self._processes.values())
+        if state:
+            items = [r for r in items if r.state == state]
+        items.sort(key=lambda r: r.created_at, reverse=True)
+        return [r.to_dict() for r in items[:limit]]
+
+    def active_count(self) -> int:
+        """活跃(非终态:queued/scheduled/running/created)进程数,O(1) 增量维护。
+        供高频 lifecycle 事件消费(免去每次 stats() 遍历全部进程)。"""
+        with self._lock:
+            return self._active
+
+    def stats(self) -> dict:
+        with self._lock:
+            counts = {}
+            for r in self._processes.values():
+                counts[r.state] = counts.get(r.state, 0) + 1
+            return {"total": len(self._processes), "by_state": counts,
+                    "active": self._active}
+
+    # ── 内部 ──
+    def _safe_transition(self, process_id: str, next_state: str) -> ProcessRecord:
+        rec = self._processes.get(process_id)
+        if rec is None:
+            return None
+        # 已是终态 → 幂等忽略(不崩溃)
+        if rec.state in _TERMINAL:
+            return rec
+        # 已在目标状态 → 幂等忽略(重复标记不报错)
+        if rec.state == next_state:
+            return rec
+        self._transition(rec, next_state)
+        self._emit(rec)
+        return rec
+
+    def _transition(self, rec: ProcessRecord, next_state: str):
+        """受状态机约束的状态流转。真正非法的跳转(如跳过中间态)抛错 fail-fast。
+
+        【P5-3】终态守卫:已是终态的进程再流转 → 幂等忽略(不改状态、不重复 -1)。
+        此前"不会重复 -1"完全依赖上游 _safe_transition/mark_failed 的守卫——若未来
+        新增调用点直接调本方法,活跃计数会被重复扣减(可扣成负数,stats 失真)。
+        这里是双保险。注意行为变更:终态 → 任何状态,从抛 ValueError 变为静默忽略。
+        """
+        # 已是终态 → 幂等忽略(不再 -1,不再改状态)
+        if rec.state in _TERMINAL:
+            return
+        allowed = _VALID_TRANSITIONS.get(rec.state, set())
+        if next_state not in allowed:
+            raise ValueError(
+                f"非法状态流转: {rec.state} → {next_state}(进程 {rec.process_id})")
+        # 进入终态 → 活跃计数 -1(每进程恰好 create 时 +1、首次入终态时 -1;
+        # 上面的终态守卫保证不会重复扣减)。
+        if next_state in _TERMINAL:
+            self._active -= 1
+        rec.state = next_state
+        rec.updated_at = time.time()
+        rec.state_history.append(next_state)
+
+    def _emit(self, rec: ProcessRecord):
+        # 【v2 ① Step3·Lifecycle 统一】emit 唯一生命周期词汇 task.lifecycle.<state>
+        # (取代旧 process.state_changed;Scheduler 委托本 pm,不再自发另一套词汇)。
+        if self.bus is not None:
+            try:
+                self.bus.publish(f"task.lifecycle.{rec.state}", {
+                    "process_id": rec.process_id, "state": rec.state, "phase": rec.state,
+                    "task": rec.task, "agent_id": rec.agent_id,
+                })
+            except Exception:
+                pass
+
+    def _evict_if_needed(self):
+        """超出上限时,清理最老的终态进程(保留活跃进程)。"""
+        if len(self._processes) <= self._history_limit:
+            return
+        terminal = [(pid, r) for pid, r in self._processes.items()
+                    if r.state in _TERMINAL]
+        terminal.sort(key=lambda x: x[1].created_at)
+        for pid, _ in terminal[:len(self._processes) - self._history_limit]:
+            del self._processes[pid]