nx-kv 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.22.0] - 2026-11-05 任务页 ack 定位轨
+
+### Added
+
+- **任务页 ack 定位轨（任务 #48）**：反复 ack 反馈的任务（正文一轮一轮变长，#34 有 5 轮、
+  正文 13903 字符）在右侧多一条定位轨——**一轮一个节点**，点一下直接跳到那一轮的
+  「上一轮完成总结」。复用简介页那套定位轨的视觉（`.doc-rail`），但定位方式不同：
+  按**块序号**跳，不按标题锚点跳。
+  - 为什么不用标题锚点：实时预览态逐块渲染，每块各有一套标题 id 生成器，于是同名标题在
+    DOM 里拿到的是**重复的同一个 id**（两个「## 上一轮完成总结」都是同一个 id）——
+    按 id 跳永远落在第一轮。块序号（`data-i`）才唯一。
+  - 阅读态（整篇一次性渲染）没有块元素，改按「第 N 个 ack 标题」定位——该态标题 id 互不相同。
+  - 轮次从**正文**抽（每轮一个「## 上一轮完成总结」段）：正文即历史，改完正文轨立刻跟着变。
+  - 只有一个节点时不显示（没有可跳的多轮，挂了也是噪音）。
+
+## [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
@@ -18,51 +57,23 @@
   - 闸门徽章升级：显示被挡后续数（`闸门×N`，悬停列出 #id）。
 - 组任务行尾新增「⋮」行菜单（编排依赖 / 闸门开关），待领取行悬停可见。
 
+- `localtask config --suffix-list "一条,二条"` / `--ack-list "一条,二条"`：**整体替换**多条
+  提示词列表（逗号分隔；HTTP body 传数组）。此前 action 只暴露单条 `--suffix`/`--ack`，
+  面板的多条保存无处可传（#41 实测发现并修）。
+
 ### Changed
 
 - **设置面板观感重做（任务 #41 重开反馈「ui 太丑了」→ 二轮「更丑了」）**：交互语义不变，只收拾
   密度与层级——「提示词 / 模板」栏的竖排 tab 侧栏改成顶部一排药丸、内容限宽；提示词条目行去描边、
   编号不用圆圈、**收起标题洗掉原始模板标记**（不再直接甩 `{{#goal}}〔…〕` 给人看）；操作条分隔线分组；
   项目级设置从大卡片改成紧凑行（项目多时一屏 8 个而不是 2 个），「持续 get」关着时只留一枚行内小开关；
-  「提示词 / 模板」栏不再套卡（盒中盒显脏）。：交互语义不变，只收拾
-  密度与层级——「提示词 / 模板」栏的竖排 tab 侧栏改成顶部一排药丸、内容限宽；
-  提示词条目行去描边、编号不用圆圈；操作条分隔线分组；项目级设置从大卡片改成
-  紧凑行（项目多时一屏 8 个而不是 2 个），「持续 get」关着时只留一枚行内小开关。
-
-### Changed
+  「提示词 / 模板」栏不再套卡（盒中盒显脏）。
 
 - **面包屑移到 maincontent 面板内顶部（任务 #44）**：路径条不再占窗口顶部通栏
   （那是侧栏的地盘），改成挂在**当前主面板**顶部的一枚小药丸——目录任务表 /
   任务详情页 / 项目组 / 全部目录总览 / 云端总览 / 仓库管理 / 任务模板 各面板
   根部都有一条；MD 工作台里则直接放进顶部工具栏（`mdw-top`）内、标题左侧；
