dsh-session-guard 0.4.0 → 3.0.1

package/src/client/pause-button.tsx

@@ -1,129 +1,129 @@
-/**
- * dsh-session-guard — 「暂停会话 / 继续会话」按钮（`conversation.input.right`，order 20）。
- *
- * 交互（v0.2.0 修订）：
- * - 未暂停 → 「暂停会话」，**可点**：点击 POST `{action:'stepPause'}`，在**下一次 step 边界**暂停
- *   （不打断当前 step；step 1 也拦，不受峰谷 / provider 限制）；
- * - 已暂停（高峰自动拉门 **或** 手动请求已登记）→ 「继续会话」，点击 POST `{action:'stepResume'}`；
- * - 状态更新双通道：① SSE `/session-guard/events?session=<id>` 即时推送；② 10s 轮询兜底
- *   （SSE 不可用 / 断线时仍能收敛）。全部 fail-open，绝不抛错。
- *
- * 与 input-traffic 的「❄ 冻结追加 / 恢复追加」并列（order 30 在其右侧），互不取代：
- * 本按钮控 step 门，冻结按钮控回合级冻结 + 队列摘除。
- */
-import { useEffect, useState } from 'react'
-import {
-  pauseButtonLabel,
-  pauseButtonTitle,
-  readPauseState,
-  readStepSnapshot,
-  type PauseButtonState,
-} from './pause-button-text'
-import { injectClientCss } from './styles'
-
-/** slot 运行时注入的会话级 props。 */
-export interface PauseButtonProps {
-  sessionId?: string
-}
-
-/** SSE 不可用时的兜底轮询间隔（正常路径由事件驱动，几乎不触发）。 */
-const POLL_MS = 10_000
-
-const IDLE: PauseButtonState = { paused: false, heldSince: null, manual: false }
-
-/** 暂停 / 继续会话按钮。 */
-export function PauseButton({ sessionId }: PauseButtonProps) {
-  const [state, setState] = useState<PauseButtonState>(IDLE)
-  const [busy, setBusy] = useState(false)
-
-  injectClientCss()
-
-  useEffect(() => {
-    if (sessionId === undefined || sessionId === '') return
-    let cancelled = false
-
-    const poll = async (): Promise<void> => {
-      try {
-        const res = await fetch(`/session-guard/state?session=${encodeURIComponent(sessionId)}`)
-        const body = await res.json().catch(() => null)
-        if (cancelled) return
-        setState(readPauseState(body))
-      } catch {
-        // fail-open：路由不存在 / 网络失败 → 保持上一次状态。
-      }
-    }
-    void poll()
-    const timer = setInterval(() => {
-      void poll()
-    }, POLL_MS)
-
-    let source: EventSource | undefined
-    try {
-      source = new EventSource(`/session-guard/events?session=${encodeURIComponent(sessionId)}`)
-      source.onmessage = (ev: MessageEvent<string>) => {
-        try {
-          const msg = JSON.parse(ev.data) as { type?: string; state?: unknown }
-          if (cancelled || msg?.type !== 'step') return
-          setState(readStepSnapshot(msg.state))
-        } catch {
-          /* 非法负载：忽略，等下一次推送或轮询 */
-        }
-      }
-      // onerror：EventSource 会自行重连；轮询同时兜底。
-      source.onerror = () => undefined
-    } catch {
-      // 浏览器不支持 EventSource → 只靠轮询。
-    }
-
-    return () => {
-      cancelled = true
-      clearInterval(timer)
-      try {
-        source?.close()
-      } catch {
-        /* ignore */
-      }
-    }
-  }, [sessionId])
-
-  if (sessionId === undefined || sessionId === '') return null
-
-  const paused = state.paused === true
-  const onClick = async (): Promise<void> => {
-    if (busy) return
-    setBusy(true)
-    try {
-      const action = paused ? 'stepResume' : 'stepPause'
-      const res = await fetch('/session-guard/rpc', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ sessionId, action }),
-      })
-      const body = await res.json().catch(() => null)
-      if (body?.ok === true) {
-        // 立即乐观更新；SSE / 轮询随后校正。
-        setState(paused ? IDLE : { paused: true, heldSince: null, manual: true })
-      }
-    } catch {
-      // fail-open：下一轮轮询会纠正显示。
-    } finally {
-      setBusy(false)
-    }
-  }
-
-  return (
-    <button
-      type="button"
-      className="sg-pause"
-      disabled={busy}
-      aria-pressed={paused || undefined}
-      title={pauseButtonTitle(state)}
-      data-sg-step-paused={paused ? 'on' : 'off'}
-      onClick={() => {
-        void onClick()
-      }}
-    >
-      {pauseButtonLabel(state)}
-    </button>
-  )
-}
+/**
+ * dsh-session-guard — 「暂停会话 / 继续会话」按钮（`conversation.input.right`，order 20）。
+ *
+ * 交互（v0.2.0 修订）：
+ * - 未暂停 → 「暂停会话」，**可点**：点击 POST `{action:'stepPause'}`，在**下一次 step 边界**暂停
+ *   （不打断当前 step；step 1 也拦，不受峰谷 / provider 限制）；
+ * - 已暂停（高峰自动拉门 **或** 手动请求已登记）→ 「继续会话」，点击 POST `{action:'stepResume'}`；
+ * - 状态更新双通道：① SSE `/session-guard/events?session=<id>` 即时推送；② 10s 轮询兜底
+ *   （SSE 不可用 / 断线时仍能收敛）。全部 fail-open，绝不抛错。
+ *
+ * 与 input-traffic 的「❄ 冻结追加 / 恢复追加」并列（order 30 在其右侧），互不取代：
+ * 本按钮控 step 门，冻结按钮控回合级冻结 + 队列摘除。
+ */
+import { useEffect, useState } from 'react'
+import {
+  pauseButtonLabel,
+  pauseButtonTitle,
+  readPauseState,
+  readStepSnapshot,
+  type PauseButtonState,
+} from './pause-button-text'
+import { injectClientCss } from './styles'
+
+/** slot 运行时注入的会话级 props。 */
+export interface PauseButtonProps {
+  sessionId?: string
+}
+
+/** SSE 不可用时的兜底轮询间隔（正常路径由事件驱动，几乎不触发）。 */
+const POLL_MS = 10_000
+
+const IDLE: PauseButtonState = { paused: false, heldSince: null, manual: false }
+
+/** 暂停 / 继续会话按钮。 */
+export function PauseButton({ sessionId }: PauseButtonProps) {
+  const [state, setState] = useState<PauseButtonState>(IDLE)
+  const [busy, setBusy] = useState(false)
+
+  injectClientCss()
+
+  useEffect(() => {
+    if (sessionId === undefined || sessionId === '') return
+    let cancelled = false
+
+    const poll = async (): Promise<void> => {
+      try {
+        const res = await fetch(`/session-guard/state?session=${encodeURIComponent(sessionId)}`)
+        const body = await res.json().catch(() => null)
+        if (cancelled) return
+        setState(readPauseState(body))
+      } catch {
+        // fail-open：路由不存在 / 网络失败 → 保持上一次状态。
+      }
+    }
+    void poll()
+    const timer = setInterval(() => {
+      void poll()
+    }, POLL_MS)
+
+    let source: EventSource | undefined
+    try {
+      source = new EventSource(`/session-guard/events?session=${encodeURIComponent(sessionId)}`)
+      source.onmessage = (ev: MessageEvent<string>) => {
+        try {
+          const msg = JSON.parse(ev.data) as { type?: string; state?: unknown }
+          if (cancelled || msg?.type !== 'step') return
+          setState(readStepSnapshot(msg.state))
+        } catch {
+          /* 非法负载：忽略，等下一次推送或轮询 */
+        }
+      }
+      // onerror：EventSource 会自行重连；轮询同时兜底。
+      source.onerror = () => undefined
+    } catch {
+      // 浏览器不支持 EventSource → 只靠轮询。
+    }
+
+    return () => {
+      cancelled = true
+      clearInterval(timer)
+      try {
+        source?.close()
+      } catch {
+        /* ignore */
+      }
+    }
+  }, [sessionId])
+
+  if (sessionId === undefined || sessionId === '') return null
+
+  const paused = state.paused === true
+  const onClick = async (): Promise<void> => {
+    if (busy) return
+    setBusy(true)
+    try {
+      const action = paused ? 'stepResume' : 'stepPause'
+      const res = await fetch('/session-guard/rpc', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ sessionId, action }),
+      })
+      const body = await res.json().catch(() => null)
+      if (body?.ok === true) {
+        // 立即乐观更新；SSE / 轮询随后校正。
+        setState(paused ? IDLE : { paused: true, heldSince: null, manual: true })
+      }
+    } catch {
+      // fail-open：下一轮轮询会纠正显示。
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      className="sg-pause"
+      disabled={busy}
+      aria-pressed={paused || undefined}
+      title={pauseButtonTitle(state)}
+      data-sg-step-paused={paused ? 'on' : 'off'}
+      onClick={() => {
+        void onClick()
+      }}
+    >
+      {pauseButtonLabel(state)}
+    </button>
+  )
+}

