dsh-worktree-groups 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +168 -2
  3. package/cordis.patch.yml +17 -0
  4. package/icon.svg +20 -0
  5. package/lib/activity.d.ts +78 -0
  6. package/lib/activity.d.ts.map +1 -0
  7. package/lib/activity.js +241 -0
  8. package/lib/activity.js.map +1 -0
  9. package/lib/client.d.ts +78 -0
  10. package/lib/client.d.ts.map +1 -0
  11. package/lib/client.js +4280 -0
  12. package/lib/git.d.ts +109 -0
  13. package/lib/git.d.ts.map +1 -0
  14. package/lib/git.js +317 -0
  15. package/lib/git.js.map +1 -0
  16. package/lib/icons.d.ts +148 -0
  17. package/lib/icons.d.ts.map +1 -0
  18. package/lib/icons.js +144 -0
  19. package/lib/icons.js.map +1 -0
  20. package/lib/index.d.ts +32 -0
  21. package/lib/index.d.ts.map +1 -0
  22. package/lib/index.js +47 -0
  23. package/lib/index.js.map +1 -0
  24. package/lib/ledger.d.ts +97 -0
  25. package/lib/ledger.d.ts.map +1 -0
  26. package/lib/ledger.js +276 -0
  27. package/lib/ledger.js.map +1 -0
  28. package/lib/live-merge.d.ts +44 -0
  29. package/lib/live-merge.d.ts.map +1 -0
  30. package/lib/live-merge.js +227 -0
  31. package/lib/live-merge.js.map +1 -0
  32. package/lib/live-state.d.ts +158 -0
  33. package/lib/live-state.d.ts.map +1 -0
  34. package/lib/live-state.js +281 -0
  35. package/lib/live-state.js.map +1 -0
  36. package/lib/locales.d.ts +71 -0
  37. package/lib/locales.d.ts.map +1 -0
  38. package/lib/locales.js +199 -0
  39. package/lib/locales.js.map +1 -0
  40. package/lib/projects.d.ts +88 -0
  41. package/lib/projects.d.ts.map +1 -0
  42. package/lib/projects.js +418 -0
  43. package/lib/projects.js.map +1 -0
  44. package/lib/routes.d.ts +376 -0
  45. package/lib/routes.d.ts.map +1 -0
  46. package/lib/routes.js +1875 -0
  47. package/lib/routes.js.map +1 -0
  48. package/lib/row-memo.d.ts +34 -0
  49. package/lib/row-memo.d.ts.map +1 -0
  50. package/lib/row-memo.js +46 -0
  51. package/lib/row-memo.js.map +1 -0
  52. package/lib/sidebar.d.ts +126 -0
  53. package/lib/sidebar.d.ts.map +1 -0
  54. package/lib/tree-model.d.ts +1226 -0
  55. package/lib/tree-model.d.ts.map +1 -0
  56. package/lib/tree-model.js +2143 -0
  57. package/lib/tree-model.js.map +1 -0
  58. package/lib/types.d.ts +98 -0
  59. package/lib/types.d.ts.map +1 -0
  60. package/lib/types.js +8 -0
  61. package/lib/types.js.map +1 -0
  62. package/locale/en.json +6 -0
  63. package/locale/zh.json +6 -0
  64. package/package.json +88 -4
