@mzzsfy/dsh-turn-notify 0.9.0 → 0.11.0

package/src/index.js

@@ -2,6 +2,7 @@
 // 命中分类即发 webhook、写入内存投影;webServer 路由供浏览器半区轮询投影与管理音效。
 // 音效持久化在 ~/.dsh/dsh-turn-notify/sounds/,投影不落盘。
 
+import { execFile } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { mkdir, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
@@ -25,6 +26,9 @@ import {
   isSubagent,
   isSubagentWakeTurn,
   isValidImBotId,
+  hostNotifyWanted,
+  isLocalBrowserPoll,
+  isLocalBrowserPresent,
   mapEventToCategory,
   mimeOf,
   normalizeImTargets,
@@ -32,6 +36,7 @@ import {
   readRawBody,
   resolvedConfig,
   sendWebhook,
+  sendHostNotify,
   shouldNotify,
   storedSessionTitle,
   unitRoutes,
@@ -49,11 +54,17 @@ export const name = 'dsh-turn-notify'
 
 export const inject = ['webServer']
 
+// spawn 实现缝:测试注入观测 stub,生产恒为 child_process.execFile(client 半区 __test 同先例)
+export const __hostSpawn = { impl: execFile }
+
 const NAMESPACE = 'turn-notify'
 const SOUNDS_DIR = join(homedir(), '.dsh', 'dsh-turn-notify', 'sounds')
 const REQUEST_BODY_MAX_BYTES = 64 * 1024
 // 长轮询挂起上限:低于客户端请求超时,保证客户端总在服务端放弃后才超时
 const LONG_POLL_WAIT_MS = 25 * 1000
+// 本机浏览器在场认可窗口:在途长轮询出账后的宽限时长,浏览器优先去重的时间边界;
+// 窗口内事件仍视为浏览器呈现,超窗即宿主补位(宁可重复不可漏)
+export const CLIENT_PRESENCE_WINDOW_MS = 2 * 1000
 
 // dsh-im 投递错误码到 HTTP 状态的映射,未收录错误按网关失败处理
 const IM_ERROR_STATUS = { 'bad-request': 400, 'unknown-bot': 404, 'bot-not-connected': 503 }
@@ -81,10 +92,13 @@ const SETTINGS_SCHEMA = z.object({
   minTurnDurationMs: z.number().default(MIN_TURN_DURATION_MS).description('最短回合时长(毫秒),回合结束类通知短于此不送达;AI 提问与审批请求即时送达'),
   rootsOnly: z.boolean().default(true).description('子代理会话不通知'),
   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 通道'),
-  kindRoutes: z.dict(z.array(z.string())).default({}).description('事件→通道路由:分类到放行通道名单(sound/system/toast/blink/webhook/im),未配置的分类全通道放行'),
+  kindRoutes: z.dict(z.array(z.string())).default({}).description('事件→通道路由:分类到放行通道名单(sound/system/toast/blink/webhook/im/host),未配置的分类全通道放行'),
 })
 
 // 读侧归一交由 core 的 resolvedConfig:字段类型异常回退默认值,与写路径校验宽松度一致
@@ -194,6 +208,10 @@ export function apply(ctx) {
   const titledSessions = new Set()
   // 回合尾部统计:assistant/message 的 tokens 累加与回答前缀,回合结束随通知消费即清
   const assistantTails = new Map()
+  // 本机(回环来源)浏览器在场信号:在途长轮询计数与最近活动时刻,
+  // 在场 = 有在途请求或认可窗口内有活动,宿主通知的浏览器优先去重据此判定
+  let inFlightLocalPolls = 0
+  let lastLocalClientSeenAt = 0
   let seq = 0
   // 音效库写互斥:展示名索引读改写与落盘非原子,串行化防并发交错
   let soundWriteQueue = Promise.resolve()
@@ -253,6 +271,25 @@ export function apply(ctx) {
       void sendWebhook({ url: settings.webhookUrl, payload: buildWebhookPayload(unit) })
     }
     if (routes === null || routes.indexOf('im') >= 0) deliverIm(unit, settings)
+    if (routes === null || routes.indexOf('host') >= 0) deliverHostNotify(unit, settings)
+  }
+
+  // 宿主桌面通知:浏览器优先,本机浏览器在场由浏览器呈现,宿主让位(正常路径
+  // 零重复);离场(无在途长轮询且超认可窗口)由宿主补位;fire-and-forget,
+  // spawn 失败不影响其余通道
+  function deliverHostNotify(unit, settings) {
+    const wanted = hostNotifyWanted({
+      hostNotify: settings.hostNotify,
+      hostNotifyFallback: settings.hostNotifyFallback,
+      localBrowserPresent: isLocalBrowserPresent({
+        inFlightPolls: inFlightLocalPolls,
+        lastSeenAt: lastLocalClientSeenAt,
+        now: Date.now(),
+        windowMs: CLIENT_PRESENCE_WINDOW_MS,
+      }),
+    })
+    if (!wanted) return
+    void sendHostNotify({ title: unit.text, body: unit.summary ?? '', platform: process.platform, execFileImpl: __hostSpawn.impl })
   }
 
   // 会话显示标题:优先 session-title 服务(与侧边栏行标题同一投影,客户端文本匹配高亮
@@ -404,13 +441,39 @@ export function apply(ctx) {
       path: '/api/turn-notify/projection',
       handler: route('GET', {}, async (req, res) => {
         const query = new URL(req.url, 'http://localhost').searchParams
-        const rawCursor = Number(query.get('cursor'))
-        const cursor = Number.isFinite(rawCursor) ? rawCursor : 0
-        if (query.has('cursor') && projection.version() === cursor) {
-          await projection.wait(cursor, LONG_POLL_WAIT_MS)
+        // 回环来源的浏览器长轮询即本机在场信号,宿主通知的浏览器优先去重据此判定;
+        // 记账形态收紧防伪造:裸 GET(img 探活/监控探测)与跨源 fetch 不入账。
+        // 记账期间计入在途,断连(浏览器关闭/中止)经 res close 事件即时出账,
+        // 离场盲区收敛到认可窗口
+        let releaseLocalPoll = null
+        if (isLocalBrowserPoll({
+          remoteAddress: req.socket && req.socket.remoteAddress,
+          hasCursor: query.has('cursor'),
+          secFetchMode: req.headers ? req.headers['sec-fetch-mode'] : undefined,
+          origin: req.headers ? req.headers.origin : undefined,
+          host: req.headers ? req.headers.host : undefined,
+        })) {
+          inFlightLocalPolls += 1
+          let settled = false
+          releaseLocalPoll = () => {
+            if (settled) return
+            settled = true
+            inFlightLocalPolls -= 1
+            lastLocalClientSeenAt = Date.now()
+          }
+          res.once('close', releaseLocalPoll)
+        }
+        try {
+          const rawCursor = Number(query.get('cursor'))
+          const cursor = Number.isFinite(rawCursor) ? rawCursor : 0
+          if (query.has('cursor') && projection.version() === cursor) {
+            await projection.wait(cursor, LONG_POLL_WAIT_MS)
+          }
+          const settings = readSettings(ctx)
+          sendJson(res, 200, { units: projection.list(), soundMapping: settings.soundMapping, version: projection.version() })
+        } finally {
+          if (releaseLocalPoll !== null) releaseLocalPoll()
         }
-        const settings = readSettings(ctx)
-        sendJson(res, 200, { units: projection.list(), soundMapping: settings.soundMapping, version: projection.version() })
       }),
     })
     return () => projection.dispose()
@@ -631,6 +694,29 @@ export function apply(ctx) {
       }),
     }), 'turn-notify test-webhook route')
 
