nx-kv 0.20.0 → 0.22.0

package/src/modules/localtask/events.js

@@ -0,0 +1,207 @@
+// （#54 自 service.js 拆出）等待生命周期事件流：轮询 store，从 waiting/waitingUntil 与
+// 已领取数的变化里派生 waiting/reminder/resolved 事件；SSE（streamEventsSSE）与
+// CLI（NDJSON）共用 watchEvents 生成器。
+import { isGlobalKey, normalizeCwd } from './paths.js';
+import { loadStore } from './store-io.js';
+import { deadlineMsOf } from './task-view.js';
+import { addEventStreamConn } from './panel-presence.js';
+// ─── 等待生命周期事件流（主面板及时通知，避免用户漏过超时）────────────
+//
+// wait 与常驻主面板通常是两个进程，内存 EventEmitter 跨不过进程，所以事件流
+// 不依赖进程内回调，而是轮询 store，从 waiting/waitingUntil 与「已领取数」的变化里
+// 派生事件：waiting / reminder（剩余 30s、10s）/ resolved（delivered 或 timeout）。
+// HTTP(SSE) 与 CLI(NDJSON) 共用本生成器。
+
+const EVENT_POLL_MS = 500;
+const REMINDER_SEC = [30, 10]; // 剩余 ≤30s、≤10s 各提醒一次
+
+// 纯函数：给定剩余秒数与已提醒过的阈值，返回本次应触发的阈值（秒）。便于单测。
+export function remindersDue(remainSec, firedSet) {
+  const out = [];
+  for (const sec of REMINDER_SEC) {
+    if (remainSec <= sec && remainSec > 0 && !firedSet.has(sec)) out.push(sec);
+  }
+  return out;
+}
+
+function consumedCount(t) {
+  return (Array.isArray(t.tasks) ? t.tasks : []).filter((x) => x.status === 'consumed').length;
+}
+
+/**
+ * 订阅等待生命周期事件（异步生成器）。
+ * @param {{cwd?:string,key?:string,pollMs?:number,signal?:AbortSignal}} opts
+ *   不传 cwd/key 则订阅全部主题（主面板总览需要）。
+ */
+export async function* watchEvents({ cwd: rawCwd, key: rawKey, pollMs = EVENT_POLL_MS, signal } = {}) {
+  let onlyKey = null;
+  if (rawKey && String(rawKey).trim()) onlyKey = String(rawKey).trim();
+  else if (rawCwd && String(rawCwd).trim()) onlyKey = normalizeCwd(rawCwd).key;
+
+  const sleep = (ms) =>
+    new Promise((res) => {
+      const to = setTimeout(res, ms);
+      if (signal) {
+        signal.addEventListener(
+          'abort',
+          () => {
+            clearTimeout(to);
+            res();
+          },
+          { once: true }
+        );
+      }
+    });
+
+  const state = new Map();
+  let first = true;
+  while (!(signal && signal.aborted)) {
+    let topics = [];
+    try {
+      const store = await loadStore();
+      topics = Object.values(store.topics).filter(
+        (t) => Array.isArray(t.tasks) && (!onlyKey || t.key === onlyKey)
+      );
+    } catch {
+      topics = [];
+    }
+
+    const now = Date.now();
+    for (const t of topics) {
+      // 截止时刻走 deadlineMsOf()：优先毫秒精度的 waitingUntilMs，老数据才解析字符串。
+      // 之前这里自己解析 waitingUntil（秒级），短时限下截断误差会让「正在等」被判成
+      // 「没在等」→ 事件流永远推不出 waiting（tests/unit/localtask-sse.test.mjs 曾
+      // 因此有 ~4% 的 flake）。
+      const deadline = deadlineMsOf(t);
+      const isWaiting = !!t.waiting && Number.isFinite(deadline) && deadline > now;
+      let st = state.get(t.key);
+
+      if (isWaiting) {
+        // 「是不是新一轮等待」用**毫秒精度的 deadline** 判定：waitingUntil 字符串只有
+        // 秒级，同一秒内开始的两次等待字符串相同，靠它判会漏掉新一轮。
+        if (!st || st.phase !== 'waiting' || st.deadline !== deadline) {
+          st = {
+            phase: 'waiting',
+            waitingUntil: t.waitingUntil,
+            deadline,
+            consumed0: consumedCount(t),
+            reminders: new Set(),
+          };
+          state.set(t.key, st);
+          yield {
+            type: 'waiting',
+            key: t.key,
+            cwd: t.cwd || '',
+            name: t.name || '',
+            summary: t.summary || '',
+            isGlobal: isGlobalKey(t.key),
+            waitingUntil: t.waitingUntil,
+            remainMs: Math.max(0, deadline - now),
+            replay: first,
+          };
+        }
+        const remainSec = Math.floor((st.deadline - now) / 1000);
+        for (const sec of remindersDue(remainSec, st.reminders)) {
+          st.reminders.add(sec);
+          yield {
+            type: 'reminder',
+            key: t.key,
+            cwd: t.cwd || '',
+            name: t.name || '',
+            summary: t.summary || '',
+            isGlobal: isGlobalKey(t.key),
+            waitingUntil: t.waitingUntil,
+            remainSec: sec,
+            remainMs: Math.max(0, st.deadline - now),
+            label: `${sec}s`,
+          };
+        }
+      } else if (st && st.phase === 'waiting') {
+        const outcome = consumedCount(t) > st.consumed0 ? 'delivered' : 'timeout';
+        state.set(t.key, { phase: 'ended' });
+        yield { type: 'resolved', key: t.key, cwd: t.cwd || '', name: t.name || '', isGlobal: isGlobalKey(t.key), outcome };
+      } else if (!st) {
+        state.set(t.key, { phase: 'idle' });
+      }
+
+      // 兜底：waiting 标志还在但截止已过（wait 进程异常退出），也派生一次 timeout
+      if (t.waiting && (!Number.isFinite(deadline) || deadline <= now)) {
+        const cur = state.get(t.key);
+        if (!cur || cur.phase === 'waiting') {
+          state.set(t.key, { phase: 'ended' });
+          yield {
+            type: 'resolved',
+            key: t.key,
+            cwd: t.cwd || '',
+            name: t.name || '',
+            isGlobal: isGlobalKey(t.key),
+            outcome: 'timeout',
+            stale: true,
+          };
+        }
+      }
+    }
+
+    first = false;
+    await sleep(pollMs);
+  }
+}
+
+// HTTP 传输：SSE。注册到 sseConns 让 panelPresence 计入（wait 据此判活标签）。
+// 客户端断开即中止生成器。SSE 心跳由 addEventStreamConn 统一管。
+export async function streamEventsSSE(req, res, { cwd, key } = {}) {
+  res.writeHead(200, {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-store',
+    connection: 'keep-alive',
+    // 断线重连提示（浏览器 EventSource 默认 3s 重连，这里写明确一点）。
+    // 对齐 opencode 的 SSE 加固做法（event.ts:21-28）。
+    'x-accel-buffering': 'no',
+  });
+  res.write('retry: 3000\n\n');
+  res.write(': connected\n\n');
+  // addEventStreamConn 内部已把 conn 加入 sseConns（panelPresence 据此统计活标签），
+  // 我们不再直接引用——心跳 / 失败剔除 / 断开清理都由它托管。
+  addEventStreamConn(req, res);
+  const ac = new AbortController();
+  req.on('close', () => ac.abort());
+  let seq = 0;
+  try {
+    for await (const ev of watchEvents({ cwd, key, signal: ac.signal })) {
+      // 单调 id：浏览器重连后可带着 Last-Event-ID 回来（这里只保证不重复，
+      // 事件本身是从 store 派生的，重放也不会串）。
+      seq += 1;
+      res.write(`id: ${seq}\nevent: ${ev.type}\ndata: ${JSON.stringify(ev)}\n\n`);
+    }
+  } catch {
+    /* 客户端断开 / 瞬时读盘错误，静默结束 */
+  }
+}
+
+// CLI 传输：**逐行 NDJSON**（一行一个事件），与 HTTP 的 SSE 同源（都用 watchEvents）。
+//
+// 以前 CLI 跑 `localtask events` 必崩：那条 action 原本只做 SSE，
+// 直接摸 `ctx.__raw.req` —— 而 `__raw` 只在 HTTP 传输下才注入，CLI 进程里是 undefined。
+// 现在按传输方式分流，CLI 这条命令真能用（CHANGELOG 当初承诺的「CLI 等价逐行 NDJSON」）。
+//
+// 它是**长连**：命令会一直打印到用户 Ctrl+C（stdout 被关闭即结束）。
+export async function streamEventsNDJSON({ cwd, key, signal, timeoutSec, limit } = {}) {
+  const ac = new AbortController();
+  // agent 需要能**给这条长连划个边界**：gh run watch 有 --exit-status / --interval，
+  // 这里给 --timeout（最长监听多少秒）与 --limit（最多几条事件）。都不给就是无限流。
+  const timer =
+    Number.isFinite(timeoutSec) && timeoutSec > 0 ? setTimeout(() => ac.abort(), timeoutSec * 1000) : null;
+  let n = 0;
+  try {
+    for await (const ev of watchEvents({ cwd, key, signal: signal || ac.signal })) {
+      process.stdout.write(`${JSON.stringify(ev)}\n`);
+      n += 1;
+      if (Number.isFinite(limit) && limit > 0 && n >= limit) break;
+    }
+  } catch {
+    /* Ctrl+C / 管道断开：静默收尾 */
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+

package/src/modules/localtask/move-prims.js

@@ -0,0 +1,98 @@
+// （#54 自 service.js 拆出）迁移原语（task move / 云端迁移编排用）：只读定位、
+// 迁出 tombstone（目标端写成功后才调用）、撤销迁出、云端回插待领取首位。
+import { badInput } from '../../core/errors.js';
+import { normalizeCwd, resolveTaskKey } from './paths.js';
+import { loadStore, saveStore, stampNow, normalizeText, topicOf, nextTaskId, bumpWorkflowRevision } from './store-io.js';
+import { normalizeTask, isPending } from './task-view.js';
+// ─── 迁移原语（task move 用；store 封装不外泄）─────────────────────
+//
+// 迁移的原子性在外层 move.js 编排（先写目标端、成功才改源端），
+// 这里只提供对 store 的最小读写原语，保证清单/历史/原子写都走同一条管线。
+
+/** 只读定位一条本机任务（不落写）。返回 {task, name, key, cwd} 或抛 notFound。 */
+export async function getTopicTask({ cwd: rawCwd, key: rawKey, id } = {}) {
+  const key = resolveTaskKey({ key: rawKey, cwd: rawCwd });
+  const want = Number(id);
+  if (!Number.isFinite(want) || want <= 0) throw badInput('缺少参数 --id <任务编号>');
+  const store = await loadStore();
+  const t = store.topics[key];
+  const raw = t && t.tasks.find((x) => Number(x.id) === want);
+  if (!raw) {
+    const { notFound } = await import('../../core/errors.js');
+    throw notFound(`主题「${t ? t.name : key}」里没有 #${want} 任务`);
+  }
+  return { task: normalizeTask(raw), key, cwd: t.cwd || '', name: t.name || key };
+}
+
+/** 给本机任务打迁出标记（tombstone）。只在目标端已写成功后调用。 */
+export async function markTaskMigrated({ cwd: rawCwd, key: rawKey, id, migratedTo } = {}) {
+  const key = resolveTaskKey({ key: rawKey, cwd: rawCwd });
+  const want = Number(id);
+  if (!Number.isFinite(want) || want <= 0) throw badInput('缺少参数 --id <任务编号>');
+  if (!migratedTo || migratedTo.side !== 'cloud') throw badInput('migratedTo 必须是 {side:"cloud", topic, targetId, at}');
+  const store = await loadStore();
+  const t = store.topics[key];
+  const raw = t && t.tasks.find((x) => Number(x.id) === want);
+  if (!raw) {
+    const { notFound } = await import('../../core/errors.js');
+    throw notFound(`主题「${t ? t.name : key}」里没有 #${want} 任务`);
+  }
+  if (raw.status === 'consumed') {
+    const { conflict } = await import('../../core/errors.js');
+    throw conflict(`主题「${t.name}」#${want} 已被领取，不能再迁移`);
+  }
+  raw.migratedTo = { side: 'cloud', topic: String(migratedTo.topic || ''), targetId: Number(migratedTo.targetId) || 0, at: String(migratedTo.at || stampNow()) };
+  t.updatedAt = stampNow();
+  bumpWorkflowRevision(t);
+  await saveStore(store);
+  return { status: 'ok', key, cwd: t.cwd || '', name: t.name, task: normalizeTask(raw) };
+}
+
+/** 撤销迁出：清掉 migratedTo 标记，任务回到待领取首位。 */
+export async function clearTaskMigrated({ cwd: rawCwd, key: rawKey, id, toTop = true } = {}) {
+  const key = resolveTaskKey({ key: rawKey, cwd: rawCwd });
+  const want = Number(id);
+  if (!Number.isFinite(want) || want <= 0) throw badInput('缺少参数 --id <任务编号>');
+  const store = await loadStore();
+  const t = store.topics[key];
+  const raw = t && t.tasks.find((x) => Number(x.id) === want);
+  if (!raw) {
+    const { notFound } = await import('../../core/errors.js');
+    throw notFound(`主题「${t ? t.name : key}」里没有 #${want} 任务`);
+  }
+  if (!raw.migratedTo) {
+    return { status: 'ok', restored: false, reason: 'not_migrated', key, name: t.name, task: normalizeTask(raw) };
+  }
+  delete raw.migratedTo;
+  // 回到待领取首位：迁出时它占着优先级位置，撤销应原样归还
+  if (toTop) {
+    const idx = t.tasks.indexOf(raw);
+    if (idx >= 0) t.tasks.splice(idx, 1);
+    t.tasks.unshift(raw);
+  }
+  t.updatedAt = stampNow();
+  bumpWorkflowRevision(t);
+  await saveStore(store);
+  return { status: 'ok', restored: true, key, cwd: t.cwd || '', name: t.name, task: normalizeTask(raw) };
+}
+
+/**
+ * 云端 → 本机：把一条任务插到本机主题队列的**待领取首位**（不打扰 waiter——
+ * 迁移是「排进队列」，不是「回填给正在等的 agent」，语义必须分开）。
+ * 返回 {task, name, key, cwd}。
+ */
+export async function insertTaskAtTop({ cwd: rawCwd, key: rawKey, text, from = 'cloud' } = {}) {
+  const body = normalizeText(text);
+  const key = resolveTaskKey({ key: rawKey, cwd: rawCwd });
+  const { cwd } = normalizeCwd(rawCwd);
+  const store = await loadStore();
+  const t = topicOf(store, key, cwd);
+  const task = normalizeTask({ id: nextTaskId(t.tasks), text: body, status: 'pending', createdAt: stampNow(), from });
+  const firstPending = t.tasks.findIndex(isPending);
+  if (firstPending >= 0) t.tasks.splice(firstPending, 0, task);
+  else t.tasks.unshift(task);
+  t.updatedAt = stampNow();
+  bumpWorkflowRevision(t);
+  await saveStore(store);
+  return { status: 'ok', key, cwd: t.cwd || cwd, name: t.name, task };
+}

package/src/modules/localtask/mutator/validate.js

@@ -1,4 +1,6 @@
 import { assertPluginSpec } from '../../../core/workflow/plugin-registry.js';
+import { isGateNode } from '../../../core/workflow/types.js';
+import { wouldCycleAfterLink } from '../../../shared/graph.js';
 
 /** @typedef {import('../../../core/workflow/types.js').WorkflowSnapshot} WorkflowSnapshot */
 /** @typedef {import('../../../core/workflow/types.js').WfNode} WfNode */
@@ -32,7 +34,7 @@ export function assertBind(node, spec, target) {
     return normalized;
   }
   if (!node) throw new Error('node required for node-level bind');
-  if (node.kind === 'control' && normalized.scope !== 'control') {
+  if (isGateNode(node) && normalized.scope !== 'control') {
     throw new Error('control node may only bind control-scope plugins');
   }
   // task + control 插件：允许，由 mutator 升级 kind→control（现网闸门常从普通任务打 --gate）
@@ -40,23 +42,12 @@ export function assertBind(node, spec, target) {
 }
 
 export function wouldCreateCycle(snap, from, to) {
-  // DFS：从 to 能否走到 from
+  // 加边 from→to 成环 ⟺ to ⇝ from（沿快照正向边）——实现下沉 src/shared/graph.js
   const adj = new Map();
   for (const e of snap.edges || []) {
     const a = String(e.from);
     if (!adj.has(a)) adj.set(a, []);
     adj.get(a).push(String(e.to));
   }
-  const start = String(to);
-  const target = String(from);
-  const stack = [start];
-  const seen = new Set();
-  while (stack.length) {
-    const cur = stack.pop();
-    if (cur === target) return true;
-    if (seen.has(cur)) continue;
-    seen.add(cur);
-    for (const n of adj.get(cur) || []) stack.push(n);
-  }
-  return false;
+  return wouldCycleAfterLink((n) => adj.get(n) || [], from, to);
 }

package/src/modules/localtask/panel-presence.js

@@ -0,0 +1,322 @@
+// （#54 自 service.js 拆出）面板 presence 观测与注册表：SSE 连接计数（含心跳剔除）、
+// 常驻主面板发现（APP_DIR/panels.json 登记）、逐端口活性探测、窗口重开节流判据
+// shouldReopenWindow（panel-guard 与 tasktool/panel-escort 用）。
+import http from 'node:http';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { APP_DIR, DEFAULT_PORT } from '../../core/paths.js';
+import { loadStore } from './store-io.js';
+import { isLiveWaiting } from './task-view.js';
+// ─── 面板空闲自释放所需的观测接口（panel-guard.js 调用）────────────
+
+// 当前有多少主题「真的在等待」——常驻面板的空闲自释放据此否决退出：
+// 有 agent 正阻塞等人时，面板是唯一提醒来源，绝不能在此时释放。
+//
+// waiting 标志由 wait 进程写入、结束复位，跨进程可见；但 wait 被强杀（SIGKILL）时
+// 标志会残留。判据统一走 isLiveWaiting（含「截止时刻已过 = 不算等待」这道闸）。
+export async function countWaitingTopics() {
+  const store = await loadStore();
+  const now = Date.now();
+  let n = 0;
+  for (const t of Object.values(store.topics)) {
+    if (isLiveWaiting(t, now)) n += 1;
+  }
+  return n;
+}
+// 活动 SSE 面板连接（只在常驻 serve 进程内有意义）。每条记录最近一次成功写入的时间，
+// wait 据此判断是否真有「活着的」面板标签：心跳写失败（标签已关、TCP 残留）会立刻剔除，
+// 超过新鲜窗口没成功写过的连接不计入——避免页面关了却误判在线、整轮零提醒也不开页。
+//
+// 本期只交付「存在性」接口：panel-guard 只要 clients 数字。SSE 事件流是更上层能力，
+// 留到下个 release 再叠加；这里只保留最小数据结构，streamEventsSSE 接入时直接复用。
+const SSE_HEARTBEAT_MS = 15000;
+const SSE_LIVE_WINDOW_MS = 30000;
+const sseConns = new Set();
+
+// 最近一次**任意**面板请求的时间。
+// SSE 只挂在「本地任务」页，用户切到别的页 SSE 就断了 → 面板明明开着却报 0。
+// 但 App 壳每 15s 打一次 /api/ping（任何页都打）→ 用它兜底才知道"面板还开着"。
+let lastPanelRequestAt = 0;
+
+/** serve 每收到一个面板请求就调一次（供 presence 与空闲判定用）。 */
+export function notePanelRequest() {
+  lastPanelRequestAt = Date.now();
+}
+
+export function panelPresence() {
+  const now = Date.now();
+  let clients = 0;
+  for (const conn of sseConns) {
+    if (now - conn.lastOkWrite <= SSE_LIVE_WINDOW_MS) clients += 1;
+  }
+  return {
+    clients,
+    total: sseConns.size,
+    // 面板最近有没有请求过（切到别的页时 SSE 断了，但面板还开着）
+    panelActive: now - lastPanelRequestAt <= SSE_LIVE_WINDOW_MS,
+  };
+}
+
+/**
+ * HTTP 面板用的 presence：在进程内计数（SSE + panelActive）之外，再补
+ * 「等待中主题数」——App 壳据此在「本地任务」tab 上打角标，用户停在别的页
+ * 也知道有 agent 在等回填（wait 因此不必再重开标签）。
+ */
+export async function httpPanelPresence() {
+  const waiting = await countWaitingTopics().catch(() => 0);
+  return { ...panelPresence(), waiting };
+}
+
+// 给 runtime/api.js 用的最小 SSE 注册表：每次「/api/localtasks/events」连接时
+// 调一下 addEventStreamConn(req, res)，把连接纳入 panelPresence 统计。
+export function addEventStreamConn(req, res) {
+  const conn = { lastOkWrite: Date.now() };
+  sseConns.add(conn);
+  const beat = setInterval(() => {
+    try {
+      res.write(`: ping ${Date.now()}\n\n`);
+      conn.lastOkWrite = Date.now();
+    } catch {
+      clearInterval(beat);
+      sseConns.delete(conn);
+    }
+  }, SSE_HEARTBEAT_MS);
+  beat.unref?.();
+  const cleanup = () => {
+    clearInterval(beat);
+    sseConns.delete(conn);
+  };
+  req.on('close', cleanup);
+  req.on('error', cleanup);
+  res.on('close', cleanup);
+  return conn;
+}
+// ─── 常驻主面板（固定端口）统一入口 ───────────────────────────────────
+
+// 「某端口上有没有可响应的面板」：GET /api/ping。
+// 这与 panelActive 不同：ping 在这里只问「端口上有没有人接 HTTP」，
+// 用于决定是否复用现成面板 / 拉起 serve。
+function pingPort(port, timeoutMs = 700) {
+  return new Promise((resolve_) => {
+    const req = http.get(`http://127.0.0.1:${port}/api/ping`, { timeout: timeoutMs }, (res) => {
+      res.resume();
+      resolve_(true);
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve_(false);
+    });
+    req.on('error', () => resolve_(false));
+  });
+}
+
+// 候选端口：默认端口优先，再叠加 panels.json 里登记的端口
+// （`serve --port` 或默认端口被占自动顺延出来的面板）。
+function candidatePanelPorts() {
+  return [...new Set([DEFAULT_PORT, ...readAllPanels().map((p) => Number(p.port))])].filter(
+    (p) => Number(p) > 0
+  );
+}
+
+/**
+ * 在给定端口列表里找一个正在响应的面板，返回第一个（按列表顺序）；都没有 → null。
+ * 纯候选集版本，便于单测注入端口（默认端口上可能正跑着真实面板）。
+ */
+export async function findRunningAmongPorts(ports, timeoutMs = 700) {
+  const list = [...new Set((Array.isArray(ports) ? ports : []).map(Number))].filter((p) => p > 0);
+  const probed = await Promise.all(
+    list.map(async (port) => ({ port, up: await pingPort(port, timeoutMs) }))
+  );
+  const hit = probed.find((r) => r.up);
+  return hit ? hit.port : null;
+}
+
+/**
+ * 在所有候选端口上找一个正在响应的面板，返回其端口（默认端口优先）；都没有 → null。
+ * 多端口发现是「wait 不再重复开页面」的关键一环。
+ */
+export async function findRunningPanelPort(timeoutMs = 700) {
+  return findRunningAmongPorts(candidatePanelPorts(), timeoutMs);
+}
+
+// 探主面板的 presence 端点。返回 {clients,total}；面板没在跑 / 探测失败 → null。
+//
+// 注意：**CLI 进程自己查自己的进程内计数恒为 0**（SSE 连接只存在于 serve 进程里），
+// 所以 CLI 的 presence 必须去问「常驻主面板」——这正是本函数存在的理由。
+async function fetchPanelPresence(timeoutMs = 900, port = DEFAULT_PORT) {
+  const url = `http://127.0.0.1:${port}/api/localtasks/presence`;
+  return new Promise((resolve_) => {
+    const req = http.get(url, { timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => {
+        body += c;
+      });
+      res.on('end', () => {
+        try {
+          const j = JSON.parse(body);
+          const d = j && typeof j === 'object' && j.data ? j.data : j;
+          resolve_({
+            clients: Math.max(0, Number(d && d.clients) || 0),
+            total: Math.max(0, Number(d && d.total) || 0),
+            panelActive: !!(d && d.panelActive),
+          });
+        } catch {
+          resolve_(null);
+        }
+      });
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve_(null);
+    });
+    req.on('error', () => resolve_(null));
+  });
+}
+
+/**
+ * wait 用的活性探测，返回 0 / 1。
+ *
+ * SSE 活标签（用户停在「本地任务」页）**或** 面板最近有请求（用户停在任意页，
+ * App 壳每 15s 打 /api/ping 兜底）都算「面板开着」→ 1；都没有 → 0。
+ * 旧口径只数 SSE：用户一切到别的页（SSE 单视图挂载，切页即断）wait 就误判
+ * 「没开」，于是重复开标签——这正是本次修复的根因。
+ *
+ * 任何探测失败都按 0 处理（保守地开一次页），绝不因探测失败而阻塞 wait。
+ */
+/**
+ * 纯判据：一次 presence 快照 → 0 / 1。
+ * SSE 活标签或面板最近有请求（停在任意页）都算「面板开着」。
+ */
+export function effectivePresenceFrom(q) {
+  if (!q) return 0;
+  const clients = Math.max(0, Number(q.clients) || 0);
+  return clients > 0 || q.panelActive ? 1 : 0;
+}
+
+export async function probeEffectivePresence(timeoutMs = 900) {
+  const q = await queryPanelPresence(timeoutMs).catch(() => null);
+  return effectivePresenceFrom(q);
+}
+
+/**
+ * 面板活跃度（对外）：**逐个问所有跑着面板的端口**再求和。
+ *
+ * 两个真缺口（结构审计 + 真实 Chrome 复核）：
+ *   1. 只问默认端口（7877）：别的端口上的面板（`serve --port` 或端口被占自动顺延）
+ *      完全看不见 → wait 会以为「没人开着面板」而多开一个窗口。
+ *      serve 起来时把自己登记进 `APP_DIR/panels.json`，这里逐个问。
+ *   2. SSE 只挂在「本地任务」页，用户切到别的页 SSE 就断了 → `panelPresence()`
+ *      报 0，但面板明明开着。这里额外用「最近有没有面板请求」兜底。
+ *
+ * 登记文件放在 APP_DIR（不是 store），**不碰 store schema**。
+ */
+export async function queryPanelPresence(timeoutMs = 900) {
+  const registered = readPanelRegistry();
+  const ports = [...new Set([DEFAULT_PORT, ...registered.map((p) => p.port)])];
+  const results = await Promise.all(
+    ports.map(async (port) => {
+      const r = await fetchPanelPresence(timeoutMs, port);
+      return r ? { port, ...r, reachable: true } : { port, clients: 0, total: 0, reachable: false };
+    })
+  );
+  // 清掉探不到的面板登记（被强杀的进程来不及注销自己，登记会越积越多）
+  const dead = registered.filter((p) => !results.some((r) => r.port === p.port && r.reachable));
+  if (dead.length) {
+    try {
+      writePanels(registered.filter((p) => !dead.includes(p)));
+    } catch {
+      /* ignore */
+    }
+  }
+  const alive = results.filter((r) => r.reachable);
+  if (!alive.length) {
+    // 一个面板都联系不上 → 退回本进程内计数（并说明来源）
+    return { ...panelPresence(), source: 'self', panels: results };
+  }
+  return {
+    clients: alive.reduce((n, r) => n + r.clients, 0),
+    total: alive.reduce((n, r) => n + r.total, 0),
+    // 面板「最近有请求」也算活着：用户可能停在别的页（SSE 已断）但面板开着
+    panelActive: alive.some((r) => r.panelActive),
+    source: 'panel',
+    panels: results,
+  };
+}
+
+// ─── 面板注册表（哪些端口上跑着面板）──────────────────────────────────
+//
+// serve 启动时登记 {port, pid}，退出时注销。presence 逐个探测这些端口。
+// 死掉的登记不碍事：探测不到就跳过（还能顺手清掉）。
+const PANEL_REGISTRY_FILE = () => join(APP_DIR, 'panels.json');
+
+function readAllPanels() {
+  try {
+    const raw = readFileSync(PANEL_REGISTRY_FILE(), 'utf8');
+    const data = JSON.parse(raw);
+    const list = Array.isArray(data && data.panels) ? data.panels : [];
+    return list.filter((p) => p && Number(p.port) > 0);
+  } catch {
+    return [];
+  }
+}
+
+function writePanels(list) {
+  try {
+    const f = PANEL_REGISTRY_FILE();
+    // 目录可能还不存在（全新机器 / CI runner：第一次跑就是干净的用户目录）。
+    // 旧实现只 writeFileSync，ENOENT 被下面的 catch 静默吞掉——registerPanel
+    // 表面上成功、实际一条没落盘，queryPanelPresence 因此永远发现不了非默认端口面板。
+    mkdirSync(dirname(f), { recursive: true });
+    writeFileSync(f, JSON.stringify({ panels: list }, null, 2), 'utf8');
+  } catch {
+    /* 登记失败不影响面板本身 */
+  }
+}
+
+/** serve 起来时登记自己（同一端口重复登记即覆盖）。 */
+export function registerPanel(port) {
+  const list = readAllPanels().filter((p) => Number(p.port) !== Number(port));
+  list.push({ port: Number(port), pid: process.pid, at: Date.now() });
+  writePanels(list);
+  return list;
+}
+
+/** serve 退出时注销自己。 */
+export function unregisterPanel(port) {
+  writePanels(readAllPanels().filter((p) => Number(p.port) !== Number(port)));
+}
+
+/** 读面板注册表（对外只读）。 */
+export function readPanelRegistry() {
+  return readAllPanels();
+}
+
+// 复查节奏与重开上限（REVIEW_MS 已随 wait 编排迁往 tasktool/wait.js）。
+const REOPEN_COOLDOWN_MS = 20_000;
+// 一次 wait 最多开 3 个窗口：够救「手滑关掉」，又不至于在浏览器拦截脚本时刷屏。
+const MAX_WINDOW_OPENS = 3;
+
+/**
+ * 复查时要不要重开窗口。四条判据，任一不满足就不开：
+ *   1. 有活标签（presence > 0）→ 用户在看着，别打扰；
+ *   2. 已经开够次数 → 停止（浏览器拦了脚本、或用户就是不想看，开再多也没用）；
+ *   3. 距上一次开页还在冷却期内 → 等一等（页面加载 + 建立 SSE 需要几秒）；
+ *   4. 其余情况才重开（标签被关了 / 第一次没开成）。
+ *
+ * 抽成纯函数的原因：这段逻辑的 bug 不报错、只表现为「窗口越开越多」，
+ * 必须能被单测钉住。
+ */
+export function shouldReopenWindow({
+  presence,
+  now,
+  lastOpenAt,
+  opens,
+  cooldownMs = REOPEN_COOLDOWN_MS,
+  maxOpens = MAX_WINDOW_OPENS,
+} = {}) {
+  if (Number(presence) > 0) return false;
+  if (Number(opens) >= maxOpens) return false;
+  if (Number(lastOpenAt) > 0 && Number(now) - Number(lastOpenAt) < cooldownMs) return false;
+  return true;
+}