@@ -0,0 +1,2143 @@
1
+ /**
2
+ * 侧栏树推导(客户端纯逻辑)。
3
+ *
4
+ * 本文件是**纯逻辑**:不 import react、不 import 任何 `@deepseek-ai/*` 包、不做 IO,
5
+ * 因此可以被 `node --test` 直接覆盖。组件(`src/sidebar.tsx`)只负责把
6
+ * {@link RenderRow} 画出来,不做任何推导。
7
+ *
8
+ * 与原生侧栏(`@deepseek-ai/dsh-client-ui-workspace`)的一致性:
9
+ * - 5 条截断:`COLLAPSED_SESSION_LIMIT = 5`,只对「非 blank 会话」计名额,
10
+ * `hiddenCount = 总数 - 可见数`(原生 `collapsedSessionRows` 语义)。
11
+ * - 展开态缺省视为展开(原生默认全展开)。
12
+ * - `blank === true` 的会话只显示当前那一条(原生 `sessionVisible` 语义)。
13
+ * - 归档会话哪里都不出现(原生 `sessionVisible` 语义)。
14
+ * - **子代理会话(`origin === 'subagent'`)不产生任何会话行**(原生 `sessionVisible`
15
+ * 的第一项就是 `session.origin !== "subagent"`);父行只保留「N 个子代理运行中」
16
+ * 计数胶囊,其 n 是**运行中的子代理后代数(所有层级)**(原生 `runningSubagentCount`)。
17
+ * 且 **n > 0 时父行状态点也是「运行中」**(需求 A,2026-09-21)—— 对齐原生
18
+ * `sessionStatuses`:只有子代理在跑时主状态点同样是 ongoing,而不是灰 idle。
19
+ * - `sessionCount` / `runningCount` / `pendingCount` 只统计顶层会话(= 非子代理),
20
+ * 子代理不计入(原生 `sessionCount` 指顶层会话数)。⚠️ `runningCount` 的取值口径
21
+ * **不含**子代理聚合(用户裁决 Q1:渲染层无消费者,不扩大范围)—— 它与 `session.running`
22
+ * 一致,而**行上的 `running` 字段**才含聚合。
23
+ * - 排序:`updatedAt` 降序,`updatedAt` 相同按 `sessionId` 升序(原生 `byRecency`),
24
+ * 保证同样的输入永远推出同样的行序列。
25
+ * - **顶部区(T11,2026-09-22 用户终裁;取代 T5/T9 的 D3a/D3c/D4 全部安排)**:每个容器内,
26
+ * **只有「正在运行」的会话**(自身 `running` **或** 任意层级有运行中的子代理,即既有聚合
27
+ * `running` 口径)进入**顶部区** —— 它们固定在所属容器**最前**、位于 5 条截断**之前**,
28
+ * 并且**不可拖动**(拖它们无效果;回弹到顶部是预期行为)。顶部区内部按 `updatedAt` 降序。
29
+ * 此外,**尚未落表的新会话**仍由渲染期提升(D2 的唯一例外),见 {@link topZoneSessionKeys}。
30
+ * ⚠️ **已结束的会话一律不再固定置顶**:「刚结束保留」(`recentlyFinished`)与「当前打开的
31
+ * 会话置顶」(`isCurrent`)两个机制已按用户终裁**删除**。已结束会话(含用户正在查看的
32
+ * 旧会话、含刚刚跑完的会话)位置**完全由持久拖拽顺序决定**,并且**必须可以正常拖动**
33
+ * (拖到哪就留在哪,不回弹)。顶部区**不写** `localStorage`(唯一写入例外是 D2 的新会话
34
+ * 插入固化表,见 {@link effectiveOrder} 与 {@link planNewSessionInserts})。
35
+ * - **手动排序(D10,2026-09-21 用户决策变更)**:三层(项目 / worktree / 会话)都可在
36
+ * 浏览器里拖拽排序,结果存 `localStorage` 并以 {@link ManualOrder} 叠加在默认顺序之上;
37
+ * `manual !== true` 时**完全不生效**(零回归)。见 {@link applyManualOrder}。
38
+ *
39
+ * 契约见 `docs/INTERFACES.md` §2.2。
40
+ */
41
+ /**
42
+ * 每个「会话容器」(worktree / history / project / 未分组)折叠时可见的**非 blank**
43
+ * 会话上限。
44
+ *
45
+ * ⚠️ **T13(2026-09-22 用户终裁):本插件**没有**「当前会话保底进前 limit 条」这条规则了。**
46
+ * 原生 `collapsedSessionRows` 把「当前会话看不见」交给「自动全部展开」处理;本插件曾以
47
+ * `truncateSessions` 的 `promote` 分支实现「保底」,但它在 T11 删除 `isCurrent` 置顶后
48
+ * 变成**可达**,并让「把当前会话往下拖」出现**视觉零位移**(与用户投诉的首要缺陷同形)。
49
+ * 用户裁决**删除**该保底:**拖拽顺序完全优先**,当前会话若被截断到不可见,就是看不见。
50
+ * 因此 `truncateSessions` 不再有 `currentSessionId` 参数(见那里的 JSDoc)。
51
+ */
52
+ export const COLLAPSED_SESSION_LIMIT = 5;
53
+ /**
54
+ * 「最近」分区旧的展示上限(2026-10-21 WSR6 / AC5)。
55
+ *
56
+ * ⚠️ **2026-11-14 PX4 起不再参与截断**:「最近」默认 {@link COLLAPSED_SESSION_LIMIT} 条,按
57
+ * {@link visibleSessionLimit} 渐进展开、无上限。常量仅为兼容既有导出保留。
58
+ */
59
+ export const RECENT_SESSION_LIMIT = 100;
60
+ /**
61
+ * 展开层级 L 对应的可见上限(2026-11-14 PX1/PX-AC2):`5 + 5·L(L+1)/2` ⇒ 5、10、20、35、55…
62
+ * (第 k 次点击多展开 `5·k` 条)。非法 / 负层级按 0。
63
+ */
64
+ export function visibleSessionLimit(level) {
65
+ const l = Number.isFinite(level) && level > 0 ? Math.floor(level) : 0;
66
+ return COLLAPSED_SESSION_LIMIT + (COLLAPSED_SESSION_LIMIT * l * (l + 1)) / 2;
67
+ }
68
+ /** 下一次点击「展开更多」会多显示的条数:`min(5·(L+1), 剩余)`(PX-AC3)。 */
69
+ export function nextExpandCount(level, remaining) {
70
+ const l = Number.isFinite(level) && level > 0 ? Math.floor(level) : 0;
71
+ const left = Number.isFinite(remaining) && remaining > 0 ? Math.floor(remaining) : 0;
72
+ return Math.min(COLLAPSED_SESSION_LIMIT * (l + 1), left);
73
+ }
74
+ /** 读取某容器的展开层级(缺失 / 非法 ⇒ 0)。 */
75
+ function expandLevelOf(levels, key) {
76
+ const value = levels?.[key];
77
+ return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
78
+ }
79
+ /**
80
+ * 折叠某一行时需要清零展开层级的会话容器 key(2026-11-14 PX3/PX-AC4)。
81
+ *
82
+ * - 项目行 `p:<projectKey>` ⇒ 自身(非 git 平铺 / 未分组容器与行同 key)+ `h:<projectKey>` +
83
+ * 其全部 worktree 容器 `w:<path>`;
84
+ * - 其余(worktree 行 `w:<path>`、history 行 `h:…`、「最近」`r:__recent__`)⇒ 仅自身
85
+ * (这些行的 key 与其会话容器 key 同源,见 `containersOfProject`)。
86
+ */
87
+ export function containerKeysUnder(projects, rowKey) {
88
+ if (!rowKey.startsWith('p:'))
89
+ return [rowKey];
90
+ const projectKey = rowKey.slice('p:'.length);
91
+ const keys = new Set([rowKey, `h:${projectKey}`]);
92
+ const project = projects.find((candidate) => candidate.key === projectKey);
93
+ for (const node of project?.worktrees ?? [])
94
+ keys.add(`w:${node.path}`);
95
+ return [...keys];
96
+ }
97
+ /**
98
+ * 「最近」分区的合成键(对应行 `key = 'r:' + RECENT_KEY`)。
99
+ */
100
+ export const RECENT_KEY = '__recent__';
101
+ /**
102
+ * 「未分组」容器的合成项目键。
103
+ *
104
+ * 冻结的 {@link RenderRow} 联合类型里没有 `ungrouped` 行种类,所以未分组容器复用
105
+ * `project` 行表达(`key = 'p:' + UNGROUPED_KEY`,`isGit: false`)。渲染层可用它把
106
+ * 未分组行与真实项目行区分开。
107
+ */
108
+ export const UNGROUPED_KEY = '__ungrouped__';
109
+ /** 会话 id 的宿主前缀(`session-<uuid>`)。仅用于**比较**父 id,输出仍用原 id。 */
110
+ const SESSION_ID_PREFIX = 'session-';
111
+ /**
112
+ * 按手动顺序**稳定重排**:置顶项最前,然后列表内的项按索引,列表外的项按默认顺序追加到末尾。
113
+ *
114
+ * 语义(四条,对应 PRD D10 的验收):
115
+ * 1. **置顶**(可选第 4 参):`pinnedKeys` 里出现的项按该数组顺序排在最**前** —— 且是
116
+ * 「先摘出来再拼」,因此它**不受 `order` 影响**(哪怕它在 `order` 里排在最后);
117
+ * 2. **列表内**:`order` 里出现的项,按 `order` 的索引升序排在其后;
118
+ * 3. **列表外**:`items` 里没出现在 `order` 的项(新建的会话 / worktree / 项目)保持
119
+ * 它们**传入时的相对顺序**,整体追加在列表内项之后 —— 因此「默认顺序」由调用方在
120
+ * 传入前排好(会话走 `updatedAt` 降序、worktree 走宿主顺序、项目走宿主顺序);
121
+ * 4. **已消失的项**:`order` / `pinnedKeys` 里在 `items` 中找不到的 id **直接忽略** ——
122
+ * 不产生空洞、不产生 `undefined`,输出长度恒等于输入长度。
123
+ *
124
+ * 纯函数:**不修改入参数组**(返回新数组;元素引用不变)。
125
+ *
126
+ * `order` 为 `undefined` / 空数组**且** `pinnedKeys` 为空时,原样返回输入的一份浅拷贝
127
+ * (顺序完全不变)—— 这是既有调用方(`effectiveOrder`、项目层、worktree 层)零回归的保证。
128
+ *
129
+ * @param items 默认顺序的项(**不被修改**)。
130
+ * @param order 手动顺序的 key 列表;`undefined` / 空 ⇒ 不按它重排。
131
+ * @param keyOf 取项的比较键。
132
+ * @param pinnedKeys 需要**置顶**的 key(按数组顺序排在最前)。缺省 / 空 ⇒ 与不传逐字一致。
133
+ * 调用方只应在**渲染路径**上传它:置顶是纯运行时推导,**绝不写进持久顺序**(见
134
+ * {@link effectiveOrder} 刻意不传)。T11 后**唯一**的置顶来源是
135
+ * {@link topZoneSessionKeys}(正在运行 / 尚未落表的新会话)。
136
+ * @returns 重排后的新数组。
137
+ *
138
+ * @example
139
+ * applyManualOrder([a, b, c], ['c', 'a'], (x) => x.id)
140
+ * // ⇒ [c, a, b] (b 不在 order 里 ⇒ 保持默认顺序追加到末尾)
141
+ *
142
+ * @example
143
+ * applyManualOrder([a, b], ['gone', 'b'], (x) => x.id)
144
+ * // ⇒ [b, a] ('gone' 在 items 里不存在 ⇒ 忽略,不产生空洞)
145
+ *
146
+ * @example
147
+ * applyManualOrder([a, b, c], ['a', 'b'], (x) => x.id, ['c'])
148
+ * // ⇒ [c, a, b] (c 置顶,其余仍按 order;a/b 的 index 已在置顶阶段被占,不会重复搬运)
149
+ */
150
+ export function applyManualOrder(items, order, keyOf, pinnedKeys) {
151
+ const copy = [...items];
152
+ const pinned = pinnedKeys === undefined ? [] : pinnedKeys;
153
+ if (pinned.length === 0 && (order === undefined || order.length === 0))
154
+ return copy;
155
+ // 索引表:key → items 里的下标。**同一个 key 出现多次时只认第一个**(与
156
+ // `reconciledSessionOrder` 的去重口径一致),避免一个 key 被搬两次。
157
+ const indexOf = new Map();
158
+ for (let i = 0; i < copy.length; i += 1) {
159
+ const key = keyOf(copy[i]);
160
+ if (!indexOf.has(key))
161
+ indexOf.set(key, i);
162
+ }
163
+ const ordered = [];
164
+ const taken = new Set();
165
+ // 置顶项**先于**手动顺序取出:`taken` 共用 ⇒ 同一个 key 不会被搬两次。
166
+ // 不在 `items` 里的置顶 key(不可见的当前会话:子代理 / 归档)自然被忽略。
167
+ for (const key of pinned) {
168
+ const index = indexOf.get(key);
169
+ if (index === undefined || taken.has(index))
170
+ continue;
171
+ taken.add(index);
172
+ ordered.push(copy[index]);
173
+ }
174
+ for (const key of order ?? []) {
175
+ const index = indexOf.get(key);
176
+ // 已消失的项(index === undefined)与重复 key(taken 里已有)都跳过。
177
+ if (index === undefined || taken.has(index))
178
+ continue;
179
+ taken.add(index);
180
+ ordered.push(copy[index]);
181
+ }
182
+ // 列表外的项:保持传入时的相对顺序,追加到末尾。
183
+ for (let i = 0; i < copy.length; i += 1) {
184
+ if (!taken.has(i))
185
+ ordered.push(copy[i]);
186
+ }
187
+ return ordered;
188
+ }
189
+ /**
190
+ * 取某个项目下的 worktree 手动顺序(`manual` 为假时恒 `undefined`)。
191
+ *
192
+ * 抽出来是为了让 `buildRows` 的三个排序点读同一份判定,不可能出现「项目层应用了、
193
+ * worktree 层忘了」这类分叉。
194
+ */
195
+ function worktreeOrderOf(order, projectKey) {
196
+ if (order === undefined || order.manual !== true)
197
+ return undefined;
198
+ return order.worktrees?.[projectKey];
199
+ }
200
+ /** 取某个容器下的会话手动顺序(`manual` 为假时恒 `undefined`)。 */
201
+ function sessionOrderOf(order, containerKey) {
202
+ if (order === undefined || order.manual !== true)
203
+ return undefined;
204
+ return order.sessions?.[containerKey];
205
+ }
206
+ /**
207
+ * 顶部区内部多个会话的相对顺序:**`updatedAt` 降序**。
208
+ *
209
+ * ## 选择理由
210
+ *
211
+ * 1. **确定性**:`updatedAt` 是唯一的稳定时间维度,且 `byRecency` 已有 `sessionId`
212
+ * 升序 tiebreak ⇒ 同样输入永远推出同样行序(与全模块「同样输入同样输出」一致)。
213
+ * 2. **与既有语义同向**:容器内默认排序、搜索排序都用它;顶部区若另立维度会让
214
+ * 「同一批会话」在顶部区内外的相对顺序规则不一致,用户拖拽后的预期更难建立。
215
+ * 3. **对「正在运行的会话」仍不理想,但已被「先于截断」兜住**:T4 已确证 `updatedAt`
216
+ * **不随 agent / subagent 活动推进**(宿主 `lastPromptAt` 只在 `user/message` 推进),
217
+ * 所以一个「长期无 prompt、只有 subagent 在跑」的会话 `updatedAt` 可能很旧 ——
218
+ * 它仍会**进入顶部区**(保证可见),只是在顶部区内部排得靠后。这是可接受的:
219
+ * 顶部区的**首要语义是「不被 5 条截断吞掉」**,区内精排是次要诉求。
220
+ *
221
+ * @param sessions 候选会话(**不被修改**)。
222
+ * @returns 按 `updatedAt` 降序(`sessionId` 升序 tiebreak)排列的**新数组**。
223
+ */
224
+ function sortTopZone(sessions) {
225
+ return sortedByRecency(sessions);
226
+ }
227
+ /**
228
+ * **「正在运行」判据的唯一来源**:这条会话是否在跑(⇒ 属于顶部区、且**不可拖动**)。
229
+ *
230
+ * ⚠️ 2026-10-22 起「不可拖动」的**唯一**判据是 {@link isSessionDragLocked}(= 本函数 ∪
231
+ * 当前空白会话占位行);本函数仍是其中「运行中」这一半的唯一实现,`topZoneSessionKeys`
232
+ * 与 `isSessionDragLocked` 都调它,不得各写一份。
233
+ *
234
+ * ## 为什么必须导出成共享函数
235
+ *
236
+ * 用户终裁「正在运行的会话固定在顶部,**拖不动**」把两件事绑在一起:
237
+ * ① 渲染层把它排到容器最前({@link topZoneSessionKeys});② 渲染层**不给它装拖拽接线**
238
+ * (`sidebar.tsx` 的 `dragHandlersFor` 调用点)。这两处若各写一遍判据,迟早分叉 ——
239
+ * 例如「行显示运行中圆点但判据只认裸 `running`」⇒ 用户看到运行中的行却能拖走它。
240
+ * 因此判据只有这一处实现,两侧都调它。
241
+ *
242
+ * ## 口径(与既有聚合 `running` 一致)
243
+ *
244
+ * 满足**任一**即算运行中:
245
+ * - `session.running === true` —— 渲染行的 `running` 是**聚合**口径
246
+ * (`session.running || runningSubagentCount > 0`,见 {@link toSessionRow}),因此它
247
+ * 本身就覆盖了「自身在跑」与「只有子代理在跑」两种情形;
248
+ * - id ∈ `topZone.runningSessionIds` —— 调用方(`sidebar.tsx`)从状态机投影的**显式**
249
+ * 聚合清单。它覆盖「状态机已知道在跑、但当前这次渲染的行数据还没反映出来」的窄窗口。
250
+ *
251
+ * ⚠️ **新会话不算「运行中」**:`newSessionIds` 命中的会话仍可拖动。它「在容器最前」由
252
+ * D2 的落表(持久顺序)承载,用户把它拖走后不会被渲染期搬回(见
253
+ * {@link TopZoneInput.writtenNewSessionIds})。用户终裁只说了「正在运行的」拖不动。
254
+ *
255
+ * @param session 会话(渲染行或 `SessionRowLike` 皆可,只要有 id 与 running)。
256
+ * @param topZone 运行时顶部区输入;缺省 ⇒ 只认 `session.running`。
257
+ * @returns 是否属于「运行中、不可拖动」这一类。
258
+ */
259
+ export function isTopZoneRunningSession(session, topZone) {
260
+ if (session.running === true)
261
+ return true;
262
+ if (topZone === undefined || topZone === null || typeof topZone !== 'object')
263
+ return false;
264
+ if (typeof session.sessionId !== 'string' || session.sessionId === '')
265
+ return false;
266
+ const ids = topZone.runningSessionIds;
267
+ if (!Array.isArray(ids))
268
+ return false;
269
+ const key = normalizeSessionId(session.sessionId);
270
+ for (const id of ids) {
271
+ if (typeof id === 'string' && normalizeSessionId(id) === key)
272
+ return true;
273
+ }
274
+ return false;
275
+ }
276
+ /**
277
+ * 是否是**当前打开的空白会话**(侧栏里的「新会话」占位行)。
278
+ *
279
+ * 宿主原生把这条行当占位符:**恒在本组最前**且**不可起拖**:
280
+ * - `dsh-client-ui-workspace/lib/client.js:983`:`sectionMembers` 先把所有 `blank` 成员挑出来放最前;
281
+ * - `:952`:`pinCurrentBlank` 再把**当前** blank 提到该账户首位;
282
+ * - `:2261`:`draggable = drag !== void 0 && !row.blank && !row.archived`。
283
+ *
284
+ * 本插件为什么需要它(2026-10-22 DR4,缺陷:复用空白会话后「新会话」掉到最下面):
285
+ * 同位置「新建会话」复用同目录的空白会话(保留草稿)之后,它不再满足
286
+ * {@link observeTopZone} 的「新会话」判据(进程内首次观测且晚于启动水位 / blank→非 blank),
287
+ * 渲染时只能按 `updatedAt`(很旧)或手动顺序表(表外 ⇒ 追加末尾)落到容器最后。
288
+ *
289
+ * ⚠️ 与 T11 终裁不冲突:终裁删除的是「**普通**当前会话置顶」(`isCurrent` 不参与顶部区),
290
+ * 本判据只认 `blank === true` 的占位行。
291
+ *
292
+ * @param session 会话(渲染行或 `SessionRowLike` 皆可,只要有 id / blank)。
293
+ * @param currentSessionId 当前会话 id(`isCurrent` 字段缺席时的第二来源;两者都做前缀归一化)。
294
+ * @returns 是否属于「当前空白会话」。
295
+ */
296
+ export function isCurrentBlankSession(session, currentSessionId) {
297
+ if (session.blank !== true)
298
+ return false;
299
+ if (session.isCurrent === true)
300
+ return true;
301
+ if (typeof currentSessionId !== 'string' || currentSessionId === '')
302
+ return false;
303
+ return isCurrentSession(session.sessionId, currentSessionId);
304
+ }
305
+ /**
306
+ * 会话行**是否禁止拖拽**的唯一判据(T11 + 2026-10-22 DR5)。
307
+ *
308
+ * = ① 当前空白会话占位行({@link isCurrentBlankSession})∪ ② 正在运行
309
+ * ({@link isTopZoneRunningSession},含任意层级运行中的子代理)。
310
+ *
311
+ * 为什么占位行必须锁拖:它被渲染期固定在容器最前(见 `emitContainer`),若还允许起拖,
312
+ * 用户拖完只会看到弹回 —— 与 T9 缺陷 1 同一类「渲染期回滚用户操作」;宿主原生同样不给
313
+ * blank 行起拖(`dsh-client-ui-workspace/lib/client.js:2261`)。占位行**仍接受落点**:
314
+ * `dragHandlersFor` 的第三参只关掉「自己起拖」,别的会话照样能拖到它上方/下方。
315
+ *
316
+ * ⚠️ **尚未落表的新会话(`newSessionIds`)不在此列**:它由 D2 落表承载持久顺序,用户
317
+ * 拖走后不得被渲染期搬回(见 {@link TopZoneInput.writtenNewSessionIds})。
318
+ *
319
+ * @param session 会话行(`RenderRow` 或 `SessionRowLike` 皆可)。
320
+ * @param topZone 运行时顶部区输入;缺省 ⇒ 只认裸 `running` 与占位行。
321
+ * @returns 是否禁止起拖。
322
+ */
323
+ export function isSessionDragLocked(session, topZone) {
324
+ if (isCurrentBlankSession(session))
325
+ return true;
326
+ return isTopZoneRunningSession(session, topZone);
327
+ }
328
+ /**
329
+ * 顶部区判据(T11,2026-09-22 用户终裁)—— 计算某容器内应置顶的会话 key。
330
+ *
331
+ * ## 判据(两类)
332
+ *
333
+ * | # | 类别 | 判据 | 持久化 |
334
+ * |---|---|---|---|
335
+ * | a | **正在运行** | id ∈ `runningSessionIds`(口径含任意层级运行中的子代理),或该会话裸 `running === true` | 否(运行时) |
336
+ * | b | **新会话** | id ∈ `newSessionIds` **且** 不在 `writtenNewSessionIds` 台账里(已落表 ⇒ 持久顺序已把它放在最前 ⇒ 无需再提升) | 由调用方单独落表(D2) |
337
+ *
338
+ * ## 用户终裁(2026-09-22,第二轮真人 GUI 复验)—— 本函数相对 T5/T9 的**语义收窄**
339
+ *
340
+ * 用户观察到侧栏三段:`刚结束运行的会话 / 当前正在运行的会话 / 其余会话`,前两段**拖不动、
341
+ * 会回弹**,据此终裁:
342
+ *
343
+ * > **正在运行的会话固定在顶部,拖不动,只要是结束了的会话就不再固定置顶了。**
344
+ *
345
+ * 因此本函数**删除**了此前的两类成员:
346
+ * - **「刚结束保留」(`recentlyFinishedSessionIds`)**:已删除。已结束的会话不再固定置顶,
347
+ * 位置完全由持久拖拽顺序决定 ⇒ 它必须可正常拖动(不再被渲染期搬回顶部)。
348
+ * - **「当前打开的会话置顶」(`isCurrent`)**:已删除。用户明确选择**不保留置顶例外** ——
349
+ * 当前会话若不处于运行中,就不置顶,留在其持久顺序位置。
350
+ *
351
+ * 同时删除的还有「拖动释放」机制(`releasedContainerKeys` / `releaseTopZoneContainer` /
352
+ * `isTopZoneReleasingDrag`):它存在的唯一目的是「拖动容器 ⇒ 清除该容器的刚结束保留」,
353
+ * 而「刚结束保留」本身已删除 ⇒ 释放机制失去全部语义,属死代码。
354
+ *
355
+ * ## 为什么「新会话」不能靠「不在固化表里」判定
356
+ *
357
+ * T4 实测(`docs/RESEARCH-session-drop-to-bottom.md` §3.2):真实 localStorage 表里
358
+ * AnyWork 容器只固化了 16 条,而有 **6 条可见顶层会话不在表里**,其中**只有 2 条**
359
+ * 晚于固化水位(`2026-09-21T09:01:43Z`),另外 **4 条是旧会话**(水位之前就存在,
360
+ * 只是固化快照本身不完整)。
361
+ *
362
+ * ⇒ 若把「表外会话」一律当新会话置顶,这 4 条旧会话会**错误地跳到最前**。
363
+ * 因此本函数的 `newSessionIds` **由调用方按可靠判据给出**,本函数不做表外推断。
364
+ * 推荐的可靠判据(`sidebar.tsx` 采用):**本进程内观测到该会话 `blank: true → false`
365
+ * 的转换**(= 用户真的给它发了第一条消息),或**本进程内首次观察到该 id 且它晚于
366
+ * 本进程启动时的固化水位**。两者都要求「时间序」证据,而不是「表里有没有」。
367
+ *
368
+ * ## 排序与去重
369
+ *
370
+ * - 顶部区成员按 {@link sortTopZone}(`updatedAt` 降序);
371
+ * - 一个会话**最多出现一次**(`Set` 去重),因此「同一会话不得同时出现在多个容器的
372
+ * 顶部区」由「顶部区范围 = 本容器的 `visible` 成员」天然保证(`applyManualOrder`
373
+ * 只会在 `items` 里找到本容器的项);
374
+ * - 不在本容器 `sessions` 里的 id(归档 / 子代理 / 别的容器)**自然被忽略**。
375
+ *
376
+ * @param sessions 该容器内**已过滤**的可见会话(与 `applyManualOrder` 的 `items` 同一批)。
377
+ * @param currentSessionId 当前打开的会话 id。
378
+ * ⚠️ **T11 起不再参与任何置顶判定**,仅为**向后兼容**保留签名位置(既有调用方与
379
+ * `docs/INTERFACES.md` §2.2 的冻结签名);传入任何值都不改变结果。
380
+ * ⚠️ 2026-10-22:**当前空白会话**(「新会话」占位行)也**不**在这里置顶 —— 它由
381
+ * `emitContainer` 用 {@link isCurrentBlankSession} 单独排到最前(与宿主
382
+ * `sectionMembers` / `pinCurrentBlank` 同语义),本函数仍只负责「运行中 / 未落表新会话」。
383
+ * @param containerKey 本容器的 key。
384
+ * ⚠️ **T11 起不再被读取**(释放机制已删除),同样仅为签名兼容保留。
385
+ * @param topZone 运行时顶部区输入;缺省 ⇒ **无任何置顶项**(零回归分支)。
386
+ * @returns 置顶 key 数组;无置顶项时返回 `undefined`
387
+ * (让 `applyManualOrder` 走零回归分支)。
388
+ */
389
+ export function topZoneSessionKeys(sessions, currentSessionId, containerKey, topZone) {
390
+ // T11:`currentSessionId` / `containerKey` 已无语义。显式 `void` 掉,既让 `strict`
391
+ // 下的「未使用参数」意图明确,也留下「这是**有意**保留的兼容位」的痕迹。
392
+ void currentSessionId;
393
+ void containerKey;
394
+ const keys = [];
395
+ const seen = new Set();
396
+ const push = (key) => {
397
+ if (key === undefined || seen.has(key))
398
+ return;
399
+ seen.add(key);
400
+ keys.push(key);
401
+ };
402
+ if (topZone === undefined)
403
+ return keys.length === 0 ? undefined : keys;
404
+ // S2(T6 次要项):`topZone` 的契约类型是 `TopZoneInput | undefined`(不含 `null`),
405
+ // 但契约外输入(`null` / 字段是数字)会一路走到 `for…of` 抛 `TypeError`。与同函数内
406
+ // 对 id 元素的 `typeof` 守卫风格一致:**静默降级为不置顶**。
407
+ // 真实链路 `sidebar.tsx` 只传 `topZoneInputOf(...)` 的产物,故不可达。
408
+ // (先赋给放宽类型的局部变量,让 `=== null` 这层「契约外输入」检查能通过 `strict`。)
409
+ const zone = topZone;
410
+ if (zone === null || typeof zone !== 'object')
411
+ return keys.length === 0 ? undefined : keys;
412
+ // a)正在运行(含任意层级有运行中的子代理 —— 由调用方按需求 A 的聚合口径给出)。
413
+ // ⚠️ S2:id 列表用 `Array.isArray` 收窄(契约外输入 `42` / `null` 不得抛 `TypeError`),
414
+ // 与「id 元素非字符串则跳过」的守卫同一风格。判据本体在
415
+ // {@link isTopZoneRunningSession} 里(与「不可拖动」共用同一实现)。
416
+ // b)新会话(D2/D3d)。**已落表**的新会话(在 `writtenNewSessionIds` 台账里)**不再**在
417
+ // 渲染期被提升:它的「在容器最前」已由持久顺序承载(D2 落表),渲染期再提升一次会让
418
+ // 用户随后的拖拽被静默回滚(真人 GUI 复验的「拖动新会话弹回原位」缺陷,T9 缺陷 1)。
419
+ // 台账缺省(不传)⇒ 与旧行为逐字一致(仍然提升),保证零回归。
420
+ const done = new Set();
421
+ for (const id of Array.isArray(zone.writtenNewSessionIds) ? zone.writtenNewSessionIds : []) {
422
+ if (typeof id === 'string')
423
+ done.add(normalizeSessionId(id));
424
+ }
425
+ const fresh = new Set();
426
+ for (const id of Array.isArray(zone.newSessionIds) ? zone.newSessionIds : []) {
427
+ if (typeof id === 'string')
428
+ fresh.add(normalizeSessionId(id));
429
+ }
430
+ const rest = [];
431
+ for (const session of sessions) {
432
+ const key = normalizeSessionId(session.sessionId);
433
+ // 需求 A 口径:`SessionRowLike.running` 是宿主 `SessionSummary.running` 的**裸**透传
434
+ // (不含子代理聚合),而调用方传的 `runningSessionIds` 是**已聚合**的口径。
435
+ // 两者取并集 ⇒ 「只有 subagent 在跑」的会话也进顶部区。
436
+ // ⚠️ 判据与「不可拖动」共用 {@link isTopZoneRunningSession}(唯一实现,不可能分叉)。
437
+ const isRunning = isTopZoneRunningSession(session, zone);
438
+ // ⚠️ `fresh.has(key) && !done.has(key)`:已落表的新会话不再渲染期提升(见上方台账注释)。
439
+ const isFresh = fresh.has(key) && !done.has(key);
440
+ if (!isRunning && !isFresh)
441
+ continue;
442
+ rest.push(session);
443
+ }
444
+ for (const session of sortTopZone(rest))
445
+ push(session.sessionId);
446
+ return keys.length === 0 ? undefined : keys;
447
+ }
448
+ /** 空状态(首次渲染的初值)。 */
449
+ export function initialTopZoneState() {
450
+ return {
451
+ baselined: false,
452
+ startedAtMs: 0,
453
+ knownSessionIds: [],
454
+ blankOf: {},
455
+ runningOf: {},
456
+ newSessionIds: [],
457
+ writtenNewSessionIds: [],
458
+ };
459
+ }
460
+ /**
461
+ * 观测一批会话,推进顶部区状态机(**纯函数**;无变化时返回**同一个引用**,
462
+ * 以便 `sidebar.tsx` 直接用于 `useState` 而不触发无限重渲染)。
463
+ *
464
+ * ## 「新会话」判定口径(关键,D2 的边界要求)
465
+ *
466
+ * 满足**任一**条件即判定为新会话(且必须:非子代理、非归档、基线之后):
467
+ *
468
+ * 1. **强证据 —— 本进程内观测到 `blank: true → false` 的转换**。
469
+ * 宿主语义(`dsh-api-session-controller/.../manager.js`):新建会话 `blank: true`,
470
+ * 发出第一条 `user/message` 后翻成 `false`。所以「先见 blank、后见非 blank」只能
471
+ * 是「这个会话在本进程观测期间发出了第一条消息」—— 时间序证据,不依赖顺序表。
472
+ * 2. **时间序证据 —— 首次观测到的会话且 `updatedAt >= 本进程基线时刻`**。
473
+ * 覆盖「新建 + 发首条消息发生在两次轮询之间、没观测到 blank 态」的窄窗口。
474
+ * `updatedAt = max(createdAt, lastPromptAt)` ⇒ 晚于本进程启动的 `updatedAt`
475
+ * 只可能来自「本进程启动后创建 / 本进程启动后发出消息」的会话。
476
+ *
477
+ * ## 为什么**不**用「不在固化顺序表里」
478
+ *
479
+ * T4 实测(`docs/RESEARCH-session-drop-to-bottom.md` §3.2):真实表里有 **6 条可见顶层
480
+ * 会话不在表里**,其中**只有 2 条**晚于固化水位,另外 **4 条是旧会话**(水位之前就存在,
481
+ * 只是固化快照本身不完整)。若按「表外即新」判定,这 4 条旧会话会被错误地插到最前。
482
+ * 本实现用「基线 + 时间序」双重证据,**基线里出现过的旧会话永远不会被判为新会话**。
483
+ *
484
+ * ## 残余不确定性(如实披露)
485
+ *
486
+ * - 若「创建会话 + 发首条消息」全部发生在**首次树数据到达之前**(页面刚加载的
487
+ * ~100ms 窗口内),该会话会进入基线 ⇒ 不会被判为新会话(**漏报**)。此时它在
488
+ * manual 模式下仍会落末尾 —— 但用户重开一次页面后,它已在基线里,属可接受降级。
489
+ * - 若宿主时钟与渲染进程时钟严重不一致(同机场景不可能),时间序判据可能误判。
490
+ * - 若**旧**会话的 `updatedAt` 因故晚于本进程基线(宿主时钟偏差 / `lastPromptAt` 被历史
491
+ * 事件推进),且它在本进程内**首次**出现,则会被判为新会话(**误报**)。同机场景不可能;
492
+ * 已在 `docs/PRD.md`「顶部区」段如实披露(T6 次要项 S3)。
493
+ *
494
+ * ## 归档语义(T6 缺陷 I3,2026-09-21 修正)
495
+ *
496
+ * 「谁算旧会话」与「谁参与顶部区判定」是**两个不同的事实**,本函数刻意分开:
497
+ *
498
+ * - `knownSessionIds`(= `seen`,**含归档与子代理会话**)只回答「这个 id 本进程见过没有」。
499
+ * 归档会话进 `known` ⇒ 即便它之后被取消归档、`updatedAt` 又被推进到基线之后,也**不会**
500
+ * 被判成新会话(否则会把一条**旧**会话插到固化表表首,违反 D5)。
501
+ * - `eligible`(**排除归档与子代理**)只回答「谁参与 blank / running 轨迹与顶部区判定」。
502
+ * 归档会话**不**产生 `blankOf` / `runningOf` 轨迹,**不**进 `newSessionIds`,也不置顶。
503
+ *
504
+ * ⚠️ 宿主**当前没有** unarchive API(`@deepseek-ai/dsh-api-workspace-controller` 只有
505
+ * `archiveSession`),所以「取消归档」这条路径当前不可达;这里仍按正确语义实现,因为
506
+ * 用户手改 `~/.dsh/storages/workspace.json` 或宿主将来提供 API 都会让它可达。
507
+ *
508
+ * ## 其它转换
509
+ *
510
+ * - `running` 轨迹(`runningOf`)逐观测更新,供 {@link topZoneInputOf} 投影
511
+ * `runningSessionIds` —— 它是顶部区**唯一**的常规成员类别(T11 终裁)。
512
+ * - ⚠️ **T11 已删除**:旧实现在 `running: true → false` 的下降沿写入
513
+ * `recentlyFinishedIds`(「刚结束保留」),并在出现新会话时清空它。用户终裁
514
+ * 「只要是结束了的会话就不再固定置顶了」⇒ 该机制连同其状态字段一并删除,
515
+ * `runningOf` 只用于回答「现在谁在跑」。
516
+ *
517
+ * @param state 上一状态。
518
+ * @param observations 本次观测到的全部会话(含 blank / 子代理 / 归档)。
519
+ * @param nowMs 本次观测的时刻(`Date.now()`);由调用方注入以便单测确定化。
520
+ * @returns 新状态;**无任何变化时返回入参 `state` 本身**。
521
+ */
522
+ export function observeTopZone(state, observations, nowMs) {
523
+ const eligible = [];
524
+ // 「本进程已观测过」的**全部**会话 id(含归档与子代理)—— 与 `eligible` 刻意分开:
525
+ // `eligible` 决定「谁参与顶部区判定」,`seen` 只决定「谁算旧会话」。
526
+ // ⚠️ 归档会话**必须**进 `seen`(T6 缺陷 I3):否则「基线时已归档、之后取消归档并收到
527
+ // 新消息」的旧会话会被 `firstSeenAfterStart` 判成新会话并写进固化表表首 ⇒ 违反 D5。
528
+ // 归档会话不参与任何**顶部区**判定,但「它存在过」这一事实必须记住。
529
+ const seen = new Set();
530
+ for (const observation of observations) {
531
+ if (typeof observation.sessionId !== 'string' || observation.sessionId === '')
532
+ continue;
533
+ const id = normalizeSessionId(observation.sessionId);
534
+ seen.add(id);
535
+ if (observation.subagent || observation.archived)
536
+ continue;
537
+ eligible.push(observation);
538
+ }
539
+ // ── 基线:本进程首次拿到树数据。把当时已知的全部会话记为「已知」,不产生新会话。
540
+ if (!state.baselined) {
541
+ const known = new Set(seen);
542
+ const blankOf = {};
543
+ const runningOf = {};
544
+ for (const observation of eligible) {
545
+ const id = normalizeSessionId(observation.sessionId);
546
+ blankOf[id] = observation.blank === true;
547
+ runningOf[id] = observation.running === true;
548
+ }
549
+ return {
550
+ baselined: true,
551
+ startedAtMs: nowMs,
552
+ knownSessionIds: [...known],
553
+ blankOf,
554
+ runningOf,
555
+ newSessionIds: [],
556
+ writtenNewSessionIds: state.writtenNewSessionIds,
557
+ };
558
+ }
559
+ const known = new Set(state.knownSessionIds);
560
+ const blankOf = { ...state.blankOf };
561
+ const runningOf = { ...state.runningOf };
562
+ const fresh = new Set(state.newSessionIds);
563
+ // 第一遍:判定「新会话」(用**旧**的 blank/known 状态,避免同批次自证)。
564
+ const detectedNew = [];
565
+ for (const observation of eligible) {
566
+ const id = normalizeSessionId(observation.sessionId);
567
+ const previousBlank = blankOf[id];
568
+ const blankedToVisible = previousBlank === true && observation.blank !== true;
569
+ const firstSeenAfterStart = !known.has(id) && Number.isFinite(observation.updatedAt) && observation.updatedAt >= state.startedAtMs;
570
+ if (!blankedToVisible && !firstSeenAfterStart)
571
+ continue;
572
+ if (!fresh.has(id))
573
+ detectedNew.push(id);
574
+ }
575
+ // 第二遍:更新 blank / running 轨迹。
576
+ // ⚠️ T11:这里**不再**记录 running 下降沿(「刚结束保留」机制已按用户终裁删除)。
577
+ for (const observation of eligible) {
578
+ const id = normalizeSessionId(observation.sessionId);
579
+ blankOf[id] = observation.blank === true;
580
+ runningOf[id] = observation.running === true;
581
+ known.add(id);
582
+ }
583
+ for (const id of detectedNew)
584
+ fresh.add(id);
585
+ // I3:归档 / 子代理会话也记入 `known`(「存在过」这一事实必须记住),但它们
586
+ // 不产生 blank / running 轨迹,也不参与任何顶部区判定。
587
+ for (const id of seen)
588
+ known.add(id);
589
+ // 无变化 ⇒ 返回同一引用(`useState` 幂等,不触发无限重渲染)。
590
+ //
591
+ // ⚠️ 这里**不能**用 `known.size === state.knownSessionIds.length` 当判据:`known` 只增
592
+ // 不减,但 `state.knownSessionIds` 是数组;用长度比较会在「已知集合不变」时恒等,
593
+ // 看起来没问题 —— 真正的问题是**顺序**:`[...known]` 的插入顺序与旧数组可能不同,
594
+ // 却仍返回旧引用。这里改为逐项比较,保证「引用相同 ⟺ 内容逐字相同」。
595
+ const nextFresh = [...fresh];
596
+ const sameIds = (a, b) => a.length === b.length && a.every((id, index) => id === b[index]);
597
+ const sameRecord = (a, b) => {
598
+ const aKeys = Object.keys(a);
599
+ if (aKeys.length !== Object.keys(b).length)
600
+ return false;
601
+ return aKeys.every((key) => b[key] === a[key]);
602
+ };
603
+ const unchanged = detectedNew.length === 0 &&
604
+ sameIds(nextFresh, state.newSessionIds) &&
605
+ sameIds([...known], state.knownSessionIds) &&
606
+ sameRecord(blankOf, state.blankOf) &&
607
+ sameRecord(runningOf, state.runningOf);
608
+ if (unchanged)
609
+ return state;
610
+ return {
611
+ baselined: true,
612
+ startedAtMs: state.startedAtMs,
613
+ knownSessionIds: [...known],
614
+ blankOf,
615
+ runningOf,
616
+ newSessionIds: nextFresh,
617
+ writtenNewSessionIds: state.writtenNewSessionIds,
618
+ };
619
+ }
620
+ /**
621
+ * 从 `effectiveOrder` 的会话表里找出某个会话所属的**容器 key**。
622
+ *
623
+ * D2 的写入需要知道「新会话插到哪张表里」。用 `effectiveOrder`(而不是自己重推容器归属)
624
+ * 保证与渲染/固化路径**同源** —— 容器 key 的推导规则全模块只有一处实现。
625
+ *
626
+ * 比较时两侧都做 `session-` 前缀归一化。同一 id 出现在多个容器时取**第一个**
627
+ * (真实链路 `buildProjects` 每个会话只 push 一次,故不可达;此处只为确定性)。
628
+ *
629
+ * @param sessions `effectiveOrder(...).sessions`。
630
+ * @param sessionId 目标会话 id。
631
+ * @returns 容器 key;找不到时 `undefined`。
632
+ */
633
+ export function containerKeyOfSession(sessions, sessionId) {
634
+ return placementOfSession(sessions, sessionId)?.containerKey;
635
+ }
636
+ /**
637
+ * 某个会话在**树/固化表里的落点**:容器 key + **该会话在表里的真实 id 形态**。
638
+ *
639
+ * ## 为什么必须把「真实形态」也带出来(T6 缺陷 B1 的根因)
640
+ *
641
+ * `observeTopZone` 内部一律用 `normalizeSessionId`(去掉 `session-` 前缀)做比较,所以
642
+ * `TopZoneState.newSessionIds` 里存的是**裸 id**;而宿主真实会话 id 恒带 `session-` 前缀
643
+ * (实测 `~/.dsh/sessions/**` 的会话头 `id = 'session-<uuid>'`,用户真实固化表 54 个条目
644
+ * **全部**带前缀)。`applyManualOrder` 用 `keyOf(item)`(= 树里的真实 id)去 `indexOf`,
645
+ * 于是「把裸 id 写进表」会产生**永远匹配不上的死条目**,并顶掉原本正确的条目。
646
+ *
647
+ * 所以 D2 落表**不能**直接把归一化 id 写进表:必须先用本函数把它还原成**树里的原形态**。
648
+ * 「比较用归一化、写入用原形态」与 {@link normalizeSessionId} 的契约(`仅用于比较,
649
+ * 输出仍用原 id`)逐字一致。
650
+ *
651
+ * @param sessions `effectiveOrder(...).sessions`。
652
+ * @param sessionId 目标会话 id(裸 id / 带前缀 id 都可)。
653
+ * @returns `{ containerKey, sessionId }`;找不到时 `undefined`。
654
+ */
655
+ export function placementOfSession(sessions, sessionId) {
656
+ if (typeof sessionId !== 'string' || sessionId === '')
657
+ return undefined;
658
+ const target = normalizeSessionId(sessionId);
659
+ for (const [containerKey, list] of sessions) {
660
+ for (const id of list) {
661
+ if (normalizeSessionId(id) === target)
662
+ return { containerKey, sessionId: id };
663
+ }
664
+ }
665
+ return undefined;
666
+ }
667
+ /**
668
+ * D2:把**新会话**插到其所属容器固化顺序表的**最前**(幂等)。
669
+ *
670
+ * 语义与边界(用户裁决 D2 + 任务书的边界要求):
671
+ * - **只在 `manual === true` 时写入**。默认模式(`manual !== true`)下新会话本来就排最前,
672
+ * 而且**凭空建表会把用户静默切成手动模式** —— 用户明确要自己点一次「恢复默认排序」,
673
+ * 我们绝不代他改这个开关。所以默认模式**返回 `undefined`**(不写、不建表)。
674
+ * - **幂等**:目标会话已在表首 ⇒ 返回 `undefined`(不产生无谓的 `localStorage` 写入)。
675
+ * - **去重**:先把该 id 从列表里全部剔除再插到首位 ⇒ 不产生重复条目。
676
+ * - **不写运行时置顶**:只写这一个新会话,`running` / 新会话提升本身一律**不进表**
677
+ * (`running` 由 {@link topZoneSessionKeys} 在渲染期推导)。
678
+ * - **不修改入参**:返回新的 {@link ManualOrder} 对象(浅拷贝 + 新数组)。
679
+ * - **写入形态(T6 缺陷 B1)**:写入的字符串必须能被 `applyManualOrder` 的 `keyOf`
680
+ * (= 树里的真实 id)匹配上。规则(按可信度):① 表里已有该会话 ⇒ 复用它的原形态
681
+ * (用户数据是真相);② 否则 `fullOrder`(= `effectiveOrder` 的产物 = 树里的真实 id)
682
+ * 里有 ⇒ 用树里的形态;③ 都没有 ⇒ 用调用方给的 `sessionId`。绝不写入与树/表形态
683
+ * 不一致的「死条目」。
684
+ *
685
+ * @param order 当前的手动顺序。
686
+ * @param containerKey 目标容器 key(由 {@link containerKeyOfSession} 求得)。
687
+ * @param sessionId 新会话 id(**树里的真实形态**;裸 id 亦可,但表里没有该会话时会按原样写入)。
688
+ * @param fullOrder 该容器的**完整生效顺序**(`effectiveOrder(...).sessions.get(containerKey)`)——
689
+ * 仅当表里还没有这个容器(或表项是**空数组**)时用作基底,避免「只写一条、其余丢失」。
690
+ * @returns 新的 {@link ManualOrder};**无需写入时返回 `undefined`**。
691
+ */
692
+ export function insertSessionAtFront(order, containerKey, sessionId, fullOrder) {
693
+ if (order.manual !== true)
694
+ return undefined;
695
+ if (typeof containerKey !== 'string' || containerKey === '')
696
+ return undefined;
697
+ if (typeof sessionId !== 'string' || sessionId === '')
698
+ return undefined;
699
+ // S1(T6 次要项):表项为**空数组**时 `??` 不触发 ⇒ 会把 `fullOrder` 里的会话全丢掉。
700
+ // 空数组只可能是用户手改 / 旧版本写坏的退化数据(`stringListMapOf` 会丢弃空数组键),
701
+ // 此时按「表里没有这个容器」处理,用 `fullOrder` 作基底 ⇒ 不丢会话。
702
+ const stored = order.sessions?.[containerKey];
703
+ const base = stored !== undefined && stored.length > 0 ? stored : (fullOrder ?? stored ?? []);
704
+ const target = normalizeSessionId(sessionId);
705
+ // B1(T6 缺陷):写入的字符串必须能被 `applyManualOrder` 的 `keyOf`(= **树里的真实 id**)
706
+ // 匹配上,否则就是一条**永远匹配不上的死条目**,还会顶掉原本正确的条目。三处证据按
707
+ // 可信度排序取「原形态」:① 表里已有该会话(用户数据是真相)→ 用它的写法;
708
+ // ② `fullOrder`(= `effectiveOrder` 的产物 = 树里的真实 id)里有 → 用树里的写法;
709
+ // ③ 都没有(该会话当前不可见)→ 回落到调用方给的 `sessionId`。
710
+ const writtenId = base.find((id) => typeof id === 'string' && normalizeSessionId(id) === target) ??
711
+ fullOrder?.find((id) => typeof id === 'string' && normalizeSessionId(id) === target) ??
712
+ sessionId;
713
+ const rest = base.filter((id) => typeof id === 'string' && normalizeSessionId(id) !== target);
714
+ const next = [writtenId, ...rest];
715
+ // 幂等:已经在表首且无重复 ⇒ 不写。
716
+ const current = order.sessions?.[containerKey];
717
+ if (current !== undefined &&
718
+ current.length === next.length &&
719
+ current.every((id, index) => id === next[index])) {
720
+ return undefined;
721
+ }
722
+ return { ...order, manual: true, sessions: { ...(order.sessions ?? {}), [containerKey]: next } };
723
+ }
724
+ /**
725
+ * **D2 落表编排(纯函数)**:把 {@link TopZoneState.newSessionIds} 里尚未消费的新会话
726
+ * 逐个插到其容器固化表最前,并回答「哪些 id 就此消费掉」。
727
+ *
728
+ * ## 为什么需要它(T6 缺陷 B2:编排层必须收敛)
729
+ *
730
+ * `observeTopZone` 的 `newSessionIds` 在本进程内**只增不减**(它是 D3d 的顶部区输入,
731
+ * 不能因为落表就移除)。若 `sidebar.tsx` 每次 effect 重跑都无条件调
732
+ * `insertSessionAtFront`,那么用户**拖动刚建的新会话**(`manualOrder` 变化 ⇒ effect
733
+ * 重跑)时会被**静默搬回表首** —— 用户拖动被回滚、持久顺序被改写。
734
+ *
735
+ * 收敛机制:调用方把本函数返回的 `consumed` 记进
736
+ * {@link TopZoneState.writtenNewSessionIds},下次 effect 重跑时 `alreadyWritten` 里已有
737
+ * 这些 id ⇒ **不再重放**。于是「同一个新会话的落表只发生一次」;用户随后把它拖到任何
738
+ * 位置都不会被 effect 改写。
739
+ *
740
+ * ## 与 `newSessionIds` 的关系
741
+ *
742
+ * 本函数**不**修改 `newSessionIds`(那是 D3d 的顶部区输入,新会话在整个页面会话内
743
+ * 都应被提升到顶部区)。「落表」与「顶部区提升」是两件事,台账分开记。
744
+ *
745
+ * ## 边界
746
+ *
747
+ * - `order.manual !== true` ⇒ 原样返回、**不消费**(默认模式不写、不建表;D2 原文)。
748
+ * - `alreadyWritten` 里的 id ⇒ 跳过(B2 的收敛点)。
749
+ * - 在 `sessions`(树/生效顺序)里找不到的 id ⇒ **不消费**(它当前不可见,例如仍是
750
+ * blank 被过滤掉);等它出现时再落表,不会永久丢失这次 D2 意图。
751
+ * - 落表用 {@link placementOfSession} 得到的**树里真实 id 形态** ⇒ 不会产生死条目(B1)。
752
+ *
753
+ * @param order 当前的手动顺序。
754
+ * @param sessions `effectiveOrder({... , manualOrder: undefined}).sessions`(**纯默认顺序**
755
+ * 的容器划分,与渲染同源)。
756
+ * @param newSessionIds 待落表的新会话 id(`TopZoneState.newSessionIds`,归一化)。
757
+ * @param alreadyWritten 已消费的新会话 id(`TopZoneState.writtenNewSessionIds`,归一化)。
758
+ * @returns 新顺序 + 本次消费的 id + 是否改动。
759
+ */
760
+ export function planNewSessionInserts(order, sessions, newSessionIds, alreadyWritten) {
761
+ if (order.manual !== true)
762
+ return { order, consumed: [], changed: false };
763
+ const done = new Set();
764
+ for (const id of alreadyWritten) {
765
+ if (typeof id === 'string' && id !== '')
766
+ done.add(normalizeSessionId(id));
767
+ }
768
+ const consumed = [];
769
+ let next = order;
770
+ let changed = false;
771
+ for (const raw of newSessionIds) {
772
+ if (typeof raw !== 'string' || raw === '')
773
+ continue;
774
+ const id = normalizeSessionId(raw);
775
+ // B2:已消费 ⇒ 永不重放(用户拖动该新会话不会被回滚)。
776
+ if (done.has(id))
777
+ continue;
778
+ const placement = placementOfSession(sessions, id);
779
+ // 不在树里(不可见:仍是 blank / 已归档 / 别的容器)⇒ 本次不消费,等它可见。
780
+ if (placement === undefined)
781
+ continue;
782
+ const inserted = insertSessionAtFront(next, placement.containerKey, placement.sessionId, sessions.get(placement.containerKey));
783
+ consumed.push(id);
784
+ if (inserted === undefined)
785
+ continue;
786
+ next = inserted;
787
+ changed = true;
788
+ }
789
+ return { order: next, consumed, changed };
790
+ }
791
+ /**
792
+ * **D2 落表台账**:把「落表意图已满足」的新会话 id 记入 {@link TopZoneState.writtenNewSessionIds}。
793
+ *
794
+ * 幂等:全部 id 都已在台账里时返回**同一引用**(不触发无谓重渲染)。
795
+ *
796
+ * ⚠️ 只动 `writtenNewSessionIds`,**不动** `newSessionIds` —— 后者是 D3d 的顶部区输入,
797
+ * 新会话在整个页面会话内都应被提升到容器顶部区。
798
+ *
799
+ * @param state 上一状态。
800
+ * @param sessionIds 本次消费的 id({@link planNewSessionInserts} 的 `consumed`)。
801
+ * @returns 新状态;无变化时返回入参 `state`。
802
+ */
803
+ export function markNewSessionsWritten(state, sessionIds) {
804
+ const seen = new Set(state.writtenNewSessionIds);
805
+ const next = [...state.writtenNewSessionIds];
806
+ let changed = false;
807
+ for (const id of sessionIds) {
808
+ if (typeof id !== 'string' || id === '')
809
+ continue;
810
+ const key = normalizeSessionId(id);
811
+ if (seen.has(key))
812
+ continue;
813
+ seen.add(key);
814
+ next.push(key);
815
+ changed = true;
816
+ }
817
+ return changed ? { ...state, writtenNewSessionIds: next } : state;
818
+ }
819
+ /**
820
+ * 尚未消费(还没落表 / 还没确认已在表首)的新会话 id(归一化)—— `sidebar.tsx` 的 D2
821
+ * effect 用它决定「这次要不要跑落表」。
822
+ *
823
+ * @param state 顶部区状态。
824
+ * @returns 待落表的 id(顺序 = `newSessionIds` 的顺序)。
825
+ */
826
+ export function pendingNewSessionIdsOf(state) {
827
+ const done = new Set(state.writtenNewSessionIds);
828
+ return state.newSessionIds.filter((id) => typeof id === 'string' && id !== '' && !done.has(normalizeSessionId(id)));
829
+ }
830
+ /**
831
+ * 归一化会话 id:去掉宿主可能带的 `session-` 前缀。
832
+ *
833
+ * 宿主持久层存在 `session-<uuid>` 与裸 `<uuid>` 两种写法,比较父 id 前必须归一化,
834
+ * 否则子代理会误判为「父不在组内」。**仅用于比较**,输出仍用原 id。
835
+ */
836
+ function normalizeSessionId(id) {
837
+ return id.startsWith(SESSION_ID_PREFIX) ? id.slice(SESSION_ID_PREFIX.length) : id;
838
+ }
839
+ /** `blank === true` 判定;用 `unknown` 入参以便对 `T extends { sessionId: string }` 生效。 */
840
+ function isBlank(row) {
841
+ return typeof row === 'object' && row !== null && row.blank === true;
842
+ }
843
+ /**
844
+ * 是否是子代理会话(`origin === 'subagent'`)。
845
+ *
846
+ * 对齐原生 `sessionVisible` 的第一项 `session.origin !== "subagent"`。注意判据是 `origin`
847
+ * 而**不是** `parentSessionId`:「派生会话」(fork)也会写 `parentSession`
848
+ * (`dsh-session` 的 `SessionStore.fork`),但它不是子代理,原生照常渲染成顶层行。
849
+ *
850
+ * 本函数只回答「是不是子代理」;**唯一的会话可见性谓词**是 {@link isVisibleMember},
851
+ * 它把本判定与归档 / blank 规则合在一起,树与搜索都只走它。
852
+ */
853
+ function isSubagentSession(session) {
854
+ return session.origin === 'subagent';
855
+ }
856
+ /**
857
+ * 用 `nestSubagents` 解出「父 → 子代」边(**不动点迭代**)。
858
+ *
859
+ * 为什么需要迭代:`nestSubagents` 的契约只展开**一层** —— 深度 ≥2 的后代会被展平为
860
+ * `depth: 0`(见它的单测「父自己是子代理 ⇒ 孙平铺为 depth 0」)。而本次要修的正是
861
+ * 「计数只数直接子代」这个错,所以深层边必须补齐:把「本轮识别出的子代」与「本轮仍是
862
+ * 根、但父在集合内且尚未归属」的会话放进下一轮,直到某一轮不再产生新边为止。
863
+ *
864
+ * 终止性:边按 `(父, 子)` 去重且最多 `n²` 条,配合「本轮无新边即停」必然收敛。
865
+ *
866
+ * 顺带复用 `nestSubagents` 的 id 归一化(`session-` 前缀)与「父必须在集合内」判定,
867
+ * 使父子关系的解析规则全模块只有一处实现。
868
+ */
869
+ function discoverChildEdges(sessions) {
870
+ const inSet = new Set();
871
+ for (const session of sessions)
872
+ inSet.add(normalizeSessionId(session.sessionId));
873
+ const edges = new Map();
874
+ const edgeKeys = new Set();
875
+ const attributed = new Set();
876
+ let frontier = sessions;
877
+ while (frontier.length > 0) {
878
+ const nested = nestSubagents(frontier);
879
+ const next = [];
880
+ const roots = [];
881
+ let added = false;
882
+ let head;
883
+ for (const entry of nested) {
884
+ if (entry.depth === 0) {
885
+ head = entry.session;
886
+ roots.push(entry.session);
887
+ continue;
888
+ }
889
+ const parent = head;
890
+ if (parent === undefined)
891
+ continue;
892
+ const parentKey = normalizeSessionId(parent.sessionId);
893
+ const childKey = normalizeSessionId(entry.session.sessionId);
894
+ const edgeKey = `${parentKey}\u0000${childKey}`;
895
+ if (!edgeKeys.has(edgeKey)) {
896
+ edgeKeys.add(edgeKey);
897
+ attributed.add(childKey);
898
+ added = true;
899
+ const bucket = edges.get(parentKey);
900
+ if (bucket === undefined)
901
+ edges.set(parentKey, [entry.session]);
902
+ else
903
+ bucket.push(entry.session);
904
+ }
905
+ next.push(entry.session);
906
+ }
907
+ // 被展平的更深后代:本轮是根,但父在集合内 ⇒ 下一轮它才可能被正确挂上。
908
+ for (const root of roots) {
909
+ const parentId = root.parentSessionId;
910
+ if (parentId === undefined)
911
+ continue;
912
+ const rootKey = normalizeSessionId(root.sessionId);
913
+ if (attributed.has(rootKey))
914
+ continue;
915
+ if (!inSet.has(normalizeSessionId(parentId)))
916
+ continue;
917
+ next.push(root);
918
+ }
919
+ if (!added)
920
+ break;
921
+ frontier = next;
922
+ }
923
+ // 兜底:`nestSubagents` 对**环 / 自指**(脏数据)选择软失败 —— 环上成员都留在根集合里,
924
+ // 于是上面拿不到边。真实数据不可能出现(会话只能由已存在的父会话创建,父子关系构成森林),
925
+ // 但这里仍把这类关系补成边,好让下面的累加与原生 `indexSubagentDescendants` 逐例一致
926
+ // (原生直接读 `parentId`,不看嵌套结果)。
927
+ for (const session of sessions) {
928
+ const childKey = normalizeSessionId(session.sessionId);
929
+ const parentId = session.parentSessionId;
930
+ if (parentId === undefined)
931
+ continue;
932
+ const parentKey = normalizeSessionId(parentId);
933
+ if (!inSet.has(parentKey))
934
+ continue;
935
+ const edgeKey = `${parentKey}\u0000${childKey}`;
936
+ if (edgeKeys.has(edgeKey))
937
+ continue;
938
+ edgeKeys.add(edgeKey);
939
+ const bucket = edges.get(parentKey);
940
+ if (bucket === undefined)
941
+ edges.set(parentKey, [session]);
942
+ else
943
+ bucket.push(session);
944
+ }
945
+ return edges;
946
+ }
947
+ /**
948
+ * 建「运行中的子代理后代数」索引(所有层级),见 {@link SubagentRunningCounts}。
949
+ *
950
+ * 累加过程是原生 `indexSubagentDescendants`(`dsh-client-ui-workspace/lib/client.js:285-306`)
951
+ * 的**逐字移植** —— 对每个**子代理**会话,沿父链一路向上、每经过一个父节点就 +1,直到
952
+ * 当前节点不再是子代理 / 没有父 / 遇到已访问节点(`seen` 环保护)为止:
953
+ *
954
+ * ```js
955
+ * let current = descendant
956
+ * while (current?.origin === "subagent" && current.parentId !== undefined && !seen.has(current.id)) {
957
+ * seen.add(current.id)
958
+ * indexed[current.parentId].runningCount += 1 // 仅在 descendant.running 时
959
+ * current = summaries[current.parentId]
960
+ * }
961
+ * ```
962
+ *
963
+ * 父子关系来自 {@link discoverChildEdges}(内部走 `nestSubagents`),因此 id 前缀归一化与
964
+ * 全模块同源。
965
+ *
966
+ * @param sessions 参与索引的全部会话(跨容器;重复 id 会被去重)。
967
+ * @returns 归一化会话 id → 运行中的子代理后代数。**每个入参会话都有键**(没有运行中的
968
+ * 子代理后代时为 `0`)。⚠️ 键是**归一化**后的 id(`session-` 前缀已去掉)——
969
+ * 查询请一律走 {@link subagentCountOf}(它内部归一化),不要直接 `get(原始 id)`。
970
+ */
971
+ export function indexRunningSubagentDescendants(sessions) {
972
+ const edges = discoverChildEdges(sessions);
973
+ const parentOf = new Map();
974
+ const byKey = new Map();
975
+ const counts = new Map();
976
+ for (const session of sessions) {
977
+ const key = normalizeSessionId(session.sessionId);
978
+ if (!byKey.has(key))
979
+ byKey.set(key, session);
980
+ // 预置 0:所有入参会话都有键(见 JSDoc 的返回契约)。
981
+ if (!counts.has(key))
982
+ counts.set(key, 0);
983
+ }
984
+ for (const [parentKey, children] of edges) {
985
+ for (const child of children) {
986
+ const childKey = normalizeSessionId(child.sessionId);
987
+ if (!parentOf.has(childKey))
988
+ parentOf.set(childKey, parentKey);
989
+ }
990
+ }
991
+ // 按**去重后**的会话遍历(原生的 `byId` 是 Map ⇒ 同 id 只累加一次)。
992
+ for (const session of byKey.values()) {
993
+ if (!isSubagentSession(session))
994
+ continue;
995
+ const seen = new Set();
996
+ let currentKey = normalizeSessionId(session.sessionId);
997
+ let current = byKey.get(currentKey);
998
+ while (current !== undefined && isSubagentSession(current) && !seen.has(currentKey)) {
999
+ const parentKey = parentOf.get(currentKey);
1000
+ if (parentKey === undefined)
1001
+ break;
1002
+ seen.add(currentKey);
1003
+ if (session.running === true)
1004
+ counts.set(parentKey, (counts.get(parentKey) ?? 0) + 1);
1005
+ currentKey = parentKey;
1006
+ current = byKey.get(parentKey);
1007
+ }
1008
+ }
1009
+ return counts;
1010
+ }
1011
+ /** 查索引(缺键视为 0)。 */
1012
+ function subagentCountOf(counts, sessionId) {
1013
+ return counts.get(normalizeSessionId(sessionId)) ?? 0;
1014
+ }
1015
+ function allSessionsOf(source) {
1016
+ const all = [];
1017
+ for (const project of source.projects) {
1018
+ for (const node of project.worktrees)
1019
+ all.push(...node.sessions);
1020
+ all.push(...project.history);
1021
+ all.push(...project.flatSessions);
1022
+ }
1023
+ all.push(...source.ungrouped);
1024
+ return all;
1025
+ }
1026
+ /**
1027
+ * 把 {@link SidebarModelInput} 投影成顶部区状态机的观测批次(T5,**纯函数**)。
1028
+ *
1029
+ * 为什么要这一层:顶部区状态机需要**每条会话**的 `blank` / **聚合** `running` /
1030
+ * `subagent` / `archived`,而 `sidebar.tsx` 只有原始树数据。把投影放在这里(而不是
1031
+ * `.tsx` 里手写循环)⇒ 投影口径可被 `node --test` 覆盖,`sidebar.tsx` 的改动退化为
1032
+ * 「调用一个纯函数 + `useState`」。
1033
+ *
1034
+ * ⚠️ **`running` 用聚合口径**(= `RenderRow.running`,含任意层级运行中的子代理后代):
1035
+ * D3a 明确要求「任意层级有 running subagent」也算运行中。裸的 `session.running` 会让
1036
+ * 「只有 subagent 在跑」的会话漏出顶部区 —— 这正是 T4 §4.4 指出的缺口。
1037
+ *
1038
+ * ⚠️ 观测批次必须**含归档与子代理会话**:状态机要靠「某 id 一直是子代理 / 一直归档」
1039
+ * 把它们排除,且它们的 `running` 要参与子代理聚合索引(`indexRunningSubagentDescendants`
1040
+ * 本身就是未过滤口径)。
1041
+ *
1042
+ * ## N1/I3 真实链路修复(T9,2026-09-22)
1043
+ *
1044
+ * **缺陷**:`buildProjects`(`src/projects.ts` 的 `:400` / `collectUngrouped` 的 `:480`)
1045
+ * 已经把**归档会话从树里剔除**,所以树数据里根本没有归档会话 —— 而本函数此前只从树
1046
+ * (`allSessionsOf`)取会话 ⇒ 归档会话**从未进过观测批次** ⇒ `observeTopZone` 的
1047
+ * `seen` 里没有它们 ⇒ 「基线时已归档、之后取消归档并收到新消息」的**旧**会话会被
1048
+ * `firstSeenAfterStart` 判成新会话并写进固化表表首(违反 D5)。
1049
+ * T7 的单测 fixture 把归档会话**同时**放进树和 `archivedSessionIds`,与真实链路**不同构**
1050
+ * ⇒ 那条用例是**恒真测试**(T8 实测真实链路下 `newSessionIds = ['oldarch']`)。
1051
+ *
1052
+ * **修复**:把 `source.archivedSessionIds` **单独投影**成 `archived: true` 的观测
1053
+ * (见下方 `archivedIds` 循环),使 `seen` 覆盖归档会话。这些观测:
1054
+ * - **进 `known`**(「存在过」的事实必须记住 ⇒ 取消归档后不误判新会话);
1055
+ * - **不产生** `blankOf` / `runningOf` 轨迹,**不参与**顶部区判定(`observeTopZone`
1056
+ * 里 `observation.archived` 被跳过)。
1057
+ *
1058
+ * `updatedAt` 对归档 id 未知(归档会话不在树里,没有宿主摘要)⇒ 填 `0`(有限值,
1059
+ * 不会因此被时间序判据选中;且 `archived` 为真时本就不会进入新会话判定)。
1060
+ *
1061
+ * @param input 与 `buildRows` 同一份入参。
1062
+ * @returns 每条输入会话一条观测(顺序 = `allSessionsOf` 的顺序),**后接**归档 id 观测。
1063
+ */
1064
+ export function observationsOf(source) {
1065
+ const archived = new Set(source.archivedSessionIds);
1066
+ const counts = indexRunningSubagentDescendants(allSessionsOf(source));
1067
+ const observations = [];
1068
+ const seen = new Set();
1069
+ for (const session of allSessionsOf(source)) {
1070
+ if (typeof session.sessionId !== 'string' || session.sessionId === '')
1071
+ continue;
1072
+ const key = normalizeSessionId(session.sessionId);
1073
+ // 同一 id 只产出一条观测(真实链路不会重复;这里保证确定性)。
1074
+ if (seen.has(key))
1075
+ continue;
1076
+ seen.add(key);
1077
+ observations.push({
1078
+ sessionId: session.sessionId,
1079
+ updatedAt: Number.isFinite(session.updatedAt) ? session.updatedAt : 0,
1080
+ blank: isBlank(session),
1081
+ // 与 `toSessionRow` 的 `running` 同式 ⇒ 「只有 subagent 在跑」也算运行中(D3a)。
1082
+ running: session.running === true || subagentCountOf(counts, session.sessionId) > 0,
1083
+ subagent: isSubagentSession(session),
1084
+ archived: archived.has(session.sessionId),
1085
+ });
1086
+ }
1087
+ // ── N1/I3:归档会话**不在树里**(`buildProjects` 已剔除)⇒ 必须从独立通道补投影 ──
1088
+ // 真实链路形态:`archivedSessionIds` 来自 `~/.dsh/storages/workspace.json` 的
1089
+ // `global.archivedSessionIds`(实测 173 条,全部带 `session-` 前缀),树里**不含**它们。
1090
+ // 补投影后 `observeTopZone` 的 `seen` 才真正覆盖归档会话(I3 的修复点)。
1091
+ for (const raw of source.archivedSessionIds) {
1092
+ if (typeof raw !== 'string' || raw === '')
1093
+ continue;
1094
+ const key = normalizeSessionId(raw);
1095
+ if (seen.has(key))
1096
+ continue;
1097
+ seen.add(key);
1098
+ observations.push({
1099
+ sessionId: raw,
1100
+ updatedAt: 0,
1101
+ blank: false,
1102
+ running: false,
1103
+ subagent: false,
1104
+ archived: true,
1105
+ });
1106
+ }
1107
+ return observations;
1108
+ }
1109
+ /**
1110
+ * 把 {@link TopZoneState} 投影成渲染期用的 {@link TopZoneInput}(T5,**纯函数**)。
1111
+ *
1112
+ * `runningSessionIds` 直接从观测轨迹(`runningOf`)里取 —— 它就是**聚合后**的口径
1113
+ * (见 {@link observationsOf}),与 `RenderRow.running` 同源。
1114
+ *
1115
+ * @param state 顶部区状态机状态。
1116
+ * @returns 渲染期输入(全部为归一化 id)。
1117
+ */
1118
+ export function topZoneInputOf(state) {
1119
+ const runningSessionIds = [];
1120
+ for (const [id, running] of Object.entries(state.runningOf)) {
1121
+ if (running === true)
1122
+ runningSessionIds.push(id);
1123
+ }
1124
+ return {
1125
+ runningSessionIds,
1126
+ newSessionIds: state.newSessionIds,
1127
+ // T9 缺陷 1:把落表台账一并投影进渲染期输入 —— 已落表的新会话不再被渲染期提升,
1128
+ // 否则用户把它拖到分组内其他位置后会被搬回原位(真人 GUI 复验的「弹回」缺陷)。
1129
+ writtenNewSessionIds: state.writtenNewSessionIds,
1130
+ };
1131
+ }
1132
+ /** 是否被折叠(`true` 才算;缺省 / 无表都视为展开,与原生一致)。 */
1133
+ function isCollapsed(keys, key) {
1134
+ return keys !== undefined && keys[key] === true;
1135
+ }
1136
+ /** 会话排序:`updatedAt` 降序,同值按 `sessionId` 升序(确定性 tiebreak)。 */
1137
+ function byRecency(a, b) {
1138
+ if (a.updatedAt !== b.updatedAt)
1139
+ return b.updatedAt - a.updatedAt;
1140
+ if (a.sessionId === b.sessionId)
1141
+ return 0;
1142
+ return a.sessionId < b.sessionId ? -1 : 1;
1143
+ }
1144
+ /** 拷贝后排序(不改入参)。 */
1145
+ function sortedByRecency(sessions) {
1146
+ return [...sessions].sort(byRecency);
1147
+ }
1148
+ /**
1149
+ * 「最近」分区的排序键:`max(updatedAt, 有限的 lastActivityAt)`(2026-10-29 RAS1/RAS4)。
1150
+ *
1151
+ * - `lastActivityAt` 缺失 / 非有限数字 ⇒ 回退 `updatedAt`(与 WSR6 旧行为逐字一致)。
1152
+ * - `lastActivityAt` 比 `updatedAt` 旧 ⇒ 仍取 `updatedAt`(不降低排序键)。
1153
+ * - `updatedAt` 本身非法 ⇒ 该边按 `0` 处理,保证结果恒为有限数字。
1154
+ *
1155
+ * ⚠️ **只有**「最近」分区使用本函数;工作区树 / 顶部区 / 手动顺序不得消费它。
1156
+ */
1157
+ export function recentActivityOf(session) {
1158
+ const updatedAt = Number.isFinite(session.updatedAt) ? session.updatedAt : 0;
1159
+ const lastActivityAt = typeof session.lastActivityAt === 'number' && Number.isFinite(session.lastActivityAt)
1160
+ ? session.lastActivityAt
1161
+ : 0;
1162
+ return Math.max(updatedAt, lastActivityAt);
1163
+ }
1164
+ /** 「最近」分区排序:最后更新时间降序,同值按 `sessionId` 升序(确定性 tiebreak)。 */
1165
+ function byRecentActivity(a, b) {
1166
+ const delta = recentActivityOf(b) - recentActivityOf(a);
1167
+ if (delta !== 0)
1168
+ return delta;
1169
+ if (a.sessionId === b.sessionId)
1170
+ return 0;
1171
+ return a.sessionId < b.sessionId ? -1 : 1;
1172
+ }
1173
+ /** 路径 basename(同时接受 `/` 与 `\`,忽略尾分隔符)。 */
1174
+ function basenameOf(path) {
1175
+ if (path === undefined)
1176
+ return '';
1177
+ const trimmed = path.replace(/[/\\]+$/, '');
1178
+ const separator = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
1179
+ return trimmed.slice(separator + 1);
1180
+ }
1181
+ /** 会话显示标题:blank 与空标题都退化为 `session.new`(原生 `displayTitle` 语义)。 */
1182
+ function sessionLabelOf(session, titleOf, t) {
1183
+ if (isBlank(session))
1184
+ return t('session.new');
1185
+ // `titleOf` 的**契约签名**是 `=> string`,但运行时会返回 `undefined` / `null`
1186
+ // (`SessionRowLike.title` 本身可选,最自然的实现就是 `(s) => s.title`),
1187
+ // 因此按 `unknown` 收窄:非字符串(含 undefined / null / 数字)一律回退,
1188
+ // 纯空白标题也回退。返回值**保证**是 string(§2.2 冻结的 `RenderRow.label: string`)。
1189
+ const raw = titleOf(session);
1190
+ return typeof raw === 'string' && raw.trim() !== '' ? raw : t('session.new');
1191
+ }
1192
+ /**
1193
+ * 单节点截断:保留**输入顺序**里的前 `limit` 条非 blank 会话(逐字对齐原生
1194
+ * `collapsedSessionRows` 的「前 N 条」部分)。
1195
+ *
1196
+ * 行为:
1197
+ * - `blank === true` 的会话始终保留且**不占**名额(原生:`if (session.blank) return true`);
1198
+ * - 其余会话按输入顺序保留前 `limit` 条(原生:`ordinaryCount >= limit ⇒ false`);
1199
+ * - `limit <= 0` 按 0 处理(只留 blank 的);
1200
+ * - `hiddenCount = sessions.length - visible.length`(原生同式)。
1201
+ *
1202
+ * ⚠️ **T13(2026-09-22 用户终裁):本函数不再接受 `currentSessionId`。**
1203
+ * 曾经存在的「当前会话保底进前 limit 条」(`promote` 分支)已**整体删除**:它在 T11
1204
+ * 删除 `isCurrent` 置顶后变成**可达**,使「把当前会话拖到第 6 位之后」出现**视觉零位移**
1205
+ * (持久表已变、渲染未变 —— 与用户投诉的首要缺陷同形)。用户裁决「**拖拽顺序完全优先**」,
1206
+ * 并明确接受副作用(当前会话若被截断到不可见,就是看不见)。
1207
+ *
1208
+ * 调用方({@link emitContainer})因此**只**按顺序截断,不再传任何「当前会话」线索 ——
1209
+ * 渲染层对已结束会话的位置**完全**由持久拖拽顺序决定。调用方若还想让某条会话必进可见区,
1210
+ * 唯一正当途径是**渲染期置顶**({@link topZoneSessionKeys} → `applyManualOrder` 的
1211
+ * `pinnedKeys`,运行中 / 尚未落表的新会话),那是**先于**截断生效的另一机制。
1212
+ *
1213
+ * @param sessions 输入会话(**不被修改**,返回的是同一批引用)。
1214
+ * @param limit 每个容器的非 blank 可见上限;非有限值按 0 处理。
1215
+ * @returns 可见会话(保持输入顺序)与被隐藏条数。
1216
+ */
1217
+ export function truncateSessions(sessions, limit) {
1218
+ const quota = Number.isFinite(limit) ? Math.max(0, Math.floor(limit)) : 0;
1219
+ const visible = [];
1220
+ let ordinary = 0;
1221
+ for (let i = 0; i < sessions.length; i += 1) {
1222
+ const session = sessions[i];
1223
+ if (isBlank(session)) {
1224
+ visible.push(session);
1225
+ continue;
1226
+ }
1227
+ if (ordinary < quota) {
1228
+ visible.push(session);
1229
+ ordinary += 1;
1230
+ }
1231
+ }
1232
+ return { visible, hiddenCount: sessions.length - visible.length };
1233
+ }
1234
+ /**
1235
+ * 子代理折叠:`parentSessionId` 指向**同组内**存在的父会话时挂为子行(深度 +1)。
1236
+ *
1237
+ * 规则:
1238
+ * - 顶层会话 `depth: 0`,直接子代理 `depth: 1`;不支持更深嵌套;
1239
+ * - 兜底:父会话不在本组内、父会话就是自己、或父会话**自己也是子代理**时,该会话
1240
+ * 平铺为 `depth: 0`(不凭空多缩进,也不丢);
1241
+ * - 父 id 与候选父 id 都先做 `session-` 前缀归一化后再比较(输出仍是原对象);
1242
+ * - 输出顺序:每个顶层会话后面紧跟它的子代理,子代理之间保持输入顺序;
1243
+ * - 环(A→B→A)软失败:环上成员按顶层处理,不抛错、不丢行(同原生 `flattenLineage`)。
1244
+ *
1245
+ * @param sessions 同一容器内的会话(**不被修改**)。
1246
+ * @returns 从容器根部展平的 `{ session, depth }` 序列。
1247
+ */
1248
+ export function nestSubagents(sessions) {
1249
+ const byNormalizedId = new Map();
1250
+ for (const session of sessions) {
1251
+ const key = normalizeSessionId(session.sessionId);
1252
+ if (!byNormalizedId.has(key))
1253
+ byNormalizedId.set(key, session);
1254
+ }
1255
+ const childMemo = new Map();
1256
+ const visiting = new Set();
1257
+ /** 该会话是否是「挂在某个 depth 0 父会话下的子代」。 */
1258
+ const isChild = (session) => {
1259
+ const cached = childMemo.get(session);
1260
+ if (cached !== undefined)
1261
+ return cached;
1262
+ if (visiting.has(session))
1263
+ return false;
1264
+ const parentId = session.parentSessionId;
1265
+ if (parentId === undefined)
1266
+ return false;
1267
+ const parent = byNormalizedId.get(normalizeSessionId(parentId));
1268
+ if (parent === undefined || parent === session)
1269
+ return false;
1270
+ visiting.add(session);
1271
+ const parentIsChild = isChild(parent);
1272
+ visiting.delete(session);
1273
+ const result = !parentIsChild;
1274
+ childMemo.set(session, result);
1275
+ return result;
1276
+ };
1277
+ const childrenOf = new Map();
1278
+ const roots = [];
1279
+ for (const session of sessions) {
1280
+ if (isChild(session)) {
1281
+ const parent = byNormalizedId.get(normalizeSessionId(session.parentSessionId ?? ''));
1282
+ if (parent === undefined) {
1283
+ roots.push(session);
1284
+ continue;
1285
+ }
1286
+ const siblings = childrenOf.get(parent);
1287
+ if (siblings === undefined)
1288
+ childrenOf.set(parent, [session]);
1289
+ else
1290
+ siblings.push(session);
1291
+ }
1292
+ else {
1293
+ roots.push(session);
1294
+ }
1295
+ }
1296
+ const flattened = [];
1297
+ for (const root of roots) {
1298
+ flattened.push({ session: root, depth: 0 });
1299
+ const children = childrenOf.get(root);
1300
+ if (children === undefined)
1301
+ continue;
1302
+ for (const child of children)
1303
+ flattened.push({ session: child, depth: 1 });
1304
+ }
1305
+ return flattened;
1306
+ }
1307
+ /** 把项目节点划分成若干会话容器(顺序即渲染顺序,不含展开态判断)。 */
1308
+ function containersOfProject(project, context) {
1309
+ const projectKey = `p:${project.key}`;
1310
+ // D11(2026-09-21 用户决策变更):**git 项目一律产生 worktree 子行**,单 worktree 也
1311
+ // 不再平铺 —— `+`(新建会话)必须落在 worktree 行上,项目行只留 `…`。
1312
+ // `flat` 容器因此**只留给非 git 工作区**(它的会话直接挂项目行下)。
1313
+ const hasWorktreeRows = project.isGit === true;
1314
+ const worktrees = [];
1315
+ if (hasWorktreeRows) {
1316
+ for (const node of project.worktrees) {
1317
+ worktrees.push({
1318
+ node,
1319
+ spec: {
1320
+ key: `w:${node.path}`,
1321
+ kind: 'worktree',
1322
+ depth: 2,
1323
+ sessions: node.sessions,
1324
+ project,
1325
+ worktree: node,
1326
+ },
1327
+ });
1328
+ }
1329
+ }
1330
+ const result = {
1331
+ project,
1332
+ projectKey,
1333
+ hasWorktreeRows,
1334
+ worktrees,
1335
+ };
1336
+ if (!hasWorktreeRows) {
1337
+ // 非 git 工作区:会话平铺在项目行下(`flatSessions`)。此容器**不带** `worktree`:
1338
+ // 非 git 工作区没有 worktree,也就没有分支名可搜(搜索 haystack 自然为空)。
1339
+ result.flat = {
1340
+ key: projectKey,
1341
+ kind: 'project',
1342
+ depth: 1,
1343
+ sessions: project.flatSessions,
1344
+ project,
1345
+ };
1346
+ }
1347
+ // history 容器行的**存在性必须与子行同源**:只用 `project.history.length > 0`
1348
+ // 会在「history 里全是 blank 且非当前」时建出一个 `sessionCount = 0` 的空容器行。
1349
+ // 所以先过一遍与 `emitContainer` 完全相同的可见性判定(同一个 `isVisibleMember`)。
1350
+ if (hasVisibleMembers(project.history, context)) {
1351
+ result.history = {
1352
+ key: `h:${project.key}`,
1353
+ kind: 'history',
1354
+ depth: 2,
1355
+ sessions: project.history,
1356
+ project,
1357
+ };
1358
+ }
1359
+ return result;
1360
+ }
1361
+ /** 未分组容器(复用 project 行表达;见 {@link UNGROUPED_KEY})。 */
1362
+ function ungroupedContainer(input) {
1363
+ return {
1364
+ key: `p:${UNGROUPED_KEY}`,
1365
+ kind: 'project',
1366
+ depth: 1,
1367
+ sessions: input.ungrouped,
1368
+ };
1369
+ }
1370
+ /**
1371
+ * 单条会话是否在容器里可见 —— **唯一的会话可见性谓词**,逐字对齐原生 `sessionVisible`:
1372
+ *
1373
+ * ```js
1374
+ * session.origin !== "subagent" && !archived.has(session.id) && (!session.blank || session.id === current)
1375
+ * ```
1376
+ *
1377
+ * 三处调用者全部走它,因此不可能再出现「树里滤了、搜索里忘了」这类分叉:
1378
+ * - `containersOfProject` —— 判断 history 容器该不该建;
1379
+ * - `visibleMembers` —— 树上真正的会话行;
1380
+ * - `collectSearchCandidates` —— 搜索候选。
1381
+ *
1382
+ * 注意 `isCurrent` **不**因此豁免:当前会话若本身是子代理,它同样不渲染(原生亦然)。
1383
+ * ⚠️ **T13**:`currentSessionId` 在本文件里**只**服务四件事 —— ① 本谓词的「blank 会话豁免」;
1384
+ * ② {@link toSessionRow} 的 `isCurrent` 行高亮;③ {@link topZoneSessionKeys} 的**兼容形参位**
1385
+ * (函数体已 `void` 掉,行为中性);④ **2026-10-22 DR4**:{@link isCurrentBlankSession}
1386
+ * 用它把「新会话」占位行排到容器最前、并由 {@link isSessionDragLocked} 锁住拖拽。
1387
+ * 它**不**影响截断(`truncateSessions` 已无该参数,D12 保底已删除),也**不**参与
1388
+ * 「普通会话」的置顶判定。
1389
+ *
1390
+ * 本谓词**不**参与需求 A 的 `running` 聚合:子代理行被过滤掉之后,其 `running` 已经
1391
+ * 通过 {@link indexRunningSubagentDescendants} 汇总进父行的 `subagentCount`
1392
+ * (见 {@link toSessionRow})。
1393
+ */
1394
+ /**
1395
+ * 判断某会话是否是当前打开的会话(`session-` 前缀归一化比较,2026-10-21 WSR3 / AC3)。
1396
+ */
1397
+ function isCurrentSession(sessionId, currentSessionId) {
1398
+ if (typeof sessionId !== 'string' || sessionId === '')
1399
+ return false;
1400
+ if (typeof currentSessionId !== 'string' || currentSessionId === '')
1401
+ return false;
1402
+ const a = normalizeSessionId(sessionId);
1403
+ const b = normalizeSessionId(currentSessionId);
1404
+ return a !== '' && a === b;
1405
+ }
1406
+ function isVisibleMember(session, context) {
1407
+ return (!isSubagentSession(session) &&
1408
+ !context.archived.has(session.sessionId) &&
1409
+ (!isBlank(session) || isCurrentSession(session.sessionId, context.currentSessionId)));
1410
+ }
1411
+ /** 容器的显示过滤(谓词见 {@link isVisibleMember})。 */
1412
+ function visibleMembers(spec, context) {
1413
+ return spec.sessions.filter((session) => isVisibleMember(session, context));
1414
+ }
1415
+ /**
1416
+ * 容器是否**有可见成员**(=「该不该建容器行」的唯一判据)。
1417
+ *
1418
+ * 不变式:`hasVisibleMembers(x, ctx)` 为真 ⟺ `emitContainer` 会产出至少一条子行
1419
+ * (`sessionCount > 0` 或至少一条 `more` 行,因为 `hiddenCount > 0` 也蕴含可见成员非空)。
1420
+ */
1421
+ function hasVisibleMembers(sessions, context) {
1422
+ return sessions.some((session) => isVisibleMember(session, context));
1423
+ }
1424
+ /** 造一个 `session` 行。 */
1425
+ function toSessionRow(session, depth, subagentCount, spec, context) {
1426
+ const keyPrefix = spec.kind === 'recent' ? 'rs:' : 's:';
1427
+ const base = {
1428
+ kind: 'session',
1429
+ key: `${keyPrefix}${session.sessionId}`,
1430
+ sessionId: session.sessionId,
1431
+ label: sessionLabelOf(session, context.titleOf, context.t),
1432
+ depth,
1433
+ updatedAt: session.updatedAt,
1434
+ // 需求 A(2026-09-21):主 agent 空闲、但有**运行中的子代理后代**时,父行状态点同样
1435
+ // 是「运行中」—— 对齐原生 `sessionStatuses`(`dsh-client-ui-workspace/lib/client.js`
1436
+ // 的 `if (subagents !== void 0) return [subagents]`:`runningSubagentCount > 0` ⇒
1437
+ // 主状态点就是 ongoing)。原实现只读会话自己的 summary ⇒ 此场景退化成灰色 idle。
1438
+ //
1439
+ // `subagentCount` 就是原生 `runningSubagentCount`(所有层级的**运行中**子代理后代数,
1440
+ // 见 {@link indexRunningSubagentDescendants}),所以这里不需要任何新数据源。
1441
+ // 放在本函数(而不是各调用点)⇒ 树(`emitContainer`)与搜索(`buildSearchRows`)
1442
+ // 两条路径自动同源,不可能「树里改了、搜索里忘了」。
1443
+ running: session.running === true || subagentCount > 0,
1444
+ completed: session.completed === true,
1445
+ blank: isBlank(session),
1446
+ subagentCount,
1447
+ isCurrent: isCurrentSession(session.sessionId, context.currentSessionId),
1448
+ parentKey: spec.key,
1449
+ parentKind: spec.kind,
1450
+ };
1451
+ return session.pendingInteraction === undefined
1452
+ ? base
1453
+ : { ...base, pendingInteraction: session.pendingInteraction };
1454
+ }
1455
+ /**
1456
+ * 渐进式截断(2026-11-14 PX1–PX3):顶层会话 ≤ 5 ⇒ 全部可见、无 more 行;否则按展开层级
1457
+ * 显示前 {@link visibleSessionLimit} 条(blank 不计名额,同 {@link truncateSessions}),
1458
+ * 层级 > 0 或仍有剩余时产出一条 more 行。旧式 `expandedAllKeys[key] === true` 视为无限层级。
1459
+ */
1460
+ function truncateByLevel(heads, key, context, parentKind = 'project', depth = 1) {
1461
+ if (heads.length <= COLLAPSED_SESSION_LIMIT)
1462
+ return { selected: heads, hiddenCount: 0 };
1463
+ const legacyAll = context.expandedAllKeys?.[key] === true;
1464
+ const level = expandLevelOf(context.expandLevels, key);
1465
+ const truncated = legacyAll
1466
+ ? { visible: heads, hiddenCount: 0 }
1467
+ : truncateSessions(heads, visibleSessionLimit(level));
1468
+ const canCollapse = legacyAll || level > 0;
1469
+ if (truncated.hiddenCount === 0 && !canCollapse)
1470
+ return { selected: truncated.visible, hiddenCount: 0 };
1471
+ return {
1472
+ selected: truncated.visible,
1473
+ hiddenCount: truncated.hiddenCount,
1474
+ more: {
1475
+ kind: 'more',
1476
+ key: `m:${key}`,
1477
+ parentKey: key,
1478
+ parentKind,
1479
+ hiddenCount: truncated.hiddenCount,
1480
+ nextCount: nextExpandCount(level, truncated.hiddenCount),
1481
+ canCollapse,
1482
+ depth,
1483
+ },
1484
+ };
1485
+ }
1486
+ /**
1487
+ * 推导一个容器的行:过滤 → 排序 → 5 条截断 → more 行。
1488
+ *
1489
+ * 计数只统计**顶层会话**(= 已过滤掉子代理后的可见会话),且**不**受截断影响
1490
+ * (原生 `sessionCount: g.sessions.length` 在截断之前)。
1491
+ *
1492
+ * more 行的存在性只取决于「容器是否真的超过 `COLLAPSED_SESSION_LIMIT` 条**顶层**会话」:
1493
+ * 超过 ⇒ 一定有 more 行(`expandedAll` 时也有,用于「收起」);不超过 ⇒ 一定没有。
1494
+ * `hiddenCount` 恒为 `truncateSessions(heads, …).hiddenCount`(折叠时隐藏的条数),
1495
+ * 与当前是否 `expandedAll` 无关 —— 它是渲染层「展开其余 {n} 个」的 n 的来源。
1496
+ */
1497
+ function emitContainer(spec, context) {
1498
+ // 过滤已排除 `origin === 'subagent'`(`isVisibleMember`)⇒ 这里全部是顶层会话,
1499
+ // 不再需要 `nestSubagents` 折叠子行。子代理只以 `subagentCount` 胶囊的形式出现在父行上。
1500
+ //
1501
+ // 顺序:**先默认排序(updatedAt 降序),再叠加手动顺序**(D10)。次序不能颠倒 ——
1502
+ // `applyManualOrder` 把「不在手动列表里的会话」按**传入顺序**追加到末尾,所以传入的
1503
+ // 必须是已按 `updatedAt` 排好的序列,新会话才会落在末尾而不是乱序。
1504
+ //
1505
+ // ── 顶部区(T11,2026-09-22 用户终裁)────────────────────────────────────
1506
+ // 每个容器内,**正在运行**的会话(自身 running 或任意层级有运行中的子代理)被提到
1507
+ // **本容器最前**,且**先于**下面的 5 条截断生效。⚠️ 措辞准确化(T13 的 N-6):
1508
+ // 「先于截断生效」**不**等于「一定可见」—— 顶部区成员超过 `COLLAPSED_SESSION_LIMIT`
1509
+ // 条时(例如 6 条并发运行中的会话),超出的部分**仍会被截断**(有意行为,由
1510
+ // `T5/截断: 顶部区成员数 > 5 时,只有前 5 条可见` 锁定)。
1511
+ //
1512
+ // ⚠️ 用户终裁删除了此前的两类成员:「刚结束保留」与「当前会话置顶」。
1513
+ // 已结束的会话(含用户正在查看的旧会话、含刚跑完的会话)**不再固定置顶** —— 位置完全
1514
+ // 由持久拖拽顺序(`manualOrder`)决定,因此它们**必须可正常拖动**。
1515
+ // 唯一保留的额外成员是「尚未落表的新会话」(D2/D3d),判据与排序全在
1516
+ // {@link topZoneSessionKeys} 里,本函数不再自己判断。
1517
+ //
1518
+ // ── 占位行(2026-10-22 DR4,用户复验「复用空白会话」后的追加缺陷)──────────────
1519
+ // **当前打开的空白会话**(=「新会话」占位行)恒在本容器**最前**,且先于顶部区与截断:
1520
+ // 用户点 `+` 之后第一眼必须看到自己正在写的那条。判据在
1521
+ // {@link isCurrentBlankSession},与宿主 `sectionMembers` / `pinCurrentBlank` 同语义。
1522
+ // 该行**不起拖**({@link isSessionDragLocked}),因此「固定最前」不会出现「拖完弹回」。
1523
+ //
1524
+ // ⚠️ 顶部区 / 占位行都**不写 localStorage**(`effectiveOrder` 刻意不传任何置顶);只有
1525
+ // D2 的「新会话插入固化表」是 `sidebar.tsx` 的独立写入动作。
1526
+ const visible = visibleMembers(spec, context);
1527
+ const placeholder = visible.find((session) => isCurrentBlankSession(session, context.currentSessionId));
1528
+ const pinnedKeys = [
1529
+ ...(placeholder === undefined ? [] : [placeholder.sessionId]),
1530
+ ...(topZoneSessionKeys(visible, context.currentSessionId, spec.key, context.topZone) ?? []),
1531
+ ];
1532
+ const heads = applyManualOrder(sortedByRecency(visible), sessionOrderOf(context.manualOrder, spec.key), (session) => session.sessionId, pinnedKeys);
1533
+ // 截断在手动顺序**之后**:手动排到前面的会话必须能进前 `COLLAPSED_SESSION_LIMIT` 条,
1534
+ // 否则用户拖了却看不见(PRD D10 验收)。
1535
+ const truncation = truncateByLevel(heads, spec.key, context, spec.kind, spec.depth);
1536
+ const selected = truncation.selected;
1537
+ const hiddenCount = truncation.hiddenCount;
1538
+ const rows = selected.map((session) => toSessionRow(session, spec.depth, subagentCountOf(context.subagentRunningCounts, session.sessionId), spec, context));
1539
+ if (truncation.more !== undefined)
1540
+ rows.push(truncation.more);
1541
+ return {
1542
+ rows,
1543
+ sessionCount: heads.length,
1544
+ runningCount: heads.filter((session) => session.running === true).length,
1545
+ pendingCount: heads.filter((session) => session.pendingInteraction !== undefined).length,
1546
+ // 2026-10-20 运行中任务高亮(RT1):**截断前**的 `heads`,聚合口径与
1547
+ // `toSessionRow` 的 `running` **逐字同源**(同一索引、同一 helper)。
1548
+ // 只有子代理在跑时 `runningCount` 仍为 0,但这里为 true —— 有意为之,见
1549
+ // `RenderRow` 的 JSDoc 与 `docs/INTERFACES.md` §2.2.1。
1550
+ hasRunningTasks: heads.some((session) => session.running === true ||
1551
+ subagentCountOf(context.subagentRunningCounts, session.sessionId) > 0),
1552
+ hiddenCount,
1553
+ };
1554
+ }
1555
+ /** worktree 行的 label / sublabel(分支名优先,无分支用目录 basename)。 */
1556
+ function worktreeLabels(node, t) {
1557
+ const base = basenameOf(node.path);
1558
+ const label = node.branch !== undefined && node.branch !== '' ? node.branch : base;
1559
+ return label === base ? { label } : { label, sublabel: base };
1560
+ }
1561
+ /**
1562
+ * 从项目 `key` 解出 workspaceId —— **仅非 git 工作区**(key 形态为 `ws:<workspaceId>`)。
1563
+ *
1564
+ * 存在的理由:**非 git 工作区的 `worktrees` 恒为空数组**(`buildProjects` 的 `'flat'` 分支
1565
+ * 不建 worktree 节点),所以它的工作区 id 既不在任何 worktree 节点上,也只能从 key 解出。
1566
+ * 这是渲染层「在该工作区新建会话」(非 git 行 hover 的 `+`)**唯一**的 id 来源 ——
1567
+ * 漏掉它,那一行的 `+` 会因为 `workspaceId === undefined` 而根本不渲染。
1568
+ *
1569
+ * git 项目的 key 是 commonDir,本函数恒返回 `undefined`(它的 id 要从 worktree 节点取)。
1570
+ *
1571
+ * 导出以便单测覆盖(`src/sidebar.tsx` 是 `.tsx`,不进 `lib/`,逻辑无法被 `node --test` 直接测)。
1572
+ */
1573
+ export function workspaceIdFromProjectKey(key) {
1574
+ return key.startsWith('ws:') ? key.slice('ws:'.length) : undefined;
1575
+ }
1576
+ /** project 行的 path / workspaceId(非 git 工作区才有 path)。 */
1577
+ function projectIdentity(project) {
1578
+ const identity = {};
1579
+ const workspaceId = workspaceIdFromProjectKey(project.key);
1580
+ if (workspaceId !== undefined)
1581
+ identity.workspaceId = workspaceId;
1582
+ if (project.isGit !== true) {
1583
+ const path = project.mainPath ?? project.flatSessions[0]?.cwd;
1584
+ if (path !== undefined)
1585
+ identity.path = path;
1586
+ }
1587
+ return identity;
1588
+ }
1589
+ /**
1590
+ * 收集搜索候选:所有容器里的**所有**可见会话(不过滤展开态、不截断)。
1591
+ *
1592
+ * 可见性走与树**同一个** {@link isVisibleMember} ⇒ 子代理(`origin === 'subagent'`)
1593
+ * 与归档会话一样搜不到,不存在「树里滤了、搜索里忘了」的分叉。
1594
+ *
1595
+ * 匹配源(大小写不敏感子串):会话标题(blank 用 `session.new`)、所属项目名、
1596
+ * 所属 worktree 的分支名 / 路径 basename / worktree 标题(即工作区名,PRD D20)、
1597
+ * 会话 cwd 的 basename(未分组会话的主要上下文)。
1598
+ */
1599
+ /** 过滤掉被客户端或服务端标记为已归档的工作空间。 */
1600
+ function activeProjectsOf(input) {
1601
+ const keys = input.archivedProjectKeys;
1602
+ if (!Array.isArray(keys) || keys.length === 0)
1603
+ return input.projects;
1604
+ const archived = new Set();
1605
+ for (const key of keys) {
1606
+ if (typeof key === 'string' && key !== '') {
1607
+ archived.add(key);
1608
+ if (key.startsWith('p:'))
1609
+ archived.add(key.slice(2));
1610
+ }
1611
+ }
1612
+ if (archived.size === 0)
1613
+ return input.projects;
1614
+ return input.projects.filter((project) => !archived.has(project.key));
1615
+ }
1616
+ function collectSearchCandidates(input, query, context) {
1617
+ const specs = [];
1618
+ for (const project of activeProjectsOf(input)) {
1619
+ const containers = containersOfProject(project, context);
1620
+ for (const entry of containers.worktrees)
1621
+ specs.push(entry.spec);
1622
+ if (containers.flat !== undefined)
1623
+ specs.push(containers.flat);
1624
+ if (containers.history !== undefined)
1625
+ specs.push(containers.history);
1626
+ }
1627
+ if (hasVisibleMembers(input.ungrouped, context))
1628
+ specs.push(ungroupedContainer(input));
1629
+ const candidates = [];
1630
+ const seen = new Set();
1631
+ for (const spec of specs) {
1632
+ const members = visibleMembers(spec, context);
1633
+ const projectName = spec.project?.title ?? '';
1634
+ const worktreeHaystacks = spec.worktree === undefined
1635
+ ? []
1636
+ : [spec.worktree.branch ?? '', basenameOf(spec.worktree.path), spec.worktree.title ?? ''];
1637
+ for (const session of members) {
1638
+ if (seen.has(session.sessionId))
1639
+ continue;
1640
+ const haystacks = [
1641
+ sessionLabelOf(session, input.titleOf, input.t),
1642
+ projectName,
1643
+ basenameOf(session.cwd),
1644
+ ...worktreeHaystacks,
1645
+ ];
1646
+ const hit = haystacks.some((text) => text.toLowerCase().includes(query));
1647
+ if (!hit)
1648
+ continue;
1649
+ seen.add(session.sessionId);
1650
+ candidates.push({
1651
+ session,
1652
+ spec,
1653
+ subagentCount: subagentCountOf(context.subagentRunningCounts, session.sessionId),
1654
+ });
1655
+ }
1656
+ }
1657
+ return candidates;
1658
+ }
1659
+ /** 搜索模式:扁平输出匹配到的会话行(`depth: 0`,保留真实归属),按最近更新排序。 */
1660
+ function buildSearchRows(input, context, query) {
1661
+ const candidates = collectSearchCandidates(input, query, context);
1662
+ // **搜索模式刻意不应用手动顺序**(D10):搜索结果按 `updatedAt` 降序更自然 ——
1663
+ // 用户搜一个词是为了找最近用过的那个,而不是找回自己上个月拖出来的位置;
1664
+ // 且手动顺序是**容器内**的相对顺序,跨容器的扁平结果里没有它成立的前提。
1665
+ // 这条与「树模式应用手动顺序」的差异是有意为之,已写入 `docs/INTERFACES.md` §2.3。
1666
+ candidates.sort((a, b) => byRecency(a.session, b.session));
1667
+ return candidates.map((candidate) => toSessionRow(candidate.session, 0, candidate.subagentCount, candidate.spec, context));
1668
+ }
1669
+ /**
1670
+ * 取三层各自的**完整生效顺序**(默认顺序 + 已应用的手动顺序)。
1671
+ *
1672
+ * 与 {@link buildRows} 走**同一批**内部函数(`containersOfProject` / `visibleMembers` /
1673
+ * {@link sortedByRecency} / {@link applyManualOrder}),因此不可能与树里看到的顺序分叉 ——
1674
+ * 这是本函数存在的全部理由(容器 key 的推导规则只有一处实现)。
1675
+ *
1676
+ * 与 `buildRows` 的两处**有意**差异:
1677
+ * - **不应用折叠与 5 条截断**:返回的是每个容器的全部可见成员(见 {@link EffectiveOrder});
1678
+ * - **不产出未分组行**:`projects` 里没有 `UNGROUPED_KEY`(它不是真实项目,§2.6 裁定 1),
1679
+ * 但未分组的**会话**照常进 `sessions`(键 = `p:${UNGROUPED_KEY}`)。
1680
+ *
1681
+ * ⚠️ **第三处有意差异(T11,2026-09-22 用户终裁)**:本函数**不应用任何运行时顶部区**。
1682
+ * 顶部区是**纯运行时推导**(由会话此刻是否在跑、以及新会话是否已落表决定),而本函数的输出
1683
+ * 正是 `commitDrag` 首次拖拽时**全量固化进 `localStorage`** 的那份顺序
1684
+ * (`src/sidebar.tsx` 的 `commitDrag`:`effectiveOrder({ ...treeInput, manualOrder: undefined })`)。
1685
+ * 若这里也应用顶部区,就会把「运行时置顶」变成「持久化钉在第 1 位」—— 用户关掉那个会话后
1686
+ * 它仍赖在最前面,且持久顺序被污染。所以本函数把 `context.topZone` **硬置 `undefined`**,
1687
+ * 返回的永远是「不含任何运行时置顶的真实顺序」。**这是被测试锁定的不变式**
1688
+ * (见 `test/tree-model.test.mjs` 的 `effectiveOrder` 持久化用例)。
1689
+ *
1690
+ * `input.manualOrder` 缺省或 `manual !== true` 时,返回的就是**纯默认顺序** ——
1691
+ * 这正是「首次拖拽时固化全量顺序」所需要的输入。
1692
+ *
1693
+ * @param input 与 `buildRows` 同一份入参。
1694
+ * @returns 三层的完整生效顺序。
1695
+ */
1696
+ export function effectiveOrder(input) {
1697
+ const context = {
1698
+ archived: new Set(input.archivedSessionIds),
1699
+ collapsedKeys: input.collapsedKeys,
1700
+ expandedAllKeys: input.expandedAllKeys,
1701
+ expandLevels: input.expandLevels,
1702
+ currentSessionId: input.currentSessionId,
1703
+ titleOf: input.titleOf,
1704
+ t: input.t,
1705
+ subagentRunningCounts: new Map(),
1706
+ manualOrder: input.manualOrder,
1707
+ // ⚠️ T5/T11:`effectiveOrder` **刻意不传 `topZone`** —— 与「不把运行时状态写进持久
1708
+ // 顺序」同一不变式,且这里连 `context.topZone` 都置 `undefined`,从结构上杜绝
1709
+ // 「运行时顶部区混进持久顺序」。
1710
+ topZone: undefined,
1711
+ };
1712
+ const order = (members, containerKey) =>
1713
+ // ⚠️ T11:这里**刻意不传**任何置顶 key —— 本函数的产物是首次拖拽时固化进
1714
+ // `localStorage` 的顺序,运行时顶部区绝不能进持久化(见函数 JSDoc 的第三处差异)。
1715
+ applyManualOrder(sortedByRecency(visibleMembers({ key: containerKey, kind: 'worktree', depth: 0, sessions: members }, context)), sessionOrderOf(input.manualOrder, containerKey), (session) => session.sessionId).map((session) => session.sessionId);
1716
+ const activeProjects = activeProjectsOf(input);
1717
+ const manualProjects = input.manualOrder?.manual === true ? input.manualOrder.projects : undefined;
1718
+ const projects = applyManualOrder(activeProjects, manualProjects, (project) => project.key).map((project) => project.key);
1719
+ const worktrees = new Map();
1720
+ const sessions = new Map();
1721
+ for (const project of activeProjects) {
1722
+ const containers = containersOfProject(project, context);
1723
+ const paths = applyManualOrder(containers.worktrees, worktreeOrderOf(input.manualOrder, project.key), (entry) => entry.node.path).map((entry) => entry.node.path);
1724
+ if (paths.length > 0)
1725
+ worktrees.set(project.key, paths);
1726
+ for (const entry of containers.worktrees) {
1727
+ sessions.set(entry.spec.key, order(entry.spec.sessions, entry.spec.key));
1728
+ }
1729
+ if (containers.flat !== undefined) {
1730
+ sessions.set(containers.flat.key, order(containers.flat.sessions, containers.flat.key));
1731
+ }
1732
+ if (containers.history !== undefined) {
1733
+ sessions.set(containers.history.key, order(containers.history.sessions, containers.history.key));
1734
+ }
1735
+ }
1736
+ if (hasVisibleMembers(input.ungrouped, context)) {
1737
+ const spec = ungroupedContainer(input);
1738
+ sessions.set(spec.key, order(spec.sessions, spec.key));
1739
+ }
1740
+ return { projects, worktrees, sessions };
1741
+ }
1742
+ /**
1743
+ * 把「被拖项 + 落点」换算成新的顺序列表(**纯函数**)。
1744
+ *
1745
+ * 语义与原生 `commitSessionDrag` 的可见项算法一致:
1746
+ * 1. 从当前列表里**摘掉**被拖项;
1747
+ * 2. 找到落点项在「摘掉之后」的下标;
1748
+ * 3. `before` ⇒ 插在它前面;`after` ⇒ 插在它后面。
1749
+ *
1750
+ * @param keys 当前**完整**顺序(默认顺序 + 已应用的手动顺序)。
1751
+ * @param draggedId 被拖项的 id。
1752
+ * @param overId 落点项的 id。
1753
+ * @param half 落点在行的上半(`before`)还是下半(`after`)。
1754
+ * @returns 新顺序;**无需改动**时返回 `null`(落点就是自己 / 已在原位 / 落点不在列表里)。
1755
+ * 返回 `null` 而不是原数组,是为了让调用方区分「拖了但没变化」与「真的重排了」——
1756
+ * 前者不该把 `manual` 置 true(否则用户只是原地抖一下鼠标就永久切到手动排序了)。
1757
+ */
1758
+ export function reorderKeys(keys, draggedId, overId, half) {
1759
+ if (draggedId === overId)
1760
+ return null;
1761
+ const sourceIndex = keys.indexOf(draggedId);
1762
+ if (sourceIndex === -1)
1763
+ return null;
1764
+ const withoutSource = keys.filter((key) => key !== draggedId);
1765
+ const overIndex = withoutSource.indexOf(overId);
1766
+ // 落点不在列表里(理论上不会发生:`over` 来自已渲染的行)⇒ 不动。
1767
+ if (overIndex === -1)
1768
+ return null;
1769
+ const insertAt = half === 'before' ? overIndex : overIndex + 1;
1770
+ // 已在原位 ⇒ 不产生「看似变化其实没变」的写入。
1771
+ if (insertAt === sourceIndex)
1772
+ return null;
1773
+ const next = [...withoutSource];
1774
+ next.splice(insertAt, 0, draggedId);
1775
+ return next;
1776
+ }
1777
+ /**
1778
+ * 把**持久手动顺序表**与「当前默认顺序」对齐(2026-10-22 DR6)。
1779
+ *
1780
+ * 规则(与渲染期 `applyManualOrder` 的表外项语义**逐字一致**):
1781
+ * 1. 表内项保持原相对顺序(含**当前不可见**的项 —— 归档会话/归档工作区的槽位因此不丢,
1782
+ * 取消归档后回到原位);
1783
+ * 2. 表外项按 `defaults` 的顺序**追加到末尾**(渲染期正是这样画的);
1784
+ * 3. 去重(同一 key 只认第一次出现)、忽略非字符串/空串;
1785
+ * 4. 纯函数:不修改入参,返回新数组。
1786
+ *
1787
+ * 为什么需要它(缺陷背景):`manualOrder` 是**首次拖拽时固化的快照**,之后新增的工作区 /
1788
+ * worktree / 会话都不在表里。`commitDrag` 旧实现直接拿持久表做 `reorderKeys`,而
1789
+ * `reorderKeys` 对「拖拽源不在表里」与「落点不在表里」都返回 `null` ⇒ **整次拖拽静默无效**
1790
+ * (用户看到的「拖不动 / 松手没反应」)。先对齐再换算,就能让新增项照常参与排序。
1791
+ *
1792
+ * @param order 持久表里的该层顺序(可能缺项 / 为空 / undefined)。
1793
+ * @param defaults 当前默认顺序(`effectiveOrder` 的产物,与渲染同源)。
1794
+ * @returns 对齐后的完整顺序(新数组)。
1795
+ */
1796
+ export function reconcileManualOrder(order, defaults) {
1797
+ const seen = new Set();
1798
+ const out = [];
1799
+ for (const raw of order ?? []) {
1800
+ if (typeof raw !== 'string' || raw === '' || seen.has(raw))
1801
+ continue;
1802
+ seen.add(raw);
1803
+ out.push(raw);
1804
+ }
1805
+ for (const key of defaults) {
1806
+ if (typeof key !== 'string' || key === '' || seen.has(key))
1807
+ continue;
1808
+ seen.add(key);
1809
+ out.push(key);
1810
+ }
1811
+ return out;
1812
+ }
1813
+ /**
1814
+ * **拖拽换算的唯一入口**(2026-10-22 DR6,替代 `commitDrag` 里直接调 `reorderKeys`)。
1815
+ *
1816
+ * = `reorderKeys(reconcileManualOrder(order, defaults), draggedId, overId, half)`:
1817
+ * 先把持久表与当前默认顺序对齐(补齐表外的新增项),再计算新顺序。
1818
+ *
1819
+ * 语义与 `reorderKeys` 逐字一致:拖到自己身上、已在原位、找不到落点 ⇒ `null`(不写表,
1820
+ * 不把用户「原地抖一下」误变成持久改动)。
1821
+ *
1822
+ * @param order 持久表里的该层顺序(手动模式);`undefined` = 非手动 ⇒ 直接用默认顺序。
1823
+ * @param defaults 该层当前默认顺序(`effectiveOrder` 的产物)。
1824
+ * @param draggedId 拖拽源 id(树里的真实形态,不带容器前缀)。
1825
+ * @param overId 落点 id(同上)。
1826
+ * @param half 落点在目标之前 / 之后。
1827
+ * @returns 新的顺序;无需改动 ⇒ `null`。
1828
+ */
1829
+ export function reorderManualScope(order, defaults, draggedId, overId, half) {
1830
+ return reorderKeys(reconcileManualOrder(order, defaults), draggedId, overId, half);
1831
+ }
1832
+ /**
1833
+ * 把树模型摊平成渲染行序列(已应用展开态、5 条截断、搜索过滤)。纯函数。
1834
+ *
1835
+ * 渲染顺序:
1836
+ * ```
1837
+ * [project 行]
1838
+ * [worktree 行] ← git 项目逐个(含单 worktree;保持宿主顺序)
1839
+ * [session 行] … ← depth 2
1840
+ * [more 行] ← 仅当被截断
1841
+ * [history 行] ← 仅当 project.history 有**可见成员**(非空且过滤后非空)
1842
+ * [session 行] … ← depth 2
1843
+ * [more 行]
1844
+ * [下一个 project 行]
1845
+ * …
1846
+ * [未分组行] ← 仅当 ungrouped 有**可见成员**时(project 行形态,key = `p:${UNGROUPED_KEY}`)
1847
+ * [session 行] … ← depth 1
1848
+ * [more 行]
1849
+ * ```
1850
+ *
1851
+ * **没有会话行是子代理**:`origin === 'subagent'` 的会话在任何容器里都不产生行
1852
+ * (原生 `sessionVisible`),它们只通过父行的 `subagentCount` 胶囊体现。
1853
+ *
1854
+ * 关键约束:
1855
+ * - D11(2026-09-21 修订):**git 项目**(`isGit === true`)恒产生 worktree 子行,
1856
+ * 会话挂 worktree 行下(`parentKind: 'worktree'`、`depth: 2`);只有**非 git 工作区**
1857
+ * 才平铺,会话直接挂 project 行下(`parentKind: 'project'`、`depth: 1`);
1858
+ * - 展开态:`collapsedKeys[key] === true` 才折叠(缺省展开);
1859
+ * - 每个会话容器各自独立应用 `truncateSessions(…, COLLAPSED_SESSION_LIMIT)`;
1860
+ * 容器内顶层会话数 `<= COLLAPSED_SESSION_LIMIT` ⇒ **不产生** more 行(没东西可折叠);
1861
+ * ⚠️ **T13**:截断**只**按传入顺序取前 N 条,**不再**为「当前会话」做任何保底 ——
1862
+ * 已结束会话的位置完全由持久拖拽顺序决定(见 {@link truncateSessions} 的 JSDoc);
1863
+ * - `expandedAllKeys[容器key] === true` 且容器**确实超过** `COLLAPSED_SESSION_LIMIT` 条时:
1864
+ * 全量输出该容器会话,**仍产出恰好一条** more 行,且其 `hiddenCount` 保留真实值
1865
+ * (=「若折叠会隐藏多少条」,即 `truncateSessions(...).hiddenCount`)—— 这条 more 行是
1866
+ * 用户回到折叠态的**唯一入口**(PRD US4「点击后全部展开,变为收起」)。渲染层按
1867
+ * `expandedAllKeys[parentKey] === true` 取 `sessions.collapse`,否则取
1868
+ * `sessions.expand`(契约 §2.6 裁定 2:more 行**无** label,取词在渲染层);
1869
+ * - `expandedAllKeys[容器key] !== true` 且被截断 ⇒ 前 `COLLAPSED_SESSION_LIMIT` 条 + 一条
1870
+ * more 行,`hiddenCount` = 隐藏条数(`truncateSessions` 的真实结果);
1871
+ * - 子代理在任何容器里都不出现;归档会话也不出现;blank 会话只显示当前那一条且不占名额;
1872
+ * - **父行状态点含子代理(需求 A,2026-09-21)**:`row.running = 该会话自己的 running ||
1873
+ * subagentCount > 0`(对齐原生 `sessionStatuses` 的 `runningSubagentCount > 0 ⇒ ongoing`)。
1874
+ * 多层链(depth 3)由 {@link indexRunningSubagentDescendants} 一并累加到顶层可见行;
1875
+ * 子代理全不跑且自身空闲 ⇒ 仍是 `idle`(`running: false`)。**树与搜索两条路径同源**
1876
+ * (判据写在 {@link toSessionRow} 里)。`runningCount` 的口径**不变**(仍只数
1877
+ * `session.running`)—— 渲染层无消费者,本次不动(用户裁决 Q1);
1878
+ * - **顶部区(T11,2026-09-22 用户终裁)**:每个容器内,**正在运行**的会话(自身
1879
+ * `running` **或** 任意层级有运行中的子代理)排在本容器**最前**(先于 5 条截断生效,
1880
+ * 但**顶部区成员超过 `COLLAPSED_SESSION_LIMIT` 条时,超出的仍会被截断** —— 见
1881
+ * `T5/截断: 顶部区成员数 > 5 时,只有前 5 条可见`),并按 `updatedAt` 降序排列;
1882
+ * 它们**不可拖动**(拖拽接线在 `sidebar.tsx` 层不给这些行安装)。
1883
+ * **尚未落表的新会话**同样进入顶部区(D2/D3d)。
1884
+ * ⚠️ 已结束的会话(含用户正在查看的旧会话、含刚跑完的会话)**不再固定置顶** ——
1885
+ * 位置完全由持久拖拽顺序决定,且**必须可正常拖动**。「刚结束保留」与「当前会话置顶」
1886
+ * 两个机制已按用户终裁**删除**(见 {@link topZoneSessionKeys})。
1887
+ * 顶部区是**纯运行时推导**,**不写进 `localStorage`**({@link effectiveOrder} 刻意不应用);
1888
+ * - `query.trim()` 非空 ⇒ 扁平模式:只输出会话行(`depth: 0`),不应用展开态、截断与顶部区
1889
+ * (搜索结果跨容器,容器内相对顺序无意义);
1890
+ * - **手动顺序(D10,2026-09-21)**:`input.manualOrder` 且 `manual === true` 时,三层
1891
+ * 各自在**默认排序之后、截断之前**叠加手动顺序({@link applyManualOrder}):
1892
+ * 项目按 `projects`(键 = `ProjectNode.key`)、worktree 按 `worktrees[projectKey]`
1893
+ * (键 = `WorktreeNode.path`,**只在同一项目内**)、会话按 `sessions[容器key]`
1894
+ * (键 = `sessionId`,**只在同一容器内**)。列表外的新项按默认顺序追加到末尾;
1895
+ * 已消失的项被忽略。**搜索模式不应用**(见 {@link buildSearchRows})。
1896
+ * `manualOrder` 缺省或 `manual !== true` ⇒ 与不传逐字一致(零回归);
1897
+ * - 纯函数:不修改任何入参(排序前先拷贝)。
1898
+ *
1899
+ * @param input 侧栏模型入参(见 {@link SidebarModelInput})。
1900
+ * @returns 渲染行序列;搜索无匹配时返回空数组(渲染层据此显示 `search.empty`)。
1901
+ */
1902
+ export function buildRows(input) {
1903
+ const archived = new Set(input.archivedSessionIds);
1904
+ const context = {
1905
+ archived,
1906
+ collapsedKeys: input.collapsedKeys,
1907
+ expandedAllKeys: input.expandedAllKeys,
1908
+ expandLevels: input.expandLevels,
1909
+ currentSessionId: input.currentSessionId,
1910
+ titleOf: input.titleOf,
1911
+ t: input.t,
1912
+ // 索引建立在**全部**输入会话上(含归档与 blank),与原生的 `list.byId` 同口径 ——
1913
+ // 子代理被隐藏后,父行仍要如实显示「有几个子代理在跑」,不因父/子归档状态而漏计。
1914
+ subagentRunningCounts: indexRunningSubagentDescendants(allSessionsOf(input)),
1915
+ manualOrder: input.manualOrder,
1916
+ topZone: input.topZone,
1917
+ };
1918
+ const query = (typeof input.query === 'string' ? input.query : '').trim().toLowerCase();
1919
+ if (query !== '')
1920
+ return buildSearchRows(input, context, query);
1921
+ // ── 项目层手动顺序(D10)────────────────────────────────────────────
1922
+ // `applyManualOrder` 的「列表外项保持传入顺序追加到末尾」正是这里要的语义:
1923
+ // `input.projects` 已是宿主 `workspaceRegistry.list()` 的顺序,新项目自然落到末尾。
1924
+ const activeProjects = activeProjectsOf(input);
1925
+ const manualProjects = input.manualOrder?.manual === true ? input.manualOrder.projects : undefined;
1926
+ const orderedProjects = applyManualOrder(activeProjects, manualProjects, (project) => project.key);
1927
+ const rows = [];
1928
+ for (const project of orderedProjects) {
1929
+ const containers = containersOfProject(project, context);
1930
+ const projectCollapsed = isCollapsed(context.collapsedKeys, containers.projectKey);
1931
+ // 计数与行内容都要算(折叠时仍要显示计数)。
1932
+ // flat / 普通会话容器:**所有项目**都构建,供 project 行聚合高亮(2026-10-20 追加裁决:
1933
+ // 所有 workspace 都统计普通/flat 会话)。`containers.flat` 只对非 git 工作区存在
1934
+ // (D11:git 项目的会话挂 worktree 子行),故 git 项目在这里用 `project.flatSessions`
1935
+ // 构造一个**仅供判定**的等价容器;它的 rows / 计数不参与渲染与 sessionCount
1936
+ // (真实宿主数据里 `flatSessions` 对 git 项目恒为空,见 `projects.ts` 归属规则 2b)。
1937
+ const flatContainer = containers.flat ?? {
1938
+ key: containers.projectKey,
1939
+ kind: 'project',
1940
+ depth: 1,
1941
+ sessions: project.flatSessions,
1942
+ project,
1943
+ };
1944
+ const flatResult = emitContainer(flatContainer, context);
1945
+ const rendersFlat = containers.flat !== undefined;
1946
+ const historyResult = containers.history === undefined ? undefined : emitContainer(containers.history, context);
1947
+ // ── worktree 层手动顺序(D10)──────────────────────────────────────
1948
+ // 约束:**只能在同一个项目内重排**。`order.worktrees` 以 `project.key` 分桶,
1949
+ // 所以跨项目的拖拽在本函数里根本无从表达(键不同),渲染层也据此禁止跨项目拖拽。
1950
+ const orderedWorktrees = applyManualOrder(containers.worktrees, worktreeOrderOf(context.manualOrder, project.key), (entry) => entry.node.path);
1951
+ const worktreeResults = orderedWorktrees.map((entry) => ({
1952
+ node: entry.node,
1953
+ spec: entry.spec,
1954
+ result: emitContainer(entry.spec, context),
1955
+ }));
1956
+ const allResults = [
1957
+ ...worktreeResults.map((entry) => entry.result),
1958
+ // flat 只对非 git 工作区计入 sessionCount / runningCount(D11 语义不变);
1959
+ // git 项目的 flat 容器仅用于上面的高亮判定。
1960
+ ...(rendersFlat ? [flatResult] : []),
1961
+ ...(historyResult === undefined ? [] : [historyResult]),
1962
+ ];
1963
+ const identity = projectIdentity(project);
1964
+ rows.push({
1965
+ kind: 'project',
1966
+ key: containers.projectKey,
1967
+ label: project.title,
1968
+ depth: 0,
1969
+ expanded: !projectCollapsed,
1970
+ isGit: project.isGit === true,
1971
+ // D11(2026-09-21 修订):git 项目恒有 worktree 子行 ⇒ worktreeCount 恒等于
1972
+ // `worktrees.length`(含单 worktree 的 git 项目);非 git 工作区为 0。
1973
+ worktreeCount: containers.hasWorktreeRows ? project.worktrees.length : 0,
1974
+ sessionCount: allResults.reduce((sum, result) => sum + result.sessionCount, 0),
1975
+ runningCount: allResults.reduce((sum, result) => sum + result.runningCount, 0),
1976
+ pendingCount: allResults.reduce((sum, result) => sum + result.pendingCount, 0),
1977
+ // RT2(2026-10-20,含追加裁决):**worktree 子项 OR 本 workspace 的 flat/普通会话**。
1978
+ // `allResults` 同时含 history,绝不能整体用于此判定;history 桶与未分组仍显式排除。
1979
+ hasRunningTasks: worktreeResults.some((entry) => entry.result.hasRunningTasks === true) ||
1980
+ flatResult.hasRunningTasks === true,
1981
+ ...identity,
1982
+ });
1983
+ if (projectCollapsed)
1984
+ continue;
1985
+ for (const entry of worktreeResults) {
1986
+ const labels = worktreeLabels(entry.node, context.t);
1987
+ rows.push({
1988
+ kind: 'worktree',
1989
+ key: entry.spec.key,
1990
+ label: labels.label,
1991
+ depth: 1,
1992
+ expanded: !isCollapsed(context.collapsedKeys, entry.spec.key),
1993
+ path: entry.node.path,
1994
+ isMain: entry.node.isMain === true,
1995
+ exists: entry.node.exists === true,
1996
+ sessionCount: entry.result.sessionCount,
1997
+ runningCount: entry.result.runningCount,
1998
+ pendingCount: entry.result.pendingCount,
1999
+ hasRunningTasks: entry.result.hasRunningTasks,
2000
+ ...(labels.sublabel === undefined ? {} : { sublabel: labels.sublabel }),
2001
+ ...(entry.node.workspaceId === undefined ? {} : { workspaceId: entry.node.workspaceId }),
2002
+ });
2003
+ if (isCollapsed(context.collapsedKeys, entry.spec.key))
2004
+ continue;
2005
+ rows.push(...entry.result.rows);
2006
+ }
2007
+ if (rendersFlat)
2008
+ rows.push(...flatResult.rows);
2009
+ if (containers.history !== undefined && historyResult !== undefined) {
2010
+ rows.push({
2011
+ kind: 'history',
2012
+ key: containers.history.key,
2013
+ label: context.t('history.label'),
2014
+ depth: 1,
2015
+ expanded: !isCollapsed(context.collapsedKeys, containers.history.key),
2016
+ sessionCount: historyResult.sessionCount,
2017
+ runningCount: historyResult.runningCount,
2018
+ pendingCount: historyResult.pendingCount,
2019
+ });
2020
+ if (!isCollapsed(context.collapsedKeys, containers.history.key)) {
2021
+ rows.push(...historyResult.rows);
2022
+ }
2023
+ }
2024
+ }
2025
+ // 未分组行同理:`ungrouped` 非空 ≠ 有可见成员(可能全是归档 / 非当前的 blank)。
2026
+ if (hasVisibleMembers(input.ungrouped, context)) {
2027
+ const spec = ungroupedContainer(input);
2028
+ const result = emitContainer(spec, context);
2029
+ const collapsed = isCollapsed(context.collapsedKeys, spec.key);
2030
+ rows.push({
2031
+ kind: 'project',
2032
+ key: spec.key,
2033
+ label: context.t('section.ungrouped'),
2034
+ depth: 0,
2035
+ expanded: !collapsed,
2036
+ isGit: false,
2037
+ worktreeCount: 0,
2038
+ sessionCount: result.sessionCount,
2039
+ runningCount: result.runningCount,
2040
+ pendingCount: result.pendingCount,
2041
+ // RT2(用户裁决):未分组行虽然是 `project` 形态,但**显式**为 false ——
2042
+ // 即使 `result.hasRunningTasks` 为 true(未分组容器内有会话在跑)也不许用:
2043
+ // 「project 文件夹高亮」只代表「该 workspace 的 worktree 子项或 flat 会话有任务在跑」,
2044
+ // 未分组不属于任何 workspace(2026-10-20 追加裁决后仍然排除)。
2045
+ hasRunningTasks: false,
2046
+ });
2047
+ if (!collapsed)
2048
+ rows.push(...result.rows);
2049
+ }
2050
+ if (input.includeRecent === true) {
2051
+ rows.push(...emitRecentSection(input, context));
2052
+ }
2053
+ return rows;
2054
+ }
2055
+ /**
2056
+ * 推导侧栏底部「最近」分区行序列(2026-10-21 WSR5/WSR6,AC4–AC6;2026-10-29 RAS1/RAS3 改排序键)。
2057
+ *
2058
+ * - 汇总全局所有可见顶层会话(跨所有 project 的 worktree / flat / history 及 ungrouped,
2059
+ * 统一走 {@link isVisibleMember} 排除子代理、归档与非当前 blank),按归一化 `sessionId` 去重;
2060
+ * - 固定按**最后更新时间**({@link recentActivityOf} = `max(updatedAt, lastActivityAt)`)降序
2061
+ * (`sessionId` 升序 tiebreak)排列,最多保留 {@link RECENT_SESSION_LIMIT}(100)条;
2062
+ * ⚠️ `lastActivityAt` 只在本分区消费 —— 工作区树/顶部区仍按 `updatedAt`;
2063
+ * - 产出 `kind: 'recent'` 分区头(`key: 'r:__recent__'`),支持 `collapsedKeys['r:__recent__']` 折叠,
2064
+ * 展开时直接平铺全部(最多 100 条)`rs:<sessionId>` 会话行,**不产生 `more` 行**;
2065
+ * - 搜索模式(`query` 非空)或无可见会话时返回 `[]`。
2066
+ */
2067
+ export function buildRecentRows(input) {
2068
+ const query = (typeof input.query === 'string' ? input.query : '').trim();
2069
+ if (query !== '')
2070
+ return [];
2071
+ const context = {
2072
+ archived: new Set(input.archivedSessionIds),
2073
+ collapsedKeys: input.collapsedKeys,
2074
+ expandedAllKeys: input.expandedAllKeys,
2075
+ expandLevels: input.expandLevels,
2076
+ currentSessionId: input.currentSessionId,
2077
+ titleOf: input.titleOf,
2078
+ t: input.t,
2079
+ subagentRunningCounts: indexRunningSubagentDescendants(allSessionsOf(input)),
2080
+ manualOrder: input.manualOrder,
2081
+ topZone: input.topZone,
2082
+ };
2083
+ return emitRecentSection(input, context);
2084
+ }
2085
+ function emitRecentSection(input, context) {
2086
+ const specs = [];
2087
+ for (const project of activeProjectsOf(input)) {
2088
+ const containers = containersOfProject(project, context);
2089
+ for (const entry of containers.worktrees)
2090
+ specs.push(entry.spec);
2091
+ if (containers.flat !== undefined)
2092
+ specs.push(containers.flat);
2093
+ if (containers.history !== undefined)
2094
+ specs.push(containers.history);
2095
+ }
2096
+ if (hasVisibleMembers(input.ungrouped, context)) {
2097
+ specs.push(ungroupedContainer(input));
2098
+ }
2099
+ const byKey = new Map();
2100
+ for (const spec of specs) {
2101
+ for (const session of visibleMembers(spec, context)) {
2102
+ const key = normalizeSessionId(session.sessionId);
2103
+ if (key === '')
2104
+ continue;
2105
+ const prior = byKey.get(key);
2106
+ if (prior === undefined || byRecentActivity(session, prior) < 0) {
2107
+ byKey.set(key, session);
2108
+ }
2109
+ }
2110
+ }
2111
+ if (byKey.size === 0)
2112
+ return [];
2113
+ // 2026-11-14 PX4:取消 100 条上限,改为与工作区容器一致的渐进式展开。
2114
+ const ordered = [...byKey.values()].sort(byRecentActivity);
2115
+ const recentKey = `r:${RECENT_KEY}`;
2116
+ const collapsed = isCollapsed(context.collapsedKeys, recentKey);
2117
+ const recentSpec = {
2118
+ key: recentKey,
2119
+ kind: 'recent',
2120
+ depth: 1,
2121
+ sessions: ordered,
2122
+ };
2123
+ const rows = [
2124
+ {
2125
+ kind: 'recent',
2126
+ key: recentKey,
2127
+ label: context.t('section.recent'),
2128
+ depth: 0,
2129
+ expanded: !collapsed,
2130
+ sessionCount: ordered.length,
2131
+ },
2132
+ ];
2133
+ if (!collapsed) {
2134
+ const truncation = truncateByLevel(ordered, recentKey, context, 'recent', recentSpec.depth);
2135
+ for (const session of truncation.selected) {
2136
+ rows.push(toSessionRow(session, recentSpec.depth, subagentCountOf(context.subagentRunningCounts, session.sessionId), recentSpec, context));
2137
+ }
2138
+ if (truncation.more !== undefined)
2139
+ rows.push(truncation.more);
2140
+ }
2141
+ return rows;
2142
+ }
2143
+ //# sourceMappingURL=tree-model.js.map