codebee 0.1.22 → 0.1.24

package/app/core/portguard.py

@@ -0,0 +1,111 @@
+# -*- coding: utf-8 -*-
+"""启动端口清场（用户拍板 2026-09-21）：端口被占时先清场再启动。
+
+- **自家旧实例**（命令行含本包 main.py 完整路径，或 npm 包内 app/main.py）
+  → 杀树（TerminateProcess 直杀）——升级/重启最常见的占用者就是没退干净
+  的 CodeBee 自己；控制台进程对温和信号（WM_CLOSE）无反应，温和关不掉
+  正是用户「旧进程太难杀」的痛点，所以自家实例直接强杀。
+- **别人的进程** → 只报告占用者，不发送任何信号；启动流程不得替用户
+  关闭可能正在开发中的服务。
+- 系统/自身进程拒关（portscan 内置护栏）。
+"""
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+import subprocess
+
+from . import portscan, runner
+
+log = logging.getLogger(__name__)
+
+PS_EXE = "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
+
+
+def proc_cmdline(pid):
+    """读进程命令行；失败返回空串。仅用于确认旧 CodeBee 实例身份。"""
+    try:
+        pid = int(pid)
+    except (TypeError, ValueError):
+        return ""
+    if pid <= 0:
+        return ""
+    if os.name != "nt":
+        try:
+            with open("/proc/%d/cmdline" % pid, "rb") as fh:
+                return fh.read().decode("utf-8", "replace").replace("\x00", " ").strip()
+        except Exception:
+            return ""
+    try:
+        r = subprocess.run(
+            [PS_EXE, "-NoProfile", "-Command",
+             "(Get-CimInstance Win32_Process -Filter 'ProcessId = %d').CommandLine" % pid],
+            capture_output=True, timeout=10)
+        return r.stdout.decode("utf-8", "replace").strip() if r.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+def _command_tokens(cmdline):
+    try:
+        return [token.strip().strip('"').strip("'")
+                for token in shlex.split(str(cmdline or ""), posix=False)]
+    except (TypeError, ValueError):
+        return []
+
+
+def is_own_instance(cmdline, main_script, port=None):
+    """按启动器、脚本独立参数和端口精确确认 CodeBee 实例。"""
+    tokens = _command_tokens(cmdline)
+    if len(tokens) < 2:
+        return False
+    launcher = os.path.splitext(os.path.basename(tokens[0]))[0].lower()
+    if launcher not in ("python", "python3", "py"):
+        return False
+    script = ""
+    for token in tokens[1:]:
+        if token.startswith("-"):
+            continue
+        script = token
+        break
+    if not script or not os.path.isabs(script):
+        return False
+    actual = os.path.normcase(os.path.normpath(os.path.abspath(script)))
+    expected = os.path.normcase(os.path.normpath(os.path.abspath(str(main_script))))
+    packaged = actual.replace("\\", "/").lower().endswith(
+        "/node_modules/codebee/app/main.py")
+    if actual != expected and not packaged:
+        return False
+    if port is None:
+        return True
+    try:
+        wanted = str(int(port))
+    except (TypeError, ValueError):
+        return False
+    explicit_port = None
+    for i, token in enumerate(tokens):
+        if token == "--port" and i + 1 < len(tokens):
+            explicit_port = tokens[i + 1]
+        elif token.startswith("--port="):
+            explicit_port = token.split("=", 1)[1]
+    # argparse 默认端口可不出现在旧实例参数中；非默认端口必须显式相符。
+    return ((explicit_port == wanted) if explicit_port is not None
+            else wanted == "8765")
+
+
+def clear_stale_port(port, main_script):
+    """清掉占用端口的进程。返回 (是否清掉, 人话说明)。"""
+    holders = [p for p in portscan.listening_ports() if p.get("port") == int(port)]
+    if not holders:
+        return True, ""
+    pid = int(holders[0].get("pid") or 0)
+    if pid <= 4 or pid == os.getpid():
+        return False, "占用者是系统进程/自身，拒绝清理"
+    if is_own_instance(proc_cmdline(pid), main_script, port=port):
+        try:
+            runner._kill_tree(pid)
+            return True, "已结束旧实例 PID %d" % pid
+        except Exception as e:
+            return False, "旧实例 PID %d 清理失败 %s" % (pid, str(e)[:80])
+    return False, "占用者非 CodeBee（PID %d），未自动关闭" % pid