package/src/client/styles.ts

@@ -1,30 +1,30 @@
-/**
- * dsh-session-guard — 客户端样式（与 composer 右侧 input-traffic 冻结按钮同一视觉语言）。
- *
- * 为什么注入 `<style>` 而不是 CSS Modules：本插件的 tsdown 配置没有 CSS Modules 管线
- * （input-traffic 有），而 settings-card 已经用 `<style data-plugin-css>` 的既有约定。
- * 这里只做一件事：把「暂停会话 / 继续会话」按钮与状态徽标对齐到同一行的其它控件
- * （高度 24px、圆角 6px、12px 字号、同样的 border / hover / pressed 令牌）。
- */
-
-/** 与 `dsh-input-traffic/src/client/freeze-button.module.css` 对齐的控件外观。 */
-export const CLIENT_CSS = `
-.sg-pause{display:inline-flex;align-items:center;gap:4px;height:24px;padding:0 8px;border:1px solid var(--dsw-alias-border-l3,rgba(0,0,0,.12));border-radius:6px;background:transparent;color:var(--dsw-alias-label-secondary,#6b7280);font-size:12px;line-height:1;cursor:pointer;white-space:nowrap;flex:none}
-.sg-pause:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover,rgba(0,0,0,.04))}
-.sg-pause:disabled{opacity:.55;cursor:default}
-.sg-pause[aria-pressed='true']{border-color:var(--dsw-alias-state-warning-primary,#d97706);color:var(--dsw-alias-state-warning-primary,#d97706);background:color-mix(in srgb,var(--dsw-alias-state-warning-primary,#d97706) 8%,transparent)}
-.sg-status{display:inline-flex;align-items:center;height:24px;padding:0 8px;border:1px solid var(--dsw-alias-border-l3,rgba(0,0,0,.12));border-radius:6px;font-size:12px;line-height:1;color:var(--dsw-alias-label-secondary,#6b7280);white-space:nowrap;flex:none}
-.sg-status.sg-peak{border-color:var(--dsw-alias-state-warning-primary,#d97706);color:var(--dsw-alias-state-warning-primary,#d97706)}
-.sg-status.sg-weekend{border-color:var(--dsw-alias-state-success-primary,#30a46c);color:var(--dsw-alias-state-success-primary,#30a46c)}
-`
-
-/** 注入一次（幂等；无 document 时静默跳过）。 */
-export function injectClientCss(): void {
-  if (typeof document === 'undefined') return
-  if (document.querySelector('style[data-plugin-css="session-guard-client"]') !== null) return
-  const tag = document.createElement('style')
-  tag.dataset.plugin = 'dsh-session-guard'
-  tag.dataset.pluginCss = 'session-guard-client'
-  tag.textContent = CLIENT_CSS
-  document.head.appendChild(tag)
-}
+/**
+ * dsh-session-guard — 客户端样式（与 composer 右侧 input-traffic 冻结按钮同一视觉语言）。
+ *
+ * 为什么注入 `<style>` 而不是 CSS Modules：本插件的 tsdown 配置没有 CSS Modules 管线
+ * （input-traffic 有），而 settings-card 已经用 `<style data-plugin-css>` 的既有约定。
+ * 这里只做一件事：把「暂停会话 / 继续会话」按钮与状态徽标对齐到同一行的其它控件
+ * （高度 24px、圆角 6px、12px 字号、同样的 border / hover / pressed 令牌）。
+ */
+
+/** 与 `dsh-input-traffic/src/client/freeze-button.module.css` 对齐的控件外观。 */
+export const CLIENT_CSS = `
+.sg-pause{display:inline-flex;align-items:center;gap:4px;height:24px;padding:0 8px;border:1px solid var(--dsw-alias-border-l3,rgba(0,0,0,.12));border-radius:6px;background:transparent;color:var(--dsw-alias-label-secondary,#6b7280);font-size:12px;line-height:1;cursor:pointer;white-space:nowrap;flex:none}
+.sg-pause:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover,rgba(0,0,0,.04))}
+.sg-pause:disabled{opacity:.55;cursor:default}
+.sg-pause[aria-pressed='true']{border-color:var(--dsw-alias-state-warning-primary,#d97706);color:var(--dsw-alias-state-warning-primary,#d97706);background:color-mix(in srgb,var(--dsw-alias-state-warning-primary,#d97706) 8%,transparent)}
+.sg-status{display:inline-flex;align-items:center;height:24px;padding:0 8px;border:1px solid var(--dsw-alias-border-l3,rgba(0,0,0,.12));border-radius:6px;font-size:12px;line-height:1;color:var(--dsw-alias-label-secondary,#6b7280);white-space:nowrap;flex:none}
+.sg-status.sg-peak{border-color:var(--dsw-alias-state-warning-primary,#d97706);color:var(--dsw-alias-state-warning-primary,#d97706)}
+.sg-status.sg-weekend{border-color:var(--dsw-alias-state-success-primary,#30a46c);color:var(--dsw-alias-state-success-primary,#30a46c)}
+`
+
+/** 注入一次（幂等；无 document 时静默跳过）。 */
+export function injectClientCss(): void {
+  if (typeof document === 'undefined') return
+  if (document.querySelector('style[data-plugin-css="session-guard-client"]') !== null) return
+  const tag = document.createElement('style')
+  tag.dataset.plugin = 'dsh-session-guard'
+  tag.dataset.pluginCss = 'session-guard-client'
+  tag.textContent = CLIENT_CSS
+  document.head.appendChild(tag)
+}

