codebee 0.1.65 → 0.1.66

package/app/core/tlsctx.py

@@ -1,64 +1,64 @@
-# -*- coding: utf-8 -*-
-"""HTTPS 证书校验上下文：补齐 macOS 上 Python 缺失的 CA 源（不关校验）。
-
-现象：用官方 pkg 装 Node 的 Mac 上往往再装 python.org 的 Python，它不读
-系统钥匙串，默认验证路径下没有根证书，所有 HTTPS 请求报
-CERTIFICATE_VERIFY_FAILED（unable to get local issuer certificate）。
-
-修法是给默认上下文**追加**可用 CA 源，校验语义只增不减：
-  1. certifi（装了就用，跨平台最全）；
-  2. /etc/ssl/cert.pem（macOS 系统自带 CA 束，Catalina 起就有）。
-两个都拿不到时返回默认上下文——报错与旧行为一致，绝不静默关校验。
-"""
-import ssl
-import sys
-
-
-def cafiles():
-    """候选 CA 束路径；坏路径/不存在由 load_verify_locations 抛错后被吞。"""
-    out = []
-    try:
-        import certifi
-        out.append(certifi.where())
-    except Exception:
-        pass
-    if sys.platform == "darwin":
-        out.append("/etc/ssl/cert.pem")
-    return out
-
-
-def _build():
-    ctx = ssl.create_default_context()
-    for f in cafiles():
-        try:
-            ctx.load_verify_locations(cafile=f)
-        except Exception:
-            pass
-    return ctx
-
-
-_CTX = None
-
-
-def context():
-    """带兜底 CA 源的 ssl.SSLContext（进程内缓存；校验语义与默认一致）。"""
-    global _CTX
-    if _CTX is None:
-        _CTX = _build()
-    return _CTX
-
-
-def humanize(err_text):
-    """证书验证失败 → 可行动的人话提示（非证书类错误原样返回）。
-
-    兜底 CA 仍验证失败只剩两类真实原因：本机代理对 HTTPS 做 TLS 拦截
-    （其根证书只在系统钥匙串/浏览器里，Python 的静态 CA 束不认），或极端
-    环境连 /etc/ssl/cert.pem 都没有。SSL_CERT_FILE 是 OpenSSL 标准逃生门，
-    create_default_context() 本就吃它，无需额外代码。"""
-    text = str(err_text or "")
-    if "CERTIFICATE_VERIFY_FAILED" not in text:
-        return text
-    return (text + " —— 证书验证仍失败：① 若开着代理/安全软件且开启了 HTTPS 拦截，"
-            "关掉拦截，或把其根证书导出后设环境变量 SSL_CERT_FILE 指向它再启动；"
-            "② 确认系统存在 /etc/ssl/cert.pem；③ 刚升级过 CodeBee 的话，"
-            "旧服务进程可能还在跑——关掉终端窗口重开")
+# -*- coding: utf-8 -*-
+"""HTTPS 证书校验上下文：补齐 macOS 上 Python 缺失的 CA 源（不关校验）。
+
+现象：用官方 pkg 装 Node 的 Mac 上往往再装 python.org 的 Python，它不读
+系统钥匙串，默认验证路径下没有根证书，所有 HTTPS 请求报
+CERTIFICATE_VERIFY_FAILED（unable to get local issuer certificate）。
+
+修法是给默认上下文**追加**可用 CA 源，校验语义只增不减：
+  1. certifi（装了就用，跨平台最全）；
+  2. /etc/ssl/cert.pem（macOS 系统自带 CA 束，Catalina 起就有）。
+两个都拿不到时返回默认上下文——报错与旧行为一致，绝不静默关校验。
+"""
+import ssl
+import sys
+
+
+def cafiles():
+    """候选 CA 束路径；坏路径/不存在由 load_verify_locations 抛错后被吞。"""
+    out = []
+    try:
+        import certifi
+        out.append(certifi.where())
+    except Exception:
+        pass
+    if sys.platform == "darwin":
+        out.append("/etc/ssl/cert.pem")
+    return out
+
+
+def _build():
+    ctx = ssl.create_default_context()
+    for f in cafiles():
+        try:
+            ctx.load_verify_locations(cafile=f)
+        except Exception:
+            pass
+    return ctx
+
+
+_CTX = None
+
+
+def context():
+    """带兜底 CA 源的 ssl.SSLContext（进程内缓存；校验语义与默认一致）。"""
+    global _CTX
+    if _CTX is None:
+        _CTX = _build()
+    return _CTX
+
+
+def humanize(err_text):
+    """证书验证失败 → 可行动的人话提示（非证书类错误原样返回）。
+
+    兜底 CA 仍验证失败只剩两类真实原因：本机代理对 HTTPS 做 TLS 拦截
+    （其根证书只在系统钥匙串/浏览器里，Python 的静态 CA 束不认），或极端
+    环境连 /etc/ssl/cert.pem 都没有。SSL_CERT_FILE 是 OpenSSL 标准逃生门，
+    create_default_context() 本就吃它，无需额外代码。"""
+    text = str(err_text or "")
+    if "CERTIFICATE_VERIFY_FAILED" not in text:
+        return text
+    return (text + " —— 证书验证仍失败：① 若开着代理/安全软件且开启了 HTTPS 拦截，"
+            "关掉拦截，或把其根证书导出后设环境变量 SSL_CERT_FILE 指向它再启动；"
+            "② 确认系统存在 /etc/ssl/cert.pem；③ 刚升级过 CodeBee 的话，"
+            "旧服务进程可能还在跑——关掉终端窗口重开")

