nx-kv 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.8.3] - 2026-10-12
+
+### Changed
+
+- **wait 统一到常驻主面板（固定端口 7877），彻底移除随机端口临时弹窗**：
+  - wait 阻塞时不再在 wait 进程内临时起 http 服务器/弹窗，而是复用 `nx-kv serve` 的
+    「本地任务」页：已在运行则直接打开并深链到当前主题
+    （`#/localtask?key=<主题>&cwd=<目录>`，前端按 key/cwd 自动选中）；
+  - 主面板未运行时，wait 在后台 **detached 自动拉起** `nx-kv serve --no-open
+    --auto-exit`（独立常驻进程，健康检查通过后再开浏览器；拉起失败只降级为纯阻塞、
+    绝不报错中断）；
+  - **主面板页面常驻、提交后不关闭、可连续排队**；wait 拿到任务或超时退出后 serve 依然存活，
+    回填统一由约每 0.5 秒的跨进程文件轮询取走（独立进程写入返回 `delivered:false`）；
+  - `--no-open` 语义保持：不开浏览器、也不自动拉起 serve，仅阻塞等待（冒烟/CI 依赖）。
+
+### Removed
+
+- 删除随 wait 生命周期起停的随机端口临时弹窗服务器及其内嵌页面
+  （`src/modules/localtask/popup.js`），以及与之重复的弹窗专用 HTTP 路由；
+  实时任务统一在固定端口常驻主面板完成。
+  **行为变更**：不再有「wait 结束即关闭」的临时窗口，也不再输出随机端口地址——
+  请改用常驻面板 `http://127.0.0.1:7877/`（wait 会自动打开/拉起）。
+
+## [0.8.2] - 2026-10-12
+
+### Added
+
+- **实时任务 wait 返回任务时自动追加「收尾提醒」（可配置，默认开启）**，防止 agent 在长对话里
+  漂移、偶尔忘记最后再 wait 一次：
+  - wait 交付任务时在 `task.text` 末尾拼接一段固定提醒（默认大意：规划计划、完成本任务，
+    计划的最后一个动作是再次调用 `nx-kv localtask wait` 收尾本轮，拿到下一条或超时前不要提前结束）。
+  - 只作用于**返回给 agent 的载荷**，面板/库存里的任务原文保持干净、不被改写；原文已包含同样
+    追加语时幂等不重复追加。
+  - 可在「本地任务」页配置（编辑、保存、恢复默认、一键关闭），CLI/HTTP：
+    `localtask config --suffix "<文案>"`、`--no-suffix` 关闭、`--reset-suffix` 恢复默认
+    （HTTP `PATCH` 传 `"suffix": ""` 关闭）；
+    `PATCH /api/localtasks/setting` 增 `suffix` 字段，设置视图增 `taskSuffix`/`defaultTaskSuffix`/`suffixEnabled`。
+
+### Fixed
+
+- `loadStore` 重建 settings 时只保留 `timeoutSec`、把 `taskSuffix` 字段丢掉，导致
+  第一次 PATCH 关闭后第二次 PATCH 改超时，taskSuffix 会被默认值覆盖（仅 0.8.1 受影响）。
+
 ## [0.8.1] - 2026-10-12
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "nx-kv — KV 清单管理中枢（远程）+ 本机本地任务队列（localtask）：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 提交 / 领取 / 阻塞接收任务",
   "type": "module",
   "bin": {

package/src/modules/localtask/index.js

@@ -181,10 +181,24 @@ export default {
       id: 'localtask.config',
       cli: ['localtask', 'config'],
       http: ['PATCH', '/api/localtasks/setting'],
-      summary: '配置等待超时（秒；推荐 180=3 分钟，最大 600=10 分钟，超上限自动截断）',
-      flags: { timeout: { type: 'number', required: true, hint: '超时秒数（1-600）' } },
-      run: (ctx) => service.updateSettings({ timeoutSec: ctx.timeout }),
-      render: (s) => `已配置等待超时 ${s.timeoutSec} 秒（推荐 ${s.recommendedSec}，最大 ${s.maxSec}）`,
+      summary: '配置等待超时（秒）/ 收尾追加语（task.text 末尾自动追加的固定指令；置空关闭）',
+      flags: {
+        timeout: { type: 'number', hint: '超时秒数（1-600）' },
+        suffix: { type: 'string', hint: '收尾追加语文本（与 --reset-suffix/--no-suffix 互斥）' },
+        'reset-suffix': { type: 'boolean', hint: '恢复默认收尾追加语' },
+        'no-suffix': { type: 'boolean', hint: '清空并关闭收尾追加语' },
+      },
+      run: (ctx) => {
+        const patch = { timeoutSec: ctx.timeout };
+        if (ctx['no-suffix']) patch.taskSuffix = '';
+        else if (ctx['reset-suffix']) patch.taskSuffix = service.DEFAULT_TASK_SUFFIX;
+        else if (ctx.suffix !== undefined) patch.taskSuffix = ctx.suffix;
+        return service.updateSettings(patch);
+      },
+      render: (s) => {
+        const x = s.suffixEnabled ? '收尾追加语已开启' : '收尾追加语已关闭';
+        return `已配置等待超时 ${s.timeoutSec} 秒（推荐 ${s.recommendedSec}，最大 ${s.maxSec}）· ${x}`;
+      },
     },
 
     {
@@ -257,5 +271,16 @@ export default {
       run: (ctx) => service.cancelWait({ cwd: ctx.cwd, key: ctx.key }),
       render: renderCancel,
     },
+
+    {
+      // 探测常驻面板上当前正打开的「实时任务」标签数（活动 SSE 连接数）。
+      // wait 开页前先经此端点：有活标签就复用、不再 openBrowser 新开页（避免 Edge 重复开标签）；
+      // 没有活标签时才开页深链。探测失败 / 旧版无此端点时 service 保守返回 0，不阻塞 wait。
+      id: 'localtask.presence',
+      cli: ['localtask', 'presence'],
+      http: ['GET', '/api/localtasks/presence'],
+      summary: '探测主面板上当前打开的「实时任务」标签数（活动 SSE 连接数；用于 wait 不重复开页）',
+      run: () => service.panelPresence(),
+    },
   ],
 };