package/src/detect.js

@@ -1,27 +1,27 @@
-/**
- * dsh-session-guard — 自动检测（D7，诚实边界）。
- *
- * - host 可自动探测：`ctx.get('taskControl')`（会话门）、`ctx.get('sessionGuard')`。
- * - client 可自动探测：input-traffic 补的「最小桥」标记 `window.__DSH_SESSION_GUARD_BRIDGE__`
- *   （方案 A 中 input-traffic 冻结按钮触发时会调 sessionGuard.stopNextTurn）。
- *   探测不到 → 本插件客户端使用自带回退冻结（fallback），fail-open 不报错（D8）。
- */
-
-/** host：会话门（dsh-task-control）是否可用。 */
-export function detectTaskControl(ctx) {
-  return !!(ctx && typeof ctx.get === 'function' && ctx.get('taskControl'))
-}
-
-/** host：sessionGuard 服务是否已提供（其他插件探测用）。 */
-export function detectSessionGuard(ctx) {
-  return !!(ctx && typeof ctx.get === 'function' && ctx.get('sessionGuard'))
-}
-
-/**
- * client：input-traffic 最小桥是否已注册。
- * @param {object} [g] 显式传入全局对象（便于测试）；默认 globalThis
- */
-export function detectInputTrafficBridge(g) {
-  const root = g || (typeof globalThis !== 'undefined' ? globalThis : {})
-  return !!(root && root.__DSH_SESSION_GUARD_BRIDGE__ && typeof root.__DSH_SESSION_GUARD_BRIDGE__.stopNextTurn === 'function')
-}
+/**
+ * dsh-session-guard — 自动检测（D7，诚实边界）。
+ *
+ * - host 可自动探测：`ctx.get('taskControl')`（会话门）、`ctx.get('sessionGuard')`。
+ * - client 可自动探测：input-traffic 补的「最小桥」标记 `window.__DSH_SESSION_GUARD_BRIDGE__`
+ *   （方案 A 中 input-traffic 冻结按钮触发时会调 sessionGuard.stopNextTurn）。
+ *   探测不到 → 本插件客户端使用自带回退冻结（fallback），fail-open 不报错（D8）。
+ */
+
+/** host：会话门（dsh-task-control）是否可用。 */
+export function detectTaskControl(ctx) {
+  return !!(ctx && typeof ctx.get === 'function' && ctx.get('taskControl'))
+}
+
+/** host：sessionGuard 服务是否已提供（其他插件探测用）。 */
+export function detectSessionGuard(ctx) {
+  return !!(ctx && typeof ctx.get === 'function' && ctx.get('sessionGuard'))
+}
+
+/**
+ * client：input-traffic 最小桥是否已注册。
+ * @param {object} [g] 显式传入全局对象（便于测试）；默认 globalThis
+ */
+export function detectInputTrafficBridge(g) {
+  const root = g || (typeof globalThis !== 'undefined' ? globalThis : {})
+  return !!(root && root.__DSH_SESSION_GUARD_BRIDGE__ && typeof root.__DSH_SESSION_GUARD_BRIDGE__.stopNextTurn === 'function')
+}

