dsh-my-observability 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 本文件记录 dsh-my-observability 的所有版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.1.6] - 2026-09-04
+
+### 变更
+
+- fix(observability): 轨迹回放会话下拉可读标题（首条用户消息）——此前只展示 UUID 清单
+
+## [0.1.5] - 2026-09-04
+
+### 变更
+
+- feat(observability): #127 资源看门狗自动降级——写入速率/文件大小连续 ≥3 次采样超限自动暂停落盘（事件仍入内存，FIFO 有界不丢）+ 日志告警；连续 ≥3 次正常自动恢复（全量快照补齐降级窗口）；API 暴露 degraded 标记（#136）
+- 发版前功能级验证清单（issue #67）：verification/dsh-my-observability-0.1.5.md
+
 ## [0.1.4] - 2026-09-03
 
 ### 变更

package/README.md

@@ -26,7 +26,7 @@ Server 端只读观察 DSH 生命周期事件并记录审计日志：
 - **重启恢复**：持久化到 `$DSH_HOME/observability/audit.jsonl`（**增量追加** + 防抖批量 flush + 周期 compact 原子快照），重启后完整恢复；升级前旧格式 `audit.json` 自动迁移；
 - **防膨胀**：每会话最多 2000 条（FIFO 淘汰）、全局 20000 条（轮转淘汰）；
 - **零写放大**：落盘只写新增事件（≈事件本体字节），不会因事件流持续而反复全量重写审计文件；
-- **资源监控**：面板「资源」区块展示本进程 CPU/内存 + 审计文件大小与写入速率（15s 采样），写放大/超限自动告警（阈值见 `resource-budget-review`）；
+- **资源监控 + 自动降级（资源看门狗）**：面板「资源」区块展示本进程 CPU/内存 + 审计文件大小与写入速率（15s 采样），写放大/超限自动告警（告警列表展示在「资源」区块，阈值见 `resource-budget-review`）；写入速率/文件大小连续超限自动**暂停落盘**（事件仍入内存，有界不丢），回落自动恢复（全量快照补齐降级窗口），全程日志告警 + API `degraded` 标记（issue #127）。
 - **只读观察**：waterfall 事件一律透传 `next()`，绝不改变工具/模型流程。
 
 ### 2. 轨迹回放面板（时间轴）

package/lib/audit.js