package/src/modules/localtask/service.js

@@ -24,11 +24,12 @@
 import http from 'node:http';
 import crypto from 'node:crypto';
 import fsp from 'node:fs/promises';
+import { spawn } from 'node:child_process';
 import { basename, dirname, join, resolve } from 'node:path';
-import { APP_DIR } from '../../core/paths.js';
+import { fileURLToPath } from 'node:url';
+import { APP_DIR, DEFAULT_PORT } from '../../core/paths.js';
 import { badInput } from '../../core/errors.js';
 import { openBrowser } from '../../core/open.js';
-import { renderPopupPage } from './popup.js';
 
 export const DEFAULT_TIMEOUT_MS = 180_000; // 阻塞默认 3 分钟（推荐值）
 const POLL_MS = 500; // 跨进程兜底轮询间隔
@@ -37,6 +38,25 @@ export const MAX_TIMEOUT_SEC = 600; // 阻塞时长上限（10 分钟）
 export const MAX_SUMMARY = 2000; // 现状（状态）长度上限（原 200，已放宽）
 export const MAX_TEXT = 20_000; // 单条任务内容长度上限
 
+// wait 取任务返回时，在 task.text 末尾追加的「收尾指令」（可在面板/CLI 修改；置空关闭）。
+// 作用：从每一条任务层面反复强调「计划最后再 wait 一次」，避免 agent 在长对话里漂移、漏调。
+// 注意：命令名是 localtask 不是 sessiontask（v0.8.0 重命名后），但默认文案直接复用同一段文字。
+export const DEFAULT_TASK_SUFFIX =
+  '规划计划，然后完成这个任务；计划的最后一个动作，是再次调用 ' +
+  'nx-kv localtask wait（带上 --cwd 当前工作目录、--summary 当前现状、--json）收尾本轮，' +
+  '在拿到下一条任务或超时之前不要提前结束。';
+const MAX_SUFFIX_LEN = 500; // 收尾追加语长度上限
+
+// 归一化收尾追加语：缺省（旧 store 无此字段）→ 默认；显式传 ''（清空）→ '' 表示关闭。
+// 注意：与 timeoutSec 不同——timeoutSec 缺省→推荐值（仍开启），taskSuffix 缺省→默认文本。
+// 因此从老 store 读 settings.taskSuffix 时，clampTaskSuffix 会自动补默认；想"关闭"必须显式 ''。
+export function clampTaskSuffix(v) {
+  if (v === undefined || v === null) return DEFAULT_TASK_SUFFIX;
+  let s = String(v).trim();
+  if (s.length > MAX_SUFFIX_LEN) s = s.slice(0, MAX_SUFFIX_LEN);
+  return s;
+}
+
 // ─── 存储位置：可环境变量覆盖（测试隔离）；旧名/旧文件自动兼容 ──────────
 
 export function storePath() {
@@ -119,7 +139,11 @@ export function stampNow(d = new Date()) {
 // ─── 存储读写（原子写 + 损坏容忍 + v1/v2 迁移） ───────────────────
 
 function emptyStore() {
-  return { version: 4, settings: { timeoutSec: DEFAULT_TIMEOUT_SEC }, topics: {} };
+  return {
+    version: 4,
+    settings: { timeoutSec: DEFAULT_TIMEOUT_SEC, taskSuffix: DEFAULT_TASK_SUFFIX },
+    topics: {},
+  };
 }
 
 // 归一化超时秒数：非法/缺省 → 推荐值；超上限截断为 10 分钟
@@ -182,7 +206,14 @@ async function loadStore() {
   if (!topics) return emptyStore();
   return {
     version: 4,
-    settings: { timeoutSec: clampTimeoutSec(settings && settings.timeoutSec) },
+    settings: {
+      timeoutSec: clampTimeoutSec(settings && settings.timeoutSec),
+      // 旧 store 可能没存过 taskSuffix（v0.8.0 之前）；clampTaskSuffix 缺省→默认文本。
+      // 显式 ''（关闭）会保留——判断条件是「字段存在且非 undefined」，不能只看 falsy。
+      taskSuffix: settings && Object.prototype.hasOwnProperty.call(settings, 'taskSuffix')
+        ? clampTaskSuffix(settings.taskSuffix)
+        : DEFAULT_TASK_SUFFIX,
+    },
     topics,
   };
 }
@@ -358,6 +389,10 @@ function settingsView(s) {
     timeoutSec: clampTimeoutSec(s && s.timeoutSec),
     recommendedSec: DEFAULT_TIMEOUT_SEC,
     maxSec: MAX_TIMEOUT_SEC,
+    // wait 交付任务时追加到 task.text 末尾的收尾提醒；''=关闭；defaultTaskSuffix 供 UI 恢复默认
+    taskSuffix: clampTaskSuffix(s && s.taskSuffix),
+    defaultTaskSuffix: DEFAULT_TASK_SUFFIX,
+    suffixEnabled: !!clampTaskSuffix(s && s.taskSuffix),
   };
 }
 
@@ -402,14 +437,27 @@ export async function pruneTopics({ allFinished = false, dryRun = false } = {})
   return { status: 'ok', dryRun: !!dryRun, count: removed.length, removed };
 }
 
