dsh-session-guard 4.0.2 → 4.1.5

package/src/pause-store.js

@@ -1,101 +1,101 @@
-/**
- * dsh-session-guard — 自研会话门暂停状态持久化（脱离 dsh-task-control）。
- *
- * 与 queueLock（src/store.js，队列锁）分离：这里是「真暂停」的持久化快照，
- * 仿 task-control 的状态模型，但独立子目录 /pause 避免与队列锁文件互相污染。
- *
- * 暂停/锁定状态仍**不写 session log**（harness 持久化 reader 只有已知事件集，
- * 自定义 `session-guard/*` 事件会导致重启后会话无法加载），走插件自有 JSON 文件：
- * `$DSH_HOME/.dsh/session-guard/pause/<sessionId>.json`（`DSH_SESSION_GUARD_PAUSE_DIR`
- * 可覆盖根目录）。原子写：tmp + rename。
- */
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { storeRoot } from './store.js'
-
-/** 会话 id → 安全文件名（与队列锁同规则）。 */
-export function encodeSessionId(id) {
-  return String(id).replace(/[^a-zA-Z0-9._-]/g, '_')
-}
-
-/** 自研暂停状态根目录（独立于队列锁）。 */
-export function pauseStateRoot() {
-  return (
-    process.env.DSH_SESSION_GUARD_PAUSE_DIR ||
-    join(storeRoot(), 'pause')
-  )
-}
-
-/** 每会话暂停状态文件路径。 */
-export function pauseFilePath(id) {
-  return join(pauseStateRoot(), `${encodeSessionId(id)}.json`)
-}
-
-/** 未暂停基线快照。 */
-export function idlePauseState(id) {
-  return {
-    sessionId: String(id),
-    paused: false,
-    resumeContent: null,
-    forced: false,
-    interruptedTool: null,
-    deferredTools: null,
-    updatedAt: null,
-  }
-}
-
-/**
- * 创建暂停状态存储（内存缓存 + 磁盘持久化，原子写）。
- * 独立于队列锁 store，字段形态仿 task-control（paused/forced/interruptedTool/deferredTools）。
- */
-export function createPauseStore() {
-  const cache = new Map()
-
-  function read(id) {
-    if (cache.has(id)) return cache.get(id)
-    try {
-      const f = pauseFilePath(id)
-      if (!existsSync(f)) return null
-      const v = JSON.parse(readFileSync(f, 'utf8'))
-      cache.set(id, v)
-      return v
-    } catch {
-      return null
-    }
-  }
-
-  return {
-    /** 读一会话暂停态；无记录返回 null（调用方 fallback idlePauseState）。 */
-    get(id) {
-      return read(id)
-    },
-    /** 原子写。 */
-    set(id, value) {
-      cache.set(id, value)
-      try {
-        const f = pauseFilePath(id)
-        mkdirSync(dirname(f), { recursive: true })
-        const tmp = `${f}.tmp`
-        writeFileSync(tmp, JSON.stringify(value, null, 2))
-        renameSync(tmp, f)
-      } catch (e) {
-        // 落盘失败仅影响重启恢复，内存态仍可用。
-        console.error(`[session-guard] pause store write failed: ${String(e && e.message || e)}`)
-      }
-    },
-    /** 清除（resume/cancel 后）。 */
-    clear(id) {
-      cache.delete(id)
-      try {
-        rmSync(pauseFilePath(id), { force: true })
-      } catch {
-        /* ignore */
-      }
-    },
-    /** 当前有效快照（无记录时 idle 基线）。 */
-    current(id) {
-      const v = read(id)
-      return v !== null && typeof v === 'object' ? v : idlePauseState(id)
-    },
-  }
-}
+/**
+ * dsh-session-guard — 自研会话门暂停状态持久化（脱离 dsh-task-control）。
+ *
+ * 与 queueLock（src/store.js，队列锁）分离：这里是「真暂停」的持久化快照，
+ * 仿 task-control 的状态模型，但独立子目录 /pause 避免与队列锁文件互相污染。
+ *
+ * 暂停/锁定状态仍**不写 session log**（harness 持久化 reader 只有已知事件集，
+ * 自定义 `session-guard/*` 事件会导致重启后会话无法加载），走插件自有 JSON 文件：
+ * `$DSH_HOME/.dsh/session-guard/pause/<sessionId>.json`（`DSH_SESSION_GUARD_PAUSE_DIR`
+ * 可覆盖根目录）。原子写：tmp + rename。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { storeRoot } from './store.js'
+
+/** 会话 id → 安全文件名（与队列锁同规则）。 */
+export function encodeSessionId(id) {
+  return String(id).replace(/[^a-zA-Z0-9._-]/g, '_')
+}
+
+/** 自研暂停状态根目录（独立于队列锁）。 */
+export function pauseStateRoot() {
+  return (
+    process.env.DSH_SESSION_GUARD_PAUSE_DIR ||
+    join(storeRoot(), 'pause')
+  )
+}
+
+/** 每会话暂停状态文件路径。 */
+export function pauseFilePath(id) {
+  return join(pauseStateRoot(), `${encodeSessionId(id)}.json`)
+}
+
+/** 未暂停基线快照。 */
+export function idlePauseState(id) {
+  return {
+    sessionId: String(id),
+    paused: false,
+    resumeContent: null,
+    forced: false,
+    interruptedTool: null,
+    deferredTools: null,
+    updatedAt: null,
+  }
+}
+
+/**
+ * 创建暂停状态存储（内存缓存 + 磁盘持久化，原子写）。
+ * 独立于队列锁 store，字段形态仿 task-control（paused/forced/interruptedTool/deferredTools）。
+ */
+export function createPauseStore() {
+  const cache = new Map()
+
+  function read(id) {
+    if (cache.has(id)) return cache.get(id)
+    try {
+      const f = pauseFilePath(id)
+      if (!existsSync(f)) return null
+      const v = JSON.parse(readFileSync(f, 'utf8'))
+      cache.set(id, v)
+      return v
+    } catch {
+      return null
+    }
+  }
+
+  return {
+    /** 读一会话暂停态；无记录返回 null（调用方 fallback idlePauseState）。 */
+    get(id) {
+      return read(id)
+    },
+    /** 原子写。 */
+    set(id, value) {
+      cache.set(id, value)
+      try {
+        const f = pauseFilePath(id)
+        mkdirSync(dirname(f), { recursive: true })
+        const tmp = `${f}.tmp`
+        writeFileSync(tmp, JSON.stringify(value, null, 2))
+        renameSync(tmp, f)
+      } catch (e) {
+        // 落盘失败仅影响重启恢复，内存态仍可用。
+        console.error(`[session-guard] pause store write failed: ${String(e && e.message || e)}`)
+      }
+    },
+    /** 清除（resume/cancel 后）。 */
+    clear(id) {
+      cache.delete(id)
+      try {
+        rmSync(pauseFilePath(id), { force: true })
+      } catch {
+        /* ignore */
+      }
+    },
+    /** 当前有效快照（无记录时 idle 基线）。 */
+    current(id) {
+      const v = read(id)
+      return v !== null && typeof v === 'object' ? v : idlePauseState(id)
+    },
+  }
+}

