dsh-session-guard 0.1.5-beta.1 → 0.3.0

package/src/index.js

@@ -19,7 +19,9 @@ import { createBridge } from './bridge.js'
 import { createRetry } from './retry.js'
 import { createPauseStore } from './pause-store.js'
 import { createPauseGate } from './pause-gate.js'
+import { createStepGate } from './step-gate.js'
 import { detectTaskControl } from './detect.js'
+import { makeIsRoot } from './request-guard.js'
 import { createWiring } from './wiring.js'
 import { NS, DEFAULT_SETTINGS, SettingsSchema, registerSettings } from './settings.js'
 
@@ -42,17 +44,52 @@ export function apply(ctx) {
     }
   }
 
+  // ── SSE 推送（v0.2.0）：step 门状态变化时立刻推给对应会话页面 ──
+  // 客户端「暂停会话 / 继续会话」按钮据此更新，无需等轮询。
+  const sseClients = new Set()
+
+  function sseSend(client, payload) {
+    try {
+      client.res.write(`data: ${JSON.stringify(payload)}\n\n`)
+    } catch {
+      /* 连接已断开：交给 close 事件清理 */
+    }
+  }
+
+  function broadcastStep(sessionId, stepState) {
+    const id = String(sessionId)
+    for (const client of [...sseClients]) {
+      if (client.sessionId !== '' && client.sessionId !== id) continue
+      sseSend(client, { type: 'step', sessionId: id, state: stepState })
+    }
+  }
+
   // ── 自研会话门（脱离 dsh-task-control，真暂停）──
   // 状态持久化 + 引擎；经 gate.stopNextTurn/resume 主路径接入；/pause /resume /cancel 命令。
+  // v0.2.0 追加 step 级门控（src/step-gate.js）：stepGate 与 pauseGate/wiring 互相需要，
+  // 用 late-bound 引用装配，避免构造期循环依赖。
   const pauseStore = createPauseStore()
-  const pauseGate = createPauseGate({ ctx, pauseStore })
+  let pauseGateRef = null
+  let wiringRef = null
+  const stepGate = createStepGate({
+    getSettings: readCfg,
+    shouldHoldSession: (cfg, id) => (wiringRef ? wiringRef.shouldPauseSession(cfg, id) : true),
+    isHeldByDeferrals: (id) => (wiringRef ? wiringRef.deferrals.has(id) : false),
+    isRootAgent: makeIsRoot(ctx),
+    pauseGate: { pause: (id, opts) => pauseGateRef.pause(id, opts) },
+    logger: ctx.logger,
+    onChange: (id, snapshot) => broadcastStep(id, snapshot),
+  })
+  const pauseGate = createPauseGate({ ctx, pauseStore, stepGate })
+  pauseGateRef = pauseGate
   const gate = createGate({ getCtx: () => ctx, getSettings: readCfg, store, pauseGate })
-  const bridge = createBridge(ctx, gate, store, pauseGate)
+  const bridge = createBridge(ctx, gate, store, pauseGate, stepGate)
 
   // ── 官方 provider 二维判定接线（目标追踪 / 请求级守卫 / 入峰过滤 / 退峰释放）──
   // 纯逻辑见 provider.js / provider-directory.js / deferrals.js / request-guard.js / targets.js，
   // 接线与编排见 wiring.js；这里只负责装配与生命周期。
-  const wiring = createWiring({ ctx, getSettings: readCfg, gate, logger: ctx.logger })
+  const wiring = createWiring({ ctx, getSettings: readCfg, gate, stepGate, logger: ctx.logger })
+  wiringRef = wiring
 
   // ── 冗余端口：input-traffic 冻结按钮透传接入（D5/D6/D8）──
   ctx.provide('sessionGuard', bridge)