package/src/gate.js

@@ -1,93 +1,93 @@
-/**
- * dsh-session-guard — 会话门驱动（D3/D5/D6，自研真实锁定）。
- *
- * **主路径**（替换 dsh-task-control）：经自研 `pauseGate` 真暂停 session 推进——
- * `pauseGate.pause(id,{mode,reason})` 调用 agent.cancel / goals.pause / session/event
- * 安全边界落地（见 src/pause-gate.js），不再依赖 `ctx.get('taskControl')`，也不再退化成
- * 只写 `queueLocked` 标记。
- *
- * **降级路径**（fail-open，D8）：仅当自研暂停因 agent 不可用而失败时，按 `queueFallback`
- * 回退为只锁等待队列（`queueLocked` 持久化标记，供前端/重试让路）。
- *
- * resume 对称：自研 resume（从暂停点续跑）或清 queueLock。
- */
-import { idleState } from './store.js'
-
-/**
- * @param {object} deps
- * @param {()=>object|null} deps.getCtx 取当前 host ctx（懒，便于测试）
- * @param {()=>object} deps.getSettings 读实时配置（pauseMode/pauseReason）
- * @param {ReturnType<import('./store.js').createStore>} deps.store 持久化队列锁
- * @param {ReturnType<import('./pause-gate.js').createPauseGate>} [deps.pauseGate] 自研会话门引擎
- * @param {(event:string, sessionId:string, payload?:object)=>void} [deps.emit] 状态变化通知
- */
-export function createGate({ getCtx: _getCtx, getSettings, store, pauseGate, emit }) {
-  function lockQueue(sessionId, reason) {
-    const cur = store.get(sessionId)
-    const next = { ...(cur || idleState(sessionId)), queueLocked: true, lockReason: reason, updatedAt: Date.now() }
-    store.set(sessionId, next)
-    if (emit) emit('queue-lock', sessionId, { reason })
-    return next
-  }
-
-  function unlockQueue(sessionId) {
-    const cur = store.get(sessionId)
-    const next = { ...(cur || idleState(sessionId)), queueLocked: false, lockReason: null, updatedAt: Date.now() }
-    store.set(sessionId, next)
-    if (emit) emit('queue-unlock', sessionId)
-    return next
-  }
-
-  /**
-   * 停掉 session 的下一回合（真实锁定推进）。
-   * ① 自研 pauseGate.pause（真暂停）；② 自研失败/agent 不可用 → 按 queueFallback 降级锁队列。
-   * @param {string} sessionId
-   * @param {object} [opts] { mode, reason }
-   */
-  async function stopNextTurn(sessionId, opts = {}) {
-    const cfg = getSettings()
-    if (pauseGate) {
-      try {
-        const mode = opts.mode ?? cfg.pauseMode ?? 'safe'
-        const reason = opts.reason ?? cfg.pauseReason ?? 'wait'
-        const r = pauseGate.pause(sessionId, { mode, reason })
-        if (r && r.kind === 'success') return { ok: true, via: 'pauseGate', result: r }
-        // kind === 'error'（如 no live agent）→ 落到降级，语义如实上报。
-      } catch {
-        // 自研内部异常 → fail-open 降级，绝不中断冻结动作。
-      }
-    }
-    // 无自研门或自研失败 → 回退只锁等待队列（自带实现，D5）。
-    if (cfg.queueFallback === false) {
-      return { ok: false, via: 'queueLock', error: 'queueFallback disabled' }
-    }
-    lockQueue(sessionId, 'peak')
-    return { ok: true, via: 'queueLock' }
-  }
-
-  /**
-   * 恢复 session 推进（从暂停点续跑）。
-   * ① 自研 resume（confirm + choice）；② 降级清 queueLock。
-   */
-  async function resume(sessionId, opts = {}) {
-    if (pauseGate) {
-      try {
-        const r = pauseGate.resume(sessionId, { confirm: true, choice: opts.choice ?? 'rerun' })
-        if (r && r.kind === 'success') return { ok: true, via: 'pauseGate', result: r }
-      } catch {
-        // 降级清队列锁。
-      }
-    }
-    unlockQueue(sessionId)
-    return { ok: true, via: 'queueLock' }
-  }
-
-  return {
-    stopNextTurn,
-    resume,
-    lockQueue,
-    unlockQueue,
-    /** 自研会话门是否可用（自研后恒视为可用；供 detect/UI 展示）。 */
-    taskControlAvailable: () => (pauseGate ? pauseGate.taskControlAvailable() : false),
-  }
-}
+/**
+ * dsh-session-guard — 会话门驱动（D3/D5/D6，自研真实锁定）。
+ *
+ * **主路径**（替换 dsh-task-control）：经自研 `pauseGate` 真暂停 session 推进——
+ * `pauseGate.pause(id,{mode,reason})` 调用 agent.cancel / goals.pause / session/event
+ * 安全边界落地（见 src/pause-gate.js），不再依赖 `ctx.get('taskControl')`，也不再退化成
+ * 只写 `queueLocked` 标记。
+ *
+ * **降级路径**（fail-open，D8）：仅当自研暂停因 agent 不可用而失败时，按 `queueFallback`
+ * 回退为只锁等待队列（`queueLocked` 持久化标记，供前端/重试让路）。
+ *
+ * resume 对称：自研 resume（从暂停点续跑）或清 queueLock。
+ */
+import { idleState } from './store.js'
+
+/**
+ * @param {object} deps
+ * @param {()=>object|null} deps.getCtx 取当前 host ctx（懒，便于测试）
+ * @param {()=>object} deps.getSettings 读实时配置（pauseMode/pauseReason）
+ * @param {ReturnType<import('./store.js').createStore>} deps.store 持久化队列锁
+ * @param {ReturnType<import('./pause-gate.js').createPauseGate>} [deps.pauseGate] 自研会话门引擎
+ * @param {(event:string, sessionId:string, payload?:object)=>void} [deps.emit] 状态变化通知
+ */
+export function createGate({ getCtx: _getCtx, getSettings, store, pauseGate, emit }) {
+  function lockQueue(sessionId, reason) {
+    const cur = store.get(sessionId)
+    const next = { ...(cur || idleState(sessionId)), queueLocked: true, lockReason: reason, updatedAt: Date.now() }
+    store.set(sessionId, next)
+    if (emit) emit('queue-lock', sessionId, { reason })
+    return next
+  }
+
+  function unlockQueue(sessionId) {
+    const cur = store.get(sessionId)
+    const next = { ...(cur || idleState(sessionId)), queueLocked: false, lockReason: null, updatedAt: Date.now() }
+    store.set(sessionId, next)
+    if (emit) emit('queue-unlock', sessionId)
+    return next
+  }
+
+  /**
+   * 停掉 session 的下一回合（真实锁定推进）。
+   * ① 自研 pauseGate.pause（真暂停）；② 自研失败/agent 不可用 → 按 queueFallback 降级锁队列。
+   * @param {string} sessionId
+   * @param {object} [opts] { mode, reason }
+   */
+  async function stopNextTurn(sessionId, opts = {}) {
+    const cfg = getSettings()
+    if (pauseGate) {
+      try {
+        const mode = opts.mode ?? cfg.pauseMode ?? 'safe'
+        const reason = opts.reason ?? cfg.pauseReason ?? 'wait'
+        const r = pauseGate.pause(sessionId, { mode, reason })
+        if (r && r.kind === 'success') return { ok: true, via: 'pauseGate', result: r }
+        // kind === 'error'（如 no live agent）→ 落到降级，语义如实上报。
+      } catch {
+        // 自研内部异常 → fail-open 降级，绝不中断冻结动作。
+      }
+    }
+    // 无自研门或自研失败 → 回退只锁等待队列（自带实现，D5）。
+    if (cfg.queueFallback === false) {
+      return { ok: false, via: 'queueLock', error: 'queueFallback disabled' }
+    }
+    lockQueue(sessionId, 'peak')
+    return { ok: true, via: 'queueLock' }
+  }
+
+  /**
+   * 恢复 session 推进（从暂停点续跑）。
+   * ① 自研 resume（confirm + choice）；② 降级清 queueLock。
+   */
+  async function resume(sessionId, opts = {}) {
+    if (pauseGate) {
+      try {
+        const r = pauseGate.resume(sessionId, { confirm: true, choice: opts.choice ?? 'rerun' })
+        if (r && r.kind === 'success') return { ok: true, via: 'pauseGate', result: r }
+      } catch {
+        // 降级清队列锁。
+      }
+    }
+    unlockQueue(sessionId)
+    return { ok: true, via: 'queueLock' }
+  }
+
+  return {
+    stopNextTurn,
+    resume,
+    lockQueue,
+    unlockQueue,
+    /** 自研会话门是否可用（自研后恒视为可用；供 detect/UI 展示）。 */
+    taskControlAvailable: () => (pauseGate ? pauseGate.taskControlAvailable() : false),
+  }
+}