@@ -17,6 +17,7 @@ import { MAX_ARG_KEYS, MAX_TEXT_LEN } from './constants.js'
 /** 注册全部审计监听；返回 disposer 数组（全部经 ctx.on 注册）。 */
 export function attachAuditListeners(ctx, record) {
   return [
+    ctx.on('session/event', (session, event) => handleSessionEvent(session, event, record)),
     ctx.on('agent/status', (payload) => handleStatus(payload, record)),
     ctx.on('llm/stream', (options, next) => handleStream(options, next, record)),
     ctx.on('tools/pre-execute', (exec, next) => handlePreExecute(exec, next, record)),
@@ -24,6 +25,43 @@ export function attachAuditListeners(ctx, record) {
   ]
 }
 
+/**
+ * session/event → user_message 事件（会话标题来源）。
+ * 轨迹回放面板需要"对话可读标题"而非 UUID：从每个会话真实用户的首条
+ * 消息截断生成（跳过插件注入消息），面板 sessionsOf 取最早一条作为
+ * title。不作为独立存储字段，走现有事件通路，重启后自然恢复。
+ */
+function handleSessionEvent(session, event, record) {
+  if (event === null || typeof event !== 'object' || event.type !== 'user/message') return
+  const message = event.data
+  if (isPluginMessage(message)) return
+  const sessionId = session?.id
+  if (typeof sessionId !== 'string' || sessionId === '') return
+  const text = userTextOf(message)
+  if (text === '') return
+  record({ type: 'user_message', sessionId, data: { text: truncate(text) } })
+}
+
+/** 是否为插件注入的消息（非真实用户输入，不作为标题）。 */
+function isPluginMessage(message) {
+  const source = message?.source
+  return source !== null && typeof source === 'object' && source.kind === 'plugin'
+}
+
+/** 从 user message 提取文本（content 中全部 text block 拼接）。 */
+function userTextOf(message) {
+  if (message === null || typeof message !== 'object') return ''
+  const content = message.content
+  if (!Array.isArray(content)) return ''
+  const parts = []
+  for (const block of content) {
+    if (block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string') {
+      parts.push(block.text)
+    }
+  }
+  return parts.join(' ').trim()
+}
+
 /** agent/status → agent_status 事件（含顶层/子代理标记）。 */
 function handleStatus(payload, record) {
   const agent = payload?.agent

package/lib/client.js

@@ -50,6 +50,9 @@ const strings = {
   resourceMem: () => (isZh() ? '内存' : 'Memory'),
   gitTitle: () => (isZh() ? 'Git 工具' : 'Git Tools'),
   allSessions: () => (isZh() ? '全部会话' : 'All sessions'),
+  // ── 会话下拉可读性（issue #1xx：只能看到 UUID）────────────────────────
+  eventCount: (n) => (isZh() ? `${n} 事件` : `${n} events`),
+  sessionFallback: (shortId) => (isZh() ? `会话 ${shortId}` : `session ${shortId}`),
   filterAll: () => (isZh() ? '全部' : 'All'),
   filterStatus: () => (isZh() ? '状态' : 'Status'),
   filterLlm: () => (isZh() ? '模型流' : 'LLM'),
@@ -907,6 +910,18 @@ async function loadReplayData(selected, currentSession, setters) {
   }
 }
 
+/** 下拉选项文案：可读标题（首条用户消息）优先，无标题回退 UUID 短显；
+ *  附加事件数与时间，用户一眼看出"哪个对话"。 */
+function sessionOptionLabel(s) {
+  const title = typeof s.title === 'string' && s.title !== '' ? s.title : strings.sessionFallback(shortId(s.sessionId))
+  return `${title} · ${strings.eventCount(s.count)}`
+}
+
+/** 会话 id 短显示（UUID 取前 8 位）。 */
+function shortId(sessionId) {
+  return typeof sessionId === 'string' && sessionId.length > 8 ? `${sessionId.slice(0, 8)}…` : sessionId || ''
+}
+
 /** 工具栏：会话选择 + 手动刷新 + 类型过滤。 */
 function ReplayToolbar({ sessions, selected, onSelect, filter, onFilter, onRefresh }) {
   return createElement(
@@ -925,7 +940,9 @@ function ReplayToolbar({ sessions, selected, onSelect, filter, onFilter, onRefre
         },
         sessions.length === 0
           ? createElement('option', { value: '' }, strings.allSessions())
-          : sessions.map((s) => createElement('option', { key: s.sessionId, value: s.sessionId }, s.sessionId)),
+          : sessions.map((s) =>
+              createElement('option', { key: s.sessionId, value: s.sessionId }, sessionOptionLabel(s)),
+            ),
       ),
       createElement(
         'button',
@@ -1050,7 +1067,10 @@ function useResourceState(visible) {
     if (!visible) return undefined
     let alive = true
     const tick = () => {
-      if (alive) apiJson('/observability/api/resources').then(setResource).catch(() => {})
+      if (alive)
+        apiJson('/observability/api/resources')
+          .then(setResource)
+          .catch(() => {})
     }
     tick()
     const timer = setInterval(tick, RESOURCE_POLL_MS)
@@ -1085,8 +1105,14 @@ function ResourcePanel({ resource }) {
       'div',
       { className: 'dsh-my-observability-resource-grid' },
       createElement(ResourceMetric, { label: strings.resourceFile(), value: fmtResourceBytes(resource.fileBytes) }),
-      createElement(ResourceMetric, { label: strings.resourceRate(), value: `${fmtResourceBytes(resource.writeRateBytesPerHour)}/h` }),
-      createElement(ResourceMetric, { label: strings.resourceCpu(), value: `${Math.round(resource.cpuPercent ?? 0)}%` }),
+      createElement(ResourceMetric, {
+        label: strings.resourceRate(),
+        value: `${fmtResourceBytes(resource.writeRateBytesPerHour)}/h`,
+      }),
+      createElement(ResourceMetric, {
+        label: strings.resourceCpu(),
+        value: `${Math.round(resource.cpuPercent ?? 0)}%`,
+      }),
       createElement(ResourceMetric, { label: strings.resourceMem(), value: fmtResourceBytes(resource.memoryBytes) }),
     ),
     alerts.length > 0
@@ -1386,7 +1412,10 @@ function useReplayDataState(props) {
     if (!visible) return undefined
     let alive = true
     const tick = () => {
-      if (alive) apiJson('/observability/api/resources').then(setResource).catch(() => {})
+      if (alive)
+        apiJson('/observability/api/resources')
+          .then(setResource)
+          .catch(() => {})
     }
     tick()
     const timer = setInterval(tick, RESOURCE_POLL_MS)

package/lib/index.js

@@ -41,10 +41,21 @@ export function apply(ctx, config) {
   // ── 事件监听（只读观察；waterfall 一律透传 next()）──────────────────
   attachAuditListeners(ctx, store.record)
 
-  // ── 资源监控（15s 采样 CPU/内存/审计写入速率，阈值告警）─────────────
+  // ── 资源监控 + 降级看门狗（15s 采样 CPU/内存/审计写入速率；写放大/文件
+  //    超限连续触发时自动降级停落盘，资源回归后自动恢复——issue #127）────
   const monitor = createResourceMonitor(ctx, {
     intervalMs: config?.resourceIntervalMs,
     limits: config?.resourceLimits,
+    onDegrade: () => {
+      store.setPersistEnabled(false)
+      ctx.logger.warn(
+        '[dsh-my-observability] 资源看门狗：审计写入速率/文件大小连续超限，已暂停落盘（事件仍在内存，恢复后全量快照补齐）',
+      )
+    },
+    onRecover: () => {
+      store.setPersistEnabled(true)
+      ctx.logger.warn('[dsh-my-observability] 资源看门狗：写入速率回归正常，已恢复审计落盘')
+    },
   })
   monitor.start()
 

package/lib/parts/i18n.js

@@ -18,6 +18,9 @@ const strings = {
   resourceMem: () => (isZh() ? '内存' : 'Memory'),
   gitTitle: () => (isZh() ? 'Git 工具' : 'Git Tools'),
   allSessions: () => (isZh() ? '全部会话' : 'All sessions'),
+  // ── 会话下拉可读性（issue #1xx：只能看到 UUID）────────────────────────
+  eventCount: (n) => (isZh() ? `${n} 事件` : `${n} events`),
+  sessionFallback: (shortId) => (isZh() ? `会话 ${shortId}` : `session ${shortId}`),
   filterAll: () => (isZh() ? '全部' : 'All'),
   filterStatus: () => (isZh() ? '状态' : 'Status'),
   filterLlm: () => (isZh() ? '模型流' : 'LLM'),

package/lib/parts/replay-ext.js

@@ -279,7 +279,10 @@ function useReplayDataState(props) {
     if (!visible) return undefined
     let alive = true
     const tick = () => {
-      if (alive) apiJson('/observability/api/resources').then(setResource).catch(() => {})
+      if (alive)
+        apiJson('/observability/api/resources')
+          .then(setResource)
+          .catch(() => {})
     }
     tick()
     const timer = setInterval(tick, RESOURCE_POLL_MS)

package/lib/parts/replay.js

@@ -194,6 +194,18 @@ async function loadReplayData(selected, currentSession, setters) {
   }
 }
 
+/** 下拉选项文案：可读标题（首条用户消息）优先，无标题回退 UUID 短显；
+ *  附加事件数与时间，用户一眼看出"哪个对话"。 */
+function sessionOptionLabel(s) {
+  const title = typeof s.title === 'string' && s.title !== '' ? s.title : strings.sessionFallback(shortId(s.sessionId))
+  return `${title} · ${strings.eventCount(s.count)}`
+}
+
+/** 会话 id 短显示（UUID 取前 8 位）。 */
+function shortId(sessionId) {
+  return typeof sessionId === 'string' && sessionId.length > 8 ? `${sessionId.slice(0, 8)}…` : sessionId || ''
+}
+
 /** 工具栏：会话选择 + 手动刷新 + 类型过滤。 */
 function ReplayToolbar({ sessions, selected, onSelect, filter, onFilter, onRefresh }) {
   return createElement(
@@ -212,7 +224,9 @@ function ReplayToolbar({ sessions, selected, onSelect, filter, onFilter, onRefre
         },
         sessions.length === 0
           ? createElement('option', { value: '' }, strings.allSessions())
-          : sessions.map((s) => createElement('option', { key: s.sessionId, value: s.sessionId }, s.sessionId)),
+          : sessions.map((s) =>
+              createElement('option', { key: s.sessionId, value: s.sessionId }, sessionOptionLabel(s)),
+            ),
       ),
       createElement(
         'button',

package/lib/parts/resource.js

@@ -15,7 +15,10 @@ function useResourceState(visible) {
     if (!visible) return undefined
     let alive = true
     const tick = () => {
-      if (alive) apiJson('/observability/api/resources').then(setResource).catch(() => {})
+      if (alive)
+        apiJson('/observability/api/resources')
+          .then(setResource)
+          .catch(() => {})
     }
     tick()
     const timer = setInterval(tick, RESOURCE_POLL_MS)
@@ -50,8 +53,14 @@ function ResourcePanel({ resource }) {
       'div',
       { className: 'dsh-my-observability-resource-grid' },
       createElement(ResourceMetric, { label: strings.resourceFile(), value: fmtResourceBytes(resource.fileBytes) }),
-      createElement(ResourceMetric, { label: strings.resourceRate(), value: `${fmtResourceBytes(resource.writeRateBytesPerHour)}/h` }),
-      createElement(ResourceMetric, { label: strings.resourceCpu(), value: `${Math.round(resource.cpuPercent ?? 0)}%` }),
+      createElement(ResourceMetric, {
+        label: strings.resourceRate(),
+        value: `${fmtResourceBytes(resource.writeRateBytesPerHour)}/h`,
+      }),
+      createElement(ResourceMetric, {
+        label: strings.resourceCpu(),
+        value: `${Math.round(resource.cpuPercent ?? 0)}%`,
+      }),
       createElement(ResourceMetric, { label: strings.resourceMem(), value: fmtResourceBytes(resource.memoryBytes) }),
     ),
     alerts.length > 0

package/lib/resource-monitor.js

@@ -1,42 +1,52 @@
 /**
- * dsh-my-observability — 资源采样监控。
+ * dsh-my-observability — 资源采样监控 + 降级看门狗。
  *
  * 每 intervalMs（默认 15s）采样本进程 CPU/内存与审计文件大小/写入速率，
  * 保留最近 MAX_HISTORY 个样本（ring buffer），并做阈值评估（resource-rules）。
  * 用途：让「写放大/资源超限」在运行期当小时可见（9/2 事故复盘结论：
  * 15 小时 300GB 写入零监控是事故未被及时发现的主因）。
  *
+ * 降级看门狗（issue #127 资源占用防护）：关键阈值（写放大/文件字节）连续
+ * DEGRADE_CONFIRM_COUNT 次超限 → 触发 onDegrade 回调（宿主降级：停落盘等）；
+ * 连续 RECOVER_CONFIRM_COUNT 次正常 → 触发 onRecover 回调（宿主恢复 + 全量快照）。
+ * 判定为纯函数（resource-rules.shouldEnterDegrade/shouldExitDegrade），可单测。
+ *
  * 采样自身开销：15s 一次 process.cpuUsage/memoryUsage + fs.stat（<0.01% CPU、
  * 零分配大对象），远低于「监控不能放大被监控对象」的护栏（resource-budget-review）。
  */
 import { statSync } from 'node:fs'
-import { evaluateResourceAlerts, DEFAULT_LIMITS } from './resource-rules.js'
+import { evaluateResourceAlerts, shouldEnterDegrade, shouldExitDegrade, DEFAULT_LIMITS } from './resource-rules.js'
 import { jsonlFile } from './store-persist.js'
 
 const DEFAULT_INTERVAL_MS = 15000
 const MAX_HISTORY = 60
 
-/** 创建资源监控器：{ sample, start, stop }。options: intervalMs / limits。 */
+/** 创建资源监控器：{ sample, start, stop }。options: intervalMs / limits / onDegrade / onRecover。 */
 export function createResourceMonitor(ctx, options = {}) {
-  const intervalMs = Number.isFinite(options.intervalMs) && options.intervalMs > 0 ? options.intervalMs : DEFAULT_INTERVAL_MS
+  const intervalMs =
+    Number.isFinite(options.intervalMs) && options.intervalMs > 0 ? options.intervalMs : DEFAULT_INTERVAL_MS
   const limits = { ...DEFAULT_LIMITS, ...(options.limits ?? {}) }
+  const onDegrade = typeof options.onDegrade === 'function' ? options.onDegrade : null
+  const onRecover = typeof options.onRecover === 'function' ? options.onRecover : null
   const state = {
     timer: null,
     file: jsonlFile(),
     lastSample: null,
     lastCpu: process.cpuUsage(),
     history: [],
+    degraded: false,
   }
   const monitor = {
-    sample: () => sample(state, limits),
+    sample: () => sample(state, limits, onDegrade, onRecover),
     start: () => startMonitor(state, intervalMs, monitor),
     stop: () => stopMonitor(state),
+    isDegraded: () => state.degraded,
   }
   return monitor
 }
 
-/** 采样一次：CPU 使用率（窗口内 user+sys）/RSS/审计文件字节/写入速率 + 告警。 */
-function sample(state, limits) {
+/** 采样一次：CPU 使用率（窗口内 user+sys）/RSS/审计文件字节/写入速率 + 告警 + 降级判定。 */
+function sample(state, limits, onDegrade, onRecover) {
   const now = Date.now()
   const cpu = process.cpuUsage()
   const cpuDelta = cpu.user - state.lastCpu.user + (cpu.system - state.lastCpu.system) // µs
@@ -60,10 +70,32 @@ function sample(state, limits) {
     state.history.push(sample)
     if (state.history.length > MAX_HISTORY) state.history.splice(0, state.history.length - MAX_HISTORY)
     state.lastSample = sample
-    return { ...sample, history: [...state.history], alerts: evaluateResourceAlerts(sample, limits) }
+    updateDegradeState(state, limits, onDegrade, onRecover)
+    return {
+      ...sample,
+      history: [...state.history],
+      alerts: evaluateResourceAlerts(sample, limits),
+      degraded: state.degraded,
+    }
   }
   state.lastSample = { time: now, fileBytes, memoryBytes, cpuPercent: 0, writeRateBytesPerHour: 0 }
-  return { ...state.lastSample, history: [...state.history], alerts: [] }
+  return { ...state.lastSample, history: [...state.history], alerts: [], degraded: state.degraded }
+}
+
+/**
+ * 降级状态机：未降级且连续超限 → 进入降级（回调）；已降级且连续正常 → 退出降级（回调）。
+ * 判定纯函数见 resource-rules.js；本函数只持有状态并触发宿主回调。
+ */
+function updateDegradeState(state, limits, onDegrade, onRecover) {
+  if (!state.degraded) {
+    if (shouldEnterDegrade(state.history, limits)) {
+      state.degraded = true
+      onDegrade?.()
+    }
+  } else if (shouldExitDegrade(state.history, limits)) {
+    state.degraded = false
+    onRecover?.()
+  }
 }
 
 /** 启动周期采样（幂等）。 */

package/lib/resource-rules.js

@@ -60,6 +60,43 @@ export function evaluateResourceAlerts(sample, limits = DEFAULT_LIMITS) {
   return alerts
 }
 
+/** 连续多少次采样超限（关键阈值）判定进入降级（模块内默认值）。 */
+const DEGRADE_CONFIRM_COUNT = 3
+
+/** 连续多少次采样正常判定退出降级（模块内默认值）。 */
+const RECOVER_CONFIRM_COUNT = 3
+
+/**
+ * 关键阈值判定：磁盘写放大风险主导（write-rate / file-size 任一超限即记超限）。
+ * CPU/内存超限告警但不触发落盘降级（避免误伤正常大请求峰值）。
+ */
+function isCriticalOverLimit(sample, limits = DEFAULT_LIMITS) {
+  return (
+    (sample.writeRateBytesPerHour ?? 0) > limits.writeRateBytesPerHour || (sample.fileBytes ?? 0) > limits.fileBytes
+  )
+}
+
+/**
+ * 降级判定（纯函数）：最近 confirmCount 个样本**全部**关键阈值超限 → 进入降级。
+ * 历史样本不足 confirmCount 时不降级（冷启动保护）。
+ * 返回布尔（shouldEnterDegrade）。
+ */
+export function shouldEnterDegrade(history, limits = DEFAULT_LIMITS, confirmCount = DEGRADE_CONFIRM_COUNT) {
+  const recent = history.slice(-confirmCount)
+  if (recent.length < confirmCount) return false
+  return recent.every((sample) => isCriticalOverLimit(sample, limits))
+}
+
+/**
+ * 恢复判定（纯函数）：最近 confirmCount 个样本**全部**关键阈值正常 → 退出降级。
+ * 历史样本不足 confirmCount 时不恢复（避免刚降级立即恢复抖动）。
+ */
+export function shouldExitDegrade(history, limits = DEFAULT_LIMITS, confirmCount = RECOVER_CONFIRM_COUNT) {
+  const recent = history.slice(-confirmCount)
+  if (recent.length < confirmCount) return false
+  return recent.every((sample) => !isCriticalOverLimit(sample, limits))
+}
+
 function fmtMB(bytes) {
   return `${(bytes / 1024 / 1024).toFixed(1)} MB`
 }

package/lib/store-persist.js

@@ -24,7 +24,7 @@ export const MAX_TOTAL_EVENTS = 20000
 export const COMPACT_LINES = 5000
 
 /** 数据根目录：$DSH_HOME（fallback 家目录）。 */
-export function dataHome() {
+function dataHome() {
   const home = process.env.DSH_HOME
   return typeof home === 'string' && home !== '' ? home : homedir()
 }
@@ -40,7 +40,7 @@ export function legacyFile() {
 }
 
 /** 事件结构校验（时间/会话/类型为合理形态）。 */
-export function isValidEvent(event) {
+function isValidEvent(event) {
   return (
     event !== null &&
     typeof event === 'object' &&
@@ -65,7 +65,9 @@ export function normalizeLoaded(bySession) {
   let total = 0
   for (const bucket of Object.values(sessionBuckets)) total += bucket.events.length
   if (total > MAX_TOTAL_EVENTS) {
-    const ordered = Object.keys(sessionBuckets).sort((a, b) => firstTimeOf(sessionBuckets[a]) - firstTimeOf(sessionBuckets[b]))
+    const ordered = Object.keys(sessionBuckets).sort(
+      (a, b) => firstTimeOf(sessionBuckets[a]) - firstTimeOf(sessionBuckets[b]),
+    )
     for (const sessionId of ordered) {
       if (total <= MAX_TOTAL_EVENTS) break
       total -= sessionBuckets[sessionId].events.length

package/lib/store.js

@@ -53,12 +53,14 @@ export function createStore(ctx) {
     compactTimer: null,
     compacting: false,
     migrated: false,
+    persistEnabled: true,
     dirtyChain: Promise.resolve(),
   }
   store.record = (event) => record(handle, event)
   store.events = (sessionId, type, limit) => eventsOf(handle, sessionId, type, limit)
   store.sessions = () => sessionsOf(handle)
   store.count = () => countOf(handle)
+  store.setPersistEnabled = (enabled) => setPersistEnabled(handle, enabled)
   store.dispose = () => dispose(handle)
   void loadPersisted(handle.file, handle.legacy).then((result) => onLoaded(handle, result))
   return store
@@ -76,14 +78,34 @@ function record(handle, event) {
   return item
 }
 
-/** 事件入内存桶 + 排队待落盘行（回放与运行时共用，保证回放也落盘）。 */
+/** 事件入内存桶 + 排队待落盘行（回放与运行时共用，保证回放也落盘）。
+ *  降级（persistEnabled=false）时事件照常入内存桶（有 FIFO 上限保护），
+ *  但不排队落盘行、不触发 flush——写盘完全停止，恢复时全量快照补齐。 */
 function enqueueRecord(handle, item) {
   appendEvent(handle, item)
+  if (!handle.persistEnabled) return
   handle.lineQueue.push(JSON.stringify(item))
   handle.queuedLines += 1
   if (handle.queuedLines >= COMPACT_LINES) scheduleCompact(handle)
 }
 
+/**
+ * 落盘开关（资源看门狗降级用）：
+ *  - false（降级）：停止落盘——清空待写行（内存 state 仍在，不丢），停 flush。
+ *  - true（恢复）：立即 compact 全量快照（内存=真相，补齐降级窗口事件），恢复增量。
+ */
+function setPersistEnabled(handle, enabled) {
+  if (handle.persistEnabled === enabled) return
+  handle.persistEnabled = enabled
+  if (handle.flushTimer !== null) {
+    clearTimeout(handle.flushTimer)
+    handle.flushTimer = null
+  }
+  handle.lineQueue = []
+  handle.queuedLines = 0
+  if (enabled) compactNow(handle)
+}
+
 /** 全部会话事件：合并各会话并按时间正序（sessionId='*'）。 */
 function eventsAllOf(handle, type, limit) {
   let all = []
@@ -112,7 +134,7 @@ function eventsOf(handle, sessionId, type, limit) {
   return capped.map((event) => ({ ...event }))
 }
 
-/** 有审计事件的会话列表（按最后活动时间倒序，含事件数）。 */
+/** 有审计事件的会话列表（按最后活动时间倒序，含事件数与可读标题）。 */
 function sessionsOf(handle) {
   const entries = Object.entries(handle.store.state.bySession)
   const list = entries
@@ -120,12 +142,23 @@ function sessionsOf(handle) {
       sessionId,
       count: bucket.events.length,
       lastTime: bucket.events.length > 0 ? bucket.events[bucket.events.length - 1].time : 0,
+      title: sessionTitleOf(bucket),
     }))
     .filter((entry) => entry.count > 0)
   list.sort((a, b) => b.lastTime - a.lastTime)
   return list
 }
 
+/** 会话标题：最早一条 user_message 事件的文本（无则空串，面板回退 UUID 短显）。 */
+function sessionTitleOf(bucket) {
+  for (const event of bucket.events) {
+    if (event.type === 'user_message' && typeof event.data?.text === 'string' && event.data.text !== '') {
+      return event.data.text
+    }
+  }
+  return ''
+}
+
 /** 全部会话事件总数（O(1) 计数）。 */
 function countOf(handle) {
   return handle.total
@@ -209,12 +242,10 @@ function scheduleFlush(handle) {
 }
 
 function flushNow(handle) {
-  if (handle.lineQueue.length === 0) return
+  if (handle.lineQueue.length === 0 || !handle.persistEnabled) return
   const text = `${handle.lineQueue.join('\n')}\n`
   handle.lineQueue = []
-  handle.dirtyChain = handle.dirtyChain.then(() =>
-    appendLines(handle.file, text, handle.ctx.logger, PREFIX),
-  )
+  handle.dirtyChain = handle.dirtyChain.then(() => appendLines(handle.file, text, handle.ctx.logger, PREFIX))
 }
 
 /** 防抖紧凑调度（合并短时间多次触发）。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-my-observability",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "DSH 可观测性 + Git 工程工具插件：会话轨迹回放（时间轴）、事件审计（agent 行为记录）、结构化 Git 提交（Conventional Commits）、增量 diff 审查（提交前审查）。DSH web plugin: trajectory replay timeline, event audit log, structured git commits, pre-commit incremental diff review.",
   "type": "module",
   "main": "lib/index.js",