-  「← 返回」随路径条一起搬进面板（按来处返回的行为不变）。：路径条不再占窗口顶部通栏
-  （那是侧栏的地盘），改成挂在**当前主面板**顶部的一枚小药丸——目录任务表 /
-  任务详情页 / 项目组 / 全部目录总览 / 云端总览 / 仓库管理 / 任务模板 各面板
-  根部都有一条；「← 返回」随路径条一起搬进面板（按来处返回的行为不变）。
-
-### Fixed
-
-- **改归属项目即搬家（任务 #43「提交任务后发现归属项目填错了，重新修改提交无效」）**：
-  此前「归属决定落点」只在提交那一刻生效——提交后发现归属填错，改正文里的 project 再保存，
-  正文改了队列没动：任务还挂在旧项目队列里，旧项目的 agent 照旧领走，新项目的 agent 永远
-  看不见，组面板/目录页也都显示旧归属。现在 `localtask update --text` / `localtask reopen --text`
-  / 面板「保存并同步 / 重做」走与派任务同一套落点判定：effective frontmatter.project 解析到
-  哪个登记项目，任务就迁到哪个队列；介绍引用（projectIntro/projectDesc）随归属刷新。
-  约束如实说明：已领取的任务不能改归属（要改先 reopen）；带队列内依赖/闸门的任务搬运会
-  跨队列断链，先解除再改（明确报错，不静默）；搬家后任务拿到**新队列的 id**（面板页签自动
-  跟到新号，CLI 输出标注迁移）；指向它的跨队列引用（`topicKey:id`）改写到新地址。
-  另自愈历史脏数据：归属字段与所在队列对不上（上一轮只改字段没搬队列的残留）时，
-  保存即搬到归属队列；已领取/带队列内依赖的脏数据不搬也不拦普通编辑。
-
-- **顶部面包屑真正可见 + 补返回键（任务 #42）**：面包屑此前**渲染了却看不见**——
-  FlexLayout 的根是绝对定位（inset:0），铺满工作区把 26px 的路径条盖在下面
-  （侧栏面板压在上面，路径条点不到也看不见）。现在工作区有面包屑时布局整体下移一条；
-  侧栏也不再出页签条（#33「无页签化」的残留，页签条同样压在路径条上）。
-  面包屑条左侧新增「← 返回」：按**来处**返回（会话内路由历史栈）——
-  从项目组点任务（任务住在 dir 队列里，详情页落在 dir 作用域）时，返回会回到**组**
-  而不是掉进目录；没有上一级时不画返回键。
-
-### Changed
+  「← 返回」随路径条一起搬进面板（按来处返回的行为不变）。
 
 - **可视化编排面板（任务 #40 验收反馈重开）**：目录与项目组**共用**一块编排面板，
   从任务面板**头部右侧的绿色超链**进入（开在右侧主内容区）：
@@ -83,13 +94,27 @@
   - **项目级「持续 get」一句话配置**：选模板（内置默认 + 全局回调提示词条目）→ 改一句话
     （`%s` = 任务编号，存取时与 `{{task.id}}` 互转）→ 添加；不再手写整段模板。
 
-### Added
+### Fixed
 
-- `localtask config --suffix-list "一条,二条"` / `--ack-list "一条,二条"`：**整体替换**多条
-  提示词列表（逗号分隔；HTTP body 传数组）。此前 action 只暴露单条 `--suffix`/`--ack`，
-  面板的多条保存无处可传（#41 实测发现并修）。
+- **改归属项目即搬家（任务 #43「提交任务后发现归属项目填错了，重新修改提交无效」）**：
+  此前「归属决定落点」只在提交那一刻生效——提交后发现归属填错，改正文里的 project 再保存，
+  正文改了队列没动：任务还挂在旧项目队列里，旧项目的 agent 照旧领走，新项目的 agent 永远
+  看不见，组面板/目录页也都显示旧归属。现在 `localtask update --text` / `localtask reopen --text`
+  / 面板「保存并同步 / 重做」走与派任务同一套落点判定：effective frontmatter.project 解析到
+  哪个登记项目，任务就迁到哪个队列；介绍引用（projectIntro/projectDesc）随归属刷新。
+  约束如实说明：已领取的任务不能改归属（要改先 reopen）；带队列内依赖/闸门的任务搬运会
+  跨队列断链，先解除再改（明确报错，不静默）；搬家后任务拿到**新队列的 id**（面板页签自动
+  跟到新号，CLI 输出标注迁移）；指向它的跨队列引用（`topicKey:id`）改写到新地址。
+  另自愈历史脏数据：归属字段与所在队列对不上（上一轮只改字段没搬队列的残留）时，
+  保存即搬到归属队列；已领取/带队列内依赖的脏数据不搬也不拦普通编辑。
 