package/app/core/portscan.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""端口/进程扫描与项目归属推断（借鉴 leftopen 38★）。
+
+三个机制：
+- **端口→进程→项目归属推断**：netstat/ss 拿端口→PID，再从进程 CWD 向上走找
+  .git/package.json 等项目根——知道该进程属于哪个项目/用户
+- **本地 vs LAN 区分**：127.0.0.1 与 0.0.0.0/LAN 的安全边界
+- **温和关闭**：SIGTERM only（Windows taskkill /PID 不带 /F），关闭前重验 PID
+
+跨平台（Windows netstat + PowerShell / POSIX ss + /proc）纯标准库。
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import subprocess
+
+log = logging.getLogger(__name__)
+
+_PROJECT_MARKERS = (".git", "package.json", "pyproject.toml", "Cargo.toml",
+                    "go.mod", "pom.xml", "build.gradle", ".codebee")
+_SYSTEM_PROCS = {"system", "idle", "kernel", "svchost", "launchd", "init",
+                 "systemd", "sshd", "explorer", "finder", "windowserver"}
+
+
+def _project_from_cwd(cwd):
+    """从 CWD 向上走到项目根（含标志文件的最深目录名）。"""
+    if not cwd:
+        return ""
+    cur = os.path.abspath(cwd)
+    origin = cur
+    home = os.path.abspath(os.path.expanduser("~"))
+    while cur and cur != os.path.dirname(cur):
+        # 家目录及以上散落的标志文件（package.json 等）是环境噪音不是项目；
+        # 只有进程就跑在家目录本身时才认它为归属。
+        if cur == home and cur != origin:
+            return ""
+        for marker in _PROJECT_MARKERS:
+            if os.path.exists(os.path.join(cur, marker)):
+                return os.path.basename(cur)
+        cur = os.path.dirname(cur)
+    return ""
+
+
+def _proc_detail(pid):
+    """POSIX：读 /proc/<pid>/cwd 和 comm 获取进程详情。"""
+    detail = {"name": "", "project": ""}
+    try:
+        cwd = os.readlink("/proc/%d/cwd" % pid)
+        with open("/proc/%d/comm" % pid) as f:
+            detail["name"] = f.read().strip()
+        proj = _project_from_cwd(cwd)
+        if proj:
+            detail["project"] = proj
+    except (OSError, PermissionError):
+        pass
+    return detail
+
+
+def _parse_ss(output):
+    """解析 ss/netstat -tlnp 输出为端口条目列表。"""
+    ports, pid_map = [], {}
+    for ln in output.splitlines():
+        m = re.search(r":(\d{4,5})\s", ln)
+        if not m:
+            continue
+        port = int(m.group(1))
+        pm = re.search(r"pid=(\d+)", ln)
+        pid = int(pm.group(1)) if pm else 0
+        local_only = "127.0.0.1" in ln or "[::1]" in ln or "localhost" in ln
+        if pid and pid not in pid_map:
+            pid_map[pid] = _proc_detail(pid)
+        ports.append({"port": port, "pid": pid, "local_only": local_only,
+                      "process": pid_map.get(pid, {}).get("name", ""),
+                      "project": pid_map.get(pid, {}).get("project", "")})
+    dedup = {}
+    for p in ports:
+        key = p["port"]
+        if key not in dedup or (p["pid"] and not dedup[key]["pid"]):
+            dedup[key] = p
+    return sorted(dedup.values(), key=lambda x: x["port"])
+
+
+def _ports_linux():
+    """Linux/macOS：ss 优先，netstat 兜底。"""
+    try:
+        proc = subprocess.run(["ss", "-tlnp"], capture_output=True, timeout=15)
+        if proc.returncode == 0 and proc.stdout:
+            return _parse_ss(proc.stdout.decode("utf-8", "replace"))
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    try:
+        proc = subprocess.run(["netstat", "-tlnp"], capture_output=True, timeout=15)
+        if proc.returncode == 0 and proc.stdout:
+            return _parse_ss(proc.stdout.decode("utf-8", "replace"))
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    return []
+
+
+def _ports_windows(with_names=True):
+    """Windows：netstat -ano -p TCP 拿端口，PowerShell 一次性补进程名。"""
+    try:
+        proc = subprocess.run(
+            ["C:\\Windows\\System32\\netstat.exe", "-ano", "-p", "TCP"],
+            capture_output=True, timeout=15)
+    except (OSError, subprocess.TimeoutExpired):
+        return []
+    ports = []
+    for ln in proc.stdout.decode("utf-8", "replace").splitlines():
+        parts = ln.split()
+        if len(parts) < 5 or parts[0] != "TCP" or parts[3] != "LISTENING":
+            continue
+        local = parts[1]
+        pid_str = parts[4]
+        if not pid_str.isdigit():
+            continue
+        addr, _, port_str = local.rpartition(":")
+        if not port_str.isdigit():
+            continue
+        ports.append({"port": int(port_str), "pid": int(pid_str),
+                      "local_only": addr in ("127.0.0.1", "[::1]", "::1"),
+                      "process": "", "project": ""})
+    if with_names and ports:
+        try:
+            pn = subprocess.run(
+                ["C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
+                 "-NoProfile", "-Command",
+                 "Get-Process | Select-Object Id,ProcessName | ConvertTo-Json -Compress"],
+                capture_output=True, timeout=15)
+            procs = json.loads(pn.stdout.decode("utf-8", "replace"))
+            if isinstance(procs, dict):
+                procs = [procs]
+            name_map = {p.get("Id"): p.get("ProcessName", "") for p in procs}
+            for p in ports:
+                p["process"] = name_map.get(p["pid"], "")
+        except Exception:
+            pass
+    dedup = {}
+    for p in ports:
+        dedup.setdefault(p["port"], p)
+    return sorted(dedup.values(), key=lambda x: x["port"])
+
+
+def listening_ports(with_names=True):
+    """扫描本机所有 LISTEN 端口，返回 [{port, pid, process, project, local_only}]。
+
+    project 从进程 CWD 推断项目根目录名（POSIX /proc 可得，Windows 留空）。
+    with_names=False：跳过进程名/归属补全（Windows 下省掉 PowerShell 一次
+    起跳，重验场景用），process/project 恒为空串。
+    结果按端口号排序，重复端口去重（保留有 PID 信息的条目）。"""
+    if os.name == "nt":
+        return _ports_windows(with_names)
+    return _ports_linux()
+
+
+def close_port(port):
+    """温和关闭端口上的进程。返回 (ok, message)。关闭前重验 PID 绑定。"""
+    for p in listening_ports():
+        if p["port"] != port:
+            continue
+        pid = p.get("pid", 0)
+        if not pid or pid <= 4:
+            return False, "系统进程，不关闭"
+        if pid == os.getpid():
+            return False, "不能关闭自身服务进程"
+        if p.get("process", "").lower() in _SYSTEM_PROCS:
+            return False, "系统服务，不关闭"
+        # 重验 PID 仍在监听该端口（防 PID 复用竞态）；轻量扫描省掉 PowerShell
+        still = any(pp["port"] == port and pp["pid"] == pid
+                    for pp in listening_ports(with_names=False))
+        if not still:
+            return False, "PID %d 已不在端口 %d 上监听（竞态）" % (pid, port)
+        if os.name == "posix":
+            try:
+                os.kill(pid, 15)   # SIGTERM
+                return True, "已发送 SIGTERM（PID %d）" % pid
+            except OSError as e:
+                return False, str(e)[:160]
+        try:
+            subprocess.run(["taskkill", "/PID", str(pid)],
+                           timeout=10, capture_output=True)
+            return True, "已发送关闭信号（PID %d）" % pid
+        except Exception as e:
+            return False, str(e)[:160]
+    return False, "端口 %d 未找到监听进程" % port