-// 配置等待超时（页面可调；推荐 180=3 分钟，最大 600=10 分钟，超上限自动截断）
-export async function updateSettings({ timeoutSec } = {}) {
-  const n = Number(timeoutSec);
-  if (!Number.isFinite(n) || n <= 0) {
-    throw badInput(`超时时间需为 1-${MAX_TIMEOUT_SEC} 秒（推荐 ${DEFAULT_TIMEOUT_SEC}）`);
+// 配置等待超时 / 任务收尾追加语（页面可调）。超时推荐 180=3 分钟、最大 600=10 分钟；
+// taskSuffix 为 wait 返回任务时追加到 task.text 末尾的固定指令，传 '' 关闭、不传保持不变。
+export async function updateSettings({ timeoutSec, taskSuffix } = {}) {
+  const hasTimeout = timeoutSec !== undefined && timeoutSec !== null;
+  const hasSuffix = taskSuffix !== undefined;
+  if (!hasTimeout && !hasSuffix) {
+    throw badInput(
+      '请至少指定一项：--timeout <秒>，或 --suffix "<收尾追加语>"（--no-suffix 关闭追加、--reset-suffix 恢复默认）'
+    );
   }
   const store = await loadStore();
-  store.settings = { timeoutSec: clampTimeoutSec(n) };
+  const next = { ...store.settings };
+  if (hasTimeout) {
+    const n = Number(timeoutSec);
+    if (!Number.isFinite(n) || n <= 0) {
+      throw badInput(`超时时间需为 1-${MAX_TIMEOUT_SEC} 秒（推荐 ${DEFAULT_TIMEOUT_SEC}）`);
+    }
+    next.timeoutSec = clampTimeoutSec(n);
+  }
+  if (hasSuffix) next.taskSuffix = clampTaskSuffix(taskSuffix);
+  store.settings = next;
   await saveStore(store);
   return settingsView(store.settings);
 }
@@ -628,6 +676,16 @@ export async function reorderTasks({ cwd: rawCwd, id, beforeId, afterId } = {})
 
 // ─── 阻塞等待：核心入口 ─────────────────────────────────────────────
 
+// 把收尾追加语拼到返回给 agent 的 task.text 末尾（只改返回载荷，绝不回写库存原文）。
+// suffix 为空 → 原样返回；已包含同样追加语（幂等）→ 不重复追加。
+function withTaskSuffix(task, suffix) {
+  const s = clampTaskSuffix(suffix);
+  if (!task || !s) return task;
+  const base = String(task.text || '');
+  if (base.includes(s)) return task;
+  return { ...task, text: `${base.replace(/\s+$/, '')}\n\n${s}` };
+}
+
 /**
  * 针对某主题（工作目录）等待用户回填下一条任务。
  * @param {string}  [cwd]     工作目录（主题按目录名识别）；缺省 → 进程当前 cwd
@@ -649,19 +707,30 @@ export async function waitForTask({
   const summary = normalizeSummary(rawSummary); // 现状必填
 
   // 超时：显式 --timeout（秒/毫秒）优先；否则用页面配置；统一夹到 1-600
+  const startStore = await loadStore();
   let sec;
   if (timeoutSec !== undefined && timeoutSec !== null) sec = timeoutSec;
   else if (timeoutMs !== undefined && timeoutMs !== null) sec = Number(timeoutMs) / 1000;
-  else sec = (await loadStore()).settings.timeoutSec;
+  else sec = startStore.settings.timeoutSec;
   const tmo = clampTimeoutSec(sec) * 1000;
+  const suffix = startStore.settings.taskSuffix; // 返回任务时追加的收尾指令（本轮固定）
 
   // 1. 主题队列已有 pending → 立即取走，不开窗、不阻塞；记录本轮完成总结
   const queued = await consumeFirstPending(key, summary);
-  if (queued) return { status: 'ok', key, cwd, name, summary, task: queued, queued: true };
+  if (queued) {
+    return { status: 'ok', key, cwd, name, summary, task: withTaskSuffix(queued, suffix), queued: true };
+  }
 
-  // 2. 没有 pending → 起内嵌弹窗服务器
-  const server = await startPopupServer(key, cwd, summary, tmo);
-  const addr = `http://127.0.0.1:${server.address().port}/`;
+  // 2. 没有 pending → 复用常驻主面板（不再起随机端口临时弹窗）：
+  //    a) 确保主面板在跑（不存在就 detached 拉起 serve --no-open --auto-exit）；
+  //    b) 探测活动 SSE 连接：有活标签就不开新页（避免 Edge 重复开标签）；
+  //                没活标签就 openBrowser 深链到当前主题。
+  //    失败只降级为纯阻塞——绝不抛错中断 wait。
+  //    --no-open 模式（冒烟/CI）不发起任何面板相关动作：不开浏览器、不拉起 serve、不开 SSE。
+  //    这样可避免在测试里 spawn 出一堆孤儿进程占着 7877 端口。
+  const panelInfo = open ? await ensureMainPanel() : { running: false, started: false, url: '' };
+  const presence = panelInfo.running ? await probePresence() : 0;
+  const deepLink = deepLinkUrl(key, cwd);
 
   // 3. 结果承诺：两个生产者（同进程 waiter / 跨进程轮询）+ 超时
   let resolveOutcome;
@@ -694,7 +763,7 @@ export async function waitForTask({
       .catch(() => {});
   }, POLL_MS);
 
-  // 登记「等待中」（含截止时刻与现状），面板/弹窗据此显示倒计时
+  // 登记「等待中」（含截止时刻与现状），面板据此显示倒计时
   await setWaiting(key, cwd, summary, true, new Date(Date.now() + tmo));
 
   // 登记之后再查一次关闭标记：setWaiting 刚清掉上一轮残留的标记，因此这里若有值
@@ -706,13 +775,32 @@ export async function waitForTask({
   // waiter/轮询就位后再回调，保证 onReady 里立刻回填也能被接住
   if (typeof onReady === 'function') {
     try {
-      await onReady({ addr, key, cwd, name, summary });
+      await onReady({ addr: deepLink, key, cwd, name, summary });
     } catch {
       /* 钩子异常不得影响 wait */
     }
   }
 
