dsh-tree-task-flow 0.3.14 → 0.3.15

package/lib/region.js

@@ -1,23 +1,23 @@
 /**
  * 折叠：把一段执行过程从上下文里收起来，换成一条说明收走了什么的短消息。
  *
- * 规则只有一条，**只看表层，与计划树无关**：
+ * 规则只有一条，**只看表层，与计划树无关**（计划树只用来认出"这次完成的是不是一条需求"）：
  *
- *     从「上一次 `tree_task_done` 之后的第一条 `tree_task_create` 调用」之后，
- *     到本次 `tree_task_done` 之前，中间那一段过程收走。
+ *   - `tree_task_start`：把**上一次折叠成功之后**到它之前的那一段收走；
+ *   - `tree_task_done`：把**上一次 done / start / create 之后**到它之前的那一段收走；
+ *   - 完成的是**需求**时折「全部」：一路退到这条需求开工的那次 `tree_task_create`。
  *
- * 更早没有 `tree_task_done` 时，起点取表层第一条 `tree_task_create`；区间里一次
- * `create` 都没有时，回退到上一次 `tree_task_done` 之后（更早没有 `done` 则是
- * 表层开头）。起点那次调用、以及本次 `done` 的调用与返回，都留在表层上——
- * 那是模型看"计划是什么、下一步干什么"的地方。
+ * 边界调用（`create` / `start` / `done`）本身永远留在表层——那是模型看"计划是什么、
+ * 下一步干什么"的地方。写树的 `tree_task_plan` **不是边界**，它跟普通过程一样落在
+ * 区间里就被收走。
  *
- * 边界只有 `create` 与 `done` 两个：写树的 `tree_task_plan` **不是边界**，
- * 它跟普通过程一样落在区间里就被收走。
+ * **为什么 `start` 认「上次折叠成功」而不是「上一个边界」**：折叠会被挡（用户的话
+ * 还没写进需求），挡掉的那一段如果只按边界算，下一条边界一出现它就永远落在区间外，
+ * 再也收不走。记一个"折到哪儿了"的游标，`start` 时从那里补折，被挡的过程才有第二次机会。
  *
- * **为什么不能把 `create` 并进 `plan`**：起点取的是"上一次 done 之后最早的
- * 那一次开工调用"，而 `plan` 每补一次步骤就调一次；并成一个工具之后，
- * 每一次补步骤都会把起点往后推，`done` 与它之间那段过程就永远收不走。
- * 靠"实参里有没有 `parentId`"去区分，也只是把认错起点的机会交给模型。
+ * **为什么 `done` 认「上一个边界」而不是「上次折叠成功」**：一次 done 收的就是它前面
+ * 这一小节过程，边界本身已经把范围划清了；用游标反而会把更早的、已经由 start 收过的
+ * 内容再卷一遍。
  *
  * 判定表见 `docs/06-折叠范围规则.md`。
  *
@@ -30,9 +30,10 @@
  *
  *     [节点 0] 系统提示词
  *     [用户消息]
- *     [tree_task_create 调用]  [返回：计划已建立 + 这个目标的树]
- *     [tree_task消息：隐藏了 12 条过程上下文。读取：… 写入：…]
- *     [tree_task_done 调用]    [返回：接下来需要进行步骤：「二」(s-4)。]
+ *     [tree_task_create 调用]  [返回：草稿编号]
+ *     [tree_task_start 调用]   [返回：需求详情]
+ *     [tree_task消息：隐藏了 4 条过程上下文。读取：… 写入：…]
+ *     [tree_task_done 调用]    [返回：接下来需要进行任务：「二」(t-4)。]
  *     [当前这一段执行过程]     ← 下一次折叠的对象
  *
  * 这一段过程里还夹着一次 `tree_task_plan` 的调用与返回——它不是边界，
@@ -45,6 +46,8 @@
  */
 
 import { activePath } from "./plan.js";