package/src/retry.js

@@ -1,227 +1,227 @@
-/**
- * dsh-session-guard — 后端自动重试（host side，D9）。
- *
- * 监听 session/event：turn/end 以 error / interrupted / max-tokens 结束时，
- * 分类瞬时/永久失败，自适应退避后自动 `agent.followup(retryText)` 续跑。
- *
- * 关键纪律：
- * - **冻结让路**：会话被本插件门控（高峰暂停 / 队列锁）时不触发重试——
- *   与 input-traffic「freeze 是一等公民」一致，自动重试不得绕过会话门。
- * - 用户手动介入（user/message）与成功回合重置连续计数。
- * - 子代理会话不重试（由父代理处理）。
- * - 永久失败（鉴权/余额/模型不存在/上下文超限等）重试无益 → 停止并告警。
- *
- * 纯决策逻辑（classifyTurnEnd / isTransientFailure / effectiveCooldown /
- * shouldRetry）零依赖可单测；事件接线在 createRetry。
- */
-
-/** 默认重试配置。 */
-export const DEFAULT_RETRY = Object.freeze({
-  retryEnabled: false, // ← 自动重试开关（默认关，保守）
-  retryText: '继续（自动重试）',
-  retryGraceMs: 3000, // 失败后等待多久再发
-  retryCooldownMs: 20000, // 同一会话两次重试最小间隔
-  retryBackoffFactor: 2,
-  retryBackoffMaxMs: 300000,
-  retryMaxConsecutive: 3, // 连续重试上限，超过停止
-})
-
-/** 本插件自己的延后失败哨兵（与 deferrals.js 的 PEAK_DEFERRED_CODE 同一个值）。 */
-export const PEAK_DEFERRED_CODE = 'PEAK_DEFERRED'
-
-/**
- * 是否本插件的「高峰延后」失败（**精确匹配，唯一短路**）。
- *
- * 两条路径都必须认：
- * - `code === 'PEAK_DEFERRED'`：结构化路径（若上层保留了 failure.code）；
- * - `message` 以 `PEAK_DEFERRED:` 开头：DSH 回合循环只对 `error instanceof LlmError`
- *   保留结构化 failure，其它一律压成 `{ message: errorChain(error), code: 'UNKNOWN' }`
- *   （见 findings 8.3），本插件不能 value-import `@deepseek-ai/dsh-llm`。
- *
- * **严禁**在这里加 `高峰` / `已延后` / `拦截` 之类宽泛关键词——那会误伤真实错误，
- * 也会破坏 429 / 传输层的重试语义。
- */
-export function isPeakDeferredFailure({ code, message } = {}) {
-  if (code === PEAK_DEFERRED_CODE) return true
-  return typeof message === 'string' && message.startsWith(`${PEAK_DEFERRED_CODE}:`)
-}
-
-/** 瞬时 vs 永久失败分类：瞬时值得重试，永久重试无益。 */
-export function isTransientFailure({ code, message, status } = {}) {
-  // 本插件自己的延后失败是「永久」——重试只会再被拦一次，形成放大。
-  if (isPeakDeferredFailure({ code, message })) return false
-  const haystack = `${code ?? ''} ${message ?? ''}`.toLowerCase()
-  if (status !== undefined && (status === 401 || status === 403)) return false
-  const permanent =
-    /auth|unauthor|forbidden|credential|api\s*[_-]?\s*key|permission/i.test(haystack) ||
-    /insufficient.*(balance|quota)|billing|payment/i.test(haystack) ||
-    /model[^a-z]*not[^a-z]*found|unknown[_-]?model|not.*support.*model/i.test(haystack) ||
-    /context.*(length|limit|overflow|exceed)|token.*limit|max.*context/i.test(haystack) ||
-    /invalid[_-]?request|bad[_-]?request/i.test(haystack)
-  return !permanent
-}
-
-/**
- * turn/end reason → 是否可自动重试。
- * - completed / aborted（用户停）/ blocked（策略拒）→ 否
- * - error → 先按精确码短路 `PEAK_DEFERRED`（永久），再按 isTransientFailure 分类
- * - interrupted（崩溃修复）→ 可重试
- * - max-tokens → 可重试
- */
-export function classifyTurnEnd(reason, failure) {
-  const kind = reason && reason.kind
-  if (kind === 'completed' || kind === 'aborted' || kind === 'blocked') return false
-  if (kind === 'error') {
-    if (isPeakDeferredFailure(failure)) return false
-    return isTransientFailure(failure)
-  }
-  if (kind === 'interrupted' || kind === 'max-tokens') return true
-  return false
-}
-
-/** 自适应退避：consecutive 次连续后 cooldown * factor^n，封顶 max。 */
-export function effectiveCooldown(consecutive, base, factor, max) {
-  const mult = Math.pow(factor, Math.max(0, consecutive))
-  return Math.min(Math.max(base, base * mult), Math.max(base, max))
-}
-
-/**
- * 纯决策：此刻是否应触发重试。
- * @param {object} s 会话状态 { consecutive, lastAttemptAt, pending }
- * @param {object} cfg 重试配置
- * @param {boolean} frozen 会话是否被门控（高峰暂停/队列锁）
- * @param {number} now
- */
-export function shouldRetry(s, cfg, frozen, now = Date.now()) {
-  if (!cfg.retryEnabled) return false
-  if (frozen) return false // 冻结让路（D9）
-  if (s.pending) return false // 已有排队重试
-  if (s.consecutive >= cfg.retryMaxConsecutive) return false
-  if (now - s.lastAttemptAt < effectiveCooldown(s.consecutive, cfg.retryCooldownMs, cfg.retryBackoffFactor, cfg.retryBackoffMaxMs)) return false
-  return true
-}
-
-/** 会话状态工厂。 */
-export function freshRetryState() {
-  return { consecutive: 0, lastAttemptAt: 0, pending: false }
-}
-
-/**
- * 事件接线（host）：
- * @param {object} deps
- * @param {object} deps.ctx host context
- * @param {()=>object} deps.getSettings 读实时配置
- * @param {(sessionId:string)=>boolean} deps.isFrozen 会话是否被门控
- * @param {(sessionId:string, text:string)=>void} [deps.send] 发送函数（默认 agent.followup）
- */
-export function createRetry({ ctx, getSettings, isFrozen, send }) {
-  const states = new Map()
-
-  function state(sessionId) {
-    let s = states.get(sessionId)
-    if (!s) {
-      s = freshRetryState()
-      states.set(sessionId, s)
-    }
-    return s
-  }
-
-  /** 从 turn/end reason 提取失败事实。 */
-  function failureFacts(reason) {
-    const error = reason && reason.error
-    return {
-      code: error && typeof error.code === 'string' ? error.code : 'UNKNOWN',
-      message: error && typeof error.message === 'string' ? error.message : '',
-      status: error && typeof error.status === 'number' ? error.status : undefined,
-    }
-  }
-
-  function schedule(sessionId, reason) {
-    const s = state(sessionId)
-    const cfg = getSettings()
-    if (s.pending) return
-    const frozen = isFrozen(sessionId)
-    if (!shouldRetry({ ...s, pending: true }, cfg, frozen)) return
-    s.pending = true
-    const grace = cfg.retryGraceMs ?? DEFAULT_RETRY.retryGraceMs
-    const timer = setTimeout(() => {
-      s.pending = false
-      // 到点再复核：门控/上限变化后放弃。
-      if (!shouldRetry(s, cfg, isFrozen(sessionId))) return
-      const agent = ctx.agents.get(sessionId)
-      if (!agent || agent.status !== 'idle') return
-      const text = cfg.retryText ?? DEFAULT_RETRY.retryText
-      try {
-        if (send) {
-          send(sessionId, text)
-        } else {
-          // 与 autoresume 同构：直接构造 plugin-source 消息，避免运行时依赖。
-          agent.followup({
-            id: `session-guard-retry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-            role: 'user',
-            content: [{ type: 'text', text }],
-            source: { kind: 'plugin:session-guard', form: 'notice' },
-          })
-        }
-        s.lastAttemptAt = Date.now()
-        s.consecutive += 1
-        ctx.logger?.info?.(`[session-guard] auto-retry ${sessionId} (${String(reason && reason.kind)}), #${s.consecutive}`)
-      } catch (e) {
-        ctx.logger?.warn?.(`[session-guard] auto-retry send failed: ${String(e && e.message || e)}`)
-      }
-    }, grace)
-    // 会话对象上的清理钩子（若宿主提供）。
-    const dispose = () => clearTimeout(timer)
-    return dispose
-  }
-
-  function onEvent(session, event) {
-    const sessionId = session && session.id
-    if (typeof sessionId !== 'string') return
-    const s = state(sessionId)
-    switch (event.type) {
-      case 'turn/end': {
-        const reason = event.data && event.data.reason
-        if (reason && reason.kind === 'completed') {
-          s.consecutive = 0 // 成功回合重置
-          s.pending = false
-          return
-        }
-        if (reason && reason.kind === 'aborted') {
-          // 用户主动停止：不重试，重置。
-          s.consecutive = 0
-          s.pending = false
-          return
-        }
-        if (reason && classifyTurnEnd(reason, failureFacts(reason))) {
-          schedule(sessionId, reason)
-        }
-        return
-      }
-      case 'user/message': {
-        // 用户手动介入：重置（无论是否我们的回显都保守重置）。
-        if (event.data && event.data.source && event.data.source.kind === 'user') {
-          s.consecutive = 0
-          s.pending = false
-        }
-        return
-      }
-      default:
-        return
-    }
-  }
-
-  ctx.on('session/event', (session, event) => {
-    try {
-      onEvent(session, event)
-    } catch (e) {
-      ctx.logger?.warn?.(`[session-guard] retry event failed: ${String(e && e.message || e)}`)
-    }
-  })
-
-  return {
-    onEvent,
-    state,
-    states,
-  }
-}
+/**
+ * dsh-session-guard — 后端自动重试（host side，D9）。
+ *
+ * 监听 session/event：turn/end 以 error / interrupted / max-tokens 结束时，
+ * 分类瞬时/永久失败，自适应退避后自动 `agent.followup(retryText)` 续跑。
+ *
+ * 关键纪律：
+ * - **冻结让路**：会话被本插件门控（高峰暂停 / 队列锁）时不触发重试——
+ *   与 input-traffic「freeze 是一等公民」一致，自动重试不得绕过会话门。
+ * - 用户手动介入（user/message）与成功回合重置连续计数。
+ * - 子代理会话不重试（由父代理处理）。
+ * - 永久失败（鉴权/余额/模型不存在/上下文超限等）重试无益 → 停止并告警。
+ *
+ * 纯决策逻辑（classifyTurnEnd / isTransientFailure / effectiveCooldown /
+ * shouldRetry）零依赖可单测；事件接线在 createRetry。
+ */
+
+/** 默认重试配置。 */
+export const DEFAULT_RETRY = Object.freeze({
+  retryEnabled: false, // ← 自动重试开关（默认关，保守）
+  retryText: '继续（自动重试）',
+  retryGraceMs: 3000, // 失败后等待多久再发
+  retryCooldownMs: 20000, // 同一会话两次重试最小间隔
+  retryBackoffFactor: 2,
+  retryBackoffMaxMs: 300000,
+  retryMaxConsecutive: 3, // 连续重试上限，超过停止
+})
+
+/** 本插件自己的延后失败哨兵（与 deferrals.js 的 PEAK_DEFERRED_CODE 同一个值）。 */
+export const PEAK_DEFERRED_CODE = 'PEAK_DEFERRED'
+
+/**
+ * 是否本插件的「高峰延后」失败（**精确匹配，唯一短路**）。
+ *
+ * 两条路径都必须认：
+ * - `code === 'PEAK_DEFERRED'`：结构化路径（若上层保留了 failure.code）；
+ * - `message` 以 `PEAK_DEFERRED:` 开头：DSH 回合循环只对 `error instanceof LlmError`
+ *   保留结构化 failure，其它一律压成 `{ message: errorChain(error), code: 'UNKNOWN' }`
+ *   （见 findings 8.3），本插件不能 value-import `@deepseek-ai/dsh-llm`。
+ *
+ * **严禁**在这里加 `高峰` / `已延后` / `拦截` 之类宽泛关键词——那会误伤真实错误，
+ * 也会破坏 429 / 传输层的重试语义。
+ */
+export function isPeakDeferredFailure({ code, message } = {}) {
+  if (code === PEAK_DEFERRED_CODE) return true
+  return typeof message === 'string' && message.startsWith(`${PEAK_DEFERRED_CODE}:`)
+}
+
+/** 瞬时 vs 永久失败分类：瞬时值得重试，永久重试无益。 */
+export function isTransientFailure({ code, message, status } = {}) {
+  // 本插件自己的延后失败是「永久」——重试只会再被拦一次，形成放大。
+  if (isPeakDeferredFailure({ code, message })) return false
+  const haystack = `${code ?? ''} ${message ?? ''}`.toLowerCase()
+  if (status !== undefined && (status === 401 || status === 403)) return false
+  const permanent =
+    /auth|unauthor|forbidden|credential|api\s*[_-]?\s*key|permission/i.test(haystack) ||
+    /insufficient.*(balance|quota)|billing|payment/i.test(haystack) ||
+    /model[^a-z]*not[^a-z]*found|unknown[_-]?model|not.*support.*model/i.test(haystack) ||
+    /context.*(length|limit|overflow|exceed)|token.*limit|max.*context/i.test(haystack) ||
+    /invalid[_-]?request|bad[_-]?request/i.test(haystack)
+  return !permanent
+}
+
+/**
+ * turn/end reason → 是否可自动重试。
+ * - completed / aborted（用户停）/ blocked（策略拒）→ 否
+ * - error → 先按精确码短路 `PEAK_DEFERRED`（永久），再按 isTransientFailure 分类
+ * - interrupted（崩溃修复）→ 可重试
+ * - max-tokens → 可重试
+ */
+export function classifyTurnEnd(reason, failure) {
+  const kind = reason && reason.kind
+  if (kind === 'completed' || kind === 'aborted' || kind === 'blocked') return false
+  if (kind === 'error') {
+    if (isPeakDeferredFailure(failure)) return false
+    return isTransientFailure(failure)
+  }
+  if (kind === 'interrupted' || kind === 'max-tokens') return true
+  return false
+}
+
+/** 自适应退避：consecutive 次连续后 cooldown * factor^n，封顶 max。 */
+export function effectiveCooldown(consecutive, base, factor, max) {
+  const mult = Math.pow(factor, Math.max(0, consecutive))
+  return Math.min(Math.max(base, base * mult), Math.max(base, max))
+}
+
+/**
+ * 纯决策：此刻是否应触发重试。
+ * @param {object} s 会话状态 { consecutive, lastAttemptAt, pending }
+ * @param {object} cfg 重试配置
+ * @param {boolean} frozen 会话是否被门控（高峰暂停/队列锁）
+ * @param {number} now
+ */
+export function shouldRetry(s, cfg, frozen, now = Date.now()) {
+  if (!cfg.retryEnabled) return false
+  if (frozen) return false // 冻结让路（D9）
+  if (s.pending) return false // 已有排队重试
+  if (s.consecutive >= cfg.retryMaxConsecutive) return false
+  if (now - s.lastAttemptAt < effectiveCooldown(s.consecutive, cfg.retryCooldownMs, cfg.retryBackoffFactor, cfg.retryBackoffMaxMs)) return false
+  return true
+}
+
+/** 会话状态工厂。 */
+export function freshRetryState() {
+  return { consecutive: 0, lastAttemptAt: 0, pending: false }
+}
+
+/**
+ * 事件接线（host）：
+ * @param {object} deps
+ * @param {object} deps.ctx host context
+ * @param {()=>object} deps.getSettings 读实时配置
+ * @param {(sessionId:string)=>boolean} deps.isFrozen 会话是否被门控
+ * @param {(sessionId:string, text:string)=>void} [deps.send] 发送函数（默认 agent.followup）
+ */
+export function createRetry({ ctx, getSettings, isFrozen, send }) {
+  const states = new Map()
+
+  function state(sessionId) {
+    let s = states.get(sessionId)
+    if (!s) {
+      s = freshRetryState()
+      states.set(sessionId, s)
+    }
+    return s
+  }
+
+  /** 从 turn/end reason 提取失败事实。 */
+  function failureFacts(reason) {
+    const error = reason && reason.error
+    return {
+      code: error && typeof error.code === 'string' ? error.code : 'UNKNOWN',
+      message: error && typeof error.message === 'string' ? error.message : '',
+      status: error && typeof error.status === 'number' ? error.status : undefined,
+    }
+  }
+
+  function schedule(sessionId, reason) {
+    const s = state(sessionId)
+    const cfg = getSettings()
+    if (s.pending) return
+    const frozen = isFrozen(sessionId)
+    if (!shouldRetry({ ...s, pending: true }, cfg, frozen)) return
+    s.pending = true
+    const grace = cfg.retryGraceMs ?? DEFAULT_RETRY.retryGraceMs
+    const timer = setTimeout(() => {
+      s.pending = false
+      // 到点再复核：门控/上限变化后放弃。
+      if (!shouldRetry(s, cfg, isFrozen(sessionId))) return
+      const agent = ctx.agents.get(sessionId)
+      if (!agent || agent.status !== 'idle') return
+      const text = cfg.retryText ?? DEFAULT_RETRY.retryText
+      try {
+        if (send) {
+          send(sessionId, text)
+        } else {
+          // 与 autoresume 同构：直接构造 plugin-source 消息，避免运行时依赖。
+          agent.followup({
+            id: `session-guard-retry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            role: 'user',
+            content: [{ type: 'text', text }],
+            source: { kind: 'plugin:session-guard', form: 'notice' },
+          })
+        }
+        s.lastAttemptAt = Date.now()
+        s.consecutive += 1
+        ctx.logger?.info?.(`[session-guard] auto-retry ${sessionId} (${String(reason && reason.kind)}), #${s.consecutive}`)
+      } catch (e) {
+        ctx.logger?.warn?.(`[session-guard] auto-retry send failed: ${String(e && e.message || e)}`)
+      }
+    }, grace)
+    // 会话对象上的清理钩子（若宿主提供）。
+    const dispose = () => clearTimeout(timer)
+    return dispose
+  }
+
+  function onEvent(session, event) {
+    const sessionId = session && session.id
+    if (typeof sessionId !== 'string') return
+    const s = state(sessionId)
+    switch (event.type) {
+      case 'turn/end': {
+        const reason = event.data && event.data.reason
+        if (reason && reason.kind === 'completed') {
+          s.consecutive = 0 // 成功回合重置
+          s.pending = false
+          return
+        }
+        if (reason && reason.kind === 'aborted') {
+          // 用户主动停止：不重试，重置。
+          s.consecutive = 0
+          s.pending = false
+          return
+        }
+        if (reason && classifyTurnEnd(reason, failureFacts(reason))) {
+          schedule(sessionId, reason)
+        }
+        return
+      }
+      case 'user/message': {
+        // 用户手动介入：重置（无论是否我们的回显都保守重置）。
+        if (event.data && event.data.source && event.data.source.kind === 'user') {
+          s.consecutive = 0
+          s.pending = false
+        }
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  ctx.on('session/event', (session, event) => {
+    try {
+      onEvent(session, event)
+    } catch (e) {
+      ctx.logger?.warn?.(`[session-guard] retry event failed: ${String(e && e.message || e)}`)
+    }
+  })
+
+  return {
+    onEvent,
+    state,
+    states,
+  }
+}