-### Fixed
+- **顶部面包屑真正可见 + 补返回键（任务 #42）**：面包屑此前**渲染了却看不见**——
+  FlexLayout 的根是绝对定位（inset:0），铺满工作区把 26px 的路径条盖在下面
+  （侧栏面板压在上面，路径条点不到也看不见）。现在工作区有面包屑时布局整体下移一条；
+  侧栏也不再出页签条（#33「无页签化」的残留，页签条同样压在路径条上）。
+  面包屑条左侧新增「← 返回」：按**来处**返回（会话内路由历史栈）——
+  从项目组点任务（任务住在 dir 队列里，详情页落在 dir 作用域）时，返回会回到**组**
+  而不是掉进目录；没有上一级时不画返回键。
 
 - **首次打开设置面板爆栈**（任务 #41 实测发现，#33 遗留）：`openPanel` 按区域分发时
   FLOAT → `openFloatingPanel` → `openPanel`（未带 area）→ 又判成 FLOAT → 无限递归
@@ -551,7 +576,6 @@
   - **实时预览块级查找**：Ctrl/⌘F 在预览态可用，n/m 计数 + 命中块高亮 + 滚动定位
   - **无障碍**：编辑区 aria-label 补齐、状态栏小字对比度提到 WCAG AA
 
-
 - **仓库获得全局唯一 key，导入导出改以 key 为身份（v3）+ 全屏导入导出面板**：
   - **key**：归一化远程地址派生（`git@c:o/r.git`、`https://c/o/r`、
     `ssh://git@ssh.github.com:443/o/r.git`、带端口、带 `.git` 都是同一个

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.20.0",
+  "version": "0.22.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 */
@@ -64,22 +64,20 @@ export function applySnapshotToTopic(topic, snap) {
     syncTaskFromNode(task, node);
   }
 
-  // 边 → blockBy（显式依赖）；闸门边由 blocksFollowing 表达，不写进每条 blockBy
+  // 边 → blockBy（显式依赖）；闸门边由 blocksFollowing 表达，不写进每条 blockBy。
+  // 本地依赖取「现有 ∪ 快照边」的**并集**而不是按边重建：快照可能滞后于外部任务行写
+  // （引擎在途写），按边重建会把外部刚设好的 blockBy 洗掉。依赖是「只能多、不能凭空少」
+  // 的保守口径——解除依赖一律走外部 clear 先落盘，再由 syncTaskDagUpdate 拆边，
+  // 不存在「只删引擎边、不删任务行」的路径，所以并集不会让解除失效。
   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) {
     if (task.deletedAt || task.migratedTo) continue;
-    const keepForeign = normalizeBlockBy(task.blockBy, task.id).filter(
-      (d) => parseDepRef(d)?.kind === 'foreign',
-    );
+    const keep = normalizeBlockBy(task.blockBy, task.id);
+    const keepForeign = keep.filter((d) => parseDepRef(d)?.kind === 'foreign');
+    const keepLocal = keep.filter((d) => parseDepRef(d)?.kind === 'local');
     const incoming = (snap.edges || []).filter((e) => String(e.to) === String(task.id));
     const localDeps = [];
     for (const e of incoming) {
@@ -88,7 +86,7 @@ export function applySnapshotToTopic(topic, snap) {
       const n = Number(e.from);
       if (Number.isFinite(n) && n > 0) localDeps.push(n);
     }
-    task.blockBy = normalizeBlockBy([...localDeps, ...keepForeign], task.id);
+    task.blockBy = normalizeBlockBy([...keepLocal, ...localDeps, ...keepForeign], task.id);
   }
 
   topic.workflowRevision = Number(snap.revision) || 0;
@@ -100,8 +98,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 };
+}