+import { notesInRange, parseNoteLines, renderNoteLines } from "./notes.js";
+import { REQUIREMENT_STATUS, listActive, listArchived, requirementOf } from "./requirement.js";
 
 /** 本插件放下的消息都带这个身份。 */
 export const PLUGIN = "dsh-tree-task-flow";
@@ -139,7 +142,7 @@ const LEVELS = ["goal", "task", "step"];
  * 边界调用：`tree_task_create` 与 `tree_task_done`。它们的调用与返回不进替换区间，
  * 是折叠的起止点。**`tree_task_plan` 不在其中**——它跟别的过程一样，落在区间里就被收走。
  */
-const BOUNDARY_TOOLS = new Set(["tree_task_create", "tree_task_done"]);
+const BOUNDARY_TOOLS = new Set(["tree_task_create", "tree_task_start", "tree_task_done"]);
 
 /** 注入消息的抬头。 */
 const NOTICE_PREFIX = "tree_task消息：";
@@ -181,6 +184,11 @@ function isDoneCall(event) {
   return toolNamesOf(event).includes("tree_task_done");
 }
 
+/** 这条 assistant 消息里有没有 `tree_task_start`。 */
+function isStartCall(event) {
+  return toolNamesOf(event).includes("tree_task_start");
+}
+
 /** 这条消息是不是真人发的——插件注入的消息 source 是 plugin，不算。 */
 function isHumanMessage(event) {
   return event?.type === "user/message" && event.data?.source?.kind === "user";
@@ -191,6 +199,80 @@ function isPluginNotice(event) {
   return event?.type === "user/message" && isPluginSource(event.data?.source);
 }
 
+/**
+ * `tree_task_requirement` 里算得上「把用户的话写进需求」的那几个动作。
+ *
+ * `archive` / `prerequisites` / `question` 不算：归档与设前置改的是关联，不是需求正文；
+ * `question` 是"我还没看懂"，正好相反——那一段更不该被收走。
+ */
+const REQUIREMENT_WRITE_ACTIONS = new Set(["confirm", "update", "confirmChange"]);
+
+/** 解析一次工具调用的实参；坏 JSON 返回 null。 */
+function argsOf(call) {
+  if (typeof call?.arguments !== "string") return null;
+  try {
+    const value = JSON.parse(call.arguments);
+    return value !== null && typeof value === "object" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 这条 assistant 消息里有没有「写需求」的调用。
+ *
+ * 这是 `docs/09` §7.2 那条前提的判据：区间里最晚的一条用户消息之后，必须有过一次写需求，
+ * 那段过程才可以收。**它挡的是"忘了写"，挡不住"糊弄写"**——写进去的内容有没有真吸收，
+ * 只有模型自己知道。
+ *
+ * @param event - 表层事件。
+ * @returns 有写需求调用为 true。
+ */
+function isRequirementWriteCall(event) {
+  const content = event?.data?.message?.content;
+  if (!Array.isArray(content)) return false;
+  return content.some((part) => {
+    if (part?.type !== "tool-call") return false;
+    if (part.name === "tree_task_create") return true;
+    if (part.name !== "tree_task_requirement") return false;
+    const args = argsOf(part);
+    // 实参解析不出来就**不当**写入：宁可这次不折，也别把没吸收的过程收走。
+    return args !== null && REQUIREMENT_WRITE_ACTIONS.has(String(args.action ?? ""));
+  });
+}
+
+/**
+ * 一次 `tree_task_done` 调用指向的节点 id。
+ *
+ * @param event - 表层事件。
+ * @returns id；不是 done 调用或没给 id 时返回 null。
+ */
+function doneTargetId(event) {
+  const content = event?.data?.message?.content;
+  if (!Array.isArray(content)) return null;
+  const call = content.find((part) => part?.type === "tool-call" && part.name === "tree_task_done");
+  if (call === undefined) return null;
+  const args = argsOf(call);
+  const id = typeof args?.id === "string" ? args.id.trim() : "";
+  return id === "" ? null : id;
+}
+
+/**
+ * 这次 done 是不是在完成一条**需求**（而不是任务或步骤）。
+ *
+ * 需求完成要收走整条：从它开工那一刻起，连同中间那些任务级通告。
+ *
+ * @param event - 表层事件。
+ * @param plan - 计划树（`null` 时一律当作不是需求完成）。
+ * @returns 是需求完成返回它的编号，否则 null。
+ */
+function requirementDoneId(event, plan) {
+  if (plan === null) return null;
+  const id = doneTargetId(event);
+  if (id === null) return null;
+  return requirementOf(plan, id) === null ? null : id;
+}
+
 /** 从一次工具调用的参数里取它指向的文件路径；不是文件类调用就返回 null。 */
 function filePathOf(call) {
   if (typeof call?.arguments !== "string") return null;
@@ -250,20 +332,87 @@ export function summaryMessage(id, text, summary) {
   };
 }
 
+/** 一条消息里的正文文本。 */
+function textOfMessage(event) {
+  const content = event?.data?.content;
+  if (!Array.isArray(content)) return "";
+  return content.map((part) => (typeof part?.text === "string" ? part.text : "")).join("");
+}
+
 /**
- * 汇总消息的正文：这一次收走了多少条过程上下文，以及那一段里读写过哪些文件。
+ * 把所有被收走的通告里带着的笔记捡回来。
+ *
+ * **为什么光按 seq 不够**：通告是"替换"插进来的，位置在原来那一段的开头，seq 却是新的、
+ * 比被它收走的内容都大。于是需求级折叠把起止点往前推时，新区间的起点 seq 反而**大于**
+ * 早先那些笔记的 seq——只按区间筛就会把它们漏掉。所以旧通告里的笔记必须显式捡回来，
+ * 这也是 `renderNoteLines` / `parseNoteLines` 要成对存在的原因。
+ *
+ * @param session - 当前会话。
+ * @param shadowed - 这次被收走的节点 seq。
+ * @returns 笔记数组（`{ key, rev, text }`）。
+ */
+function carriedNotes(session, shadowed) {
+  const rows = [];
+  for (const seq of shadowed) {
+    const event = session.eventAt(seq);
+    if (!isPluginNotice(event)) continue;
+    rows.push(...parseNoteLines(textOfMessage(event)));
+  }
+  return rows;
+}
+
+/**
+ * 合并两组笔记：同名取修订号大的；修订号相同则后出现的算新。
+ *
+ * @param carried - 从旧通告里捡回来的。
+ * @param fresh - 落在本区间里的（seq 命中）。
+ * @returns 去重后的笔记数组。
+ */
+function mergeNotes(carried, fresh) {
+  const byKey = new Map();
+  for (const note of [...carried, ...fresh]) {
+    const previous = byKey.get(note.key);
+    if (previous === undefined || Number(note.rev ?? 0) >= Number(previous.rev ?? 0)) {
+      byKey.set(note.key, note);
+    }
+  }
+  return [...byKey.values()];
+}
+
+/**
+ * 汇总消息的正文：这一次收走了多少条过程上下文、那一段里读写过哪些文件、
+ * 本区间动过的笔记，以及活跃需求的指针。
  *
  * 文件列表是给后面用的——过程收走了，但"这活碰过哪些文件"得留下，
  * 否则模型要从头再找一遍。
  *
+ * 笔记有两个来源：按 seq 落在本区间里的（新写的），以及从被收走的旧通告里捡回来的
+ * （见 `carriedNotes`）。两处加起来，**每条笔记在上下文里仍然只出现一次**。
+ *
+ * 末尾那句话是**指针**：列表不常驻上下文，而折叠正是模型刚丢失上下文的那一刻，
+ * 最容易忘了"这个会话里还有别的事没做"。
+ *
  * @param count - 被这次替换收走的节点条数。
  * @param files - `touchedFiles()` 的结果。
+ * @param notes - 本区间里的笔记。
+ * @param pointer - 活跃需求指针那句话；空串就不输出。
+ * @param requirementId - 需求级折叠时被收走的那条需求编号；普通折叠是 null。
  * @returns 正文文本，可能多行。
  */
-function renderSummary(count, files) {
-  const lines = [`${NOTICE_PREFIX}隐藏了${count}条过程上下文。`];
+function renderSummary(count, files, notes = [], pointer = "", requirementId = null) {
+  const head =
+    requirementId === null
+      ? `${NOTICE_PREFIX}隐藏了${count}条过程上下文。`
+      : `${NOTICE_PREFIX}隐藏了${count}条过程上下文（${requirementId} 从开工到完成）。`;
+  const lines = [head];
   if (files.read.length > 0) lines.push(`读取：${files.read.join("、")}`);
   if (files.write.length > 0) lines.push(`写入：${files.write.join("、")}`);
+  const noteText = renderNoteLines(notes);
+  if (noteText !== "") {
+    lines.push("笔记：");
+    lines.push(noteText);
+  }
+  if (pointer !== "") lines.push(pointer);
   return lines.join("\n");
 }
 
@@ -272,14 +421,33 @@ function renderSummary(count, files) {
  *
  * @param count - 被这次替换收走的节点条数。
  * @param files - `touchedFiles()` 的结果。
+ * @param requirementId - 需求级折叠时被收走的那条需求编号。
  * @returns 一行摘要。
  */
-function summaryLine(count, files) {
+function summaryLine(count, files, requirementId = null) {
   const touched = files.read.length + files.write.length;
-  const base = `隐藏了${count}条过程上下文`;
+  const base =
+    requirementId === null
+      ? `隐藏了${count}条过程上下文`
+      : `隐藏了${count}条过程上下文（${requirementId} 整条归档）`;
   return touched === 0 ? base : `${base} · 涉及 ${touched} 个文件`;
 }
 
+/**
+ * 活跃需求指针：还剩几条、其中几条做完了没归档。
+ *
+ * @param plan - 计划树。
+ * @returns 一句话；没有需求时是空串。
+ */
+function activePointer(plan) {
+  if (plan === null) return "";
+  const active = listActive(plan);
+  if (active.length === 0) return "";
+  const done = active.filter((row) => row.status === REQUIREMENT_STATUS.DONE).length;
+  const tail = done > 0 ? `（其中 ${done} 条已完成未归档）` : "";
+  return `活跃需求 ${active.length} 条${tail}，用 tree_task_status 查看。`;
+}
+
 /**
  * 这条 assistant 消息里有没有**新建目标**的那次 `tree_task_create`。
  *
@@ -299,50 +467,97 @@ function isCreateCall(event) {
 /**
  * 找这一次要折叠的区间。
  *
- * 从末尾往前找最近的一次边界调用，**它必须是 `tree_task_done`**（它就是这次完成的
- * 那一下）；再往前找上一次 `tree_task_done`，起点就是**它之后最早的那次
- * `tree_task_create`**——更早没有 `done` 时，起点是表层第一条 `tree_task_create`。
+ * 终点是末尾最近的一次**会触发折叠的边界调用**：`tree_task_start` 或 `tree_task_done`
+ * （`tree_task_create` 只当起点用，它自己不触发折叠）。
+ *
+ * 起点分三种：
+ *
+ *   - `start`：上一次**折叠成功**的位置（`cursors.foldedAt`），那里没有（或已经被
+ *     后一次折叠收走）就退回上一个边界调用；
+ *   - `done` 完成的是任务 / 步骤：上一个边界调用（`done` / `start` / `create`）；
+ *   - `done` 完成的是需求：一路退到这条需求开工的那次 `create`（「折全部」）。
  *
- * 区间里一次 `create` 都没有时，起点退回上一次 `done` 之后（更早没有 `done`
- * 则是表层第一个节点之后）——那时区间多半会撞上真人消息，于是整段不折，这是安全的那一侧。
+ * 边界调用本身永远留在表层，区间从它的 `tool/result` 之后开始。
  *
  * @param session - 当前会话。
- * @returns `{ from, to, shadowed }`；这一轮不该折时返回 null。
+ * @param plan - 计划树，只用来认出「完成的是不是一条需求」。
+ * @param cursors - `store.readSurfaces()` 的结果，读 `foldedAt`；可以不给。
+ * @returns `{ from, to, shadowed, trigger, requirementId }`；这一轮不该折时返回 null。
  */
-export function foldRange(session) {
+export function foldRange(session, plan = null, cursors = null) {
   const nodes = session.surface?.nodes ?? [];
   if (typeof session.eventAt !== "function" || nodes.length === 0) return null;
 
-  // 终点：最近的一次边界调用，必须是一次 done。
+  // 终点：末尾最近的一次 start / done。两个都没有（比如刚 create 完）就不折。
   let endIdx = -1;
+  let trigger = null;
   for (let index = nodes.length - 1; index >= 0; index -= 1) {
-    if (!isBoundaryCall(session.eventAt(nodes[index]))) continue;
-    // 末尾最近的那次边界调用不是 done：说明还没走到"完成"这一步，这一轮不折。
-    if (!isDoneCall(session.eventAt(nodes[index]))) return null;
-    endIdx = index;
-    break;
+    const event = session.eventAt(nodes[index]);
+    if (isDoneCall(event)) {
+      endIdx = index;
+      trigger = "done";
+      break;
+    }
+    if (isStartCall(event)) {
+      endIdx = index;
+      trigger = "start";
+      break;
+    }
   }
   if (endIdx === -1) return null;
 
-  // 上一次 done 的位置；更早没有 done 时是 -1，起点就从头算。
-  let prevDoneIdx = -1;
+  // 这次 done 是不是在完成一条需求？是的话，起点要一路退到它开工那一刻，
+  // 把中间那些任务级通告也一并收掉（`docs/09` §7.1）。
+  const requirementId =
+    trigger === "done" ? requirementDoneId(session.eventAt(nodes[endIdx]), plan) : null;
+
+  // 默认起点：这次触发之前最近的一次边界调用。
+  let startIdx = -1;
   for (let index = endIdx - 1; index >= 0; index -= 1) {
-    if (isDoneCall(session.eventAt(nodes[index]))) {
-      prevDoneIdx = index;
+    if (isBoundaryCall(session.eventAt(nodes[index]))) {
+      startIdx = index;
       break;
     }
   }
 
-  // 起点：上一次 done 之后最早的那次 create。
-  let startIdx = -1;
-  for (let index = prevDoneIdx + 1; index < endIdx; index += 1) {
-    if (isCreateCall(session.eventAt(nodes[index]))) {
-      startIdx = index;
-      break;
+  // 需求级折叠：退到「上一次需求完成」之后最早的那次 create。
+  if (requirementId !== null) {
+    let anchorIdx = -1;
+    for (let index = endIdx - 1; index >= 0; index -= 1) {
+      if (requirementDoneId(session.eventAt(nodes[index]), plan) !== null) {
+        anchorIdx = index;
+        break;
+      }
+    }
+    startIdx = -1;
+    for (let index = anchorIdx + 1; index < endIdx; index += 1) {
+      if (isCreateCall(session.eventAt(nodes[index]))) {
+        startIdx = index;
+        break;
+      }
+    }
+    if (startIdx === -1) startIdx = anchorIdx;
+  }
+
+  // start 折叠：从**上一次折叠成功**的地方起；一次都没成功过，就退回这次开工的那次
+  // create。这里**不保护中间那些边界调用**——它们都在"上次折叠成功"之后就都属于
+  // 这条需求的过程，留着只是白占上下文（start 的返回里会把需求详情重新给一遍）。
+  if (trigger === "start") {
+    startIdx = -1;
+    const foldedAt = Number(cursors?.foldedAt ?? 0);
+    if (foldedAt > 0) {
+      const at = nodes.indexOf(foldedAt);
+      if (at !== -1) startIdx = at;
+    }
+    if (startIdx === -1) {
+      for (let index = endIdx - 1; index >= 0; index -= 1) {
+        if (isCreateCall(session.eventAt(nodes[index]))) {
+          startIdx = index;
+          break;
+        }
+      }
     }
   }
-  // 区间里没有 create：退回上一次 done 之后（更早没有 done 就是表层开头）。
-  if (startIdx === -1) startIdx = prevDoneIdx;
 
   // 区间从起点调用的 `tool/result` 之后开始；找不到起点（-1）就退回表层第一个节点之后
   // （节点 0 是系统提示词，受 DSH 的重写保护，不能进替换区间）。
@@ -352,7 +567,13 @@ export function foldRange(session) {
   let from = startIdx === -1 ? 1 : startIdx + 1;
   while (from < endIdx) {
     const event = session.eventAt(nodes[from]);
-    if (event?.type === "tool/result" || isPluginNotice(event)) {
+    if (event?.type === "tool/result") {
+      from += 1;
+      continue;
+    }
+    // 上一次折叠落下的通告：普通折叠要跳过它（它已经是收过的结果，再收一次会一轮轮空折下去）；
+    // **需求级折叠反过来要收它**——那些任务级通告正是这条需求的历史，留着就是层层堆叠。
+    if (requirementId === null && isPluginNotice(event)) {
       from += 1;
       continue;
     }
@@ -361,7 +582,81 @@ export function foldRange(session) {
   const to = endIdx - 1;
   if (from > to) return null;
 
-  return { from, to, shadowed: nodes.slice(from, to + 1) };
+  // 区间里只剩上一次折叠留下的通告（和那几次调用的 tool/result）时，什么都不做。
+  //
+  // 需求级折叠**故意不跳过通告**（那些任务级通告是这条需求的历史，第一次折全部时要一起收
+  // 走）。可是折完之后区间里就只剩刚插进去的那条通告了，`tree_task_done` 的调用还在表层
+  // 上，终点于是每次都指向它——再折一次等于拿一条新通告换掉一条旧通告，**每个 step 都插
+  // 一条**。2026-11-07 现场：R8 完成后连着插了几十条「隐藏了1条过程上下文」。
+  let hasContent = false;
+  for (let index = from; index <= to; index += 1) {
+    const event = session.eventAt(nodes[index]);
+    if (event?.type === "tool/result" || isPluginNotice(event)) continue;
+    hasContent = true;
+    break;
+  }
+  if (!hasContent) return null;
+
+  return {
+    from,
+    to,
+    endIdx,
+    requirementId,
+    trigger,
+    shadowed: nodes.slice(from, to + 1),
+  };
+}
+
+/**
+ * 这一次折叠会不会被「用户的话还没写进需求」挡住。
+ *
+ * 判据（`docs/09` §7.2）：区间里**最晚的那条用户消息之后**必须有过一次写需求。
+ * 一次写需求盖住它之前的所有用户消息，所以只比最晚那一条就够。
+ *
+ * @param session - 当前会话。
+ * @param range - `foldRange()` 的结果。
+ * @returns `{ seq }`（被挡住时）或 null。
+ */
+export function foldBlockReason(session, range) {
+  const nodes = session.surface.nodes;
+
+  // 从后往前找区间里最晚的一条真人消息。
+  let humanSeq = null;
+  for (let index = range.to; index >= range.from; index -= 1) {
+    if (isHumanMessage(session.eventAt(nodes[index]))) {
+      humanSeq = nodes[index];
+      break;
+    }
+  }
+  if (humanSeq === null) return null;
+
+  for (let index = range.from; index < range.endIdx; index += 1) {
+    if (nodes[index] <= humanSeq) continue;
+    if (isRequirementWriteCall(session.eventAt(nodes[index]))) return null;
+  }
+  return { seq: humanSeq };
+}
+
+/**
+ * 给调用方看的一眼预览：这一次会不会折、被挡的话是哪一条用户消息。
+ *
+ * `tree_task_done` 用它把「这段收不走、先去写需求」直接说在返回里——那一刻模型刚完成
+ * 一个节点，最容易顺手把用户的话落进需求。
+ *
+ * @param session - 当前会话。
+ * @param plan - 计划树。
+ * @param cursors - 游标（读 `foldedAt`）；可以不给。
+ * @returns `{ folds, blocked, requirementId, trigger }`。
+ */
+export function previewFold(session, plan, cursors = null) {
+  const range = foldRange(session, plan, cursors);
+  if (range === null) return { folds: false, blocked: null, requirementId: null, trigger: null };
+  return {
+    folds: true,
+    blocked: foldBlockReason(session, range),
+    requirementId: range.requirementId,
+    trigger: range.trigger,
+  };
 }
 
 /**
@@ -371,30 +666,51 @@ export function foldRange(session) {
  *
  * @param ctx - 挂载本行的 Cordis 上下文，只用来记日志。
  * @param session - 当前会话。
+ * @param plan - 计划树，用来认出「这次完成的是不是一条需求」并拼出活跃需求指针。
+ * @param store - 状态读写（笔记要跟着通告走）。
+ * @param cursors - 游标；给了就把这次折叠成功的位置记进 `foldedAt`。
  * @returns 是否真的替换了内容。
  */
-export function foldOnce(ctx, session) {
-  const range = foldRange(session);
+export function foldOnce(ctx, session, plan = null, store = null, cursors = null) {
+  const range = foldRange(session, plan, cursors);
   if (range === null) return false;
 
-  // 中间夹着真人消息：整段不折。往前折丢了需求，往后折丢了回应。
-  if (range.shadowed.some((seq) => isHumanMessage(session.eventAt(seq)))) return false;
+  // 用户的话还没写进需求：整段不折（`docs/09` §7.2）。不说出来，模型就永远不知道该先写需求。
+  if (foldBlockReason(session, range) !== null) return false;
 
   const nodes = session.surface.nodes;
   const files = touchedFiles(session, range.shadowed);
+  const sessionId = session.id;
+  const fresh =
+    store !== null && sessionId !== undefined
+      ? notesInRange(store.readNotes(sessionId), nodes[range.from], nodes[range.to])
+      : [];
+  const notes = mergeNotes(carriedNotes(session, range.shadowed), fresh);
   try {
     session.append(
       "user/message",
       summaryMessage(
         foldId(),
-        renderSummary(range.shadowed.length, files),
-        summaryLine(range.shadowed.length, files),
+        renderSummary(
+          range.shadowed.length,
+          files,
+          notes,
+          activePointer(plan),
+          range.requirementId,
+        ),
+        summaryLine(range.shadowed.length, files, range.requirementId),
       ),
       {
         surfaceOp: { op: "replace", startSeq: nodes[range.from], endSeq: nodes[range.to] },
         sourceEventSeqs: range.shadowed,
       },
     );
+    // 这次折叠成功的位置 = 刚插进去的那条通告。下一次 start 就从它之后补折
+    // （被挡过的那几段因此还有机会收走）。通告落在原区间起点那个下标上。
+    if (cursors !== null && typeof cursors === "object") {
+      const notice = session.surface?.nodes?.[range.from];
+      if (notice !== undefined) cursors.foldedAt = notice;
+    }
     return true;
   } catch (error) {
     // 注入失败不能拖垮会话，原区间原样留着，下一轮还有机会。
@@ -466,11 +782,12 @@ export function registerRegion(ctx, { store }) {
     const plan = store.readPlan(sessionId);
     if (plan === null) return decision;
 
-    // 折叠只看表层：边界调用之间那一段过程。
-    let changed = foldOnce(ctx, session);
+    // 折叠只看表层：边界调用之间那一段过程。计划树只用来认出「这次完成的是不是一条需求」，
+    // 需求完成时起点要一路退到它开工那一刻。游标里的 `foldedAt` 是 start 折叠的起点。
+    const cursors = store.readSurfaces(sessionId);
+    let changed = foldOnce(ctx, session, plan, store, cursors);
 
     // 三层游标照旧维护，它是给界面看的，不参与上面那次判断。
-    const cursors = store.readSurfaces(sessionId);
     if (syncCursors(session, cursors, activePath(plan))) changed = true;
 
     if (changed) {