dsh-offhours 0.1.3 → 0.2.0

package/mechanism/scan.sh

@@ -62,6 +62,44 @@ ISOLATED=${NIGHTSHIFT_ISOLATED_WORKTREE:-0}
 ONLY_LIST=$(printf '%s' "${ONLY:-}" | tr ',' ' ')
 LOG=$RUNTIME_DIR/nightshift.log
 
+# ---------------------------------------------------------------------------
+# 执行器分派：superagent 模式不再起本地 headless worker。
+# 夜间跑批只把卡变成 Gitea issue（方案 A），superagent 的 Source/Eval/Ticket/Executor
+# 负责认领、独立 worktree、PR 与 attention；这里只做低谷闸门 + 派发 + 状态回写。
+EXECUTOR=${NIGHTSHIFT_EXECUTOR:-local}
+if [ "$EXECUTOR" = "superagent" ]; then
+  mkdir -p "$RUNTIME_DIR"
+  CFG=${NIGHTSHIFT_SUPERAGENT_CONFIG:-${OFFHOURS_CONFIG:-}}
+  BRIDGE="$SELF_DIR/superagent_bridge.py"
+  _sa_log() { printf '%s [%s] %s\n' "$(date '+%F %T')" "${NIGHTSHIFT_BOARD##*/}" "$*" >> "$LOG"; }
+  if [ -z "$CFG" ] || [ ! -f "$CFG" ]; then
+    echo "NIGHTSHIFT_SUPERAGENT_CONFIG 未设置或不存在：${CFG:-<empty>}" >&2
+    exit 2
+  fi
+  [ -f "$BRIDGE" ] || { echo "缺少 $BRIDGE" >&2; exit 2; }
+  if [ "$DRY" = 1 ]; then
+    python3 "$BRIDGE" dispatch "$BOARD" --config "$CFG" --dry-run
+    exit 0
+  fi
+  DISABLED="${DISABLED:-$RUNTIME_DIR/DISABLED}"
+  FORCE_ARG=""
+  [ "$FORCE" = 1 ] && FORCE_ARG="--force"
+  if [ "$DAEMON" = 1 ]; then
+    _sa_log "SUPERAGENT daemon 启动（派发 issue + 回写卡状态）"
+    while :; do
+      date +%s > "$RUNTIME_DIR/DAEMON.heartbeat" 2>/dev/null || true
+      [ -f "$DISABLED" ] && { _sa_log "SUPERAGENT 暂停（DISABLED）"; sleep 30; continue; }
+      python3 "$BRIDGE" dispatch "$BOARD" --config "$CFG" --limit 1 $FORCE_ARG >>"$LOG" 2>&1 || _sa_log "dispatch 失败"
+      python3 "$BRIDGE" sync "$BOARD" --config "$CFG" >>"$LOG" 2>&1 || _sa_log "sync 失败"
+      sleep 10
+    done
+  fi
+  date +%s > "$RUNTIME_DIR/DAEMON.heartbeat" 2>/dev/null || true
+  python3 "$BRIDGE" dispatch "$BOARD" --config "$CFG" --limit 1 $FORCE_ARG >>"$LOG" 2>&1 || _sa_log "dispatch 失败"
+  python3 "$BRIDGE" sync "$BOARD" --config "$CFG" >>"$LOG" 2>&1 || _sa_log "sync 失败"
+  exit 0
+fi
+
 # ---------------------------------------------------------------------------
 # worker 提示词的「稳定头」：**所有 worker 逐字节完全相同**，因此它是可被
 # DeepSeek 磁盘缓存识别并持久化的公共前缀单元（官方文档：命中要求完全匹配一个