package/app/core/token_meter.py

@@ -1,148 +1,148 @@
-# -*- coding: utf-8 -*-
-"""Token 压力估算：按 run 累计 usage，给出「已用/容量」压力比。
-
-设计稿：docs/migration/02-context-compaction.md §1C。
-参考 dsh packages/llm/token-meter/src/index.ts：滑动窗口 + usage 锚点 + 失败重定价。
-
-Tutti 简化实现：每 run 一个累计窗口（deque 有上限），usage 来自
-runner._parse_codex_jsonl / _parse_claude_json 已解析的字段；
-容量查 DEFAULT_CAPACITY 表（可被 data/model_capacity.json 覆盖）。
-"""
-from __future__ import annotations
-
-import json
-import logging
-import threading
-import time
-from collections import deque
-from pathlib import Path
-
-log = logging.getLogger(__name__)
-
-# 默认模型容量（token）。未命中 key 时用 "" 兜底行。
-DEFAULT_CAPACITY = {
-    "": 128_000,
-    "gpt-5": 400_000,
-    "gpt-5.5": 400_000,
-    "deepseek-chat": 128_000,
-    "deepseek-reasoner": 64_000,
-    "qwen3-max": 256_000,
-    "qwen3.8-flash": 256_000,
-}
-
-# 压缩触发阈值（设计稿 §1B 默认 0.8，可被 orchestration.json 覆盖）
-DEFAULT_PRESSURE_THRESHOLD = 0.8
-
-# 容量覆盖文件（热改立即生效）
-_CAPACITY_FILE = Path(__file__).resolve().parents[2] / "data" / "model_capacity.json"
-
-
-def _load_capacity():
-    """默认表 + 可选覆盖文件合并。文件缺失/坏 JSON 静默用默认。"""
-    cap = dict(DEFAULT_CAPACITY)
-    try:
-        if _CAPACITY_FILE.is_file():
-            data = json.loads(_CAPACITY_FILE.read_text(encoding="utf-8"))
-            if isinstance(data, dict):
-                cap.update({str(k): int(v) for k, v in data.items()})
-    except Exception:
-        pass
-    return cap
-
-
-class TokenMeter:
-    """每 run 独立累计窗口；线程安全。"""
-
-    def __init__(self, capacity=None, *, window_size=200):
-        self._capacity_override = capacity
-        self._window_size = window_size
-        self._lock = threading.Lock()
-        # run_id -> deque[(ts, input, output, reasoning, cached)]
-        self._windows: dict = {}
-        # run_id -> 最后一次见到的 model 名（pressure_ratio 未显式传 model 时用）
-        self._last_model: dict = {}
-        self._cap_cache = None
-        self._cap_mtime = 0.0
-
-    def _capacity(self):
-        """容量表（带 mtime 缓存，热改 data/model_capacity.json 立即生效）。"""
-        try:
-            mtime = _CAPACITY_FILE.stat().st_mtime
-        except OSError:
-            mtime = 0.0
-        if self._cap_cache is None or mtime != self._cap_mtime:
-            if self._capacity_override is not None:
-                self._cap_cache = dict(self._capacity_override)
-            else:
-                self._cap_cache = _load_capacity()
-            self._cap_mtime = mtime
-        return self._cap_cache
-
-    def accumulate(self, run_id: str, usage, model: str = ""):
-        """记录一次调用的 usage。usage 字段缺失按 0 处理；usage=None 跳过。
-
-        cached 单独记录但不计入 used()——缓存读不占新一轮上下文压力
-        （与 runner._parse_claude_json 的口径一致：cached 是省钱的部分）。
-        """
-        if not usage:
-            return
-        with self._lock:
-            if model:
-                self._last_model[run_id] = model
-            window = self._windows.setdefault(run_id, deque(maxlen=self._window_size))
-            window.append((
-                time.time(),
-                int(usage.get("input") or 0),
-                int(usage.get("output") or 0),
-                int(usage.get("reasoning") or 0),
-                int(usage.get("cached") or 0),
-            ))
-
-    def used(self, run_id: str) -> int:
-        """窗口内累计（input + output + reasoning），不含 cached。"""
-        with self._lock:
-            window = self._windows.get(run_id)
-            if not window:
-                return 0
-            return sum(i + o + r for _, i, o, r, _ in window)
-
-    def cached(self, run_id: str) -> int:
-        with self._lock:
-            window = self._windows.get(run_id)
-            if not window:
-                return 0
-            return sum(c for _, _, _, _, c in window)
-
-    def pressure_ratio(self, run_id: str, model: str = "") -> float:
-        """已用 / 容量。model 未传时用该 run 最后一次见到的模型名。"""
-        cap_table = self._capacity()
-        with self._lock:
-            m = model or self._last_model.get(run_id, "")
-        cap = cap_table.get(m, cap_table.get("", 128_000))
-        return self.used(run_id) / max(cap, 1)
-
-    def capacity(self, model: str = "") -> int:
-        """模型上下文容量（未命中用默认行）。"""
-        cap_table = self._capacity()
-        return cap_table.get(model or "", cap_table.get("", 128_000))
-
-    def last_context(self, run_id: str) -> int:
-        """最近一次调用的 input+output+reasoning——下个请求要重发的上下文锚点。
-
-        used() 是窗口累计（多次调用叠加，系统性偏大，适合做响应式预算闸）；
-        事前预检判断「这个请求会不会被拒」要用最近一次的真实上下文体量，
-        两者口径不同不可混用（借鉴 freebuff base-chat 每步容量重估）。"""
-        with self._lock:
-            window = self._windows.get(run_id)
-            if not window:
-                return 0
-            _, i, o, r, _ = window[-1]
-            return i + o + r
-
-    def reset(self, run_id: str):
-        with self._lock:
-            self._windows.pop(run_id, None)
-            self._last_model.pop(run_id, None)
-
-
+# -*- coding: utf-8 -*-
+"""Token 压力估算：按 run 累计 usage，给出「已用/容量」压力比。
+
+设计稿：docs/migration/02-context-compaction.md §1C。
+参考 dsh packages/llm/token-meter/src/index.ts：滑动窗口 + usage 锚点 + 失败重定价。
+
+Tutti 简化实现：每 run 一个累计窗口（deque 有上限），usage 来自
+runner._parse_codex_jsonl / _parse_claude_json 已解析的字段；
+容量查 DEFAULT_CAPACITY 表（可被 data/model_capacity.json 覆盖）。
+"""
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from collections import deque
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+# 默认模型容量（token）。未命中 key 时用 "" 兜底行。
+DEFAULT_CAPACITY = {
+    "": 128_000,
+    "gpt-5": 400_000,
+    "gpt-5.5": 400_000,
+    "deepseek-chat": 128_000,
+    "deepseek-reasoner": 64_000,
+    "qwen3-max": 256_000,
+    "qwen3.8-flash": 256_000,
+}
+
+# 压缩触发阈值（设计稿 §1B 默认 0.8，可被 orchestration.json 覆盖）
+DEFAULT_PRESSURE_THRESHOLD = 0.8
+
+# 容量覆盖文件（热改立即生效）
+_CAPACITY_FILE = Path(__file__).resolve().parents[2] / "data" / "model_capacity.json"
+
+
+def _load_capacity():
+    """默认表 + 可选覆盖文件合并。文件缺失/坏 JSON 静默用默认。"""
+    cap = dict(DEFAULT_CAPACITY)
+    try:
+        if _CAPACITY_FILE.is_file():
+            data = json.loads(_CAPACITY_FILE.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                cap.update({str(k): int(v) for k, v in data.items()})
+    except Exception:
+        pass
+    return cap
+
+
+class TokenMeter:
+    """每 run 独立累计窗口；线程安全。"""
+
+    def __init__(self, capacity=None, *, window_size=200):
+        self._capacity_override = capacity
+        self._window_size = window_size
+        self._lock = threading.Lock()
+        # run_id -> deque[(ts, input, output, reasoning, cached)]
+        self._windows: dict = {}
+        # run_id -> 最后一次见到的 model 名（pressure_ratio 未显式传 model 时用）
+        self._last_model: dict = {}
+        self._cap_cache = None
+        self._cap_mtime = 0.0
+
+    def _capacity(self):
+        """容量表（带 mtime 缓存，热改 data/model_capacity.json 立即生效）。"""
+        try:
+            mtime = _CAPACITY_FILE.stat().st_mtime
+        except OSError:
+            mtime = 0.0
+        if self._cap_cache is None or mtime != self._cap_mtime:
+            if self._capacity_override is not None:
+                self._cap_cache = dict(self._capacity_override)
+            else:
+                self._cap_cache = _load_capacity()
+            self._cap_mtime = mtime
+        return self._cap_cache
+
+    def accumulate(self, run_id: str, usage, model: str = ""):
+        """记录一次调用的 usage。usage 字段缺失按 0 处理；usage=None 跳过。
+
+        cached 单独记录但不计入 used()——缓存读不占新一轮上下文压力
+        （与 runner._parse_claude_json 的口径一致：cached 是省钱的部分）。
+        """
+        if not usage:
+            return
+        with self._lock:
+            if model:
+                self._last_model[run_id] = model
+            window = self._windows.setdefault(run_id, deque(maxlen=self._window_size))
+            window.append((
+                time.time(),
+                int(usage.get("input") or 0),
+                int(usage.get("output") or 0),
+                int(usage.get("reasoning") or 0),
+                int(usage.get("cached") or 0),
+            ))
+
+    def used(self, run_id: str) -> int:
+        """窗口内累计（input + output + reasoning），不含 cached。"""
+        with self._lock:
+            window = self._windows.get(run_id)
+            if not window:
+                return 0
+            return sum(i + o + r for _, i, o, r, _ in window)
+
+    def cached(self, run_id: str) -> int:
+        with self._lock:
+            window = self._windows.get(run_id)
+            if not window:
+                return 0
+            return sum(c for _, _, _, _, c in window)
+
+    def pressure_ratio(self, run_id: str, model: str = "") -> float:
+        """已用 / 容量。model 未传时用该 run 最后一次见到的模型名。"""
+        cap_table = self._capacity()
+        with self._lock:
+            m = model or self._last_model.get(run_id, "")
+        cap = cap_table.get(m, cap_table.get("", 128_000))
+        return self.used(run_id) / max(cap, 1)
+
+    def capacity(self, model: str = "") -> int:
+        """模型上下文容量（未命中用默认行）。"""
+        cap_table = self._capacity()
+        return cap_table.get(model or "", cap_table.get("", 128_000))
+
+    def last_context(self, run_id: str) -> int:
+        """最近一次调用的 input+output+reasoning——下个请求要重发的上下文锚点。
+
+        used() 是窗口累计（多次调用叠加，系统性偏大，适合做响应式预算闸）；
+        事前预检判断「这个请求会不会被拒」要用最近一次的真实上下文体量，
+        两者口径不同不可混用（借鉴 freebuff base-chat 每步容量重估）。"""
+        with self._lock:
+            window = self._windows.get(run_id)
+            if not window:
+                return 0
+            _, i, o, r, _ = window[-1]
+            return i + o + r
+
+    def reset(self, run_id: str):
+        with self._lock:
+            self._windows.pop(run_id, None)
+            self._last_model.pop(run_id, None)
+
+
 token_meter = TokenMeter()  # 单例

package/app/core/upstream.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""Shared upstream identity normalization for routing and retry guards."""
+from __future__ import annotations
+
+import ipaddress
+from urllib.parse import urlsplit
+
+
+def normalize_upstream(value, default_scheme="https"):
+    """Return a stable host[:port] identity, without URL path or credentials.
+
+    Host names are case-insensitive and a trailing dot is equivalent to the
+    non-dotted form. Default HTTP(S) ports are omitted so equivalent URLs share
+    one failure/permission bucket. Non-default ports remain distinct.
+    """
+    raw = str(value or "").strip()
+    if not raw:
+        return ""
+    candidate = raw if "://" in raw else "%s://%s" % (default_scheme, raw)
+    try:
+        parsed = urlsplit(candidate)
+        host = parsed.hostname
+        if not host:
+            return ""
+        host = host.rstrip(".").lower()
+        ip_host = None
+        try:
+            ip_host = ipaddress.ip_address(host)
+            host = ip_host.compressed.lower()
+        except ValueError:
+            pass
+        port = parsed.port
+        scheme = (parsed.scheme or default_scheme).lower()
+        if port is not None and not ((scheme == "https" and port == 443)
+                                     or (scheme == "http" and port == 80)):
+            if getattr(ip_host, "version", None) == 6:
+                return "[%s]:%d" % (host, port)
+            return "%s:%d" % (host, port)
+        return host
+    except (TypeError, ValueError):
+        return ""

package/app/core/usage.py

@@ -30,7 +30,8 @@ DIMENSIONS = {
 
 FIELDS = ("ts", "day", "run_id", "step", "task_id", "task_type", "role", "agent", "agent_label",
           "tool", "model", "provider", "ok", "duration_s",
-          "input", "output", "cached", "reasoning", "total", "cost_usd", "source")
+          "input", "output", "cached", "reasoning", "total", "cost_usd", "source",
+          "first_token_ms", "tokens_per_sec")
 
 
 def _month_file(day):
@@ -63,7 +64,8 @@ def _parse_bool(v):
 
 def record(source="", run_id="", task_id="", task_type="", role="", step=0,
            agent="", agent_label="", tool="", model="", provider="",
-           ok=True, duration_s=0.0, cost_usd=0.0, usage=None):
+           ok=True, duration_s=0.0, cost_usd=0.0, usage=None,
+           first_token_ms=0.0, tokens_per_sec=0.0):
     """追加一条用量记录。usage 为细分 dict：{input, output, cached, reasoning, total}；
     缺省字段按 0 处理。任何异常都吞掉——统计永远不能拖垮业务调用方。
 
@@ -97,6 +99,19 @@ def record(source="", run_id="", task_id="", task_type="", role="", step=0,
         total = _parse_int(u.get("total")) or (inp + out + cach)
         rec.update({"input": inp, "output": out, "cached": cach,
                     "reasoning": reas, "total": total})
+        # 压缩省量注记（source=compaction 专用）：上下文折叠净省的估算 token，
+        # 与消耗并列成账——省了多少不再是黑箱。零值不落字段防老记录膨胀。
+        saved = max(0, _parse_int(u.get("saved")))
+        if saved:
+            rec["saved"] = saved
+        # 体验指标（§07）：只有内置直连的流式路径可测，CLI 事件流没有逐 token
+        # 时刻。零值不落字段——"缺字段"表示不可测，不能读成"首字 0 毫秒"。
+        ft = round(_parse_float(first_token_ms), 1)
+        if ft > 0:
+            rec["first_token_ms"] = ft
+        tps = round(_parse_float(tokens_per_sec), 2)
+        if tps > 0:
+            rec["tokens_per_sec"] = tps
         line = json.dumps(rec, ensure_ascii=False)
         with LOCK:
             paths.USAGE_DIR.mkdir(parents=True, exist_ok=True)
@@ -638,6 +653,21 @@ def summary(days=30, recent_limit=30):
     totals["cache_rate"] = round(totals["cached"] * 100.0 / denom, 1) if denom else 0.0
     totals["peak_tokens"] = max((bd["tokens"] for bd in by_day), default=0)
     totals["max_duration_s"] = round(max((float(r.get("duration_s") or 0.0) for r in records), default=0.0), 1)
+    # 压缩省量（source=compaction 记录的 saved 合计）：与消耗并列的第七维，
+    # 台账从此能答「省了多少」；无压缩记录时为 0，老前端不读不受影响
+    totals["compaction_saved"] = sum(_num(r, "saved") for r in records)
+    # 体验指标：只统计可测记录（缺失与 0 都表示"这条没测到"，不参与均值），
+    # 否则 CLI 路径会把首字延迟平均数拉到 0，读数即假数。
+    ft_list = sorted(_parse_float(r.get("first_token_ms")) for r in records
+                     if _parse_float(r.get("first_token_ms")) > 0)
+    tps_list = [_parse_float(r.get("tokens_per_sec")) for r in records
+                if _parse_float(r.get("tokens_per_sec")) > 0]
+    totals["perf_samples"] = len(ft_list)
+    totals["avg_first_token_ms"] = (round(sum(ft_list) / len(ft_list), 1)
+                                    if ft_list else 0.0)
+    totals["p95_first_token_ms"] = _percentile(ft_list, 0.95) if ft_list else 0.0
+    totals["avg_tokens_per_sec"] = (round(sum(tps_list) / len(tps_list), 2)
+                                    if tps_list else 0.0)
     cur, lng = _streaks(str(r.get("day") or "") for r in all_records)
     totals["streak_current"] = cur
     totals["streak_longest"] = lng
@@ -659,6 +689,8 @@ def summary(days=30, recent_limit=30):
     }
 
 
+THIN_SAMPLES = 10   # 低于此样本数即「薄样本」，口径见执行标准第 6 条
+
 _DURATION_BASELINES = {
     "direct": 90, "rank_scan": 240, "email": 180, "weekly_report": 240,
     "translation": 240, "speech": 360, "video_script": 360, "article": 480,
@@ -672,7 +704,9 @@ def estimate(task_type="", days=90, mode="auto", thinking="standard", rounds=Non
 
     同一 run 的多条步骤记录加总为一个样本，优先用成功 run，给中位数/平均/P90。
     无历史样本时使用流程级保守基线；模式与思考程度只做透明倍率修正。"""
-    span = max(1, min(3650, int(days or 90)))
+    # days<=0（UI 的「全部」档）不能退化成「只扫今天」：基线会跟着窗口一起坍缩，
+    # 于是全历史被估成 480 秒常数。按保守年限扫全量。
+    span = 3650 if days is not None and int(days) <= 0 else max(1, min(3650, int(days or 90)))
     with LOCK:
         records = _iter_records(span)
     runs = {}
@@ -703,11 +737,16 @@ def estimate(task_type="", days=90, mode="auto", thinking="standard", rounds=Non
     except (TypeError, ValueError):
         pass
     if not basis:
+        # 全历史里一条同类样本都没有（article/doc 等低频类型）时才用基线，
+        # 并在 duration_source 上如实标 baseline，UI 必须点名它不是实测。
         baseline = _DURATION_BASELINES.get(task_type, 480)
         median_s = max(30, int(baseline * factor))
         return {"task_type": task_type or "", "days": span, "samples": 0,
                 "estimated_duration_s": median_s,
                 "p90_duration_s": max(median_s + 30, int(median_s * 1.7)),
+                # 标准「成本与时延预算」第 6 条：样本 <10 即薄样本，UI 必须点名，
+                # 不能把"仅此一例"的历史当实测承诺。
+                "thin": True, "min_samples_for_estimate": THIN_SAMPLES,
                 "duration_source": "baseline"}
     toks = sorted(g["tokens"] for g in basis)
     costs = sorted(g["cost"] for g in basis)
@@ -742,6 +781,78 @@ def estimate(task_type="", days=90, mode="auto", thinking="standard", rounds=Non
         "estimated_duration_s": max(30, int(dmed * factor)),
         "p90_duration_s": max(60, int(dp90 * factor)),
         "duration_samples": len(durations),
+        "thin": n < THIN_SAMPLES, "min_samples_for_estimate": THIN_SAMPLES,
         "duration_source": duration_source,
         "since": (datetime.date.today() - datetime.timedelta(days=span - 1)).isoformat(),
     }
+
+
+def _audit_file(day):
+    return paths.USAGE_DIR / ("estimate-audit-%s.jsonl" % day[:7].replace("-", ""))
+
+
+_AUDITED = {}      # run_id -> 落盘路径；幂等去重，上限后整体清空防无界增长
+_AUDIT_LIMIT = 4000
+TERMINAL_STATUSES = ("done", "failed", "cancelled", "timeout")
+
+
+def audit_run(run):
+    """事后对账：开跑前的预估快照 vs 本次真实用量，一条 run 一行。
+
+    预估值只取 run 上的快照（store.create_run 落的 estimated_duration_s 等），
+    绝不回读当前 estimate()——那会把本次刚写入的消耗算进"预估"，比值永远偏低。
+    快照缺失（回填前的老 run、非编排类）时如实标 basis=none，不猜一个数充数。
+    """
+    try:
+        run_id = str((run or {}).get("id") or "")
+        if not run_id or run_id in _AUDITED:
+            return None
+        status = str(run.get("status") or "")
+        if status not in TERMINAL_STATUSES:
+            return None
+        task_type = str(run.get("task_type") or (run.get("op") or {}).get("type") or "")
+        est_s = _parse_float(run.get("estimated_duration_s"))
+        est_p90 = _parse_float(run.get("estimated_p90_s"))
+        basis = "stored"
+        if est_s <= 0:
+            # 快照缺失时退而用同类型历史口径，但必须落 basis=recomputed 标出来源
+            snap = estimate(task_type=task_type, days=(run.get("estimate_days") or 90))
+            est_s = _parse_float(snap.get("estimated_duration_s"))
+            est_p90 = _parse_float(snap.get("p90_duration_s"))
+            basis = "recomputed" if est_s > 0 else "none"
+        actual_s = 0.0
+        actual_tokens = 0
+        for r in _iter_records(366):
+            if str(r.get("run_id") or "") != run_id:
+                continue
+            actual_s += max(0.0, _parse_float(r.get("duration_s")))
+            actual_tokens += _parse_int(r.get("total"))
+        rec = {
+            "ts": time.strftime("%Y-%m-%d %H:%M:%S"),
+            "day": time.strftime("%Y-%m-%d"),
+            "run_id": run_id[:64],
+            "task_id": str(run.get("task_id") or "")[:64],
+            "task_type": task_type[:32] or "unknown",
+            "status": status[:16],
+            "est_duration_s": round(est_s, 1),
+            "est_p90_s": round(est_p90, 1),
+            "est_source": str(run.get("estimate_source") or "")[:16],
+            "est_samples": _parse_int(run.get("estimate_samples")),
+            "est_basis": basis[:16],
+            "actual_duration_s": round(actual_s, 1),
+            "actual_tokens": actual_tokens,
+            "ratio": round(actual_s / est_s, 3) if est_s > 0 else 0.0,
+            "over_p90": bool(est_p90 > 0 and actual_s > est_p90),
+        }
+        line = json.dumps(rec, ensure_ascii=False)
+        path = _audit_file(rec["day"])
+        with LOCK:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with open(path, "a", encoding="utf-8") as f:
+                f.write(line + "\n")
+        if len(_AUDITED) >= _AUDIT_LIMIT:
+            _AUDITED.clear()
+        _AUDITED[run_id] = str(path)
+        return rec
+    except Exception:
+        return None