@@ -74,6 +111,11 @@ export function apply(ctx) {
   // ── 请求级守卫（agent/request waterfall）──
   // 覆盖缺口：tick 只在状态跳变时处理 running 会话，入峰后新启动 / 中途切官方都会漏。
   ctx.effect(() => wiring.installGuard(), 'session-guard: request guard')
+
+  // ── step 级门控（agent/pre-step waterfall，v0.2.0）──
+  // 高峰 + 非周末 + 目标官方 → 在下一个 step 的模型请求前拉门；退峰原地续跑。
+  ctx.effect(() => wiring.installStepGuard(), 'session-guard: step guard')
+
   ctx.effect(() => () => wiring.dispose(), 'session-guard: wiring dispose')
 
   // ── 手动会话门命令（/pause /resume /cancel，全量移植）──
@@ -102,6 +144,8 @@ export function apply(ctx) {
         const sid = String(invocation?.agent?.id ?? '')
         if (!sid) return { kind: 'error', text: 'no session for this command' }
         const tokens = tokensOf(invocation.rawInput)
+        // v0.2.0：step 门挂起时，「恢复」= 放行该 step 且本峰内不再拦（用户显式继续）。
+        bridge.stepResume(sid, { bypass: true, reason: 'command' })
         return pauseGate.resume(sid, {
           confirm: tokens.includes('confirm'),
           choice: tokens.includes('skip') ? 'skip' : 'rerun',
@@ -114,6 +158,7 @@ export function apply(ctx) {
       handler: (invocation) => {
         const sid = String(invocation?.agent?.id ?? '')
         if (!sid) return { kind: 'error', text: 'no session for this command' }
+        bridge.stepResume(sid, { bypass: false, reason: 'command' })
         return pauseGate.cancel(sid)
       },
     }))
@@ -127,6 +172,7 @@ export function apply(ctx) {
       const st = bridge.state(sessionId)
       if (st.queueLocked) return true
       if (st.paused) return true // 自研会话门真暂停
+      if (st.pausedStep) return true // v0.2.0：step 门挂起同样让路，绝不绕过会话门
       if (st.taskControl && st.taskControl.paused) return true
       return false
     },
@@ -190,14 +236,52 @@ export function apply(ctx) {
           if (method === 'GET' && url.pathname === '/session-guard/state') {
             const sessionId = url.searchParams.get('session') ?? ''
             if (!sessionId) return json(400, { ok: false, error: 'missing session' })
+            const st = bridge.state(sessionId)
             return json(200, {
               ok: true,
-              state: bridge.state(sessionId),
+              state: st,
+              // v0.2.0：PRD §6.2 的 `paused: { step, turn }` 形状（顶层，兼容既有 state.paused 布尔）
+              // step = 已拉门；manual = 已请求但还没到边界（按钮同样显示「继续会话」）
+              paused: { step: st.pausedStep === true, turn: st.paused === true, manual: st.stepManual === true },
+              stepGate: {
+                held: st.pausedStep === true,
+                manual: st.stepManual === true,
+                since: st.stepHeldSince,
+                bypass: st.stepBypass === true,
+              },
               target: wiring.targets.get(sessionId),
               held: wiring.deferrals.has(sessionId),
               deferred: wiring.deferrals.isDeferred(sessionId),
             })
           }
+          // GET /session-guard/events?session=<id> —— SSE：step 门状态变化即时推送
+          if (method === 'GET' && url.pathname === '/session-guard/events') {
+            const sessionId = url.searchParams.get('session') ?? ''
+            res.writeHead(200, {
+              'content-type': 'text/event-stream; charset=utf-8',
+              'cache-control': 'no-cache, no-transform',
+              connection: 'keep-alive',
+            })
+            res.write(': connected\n\n')
+            const client = { sessionId, res }
+            sseClients.add(client)
+            sseSend(client, { type: 'step', sessionId, state: stepGate.state(sessionId) })
+            const keepAlive = setInterval(() => {
+              try {
+                res.write(': ping\n\n')
+              } catch {
+                /* 连接已断开 */
+              }
+            }, 25_000)
+            if (typeof keepAlive.unref === 'function') keepAlive.unref()
+            const cleanup = () => {
+              clearInterval(keepAlive)
+              sseClients.delete(client)
+            }
+            req.on?.('close', cleanup)
+            res.on?.('close', cleanup)
+            return undefined
+          }
           // GET /session-guard/provider?provider=<id> —— 官方判定诊断（排查误判用）
           if (method === 'GET' && url.pathname === '/session-guard/provider') {
             const provider = url.searchParams.get('provider') ?? ''
@@ -229,8 +313,10 @@ export function apply(ctx) {
                 enabled: cfg.enabled,
                 weekendMode: cfg.weekendMode,
                 providerGuard: cfg.providerGuard === true,
+                stepLevelPause: cfg.stepLevelPause === true,
                 held: wiring.deferrals.size(),
                 deferred: wiring.deferrals.deferredSize(),
+                stepHeld: stepGate.heldIds().length,
                 timezone: cfg.timezone,
                 billingTimezone: BILLING_TIMEZONE,
                 now: now.toISOString(),
@@ -267,6 +353,12 @@ export function apply(ctx) {
                 configurableProviders: wiring.directory.entries().length,
                 held: wiring.deferrals.size(),
                 deferred: wiring.deferrals.deferredSize(),
+                stepGate: {
+                  held: stepGate.heldIds(),
+                  bypass: stepGate._bypassed(),
+                  timeoutMs: readCfg().stepGateTimeoutMs,
+                  enabled: readCfg().stepLevelPause === true,
+                },
               },
             })
           }
@@ -288,6 +380,16 @@ export function apply(ctx) {
             if (action === 'resume') return json(200, { ok: true, result: await bridge.resume(sessionId, parsed) })
             if (action === 'lockQueue') return json(200, { ok: true, result: bridge.lockQueue(sessionId, parsed.reason) })
             if (action === 'unlockQueue') return json(200, { ok: true, result: bridge.unlockQueue(sessionId) })
+            if (action === 'stepResume') {
+              return json(200, {
+                ok: true,
+                result: bridge.stepResume(sessionId, {
+                  bypass: parsed.bypass !== false,
+                  reason: typeof parsed.reason === 'string' && parsed.reason !== '' ? parsed.reason : 'rpc',
+                }),
+              })
+            }
+            if (action === 'stepPause') return json(200, { ok: true, result: bridge.stepPause(sessionId) })
             if (action === 'state') return json(200, { ok: true, state: bridge.state(sessionId) })
             return json(400, { ok: false, error: `unknown action ${action}` })
           }

package/src/pause-gate.js

@@ -52,11 +52,26 @@ export function createPluginUserMessage({ content, source }) {
  * @param {ReturnType<import('./pause-store.js').createPauseStore>} deps.pauseStore 暂停状态存储
  * @param {string} [deps.pluginId] followup 消息的 source.plugin（默认 'session-guard'）
  * @param {(input: {content: object, source: object}) => unknown} [deps.makeFollowupMessage] 恢复消息构造（默认本地构造；测试注入）
+ * @param {ReturnType<import('./step-gate.js').createStepGate>} [deps.stepGate] step 级门控（v0.2.0）
+ *
+ * **为什么 pause/resume/cancel 必须先释放 step gate（F6 死锁）**：step 门控挂起在
+ * `agent/pre-step`，此刻既不会产生 `assistant/message` 也不会产生 `tool/result`；
+ * 而 safe+wait / safe+stop 都靠这两个事件落地暂停 → 两边互等，会话永久卡死。
  */
-export function createPauseGate({ ctx, pauseStore, pluginId = 'session-guard', makeFollowupMessage = createPluginUserMessage }) {
+export function createPauseGate({ ctx, pauseStore, pluginId = 'session-guard', makeFollowupMessage = createPluginUserMessage, stepGate }) {
   const state = { inFlight: new Map(), pendingPause: new Map() }
   const getAgent = (sessionId) => (ctx && typeof ctx.agents?.get === 'function' ? ctx.agents.get(sessionId) : undefined)
 
+  /** 先解开 step 门（若存在），再走 turn 级逻辑；任何异常都不阻断暂停动作。 */
+  function releaseStepGate(sessionId, reason) {
+    if (!stepGate || typeof stepGate.release !== 'function') return
+    try {
+      stepGate.release(sessionId, reason)
+    } catch (e) {
+      ctx?.logger?.warn?.('[session-guard] step gate release failed: ' + String(e))
+    }
+  }
+
   /** 会话门（dsh-task-control）当前是否可用（兼容探测；自研后始终视为可用）。 */
   const taskControlAvailable = () => true
 
@@ -218,6 +233,8 @@ export function createPauseGate({ ctx, pauseStore, pluginId = 'session-guard', m
    * 默认 safe+wait（对齐 DEFAULT_SETTINGS）。返回 { kind, text, needConfirmation? }。
    */
   function pauseTask(sessionId, opts = {}) {
+    // F6：先解开 step 门，否则 safe 模式的 pendingPause 永远等不到安全边界事件。
+    releaseStepGate(sessionId, 'pause')
     const agent = getAgent(sessionId)
     if (agent === undefined) return { kind: 'error', text: 'no live agent for this session — nothing to pause' }
     const current = currentPause(sessionId)
@@ -262,6 +279,8 @@ export function createPauseGate({ ctx, pauseStore, pluginId = 'session-guard', m
    * opts: { confirm:boolean, choice:'rerun'|'skip' }。
    */
   function resumeTask(sessionId, opts = {}) {
+    // F6：step 门挂起时「恢复」等价于放行该 step（回合本来就还开着）。
+    releaseStepGate(sessionId, 'resume')
     const agent = getAgent(sessionId)
     if (agent === undefined) return { kind: 'error', text: 'no live agent for this session' }
     state.pendingPause.delete(sessionId)
@@ -336,6 +355,8 @@ export function createPauseGate({ ctx, pauseStore, pluginId = 'session-guard', m
 
   /** 立即终止当前回合，回报被中断工具的目的/副作用风险。 */
   function cancelTask(sessionId) {
+    // F6：取消 = 释放 step 门 + 中断回合（顺序无所谓，release 幂等）。
+    releaseStepGate(sessionId, 'cancel')
     const agent = getAgent(sessionId)
     if (agent === undefined) return { kind: 'error', text: 'no live agent for this session' }
     const current = currentPause(sessionId)

package/src/settings.js

@@ -28,6 +28,8 @@ export const DEFAULT_SETTINGS = Object.freeze({
   ],
   pauseMode: 'safe', // 透传 taskControl.pause mode
   pauseReason: 'wait', // 透传 taskControl.pause reason
+  stepLevelPause: true, // step 级门控（agent/pre-step）：高峰在下一个 step 前拉门
+  stepGateTimeoutMs: 300_000, // step 门控超时（防死锁；到期升级为 turn 级 force 暂停）
   queueFallback: true, // 无会话门时回退锁等待队列（简单开关）
   retryEnabled: false, // 自动重试开关（后端，D9；默认关，保守）
   retryText: DEFAULT_RETRY.retryText,
@@ -61,6 +63,8 @@ export const SettingsSchema = z.object({
     .default(DEFAULT_SETTINGS.peakWindows),
   pauseMode: z.union([z.const('safe'), z.const('force')]).default(DEFAULT_SETTINGS.pauseMode),
   pauseReason: z.union([z.const('wait'), z.const('stop')]).default(DEFAULT_SETTINGS.pauseReason),
+  stepLevelPause: z.boolean().default(DEFAULT_SETTINGS.stepLevelPause),
+  stepGateTimeoutMs: z.number().min(0).default(DEFAULT_SETTINGS.stepGateTimeoutMs),
   queueFallback: z.boolean().default(DEFAULT_SETTINGS.queueFallback),
   retryEnabled: z.boolean().default(DEFAULT_SETTINGS.retryEnabled),
   retryText: z.string().default(DEFAULT_SETTINGS.retryText),

package/src/step-gate.js

@@ -0,0 +1,399 @@
+/**
+ * dsh-session-guard — step 级门控（v0.2.0，`agent/pre-step` waterfall）。
+ *
+ * 为什么需要它：turn 级暂停（pause-gate.js）只在安全边界停下整个回合，
+ * 高峰切入时已经花掉当前 step 的 token。step 门控挂在 `agent/pre-step`，
+ * 在**下一个 step 的模型请求发生之前**把回合挂起，退峰/手动继续后原地续跑。
+ *
+ * 关键语义（见计划 findings F2/F3/F6/F7/F8）：
+ * - `agent/pre-step` 是 waterfall：监听器 `await` 任意 Promise 后再 `return next()` 合法。
+ *   **不要**返回 `{kind:'reject'}`——loop 把 reject 映射为 `turnEnds={kind:'blocked'}` 并结束回合。
+ * - abort：`await` 期间 signal abort 必须自己 resolve（否则 Promise 泄漏）；resolve 后
+ *   loop 的 `signal.throwIfAborted()` 会抛出并结束回合，因此 agent.cancel 天然解锁。
+ * - 超时（默认 5min）：不是放行，而是**升级为 turn 级 force 暂停**（F8），
+ *   否则会在高峰形成「每 5 分钟一个 step」的 token drip。
+ * - 互斥：请求级 hold（deferrals）已挂起该会话时绝不拉门（F7）。
+ * - 手动「继续」置 bypass，本峰内不再拦该会话（否则下一个 pre-step 立刻再拉门）。
+ *
+ * 状态仅存内存：挂起的是 Promise，进程重启必然失效，落盘只会产生幽灵状态。
+ * 零 `@deepseek-ai/*` 值导入；所有判定异常 fail-open 放行。
+ */
+import { shouldPause } from './time.js'
+
+/** 默认 step 门控超时（防死锁，与 PRD §2.2 的 5min 一致）。 */
+export const DEFAULT_STEP_TIMEOUT_MS = 300_000
+
+/**
+ * 纯判定：该 step 是否应拉门。
+ *
+ * 顺序（全部满足才拉门，任一步抛错由调用方 fail-open）：
+ *   1. enabled            2. stepLevelPause      3. step > 1
+ *   4. 未被 bypass        5. root / guardSubagents
+ *   6. pauseVerdict.pause（含周末 / 峰谷）        7. shouldHoldSession（providerGuard 二维判定）
+ *   8. 未被请求级 hold    9. 该会话当前没有已挂起的门
+ *
+ * @param {object} input
+ * @param {object} input.cfg 实时设置
+ * @param {number} input.step 提议的 step 号（1 基）
+ * @param {boolean} [input.isRoot] 是否 root agent
+ * @param {{pause:boolean,reason:string}} input.pauseVerdict time.shouldPause 结果
+ * @param {(cfg:object,sessionId:string)=>boolean} [input.shouldHoldSession] 目标 provider 判定
+ * @param {boolean} [input.isHeldByDeferrals] 请求级守卫是否已挂起该会话
+ * @param {boolean} [input.bypassed] 本峰内是否被用户手动跳过
+ * @param {boolean} [input.alreadyHeld] 该会话是否已有挂起的门
+ * @param {boolean} [input.manual] 用户手动点了「暂停会话」（优先级最高，不受峰谷/step/provider 限制）
+ * @returns {{hold:boolean, why:string}}
+ */
+export function decideStepHold({
+  cfg,
+  step,
+  isRoot = true,
+  pauseVerdict,
+  shouldHoldSession,
+  isHeldByDeferrals = false,
+  bypassed = false,
+  alreadyHeld = false,
+  manual = false,
+} = {}) {
+  // 手动暂停：用户显式意图，绕过 enabled / stepLevelPause / step>1 / 峰谷 / provider 判定，
+  // 仅保留互斥铁律（请求已 hold）与防双门。
+  if (manual === true) {
+    if (isHeldByDeferrals === true) return { hold: false, why: 'request-held' }
+    if (alreadyHeld === true) return { hold: false, why: 'already-held' }
+    return { hold: true, why: 'manual' }
+  }
+  if (!cfg || cfg.enabled !== true) return { hold: false, why: 'disabled' }
+  if (cfg.stepLevelPause !== true) return { hold: false, why: 'step-level-off' }
+  if (!(Number(step) > 1)) return { hold: false, why: 'first-step' }
+  if (bypassed === true) return { hold: false, why: 'bypassed' }
+  if (isRoot === false && cfg.guardSubagents === false) return { hold: false, why: 'subagent' }
+  if (!pauseVerdict || pauseVerdict.pause !== true) {
+    return { hold: false, why: (pauseVerdict && pauseVerdict.reason) || 'not-peak' }
+  }
+  if (typeof shouldHoldSession === 'function' && shouldHoldSession(cfg) !== true) {
+    return { hold: false, why: 'non-official' }
+  }
+  if (isHeldByDeferrals === true) return { hold: false, why: 'request-held' }
+  if (alreadyHeld === true) return { hold: false, why: 'already-held' }
+  return { hold: true, why: 'peak' }
+}
+
+/**
+ * step 门控引擎。
+ *
+ * @param {object} deps
+ * @param {()=>object} deps.getSettings 读实时设置
+ * @param {(cfg:object,sessionId:string)=>boolean} [deps.shouldHoldSession] 复用 wiring.shouldPauseSession
+ * @param {(sessionId:string)=>boolean} [deps.isHeldByDeferrals] 请求级 hold 查询
+ * @param {(agent:object)=>boolean} [deps.isRootAgent] root 判定（默认恒 true）
+ * @param {{pause:(id:string,opts:object)=>unknown}} [deps.pauseGate] 超时升级用的 turn 级门
+ * @param {object} [deps.logger]
+ * @param {()=>number} [deps.now]
+ * @param {typeof setTimeout} [deps.setTimer]
+ * @param {typeof clearTimeout} [deps.clearTimer]
+ * @param {boolean} [deps.unrefTimers]
+ * @param {(sessionId:string, state:object)=>void} [deps.onChange] 门控状态变化回调（SSE 推送用）
+ */
+export function createStepGate({
+  getSettings,
+  shouldHoldSession,
+  isHeldByDeferrals = () => false,
+  isRootAgent = () => true,
+  pauseGate,
+  logger,
+  now = () => Date.now(),
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  unrefTimers = true,
+  onChange,
+} = {}) {
+  /** sessionId -> { sessionId, step, turn, since, resolve, timer, signal, onAbort } */
+  const holds = new Map()
+  /** 本峰内被用户手动跳过的会话 */
+  const bypass = new Set()
+  /** 用户手动点「暂停会话」但还没到 pre-step 边界的会话 */
+  const manualPause = new Set()
+
+  const warn = (m) => {
+    try {
+      logger?.warn?.(`[session-guard] ${m}`)
+    } catch {
+      /* 日志失败不影响门控 */
+    }
+  }
+  const info = (m) => {
+    try {
+      logger?.info?.(`[session-guard] ${m}`)
+    } catch {
+      /* ignore */
+    }
+  }
+
+  function readCfg() {
+    try {
+      const v = getSettings()
+      return v && typeof v === 'object' ? v : {}
+    } catch {
+      return {}
+    }
+  }
+
+  /** 通知状态变化（SSE 推送；异常不得影响门控）。 */
+  function emitChange(sessionId) {
+    if (typeof onChange !== 'function') return
+    try {
+      onChange(String(sessionId), state(sessionId))
+    } catch (e) {
+      warn(`step gate onChange failed: ${String(e && e.message || e)}`)
+    }
+  }
+
+  /** 摘掉一条挂起记录（不 resolve），幂等。 */
+  function detach(entry) {
+    if (!entry) return false
+    if (holds.get(entry.sessionId) === entry) holds.delete(entry.sessionId)
+    if (entry.timer !== null) {
+      try {
+        clearTimer(entry.timer)
+      } catch {
+        /* ignore */
+      }
+      entry.timer = null
+    }
+    if (entry.signal && entry.onAbort) {
+      try {
+        entry.signal.removeEventListener('abort', entry.onAbort)
+      } catch {
+        /* ignore */
+      }
+    }
+    entry.onAbort = null
+    return true
+  }
+
+  /**
+   * 释放一会话的挂起门。幂等：未挂起 → `{released:false}`。
+   * @param {string} sessionId
+   * @param {string} [reason] manual | off-peak | abort | timeout | pause | cancel | command | disposed
+   */
+  function release(sessionId, reason = 'manual') {
+    const id = String(sessionId)
+    const entry = holds.get(id)
+    if (entry === undefined) {
+      // 没挂起，但可能有未落地的手动暂停请求 → 一并撤销
+      if (manualPause.delete(id)) emitChange(id)
+      return { released: false, reason }
+    }
+    detach(entry)
+    manualPause.delete(id)
+    info(`step gate released (${reason}) for ${id} (step ${entry.step})`)
+    try {
+      entry.resolve({ released: true, reason })
+    } catch (e) {
+      warn(`step gate resolve failed: ${String(e && e.message || e)}`)
+    }
+    emitChange(id)
+    return { released: true, reason }
+  }
+
+  /** 释放全部挂起门（退峰 / 卸载）。返回被释放的会话 id 列表。 */
+  function releaseAll(reason = 'releaseAll') {
+    const ids = [...holds.keys()]
+    for (const id of ids) release(id, reason)
+    for (const id of [...manualPause]) {
+      manualPause.delete(id)
+      emitChange(id)
+    }
+    return ids
+  }
+
+  /**
+   * 用户手动请求暂停（「暂停会话」按钮 / `stepPause` RPC / 服务端口）。
+   * 不打断当前 step：在下一次 `agent/pre-step` 边界拉门（step 1 也拦）。
+   * 已挂起时幂等；同时撤销本峰 bypass（显式暂停优先）。
+   * @returns {{requested:boolean, held:boolean}}
+   */
+  function requestPause(sessionId) {
+    const id = String(sessionId)
+    bypass.delete(id)
+    if (holds.has(id)) return { requested: true, held: true }
+    manualPause.add(id)
+    info(`step gate manual pause requested for ${id}`)
+    emitChange(id)
+    return { requested: true, held: false }
+  }
+
+  /** 超时：释放 + 升级为 turn 级 force 暂停（F8）。 */
+  function escalate(sessionId) {
+    const id = String(sessionId)
+    release(id, 'timeout')
+    if (!pauseGate || typeof pauseGate.pause !== 'function') return
+    try {
+      const r = pauseGate.pause(id, { mode: 'force', reason: 'stop' })
+      if (r && typeof r.then === 'function') {
+        r.then(undefined, (e) => warn(`step gate escalation pause failed for ${id}: ${String(e && e.message || e)}`))
+      }
+    } catch (e) {
+      warn(`step gate escalation pause threw for ${id}: ${String(e && e.message || e)}`)
+    }
+  }
+
+  /** 本峰内跳过该会话（用户手动继续）。 */
+  function markBypass(sessionId) {
+    const id = String(sessionId)
+    manualPause.delete(id)
+    bypass.add(id)
+    emitChange(id)
+  }
+
+  function clearBypass(sessionId) {
+    const id = String(sessionId)
+    if (bypass.delete(id)) emitChange(id)
+  }
+
+  function clearAllBypass() {
+    bypass.clear()
+  }
+
+  /** 该会话的 step 门控状态。 */
+  function state(sessionId) {
+    const id = String(sessionId)
+    const entry = holds.get(id)
+    return {
+      held: entry !== undefined,
+      step: entry ? entry.step : null,
+      since: entry ? entry.since : null,
+      bypass: bypass.has(id),
+      /** 用户已请求暂停但还没到边界（按钮已应显示「继续会话」） */
+      manual: manualPause.has(id) || (entry !== undefined && entry.manual === true),
+    }
+  }
+
+  function heldIds() {
+    return [...holds.keys()]
+  }
+
+  /**
+   * `agent/pre-step` waterfall 主体：判定 → 拉门 → 释放后放行本 step。
+   * @param {{agent?:object, step?:number, turn?:number, signal?:AbortSignal, messages?:unknown[]}} payload
+   * @param {()=>Promise<unknown>} next
+   */
+  async function hold(payload, next) {
+    const pass = () => (typeof next === 'function' ? next() : Promise.resolve({ kind: 'enter', messages: [] }))
+    try {
+      const agent = payload && payload.agent
+      const id = String((agent && agent.id) ?? '')
+      if (id === '') return pass()
+
+      const cfg = readCfg()
+      let verdict
+      try {
+        verdict = shouldPause(cfg, new Date(now()))
+      } catch (e) {
+        warn(`step gate peak verdict failed for ${id}: ${String(e && e.message || e)}`)
+        verdict = { pause: false, reason: 'fail-open' }
+      }
+
+      let targetOk = true
+      if (typeof shouldHoldSession === 'function') {
+        try {
+          targetOk = shouldHoldSession(cfg, id) === true
+        } catch (e) {
+          warn(`step gate target verdict failed for ${id}: ${String(e && e.message || e)}`)
+          targetOk = false // fail-open 放行
+        }
+      }
+
+      let held = false
+      try {
+        held = isHeldByDeferrals(id) === true
+      } catch {
+        held = false
+      }
+
+      let rootFlag = true
+      try {
+        rootFlag = isRootAgent(agent) !== false
+      } catch {
+        rootFlag = true
+      }
+
+      const manual = manualPause.has(id)
+      const decision = decideStepHold({
+        cfg,
+        step: payload && payload.step,
+        isRoot: rootFlag,
+        pauseVerdict: verdict,
+        shouldHoldSession: () => targetOk,
+        isHeldByDeferrals: held,
+        bypassed: bypass.has(id),
+        alreadyHeld: holds.has(id),
+        manual,
+      })
+      if (!decision.hold) return pass()
+
+      const entry = {
+        sessionId: id,
+        step: Number(payload && payload.step),
+        turn: Number(payload && payload.turn),
+        since: now(),
+        resolve: null,
+        timer: null,
+        signal: (payload && payload.signal) || null,
+        onAbort: null,
+        manual,
+      }
+      const promise = new Promise((resolve) => {
+        entry.resolve = resolve
+      })
+      holds.set(id, entry)
+      emitChange(id)
+
+      // abort（agent.cancel / 冻结 / /pause / /cancel）→ 释放，让 loop 的 throwIfAborted 收尾
+      if (entry.signal && typeof entry.signal.addEventListener === 'function') {
+        entry.onAbort = () => release(id, 'abort')
+        try {
+          entry.signal.addEventListener('abort', entry.onAbort, { once: true })
+        } catch {
+          entry.onAbort = null
+        }
+        if (entry.signal.aborted === true) release(id, 'abort')
+      }
+
+      const rawTimeout = Number(cfg.stepGateTimeoutMs)
+      const timeoutMs = Number.isFinite(rawTimeout) && rawTimeout > 0 ? rawTimeout : DEFAULT_STEP_TIMEOUT_MS
+      entry.timer = setTimer(() => {
+        entry.timer = null
+        escalate(id)
+      }, timeoutMs)
+      if (unrefTimers && entry.timer && typeof entry.timer.unref === 'function') entry.timer.unref()
+
+      info(`step gate held for ${id} at step ${entry.step} (timeout ${timeoutMs}ms)`)
+      await promise
+      return pass()
+    } catch (e) {
+      // 门控自身异常 → fail-open 放行，绝不阻断回合
+      warn(`step gate failed open: ${String(e && e.message || e)}`)
+      return pass()
+    }
+  }
+
+  return {
+    hold,
+    release,
+    releaseAll,
+    requestPause,
+    escalate,
+    markBypass,
+    clearBypass,
+    clearAllBypass,
+    state,
+    heldIds,
+    /** 当前挂起门数（测试 / diag 用）。 */
+    _count: () => holds.size,
+    /** 本峰 bypass 集合（测试 / diag 用）。 */
+    _bypassed: () => [...bypass],
+    /** 待落地的手动暂停请求（测试 / diag 用）。 */
+    _manualPending: () => [...manualPause],
+  }
+}