package/app/core/redact.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+"""自由文本脱敏基础函数；不依赖业务模块，供各类本地台账复用。"""
+from __future__ import annotations
+
+import re
+
+
+_KEY_PATTERNS = (
+    (re.compile(r"\bsk-[A-Za-z0-9_-]{8,}"), "[key]"),
+    (re.compile(r"\b(?:Bearer|bearer)\s+\S+"), "Bearer [key]"),
+    (re.compile(r"(?i)\b((?:api[_-]?|access[_-]?|secret[_-]?|auth[_-]?)(?:key|token|secret))"
+                r"""["']?\s*[:=，,]\s*["']?[A-Za-z0-9._~+/=-]{8,}"""), r"\1[key]"),
+    (re.compile(r"\b[0-9a-fA-F]{40,}\b"), "[token]"),
+)
+
+_PATH_PATTERNS = (
+    (re.compile(r"(?i)\b[A-Z]:\\(?:[^\\/:*?\"<>|\r\n]+\\)*[^\\/:*?\"<>|\r\n]*"),
+     lambda m: "[path]" + m.group(0).split("\\")[-1]),
+    (re.compile(r"(?i)\b(?:\\\\[^\\\s]+\\[^\s]+)"), "[path]"),
+    (re.compile(r"(?:/Users/|/home/|~)[^\s\"':]+"),
+     lambda m: "[path]" + m.group(0).rsplit("/", 1)[-1]),
+)
+
+
+def scrub_text(text, limit=600):
+    """剥离常见密钥、令牌和绝对路径，再按字符上限截断。"""
+    if not isinstance(text, str):
+        text = "" if text is None else str(text)
+    out = text
+    for pattern, replacement in _KEY_PATTERNS:
+        out = pattern.sub(replacement, out)
+    for pattern, replacement in _PATH_PATTERNS:
+        try:
+            out = pattern.sub(replacement, out)
+        except Exception:
+            pass
+    out = out.strip()
+    return out[:limit] + "…" if len(out) > limit else out

