@mzzsfy/dsh-turn-notify 0.10.0 → 0.11.0

package/README.md

@@ -97,6 +97,10 @@ turn-notify:
 
 通知实际送达时,侧边栏会话列表中对应会话行以背景脉冲闪烁强调,六类各一色(完成绿/出错红/提问蓝/中断橙/审批黄/上限紫),点击该会话行即停止。开关在面板"偏好"页首项(独立开关,本机生效,各浏览器独立),默认开启。并行多会话时用于快速定位状态刚更新的会话:运行中的会话不闪烁(与 dsh 原生状态点分工——状态点表达运行中,闪烁表达已更新待查看),会话重新进入运行状态时闪烁自动让位;聚焦时正在查看的会话不闪烁,失焦期间本会话的通知照常闪烁,返回窗口即自动消失(回来即已读,焦点与页面可见双通道)。行定位按会话标题文本匹配,标题默认与侧边栏行同源(session-title 投影);该服务缺失或不可用(如伪会话无事件日志)时回落会话事件内存储的标题,可能与侧边栏不同步。会话行未渲染(列表折叠/懒加载未滚动到)时该次高亮静默跳过。重开页面的冷启动静默对齐同样挂高亮(见"多窗口只响一次"),重开即见哪些会话有动静。
 
+## 工作区文件夹运行标记
+
+侧边栏会话列表按工作区分组(官方 WorkspaceBrowser 分组模式)时,有运行中会话的工作区文件夹组头显示脉冲运行点并给文件夹图标着色,游离(未归属任何工作区)的可见运行中会话使末位「未分组」组头同样标记——折叠与展开同样生效。归属与运行态一律取服务快照投影,DOM 仅按下标对位官方组容器;组容器数漂移(单列表模式/搜索态/结构变更)即清除标记不误标。图标着色让位官方 folderActive(展开且含当前会话)态。开关在面板"偏好"页"会话列表"卡(存宿主配置,各浏览器共用),默认开启,变更刷新页面生效。
+
 ## 多窗口只响一次
 
 同一地址(同源)打开的多个窗口共享一次呈现:各窗口以长轮询挂起在 host 的通知队列上(事件产生或配置变更即时返回,空闲期单次挂起至多数十秒,失败按指数退避重连),经 localStorage 协调,仅一个窗口抢先呈现——发声并弹出页内提示、系统弹窗、高亮会话行,其余窗口全部跳过,不止声音。通知在产生后的下一次唤醒即送达,通常亚秒级;不同浏览器或不同地址打开的窗口各自发声互不感知。窗口关闭/刷新期间错过的通知不做重开回放:启动首轮静默对齐游标与完成标记,不逐条补发提示与声音(等待用户动作的审批与提问例外,照常呈现);未读会话行高亮不在静默范围,照常挂上。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-turn-notify",
   "description": "消息通知:六类回合事件送达声音、系统弹窗、页内提示、webhook、IM 与宿主桌面通知;内置八种合成音色,自定义音效,按事件分类指定;多窗口只响一次",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -864,6 +864,55 @@ window.__ModuleLoader__.load({
       row.className = row.className.split(' ').filter((name) => name !== SESSION_HL_CLASS && name.indexOf(SESSION_HL_CLASS + '--') !== 0).join(' ')
     }
 
+    // ---- 工作区文件夹运行标记 ----
+
+    // 官方组容器 CSS module 类名后缀(哈希前缀随构建漂移,后缀稳定)与自家标记属性;
+    // 扫描合并窗口覆盖聊天流式输出的高频 DOM mutation
+    const FOLD_SECTION_SELECTOR = 'div[class$="_groupSection"]'
+    const FOLD_RUNNING_FLAG = 'data-tn-folder-running'
+    const FOLD_SCAN_DELAY_MS = 50
+
+    // 运行标记状态:官方 dsh-client-ui-workspace 分组语义的投影——
+    // 归属走 workspace 账本 sessionIds 一级映射(官方 owningGroupKey 同构,无 cwd 回退),
+    // 游离会话入末位未分组桶;可见性镜像官方 sessionVisible(subagent / 已归档 /
+    // 空白且非当前排除),组内任一可见会话 running 即该工作区运行中。
+    // ids 保工作区登记序(官方组渲染序 = 快照 items 序),供 DOM 组容器按下标对位
+    function folderRunningState(sessionsState, workspacesState) {
+      const byId = (sessionsState && sessionsState.byId) || {}
+      const ids = (sessionsState && sessionsState.ids) || []
+      const current = sessionsState ? sessionsState.current : undefined
+      const workspaces = workspacesState && Array.isArray(workspacesState.items) ? workspacesState.items : []
+      const archived = new Set((workspacesState && workspacesState.archivedSessionIds) || [])
+      const visible = (row) => Boolean(row)
+        && row.origin !== 'subagent'
+        && !archived.has(row.id)
+        && (!row.blank || row.id === current)
+      const running = new Set()
+      const accounted = new Set()
+      const workspaceIds = []
+      for (const workspace of workspaces) {
+        // 主键不做防御过滤,与官方 groupByWorkspace 同构:items 长度即组容器对位基准,
+        // 过滤会让 ids 短于容器数,恰差一时错位成「末位未分组桶」对位
+        workspaceIds.push(workspace.workspaceId)
+        const sessionIds = Array.isArray(workspace.sessionIds) ? workspace.sessionIds : []
+        for (const sessionId of sessionIds) {
+          const row = byId[sessionId]
+          if (!row) continue
+          accounted.add(sessionId)
+          if (row.running && visible(row)) running.add(workspace.workspaceId)
+        }
+      }
+      let ungrouped = false
+      for (const sessionId of ids) {
+        if (accounted.has(sessionId)) continue
+        const row = byId[sessionId]
+        if (row && row.running && visible(row)) ungrouped = true
+      }
+      return { ids: workspaceIds, running, ungrouped }
+    }
+
+    const FOLD_SWITCH_TITLE = '侧边栏会话列表按工作区分组时,有运行中会话的文件夹组头显示运行点并给文件夹图标着色,文件夹折叠与展开同样生效;游离会话所在的「未分组」组同样标记;单列表模式下无此标记。停用即全部隐藏,刷新页面生效。'
+
     // ---- 点击直达会话:页内卡片与系统弹窗共用 ----
 
     // 按通知单元激活会话:聚焦窗口并模拟点击侧边栏会话行(官方行点击即切换会话);
@@ -1019,6 +1068,7 @@ window.__ModuleLoader__.load({
       suppressSubagentWake: true,
       hostNotify: false,
       hostNotifyFallback: false,
+      folderRunningEnabled: true,
       enabled: Object.fromEntries(CATEGORIES.map((key) => [key, true])),
       imTargets: [],
     }
@@ -1136,6 +1186,18 @@ window.__ModuleLoader__.load({
       '@media (prefers-reduced-motion: reduce) {',
       '  .tn-sess-hl { animation:none; background-color:color-mix(in srgb, var(--tn-sess-color, #4c8dff) 50%, var(--dsw-alias-bg-base, #202020) 50%); }',
       '}',
+      // 工作区文件夹运行标记:官方组容器自带 position:relative,运行点绝对定位于
+      // 组容器左缘、垂直对齐组头行中线(行高 34px 之半即 top 17px,落于组头行左内边距
+      // 区),零布局位移;图标着色让位官方 folderActive(展开含当前)态;色值取官方
+      // ongoing 运行点的实际色值(--dsh-state-ongoing 在官方仅定义于其状态点组件局部,
+      // 组容器上下文读不到,直接引用其回退源)
+      'div[class$="_groupSection"][data-tn-folder-running] { --tn-fold-running-color: var(--dsw-static-deepseek-450); }',
+      'div[class$="_groupSection"][data-tn-folder-running]::before { content:""; position:absolute; left:0; top:17px; width:5px; height:5px;',
+      '  margin-top:-2.5px; border-radius:999px; background:var(--tn-fold-running-color);',
+      '  animation:tn-fold-running-pulse 1.2s ease-in-out infinite; }',
+      'div[class$="_groupSection"][data-tn-folder-running] span[class$="_folder"]:not([class$="_folderActive"]) { color:var(--tn-fold-running-color); }',
+      '@keyframes tn-fold-running-pulse { 0%, 100% { opacity:1; } 50% { opacity:.35; } }',
+      '@media (prefers-reduced-motion: reduce) { div[class$="_groupSection"][data-tn-folder-running]::before { animation:none; } }',
     ].join('\n')
 
     function h(type, props) {
@@ -1408,6 +1470,21 @@ window.__ModuleLoader__.load({
         })
       }
 
+      // 文件夹运行标记开关:乐观回填,服务端失败回滚;变更刷新页面生效(标记
+      // 注入在插件激活时按配置装配)
+      async function toggleFolderRunning(checked) {
+        const previous = config.folderRunningEnabled
+        setConfig({ ...config, folderRunningEnabled: checked })
+        try {
+          const res = await api('/api/turn-notify/config', { method: 'POST', body: JSON.stringify({ folderRunningEnabled: checked }) })
+          setConfig({ ...DEFAULT_CONFIG, ...res })
+          patch('工作区文件夹运行标记已' + (res.folderRunningEnabled !== false ? '启用' : '停用') + ',刷新页面后生效')
+        } catch (error) {
+          setConfig((prev) => ({ ...prev, folderRunningEnabled: previous }))
+          patch('切换失败:' + (error && error.message ? error.message : String(error)), 'error')
+        }
+      }
+
       async function requestPermission() {
         try {
           const next = await Notification.requestPermission()
@@ -1794,6 +1871,20 @@ window.__ModuleLoader__.load({
                 ' 弹窗不可用时以标题闪烁替代'),
             ]),
           ) : null,
+          activeTab === '偏好' ? h('div', { className: 'tn-card' },
+            h('div', { className: 'tn-card__head' },
+              h('span', { className: 'tn-card__title' }, '会话列表'),
+              h('span', { className: 'tn-card__sub' }, '存宿主配置,各浏览器共用'),
+            ),
+            field('运行标记', [
+              h('label', { className: 'tn-meta tn-switch', title: FOLD_SWITCH_TITLE },
+                ...switchToggle({
+                  checked: config.folderRunningEnabled !== false,
+                  onChange: (e) => void toggleFolderRunning(e.target.checked),
+                }),
+                ' 有运行中会话的文件夹显示运行点'),
+            ], '侧边栏按工作区分组时,运行中的文件夹组头显示脉冲运行点并给图标着色,折叠与展开同样生效;变更刷新页面生效。'),
+          ) : null,
           activeTab === '音效' ? [
             h('div', { className: 'tn-card' },
               h('div', { className: 'tn-card__head' },
@@ -2001,17 +2092,95 @@ window.__ModuleLoader__.load({
     }
 
     return {
-      inject: ['slots'],
+      inject: ['slots', 'sessions', 'workspaces'],
       apply(ctx) {
+        const sessions = ctx.get('sessions')
+        const workspaces = ctx.get('workspaces')
         // 样式挂载宿主文档级:通知栈在面板未打开时也要有完整样式
         ctx.effect(() => {
           const style = document.createElement('style')
+          // 自带 data-plugin:缺失时宿主 claimStyles 会把它归属给后续材质化插件,其 HMR 重建即误删
+          style.setAttribute('data-plugin', '@mzzsfy/dsh-turn-notify')
           style.textContent = CSS
           document.head.appendChild(style)
           return () => style.remove()
         }, 'turn-notify styles')
         // 激活即轮询:通知链路不依赖设置面板是否打开过
         start()
+        // 工作区文件夹运行标记:服务快照投影 + DOM 组容器下标对位,状态变化经
+        // 订阅与 DOM 变更(合并窗口)双通道驱动;开关读宿主配置,变更刷新页面生效
+        let foldEnabled = null
+        ctx.effect(() => {
+          if (typeof MutationObserver === 'undefined' || typeof document.querySelectorAll !== 'function') return
+          let disposed = false
+          let timer = null
+          function clearAll() {
+            document.querySelectorAll('[' + FOLD_RUNNING_FLAG + ']').forEach((section) => {
+              section.removeAttribute(FOLD_RUNNING_FLAG)
+            })
+          }
+          function scan() {
+            const sections = document.querySelectorAll(FOLD_SECTION_SELECTOR)
+            if (sections.length === 0) {
+              clearAll()
+              return
+            }
+            // 开关未决时仅清除:终态正确且停用用户刷新页面不闪现标记
+            if (foldEnabled === null) {
+              clearAll()
+              return
+            }
+            const state = foldEnabled
+              ? folderRunningState(sessions.list.getSnapshot(), workspaces.list.getSnapshot())
+              : { ids: [], running: new Set(), ungrouped: false }
+            const expected = state.ids.length
+            // 数量不变量:组容器数 = 工作区数 或 工作区数+1(末位未分组桶);
+            // 漂移(单列表模式 / 搜索态 / 官方结构变更)即清除标记,不误标
+            const ungroupedLast = sections.length === expected + 1
+            if (sections.length !== expected && !ungroupedLast) {
+              clearAll()
+              return
+            }
+            sections.forEach((section, index) => {
+              const running = index < expected ? state.running.has(state.ids[index]) : ungroupedLast && state.ungrouped
+              // 同值跳过:流式输出期间扫描高频,重复写属性触发无谓的 CSS 重匹配
+              if (running === section.hasAttribute(FOLD_RUNNING_FLAG)) return
+              if (running) section.setAttribute(FOLD_RUNNING_FLAG, '')
+              else section.removeAttribute(FOLD_RUNNING_FLAG)
+            })
+          }
+          let scheduled = false
+          const schedule = () => {
+            if (disposed || scheduled) return
+            scheduled = true
+            timer = setTimeout(() => {
+              scheduled = false
+              timer = null
+              if (!disposed) scan()
+            }, FOLD_SCAN_DELAY_MS)
+          }
+          api('/api/turn-notify/config')
+            .then((payload) => {
+              foldEnabled = payload ? payload.folderRunningEnabled !== false : true
+            })
+            .catch(() => {
+              foldEnabled = true
+            })
+            .finally(schedule)
+          const unsubscribeSessions = sessions.list.subscribe(schedule)
+          const unsubscribeWorkspaces = workspaces.list.subscribe(schedule)
+          const observer = new MutationObserver(schedule)
+          observer.observe(document.documentElement, { childList: true, subtree: true })
+          schedule()
+          return () => {
+            disposed = true
+            if (timer !== null) clearTimeout(timer)
+            observer.disconnect()
+            unsubscribeSessions()
+            unsubscribeWorkspaces()
+            clearAll()
+          }
+        }, 'turn-notify folder running mark')
         ctx.slots.inject('settings.section', () =>
           ctx.slots.register(
             { name: 'settings.section', id: 'turn-notify', order: 41, label: '消息通知' },

package/src/core.mjs

@@ -641,7 +641,7 @@ export function imBoundBotIds(list) {
 // 返回归一化后的补丁。
 export function validateConfigPatch(patch) {
   if (patch === null || typeof patch !== 'object' || Array.isArray(patch)) return { ok: false, reason: '补丁须为对象' }
-  const known = ['webhookUrl', 'minTurnDurationMs', 'rootsOnly', 'suppressSubagentWake', 'enabled', 'imTargets', 'kindRoutes', 'hostNotify', 'hostNotifyFallback']
+  const known = ['webhookUrl', 'minTurnDurationMs', 'rootsOnly', 'suppressSubagentWake', 'enabled', 'imTargets', 'kindRoutes', 'hostNotify', 'hostNotifyFallback', 'folderRunningEnabled']
   for (const key of Object.keys(patch)) {
     if (known.indexOf(key) < 0) return { ok: false, reason: '未知配置项: ' + key }
   }
@@ -702,6 +702,10 @@ export function validateConfigPatch(patch) {
     if (typeof patch.hostNotifyFallback !== 'boolean') return { ok: false, reason: 'hostNotifyFallback 须为布尔' }
     next.hostNotifyFallback = patch.hostNotifyFallback
   }
+  if ('folderRunningEnabled' in patch) {
+    if (typeof patch.folderRunningEnabled !== 'boolean') return { ok: false, reason: 'folderRunningEnabled 须为布尔' }
+    next.folderRunningEnabled = patch.folderRunningEnabled
+  }
   if ('enabled' in patch) {
     const enabled = patch.enabled
     if (enabled === null || typeof enabled !== 'object' || Array.isArray(enabled)) return { ok: false, reason: 'enabled 须为对象' }
@@ -767,6 +771,7 @@ export function resolvedConfig(settings) {
     suppressSubagentWake: source.suppressSubagentWake !== false,
     hostNotify: source.hostNotify === true,
     hostNotifyFallback: source.hostNotifyFallback === true,
+    folderRunningEnabled: source.folderRunningEnabled !== false,
     enabled: Object.fromEntries(CATEGORIES.map((key) => [key, enabled[key] !== false])),
     soundMapping,
     imTargets: normalizeImTargets(source.imTargets),
@@ -783,6 +788,7 @@ export function publicConfig(settings) {
     suppressSubagentWake: resolved.suppressSubagentWake,
     hostNotify: resolved.hostNotify,
     hostNotifyFallback: resolved.hostNotifyFallback,
+    folderRunningEnabled: resolved.folderRunningEnabled,
     enabled: resolved.enabled,
     soundMapping: resolved.soundMapping,
     imTargets: resolved.imTargets,

package/src/index.js

@@ -94,6 +94,7 @@ const SETTINGS_SCHEMA = z.object({
   suppressSubagentWake: z.boolean().default(true).description('子代理相关回合不通知(仅任务完成类):后台委托未收尾的回合与收尾唤醒的回合'),
   hostNotify: z.boolean().default(false).description('宿主机桌面通知:通知触发时由宿主进程弹系统级通知(osascript/notify-send/PowerShell toast);浏览器优先,本机浏览器在场(2 秒内有在途长轮询)时由浏览器呈现宿主不重复弹,离场时宿主补位'),
   hostNotifyFallback: z.boolean().default(false).description('宿主通知回退:本机浏览器在场时由浏览器呈现,离场(2 秒内无在途长轮询)时宿主补位;与总开关判定一致,任一开启即生效'),
+  folderRunningEnabled: z.boolean().default(true).description('工作区文件夹运行标记:侧边栏分组模式下,有运行中会话的文件夹组头显示运行点并给图标着色;关闭后标记整体不渲染,变更刷新页面生效'),
   enabled: z.object(Object.fromEntries(CATEGORIES.map((key) => [key, z.boolean().default(true)]))).description('六类事件独立开关:完成/出错/被中断/等待审批/AI 提问/达到上限'),
   soundMapping: z.object(Object.fromEntries(CATEGORIES.map((key) => [key, z.string().default('')]))).description('每类事件的声音映射,空为内置默认,非空为内置音名或上传音效 id'),
   imTargets: z.array(z.object({ botId: z.string().default(''), targetId: z.string().default('') })).default([]).description('dsh-im 推送目标列表,空数组禁用 IM 通道'),

package/test/client-fold.test.mjs

@@ -0,0 +1,405 @@
+// 工作区文件夹运行标记:纯函数投影切片 + effect 扫描接线测试。
+// 扫描逻辑闭包在 apply 的 effect 内,经捕获 effect 函数 + DOM 桩驱动,
+// 锁定数量不变量守卫、下标对位、开关兜底与卸载清理。
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { mock } from 'node:test'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const CLIENT_SRC = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+
+// ── 纯函数切片:常量与 folderRunningState(无外部依赖) ──
+
+const PURE_START = CLIENT_SRC.indexOf('const FOLD_SECTION_SELECTOR')
+const PURE_END = CLIENT_SRC.indexOf('// ---- 点击直达会话')
+assert.ok(PURE_START >= 0 && PURE_END > PURE_START, 'client.js 文件夹运行标记纯函数切片定位失败')
+const pure = new Function(
+  CLIENT_SRC.slice(PURE_START, PURE_END)
+  + '; return { folderRunningState: folderRunningState, sectionSelector: FOLD_SECTION_SELECTOR, runningFlag: FOLD_RUNNING_FLAG, scanDelayMs: FOLD_SCAN_DELAY_MS }',
+)()
+
+const WS = (id, sessionIds) => ({ workspaceId: id, sessionIds })
+const ROW = (id, extra) => ({ id, ...extra })
+
+test('folderRunningState 主路径:运行中会话所在工作区入集合,非运行中不入', () => {
+  const sessions = {
+    ids: ['a', 'b'],
+    byId: { a: ROW('a', { running: true }), b: ROW('b', { running: false }) },
+  }
+  const workspaces = { items: [WS('w1', ['a']), WS('w2', ['b'])], archivedSessionIds: [] }
+  const state = pure.folderRunningState(sessions, workspaces)
+  assert.deepEqual(state.ids, ['w1', 'w2'])
+  assert.deepEqual([...state.running], ['w1'])
+  assert.equal(state.ungrouped, false)
+})
+
+test('folderRunningState 未分组:游离运行中会话使末位未分组桶标记', () => {
+  const sessions = {
+    ids: ['a', 'stray'],
+    byId: { a: ROW('a', { running: false }), stray: ROW('stray', { running: true }) },
+  }
+  const workspaces = { items: [WS('w1', ['a'])], archivedSessionIds: [] }
+  const state = pure.folderRunningState(sessions, workspaces)
+  assert.equal(state.running.has('w1'), false)
+  assert.equal(state.ungrouped, true)
+})
+
+test('folderRunningState 排除项:subagent、已归档、空白非当前不标记,空白当前例外', () => {
+  const sessions = {
+    ids: ['sub', 'arch', 'blank', 'cur'],
+    byId: {
+      sub: ROW('sub', { running: true, origin: 'subagent' }),
+      arch: ROW('arch', { running: true }),
+      blank: ROW('blank', { running: true, blank: true }),
+      cur: ROW('cur', { running: true, blank: true }),
+    },
+    current: 'cur',
+  }
+  const workspaces = {
+    items: [WS('w1', ['sub']), WS('w2', ['arch']), WS('w3', ['blank']), WS('w4', ['cur'])],
+    archivedSessionIds: ['arch'],
+  }
+  const state = pure.folderRunningState(sessions, workspaces)
+  assert.equal(state.running.has('w1'), false, 'subagent 运行不标记')
+  assert.equal(state.running.has('w2'), false, '已归档运行不标记')
+  assert.equal(state.running.has('w3'), false, '空白非当前运行不标记')
+  assert.equal(state.running.has('w4'), true, '空白且为当前会话标记')
+})
+
+test('folderRunningState 缺省守卫:快照缺失或账本悬空不抛错', () => {
+  assert.deepEqual(pure.folderRunningState(undefined, undefined), { ids: [], running: new Set(), ungrouped: false })
+  const state = pure.folderRunningState({ ids: ['gone'], byId: {} }, { items: [WS('w1', ['gone'])] })
+  assert.deepEqual([...state.running], [])
+  assert.equal(state.ungrouped, false)
+})
+
+// ── effect 扫描接线:DOM 桩 + 捕获 effect 函数驱动 ──
+
+const SCAN_SETTLE_MS = pure.scanDelayMs * 4
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+// 组容器桩:属性集合语义与 Element 同构
+function sectionStub() {
+  const attrs = new Set()
+  return {
+    attrs,
+    setAttribute: (name) => attrs.add(name),
+    removeAttribute: (name) => attrs.delete(name),
+    hasAttribute: (name) => attrs.has(name),
+  }
+}
+
+// 加载 client.js 并执行 apply(mock 最小服务面),effect 函数捕获不执行;
+// MutationObserver 经工厂形参注入(源码自由变量),document 桩承载组容器查询;
+// 通知长轮询经挂起 fetch 静默(测试只驱动 fold effect,不消费投影)
+function loadClient() {
+  const modules = []
+  const effects = []
+  const windowStub = {
+    __ModuleLoader__: { load: (module) => modules.push(module) },
+    addEventListener: () => {},
+    removeEventListener: () => {},
+  }
+  const reactStub = {
+    useState: (value) => [value, () => {}],
+    useEffect: () => {},
+    useSyncExternalStore: () => [],
+    useRef: (value) => ({ current: value }),
+    createElement: () => null,
+  }
+  const requireStub = (name) => {
+    if (name === '@mzzsfy/dsh-toast/client') return { show: () => 0 }
+    return reactStub
+  }
+  const sections = []
+  const documentStub = {
+    documentElement: {},
+    createElement: () => ({ style: {}, remove() {} }),
+    head: { appendChild: () => {} },
+    body: { appendChild: () => {} },
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    querySelectorAll: (selector) => {
+      if (selector === pure.sectionSelector) return [...sections]
+      if (selector === '[' + pure.runningFlag + ']') return sections.filter((section) => section.hasAttribute(pure.runningFlag))
+      return []
+    },
+  }
+  class MutationObserverStub {
+    observe() {}
+    disconnect() {}
+  }
+  // 不传 fetch 工厂参数:源码内裸 fetch 解析到 globalThis.fetch,由 withFetch 显式 mock;
+  // 传参数会把 fetch 绑定进沙箱,mock 永远打不到
+  const factory = new Function('window', 'require', 'document', 'MutationObserver', CLIENT_SRC + '\n;return null')
+  factory(windowStub, requireStub, documentStub, MutationObserverStub)
+  assert.equal(modules.length, 1, 'client.js 模块未被捕获')
+  const mod = modules[0].factory(requireStub)
+
+  // 快照源桩:监听器捕获 + emit,供测试模拟服务变更触发的重扫(生产由订阅驱动)
+  let sessionsState = { ids: [], byId: {} }
+  let workspacesState = undefined
+  function sourceStub(getSnapshot) {
+    const listeners = new Set()
+    return {
+      list: {
+        subscribe: (cb) => {
+          listeners.add(cb)
+          return () => listeners.delete(cb)
+        },
+        getSnapshot,
+      },
+      emit: () => {
+        for (const cb of [...listeners]) cb()
+      },
+    }
+  }
+  const sessions = { binding: () => undefined, ...sourceStub(() => sessionsState) }
+  const workspaces = sourceStub(() => workspacesState)
+  const ctx = {
+    get: (name) => (name === 'sessions' ? sessions : name === 'workspaces' ? workspaces : {}),
+    effect: (fn, tag) => effects.push({ fn, tag }),
+    slots: { inject: () => {}, register: () => {} },
+  }
+  mod.apply(ctx)
+  const entry = effects.find((item) => item.tag === 'turn-notify folder running mark')
+  assert.ok(entry, 'apply 未挂文件夹运行标记 effect')
+  return {
+    sections,
+    runEffect: entry.fn,
+    emitSessions: sessions.emit,
+    setSessions: (next) => { sessionsState = next },
+    setWorkspaces: (next) => { workspacesState = next },
+  }
+}
+
+// 两工作区一运行一的基准快照
+function baseSnapshots(client) {
+  client.setSessions({
+    ids: ['a', 'b'],
+    byId: { a: ROW('a', { running: true }), b: ROW('b', { running: false }) },
+  })
+  client.setWorkspaces({ items: [WS('w1', ['a']), WS('w2', ['b'])], archivedSessionIds: [] })
+}
+
+async function withFetch(implOrPayload, run) {
+  // mock.method 返回被 mock 的函数,还原须经 .mock.restore(),不可直接调用返回值;
+  // 传函数即显式 fetch 实现(构造拉取失败),传对象即固定响应,undefined 即固定
+  // 成功响应 {folderRunningEnabled:true}——默认路径显式 mock,不依赖运行环境对相对
+  // URL 的 fetch 行为(隐式环境耦合会随 Node 升级漂移);
+  // 通知长轮询路径恒返回挂起 Promise,测试期间不产生投影循环
+  const impl = typeof implOrPayload === 'function'
+    ? async (path) => (String(path).indexOf('/api/turn-notify/projection') === 0 ? new Promise(() => {}) : implOrPayload(path))
+    : async (path) => {
+      if (String(path).indexOf('/api/turn-notify/projection') === 0) return new Promise(() => {})
+      return { ok: true, json: async () => (implOrPayload === undefined ? { folderRunningEnabled: true } : implOrPayload) }
+    }
+  const mocked = mock.method(globalThis, 'fetch', impl)
+  try {
+    await run()
+  } finally {
+    mocked.mock.restore()
+  }
+}
+
+test('Given 两工作区组容器与快照同序, When 扫描, Then 运行中工作区组容器带标记', async () => {
+  await withFetch(undefined, async () => {
+    const client = loadClient()
+    baseSnapshots(client)
+    const [s1, s2] = [sectionStub(), sectionStub()]
+    client.sections.push(s1, s2)
+    client.runEffect()
+    await sleep(SCAN_SETTLE_MS)
+    assert.ok(s1.hasAttribute(pure.runningFlag), '运行中工作区组容器应带标记')
+    assert.equal(s2.hasAttribute(pure.runningFlag), false, '空闲工作区组容器不带标记')
+  })
+})
+
+test('Given 末位未分组桶存在, When 扫描, Then 组容器数 = 工作区数+1 且游离运行中落末位', async () => {
+  await withFetch(undefined, async () => {
+    const client = loadClient()
+    baseSnapshots(client)
+    client.setSessions({
+      ids: ['a', 'b', 'stray'],
+      byId: { a: ROW('a', { running: true }), b: ROW('b', { running: false }), stray: ROW('stray', { running: true }) },
+    })
+    const [s1, s2, s3] = [sectionStub(), sectionStub(), sectionStub()]
+    client.sections.push(s1, s2, s3)
+    client.runEffect()
+    await sleep(SCAN_SETTLE_MS)
+    assert.ok(s1.hasAttribute(pure.runningFlag), '首工作区(运行中)带标记')
+    assert.equal(s2.hasAttribute(pure.runningFlag), false, '次工作区(空闲)不带标记')
+    assert.ok(s3.hasAttribute(pure.runningFlag), '末位未分组桶(游离运行中)带标记')
+  })
+})
+
+test('Given 组容器数与不变量漂移(单列表/搜索态/结构变更), When 扫描, Then 清除全部标记不误标', async () => {
+  await withFetch(undefined, async () => {
+    const client = loadClient()
+    baseSnapshots(client)
+    const [s1, s2] = [sectionStub(), sectionStub()]
+    client.sections.push(s1, s2)
+    client.runEffect()
+    await sleep(SCAN_SETTLE_MS)
+    assert.ok(s1.hasAttribute(pure.runningFlag), '前置:正常对位时首组带标记')
+    // 漂移:两工作区只剩一个组容器(或多余两个)均不匹配不变量
+    client.sections.length = 0
+    client.sections.push(s1)
+    client.emitSessions()
+    await sleep(SCAN_SETTLE_MS)
+    assert.equal(s1.hasAttribute(pure.runningFlag), false, '数量漂移后标记被清除')
+  })
+})
+
+test('Given 开关关闭(拉取返回 folderRunningEnabled:false), When 扫描, Then 不标记且既有标记清除', async () => {
+  await withFetch({ folderRunningEnabled: false }, async () => {
+    const client = loadClient()
+    baseSnapshots(client)
+    const s1 = sectionStub()
+    client.sections.push(s1)
+    client.runEffect()
+    await sleep(SCAN_SETTLE_MS)
+    assert.equal(s1.hasAttribute(pure.runningFlag), false, '停用后不新增标记')
+  })
+})
+
+test('Given 开关拉取失败, When 扫描, Then 按启用兜底照常标记', async () => {
+  await withFetch(async (path) => {
+    if (String(path).indexOf('/api/turn-notify/projection') === 0) return new Promise(() => {})
+    throw new Error('network down')
+  }, async () => {
+    const client = loadClient()
+    baseSnapshots(client)
+    const [s1, s2] = [sectionStub(), sectionStub()]
+    client.sections.push(s1, s2)
+    client.runEffect()
+    await sleep(SCAN_SETTLE_MS)
+    assert.ok(s1.hasAttribute(pure.runningFlag), '拉取失败按启用兜底(默认启用)')
+    assert.equal(s2.hasAttribute(pure.runningFlag), false, '兜底不改变运行态判定')
+  })
+})
+
+test('Given 运行态变化经服务订阅到达(折叠组无 DOM 变更), When 快照更新, Then 标记跟随', async () => {
+  await withFetch(undefined, async () => {
+    const client = loadClient()
+    baseSnapshots(client)
+    const [s1, s2] = [sectionStub(), sectionStub()]
+    client.sections.push(s1, s2)
+    client.runEffect()
+    await sleep(SCAN_SETTLE_MS)
+    assert.ok(s1.hasAttribute(pure.runningFlag), '前置:首工作区运行中')
+    // 唯一运行会话转入另一工作区(模拟会话被归档/挂到他处后的快照差)
+    client.setSessions({
+      ids: ['a', 'b'],
+      byId: { a: ROW('a', { running: false }), b: ROW('b', { running: true }) },
+    })
+    client.emitSessions()
+    await sleep(SCAN_SETTLE_MS)
+    assert.equal(s1.hasAttribute(pure.runningFlag), false, '原运行工作区标记消除')
+    assert.ok(s2.hasAttribute(pure.runningFlag), '新运行工作区获得标记')
+  })
+})
+
+test('Given effect 卸载, When 清理执行, Then 标记移除且资源退订', async () => {
+  await withFetch(undefined, async () => {
+    const client = loadClient()
+    baseSnapshots(client)
+    const [s1, s2] = [sectionStub(), sectionStub()]
+    client.sections.push(s1, s2)
+    const cleanup = client.runEffect()
+    await sleep(SCAN_SETTLE_MS)
+    assert.ok(s1.hasAttribute(pure.runningFlag), '前置:标记已应用')
+    cleanup()
+    assert.equal(s1.hasAttribute(pure.runningFlag), false, '卸载清除运行中工作区的标记')
+    assert.equal(s2.hasAttribute(pure.runningFlag), false, '卸载不残留其他标记')
+  })
+})
+
+test('Given 无工作区且游离会话运行, When 扫描, Then 末位未分组桶正确标记', async () => {
+  await withFetch(undefined, async () => {
+    const client = loadClient()
+    client.setSessions({ ids: ['stray'], byId: { stray: ROW('stray', { running: true }) } })
+    client.setWorkspaces({ items: [], archivedSessionIds: [] })
+    const s1 = sectionStub()
+    client.sections.push(s1)
+    client.runEffect()
+    await sleep(SCAN_SETTLE_MS)
+    assert.ok(s1.hasAttribute(pure.runningFlag), '零工作区时组容器数 1 = 工作区数 0 + 1,末位按未分组桶标记')
+  })
+})
+
+test('Given 组容器数多于不变量上界, When 扫描, Then 清除全部标记不误标', async () => {
+  await withFetch(undefined, async () => {
+    const client = loadClient()
+    baseSnapshots(client)
+    // 数量漂移「变多」:两工作区出现四个组容器(> 工作区数+1)
+    const sections = [sectionStub(), sectionStub(), sectionStub(), sectionStub()]
+    client.sections.push(...sections)
+    client.runEffect()
+    await sleep(SCAN_SETTLE_MS)
+    for (const [index, section] of sections.entries()) {
+      assert.equal(section.hasAttribute(pure.runningFlag), false, '容器 ' + index + ' 数量漂移时不带标记')
+    }
+  })
+})
+
+test('Given 拉取未完成即卸载, When 后续拉取完成并触发调度, Then 标记不复活', async () => {
+  // 拉取挂起(永不resolve),标记先经拉取完成前的唯一路径产生:
+  // 未决期 scan 仅清除,故先注入「已启用 + 已标记」状态再卸载
+  let release
+  await withFetch((path) => {
+    if (String(path).indexOf('/api/turn-notify/projection') === 0) return new Promise(() => {})
+    return new Promise((resolve) => { release = resolve })
+  }, async () => {
+    const client = loadClient()
+    baseSnapshots(client)
+    const s1 = sectionStub()
+    client.sections.push(s1)
+    const cleanup = client.runEffect()
+    await sleep(SCAN_SETTLE_MS)
+    assert.equal(s1.hasAttribute(pure.runningFlag), false, '拉取未决期间不产生标记')
+    // 模拟标记已在(如卸载前最后一次 scan 的残留):卸载后拉取完成不得复活
+    s1.setAttribute(pure.runningFlag, '')
+    cleanup()
+    release({ ok: true, json: async () => ({ folderRunningEnabled: true }) })
+    await sleep(SCAN_SETTLE_MS)
+    assert.equal(s1.hasAttribute(pure.runningFlag), false, '卸载后拉取完成不复活标记')
+  })
+})
+
+test('Given 开关停用, When 拉取完成前的首次扫描, Then 不产生标记(未决期仅清除)', async () => {
+  // 拉取延迟释放(3 个扫描窗口后返回停用),未决期内的扫描不得标记
+  await withFetch((path) => new Promise((resolve) => {
+    if (String(path).indexOf('/api/turn-notify/projection') === 0) return
+    setTimeout(() => resolve({ ok: true, json: async () => ({ folderRunningEnabled: false }) }), pure.scanDelayMs * 3)
+  }), async () => {
+    const client = loadClient()
+    baseSnapshots(client)
+    const s1 = sectionStub()
+    client.sections.push(s1)
+    client.runEffect()
+    await sleep(SCAN_SETTLE_MS)
+    assert.equal(s1.hasAttribute(pure.runningFlag), false, '拉取未决期首次扫描不标记')
+    await sleep(SCAN_SETTLE_MS * 2)
+    assert.equal(s1.hasAttribute(pure.runningFlag), false, '拉取返回停用后维持无标记')
+  })
+})
+
+// ── 源码契约:CSS 规则、面板开关挂载、选择器与标记属性 ──
+
+test('源码契约:运行点与图标着色规则、官方组容器锚点、面板开关挂载齐备', () => {
+  assert.ok(CLIENT_SRC.includes('div[class$="_groupSection"][data-tn-folder-running]'), '缺组容器标记 CSS 锚点')
+  assert.ok(CLIENT_SRC.includes('var(--dsw-static-deepseek-450)'), '运行点色源应为官方 ongoing 实际色值(--dsh-state-ongoing 仅存在于官方状态点组件局部,组容器读不到)')
+  assert.ok(!CLIENT_SRC.includes('--tn-fold-running-color: var(--dsh-state-ongoing'), '死变量引用:组容器上下文读不到 --dsh-state-ongoing,恒走回退源,不得引入永不生效的引用')
+  assert.ok(CLIENT_SRC.includes('[class$="_folderActive"]'), '图标着色应让位官方 folderActive 态')
+  assert.ok(CLIENT_SRC.includes('tn-fold-running-pulse'), '缺运行点脉冲动画')
+  assert.ok(CLIENT_SRC.includes('prefers-reduced-motion'), '动画应尊重减少动态偏好')
+  assert.ok(CLIENT_SRC.includes('toggleFolderRunning'), '面板缺运行标记开关处理函数')
+  assert.ok(CLIENT_SRC.includes('title: FOLD_SWITCH_TITLE'), '开关行缺悬停说明挂载')
+  assert.ok(CLIENT_SRC.includes('const FOLD_SWITCH_TITLE'), '缺悬停说明常量')
+  // 开关经既有 config 路由读写:不新增路由,host 与 client 字面量一致
+  assert.ok(!CLIENT_SRC.includes("'/api/turn-notify/folder-running"), '运行标记开关不得另开路由(经 config 路由读写)')
+})

package/test/core.test.mjs

@@ -661,6 +661,7 @@ test('配置解析:enabled 缺省键按开补全,字段类型回退默认', () =
       suppressSubagentWake: true,
       hostNotify: false,
       hostNotifyFallback: false,
+      folderRunningEnabled: true,
       enabled: { completed: false, error: true, interrupted: true, approval: true, ask: true, 'max-tokens': true },
       soundMapping: { completed: 'snd-1' },
       imTargets: [],
@@ -674,6 +675,7 @@ test('配置解析:enabled 缺省键按开补全,字段类型回退默认', () =
     suppressSubagentWake: true,
     hostNotify: false,
     hostNotifyFallback: false,
+    folderRunningEnabled: true,
     enabled: Object.fromEntries(CATEGORIES.map((name) => [name, true])),
     soundMapping: {},
     imTargets: [],
@@ -692,6 +694,7 @@ test('面板可见配置:webhookUrl 原文回显', () => {
       suppressSubagentWake: true,
       hostNotify: false,
       hostNotifyFallback: false,
+      folderRunningEnabled: true,
       enabled: { completed: false, error: true, interrupted: true, approval: true, ask: true, 'max-tokens': true },
       soundMapping: { completed: 'snd-1' },
       imTargets: [],

package/test/flow.test.mjs

@@ -45,14 +45,15 @@ function loadClient({ storage, payload, onFetch, fetchImpl, document: documentOv
     listeners: windowListeners,
     localStorage: storage,
   }
+  const styleTags = []
   const documentStub = {
     hasFocus: () => true,
     // 默认桩:聚焦窗口恒可见(浏览器不变式);聚焦静默判定为可见+焦点双条件
     hidden: false,
     title: 'dsh',
-    createElement: () => ({ style: {}, remove() {} }),
+    createElement: () => ({ style: {}, attrs: {}, setAttribute(name, value) { this.attrs[name] = value }, remove() {} }),
     body: { appendChild: () => {} },
-    head: { appendChild: () => {} },
+    head: { appendChild: (node) => { styleTags.push(node) } },
     ...documentOverride,
   }
   const reactStub = { useState: (value) => [value, () => {}], useEffect: () => {}, useSyncExternalStore: () => [] }
@@ -85,7 +86,7 @@ function loadClient({ storage, payload, onFetch, fetchImpl, document: documentOv
   )
   assert.equal(modules.length, 1, 'client.js 模块未被捕获')
   // load({id, factory}) 结构:再调 factory(require) 得到真正的模块对象
-  return { mod: modules[0].factory(requireStub), shown, window: windowStub, document: documentStub }
+  return { mod: modules[0].factory(requireStub), shown, window: windowStub, document: documentStub, styleTags }
 }
 
 const units = [
@@ -718,18 +719,23 @@ test('Given 页内映射存储损坏或死链 When 解析 Then 容错回落且
 
 test('激活即启动轮询:apply 注册设置分区且 start 已执行', async () => {
   const fetched = []
-  const { mod } = loadClient({
+  const { mod, styleTags } = loadClient({
     storage: new FakeStorage(),
     payload: { units: [], soundMapping: {}, version: 1 },
     onFetch: (path) => { fetched.push(path) },
   })
   const injected = []
   const effects = []
+  // sessions/workspaces 服务桩:文件夹运行标记的注入面(订阅桩不做任何事;
+  // 本测试 document 桩无 querySelectorAll,fold effect 装配即干净退出)
+  const serviceStub = { list: { subscribe: () => () => {}, getSnapshot: () => ({}) } }
   mod.apply({
+    get: (name) => (name === 'sessions' || name === 'workspaces' ? serviceStub : undefined),
     slots: { inject: (name, fn) => { injected.push([name, fn]) } },
     effect: (fn) => { effects.push(fn()) },
   })
-  assert.equal(effects.length, 1, '文档级样式未挂载')
+  assert.equal(effects.length, 2, '文档级样式与文件夹运行标记两个 effect 均已挂载')
+  assert.equal(styleTags[0].attrs['data-plugin'], '@mzzsfy/dsh-turn-notify', '样式自带 data-plugin,防宿主 claimStyles 误归属后随他插件 HMR 整批误删')
   assert.deepEqual(injected.map(([name]) => name), ['settings.section'], '页内通知展示已移交 dsh-toast,不再注入 shell.overlay')
   // start 已执行:音效清单被首拉;轮询定时器 unref,不阻止测试进程退出
   await new Promise((resolve) => { setTimeout(resolve, 0) })
@@ -799,7 +805,11 @@ test('分类通知开关提交失败:报错并以权威配置纠偏', async () =
 })
 
 function activate(mod) {
+  // sessions/workspaces 桩:apply 的注入面声明;fold effect 在无 querySelectorAll
+  // 的 document 桩上装配即退出,不触碰订阅
+  const serviceStub = { list: { subscribe: () => () => {}, getSnapshot: () => ({}) } }
   mod.apply({
+    get: (name) => (name === 'sessions' || name === 'workspaces' ? serviceStub : undefined),
     slots: { inject: () => {} },
     effect: (fn) => { fn() },
   })