dsh-worktree-groups 0.0.0-stage → 0.1.0

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,1226 @@
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 declare 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 declare 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 declare function visibleSessionLimit(level: number): number;
65
+ /** 下一次点击「展开更多」会多显示的条数:`min(5·(L+1), 剩余)`(PX-AC3)。 */
66
+ export declare function nextExpandCount(level: number, remaining: number): number;
67
+ /**
68
+ * 折叠某一行时需要清零展开层级的会话容器 key(2026-11-14 PX3/PX-AC4)。
69
+ *
70
+ * - 项目行 `p:<projectKey>` ⇒ 自身(非 git 平铺 / 未分组容器与行同 key)+ `h:<projectKey>` +
71
+ * 其全部 worktree 容器 `w:<path>`;
72
+ * - 其余(worktree 行 `w:<path>`、history 行 `h:…`、「最近」`r:__recent__`)⇒ 仅自身
73
+ * (这些行的 key 与其会话容器 key 同源,见 `containersOfProject`)。
74
+ */
75
+ export declare function containerKeysUnder(projects: readonly ProjectNodeLike[], rowKey: string): string[];
76
+ /**
77
+ * 「最近」分区的合成键(对应行 `key = 'r:' + RECENT_KEY`)。
78
+ */
79
+ export declare const RECENT_KEY = "__recent__";
80
+ /**
81
+ * 「未分组」容器的合成项目键。
82
+ *
83
+ * 冻结的 {@link RenderRow} 联合类型里没有 `ungrouped` 行种类,所以未分组容器复用
84
+ * `project` 行表达(`key = 'p:' + UNGROUPED_KEY`,`isGit: false`)。渲染层可用它把
85
+ * 未分组行与真实项目行区分开。
86
+ */
87
+ export declare const UNGROUPED_KEY = "__ungrouped__";
88
+ /** 一条会话行(与宿主 `SessionRow` 结构兼容,不跨半边 import)。 */
89
+ export interface SessionRowLike {
90
+ sessionId: string;
91
+ updatedAt: number;
92
+ /**
93
+ * 会话**最后更新时间**(2026-10-29 RAS1–RAS5):宿主载荷自带的
94
+ * `max(updatedAt, 任意 session/event 活动时间)`。**只有「最近」分区消费它排序**;
95
+ * 工作区树 / 手动顺序 / 顶部区仍使用 `updatedAt`。旧载荷缺失时按 `updatedAt` 处理。
96
+ */
97
+ lastActivityAt?: number;
98
+ running: boolean;
99
+ blank: boolean;
100
+ cwd?: string;
101
+ parentSessionId?: string;
102
+ /** 与宿主 `SessionRow.origin` 同宽(宿主只会给 'subagent')。 */
103
+ origin?: 'subagent';
104
+ pendingInteraction?: string;
105
+ completed?: boolean;
106
+ title?: string;
107
+ }
108
+ /** 侧栏树的一个 worktree 节点(与宿主 `WorktreeNode` 结构兼容)。 */
109
+ export interface WorktreeNodeLike {
110
+ path: string;
111
+ branch?: string;
112
+ isMain: boolean;
113
+ exists: boolean;
114
+ /** 已注册的 dsh 工作区 id;未注册为 undefined(懒注册)。 */
115
+ workspaceId?: string;
116
+ title: string;
117
+ sessions: SessionRowLike[];
118
+ }
119
+ /** 侧栏树的一个项目节点(与宿主 `ProjectNode` 结构兼容)。 */
120
+ export interface ProjectNodeLike {
121
+ /** commonDir;非 git 工作区用 `ws:<workspaceId>`。 */
122
+ key: string;
123
+ isGit: boolean;
124
+ title: string;
125
+ mainPath?: string;
126
+ worktrees: WorktreeNodeLike[];
127
+ /** 已关闭 worktree 的会话(history-worktree-session 桶)。 */
128
+ history: SessionRowLike[];
129
+ /** 非 git 工作区:会话直接挂项目下(不展开 worktree 子行)。 */
130
+ flatSessions: SessionRowLike[];
131
+ }
132
+ /**
133
+ * 冻结的渲染行类型(与 `docs/INTERFACES.md` §2.2 逐字对齐)。
134
+ * 组件只负责把行画出来,不做任何推导。
135
+ */
136
+ export type RenderRow = {
137
+ kind: 'recent';
138
+ /** `r:${RECENT_KEY}` */
139
+ key: string;
140
+ /** locales: section.recent */
141
+ label: string;
142
+ depth: 0;
143
+ expanded: boolean;
144
+ sessionCount: number;
145
+ } | {
146
+ kind: 'project';
147
+ /** `p:<projectKey>`(未分组为 `p:${UNGROUPED_KEY}`)。 */
148
+ key: string;
149
+ label: string;
150
+ depth: 0;
151
+ expanded: boolean;
152
+ isGit: boolean;
153
+ /** 非 git 工作区时有值。 */
154
+ path?: string;
155
+ workspaceId?: string;
156
+ /**
157
+ * worktree 子行数:**git 项目恒为 `worktrees.length`**(含单 worktree 的 git 项目,
158
+ * D11 2026-09-21 修订);非 git 工作区恒为 0(它不产生 worktree 子行,会话平铺)。
159
+ */
160
+ worktreeCount: number;
161
+ sessionCount: number;
162
+ runningCount: number;
163
+ pendingCount: number;
164
+ /**
165
+ * **该行是否有任务正在运行(含运行中的子代理)**(2026-10-20 additive 修订)。
166
+ *
167
+ * 判定 = `worktreeResults.some(entry => entry.result.hasRunningTasks === true) ||
168
+ * flatResult.hasRunningTasks === true` —— worktree 子项**或**该 workspace 的
169
+ * flat/普通会话(2026-10-20 追加裁决:所有 workspace 都统计 flat 会话);
170
+ * history 桶 / 未分组**不参与**(RT2)。
171
+ *
172
+ * ⚠️ 它**不是** `runningCount > 0` 的别名:`runningCount` 仍只数主会话自身
173
+ * `running === true`(用户裁决 Q1 的口径**不变**),因此允许出现
174
+ * 「`runningCount === 0` 但 `hasRunningTasks === true`」(只有子代理在跑)。
175
+ * 消费者仅 `sidebar.tsx` 的 `ContainerRowView`(图标高亮)。
176
+ */
177
+ hasRunningTasks: boolean;
178
+ } | {
179
+ kind: 'worktree';
180
+ /** `w:<path>` */
181
+ key: string;
182
+ /** 分支名,无分支时用目录 basename。 */
183
+ label: string;
184
+ /** 目录 basename(与 label 不同才给)。 */
185
+ sublabel?: string;
186
+ depth: 1;
187
+ expanded: boolean;
188
+ path: string;
189
+ isMain: boolean;
190
+ exists: boolean;
191
+ workspaceId?: string;
192
+ sessionCount: number;
193
+ runningCount: number;
194
+ pendingCount: number;
195
+ /**
196
+ * **该容器内是否有任务正在运行(含运行中的子代理)**(2026-10-20 additive 修订)。
197
+ *
198
+ * 判定写在 {@link emitContainer}:用**截断前**的可见顶层会话 `heads`,
199
+ * 逐条判 `running === true || subagentCountOf(...) > 0` —— 与 `toSessionRow` 的
200
+ * `running` **逐字同源**(同一 `subagentRunningCounts` 索引),不可能出现
201
+ * 「会话行蓝点亮、容器行不亮」的分叉。
202
+ *
203
+ * ⚠️ 与 `runningCount` 口径不同是有意为之:`runningCount` 仍只数主会话自身
204
+ * `running`(Q1 裁决不变),本字段才含子代理聚合(RT1)。
205
+ */
206
+ hasRunningTasks: boolean;
207
+ } | {
208
+ kind: 'history';
209
+ /** `h:<projectKey>` */
210
+ key: string;
211
+ /** locales: history.label */
212
+ label: string;
213
+ depth: 1;
214
+ expanded: boolean;
215
+ sessionCount: number;
216
+ runningCount: number;
217
+ pendingCount: number;
218
+ } | {
219
+ kind: 'session';
220
+ /** `s:<sessionId>` */
221
+ key: string;
222
+ sessionId: string;
223
+ label: string;
224
+ /** 容器的会话深度:1(平铺项目 / 未分组下)或 2(worktree / history 下)。 */
225
+ depth: number;
226
+ updatedAt: number;
227
+ running: boolean;
228
+ completed: boolean;
229
+ blank: boolean;
230
+ pendingInteraction?: string;
231
+ /**
232
+ * **运行中的子代理后代数**(所有层级;无则在渲染层不画胶囊)。
233
+ *
234
+ * 语义对齐原生 `runningSubagentCount`(`indexSubagentDescendants`)—— 不是
235
+ * 「直接子代数」,也不是「子代理总数」:不跑的子代理**不**计入,与胶囊文案
236
+ * `a11y.subagents` = 「{n} 个子代理运行中」一致。
237
+ */
238
+ subagentCount: number;
239
+ isCurrent: boolean;
240
+ /** 所属父节点 key(用于「移出 history」等动作定位;最近分区为 `r:${RECENT_KEY}`)。 */
241
+ parentKey: string;
242
+ parentKind: 'worktree' | 'history' | 'project' | 'recent';
243
+ } | {
244
+ kind: 'more';
245
+ /** `m:<parentKey>` */
246
+ key: string;
247
+ parentKey: string;
248
+ /** 2026-11-14 PX4:「最近」分区也产出 more 行(`parentKind: 'recent'`)。 */
249
+ parentKind: 'worktree' | 'history' | 'project' | 'recent';
250
+ /** 当前**仍未显示**的顶层会话数(2026-11-14 PX 起;全部展开后为 0)。 */
251
+ hiddenCount: number;
252
+ /** 下一次点击「展开更多」会多显示的条数({@link nextExpandCount});无剩余为 0。 */
253
+ nextCount: number;
254
+ /** 是否提供「收起」(展开层级 > 0 或旧式全展开)。 */
255
+ canCollapse: boolean;
256
+ depth: number;
257
+ };
258
+ /** {@link SidebarModelInput.t} 的取词函数签名。 */
259
+ type Translate = (key: string, vars?: Record<string, string | number>) => string;
260
+ /**
261
+ * 浏览器本地的手动排序(PRD D10,2026-09-21 用户决策变更)。
262
+ *
263
+ * ## 为什么是浏览器本地顺序,而不是宿主 API
264
+ *
265
+ * 宿主提供 `workspaces.insertBefore` / `workspaces.insertSessionBefore` 两个排序 API,
266
+ * 但**都用不了**:
267
+ * 1. `insertSessionBefore(workspaceId, sessionId, beforeSessionId)` 要求被拖会话与锚点
268
+ * **同属一个 workspace**(否则抛 `WorkspaceMoveInvalidError`)。真实数据里 MyProject 的
269
+ * 6 个 worktree **只有 2 个已注册**,其余 4 个的会话不在任何 workspace 里;history 桶、
270
+ * 未分组的会话同理 —— 无法统一覆盖。
271
+ * 2. `insertBefore(workspaceId, beforeWorkspaceId)` 只能排 dsh 工作区,而树里**未注册的
272
+ * worktree 没有 workspaceId**,项目节点还可能对应多个工作区 —— 同样无法统一。
273
+ *
274
+ * 因此统一用**浏览器本地顺序**:对未注册 worktree、history 桶、未分组**全部适用**,语义
275
+ * 一致;且这是**视图偏好**而非宿主数据,不该污染宿主注册表。(原生也是双轨:workspace
276
+ * 顺序走宿主、session 顺序走浏览器本地 store。)
277
+ *
278
+ * ## 结构
279
+ *
280
+ * ```json
281
+ * {
282
+ * "manual": true,
283
+ * "projects": ["<projectKey>", "..."],
284
+ * "worktrees": { "<projectKey>": ["<worktreePath>", "..."] },
285
+ * "sessions": { "<containerKey>": ["<sessionId>", "..."] }
286
+ * }
287
+ * ```
288
+ *
289
+ * - `projects` 的键是 `ProjectNode.key`(git 项目为 commonDir,非 git 为 `ws:<id>`),
290
+ * **不含** `UNGROUPED_KEY`(未分组行不参与拖拽)。
291
+ * - `worktrees` 的键是 `ProjectNode.key`,值是 **worktree 绝对路径**(`WorktreeNode.path`)。
292
+ * - `sessions` 的键是**容器 key**(`w:<path>` / `h:<projectKey>` / `p:<projectKey>`,
293
+ * 与 `RenderRow.parentKey` 同源),值是 sessionId。
294
+ *
295
+ * ## 叠加算法(见 {@link applyManualOrder})
296
+ *
297
+ * 列表内的项按索引重排;列表外的项(新建的会话 / worktree / 项目)按各自的**默认顺序**
298
+ * 追加到**末尾**;列表里已不存在的项(被删 / 归档)**忽略**。纯函数,不改入参。
299
+ */
300
+ export interface ManualOrder {
301
+ /** 用户是否手动排过序。`false` / 缺省 ⇒ 完全走默认顺序(零回归)。 */
302
+ manual: boolean;
303
+ /** 顶层项目顺序(`ProjectNode.key`)。 */
304
+ projects?: string[];
305
+ /** 项目 key → 该项目内 worktree 路径顺序。 */
306
+ worktrees?: Record<string, string[]>;
307
+ /** 容器 key → 该容器内 sessionId 顺序。 */
308
+ sessions?: Record<string, string[]>;
309
+ }
310
+ /**
311
+ * 按手动顺序**稳定重排**:置顶项最前,然后列表内的项按索引,列表外的项按默认顺序追加到末尾。
312
+ *
313
+ * 语义(四条,对应 PRD D10 的验收):
314
+ * 1. **置顶**(可选第 4 参):`pinnedKeys` 里出现的项按该数组顺序排在最**前** —— 且是
315
+ * 「先摘出来再拼」,因此它**不受 `order` 影响**(哪怕它在 `order` 里排在最后);
316
+ * 2. **列表内**:`order` 里出现的项,按 `order` 的索引升序排在其后;
317
+ * 3. **列表外**:`items` 里没出现在 `order` 的项(新建的会话 / worktree / 项目)保持
318
+ * 它们**传入时的相对顺序**,整体追加在列表内项之后 —— 因此「默认顺序」由调用方在
319
+ * 传入前排好(会话走 `updatedAt` 降序、worktree 走宿主顺序、项目走宿主顺序);
320
+ * 4. **已消失的项**:`order` / `pinnedKeys` 里在 `items` 中找不到的 id **直接忽略** ——
321
+ * 不产生空洞、不产生 `undefined`,输出长度恒等于输入长度。
322
+ *
323
+ * 纯函数:**不修改入参数组**(返回新数组;元素引用不变)。
324
+ *
325
+ * `order` 为 `undefined` / 空数组**且** `pinnedKeys` 为空时,原样返回输入的一份浅拷贝
326
+ * (顺序完全不变)—— 这是既有调用方(`effectiveOrder`、项目层、worktree 层)零回归的保证。
327
+ *
328
+ * @param items 默认顺序的项(**不被修改**)。
329
+ * @param order 手动顺序的 key 列表;`undefined` / 空 ⇒ 不按它重排。
330
+ * @param keyOf 取项的比较键。
331
+ * @param pinnedKeys 需要**置顶**的 key(按数组顺序排在最前)。缺省 / 空 ⇒ 与不传逐字一致。
332
+ * 调用方只应在**渲染路径**上传它:置顶是纯运行时推导,**绝不写进持久顺序**(见
333
+ * {@link effectiveOrder} 刻意不传)。T11 后**唯一**的置顶来源是
334
+ * {@link topZoneSessionKeys}(正在运行 / 尚未落表的新会话)。
335
+ * @returns 重排后的新数组。
336
+ *
337
+ * @example
338
+ * applyManualOrder([a, b, c], ['c', 'a'], (x) => x.id)
339
+ * // ⇒ [c, a, b] (b 不在 order 里 ⇒ 保持默认顺序追加到末尾)
340
+ *
341
+ * @example
342
+ * applyManualOrder([a, b], ['gone', 'b'], (x) => x.id)
343
+ * // ⇒ [b, a] ('gone' 在 items 里不存在 ⇒ 忽略,不产生空洞)
344
+ *
345
+ * @example
346
+ * applyManualOrder([a, b, c], ['a', 'b'], (x) => x.id, ['c'])
347
+ * // ⇒ [c, a, b] (c 置顶,其余仍按 order;a/b 的 index 已在置顶阶段被占,不会重复搬运)
348
+ */
349
+ export declare function applyManualOrder<T>(items: T[], order: string[] | undefined, keyOf: (item: T) => string, pinnedKeys?: readonly string[]): T[];
350
+ /**
351
+ * 顶部区的运行时输入(T11,2026-09-22 用户终裁)。
352
+ *
353
+ * 顶部区是**运行时内存状态**:刷新页面即重置,除 D2 的「新会话插入固化表」外
354
+ * **不写** `localStorage`(见 {@link effectiveOrder} 的不变式)。
355
+ *
356
+ * 本对象由 `src/sidebar.tsx`(唯一拥有跨渲染内存的地方)采集后传入;
357
+ * `tree-model.ts` 只做纯推导 ⇒ 判据、排序、截断交互全部可被 `node --test` 覆盖。
358
+ */
359
+ export interface TopZoneInput {
360
+ /**
361
+ * **正在运行**的会话 id(判据 = 该会话自己的 `running === true` **或** 它有
362
+ * 任意层级的运行中子代理后代,即需求 A 的 `running` 口径)。
363
+ *
364
+ * ⚠️ 与 `SessionRowLike.running`(**裸**字段,不含子代理聚合)不同:那个字段是
365
+ * 宿主 `SessionSummary.running` 的透传。调用方要么传已聚合的 id 集合,要么不传。
366
+ *
367
+ * 这是顶部区**唯一**的常规成员类别(T11 终裁):它们固定在所属容器最前,且
368
+ * **不可拖动**(`sidebar.tsx` 不给这些行装拖拽接线)。
369
+ */
370
+ runningSessionIds?: readonly string[];
371
+ /**
372
+ * **新会话**的会话 id(D2/D3d,T11 终裁后**唯一**的非 running 顶部区成员)。
373
+ *
374
+ * ⚠️ 判定口径由调用方负责(见 {@link topZoneSessionKeys} 的 JSDoc):**不是**
375
+ * 「所有不在固化表里的会话」—— T4 实测真实数据里有 6 条表外会话,其中 4 条是
376
+ * **旧会话**(早于固化水位),把它们一律插到最前是错的。
377
+ */
378
+ newSessionIds?: readonly string[];
379
+ /**
380
+ * **D2 落表台账**({@link TopZoneState.writtenNewSessionIds} 的渲染期投影):
381
+ * 「落表意图已满足」的新会话 id(归一化)。
382
+ *
383
+ * 用途(T9 缺陷 1 的修复点):**已落表**的新会话在渲染期**不再**被提升到容器顶部区 ——
384
+ * 它的「在容器最前」已由持久顺序承载,渲染期再提升一次会让用户随后的拖拽被静默回滚。
385
+ *
386
+ * ⚠️ **缺省(不传)⇒ 与旧行为逐字一致**(`newSessionIds` 全部参与提升),保证零回归:
387
+ * 既有调用方(不传台账)行为不变。
388
+ */
389
+ writtenNewSessionIds?: readonly string[];
390
+ }
391
+ /**
392
+ * **「正在运行」判据的唯一来源**:这条会话是否在跑(⇒ 属于顶部区、且**不可拖动**)。
393
+ *
394
+ * ⚠️ 2026-10-22 起「不可拖动」的**唯一**判据是 {@link isSessionDragLocked}(= 本函数 ∪
395
+ * 当前空白会话占位行);本函数仍是其中「运行中」这一半的唯一实现,`topZoneSessionKeys`
396
+ * 与 `isSessionDragLocked` 都调它,不得各写一份。
397
+ *
398
+ * ## 为什么必须导出成共享函数
399
+ *
400
+ * 用户终裁「正在运行的会话固定在顶部,**拖不动**」把两件事绑在一起:
401
+ * ① 渲染层把它排到容器最前({@link topZoneSessionKeys});② 渲染层**不给它装拖拽接线**
402
+ * (`sidebar.tsx` 的 `dragHandlersFor` 调用点)。这两处若各写一遍判据,迟早分叉 ——
403
+ * 例如「行显示运行中圆点但判据只认裸 `running`」⇒ 用户看到运行中的行却能拖走它。
404
+ * 因此判据只有这一处实现,两侧都调它。
405
+ *
406
+ * ## 口径(与既有聚合 `running` 一致)
407
+ *
408
+ * 满足**任一**即算运行中:
409
+ * - `session.running === true` —— 渲染行的 `running` 是**聚合**口径
410
+ * (`session.running || runningSubagentCount > 0`,见 {@link toSessionRow}),因此它
411
+ * 本身就覆盖了「自身在跑」与「只有子代理在跑」两种情形;
412
+ * - id ∈ `topZone.runningSessionIds` —— 调用方(`sidebar.tsx`)从状态机投影的**显式**
413
+ * 聚合清单。它覆盖「状态机已知道在跑、但当前这次渲染的行数据还没反映出来」的窄窗口。
414
+ *
415
+ * ⚠️ **新会话不算「运行中」**:`newSessionIds` 命中的会话仍可拖动。它「在容器最前」由
416
+ * D2 的落表(持久顺序)承载,用户把它拖走后不会被渲染期搬回(见
417
+ * {@link TopZoneInput.writtenNewSessionIds})。用户终裁只说了「正在运行的」拖不动。
418
+ *
419
+ * @param session 会话(渲染行或 `SessionRowLike` 皆可,只要有 id 与 running)。
420
+ * @param topZone 运行时顶部区输入;缺省 ⇒ 只认 `session.running`。
421
+ * @returns 是否属于「运行中、不可拖动」这一类。
422
+ */
423
+ export declare function isTopZoneRunningSession(session: {
424
+ sessionId: string;
425
+ running?: boolean;
426
+ }, topZone?: TopZoneInput): boolean;
427
+ /**
428
+ * 是否是**当前打开的空白会话**(侧栏里的「新会话」占位行)。
429
+ *
430
+ * 宿主原生把这条行当占位符:**恒在本组最前**且**不可起拖**:
431
+ * - `dsh-client-ui-workspace/lib/client.js:983`:`sectionMembers` 先把所有 `blank` 成员挑出来放最前;
432
+ * - `:952`:`pinCurrentBlank` 再把**当前** blank 提到该账户首位;
433
+ * - `:2261`:`draggable = drag !== void 0 && !row.blank && !row.archived`。
434
+ *
435
+ * 本插件为什么需要它(2026-10-22 DR4,缺陷:复用空白会话后「新会话」掉到最下面):
436
+ * 同位置「新建会话」复用同目录的空白会话(保留草稿)之后,它不再满足
437
+ * {@link observeTopZone} 的「新会话」判据(进程内首次观测且晚于启动水位 / blank→非 blank),
438
+ * 渲染时只能按 `updatedAt`(很旧)或手动顺序表(表外 ⇒ 追加末尾)落到容器最后。
439
+ *
440
+ * ⚠️ 与 T11 终裁不冲突:终裁删除的是「**普通**当前会话置顶」(`isCurrent` 不参与顶部区),
441
+ * 本判据只认 `blank === true` 的占位行。
442
+ *
443
+ * @param session 会话(渲染行或 `SessionRowLike` 皆可,只要有 id / blank)。
444
+ * @param currentSessionId 当前会话 id(`isCurrent` 字段缺席时的第二来源;两者都做前缀归一化)。
445
+ * @returns 是否属于「当前空白会话」。
446
+ */
447
+ export declare function isCurrentBlankSession(session: {
448
+ sessionId: string;
449
+ blank?: boolean;
450
+ isCurrent?: boolean;
451
+ }, currentSessionId?: string): boolean;
452
+ /**
453
+ * 会话行**是否禁止拖拽**的唯一判据(T11 + 2026-10-22 DR5)。
454
+ *
455
+ * = ① 当前空白会话占位行({@link isCurrentBlankSession})∪ ② 正在运行
456
+ * ({@link isTopZoneRunningSession},含任意层级运行中的子代理)。
457
+ *
458
+ * 为什么占位行必须锁拖:它被渲染期固定在容器最前(见 `emitContainer`),若还允许起拖,
459
+ * 用户拖完只会看到弹回 —— 与 T9 缺陷 1 同一类「渲染期回滚用户操作」;宿主原生同样不给
460
+ * blank 行起拖(`dsh-client-ui-workspace/lib/client.js:2261`)。占位行**仍接受落点**:
461
+ * `dragHandlersFor` 的第三参只关掉「自己起拖」,别的会话照样能拖到它上方/下方。
462
+ *
463
+ * ⚠️ **尚未落表的新会话(`newSessionIds`)不在此列**:它由 D2 落表承载持久顺序,用户
464
+ * 拖走后不得被渲染期搬回(见 {@link TopZoneInput.writtenNewSessionIds})。
465
+ *
466
+ * @param session 会话行(`RenderRow` 或 `SessionRowLike` 皆可)。
467
+ * @param topZone 运行时顶部区输入;缺省 ⇒ 只认裸 `running` 与占位行。
468
+ * @returns 是否禁止起拖。
469
+ */
470
+ export declare function isSessionDragLocked(session: {
471
+ sessionId: string;
472
+ running?: boolean;
473
+ blank?: boolean;
474
+ isCurrent?: boolean;
475
+ }, topZone?: TopZoneInput): boolean;
476
+ /**
477
+ * 顶部区判据(T11,2026-09-22 用户终裁)—— 计算某容器内应置顶的会话 key。
478
+ *
479
+ * ## 判据(两类)
480
+ *
481
+ * | # | 类别 | 判据 | 持久化 |
482
+ * |---|---|---|---|
483
+ * | a | **正在运行** | id ∈ `runningSessionIds`(口径含任意层级运行中的子代理),或该会话裸 `running === true` | 否(运行时) |
484
+ * | b | **新会话** | id ∈ `newSessionIds` **且** 不在 `writtenNewSessionIds` 台账里(已落表 ⇒ 持久顺序已把它放在最前 ⇒ 无需再提升) | 由调用方单独落表(D2) |
485
+ *
486
+ * ## 用户终裁(2026-09-22,第二轮真人 GUI 复验)—— 本函数相对 T5/T9 的**语义收窄**
487
+ *
488
+ * 用户观察到侧栏三段:`刚结束运行的会话 / 当前正在运行的会话 / 其余会话`,前两段**拖不动、
489
+ * 会回弹**,据此终裁:
490
+ *
491
+ * > **正在运行的会话固定在顶部,拖不动,只要是结束了的会话就不再固定置顶了。**
492
+ *
493
+ * 因此本函数**删除**了此前的两类成员:
494
+ * - **「刚结束保留」(`recentlyFinishedSessionIds`)**:已删除。已结束的会话不再固定置顶,
495
+ * 位置完全由持久拖拽顺序决定 ⇒ 它必须可正常拖动(不再被渲染期搬回顶部)。
496
+ * - **「当前打开的会话置顶」(`isCurrent`)**:已删除。用户明确选择**不保留置顶例外** ——
497
+ * 当前会话若不处于运行中,就不置顶,留在其持久顺序位置。
498
+ *
499
+ * 同时删除的还有「拖动释放」机制(`releasedContainerKeys` / `releaseTopZoneContainer` /
500
+ * `isTopZoneReleasingDrag`):它存在的唯一目的是「拖动容器 ⇒ 清除该容器的刚结束保留」,
501
+ * 而「刚结束保留」本身已删除 ⇒ 释放机制失去全部语义,属死代码。
502
+ *
503
+ * ## 为什么「新会话」不能靠「不在固化表里」判定
504
+ *
505
+ * T4 实测(`docs/RESEARCH-session-drop-to-bottom.md` §3.2):真实 localStorage 表里
506
+ * AnyWork 容器只固化了 16 条,而有 **6 条可见顶层会话不在表里**,其中**只有 2 条**
507
+ * 晚于固化水位(`2026-09-21T09:01:43Z`),另外 **4 条是旧会话**(水位之前就存在,
508
+ * 只是固化快照本身不完整)。
509
+ *
510
+ * ⇒ 若把「表外会话」一律当新会话置顶,这 4 条旧会话会**错误地跳到最前**。
511
+ * 因此本函数的 `newSessionIds` **由调用方按可靠判据给出**,本函数不做表外推断。
512
+ * 推荐的可靠判据(`sidebar.tsx` 采用):**本进程内观测到该会话 `blank: true → false`
513
+ * 的转换**(= 用户真的给它发了第一条消息),或**本进程内首次观察到该 id 且它晚于
514
+ * 本进程启动时的固化水位**。两者都要求「时间序」证据,而不是「表里有没有」。
515
+ *
516
+ * ## 排序与去重
517
+ *
518
+ * - 顶部区成员按 {@link sortTopZone}(`updatedAt` 降序);
519
+ * - 一个会话**最多出现一次**(`Set` 去重),因此「同一会话不得同时出现在多个容器的
520
+ * 顶部区」由「顶部区范围 = 本容器的 `visible` 成员」天然保证(`applyManualOrder`
521
+ * 只会在 `items` 里找到本容器的项);
522
+ * - 不在本容器 `sessions` 里的 id(归档 / 子代理 / 别的容器)**自然被忽略**。
523
+ *
524
+ * @param sessions 该容器内**已过滤**的可见会话(与 `applyManualOrder` 的 `items` 同一批)。
525
+ * @param currentSessionId 当前打开的会话 id。
526
+ * ⚠️ **T11 起不再参与任何置顶判定**,仅为**向后兼容**保留签名位置(既有调用方与
527
+ * `docs/INTERFACES.md` §2.2 的冻结签名);传入任何值都不改变结果。
528
+ * ⚠️ 2026-10-22:**当前空白会话**(「新会话」占位行)也**不**在这里置顶 —— 它由
529
+ * `emitContainer` 用 {@link isCurrentBlankSession} 单独排到最前(与宿主
530
+ * `sectionMembers` / `pinCurrentBlank` 同语义),本函数仍只负责「运行中 / 未落表新会话」。
531
+ * @param containerKey 本容器的 key。
532
+ * ⚠️ **T11 起不再被读取**(释放机制已删除),同样仅为签名兼容保留。
533
+ * @param topZone 运行时顶部区输入;缺省 ⇒ **无任何置顶项**(零回归分支)。
534
+ * @returns 置顶 key 数组;无置顶项时返回 `undefined`
535
+ * (让 `applyManualOrder` 走零回归分支)。
536
+ */
537
+ export declare function topZoneSessionKeys(sessions: SessionRowLike[], currentSessionId: string | undefined, containerKey: string, topZone?: TopZoneInput): string[] | undefined;
538
+ /**
539
+ * 一次观测里的**单条会话**(顶部区状态机的输入单元)。
540
+ *
541
+ * 由 `src/sidebar.tsx` 从 HTTP 树的**全部**会话(含 blank / 子代理 / 归档)投影出来 ——
542
+ * 必须含 blank 与聚合后的 running:前者用于判定「新会话」(`blank: true → 非 blank` 的
543
+ * 转换),后者用于投影 {@link TopZoneInput.runningSessionIds}(「现在谁在跑」)。
544
+ */
545
+ export interface TopZoneObservation {
546
+ sessionId: string;
547
+ /**
548
+ * `updatedAt`(宿主 `max(createdAt, lastPromptAt)`)。
549
+ * 用于「首次观测到的会话是否晚于本进程启动」这条**时间序**判据。
550
+ */
551
+ updatedAt: number;
552
+ /** 该会话是否仍是空白(还没发过第一条消息)。 */
553
+ blank: boolean;
554
+ /** **已聚合**的 running 口径(= `RenderRow.running`:自身 running 或任意层级有运行中子代理)。 */
555
+ running: boolean;
556
+ /** 是否子代理(`origin === 'subagent'`)—— 子代理不参与任何顶部区判定。 */
557
+ subagent: boolean;
558
+ /** 是否已归档 —— 归档会话不参与任何顶部区判定。 */
559
+ archived: boolean;
560
+ }
561
+ /**
562
+ * 顶部区的**运行时内存状态**(T5)。
563
+ *
564
+ * 生命周期 = 一次页面会话:**刷新即重置**(用户裁决 D3e)。除 D2 的「新会话插入固化表」
565
+ * (那是 `sidebar.tsx` 的写入动作,状态机本身不碰 `localStorage`)外,本状态
566
+ * **绝不写** `localStorage`。
567
+ */
568
+ export interface TopZoneState {
569
+ /** 是否已建立基线(本进程首次观测到树数据)。基线之前不产生任何「新会话」。 */
570
+ baselined: boolean;
571
+ /** 基线时刻(`Date.now()`)。用于「首次观测到的会话是否晚于本进程启动」。 */
572
+ startedAtMs: number;
573
+ /** 本进程**已观测过**的会话 id(归一化)。基线里出现过的旧会话永远不会被判为新会话。 */
574
+ knownSessionIds: readonly string[];
575
+ /** 归一化 id → 上次观测到的 `blank`(仅非子代理、非归档会话)。 */
576
+ blankOf: Readonly<Record<string, boolean>>;
577
+ /** 归一化 id → 上次观测到的**聚合** `running`(仅非子代理、非归档会话)。 */
578
+ runningOf: Readonly<Record<string, boolean>>;
579
+ /** 「新会话」id(归一化)。D2:它们会被插入固化表(由 `sidebar.tsx` 执行)。 */
580
+ newSessionIds: readonly string[];
581
+ /**
582
+ * **D2 落表台账**:本进程内「落表意图已满足」(已写进固化表,或表首本来就已经是它)的
583
+ * 新会话 id(**归一化**)。由 `sidebar.tsx` 在落表后调 {@link markNewSessionsWritten} 记入。
584
+ *
585
+ * ⚠️ **与 `newSessionIds` 是两个不同的事实**,刻意不合并:
586
+ * - `newSessionIds` 是 **D3d 的顶部区输入** —— 「新会话」这一类要在**渲染期**被提升到容器
587
+ * 顶部区。它在本进程内**不因落表而减少**,否则「用户随后拖走别的会话」时新会话就不再被
588
+ * 提升,D3d 语义被悄悄改掉;
589
+ * - 本字段只回答「D2 这条落表动作还要不要再做一次」。落表后记入 ⇒ 用户随后拖动该新会话
590
+ * (`manualOrder` 变化 ⇒ 落表 effect 重跑)时 effect **不再改写**持久顺序
591
+ * (T6 缺陷 B2:落表 effect 在编排层必须**收敛**)。
592
+ */
593
+ writtenNewSessionIds: readonly string[];
594
+ }
595
+ /** 空状态(首次渲染的初值)。 */
596
+ export declare function initialTopZoneState(): TopZoneState;
597
+ /**
598
+ * 观测一批会话,推进顶部区状态机(**纯函数**;无变化时返回**同一个引用**,
599
+ * 以便 `sidebar.tsx` 直接用于 `useState` 而不触发无限重渲染)。
600
+ *
601
+ * ## 「新会话」判定口径(关键,D2 的边界要求)
602
+ *
603
+ * 满足**任一**条件即判定为新会话(且必须:非子代理、非归档、基线之后):
604
+ *
605
+ * 1. **强证据 —— 本进程内观测到 `blank: true → false` 的转换**。
606
+ * 宿主语义(`dsh-api-session-controller/.../manager.js`):新建会话 `blank: true`,
607
+ * 发出第一条 `user/message` 后翻成 `false`。所以「先见 blank、后见非 blank」只能
608
+ * 是「这个会话在本进程观测期间发出了第一条消息」—— 时间序证据,不依赖顺序表。
609
+ * 2. **时间序证据 —— 首次观测到的会话且 `updatedAt >= 本进程基线时刻`**。
610
+ * 覆盖「新建 + 发首条消息发生在两次轮询之间、没观测到 blank 态」的窄窗口。
611
+ * `updatedAt = max(createdAt, lastPromptAt)` ⇒ 晚于本进程启动的 `updatedAt`
612
+ * 只可能来自「本进程启动后创建 / 本进程启动后发出消息」的会话。
613
+ *
614
+ * ## 为什么**不**用「不在固化顺序表里」
615
+ *
616
+ * T4 实测(`docs/RESEARCH-session-drop-to-bottom.md` §3.2):真实表里有 **6 条可见顶层
617
+ * 会话不在表里**,其中**只有 2 条**晚于固化水位,另外 **4 条是旧会话**(水位之前就存在,
618
+ * 只是固化快照本身不完整)。若按「表外即新」判定,这 4 条旧会话会被错误地插到最前。
619
+ * 本实现用「基线 + 时间序」双重证据,**基线里出现过的旧会话永远不会被判为新会话**。
620
+ *
621
+ * ## 残余不确定性(如实披露)
622
+ *
623
+ * - 若「创建会话 + 发首条消息」全部发生在**首次树数据到达之前**(页面刚加载的
624
+ * ~100ms 窗口内),该会话会进入基线 ⇒ 不会被判为新会话(**漏报**)。此时它在
625
+ * manual 模式下仍会落末尾 —— 但用户重开一次页面后,它已在基线里,属可接受降级。
626
+ * - 若宿主时钟与渲染进程时钟严重不一致(同机场景不可能),时间序判据可能误判。
627
+ * - 若**旧**会话的 `updatedAt` 因故晚于本进程基线(宿主时钟偏差 / `lastPromptAt` 被历史
628
+ * 事件推进),且它在本进程内**首次**出现,则会被判为新会话(**误报**)。同机场景不可能;
629
+ * 已在 `docs/PRD.md`「顶部区」段如实披露(T6 次要项 S3)。
630
+ *
631
+ * ## 归档语义(T6 缺陷 I3,2026-09-21 修正)
632
+ *
633
+ * 「谁算旧会话」与「谁参与顶部区判定」是**两个不同的事实**,本函数刻意分开:
634
+ *
635
+ * - `knownSessionIds`(= `seen`,**含归档与子代理会话**)只回答「这个 id 本进程见过没有」。
636
+ * 归档会话进 `known` ⇒ 即便它之后被取消归档、`updatedAt` 又被推进到基线之后,也**不会**
637
+ * 被判成新会话(否则会把一条**旧**会话插到固化表表首,违反 D5)。
638
+ * - `eligible`(**排除归档与子代理**)只回答「谁参与 blank / running 轨迹与顶部区判定」。
639
+ * 归档会话**不**产生 `blankOf` / `runningOf` 轨迹,**不**进 `newSessionIds`,也不置顶。
640
+ *
641
+ * ⚠️ 宿主**当前没有** unarchive API(`@deepseek-ai/dsh-api-workspace-controller` 只有
642
+ * `archiveSession`),所以「取消归档」这条路径当前不可达;这里仍按正确语义实现,因为
643
+ * 用户手改 `~/.dsh/storages/workspace.json` 或宿主将来提供 API 都会让它可达。
644
+ *
645
+ * ## 其它转换
646
+ *
647
+ * - `running` 轨迹(`runningOf`)逐观测更新,供 {@link topZoneInputOf} 投影
648
+ * `runningSessionIds` —— 它是顶部区**唯一**的常规成员类别(T11 终裁)。
649
+ * - ⚠️ **T11 已删除**:旧实现在 `running: true → false` 的下降沿写入
650
+ * `recentlyFinishedIds`(「刚结束保留」),并在出现新会话时清空它。用户终裁
651
+ * 「只要是结束了的会话就不再固定置顶了」⇒ 该机制连同其状态字段一并删除,
652
+ * `runningOf` 只用于回答「现在谁在跑」。
653
+ *
654
+ * @param state 上一状态。
655
+ * @param observations 本次观测到的全部会话(含 blank / 子代理 / 归档)。
656
+ * @param nowMs 本次观测的时刻(`Date.now()`);由调用方注入以便单测确定化。
657
+ * @returns 新状态;**无任何变化时返回入参 `state` 本身**。
658
+ */
659
+ export declare function observeTopZone(state: TopZoneState, observations: readonly TopZoneObservation[], nowMs: number): TopZoneState;
660
+ /**
661
+ * 从 `effectiveOrder` 的会话表里找出某个会话所属的**容器 key**。
662
+ *
663
+ * D2 的写入需要知道「新会话插到哪张表里」。用 `effectiveOrder`(而不是自己重推容器归属)
664
+ * 保证与渲染/固化路径**同源** —— 容器 key 的推导规则全模块只有一处实现。
665
+ *
666
+ * 比较时两侧都做 `session-` 前缀归一化。同一 id 出现在多个容器时取**第一个**
667
+ * (真实链路 `buildProjects` 每个会话只 push 一次,故不可达;此处只为确定性)。
668
+ *
669
+ * @param sessions `effectiveOrder(...).sessions`。
670
+ * @param sessionId 目标会话 id。
671
+ * @returns 容器 key;找不到时 `undefined`。
672
+ */
673
+ export declare function containerKeyOfSession(sessions: ReadonlyMap<string, readonly string[]>, sessionId: string): string | undefined;
674
+ /**
675
+ * 某个会话在**树/固化表里的落点**:容器 key + **该会话在表里的真实 id 形态**。
676
+ *
677
+ * ## 为什么必须把「真实形态」也带出来(T6 缺陷 B1 的根因)
678
+ *
679
+ * `observeTopZone` 内部一律用 `normalizeSessionId`(去掉 `session-` 前缀)做比较,所以
680
+ * `TopZoneState.newSessionIds` 里存的是**裸 id**;而宿主真实会话 id 恒带 `session-` 前缀
681
+ * (实测 `~/.dsh/sessions/**` 的会话头 `id = 'session-<uuid>'`,用户真实固化表 54 个条目
682
+ * **全部**带前缀)。`applyManualOrder` 用 `keyOf(item)`(= 树里的真实 id)去 `indexOf`,
683
+ * 于是「把裸 id 写进表」会产生**永远匹配不上的死条目**,并顶掉原本正确的条目。
684
+ *
685
+ * 所以 D2 落表**不能**直接把归一化 id 写进表:必须先用本函数把它还原成**树里的原形态**。
686
+ * 「比较用归一化、写入用原形态」与 {@link normalizeSessionId} 的契约(`仅用于比较,
687
+ * 输出仍用原 id`)逐字一致。
688
+ *
689
+ * @param sessions `effectiveOrder(...).sessions`。
690
+ * @param sessionId 目标会话 id(裸 id / 带前缀 id 都可)。
691
+ * @returns `{ containerKey, sessionId }`;找不到时 `undefined`。
692
+ */
693
+ export declare function placementOfSession(sessions: ReadonlyMap<string, readonly string[]>, sessionId: string): {
694
+ containerKey: string;
695
+ sessionId: string;
696
+ } | undefined;
697
+ /**
698
+ * D2:把**新会话**插到其所属容器固化顺序表的**最前**(幂等)。
699
+ *
700
+ * 语义与边界(用户裁决 D2 + 任务书的边界要求):
701
+ * - **只在 `manual === true` 时写入**。默认模式(`manual !== true`)下新会话本来就排最前,
702
+ * 而且**凭空建表会把用户静默切成手动模式** —— 用户明确要自己点一次「恢复默认排序」,
703
+ * 我们绝不代他改这个开关。所以默认模式**返回 `undefined`**(不写、不建表)。
704
+ * - **幂等**:目标会话已在表首 ⇒ 返回 `undefined`(不产生无谓的 `localStorage` 写入)。
705
+ * - **去重**:先把该 id 从列表里全部剔除再插到首位 ⇒ 不产生重复条目。
706
+ * - **不写运行时置顶**:只写这一个新会话,`running` / 新会话提升本身一律**不进表**
707
+ * (`running` 由 {@link topZoneSessionKeys} 在渲染期推导)。
708
+ * - **不修改入参**:返回新的 {@link ManualOrder} 对象(浅拷贝 + 新数组)。
709
+ * - **写入形态(T6 缺陷 B1)**:写入的字符串必须能被 `applyManualOrder` 的 `keyOf`
710
+ * (= 树里的真实 id)匹配上。规则(按可信度):① 表里已有该会话 ⇒ 复用它的原形态
711
+ * (用户数据是真相);② 否则 `fullOrder`(= `effectiveOrder` 的产物 = 树里的真实 id)
712
+ * 里有 ⇒ 用树里的形态;③ 都没有 ⇒ 用调用方给的 `sessionId`。绝不写入与树/表形态
713
+ * 不一致的「死条目」。
714
+ *
715
+ * @param order 当前的手动顺序。
716
+ * @param containerKey 目标容器 key(由 {@link containerKeyOfSession} 求得)。
717
+ * @param sessionId 新会话 id(**树里的真实形态**;裸 id 亦可,但表里没有该会话时会按原样写入)。
718
+ * @param fullOrder 该容器的**完整生效顺序**(`effectiveOrder(...).sessions.get(containerKey)`)——
719
+ * 仅当表里还没有这个容器(或表项是**空数组**)时用作基底,避免「只写一条、其余丢失」。
720
+ * @returns 新的 {@link ManualOrder};**无需写入时返回 `undefined`**。
721
+ */
722
+ export declare function insertSessionAtFront(order: ManualOrder, containerKey: string, sessionId: string, fullOrder?: readonly string[]): ManualOrder | undefined;
723
+ /** {@link planNewSessionInserts} 的产物。 */
724
+ export interface NewSessionInsertPlan {
725
+ /** 应用全部可落表插入后的手动顺序(无变化时与入参 `order` **同一引用**)。 */
726
+ order: ManualOrder;
727
+ /**
728
+ * 本次「已消费」的新会话 id(**归一化**)—— 调用方应把它们并进
729
+ * {@link TopZoneState.writtenNewSessionIds}。
730
+ *
731
+ * 判据是「落表意图已满足」:写进去了,**或**它本来就在表首(幂等分支)。
732
+ */
733
+ consumed: string[];
734
+ /** 是否真的改动了顺序 ⇒ 调用方需要写 `localStorage`。 */
735
+ changed: boolean;
736
+ }
737
+ /**
738
+ * **D2 落表编排(纯函数)**:把 {@link TopZoneState.newSessionIds} 里尚未消费的新会话
739
+ * 逐个插到其容器固化表最前,并回答「哪些 id 就此消费掉」。
740
+ *
741
+ * ## 为什么需要它(T6 缺陷 B2:编排层必须收敛)
742
+ *
743
+ * `observeTopZone` 的 `newSessionIds` 在本进程内**只增不减**(它是 D3d 的顶部区输入,
744
+ * 不能因为落表就移除)。若 `sidebar.tsx` 每次 effect 重跑都无条件调
745
+ * `insertSessionAtFront`,那么用户**拖动刚建的新会话**(`manualOrder` 变化 ⇒ effect
746
+ * 重跑)时会被**静默搬回表首** —— 用户拖动被回滚、持久顺序被改写。
747
+ *
748
+ * 收敛机制:调用方把本函数返回的 `consumed` 记进
749
+ * {@link TopZoneState.writtenNewSessionIds},下次 effect 重跑时 `alreadyWritten` 里已有
750
+ * 这些 id ⇒ **不再重放**。于是「同一个新会话的落表只发生一次」;用户随后把它拖到任何
751
+ * 位置都不会被 effect 改写。
752
+ *
753
+ * ## 与 `newSessionIds` 的关系
754
+ *
755
+ * 本函数**不**修改 `newSessionIds`(那是 D3d 的顶部区输入,新会话在整个页面会话内
756
+ * 都应被提升到顶部区)。「落表」与「顶部区提升」是两件事,台账分开记。
757
+ *
758
+ * ## 边界
759
+ *
760
+ * - `order.manual !== true` ⇒ 原样返回、**不消费**(默认模式不写、不建表;D2 原文)。
761
+ * - `alreadyWritten` 里的 id ⇒ 跳过(B2 的收敛点)。
762
+ * - 在 `sessions`(树/生效顺序)里找不到的 id ⇒ **不消费**(它当前不可见,例如仍是
763
+ * blank 被过滤掉);等它出现时再落表,不会永久丢失这次 D2 意图。
764
+ * - 落表用 {@link placementOfSession} 得到的**树里真实 id 形态** ⇒ 不会产生死条目(B1)。
765
+ *
766
+ * @param order 当前的手动顺序。
767
+ * @param sessions `effectiveOrder({... , manualOrder: undefined}).sessions`(**纯默认顺序**
768
+ * 的容器划分,与渲染同源)。
769
+ * @param newSessionIds 待落表的新会话 id(`TopZoneState.newSessionIds`,归一化)。
770
+ * @param alreadyWritten 已消费的新会话 id(`TopZoneState.writtenNewSessionIds`,归一化)。
771
+ * @returns 新顺序 + 本次消费的 id + 是否改动。
772
+ */
773
+ export declare function planNewSessionInserts(order: ManualOrder, sessions: ReadonlyMap<string, readonly string[]>, newSessionIds: readonly string[], alreadyWritten: readonly string[]): NewSessionInsertPlan;
774
+ /**
775
+ * **D2 落表台账**:把「落表意图已满足」的新会话 id 记入 {@link TopZoneState.writtenNewSessionIds}。
776
+ *
777
+ * 幂等:全部 id 都已在台账里时返回**同一引用**(不触发无谓重渲染)。
778
+ *
779
+ * ⚠️ 只动 `writtenNewSessionIds`,**不动** `newSessionIds` —— 后者是 D3d 的顶部区输入,
780
+ * 新会话在整个页面会话内都应被提升到容器顶部区。
781
+ *
782
+ * @param state 上一状态。
783
+ * @param sessionIds 本次消费的 id({@link planNewSessionInserts} 的 `consumed`)。
784
+ * @returns 新状态;无变化时返回入参 `state`。
785
+ */
786
+ export declare function markNewSessionsWritten(state: TopZoneState, sessionIds: readonly string[]): TopZoneState;
787
+ /**
788
+ * 尚未消费(还没落表 / 还没确认已在表首)的新会话 id(归一化)—— `sidebar.tsx` 的 D2
789
+ * effect 用它决定「这次要不要跑落表」。
790
+ *
791
+ * @param state 顶部区状态。
792
+ * @returns 待落表的 id(顺序 = `newSessionIds` 的顺序)。
793
+ */
794
+ export declare function pendingNewSessionIdsOf(state: TopZoneState): string[];
795
+ /** {@link buildRows} 的入参(与 `docs/INTERFACES.md` §2.2 对齐)。 */
796
+ export interface SidebarModelInput {
797
+ /** 项目顺序即宿主 `workspaceRegistry.list()` 的顺序(调用方已排好)。 */
798
+ projects: ProjectNodeLike[];
799
+ ungrouped: SessionRowLike[];
800
+ archivedSessionIds: string[];
801
+ currentSessionId?: string;
802
+ /** 节点 key → 是否展开;缺省视为展开。 */
803
+ collapsedKeys: Record<string, boolean>;
804
+ /**
805
+ * 旧式「已全部展开」的节点 key 集合(兼容输入:为真 ⇒ 视为无限层级)。
806
+ * 2026-11-14 起 `sidebar.tsx` 恒传 `{}`,改用 {@link SidebarModelInput.expandLevels}。
807
+ */
808
+ expandedAllKeys: Record<string, boolean>;
809
+ /** 会话容器 key → 渐进展开层级(2026-11-14 PX1;缺省 / 非法 ⇒ 0)。 */
810
+ expandLevels?: Record<string, number>;
811
+ /** 本地过滤查询串(空串 = 不过滤)。 */
812
+ query: string;
813
+ /**
814
+ * 浏览器本地的手动排序(D10,2026-09-21)。
815
+ *
816
+ * **可选**(向后兼容:既有调用方不传 ⇒ 行为与改动前逐字一致)。
817
+ * `manual !== true` ⇒ 完全走默认顺序;搜索模式**不应用**手动顺序
818
+ * (见 {@link buildSearchRows})。
819
+ */
820
+ manualOrder?: ManualOrder;
821
+ /**
822
+ * **顶部区**运行时输入(T11,2026-09-22 用户终裁)。
823
+ *
824
+ * **可选**(向后兼容:既有调用方不传 ⇒ 无任何置顶项,逐字零回归)。
825
+ *
826
+ * 由 `src/sidebar.tsx` 从 {@link TopZoneState} 投影而来(`running` 口径必须含
827
+ * 子代理聚合)。⚠️ 它是**纯运行时**输入,**绝不**参与 `effectiveOrder` 的产物
828
+ * (见那里的不变式)—— 只有 D2 的「新会话插入固化表」是单独的写入动作。
829
+ */
830
+ topZone?: TopZoneInput;
831
+ /**
832
+ * 是否在末尾追加「最近」分区(2026-10-21 WSR5/WSR6)。
833
+ *
834
+ * **可选**(缺省 / `false` ⇒ 不追加,保证既有针对工作区树行数的单测逐字零回归;
835
+ * `src/sidebar.tsx` 恒传 `true`)。
836
+ */
837
+ includeRecent?: boolean;
838
+ /**
839
+ * 已归档工作空间的 `ProjectNode.key` 列表(2026-10-21 WSR1/WSR2 客户端即时过滤)。
840
+ *
841
+ * 传入后,`buildRows` / `effectiveOrder` / `buildRecentRows` / 搜索都会排除这些工作空间
842
+ * 及其下属会话 —— 即使宿主进程尚未重启,前端点击「归档工作空间」也能立即从侧栏消失。
843
+ */
844
+ archivedProjectKeys?: readonly string[];
845
+ /** 会话标题解析(宿主 title 投影缺失时兜底)。 */
846
+ titleOf: (s: SessionRowLike) => string;
847
+ t: Translate;
848
+ }
849
+ /**
850
+ * 「运行中的子代理后代」计数索引:会话 id(已归一化)→ 运行中的子代理后代数(所有层级)。
851
+ *
852
+ * 语义与原生 `runningSubagentCount`(`dsh-client-ui-workspace/lib/client.js` 的
853
+ * `indexSubagentDescendants`,`:285-306`)一致:
854
+ * `counts.get(P)` = 满足「从 P 出发、中间节点全是子代理」的路径上 `running` 的子代理个数。
855
+ *
856
+ * 等价形式(原生的逐层向上累加):对每个 `running` 的子代理,沿 `parentSessionId` 一路
857
+ * 向上走到**第一个非子代理祖先**为止,每经过一个祖先就 +1。
858
+ *
859
+ * 索引是**全局**的(跨容器),与原生的 `list.byId` 一致:子代理会继承父会话的 cwd,正常
860
+ * 情况下两者同容器;即便漂移到别的容器,父行的计数仍与原生相同。
861
+ */
862
+ export type SubagentRunningCounts = ReadonlyMap<string, number>;
863
+ /** {@link indexRunningSubagentDescendants} 需要的最小字段集。 */
864
+ interface Lineage {
865
+ sessionId: string;
866
+ parentSessionId?: string;
867
+ origin?: string;
868
+ running?: boolean;
869
+ }
870
+ /**
871
+ * 建「运行中的子代理后代数」索引(所有层级),见 {@link SubagentRunningCounts}。
872
+ *
873
+ * 累加过程是原生 `indexSubagentDescendants`(`dsh-client-ui-workspace/lib/client.js:285-306`)
874
+ * 的**逐字移植** —— 对每个**子代理**会话,沿父链一路向上、每经过一个父节点就 +1,直到
875
+ * 当前节点不再是子代理 / 没有父 / 遇到已访问节点(`seen` 环保护)为止:
876
+ *
877
+ * ```js
878
+ * let current = descendant
879
+ * while (current?.origin === "subagent" && current.parentId !== undefined && !seen.has(current.id)) {
880
+ * seen.add(current.id)
881
+ * indexed[current.parentId].runningCount += 1 // 仅在 descendant.running 时
882
+ * current = summaries[current.parentId]
883
+ * }
884
+ * ```
885
+ *
886
+ * 父子关系来自 {@link discoverChildEdges}(内部走 `nestSubagents`),因此 id 前缀归一化与
887
+ * 全模块同源。
888
+ *
889
+ * @param sessions 参与索引的全部会话(跨容器;重复 id 会被去重)。
890
+ * @returns 归一化会话 id → 运行中的子代理后代数。**每个入参会话都有键**(没有运行中的
891
+ * 子代理后代时为 `0`)。⚠️ 键是**归一化**后的 id(`session-` 前缀已去掉)——
892
+ * 查询请一律走 {@link subagentCountOf}(它内部归一化),不要直接 `get(原始 id)`。
893
+ */
894
+ export declare function indexRunningSubagentDescendants<T extends Lineage>(sessions: T[]): Map<string, number>;
895
+ /**
896
+ * 入参里出现过的**全部**会话(含归档、blank、子代理;跨所有容器),用于 {@link
897
+ * indexRunningSubagentDescendants}。
898
+ *
899
+ * 口径与原生 `indexSubagentDescendants(list.byId)` 相同 —— 那是一个**未过滤**的扁平表。
900
+ * 若只用可见成员建索引,父会话被归档(或子代理漂到另一个容器)时父行的计数会少算,
901
+ * 与原生不一致。
902
+ */
903
+ /**
904
+ * 「全部会话」的最小来源({@link allSessionsOf} 只需要这三项)。
905
+ *
906
+ * 抽成结构类型是为了让 {@link observationsOf} 也能吃**原始树数据**
907
+ * (`src/sidebar.tsx` 的 `TreeResponse`)—— 顶部区观测只需要树,不需要
908
+ * `collapsedKeys` / `query` / `t` 这些渲染期入参。
909
+ */
910
+ export interface TopZoneObservationSource {
911
+ projects: ProjectNodeLike[];
912
+ ungrouped: SessionRowLike[];
913
+ archivedSessionIds: string[];
914
+ }
915
+ /**
916
+ * 把 {@link SidebarModelInput} 投影成顶部区状态机的观测批次(T5,**纯函数**)。
917
+ *
918
+ * 为什么要这一层:顶部区状态机需要**每条会话**的 `blank` / **聚合** `running` /
919
+ * `subagent` / `archived`,而 `sidebar.tsx` 只有原始树数据。把投影放在这里(而不是
920
+ * `.tsx` 里手写循环)⇒ 投影口径可被 `node --test` 覆盖,`sidebar.tsx` 的改动退化为
921
+ * 「调用一个纯函数 + `useState`」。
922
+ *
923
+ * ⚠️ **`running` 用聚合口径**(= `RenderRow.running`,含任意层级运行中的子代理后代):
924
+ * D3a 明确要求「任意层级有 running subagent」也算运行中。裸的 `session.running` 会让
925
+ * 「只有 subagent 在跑」的会话漏出顶部区 —— 这正是 T4 §4.4 指出的缺口。
926
+ *
927
+ * ⚠️ 观测批次必须**含归档与子代理会话**:状态机要靠「某 id 一直是子代理 / 一直归档」
928
+ * 把它们排除,且它们的 `running` 要参与子代理聚合索引(`indexRunningSubagentDescendants`
929
+ * 本身就是未过滤口径)。
930
+ *
931
+ * ## N1/I3 真实链路修复(T9,2026-09-22)
932
+ *
933
+ * **缺陷**:`buildProjects`(`src/projects.ts` 的 `:400` / `collectUngrouped` 的 `:480`)
934
+ * 已经把**归档会话从树里剔除**,所以树数据里根本没有归档会话 —— 而本函数此前只从树
935
+ * (`allSessionsOf`)取会话 ⇒ 归档会话**从未进过观测批次** ⇒ `observeTopZone` 的
936
+ * `seen` 里没有它们 ⇒ 「基线时已归档、之后取消归档并收到新消息」的**旧**会话会被
937
+ * `firstSeenAfterStart` 判成新会话并写进固化表表首(违反 D5)。
938
+ * T7 的单测 fixture 把归档会话**同时**放进树和 `archivedSessionIds`,与真实链路**不同构**
939
+ * ⇒ 那条用例是**恒真测试**(T8 实测真实链路下 `newSessionIds = ['oldarch']`)。
940
+ *
941
+ * **修复**:把 `source.archivedSessionIds` **单独投影**成 `archived: true` 的观测
942
+ * (见下方 `archivedIds` 循环),使 `seen` 覆盖归档会话。这些观测:
943
+ * - **进 `known`**(「存在过」的事实必须记住 ⇒ 取消归档后不误判新会话);
944
+ * - **不产生** `blankOf` / `runningOf` 轨迹,**不参与**顶部区判定(`observeTopZone`
945
+ * 里 `observation.archived` 被跳过)。
946
+ *
947
+ * `updatedAt` 对归档 id 未知(归档会话不在树里,没有宿主摘要)⇒ 填 `0`(有限值,
948
+ * 不会因此被时间序判据选中;且 `archived` 为真时本就不会进入新会话判定)。
949
+ *
950
+ * @param input 与 `buildRows` 同一份入参。
951
+ * @returns 每条输入会话一条观测(顺序 = `allSessionsOf` 的顺序),**后接**归档 id 观测。
952
+ */
953
+ export declare function observationsOf(source: TopZoneObservationSource): TopZoneObservation[];
954
+ /**
955
+ * 把 {@link TopZoneState} 投影成渲染期用的 {@link TopZoneInput}(T5,**纯函数**)。
956
+ *
957
+ * `runningSessionIds` 直接从观测轨迹(`runningOf`)里取 —— 它就是**聚合后**的口径
958
+ * (见 {@link observationsOf}),与 `RenderRow.running` 同源。
959
+ *
960
+ * @param state 顶部区状态机状态。
961
+ * @returns 渲染期输入(全部为归一化 id)。
962
+ */
963
+ export declare function topZoneInputOf(state: TopZoneState): TopZoneInput;
964
+ /**
965
+ * 「最近」分区的排序键:`max(updatedAt, 有限的 lastActivityAt)`(2026-10-29 RAS1/RAS4)。
966
+ *
967
+ * - `lastActivityAt` 缺失 / 非有限数字 ⇒ 回退 `updatedAt`(与 WSR6 旧行为逐字一致)。
968
+ * - `lastActivityAt` 比 `updatedAt` 旧 ⇒ 仍取 `updatedAt`(不降低排序键)。
969
+ * - `updatedAt` 本身非法 ⇒ 该边按 `0` 处理,保证结果恒为有限数字。
970
+ *
971
+ * ⚠️ **只有**「最近」分区使用本函数;工作区树 / 顶部区 / 手动顺序不得消费它。
972
+ */
973
+ export declare function recentActivityOf(session: {
974
+ updatedAt: number;
975
+ lastActivityAt?: number;
976
+ }): number;
977
+ /**
978
+ * 单节点截断:保留**输入顺序**里的前 `limit` 条非 blank 会话(逐字对齐原生
979
+ * `collapsedSessionRows` 的「前 N 条」部分)。
980
+ *
981
+ * 行为:
982
+ * - `blank === true` 的会话始终保留且**不占**名额(原生:`if (session.blank) return true`);
983
+ * - 其余会话按输入顺序保留前 `limit` 条(原生:`ordinaryCount >= limit ⇒ false`);
984
+ * - `limit <= 0` 按 0 处理(只留 blank 的);
985
+ * - `hiddenCount = sessions.length - visible.length`(原生同式)。
986
+ *
987
+ * ⚠️ **T13(2026-09-22 用户终裁):本函数不再接受 `currentSessionId`。**
988
+ * 曾经存在的「当前会话保底进前 limit 条」(`promote` 分支)已**整体删除**:它在 T11
989
+ * 删除 `isCurrent` 置顶后变成**可达**,使「把当前会话拖到第 6 位之后」出现**视觉零位移**
990
+ * (持久表已变、渲染未变 —— 与用户投诉的首要缺陷同形)。用户裁决「**拖拽顺序完全优先**」,
991
+ * 并明确接受副作用(当前会话若被截断到不可见,就是看不见)。
992
+ *
993
+ * 调用方({@link emitContainer})因此**只**按顺序截断,不再传任何「当前会话」线索 ——
994
+ * 渲染层对已结束会话的位置**完全**由持久拖拽顺序决定。调用方若还想让某条会话必进可见区,
995
+ * 唯一正当途径是**渲染期置顶**({@link topZoneSessionKeys} → `applyManualOrder` 的
996
+ * `pinnedKeys`,运行中 / 尚未落表的新会话),那是**先于**截断生效的另一机制。
997
+ *
998
+ * @param sessions 输入会话(**不被修改**,返回的是同一批引用)。
999
+ * @param limit 每个容器的非 blank 可见上限;非有限值按 0 处理。
1000
+ * @returns 可见会话(保持输入顺序)与被隐藏条数。
1001
+ */
1002
+ export declare function truncateSessions<T extends {
1003
+ sessionId: string;
1004
+ }>(sessions: T[], limit: number): {
1005
+ visible: T[];
1006
+ hiddenCount: number;
1007
+ };
1008
+ /**
1009
+ * 子代理折叠:`parentSessionId` 指向**同组内**存在的父会话时挂为子行(深度 +1)。
1010
+ *
1011
+ * 规则:
1012
+ * - 顶层会话 `depth: 0`,直接子代理 `depth: 1`;不支持更深嵌套;
1013
+ * - 兜底:父会话不在本组内、父会话就是自己、或父会话**自己也是子代理**时,该会话
1014
+ * 平铺为 `depth: 0`(不凭空多缩进,也不丢);
1015
+ * - 父 id 与候选父 id 都先做 `session-` 前缀归一化后再比较(输出仍是原对象);
1016
+ * - 输出顺序:每个顶层会话后面紧跟它的子代理,子代理之间保持输入顺序;
1017
+ * - 环(A→B→A)软失败:环上成员按顶层处理,不抛错、不丢行(同原生 `flattenLineage`)。
1018
+ *
1019
+ * @param sessions 同一容器内的会话(**不被修改**)。
1020
+ * @returns 从容器根部展平的 `{ session, depth }` 序列。
1021
+ */
1022
+ export declare function nestSubagents<T extends {
1023
+ sessionId: string;
1024
+ parentSessionId?: string;
1025
+ origin?: string;
1026
+ }>(sessions: T[]): Array<{
1027
+ session: T;
1028
+ depth: number;
1029
+ }>;
1030
+ /**
1031
+ * 从项目 `key` 解出 workspaceId —— **仅非 git 工作区**(key 形态为 `ws:<workspaceId>`)。
1032
+ *
1033
+ * 存在的理由:**非 git 工作区的 `worktrees` 恒为空数组**(`buildProjects` 的 `'flat'` 分支
1034
+ * 不建 worktree 节点),所以它的工作区 id 既不在任何 worktree 节点上,也只能从 key 解出。
1035
+ * 这是渲染层「在该工作区新建会话」(非 git 行 hover 的 `+`)**唯一**的 id 来源 ——
1036
+ * 漏掉它,那一行的 `+` 会因为 `workspaceId === undefined` 而根本不渲染。
1037
+ *
1038
+ * git 项目的 key 是 commonDir,本函数恒返回 `undefined`(它的 id 要从 worktree 节点取)。
1039
+ *
1040
+ * 导出以便单测覆盖(`src/sidebar.tsx` 是 `.tsx`,不进 `lib/`,逻辑无法被 `node --test` 直接测)。
1041
+ */
1042
+ export declare function workspaceIdFromProjectKey(key: string): string | undefined;
1043
+ /**
1044
+ * 一次「重新排序」的结果:三层各自的**完整**顺序(不截断、不折叠)。
1045
+ *
1046
+ * 渲染层拖拽落点时用它:把「当前完整顺序 + 落点」交给 {@link reorderKeys} 得到新顺序,
1047
+ * 再写进 {@link ManualOrder}。**必须用完整顺序而不是渲染行** —— 容器折叠时它的会话行
1048
+ * 根本不存在,5 条截断还会砍掉尾部;用渲染行算会让「第 6 条之后」的顺序在每次拖拽时
1049
+ * 被截断成只剩可见的那几条。
1050
+ */
1051
+ export interface EffectiveOrder {
1052
+ /** 顶层项目顺序(`ProjectNode.key`,**不含**未分组)。 */
1053
+ projects: string[];
1054
+ /** 项目 key → 该项目内 worktree 路径顺序(`WorktreeNode.path`)。 */
1055
+ worktrees: Map<string, string[]>;
1056
+ /** 容器 key → 该容器内**可见**会话的 sessionId 顺序(未截断)。 */
1057
+ sessions: Map<string, string[]>;
1058
+ }
1059
+ /**
1060
+ * 取三层各自的**完整生效顺序**(默认顺序 + 已应用的手动顺序)。
1061
+ *
1062
+ * 与 {@link buildRows} 走**同一批**内部函数(`containersOfProject` / `visibleMembers` /
1063
+ * {@link sortedByRecency} / {@link applyManualOrder}),因此不可能与树里看到的顺序分叉 ——
1064
+ * 这是本函数存在的全部理由(容器 key 的推导规则只有一处实现)。
1065
+ *
1066
+ * 与 `buildRows` 的两处**有意**差异:
1067
+ * - **不应用折叠与 5 条截断**:返回的是每个容器的全部可见成员(见 {@link EffectiveOrder});
1068
+ * - **不产出未分组行**:`projects` 里没有 `UNGROUPED_KEY`(它不是真实项目,§2.6 裁定 1),
1069
+ * 但未分组的**会话**照常进 `sessions`(键 = `p:${UNGROUPED_KEY}`)。
1070
+ *
1071
+ * ⚠️ **第三处有意差异(T11,2026-09-22 用户终裁)**:本函数**不应用任何运行时顶部区**。
1072
+ * 顶部区是**纯运行时推导**(由会话此刻是否在跑、以及新会话是否已落表决定),而本函数的输出
1073
+ * 正是 `commitDrag` 首次拖拽时**全量固化进 `localStorage`** 的那份顺序
1074
+ * (`src/sidebar.tsx` 的 `commitDrag`:`effectiveOrder({ ...treeInput, manualOrder: undefined })`)。
1075
+ * 若这里也应用顶部区,就会把「运行时置顶」变成「持久化钉在第 1 位」—— 用户关掉那个会话后
1076
+ * 它仍赖在最前面,且持久顺序被污染。所以本函数把 `context.topZone` **硬置 `undefined`**,
1077
+ * 返回的永远是「不含任何运行时置顶的真实顺序」。**这是被测试锁定的不变式**
1078
+ * (见 `test/tree-model.test.mjs` 的 `effectiveOrder` 持久化用例)。
1079
+ *
1080
+ * `input.manualOrder` 缺省或 `manual !== true` 时,返回的就是**纯默认顺序** ——
1081
+ * 这正是「首次拖拽时固化全量顺序」所需要的输入。
1082
+ *
1083
+ * @param input 与 `buildRows` 同一份入参。
1084
+ * @returns 三层的完整生效顺序。
1085
+ */
1086
+ export declare function effectiveOrder(input: SidebarModelInput): EffectiveOrder;
1087
+ /**
1088
+ * 把「被拖项 + 落点」换算成新的顺序列表(**纯函数**)。
1089
+ *
1090
+ * 语义与原生 `commitSessionDrag` 的可见项算法一致:
1091
+ * 1. 从当前列表里**摘掉**被拖项;
1092
+ * 2. 找到落点项在「摘掉之后」的下标;
1093
+ * 3. `before` ⇒ 插在它前面;`after` ⇒ 插在它后面。
1094
+ *
1095
+ * @param keys 当前**完整**顺序(默认顺序 + 已应用的手动顺序)。
1096
+ * @param draggedId 被拖项的 id。
1097
+ * @param overId 落点项的 id。
1098
+ * @param half 落点在行的上半(`before`)还是下半(`after`)。
1099
+ * @returns 新顺序;**无需改动**时返回 `null`(落点就是自己 / 已在原位 / 落点不在列表里)。
1100
+ * 返回 `null` 而不是原数组,是为了让调用方区分「拖了但没变化」与「真的重排了」——
1101
+ * 前者不该把 `manual` 置 true(否则用户只是原地抖一下鼠标就永久切到手动排序了)。
1102
+ */
1103
+ export declare function reorderKeys(keys: string[], draggedId: string, overId: string, half: 'before' | 'after'): string[] | null;
1104
+ /**
1105
+ * 把**持久手动顺序表**与「当前默认顺序」对齐(2026-10-22 DR6)。
1106
+ *
1107
+ * 规则(与渲染期 `applyManualOrder` 的表外项语义**逐字一致**):
1108
+ * 1. 表内项保持原相对顺序(含**当前不可见**的项 —— 归档会话/归档工作区的槽位因此不丢,
1109
+ * 取消归档后回到原位);
1110
+ * 2. 表外项按 `defaults` 的顺序**追加到末尾**(渲染期正是这样画的);
1111
+ * 3. 去重(同一 key 只认第一次出现)、忽略非字符串/空串;
1112
+ * 4. 纯函数:不修改入参,返回新数组。
1113
+ *
1114
+ * 为什么需要它(缺陷背景):`manualOrder` 是**首次拖拽时固化的快照**,之后新增的工作区 /
1115
+ * worktree / 会话都不在表里。`commitDrag` 旧实现直接拿持久表做 `reorderKeys`,而
1116
+ * `reorderKeys` 对「拖拽源不在表里」与「落点不在表里」都返回 `null` ⇒ **整次拖拽静默无效**
1117
+ * (用户看到的「拖不动 / 松手没反应」)。先对齐再换算,就能让新增项照常参与排序。
1118
+ *
1119
+ * @param order 持久表里的该层顺序(可能缺项 / 为空 / undefined)。
1120
+ * @param defaults 当前默认顺序(`effectiveOrder` 的产物,与渲染同源)。
1121
+ * @returns 对齐后的完整顺序(新数组)。
1122
+ */
1123
+ export declare function reconcileManualOrder(order: readonly string[] | undefined, defaults: readonly string[]): string[];
1124
+ /**
1125
+ * **拖拽换算的唯一入口**(2026-10-22 DR6,替代 `commitDrag` 里直接调 `reorderKeys`)。
1126
+ *
1127
+ * = `reorderKeys(reconcileManualOrder(order, defaults), draggedId, overId, half)`:
1128
+ * 先把持久表与当前默认顺序对齐(补齐表外的新增项),再计算新顺序。
1129
+ *
1130
+ * 语义与 `reorderKeys` 逐字一致:拖到自己身上、已在原位、找不到落点 ⇒ `null`(不写表,
1131
+ * 不把用户「原地抖一下」误变成持久改动)。
1132
+ *
1133
+ * @param order 持久表里的该层顺序(手动模式);`undefined` = 非手动 ⇒ 直接用默认顺序。
1134
+ * @param defaults 该层当前默认顺序(`effectiveOrder` 的产物)。
1135
+ * @param draggedId 拖拽源 id(树里的真实形态,不带容器前缀)。
1136
+ * @param overId 落点 id(同上)。
1137
+ * @param half 落点在目标之前 / 之后。
1138
+ * @returns 新的顺序;无需改动 ⇒ `null`。
1139
+ */
1140
+ export declare function reorderManualScope(order: readonly string[] | undefined, defaults: readonly string[], draggedId: string, overId: string, half: 'before' | 'after'): string[] | null;
1141
+ /**
1142
+ * 把树模型摊平成渲染行序列(已应用展开态、5 条截断、搜索过滤)。纯函数。
1143
+ *
1144
+ * 渲染顺序:
1145
+ * ```
1146
+ * [project 行]
1147
+ * [worktree 行] ← git 项目逐个(含单 worktree;保持宿主顺序)
1148
+ * [session 行] … ← depth 2
1149
+ * [more 行] ← 仅当被截断
1150
+ * [history 行] ← 仅当 project.history 有**可见成员**(非空且过滤后非空)
1151
+ * [session 行] … ← depth 2
1152
+ * [more 行]
1153
+ * [下一个 project 行]
1154
+ * …
1155
+ * [未分组行] ← 仅当 ungrouped 有**可见成员**时(project 行形态,key = `p:${UNGROUPED_KEY}`)
1156
+ * [session 行] … ← depth 1
1157
+ * [more 行]
1158
+ * ```
1159
+ *
1160
+ * **没有会话行是子代理**:`origin === 'subagent'` 的会话在任何容器里都不产生行
1161
+ * (原生 `sessionVisible`),它们只通过父行的 `subagentCount` 胶囊体现。
1162
+ *
1163
+ * 关键约束:
1164
+ * - D11(2026-09-21 修订):**git 项目**(`isGit === true`)恒产生 worktree 子行,
1165
+ * 会话挂 worktree 行下(`parentKind: 'worktree'`、`depth: 2`);只有**非 git 工作区**
1166
+ * 才平铺,会话直接挂 project 行下(`parentKind: 'project'`、`depth: 1`);
1167
+ * - 展开态:`collapsedKeys[key] === true` 才折叠(缺省展开);
1168
+ * - 每个会话容器各自独立应用 `truncateSessions(…, COLLAPSED_SESSION_LIMIT)`;
1169
+ * 容器内顶层会话数 `<= COLLAPSED_SESSION_LIMIT` ⇒ **不产生** more 行(没东西可折叠);
1170
+ * ⚠️ **T13**:截断**只**按传入顺序取前 N 条,**不再**为「当前会话」做任何保底 ——
1171
+ * 已结束会话的位置完全由持久拖拽顺序决定(见 {@link truncateSessions} 的 JSDoc);
1172
+ * - `expandedAllKeys[容器key] === true` 且容器**确实超过** `COLLAPSED_SESSION_LIMIT` 条时:
1173
+ * 全量输出该容器会话,**仍产出恰好一条** more 行,且其 `hiddenCount` 保留真实值
1174
+ * (=「若折叠会隐藏多少条」,即 `truncateSessions(...).hiddenCount`)—— 这条 more 行是
1175
+ * 用户回到折叠态的**唯一入口**(PRD US4「点击后全部展开,变为收起」)。渲染层按
1176
+ * `expandedAllKeys[parentKey] === true` 取 `sessions.collapse`,否则取
1177
+ * `sessions.expand`(契约 §2.6 裁定 2:more 行**无** label,取词在渲染层);
1178
+ * - `expandedAllKeys[容器key] !== true` 且被截断 ⇒ 前 `COLLAPSED_SESSION_LIMIT` 条 + 一条
1179
+ * more 行,`hiddenCount` = 隐藏条数(`truncateSessions` 的真实结果);
1180
+ * - 子代理在任何容器里都不出现;归档会话也不出现;blank 会话只显示当前那一条且不占名额;
1181
+ * - **父行状态点含子代理(需求 A,2026-09-21)**:`row.running = 该会话自己的 running ||
1182
+ * subagentCount > 0`(对齐原生 `sessionStatuses` 的 `runningSubagentCount > 0 ⇒ ongoing`)。
1183
+ * 多层链(depth 3)由 {@link indexRunningSubagentDescendants} 一并累加到顶层可见行;
1184
+ * 子代理全不跑且自身空闲 ⇒ 仍是 `idle`(`running: false`)。**树与搜索两条路径同源**
1185
+ * (判据写在 {@link toSessionRow} 里)。`runningCount` 的口径**不变**(仍只数
1186
+ * `session.running`)—— 渲染层无消费者,本次不动(用户裁决 Q1);
1187
+ * - **顶部区(T11,2026-09-22 用户终裁)**:每个容器内,**正在运行**的会话(自身
1188
+ * `running` **或** 任意层级有运行中的子代理)排在本容器**最前**(先于 5 条截断生效,
1189
+ * 但**顶部区成员超过 `COLLAPSED_SESSION_LIMIT` 条时,超出的仍会被截断** —— 见
1190
+ * `T5/截断: 顶部区成员数 > 5 时,只有前 5 条可见`),并按 `updatedAt` 降序排列;
1191
+ * 它们**不可拖动**(拖拽接线在 `sidebar.tsx` 层不给这些行安装)。
1192
+ * **尚未落表的新会话**同样进入顶部区(D2/D3d)。
1193
+ * ⚠️ 已结束的会话(含用户正在查看的旧会话、含刚跑完的会话)**不再固定置顶** ——
1194
+ * 位置完全由持久拖拽顺序决定,且**必须可正常拖动**。「刚结束保留」与「当前会话置顶」
1195
+ * 两个机制已按用户终裁**删除**(见 {@link topZoneSessionKeys})。
1196
+ * 顶部区是**纯运行时推导**,**不写进 `localStorage`**({@link effectiveOrder} 刻意不应用);
1197
+ * - `query.trim()` 非空 ⇒ 扁平模式:只输出会话行(`depth: 0`),不应用展开态、截断与顶部区
1198
+ * (搜索结果跨容器,容器内相对顺序无意义);
1199
+ * - **手动顺序(D10,2026-09-21)**:`input.manualOrder` 且 `manual === true` 时,三层
1200
+ * 各自在**默认排序之后、截断之前**叠加手动顺序({@link applyManualOrder}):
1201
+ * 项目按 `projects`(键 = `ProjectNode.key`)、worktree 按 `worktrees[projectKey]`
1202
+ * (键 = `WorktreeNode.path`,**只在同一项目内**)、会话按 `sessions[容器key]`
1203
+ * (键 = `sessionId`,**只在同一容器内**)。列表外的新项按默认顺序追加到末尾;
1204
+ * 已消失的项被忽略。**搜索模式不应用**(见 {@link buildSearchRows})。
1205
+ * `manualOrder` 缺省或 `manual !== true` ⇒ 与不传逐字一致(零回归);
1206
+ * - 纯函数:不修改任何入参(排序前先拷贝)。
1207
+ *
1208
+ * @param input 侧栏模型入参(见 {@link SidebarModelInput})。
1209
+ * @returns 渲染行序列;搜索无匹配时返回空数组(渲染层据此显示 `search.empty`)。
1210
+ */
1211
+ export declare function buildRows(input: SidebarModelInput): RenderRow[];
1212
+ /**
1213
+ * 推导侧栏底部「最近」分区行序列(2026-10-21 WSR5/WSR6,AC4–AC6;2026-10-29 RAS1/RAS3 改排序键)。
1214
+ *
1215
+ * - 汇总全局所有可见顶层会话(跨所有 project 的 worktree / flat / history 及 ungrouped,
1216
+ * 统一走 {@link isVisibleMember} 排除子代理、归档与非当前 blank),按归一化 `sessionId` 去重;
1217
+ * - 固定按**最后更新时间**({@link recentActivityOf} = `max(updatedAt, lastActivityAt)`)降序
1218
+ * (`sessionId` 升序 tiebreak)排列,最多保留 {@link RECENT_SESSION_LIMIT}(100)条;
1219
+ * ⚠️ `lastActivityAt` 只在本分区消费 —— 工作区树/顶部区仍按 `updatedAt`;
1220
+ * - 产出 `kind: 'recent'` 分区头(`key: 'r:__recent__'`),支持 `collapsedKeys['r:__recent__']` 折叠,
1221
+ * 展开时直接平铺全部(最多 100 条)`rs:<sessionId>` 会话行,**不产生 `more` 行**;
1222
+ * - 搜索模式(`query` 非空)或无可见会话时返回 `[]`。
1223
+ */
1224
+ export declare function buildRecentRows(input: SidebarModelInput): RenderRow[];
1225
+ export {};
1226
+ //# sourceMappingURL=tree-model.d.ts.map