package/app/core/router.py

@@ -37,7 +37,7 @@ def _binding_bonus(agent_id, dispatch_mode=False):
         return 0.0
 
 
-def _history_bonus(stats, agent_id, ttype):
+def _history_bonus(stats, agent_id, ttype):
     s = (stats.get(agent_id) or {}).get(ttype) or {}
     if not s.get("runs"):
         return 0.0
@@ -47,9 +47,34 @@ def _history_bonus(stats, agent_id, ttype):
     # 偶发失败把智能体埋了）。0/3 全败 = -18：常挂的 CLI 必须排到无历史的新
     # 面孔之后（2026-09-17 前败率不扣分，0/3 还拿 +6 经验分，比没跑过还高）。
     loss_penalty = 24.0 * (1.0 - win_rate) * min(1.0, runs / 3.0)
-    return round(18.0 * win_rate + min(6.0, runs) - loss_penalty, 1)
-
-
+    return round(18.0 * win_rate + min(6.0, runs) - loss_penalty, 1)
+
+
+def _online_bonus(agent, role, ttype):
+    """近期真实运行信号：成功率、P95 延迟和均价只作软加减分。"""
+    try:
+        from . import usage
+        metrics = usage.routing_stats(task_type=ttype, role=role,
+                                      agent=agent.get("id") or "")
+        samples = int(metrics.get("samples") or 0)
+        if not samples:
+            return 0.0, ""
+        rate = float(metrics.get("success_rate") or 0.0)
+        success_score = max(-8.0, min(8.0, (rate - 0.75) * 24.0))
+        p95 = max(0.0, float(metrics.get("p95_duration_s") or 0.0))
+        latency_score = -min(6.0, max(0.0, (p95 - 45.0) / 10.0))
+        cost = max(0.0, float(metrics.get("avg_cost_usd") or 0.0))
+        cost_score = -min(4.0, max(0.0, (cost - 0.01) / 0.01))
+        total = round(success_score + latency_score + cost_score, 1)
+        success_samples = int(metrics.get("success_samples") or samples)
+        reason = ("，在线 %d/%d 验收成功（%+.1f），P95 %.1fs（%+.1f），均价 $%.4f（%+.1f）"
+                  % (int(metrics.get("successes") or 0), success_samples,
+                     success_score, p95, latency_score, cost, cost_score))
+        return total, reason
+    except Exception:
+        return 0.0, ""
+
+
 def score(agent, role, ttype, stats=None):
     """返回 (总分, 理由字符串)。配额惩罚：catalog 里配了
     quota_tokens_per_hour 的智能体，本小时用量越接近配额分越低
@@ -65,12 +90,13 @@ def score(agent, role, ttype, stats=None):
         btxt = "，绑定链可用（+%s）" % bb
     elif bb < 0:
         btxt = "，绑定链为空：相关步骤将判失败（%s）" % bb
-    hb = _history_bonus(stats, agent.get("id"), ttype)
+    hb = _history_bonus(stats, agent.get("id"), ttype)
+    online, online_txt = _online_bonus(agent, role, ttype)
     # 保持公开 score() 的历史绝对分值；运行级候选由 pipeline 标记画像后
     # 才启用能力亲和度，避免旧插件/测试调用被新权重悄然改变。
     affinity, affinity_txt = (dispatch.agent_affinity(agent.get("kind"), ttype, role)
                               if use_dispatch else (0.0, "兼容模式"))
-    total = base + bb + hb + affinity
+    total = base + bb + hb + affinity + online
     hs = (stats.get(agent.get("id")) or {}).get(ttype)
     htxt = ("，历史 %d/%d 胜（%s）" % (hs["wins"], hs["runs"], "%+.1f" % hb)) if hs else "，无历史记录"
     quota_txt = ""
@@ -87,8 +113,8 @@ def score(agent, role, ttype, stats=None):
             if penalty:
                 total += penalty
                 quota_txt = "，本小时 %d/%d tokens（%s）" % (used, quota, penalty)
-    return total, "能力基线 %d，%s%s%s%s，总分 %s" % (
-        base, affinity_txt, btxt, htxt, quota_txt, round(total, 1))
+    return total, "能力基线 %d，%s%s%s%s%s，总分 %s" % (
+        base, affinity_txt, btxt, htxt, online_txt, quota_txt, round(total, 1))
 
 
 def pick(agents, role, ttype, stats=None, exclude=()):
@@ -106,12 +132,14 @@ def pick(agents, role, ttype, stats=None, exclude=()):
     return best[1], best_reason
 
 
-def route_plan(agents, role, task_spec, stats=None, exclude=()):
-    """生成可审计的候选排序，供运行详情展示和后续 fallback 使用。"""
+def route_plan(agents, role, task_spec, stats=None, exclude=(), selected=None,
+               participants=(), selection_reason=""):
+    """生成可审计的候选排序，并可用实际选路覆盖评分预选结果。"""
     if stats is None:
         stats = history.agent_stats()
-    real = [a for a in agents or [] if a.get("mode") == "real"]
-    pool = real if real else list(agents or [])
+    # 与 pick 保持同一候选池；绑定/健康扣分仍由 score 和 modelhub 负责，
+    # 诊断不能悄悄排除实际可能被选中的 mock 或备用 CLI。
+    pool = list(agents or [])
     rows = []
     for index, agent in enumerate(pool):
         if agent.get("id") in exclude:
@@ -127,9 +155,25 @@ def route_plan(agents, role, task_spec, stats=None, exclude=()):
                      "score": round(total, 1), "reason": reason,
                      "order": index})
     rows.sort(key=lambda x: (-x["score"], x["order"]))
-    return {"role": role, "selected": rows[0]["agent_id"] if rows else "",
+    selected_id = (selected or {}).get("id") if isinstance(selected, dict) else ""
+    if selected_id and not any(x["agent_id"] == selected_id for x in rows):
+        rows.append({"agent_id": selected_id,
+                     "label": selected.get("label") or selected_id,
+                     "kind": selected.get("kind") or "builtin",
+                     "score": 0.0, "reason": selection_reason or "实际选路",
+                     "order": len(rows)})
+    chosen = selected_id or (rows[0]["agent_id"] if rows else "")
+    participant_ids = []
+    for agent in participants or ():
+        agent_id = agent.get("id") if isinstance(agent, dict) else str(agent or "")
+        if agent_id and agent_id not in participant_ids:
+            participant_ids.append(agent_id)
+    active_ids = participant_ids or ([chosen] if chosen else [])
+    return {"role": role, "selected": chosen, "participants": participant_ids,
+            "selection_reason": selection_reason,
             "candidates": rows,
-            "fallback": [x["agent_id"] for x in rows[1:]]}
+            "fallback": [x["agent_id"] for x in rows
+                         if x["agent_id"] not in active_ids]}
 
 
 def pick_reviewer(agents, impl, ttype, stats=None):

package/app/core/runner.py

@@ -768,9 +768,10 @@ def _resolve_attempts(agent):
     """
     chain = agent.get("call_chain") or []
     if chain:
