nx-kv 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.21.0] - 2026-11-05 队列与编排的职责单一化 + store 损坏防护
+
+### Fixed
+
+- **store 损坏不再静默清空队列**：localtasks.json 读不出/解析失败时，先把坏文件**改名保留**为
+  `<store>.corrupt-<时间戳>`（同目录最多留 3 份，超出删最旧；改名失败则保留原文件等下次），
+  再落到空 store。此前坏文件留在原地，下一次任何写操作会把它原地覆盖——一次磁盘抖动
+  等于全部主题无声清零。
+
+### Changed
+
+- **localtask service 拆分**（原 2458 行单文件 → 16 个单一职责文件 + 47 行门面）：
+  对外 API 路径与行为**零变化**（CLI/HTTP/面板与所有调用方无感），模块内部分工见各文件头注释。
+- **就绪判定双实现合一**：任务行入口与快照入口此前是两套算法（闸门语义被编码两次），
+  现在共用同一张图与同一个内核判定；跨队列依赖（`"topicKey:id"`）的 fail-open 口径不变。
+  新增跨模型一致性测试，逐条钉住两个入口对同一份数据的结论必须相等。
+- **闸门谓词统一**（`isGateNode`）：此前散落 5 处且判定字段漂移（有的只认插件名、
+  有的连 scope 一起认），现收成一处并集口径。
+- **环检测实现下沉 `src/shared/graph.js`**：mutator 与两个前端组件（画布编排面板、目录编排
+  编辑器）共用一份 DFS——此前三份拷贝，其中一处曾因方向写反漏判 2 节点环。
+- **wait 编排拆分**：面板随行（拉起主面板/深链/窗口重开防风暴）搬进
+  `tasktool/panel-escort.js`，`waitForTask` 回归纯队列出口语义；三个 500ms 节拍的轮询
+  合并为一个 ticker。返回契约与 `--no-open` 行为逐字不变。
+
 ## [0.20.0] - 2026-11-04 任务编排（DAG）进面板 + 面包屑/设置面板收拾 + 改归属项目即搬家
 
 ### Added

package/package.json

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

package/src/core/workflow/project.js

@@ -2,7 +2,7 @@
 // 存盘形状仍是任务行；快照是引擎视图。正文不进快照（payload.textRef）。
 // 跨队列 blockBy（"topicKey:id"）不进引擎边，投影回写时必须保留。
 
-import { BUILTIN_GOALS, edgesFromTasks, taskToNode } from './types.js';
+import { edgesFromTasks, isGateNode, taskToNode } from './types.js';
 import { normalizeBlockBy, parseDepRef } from './readiness.js';
 
 /** @typedef {import('./types.js').WorkflowSnapshot} WorkflowSnapshot */