@@ -184,13 +222,36 @@ rotate_log() {
 # 每轮跑完后立刻开始下一轮；没有可跑卡时等 10 秒再试，直到高峰/暂停。
 if [ "$DAEMON" = 1 ]; then
   log "DAEMON 启动（每轮最多 $MAX_CARDS_PER_RUN 张，轮间空档 ≤10s）"
+  # BOOT-RESET-ATTEMPTS：机器重启/实例故障后，把 attempts 清零——那是"环境中断"而不是"卡片失败"，
+  # 否则连断两次就把好卡推进 review（用户 2026-11-04 明确要求：故障后要能及时治愈回来）。
+  # 状态文件按 main 的「运行目录」口径（NIGHTSHIFT_STATE=$RUNTIME_DIR/state-<板>.json）扫描。
+  python3 - "$RUNTIME_DIR" <<'PYEOF' 2>/dev/null || true
+import json, os, sys, glob
+d = sys.argv[1]
+for f in glob.glob(os.path.join(d, "state.json")) + glob.glob(os.path.join(d, "state-*.json")):
+    try:
+        o = json.load(open(f, encoding="utf-8"))
+    except Exception:
+        continue
+    if isinstance(o, dict) and o.get("attempts"):
+        o["attempts"] = {}
+        json.dump(o, open(f, "w", encoding="utf-8"), ensure_ascii=False, indent=1)
+        print("reset attempts:", f)
+PYEOF
+  log "已清零 attempts（视为上次中断是环境故障）"
+  # HEARTBEAT-LOOP：独立的 10 秒心跳（轮次同步执行时也能证明"调度器活着"）
+  # 读写方约定：panel/index.js 的 NS_DIR 与 deploy/selfcheck.sh 都读部署目录下的 DAEMON.heartbeat，
+  # 所以写 $SELF_DIR（=扫描器所在目录）；不写 $RUNTIME_DIR，否则面板读不到。
+  ( while :; do date +%s > "$SELF_DIR/DAEMON.heartbeat" 2>/dev/null; sleep 10; done ) &
+  _HB_PID=$!
+  trap 'kill $_HB_PID 2>/dev/null' EXIT
   while :; do
     [ -f "$DISABLED" ] && { log "DAEMON 暂停（DISABLED）"; sleep 30; continue; }
     python3 "$SELF_DIR/ns.py" offpeak >/dev/null 2>&1 || { log "DAEMON 峰段休眠 60s"; sleep 60; continue; }
     # INVARIANT-HEAL：每轮后自愈（僵尸槽/错位槽/孤儿卡），把"状态一致性"变成常态而非人工
     python3 "$SELF_DIR/ns.py" invariants "$BOARD" --heal >/dev/null 2>&1 || true
     # HEARTBEAT：面板在沙箱里无法 systemctl，只能靠心跳文件判断调度器是否活着
-    date +%s > "$RUNTIME_DIR/DAEMON.heartbeat" 2>/dev/null || true
+    date +%s > "$SELF_DIR/DAEMON.heartbeat" 2>/dev/null || true
     MAX_CARDS_PER_RUN="${NIGHTSHIFT_DAEMON_MAX_PER_ROUND:-3}" "$0" --force >/dev/null 2>&1 || true
     sleep 10
   done
@@ -264,7 +325,8 @@ acquire_worker_slot() {
       rm -rf -- "$SLOTS/$i"                                          # 僵尸 ⇒ 回收
       log "回收僵尸槽位 $i（PID ${p:-未知} 已不在）"
     fi
-    mkdir -p "$SLOTS/$i" && echo $$ > "$SLOTS/$i/pid"
+    # SLOT-OWNER：槽位记录所属看板，避免对 A 板跑 invariants 时误伤 B 板的槽位
+    mkdir -p "$SLOTS/$i" && echo $$ > "$SLOTS/$i/pid" && printf '%s\n' "${BOARDKEY:-ops}" > "$SLOTS/$i/board" 2>/dev/null || true
     echo "$i"; return 0
   done
   return 1
@@ -513,6 +575,13 @@ PYST
 $PROMPT_HEAD
 
 === 本次任务（以下为逐卡变量；上面的硬规则对本次任务同样适用）===
+
+### DEVLOOP-CLOSE（2026-11-04）：与 dev-loop 闭环
+- 若工程存在 `scripts/devloop-round.sh`：**必须**按 dev-loop 一轮执行
+  `status` → `begin --round=<n>` → 干活 → `gate --all` → `finish`；
+- **判据以 gate 退出码/gate 报告为准**，不许用"看起来对"代替；
+- gate 红：只修本次改动引入的问题；与本次无关的历史红，写进卡证据并继续可做的部分；
+- 收尾把三行结论写进 `docs/devloop/ledger.md`（工程有该文件时）。
 卡片 id：$cid
 源自会话：${SOURCE_SESSION:-未记录}（DSH 无 fork CLI，血缘记在卡上）
 工作区：$WORKDIR （看板文件 $BOARD 由外层脚本维护：**你不要读改看板、也不要调用 board 相关工具——本 profile 没有它们**）
@@ -783,6 +852,9 @@ if [ "$PARALLEL" -gt 1 ] && [ "$DRY" != 1 ]; then
     # 波次循环：每波并发 PARALLEL 张，跑满 MAX_CARDS_PER_RUN 为止
     # 2026-11-01：槽位一空就补位（条件加 pids 非空）
     pids=""; wave_n=0        # 只在进入循环前初始化一次；循环内不得重置，否则会丢掉仍在跑的 pid
+    # 2026-11-10：同源会话串行保护。同一 sourceSessionId 的多张卡并行时 merge-back 会撞
+    # 同一个源 worktree（实测 .devloop/posture 冲突、结果行串味），本轮只放一个 worker。
+    ACTIVE_SESSIONS=""
     while [ "$launched" -lt "$MAX_CARDS_PER_RUN" ] || [ -n "$pids" ]; do
     wave=$((wave+1))
     while [ "$wave_n" -lt "$PARALLEL" ] && [ "$launched" -lt "$MAX_CARDS_PER_RUN" ]; do
@@ -791,7 +863,7 @@ if [ "$PARALLEL" -gt 1 ] && [ "$DRY" != 1 ]; then
         if r=$(budget_deny_reason); then log "预算拒绝：$r"; break; fi
         if r=$(cost_deny_reason); then log "花费拒绝：$r"; break; fi
       fi
-      PICK=$(python3 "$SELF_DIR/ns.py" pick "$BOARD")
+      PICK=$(NIGHTSHIFT_ACTIVE_SESSIONS="$ACTIVE_SESSIONS" python3 "$SELF_DIR/ns.py" pick "$BOARD")
       cid=$(printf '%s' "$PICK" | python3 -c "import sys,json;print((json.load(sys.stdin).get('picked') or {}).get('id',''))")
       [ -n "$cid" ] || break
       title=$(printf '%s' "$PICK" | python3 -c "import sys,json;print((json.load(sys.stdin).get('picked') or {}).get('title',''))")
@@ -828,7 +900,14 @@ if [ "$PARALLEL" -gt 1 ] && [ "$DRY" != 1 ]; then
       SRC_S=$(printf '%s\n' "$SRC" | sed -n 's/^SESSION=//p')
       SRC_F=$(printf '%s\n' "$SRC" | sed -n 's/^FEATURE=//p')
       SRC_P=$(printf '%s\n' "$SRC" | sed -n 's/^PROJECT=//p')
+      # source-of 在“自动建特性”的卡上只返回 E_DRY_RUN（父进程不建特性），不带 SESSION；
+      # 这时用 pick 自带的 sourceSessionId 作为串行键，否则同源会话保护会漏掉首轮。
+      if [ -z "$SRC_S" ]; then
+        SRC_S=$(printf '%s' "$PICK" | python3 -c "import sys,json;print((json.load(sys.stdin).get('picked') or {}).get('sourceSessionId') or '')" 2>/dev/null || true)
+      fi
       SRC_W=$(printf '%s\n' "$SRC" | sed -n 's/^WORKTREE=//p')
+      # 这张卡的源会话进入本轮 active 集：同会话下一张卡等到下一轮/下一波。
+      [ -n "$SRC_S" ] && ACTIVE_SESSIONS="$ACTIVE_SESSIONS $SRC_S"
       log "并行开跑（$((launched+1))/$PARALLEL）：$title（card=$cid）"
       (
         export NIGHTSHIFT_SOURCE_SESSION="$SRC_S" NIGHTSHIFT_SOURCE_FEATURE="$SRC_F" \

package/mechanism/selftest.py

@@ -38,12 +38,12 @@ def new_board(cards):
         json.dump({"version": 1, "cards": cards}, fh, ensure_ascii=False, indent=2)
 
 
-def card(cid, title="测试卡", tags=None, desc="说明", status="todo"):
+def card(cid, title="测试卡", tags=None, desc="说明", status="todo", sid="session-selftest"):
     # sourceSessionId 是 eligible() 的硬门槛（2026-11-01 起：没有来源会话 ⇒ 一定 E_NO_SOURCE，
     # 选卡阶段就排除）。夹具必须带上，否则 pick 恒为 None、整个用例集失去意义。
     return {"id": cid, "title": title, "status": status, "tags": tags or [],
             "description": desc, "createdAt": 1, "updatedAt": 1,
-            "sourceSessionId": "session-selftest"}
+            "sourceSessionId": sid}
 
 
 def read_card(cid):
@@ -70,6 +70,16 @@ check("todo 总数=5", pick["todoCount"] == 5, pick["todoCount"])
 check("hold 卡被计入 held", pick["heldCount"] == 1, pick["heldCount"])
 check("决策卡被剔除（拍板/阻塞）", len(pick["decisionCards"]) == 2, pick["decisionCards"])
 
+# 2026-11-10：同源会话串行保护。两张卡来自不同会话时，active 其一只能挑另一张。
+new_board([
+    card("p1", "会话1的卡", ["auto"], sid="session-p1"),
+    card("p2", "会话2的卡", ["auto"], sid="session-p2"),
+])
+p2 = json.loads(os.popen("NIGHTSHIFT_ACTIVE_SESSIONS=session-p1 python3 %s/ns.py pick %s" % (HERE, BOARD)).read())
+check("同源会话 active 时挑不同会话卡", (p2.get("picked") or {}).get("id") == "p2", p2)
+p3 = json.loads(os.popen("NIGHTSHIFT_ACTIVE_SESSIONS='session-p1 session-p2' python3 %s/ns.py pick %s" % (HERE, BOARD)).read())
+check("全部同源会话都在跑时返回空", p3.get("picked") is None and p3.get("blockedSessionCount") == 2, p3)
+
 print("\n== 2) done 必须有证据 ==")
 new_board([card("d1")])
 ns.cmd_apply([BOARD, "d1", result_file("KANBAN-RESULT: done\nKANBAN-SUMMARY: 做完了\n")])
@@ -249,3 +259,14 @@ check("claim 后看板形状合法", ns.board_shape_errors(json.load(open(BOARD,
 
 print("\n=== 结果：%s ===" % ("全部通过" if not fails else "失败 %d 项：%s" % (len(fails), fails)))
 sys.exit(1 if fails else 0)
+
+print("\n== R) 审批窗口：全部按推荐批准覆盖无审批单卡 ==")
+new_board([
+    card("ra", "无审批单的 review", status="review"),
+    card("rb", "有审批单的 review", status="review",
+         desc="【审批单 · explain-plain】\n- O1：按推荐做｜代价小\n- O2：不做\n"),
+])
+ns.cmd_confirm_recommended([BOARD])
+check("无审批单卡也回 todo", read_card("ra")["status"] == "todo", read_card("ra")["status"])
+check("有审批单卡按推荐回 todo", read_card("rb")["status"] == "todo", read_card("rb")["status"])
+check("确认块写回无审批单卡", "【确认 " in (read_card("ra").get("description") or ""))

package/mechanism/superagent_bridge.py

@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+"""dsh-offhours × dsh-superagent 的 Issue 桥接（方案 A）。
+
+夜间跑批只负责：低谷/预算闸门 + 把 KANBAN 卡变成 Gitea `agent:ready`/@agent issue。
+superagent 负责：Source → Eval → Ticket → 独立 Session/worktree → PR/评审/attention。
+本桥接不执行代码、不合并 PR、不修改 superagent 的 policy。
+
+用法：
+  superagent_bridge.py dispatch <BOARD> --config <config.json> [--limit N] [--dry-run]
+  superagent_bridge.py sync     <BOARD> --config <config.json>
+  superagent_bridge.py status   <BOARD> --config <config.json>
+
+卡片上写入的字段（ns.py/面板会忽略未知字段）：
+  superagentIssue: {number, url, at}
+  superagentPr:    {number, url, state}
+  superagentState: issue-open | pr-open | merged | reviewed | failed
+"""
+from __future__ import annotations
+
+import argparse
+import fcntl
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")
+
+
+def log(msg: str) -> None:
+    print(f"[superagent-bridge] {msg}", file=sys.stderr)
+
+
+def load_json(path: str):
+    with open(path, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def atomic_write(path: str, data) -> None:
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=p.name + ".", dir=str(p.parent))
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, ensure_ascii=False, indent=2)
+            fh.write("\n")
+        os.replace(tmp, path)
+    finally:
+        try:
+            os.unlink(tmp)
+        except FileNotFoundError:
+            pass
+
+
+def with_board_lock(board_path: str):
+    """Sidecar lock; ns.py/panel writes are short, this serialises bridge RMW only."""
+    class _Lock:
+        def __enter__(self):
+            self.fh = open(board_path + ".superagent.lock", "a+")
+            fcntl.flock(self.fh, fcntl.LOCK_EX)
+            return self
+        def __exit__(self, *exc):
+            fcntl.flock(self.fh, fcntl.LOCK_UN)
+            self.fh.close()
+    return _Lock()
+
+
+def board_config(config: dict, board_path: str) -> dict | None:
+    target = os.path.realpath(board_path)
+    for b in config.get("boards", []):
+        if os.path.realpath(str(b.get("file") or "")) == target:
+            return b
+    return None
+
+
+def superagent_config(config: dict, board: dict) -> dict:
+    sa = config.get("superagent") or {}
+    if board.get("executor", config.get("executor", "local")) != "superagent":
+        raise SystemExit("board.executor 不是 superagent")
+    missing = [k for k in ("cli", "tokenFile", "repo") if not sa.get(k)]
+    if missing:
+        raise SystemExit("superagent 配置缺少：" + ",".join(missing))
+    if not os.path.exists(sa["tokenFile"]):
+        raise SystemExit(f"superagent tokenFile 不存在：{sa['tokenFile']}")
+    if not os.access(sa["cli"], os.X_OK):
+        raise SystemExit(f"superagent cli 不可执行：{sa['cli']}")
+    return {
+        "cli": sa["cli"],
+        "tokenFile": sa["tokenFile"],
+        "repo": sa["repo"],
+        "mention": str(sa.get("mention") or "@dsh-agent"),
+        "issueLabel": str(sa.get("issueLabel") or "agent:ready"),
+        "baseUrl": str(sa.get("baseUrl") or "").rstrip("/"),
+        "orchestratorUrl": str(sa.get("orchestratorUrl") or "http://127.0.0.1:3082").rstrip("/"),
+        "stallMinutes": int(sa.get("stallMinutes") or 30),
+    }
+
+
+def api(sa: dict, method: str, path: str, fields: dict | None = None):
+    env = dict(os.environ)
+    env["GITEA_TOKEN_FILE"] = sa["tokenFile"]
+    args = [sa["cli"], "api", path]
+    if method != "GET":
+        args += ["--method", method]
+    for k, v in (fields or {}).items():
+        args += ["-f", f"{k}={v}"]
+    p = subprocess.run(args, capture_output=True, text=True, env=env, timeout=60)
+    if p.returncode != 0:
+        raise RuntimeError(f"gitea api {method} {path} 失败（rc={p.returncode}）：{(p.stderr or p.stdout)[:500]}")
+    try:
+        return json.loads(p.stdout or "null")
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"gitea api 返回非 JSON（{path}）：{p.stdout[:300]}") from exc
+
+
+def marker(board: dict, cid: str) -> str:
+    return f"<!-- offhours:card={cid} board={board.get('id','')} -->"
+
+
+def issue_body(board: dict, card: dict, sa: dict) -> str:
+    cid = str(card.get("id") or "")
+    summary = str(card.get("summary") or card.get("description") or "").strip()
+    desc = str(card.get("description") or "").strip()
+    title = str(card.get("title") or cid)
+    parts = [
+        f"来自夜间跑批看板 `{board.get('id','')}` 的卡：**{title}**",
+        "",
+        summary or "（无摘要；请按 issue 标题执行，并在完成前给出可复核证据。）",
+        "",
+        *(["", "卡片补充/人工确认：", desc] if desc and desc != summary else []),
+        f"{sa['mention']} 请按本 issue 执行；这是夜间跑批准入的任务，不是讨论请求。",
+        "",
+        "结束纪律：前台等命令结束（job_output wait=true），不要用“等后台 gate”结束回合；完成后必须给出 report，无法完成时报告 blocked/attention，不要静默结束。",
+        "",
+        marker(board, cid),
+    ]
+    return "\n".join(parts)
+
+
+def find_card(board_data: dict, cid: str):
+    return next((c for c in board_data.get("cards", []) if c.get("id") == cid), None)
+
+
+def eligible(card: dict) -> bool:
+    if card.get("status") != "todo":
+        return False
+    tags = [str(t).lower() for t in (card.get("tags") or [])]
+    if "hold" in tags or "blocked" in tags or "decision-needed" in tags:
+        return False
+    if "auto" not in tags and "superagent" not in tags:
+        return False
+    return True
+
+
+def cmd_dispatch(board_path: str, config_path: str, limit: int, dry: bool, force: bool = False) -> int:
+    config = load_json(config_path)
+    board = board_config(config, board_path)
+    if not board:
+        raise SystemExit(f"配置里找不到看板：{board_path}")
+    sa = superagent_config(config, board)
+    if not dry and not force:
+        # offpeak 是硬闸门；superagent 自己也会 peak-pause，但不在峰段创建新 issue。
+        p = subprocess.run([sys.executable, str(Path(__file__).with_name("ns.py")), "offpeak"],
+                           capture_output=True, text=True, timeout=10)
+        if p.returncode != 0:
+            log("当前不是低谷，跳过 dispatch")
+            return 0
+    with with_board_lock(board_path):
+        data = load_json(board_path)
+        candidates = [c for c in data.get("cards", []) if eligible(c) and not c.get("superagentIssue")]
+        if not candidates:
+            log("没有可 dispatch 的 todo(auto, 非 hold)")
+            return 0
+        if dry:
+            c = candidates[0]
+            print(json.dumps({
+                "wouldCreate": {
+                    "repository": sa["repo"],
+                    "title": f"[offhours] {c.get('title') or c.get('id')}",
+                    "body": issue_body(board, c, sa),
+                }
+            }, ensure_ascii=False, indent=2))
+            return 0
+        created = 0
+        for card in candidates[:max(1, limit)]:
+            cid = str(card.get("id") or "")
+            title = f"[offhours] {str(card.get('title') or cid)[:120]}"
+            issue = api(sa, "POST", f"repos/{sa['repo']}/issues", {
+                "title": title,
+                "body": issue_body(board, card, sa),
+            })
+            number = issue.get("number")
+            url = issue.get("html_url") or (f"{sa['baseUrl']}/lengr/hemou/issues/{number}" if sa["baseUrl"] else "")
+            card["status"] = "in_progress"
+            card["superagentIssue"] = {"number": number, "url": url, "at": now_iso()}
+            card["superagentState"] = "issue-open"
+            card["updatedAt"] = now_iso()
+            created += 1
+            log(f"created issue #{number} for card {cid}")
+        atomic_write(board_path, data)
+    print(json.dumps({"created": created}, ensure_ascii=False))
+    return 0
+
+
+PR_RE = re.compile(r"https?://[^\s)>\]]+/pulls/(\d+)")
+
+def local_api(sa: dict, path: str):
+    """superagent 管理 API（仅本机回环，无需额外鉴权头之外的秘密）。"""
+    url = sa.get("orchestratorUrl") or "http://127.0.0.1:3082"
+    req = Request(url + path, headers={"x-orchestrator-request": "1"})
+    with urlopen(req, timeout=8) as r:
+        return json.loads(r.read().decode("utf-8"))
+
+
+def local_post(sa: dict, path: str, payload: dict):
+    url = (sa.get("orchestratorUrl") or "http://127.0.0.1:3082") + path
+    req = Request(url, data=json.dumps(payload).encode("utf-8"),
+                  headers={"x-orchestrator-request": "1", "content-type": "application/json"}, method="POST")
+    with urlopen(req, timeout=8) as r:
+        return json.loads(r.read().decode("utf-8"))
+
+
+def cancel_ticket(sa: dict, ticket: dict | None) -> None:
+    if not ticket or ticket.get("state") != "open":
+        return
+    try:
+        local_post(sa, f"/orchestrator/api/tickets/{ticket['id']}/stop",
+                   {"reason": "human confirmed the offhours card; take over"})
+    except Exception:
+        pass
+
+
+def close_issue(sa: dict, number: int) -> None:
+    try:
+        api(sa, "PATCH", f"repos/{sa['repo']}/issues/{number}", {"state": "closed"})
+    except Exception:
+        pass
+
+
+def find_ticket(sa: dict, issue_number: int, card_title: str):
+    """找到这张 issue 对应的 superagent ticket；找不到返回 None。
+
+    用 Thread key `github:<issue>` 做身份，而不是标题猜测；标题只用于先筛列表。
+    """
+    try:
+        data = local_api(sa, "/orchestrator/api/tickets?state=all&limit=100")
+    except Exception:
+        return None
+    items = data.get("items", []) or []
+    want = card_title.strip()
+    def matches(item):
+        try:
+            full = local_api(sa, f"/orchestrator/api/tickets/{item['id']}")
+        except Exception:
+            return None
+        for th in full.get("threads", []) or []:
+            if th.get("key") == f"github:{issue_number}":
+                return full
+        return None
+
+    # 先按标题缩小范围（大多数卡标题与 issue 标题一致）；
+    for item in items:
+        title = str(item.get("title") or "").strip()
+        if want and want not in title and f"[offhours] {want}" not in title:
+            continue
+        got = matches(item)
+        if got:
+            return got
+    # 标题被人工改过/工单标题被 superagent 重写时，按 Thread key 全量兜底。
+    for item in items:
+        title = str(item.get("title") or "").strip()
+        if want and (want in title or f"[offhours] {want}" in title):
+            continue
+        got = matches(item)
+        if got:
+            return got
+    return None
+
+
+def ticket_status(ticket: dict | None):
+    if not ticket:
+        return None
+    if ticket.get("attention"):
+        return "review", "attention"
+    ended = ticket.get("ended") or {}
+    if ticket.get("state") == "ended":
+        outcome = str(ended.get("outcome") or "")
+        return ("done" if outcome in ("merged", "completed") else "review", "ticket-ended")
+    if ticket.get("stage") == "working":
+        return "in_progress", "working"
+    return "review", "person"
+
+
+def _pr_from_comments(comments) -> int | None:
+    for c in comments or []:
+        m = PR_RE.search(str(c.get("body") or ""))
+        if m:
+            return int(m.group(1))
+    return None
+
+
+def cmd_sync(board_path: str, config_path: str) -> int:
+    config = load_json(config_path)
+    board = board_config(config, board_path)
+    if not board:
+        raise SystemExit(f"配置里找不到看板：{board_path}")
+    sa = superagent_config(config, board)
+    with with_board_lock(board_path):
+        data = load_json(board_path)
+        changed = 0
+        for card in data.get("cards", []):
+            issue = card.get("superagentIssue")
+            if not issue or not issue.get("number"):
+                continue
+            n = int(issue["number"])
+            # 人工确认后 ns.py 把卡改回 todo 并写【确认】块；此时旧 ticket/issue 不能再把卡拉回 review。
+            # 先停止旧 ticket、关闭旧 issue、清掉 superagent 关联，让下一轮 dispatch 按新确认重新派发。
+            if card.get("status") == "todo" and "【确认 " in str(card.get("description") or ""):
+                t = find_ticket(sa, n, str(card.get("title") or ""))
+                cancel_ticket(sa, t)
+                close_issue(sa, n)
+                for k in ("superagentIssue", "superagentPr", "superagentTicket"):
+                    card.pop(k, None)
+                card["superagentState"] = "human-confirmed"
+                card["updatedAt"] = now_iso()
+                changed += 1
+                continue
+            issue_obj = api(sa, "GET", f"repos/{sa['repo']}/issues/{n}")
+            state = str(issue_obj.get("state") or "open")
+            comments = api(sa, "GET", f"repos/{sa['repo']}/issues/{n}/comments")
+            pr_num = _pr_from_comments(comments)
+            pr = api(sa, "GET", f"repos/{sa['repo']}/pulls/{pr_num}") if pr_num else None
+            old = (card.get("status"), card.get("superagentState"), (card.get("superagentPr") or {}).get("state"))
+            if pr:
+                pr_state = "merged" if pr.get("merged") or pr.get("merged_at") else ("closed" if str(pr.get("state")) == "closed" else "open")
+                card["superagentPr"] = {"number": pr_num, "url": pr.get("html_url") or "", "state": pr_state}
+                if pr_state == "merged" or (state == "closed" and pr_state != "open"):
+                    card["status"] = "done"
+                    card["superagentState"] = "merged"
+                elif pr_state == "closed":
+                    card["status"] = "review"
+                    card["superagentState"] = "reviewed"
+                else:
+                    card["status"] = "review"
+                    card["superagentState"] = "pr-open"
+            elif state == "closed":
+                card["status"] = "review"
+                card["superagentState"] = "reviewed"
+            else:
+                card["status"] = "in_progress"
+                card["superagentState"] = "issue-open"
+            ticket = find_ticket(sa, n, str(card.get("title") or ""))
+            if ticket:
+                card["superagentTicket"] = {"id": ticket.get("id"), "title": ticket.get("title")}
+                ts = ticket_status(ticket)
+                if ts:
+                    tstatus, tstate = ts
+                    # PR merged / ticket merged 都算 done；attention/working 以 ticket 实时状态为准。
+                    if card.get("superagentState") == "merged" or tstatus == "done":
+                        card["status"] = "done"; card["superagentState"] = "merged"
+                    elif tstatus == "review":
+                        card["status"] = "review"; card["superagentState"] = tstate
+                    elif card.get("status") != "review":
+                        card["status"] = "in_progress"; card["superagentState"] = tstate
+                # 防静默卡死：worker 可能结束回合却不再 report（等后台 gate 的已知失败模式）。
+                # 超过 stallMinutes 仍是 working 且无 report/attention ⇒ 卡转 review，让人看见。
+                if tstate == "working" and card.get("status") == "in_progress":
+                    at = str((card.get("superagentIssue") or {}).get("at") or "")
+                    try:
+                        started = datetime.fromisoformat(at).timestamp()
+                    except Exception:
+                        started = 0
+                    if started and time.time() - started > max(1, sa["stallMinutes"]) * 60:
+                        card["status"] = "review"; card["superagentState"] = "stalled"
+            if (card.get("status"), card.get("superagentState"), (card.get("superagentPr") or {}).get("state")) != old:
+                card["updatedAt"] = now_iso()
+                changed += 1
+        atomic_write(board_path, data)
+    print(json.dumps({"changed": changed}, ensure_ascii=False))
+    return 0
+
+
+def cmd_status(board_path: str, config_path: str) -> int:
+    config = load_json(config_path)
+    board = board_config(config, board_path)
+    if not board:
+        raise SystemExit(f"配置里找不到看板：{board_path}")
+    sa = superagent_config(config, board)
+    data = load_json(board_path)
+    rows = [{"id": c.get("id"), "title": c.get("title"), "status": c.get("status"),
+             "issue": c.get("superagentIssue"), "pr": c.get("superagentPr"),
+             "state": c.get("superagentState")}
+            for c in data.get("cards", []) if c.get("superagentIssue")]
+    print(json.dumps({"executor": "superagent", "repo": sa["repo"], "cards": rows}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def main(argv) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("command", choices=["dispatch", "sync", "status"])
+    ap.add_argument("board")
+    ap.add_argument("--config", default=os.environ.get("OFFHOURS_CONFIG") or os.environ.get("NIGHTSHIFT_SUPERAGENT_CONFIG"))
+    ap.add_argument("--limit", type=int, default=1)
+    ap.add_argument("--dry-run", action="store_true")
+    ap.add_argument("--force", action="store_true")
+    ns = ap.parse_args(argv)
+    if not ns.config:
+        raise SystemExit("需要 --config 或 OFFHOURS_CONFIG")
+    if ns.command == "dispatch":
+        return cmd_dispatch(ns.board, ns.config, ns.limit, ns.dry_run, ns.force)
+    if ns.command == "sync":
+        return cmd_sync(ns.board, ns.config)
+    return cmd_status(ns.board, ns.config)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-offhours",
-  "version": "0.1.3",
-  "description": "DSH 社区插件：把看板待办在低谷/夜间自动做掉（挑卡 → 独占 worktree → worker → 证据 → 合并回收），只依赖配置里的 git 仓库。",
+  "version": "0.2.0",
+  "description": "DSH 社区插件：把看板待办在低谷/夜间自动做掉；可选把卡交给 dsh-superagent 执行",
   "type": "module",
   "license": "MIT",
   "main": "panel/index.js",
@@ -26,6 +26,7 @@
     "mechanism/scan.sh",
     "mechanism/ns.py",
     "mechanism/selftest.py",
+    "mechanism/superagent_bridge.py",
     "feature-worktrees/feature",
     "feature-worktrees/feature-lib.sh",
     "feature-worktrees/feature-guard.sh",
@@ -38,7 +39,7 @@
   "scripts": {
     "prepack": "node scripts/gen-client.mjs",
     "gen:client": "node scripts/gen-client.mjs",
-    "test": "node --test tests/*.test.mjs",
+    "test": "node --test tests/node/*.test.mjs",
     "check": "node --check panel/index.js && node --check lib/config.js && node --check lib/runtime.js && node --check bin/offhours.mjs"
   },
   "engines": {
@@ -76,4 +77,4 @@
   "bugs": {
     "url": "https://github.com/shuke52tt/dsh-offhours/issues"
   }
-}
+}