+  // 宿主通知测试点火互斥:spawn 代价高于既有端点(powershell/osascript 秒级),
+  // 单在途防连点堆积
+  let hostTestInFlight = false
+  ctx.effect(() =>
+    ctx.webServer.register({
+      kind: 'exact',
+      path: '/api/turn-notify/test-host',
+      // 等待 spawn 结束,真实结果随响应返回,测试按钮不谎报
+      handler: route('POST', { crossOrigin: true }, async (req, res) => {
+        if (hostTestInFlight) {
+          sendJson(res, 429, { error: '宿主通知测试进行中,请稍候' })
+          return
+        }
+        hostTestInFlight = true
+        try {
+          const unit = buildTestUnit()
+          sendJson(res, 200, await sendHostNotify({ title: unit.text, body: unit.summary ?? '', platform: process.platform, execFileImpl: __hostSpawn.impl }))
+        } finally {
+          hostTestInFlight = false
+        }
+      }),
+    }), 'turn-notify test-host route')
+
   ctx.effect(() =>
     ctx.webServer.register({
       kind: 'exact',

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

@@ -659,6 +659,9 @@ test('配置解析:enabled 缺省键按开补全,字段类型回退默认', () =
       minTurnDurationMs: MIN_TURN_MS,
       rootsOnly: true,
       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: [],
@@ -670,6 +673,9 @@ test('配置解析:enabled 缺省键按开补全,字段类型回退默认', () =
     minTurnDurationMs: MIN_TURN_MS,
     rootsOnly: true,
     suppressSubagentWake: true,
+    hostNotify: false,
+    hostNotifyFallback: false,
+    folderRunningEnabled: true,
     enabled: Object.fromEntries(CATEGORIES.map((name) => [name, true])),
     soundMapping: {},
     imTargets: [],
@@ -686,6 +692,9 @@ test('面板可见配置:webhookUrl 原文回显', () => {
       minTurnDurationMs: MIN_TURN_MS,
       rootsOnly: true,
       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/event-wiring.test.mjs

@@ -6,13 +6,14 @@ import { EventEmitter } from 'node:events'
 
 import { apply } from '../src/index.js'
 
+// res 桩带事件能力:投影处理器挂 close 事件感知断连,桩须支持 once
 function makeRes() {
-  return {
-    status: null,
-    body: null,
-    writeHead(status) { this.status = status },
-    end(body) { this.body = JSON.parse(body) },
-  }
+  const res = new EventEmitter()
+  res.status = null
+  res.body = null
+  res.writeHead = (status) => { res.status = status }
+  res.end = (body) => { res.body = JSON.parse(body) }
+  return res
 }
 
 function makeReq(method, payload, headers) {