@@ -66,13 +66,7 @@ export function applySnapshotToTopic(topic, snap) {
 
   // 边 → blockBy（显式依赖）；闸门边由 blocksFollowing 表达，不写进每条 blockBy
   const gateIds = new Set(
-    (snap.nodes || [])
-      .filter(
-        (n) =>
-          n.kind === 'control' ||
-          (n.plugins || []).some((p) => p.name === BUILTIN_GOALS.blockgoal),
-      )
-      .map((n) => String(n.id)),
+    (snap.nodes || []).filter((n) => isGateNode(n)).map((n) => String(n.id)),
   );
 
   for (const task of tasks) {
@@ -100,8 +94,7 @@ export function applySnapshotToTopic(topic, snap) {
 
 /** @param {object} task @param {WfNode} node */
 function syncTaskFromNode(task, node) {
-  const hasBlock = (node.plugins || []).some((p) => p.name === BUILTIN_GOALS.blockgoal);
-  task.blocksFollowing = node.kind === 'control' || hasBlock;
+  task.blocksFollowing = isGateNode(node);
 
   if (node.state === 'success') {
     if (!task.completedAt) {

package/src/core/workflow/readiness.js

@@ -1,8 +1,14 @@
-// 拓扑就绪（自 localtask/dag.js 下沉）。任务行与快照节点两套入口。
+// 拓扑就绪（自 localtask/dag.js 下沉）。任务行与快照节点两套入口，**一个内核**：
+// 任务行先投影成轻量图（taskToNode + edgesFromTasks），本地依赖与闸门判定直接
+// 复用 isNodeReady——两个模型对同一份数据产出同一张图，结论必然一致
+// （一致性由 tests/unit/readiness-consistency.test.mjs 钉死）。
 //
 // blockBy 支持：
-//   - 本地 id（number）——同队列依赖（兼容旧存盘）
-//   - 跨队列引用 `"<topicKey>:<taskId>"`——组编排跨项目边；get 时跨 topic 解析
+//   - 本地 id（number）——同队列依赖（兼容旧存盘）；入图，走内核判定
+//   - 跨队列引用 `"<topicKey>:<taskId>"`——组编排跨项目边；不入引擎图
+//     （edgesFromTasks 跳过），由 resolveForeign 前置直查，fail-open
+
+import { edgesFromTasks, taskToNode, isGateNode } from './types.js';
 
 /** topicKey:id —— key 允许字母数字与 _-（含 __GLOBAL__） */
 const FOREIGN_RE = /^([A-Za-z0-9_-]+):(\d+)$/;
@@ -107,54 +113,69 @@ function isPendingLike(t) {
  *   跨队列依赖解析；缺席或返回空 = fail-open（挡不住）
  */
 
+/** 跨队列依赖是否未满足（true = 挡）。无解析器 / 解析不到 / 已删已迁 → fail-open 不挡。 */
+function foreignBlocked(task, opts) {
+  for (const d of normalizeBlockBy(task.blockBy, task.id)) {
+    const ref = parseDepRef(d);
+    if (!ref || ref.kind !== 'foreign') continue;
+    if (typeof opts?.resolveForeign !== 'function') continue;
+    const found = opts.resolveForeign(ref.key, ref.id);
+    const dep = found && isAlive(found) ? found : null;
+    if (dep && !isCompleted(dep)) return true;
+  }
+  return false;
+}
+
+/**
+ * 任务行 → 轻量图（与 topicToSnapshot 同源：taskToNode 投影节点、edgesFromTasks 产边）。
+ * blockBy 先过 normalizeBlockBy（去自身/去非法，与引擎写入路径同一口径）再产边；
+ * "key:id" 外部边不入图。这是两个模型共用的唯一边源。
+ * @param {object[]} tasks
+ * @returns {{ nodes: import('./types.js').WfNode[], edges: import('./types.js').WfEdge[] }}
+ */
+function rowsGraph(tasks) {
+  const alive = (tasks || []).filter(isAlive).map((t) => ({
+    ...t,
+    blockBy: normalizeBlockBy(t.blockBy, t.id),
+  }));
+  return { nodes: alive.map(taskToNode), edges: edgesFromTasks(alive) };
+}
+
+/** 图上判定：目标节点缺位（不在 all 里）→ true；否则交给 isNodeReady 内核。 */
+function readyInGraph(graph, taskId) {
+  const node = (graph.nodes || []).find((n) => String(n.id) === String(taskId));
+  if (!node) return true;
+  return isNodeReady(graph, node);
+}
+
 /**
  * 某条 pending 现在能不能领（任务行模型）。
+ * 本地依赖 + 闸门走快照同一内核（isNodeReady）；跨队列依赖走 resolveForeign 前置直查。
+ * 前驱判定口径：completedAt ⇔ 节点 success（taskToNode 映射），闸门 = control 屏障。
  * @param {object} task
  * @param {object[]} all
  * @param {ReadyOpts} [opts]
  */
 export function isReadyToClaim(task, all = [], opts = {}) {
   if (!isPendingLike(task)) return false;
-  const byId = new Map((all || []).filter(isAlive).map((t) => [Number(t.id), t]));
-
-  const deps = normalizeBlockBy(task.blockBy, task.id);
-  for (const d of deps) {
-    const ref = parseDepRef(d);
-    if (!ref) continue;
-    let dep = null;
-    if (ref.kind === 'local') {
-      dep = byId.get(ref.id) || null;
-    } else if (typeof opts.resolveForeign === 'function') {
-      const found = opts.resolveForeign(ref.key, ref.id);
-      dep = found && isAlive(found) ? found : null;
-    } else {
-      // 无解析器：跨队列依赖无法验证 → fail-open（与「依赖缺失」同口径）
-      continue;
-    }
-    if (!dep) continue;
-    if (!isCompleted(dep)) return false;
-  }
-
-  const idx = (all || []).indexOf(task);
-  const order = all || [];
-  const myPos = idx >= 0 ? idx : order.findIndex((t) => Number(t.id) === Number(task.id));
-  if (myPos < 0) return true;
-  for (let i = 0; i < myPos; i += 1) {
-    const prev = order[i];
-    if (!isAlive(prev) || !prev.blocksFollowing) continue;
-    if (!isCompleted(prev)) return false;
-  }
-  return true;
+  if (foreignBlocked(task, opts)) return false;
+  return readyInGraph(rowsGraph(all), task.id);
 }
 
 /**
- * 按数组序找第一条可领取的 pending；没有 → null
+ * 按数组序找第一条可领取的 pending；没有 → null。
+ * 图一次构建逐条判定（结论与逐条 isReadyToClaim 相同，省掉每条重建图）。
  * @param {object[]} tasks
  * @param {ReadyOpts} [opts]
  */
 export function findFirstReadyPending(tasks = [], opts = {}) {
-  for (const t of tasks || []) {
-    if (isReadyToClaim(t, tasks, opts)) return t;
+  const list = tasks || [];
+  const graph = rowsGraph(list);
+  for (const t of list) {
+    if (!isPendingLike(t)) continue;
+    if (foreignBlocked(t, opts)) continue;
+    const node = graph.nodes.find((n) => String(n.id) === String(t.id));
+    if (!node || isNodeReady(graph, node)) return t;
   }
   return null;
 }
@@ -177,10 +198,7 @@ export function isNodeReady(snap, node, isBarrierOpen) {
   for (const e of preds) {
     const pred = byId.get(String(e.from));
     if (!pred) continue;
-    const isControl =
-      pred.kind === 'control' ||
-      (pred.plugins || []).some((p) => p.name === 'blockgoal' || p.scope === 'control');
-    if (isControl) {
+    if (isGateNode(pred)) {
       const open = isBarrierOpen
         ? isBarrierOpen(snap, pred.id)
         : pred.state === 'success';

package/src/core/workflow/types.js

@@ -108,6 +108,21 @@ export const BUILTIN_GOALS = Object.freeze({
   timegoal: 'timegoal',
 });
 
+/**
+ * 这个节点是不是「闸门」（控制屏障）——唯一的判定口径，全系统共用
+ * （曾散落 5 处且字段漂移：有的只认 blockgoal 名、有的连 scope==='control' 一起认）。
+ * 并集口径：kind=control，或绑了 blockgoal，或绑了任意 control-scope 插件。
+ * @param {WfNode} node
+ * @returns {boolean}
+ */
+export function isGateNode(node) {
+  if (!node) return false;
+  if (node.kind === 'control') return true;
+  return (node.plugins || []).some(
+    (p) => p.name === BUILTIN_GOALS.blockgoal || p.scope === 'control'
+  );
+}
+
 /**
  * 把现有 localtask 任务行投影成契约节点（只读适配，不改存盘形状）。
  * @param {object} task

package/src/modules/localtask/deletion.js

@@ -0,0 +1,129 @@
+// （#54 自 service.js 拆出）主题删除：四条删除路径共用的同一套判定（deleteGuard：
+// 全局池/等待中/有未领取 → 需 --force）+ 单个/批量删除。
+import { badInput } from '../../core/errors.js';
+import { isGlobalKey, normalizeCwd, resolveTopicKey } from './paths.js';
+import { loadStore, saveStore } from './store-io.js';
+import { isLiveWaiting, isPending, topicView } from './task-view.js';
+// ─── 删除判定：四条删除路径共用同一套规则 ──────────────────────────────
+//
+// 以前「删任务 / 删主题 / 批量删除 / prune」各有各的保护规则，
+// 面板只暴露其中两套 → 同一个动作在 CLI 与面板上表现不一样，看着像乱。
+// 现在规则只写一份，四个入口都调它：
+//
+//   protected（全局共享池）→ 需要 --force
+//   waiting（正阻塞等待）  → 需要 --force（agent 会超时收尾）
+//   has_pending（有未领取）→ 需要 --force（活还没人领）
+//   manual（手动登记的目录）→ 只在 prune 里保留，不参与普通删除
+//
+// force=true 仍然强删（老用法不变）。
+export const DELETE_REASONS = {
+  protected: '全局共享池',
+  waiting: '等待中',
+  has_pending: '有未领取任务',
+  manual: '手动登记',
+};
+
+/**
+ * 判定一个主题能不能删。
+ * @returns {{ok:boolean, reason?:string, pending?:number, message?:string}}
+ */
+export function deleteGuard(topic, { force = false, key = '', scope = 'topic' } = {}) {
+  if (isGlobalKey(key)) {
+    return force
+      ? { ok: true }
+      : { ok: false, reason: 'protected', message: '全局主题是共享任务池，默认不能删除（确认要清空请加 --force）' };
+  }
+  if (isLiveWaiting(topic)) {
+    return force
+      ? { ok: true }
+      : { ok: false, reason: 'waiting', message: '主题正在等待中，不能删除（确认要删请加 --force，agent 将超时收尾）' };
+  }
+  const pending = countPending(topic);
+  // prune 只清"旧脏数据"，不是"删主题"：它不因未领取任务而跳过
+  //（否则会改变 prune 既有语义——它本来就只清空主题/旧模型主题）。
+  if (scope !== 'prune' && pending > 0 && !force) {
+    return {
+      ok: false,
+      reason: 'has_pending',
+      pending,
+      message: `主题「${topic.name || key}」还有 ${pending} 条未领取任务，删除会一并丢掉（确认要删请加 --force）`,
+    };
+  }
+  if (scope === 'prune' && topic.manual) {
+    return { ok: false, reason: 'manual', message: '手动登记的目录不会被 prune 清理（请用 topic remove）' };
+  }
+  return { ok: true };
+}
+
+// 主题里还有多少条**未领取且未删除**的任务（= 还没人领的活）。
+// 删除保护用它：队列里还堆着活就不该被一声不吭地清空。
+function countPending(t) {
+  if (!t || !Array.isArray(t.tasks)) return 0;
+  return t.tasks.filter(isPending).length;
+}
+
+// 删除整个主题（连同其全部任务）。默认拒绝删除「等待中」主题——那会让正阻塞的
+// agent 只能等到超时；force=true 才强删（agent 随后超时收尾）。
+// 全局主题同样默认拒绝（共享池，删掉会让所有 worker 的候补来源消失）；
+// force=true 清空全局任务池。
+export async function removeTopic({ cwd: rawCwd, key: rawKey, force = false } = {}) {
+  if (!rawKey && !rawCwd) {
+    throw badInput('需要 --cwd "<工作目录>" 或 --key "<主题key>"');
+  }
+  const key = resolveTopicKey({ key: rawKey, cwd: rawCwd });
+  const store = await loadStore();
+  const t = store.topics[key];
+  if (!t) {
+    const { notFound } = await import('../../core/errors.js');
+    throw notFound(`主题不存在（key ${key}）`);
+  }
+  // 删除判定只写一份（deleteGuard）：全局共享池 / 等待中 / 有未领取任务 → 都要 --force。
+  const guard = deleteGuard(t, { force, key });
+  if (!guard.ok) throw badInput(guard.message);
+  const view = topicView(t);
+  delete store.topics[key];
+  await saveStore(store);
+  return { status: 'removed', key, name: t.name, cwd: t.cwd, topic: view };
+}
+
+// 批量删除主题：keys / cwds（数组，可并用），或 all=true 清空全部。
+// 默认把「等待中」「不存在」计入 skipped 而不删；force=true 连等待中一起删。
+export async function removeTopics({ keys, cwds, all = false, force = false } = {}) {
+  const hasList = (a) => Array.isArray(a) && a.some((x) => String(x).trim());
+  if (!all && !hasList(keys) && !hasList(cwds)) {
+    throw badInput('需要 --keys "<key,key>" 或 --cwds "<目录,目录>"，或 --all');
+  }
+
+  const store = await loadStore();
+  let targets;
+  if (all) {
+    targets = Object.keys(store.topics);
+  } else {
+    const list = [];
+    if (Array.isArray(keys)) list.push(...keys.map((x) => String(x).trim()).filter(Boolean));
+    if (Array.isArray(cwds)) {
+      for (const c of cwds) if (String(c).trim()) list.push(normalizeCwd(c).key);
+    }
+    targets = [...new Set(list)];
+  }
+
+  const removed = [];
+  const skipped = [];
+  for (const key of targets) {
+    const t = store.topics[key];
+    if (!t) {
+      skipped.push({ key, reason: 'not_found' });
+      continue;
+    }
+    // 判定与单删共用同一套规则（deleteGuard）——批量与单个的语义必须一致
+    const g = deleteGuard(t, { force, key });
+    if (!g.ok) {
+      skipped.push({ key, name: t.name, cwd: t.cwd, reason: g.reason, pending: g.pending || 0 });
+      continue;
+    }
+    removed.push({ key, name: t.name, cwd: t.cwd });
+    delete store.topics[key];
+  }
+  if (removed.length) await saveStore(store);
+  return { status: 'ok', all: !!all, count: removed.length, removed, skipped };
+}

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,95 @@
+// （#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 } 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();
+  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();
+  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();
+  await saveStore(store);
+  return { status: 'ok', key, cwd: t.cwd || cwd, name: t.name, task };
+}