-        return [{"model": (e.get("model") or "").strip() or None,
-                 "env": dict(e.get("env") or {}),
-                 "from_chain": True,
+        return [{"model": (e.get("model") or "").strip() or None,
+                 "env": dict(e.get("env") or {}),
+                 "provider": e.get("provider") or {},
+                 "from_chain": True,
                  "own_cp": "codex_provider" in e,
                  "codex_provider": e.get("codex_provider"),
                  "provider_id": e.get("provider_id") or "",
@@ -778,8 +779,12 @@ def _resolve_attempts(agent):
     base_model = agent.get("model")
     fb = [m for m in (agent.get("model_fallbacks") or []) if m and m != base_model]
     models_to_try = ([base_model] if base_model else []) + fb
-    return [{"model": m or None, "env": {}, "from_chain": False, "own_cp": False,
-             "codex_provider": None, "provider_id": "", "key_id": ""}
+    provider = agent.get("provider") or {}
+    return [{"model": m or None, "env": {}, "provider": provider,
+             "from_chain": False, "own_cp": False,
+             "codex_provider": None,
+             "provider_id": provider.get("id") if isinstance(provider, dict) else "",
+             "key_id": ""}
             for m in (models_to_try or [None])[:3]]
 
 
@@ -1056,9 +1061,11 @@ def run_agent(agent, prompt, workdir=None, readonly=True,
                         os.remove(tf)
                     except OSError:
                         pass
-            out = {"ok": res["ok"], "text": "", "json": None, "cost_usd": 0.0,
-                   "tokens": 0, "usage": None, "error": "", "error_code": "",
-                   "sid": "", "raw": res, "kind": kind, "model": att["model"]}
+            out = {"ok": res["ok"], "text": "", "json": None, "cost_usd": 0.0,
+                   "tokens": 0, "usage": None, "error": "", "error_code": "",
+                   "sid": "", "raw": res, "kind": kind, "model": att["model"],
+                   "provider_id": att.get("provider_id") or "",
+                   "provider": att.get("provider") or {}}
             if not res["ok"]:
                 # stderr 与 stdout 都要进错误串：codex 把 "Reading prompt from
                 # stdin..." 打在 stderr，真正的配额/限流错误全在 stdout 的 JSONL

package/app/core/selfupdate.py

@@ -161,8 +161,21 @@ def check(force=False):
     return out
 
 
-def apply_upgrade():
-    """发起升级：建 mgmt run 异步跑 npm install -g @latest。返回 {run_id} 或 {error}。"""
+_PENDING_PORT = None   # apply_upgrade 记下的服务端口，升级成功后自动重启用
+
+
+def apply_upgrade(port=None):
+    """发起升级：建 mgmt run 异步跑 npm install -g @latest。返回 {run_id} 或 {error}。
+
+    port=服务端口：升级成功且版本真变时会自动就地重启（用户拍板 2026-09-21：
+    升级完不该再要求手动点「重启服务生效」——旧进程滞留是 unknown api/界面
+    闪烁/老宠物一类「升级了没生效」事故的总根子）。拿不到端口或运行环境不
+    具备时自动跳过，回落版本页的手动重启按钮。"""
+    global _PENDING_PORT
+    try:
+        _PENDING_PORT = int(port) if port else None
+    except (TypeError, ValueError):
+        _PENDING_PORT = None
     if install_mode() != "npm":
         return {"error": "当前安装方式不支持自动升级（见版本页说明）"}
     from . import store, jobs
@@ -176,15 +189,15 @@ def apply_upgrade():
     try:
         jobs.enqueue({"kind": "selfupgrade", "run_id": run["id"]})
     except Exception:
-        # run 已持久化；启动失败时显式收口，版本页不能停在误导性的待启动状态。
-        log.exception("selfupdate: 升级任务启动失败 run=%s", run["id"])
+        # run 已持久化；启动失败时显式收口，版本页不能停在误导性的待启动状态。
+        log.exception("selfupdate: 升级任务启动失败 run=%s", run["id"])
         try:
             store.update_run(run["id"], status="failed",
-                             error="升级任务启动失败，本次未排队，请稍后重试",
+                             error="升级任务启动失败，本次未排队，请稍后重试",
                              ended_at=time.strftime("%Y-%m-%d %H:%M:%S"))
         except Exception:
             log.exception("selfupdate: 升级运行失败收口失败 run=%s", run["id"])
-        return {"error": "升级任务启动失败，本次未排队，请稍后重试", "run_id": run["id"]}
+        return {"error": "升级任务启动失败，本次未排队，请稍后重试", "run_id": run["id"]}
     return {"run_id": run["id"]}
 
 
@@ -209,39 +222,85 @@ def _log_note(log_path, text):
         pass
 
 
-def run_upgrade(run_id, log_path, cancel_event=None):
+def _maybe_auto_relaunch(old_pkg, log_path):
+    """升级成功后的自动重启（三道守卫，任一不满足就回落手动按钮）：
+    ①知道服务端口（apply_upgrade 传入）；②版本真的变了（同版本重装不折腾）；
+    ③没有用户任务在跑（jobs._alive 只剩本升级任务自己）——正在干活的任务
+    不能被升级重启打断，此时留给用户挑自己合适的时间手动重启。"""
+    import threading
+    from . import jobs
+    if not _PENDING_PORT:
+        _log_note(log_path, "未记录服务端口，跳过自动重启——请在版本页手动重启生效")
+        return
+    new_pkg = package_version()
+    if not old_pkg or new_pkg == old_pkg:
+        _log_note(log_path, "版本未变化（%s），无需重启" % (new_pkg or "?"))
+        return
+    if getattr(jobs, "_alive", 0) > 1:
+        _log_note(log_path, "检测到还有 %d 个任务在运行，不自动重启——"
+                  "完成后请在版本页手动点「重启服务生效」" % (jobs._alive - 1))
+        return
+    port = _PENDING_PORT
+
+    def _go():
+        drain_started = False
+        try:
+            time.sleep(3.0)   # 留出日志收尾/浏览器看到「升级完成」的窗口
+            drain_started = jobs.begin_restart_drain()
+            if not drain_started:
+                _log_note(log_path, "延时窗口内有新任务进入，不自动重启——"
+                          "完成后请在版本页手动点「重启服务生效」")
+                return
+            _log_note(log_path, "自动重启服务以应用新版本 %s …" % new_pkg)
+            if relaunch(port):
+                self_quit()
+        except Exception:
+            log.exception("selfupdate: 自动重启失败，请在版本页手动重启")
+        finally:
+            # 正常 self_quit 会直接结束进程；若拉起失败、异常或测试替身返回，必须
+            # 释放停止接单闸，避免当前实例永久拒绝新任务。
+            if drain_started:
+                jobs.cancel_restart_drain()
+    threading.Thread(target=_go, name="selfupdate-relaunch",
+                     daemon=True).start()
+
+
+def run_upgrade(run_id, log_path, cancel_event=None):
     """worker 线程里执行升级命令（run/step 生命周期由 jobs 层管）。
 
     包目录被其他进程占用（EBUSY/EPERM：打开包目录的资源管理器/终端窗口、
     杀毒或索引扫描）是升级失败的最常见原因，且多为暂时性——自动重试
-    _RETRY_DELAYS 轮，仍败则给人话结论（原始 npm 输出在步骤日志里可查）。"""
-    res = {}
-    for attempt, delay in enumerate((0,) + _RETRY_DELAYS):
-        if cancel_event is not None and cancel_event.is_set():
-            return {"ok": False, "exit_code": None, "error": "用户主动取消",
-                    "cancelled": True}
-        if delay:
-            _log_note(log_path, "目录被占用（EBUSY/EPERM），%d 秒后自动重试（第 %d/%d 次）"
-                      % (delay, attempt, len(_RETRY_DELAYS)))
-            if cancel_event is not None and cancel_event.wait(delay):
-                return {"ok": False, "exit_code": None, "error": "用户主动取消",
-                        "cancelled": True}
-            if cancel_event is None:
-                time.sleep(delay)
-        res = runner.run_process(
+    _RETRY_DELAYS 轮，仍败则给人话结论（原始 npm 输出在步骤日志里可查）。
+    成功且版本真变时自动重启服务（_maybe_auto_relaunch，守卫见其 docstring）。"""
+    old_pkg = package_version()
+    res = {}
+    for attempt, delay in enumerate((0,) + _RETRY_DELAYS):
+        if cancel_event is not None and cancel_event.is_set():
+            return {"ok": False, "exit_code": None, "error": "用户主动取消",
+                    "cancelled": True}
+        if delay:
+            _log_note(log_path, "目录被占用（EBUSY/EPERM），%d 秒后自动重试（第 %d/%d 次）"
+                      % (delay, attempt, len(_RETRY_DELAYS)))
+            if cancel_event is not None and cancel_event.wait(delay):
+                return {"ok": False, "exit_code": None, "error": "用户主动取消",
+                        "cancelled": True}
+            if cancel_event is None:
+                time.sleep(delay)
+        res = runner.run_process(
             argv=_npm_argv("install", "-g", _PKG_NAME + "@latest"),
             # Windows 上 npm 换版本靠把包目录整体改名（codebee → .codebee-xxx）；
             # cwd 若落在本包内，目录被自身进程占用，rename 必报 EBUSY——钉在包外
-            cwd=str(Path.home()), timeout=900, log_path=log_path,
-            cancel_event=cancel_event)
-        if res.get("cancelled"):
-            return {"ok": False, "exit_code": res.get("exit_code"),
-                    "error": "用户主动取消", "cancelled": True}
+            cwd=str(Path.home()), timeout=900, log_path=log_path,
+            cancel_event=cancel_event)
+        if res.get("cancelled"):
+            return {"ok": False, "exit_code": res.get("exit_code"),
+                    "error": "用户主动取消", "cancelled": True}
         if res["ok"] or not _locked_error(res):
             break
     if res["ok"]:
         with _LOCK:  # 装完即过期查新缓存，重启后自然拿到新版本
             _CHECK_CACHE["result"] = None
+        _maybe_auto_relaunch(old_pkg, log_path)
         return {"ok": True, "exit_code": res["exit_code"], "error": ""}
     stderr = res["stderr"] or ""
     if _locked_error(res):