-  if (open) openBrowser(addr);
+  // 没活标签且主面板在跑 → 开浏览器深链（让用户能在面板里选中主题并响应等待事件）。
+  // 已有活标签 / --no-open / 主面板未启动 → 都不开（避免重复标签 + 冒烟/CI 兼容）。
+  const openPage = open && presence === 0 && panelInfo.running;
+  if (openPage) openBrowser(deepLink);
+
+  // 周期复查：等待期间每 5s 查一次活动标签；万一开始时判错（页面被关），20s 冷却内重开。
+  // 不到点不开新页（节流，避免「标签被关 → 立刻开 → 立刻关」抖动）。
+  const REVIEW_MS = 5_000;
+  const REOPEN_COOLDOWN_MS = 20_000;
+  let lastReopenAt = 0;
+  const review = setInterval(async () => {
+    if (!panelInfo.running || !open) return;
+    const n = await probePresence().catch(() => 0);
+    if (n > 0) return; // 有活标签，不动
+    const now = Date.now();
+    if (now - lastReopenAt < REOPEN_COOLDOWN_MS) return; // 冷却中
+    lastReopenAt = now;
+    openBrowser(deepLink);
+  }, REVIEW_MS);
+  review.unref?.();
 
   let result;
   try {
@@ -722,127 +810,18 @@ export async function waitForTask({
         ? { status: 'timeout', key, cwd, summary, timeoutMs: tmo }
         : r.kind === 'cancelled'
         ? { status: 'timeout', key, cwd, summary, timeoutMs: tmo, cancelled: true }
-        : { status: 'ok', key, cwd, name, summary, task: r.task, delivered: r.delivered, queued: false };
+        : { status: 'ok', key, cwd, name, summary, task: withTaskSuffix(r.task, suffix), delivered: r.delivered, queued: false };
   } finally {
     clearInterval(poll);
     clearInterval(cancelPoll);
+    clearInterval(review);
     clearTimeout(timer);
     waiters.delete(key);
     await clearWaiting(key);
-    await stopServer(server);
   }
   return result;
 }
 
-// ─── 内嵌弹窗服务器 ─────────────────────────────────────────────────
-
-function sendJson(res, status, obj) {
-  res.writeHead(status, {
-    'content-type': 'application/json; charset=utf-8',
-    'cache-control': 'no-store',
-  });
-  res.end(JSON.stringify(obj));
-}
-
-function sendHtml(res, html) {
-  res.writeHead(200, {
-    'content-type': 'text/html; charset=utf-8',
-    'cache-control': 'no-store',
-  });
-  res.end(html);
-}
-
-async function readBody(req) {
-  const chunks = [];
-  let size = 0;
-  for await (const c of req) {
-    size += c.length;
-    if (size > 1024 * 1024) throw new Error('请求体过大');
-    chunks.push(c);
-  }
-  if (!chunks.length) return {};
-  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-}
-
-// 与主 api.js 同一套跨站防护：弹窗服务器虽只绑 127.0.0.1，浏览器里任意页面都能
-// 向它发请求，非本机来源一律挡。
-function originAllowed(req) {
-  const origin = req.headers.origin;
-  if (!origin) return true;
-  try {
-    const h = new URL(origin).hostname;
-    return h === '127.0.0.1' || h === 'localhost' || h === '::1';
-  } catch {
-    return false;
-  }
-}
-
-async function handlePopup(req, res, key, cwd, summary, timeoutMs) {
-  const url = new URL(req.url, 'http://127.0.0.1/');
-  const method = (req.method || 'GET').toUpperCase();
-
-  try {
-    if ((method === 'GET' || method === 'HEAD') && (url.pathname === '/' || url.pathname === '/index.html')) {
-      sendHtml(res, renderPopupPage({ key, cwd, summary, timeoutMs }));
-      return;
-    }
-
-    if (url.pathname === '/api/localtasks' && method === 'GET') {
-      sendJson(res, 200, { ok: true, data: await listTasks() });
-      return;
-    }
-
-    if (url.pathname === '/api/localtasks' && method === 'POST') {
-      if (!originAllowed(req)) {
-        sendJson(res, 403, { ok: false, error: '跨站请求被拒绝（弹窗仅接受本机来源）', code: 'BLOCKED' });
-        return;
-      }
-      const body = await readBody(req);
-      sendJson(res, 200, { ok: true, data: await addTask({ cwd, text: body.text }) });
-      return;
-    }
-
-    if (url.pathname === '/api/localtasks/item' && method === 'DELETE') {
-      if (!originAllowed(req)) {
-        sendJson(res, 403, { ok: false, error: '跨站请求被拒绝（弹窗仅接受本机来源）', code: 'BLOCKED' });
-      } else {
-        const body = await readBody(req);
-        sendJson(res, 200, { ok: true, data: await removeTask({ cwd, id: body.id }) });
-      }
-      return;
-    }
-
-    sendJson(res, 404, { ok: false, error: '不存在: ' + method + ' ' + url.pathname });
-  } catch (err) {
-    const code = err && err.code === 'INVALID_INPUT' ? 400 : err && err.code === 'NOT_FOUND' ? 404 : 500;
-    sendJson(res, code, { ok: false, error: String((err && err.message) || err), code: err.code || 'INTERNAL' });
-  }
-}
-
-function startPopupServer(key, cwd, summary, timeoutMs) {
-  const server = http.createServer((req, res) => handlePopup(req, res, key, cwd, summary, timeoutMs));
-  return new Promise((resolve_, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', () => resolve_(server));
-  });
-}
-
-function stopServer(server) {
-  return new Promise((resolve_) => {
-    const force = setTimeout(() => {
-      try {
-        server.closeAllConnections();
-      } catch {
-        /* Node 版本不支持则忽略，close 仍会兜底 */
-      }
-    }, 800);
-    server.close(() => {
-      clearTimeout(force);
-      resolve_();
-    });
-  });
-}
-
 // ─── 面板空闲自释放所需的观测接口（panel-guard.js 调用）────────────
 
 // 当前有多少主题「真的在等待」——常驻面板的空闲自释放据此否决退出：
@@ -913,3 +892,102 @@ export function addEventStreamConn(req, res) {
   res.on('close', cleanup);
   return conn;
 }
+
+// ─── 常驻主面板（固定端口）统一入口 ───────────────────────────────────
+
+// 「主面板就绪」=端口上有可响应的服务。
+// 这与 /api/ping 不同：ping 是面板壳层每 15s 主动上报「有页面开着」，
+// 这里只问「端口上有没有人接 HTTP」——用于决定是否要拉起 serve。
+async function probePanelReady(timeoutMs = 900) {
+  const url = `${panelBaseUrl()}/api/ping`;
+  return new Promise((resolve_) => {
+    const req = http.get(url, { timeout: timeoutMs }, (res) => {
+      res.resume();
+      resolve_(true);
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve_(false);
+    });
+    req.on('error', () => resolve_(false));
+  });
+}
+
+// 「活动 SSE 连接数」= 主面板上当前正打开的「实时任务」标签数。
+// 用于 wait 决策：已有活标签就不重开页面，让那个标签响铃/打角标/弹通知；
+// 没有活标签时再 openBrowser 新开深链标签。
+//
+// 任何失败/旧版无此端点都按 0 处理（保守地开一次页），绝不因探测失败而阻塞 wait。
+async function probePresence(timeoutMs = 900) {
+  const url = `${panelBaseUrl()}/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_(Math.max(0, Number(d && d.clients) || 0));
+        } catch {
+          resolve_(0);
+        }
+      });
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve_(0);
+    });
+    req.on('error', () => resolve_(0));
+  });
+}
+
+function panelBaseUrl() {
+  return `http://127.0.0.1:${DEFAULT_PORT}`;
+}
+
+// 深链到主面板「实时任务」页并选中当前主题（key 优先，cwd 兜底）。
+function deepLinkUrl(key, cwd) {
+  return `${panelBaseUrl()}/#/localtask?key=${encodeURIComponent(key)}&cwd=${encodeURIComponent(cwd)}`;
+}
+
+// 本仓库/已安装包的 CLI 入口（src/modules/localtask/ 上三级到包根）。
+function binCliPath() {
+  return fileURLToPath(new URL('../../../bin/cli.mjs', import.meta.url));
+}
+
+// 确保常驻主面板可用：已在运行直接复用；否则后台 detached 拉起一个独立
+// `nx-kv serve --no-open --auto-exit`（unref，不随 wait 退出而关闭），再轮询健康端点。
+// 失败只返回 running:false，绝不抛错——wait 仍可阻塞等待 CLI/轮询回填。
+//
+// --auto-exit：这个实例是**为等用户回填而临时拉起**的，用完就该让位——面板页全部关闭、
+// 又没有等待中的主题时自行退出（宽限期见 panel-guard.js）。下一次 wait 需要时会再拉起
+// （冷启动 <1s）。用户手动 `nx-kv serve` 的实例不带此标志，不会自己跑掉。
+async function ensureMainPanel() {
+  const url = panelBaseUrl() + '/';
+  if (await probePanelReady()) return { running: true, started: false, url };
+
+  try {
+    const child = spawn(process.execPath, [binCliPath(), 'serve', '--no-open', '--auto-exit'], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.on('error', () => {
+      /* 见轮询兜底 */
+    });
+    child.unref();
+  } catch {
+    return { running: false, started: false, url };
+  }
+
+  const deadline = Date.now() + 15_000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 200));
+    if (await probePanelReady(700)) return { running: true, started: true, url };
+  }
+  return { running: false, started: true, url };
+}