agentworkshop 0.7.44 → 0.7.47

package/server/services/workshop/agents/harness-availability.ts

@@ -1,127 +1,127 @@
-/**
- * HarnessAvailability —— 执行引擎环境可用性探测(单一事实源)。
- *
- * 两个消费面共用本模块:
- *   - 前端选择面:GET /api/workshop/harnesses 的 available 字段(下拉禁用未安装项/仪表盘面板);
- *   - 执行前强校验:manager 的模板增改/克隆入 channel/实例改引擎/任务直发/lead 派发
- *     全部经 assertHarnessUsable,不可用直接 409,任务不再进入「起跑后失败」路径。
- *
- * 探测规则(与真实拉起同源,见 line-spawn.resolveExecutable):
- *   - 进程内引擎(mock/claude SDK):无外部 CLI,恒可用;
- *   - 进程型引擎(omp/opencode/codex/dsh):经 HarnessDef.probe 解析命令
- *     (实例 config.command 覆盖 → 运行时设置缺省),再按 PATH/PATHEXT(unix 加 X_OK)
- *     探测磁盘上的真实可执行文件;找不到 = 未安装。
- * 探测结果按「引擎+命令」缓存 30s(fs 探测廉价但热路径避抖);refresh=1 强制重探。
- */
-import { accessSync, constants, existsSync, statSync } from 'node:fs'
-import { join } from 'node:path'
-import { AppError } from '../../../utils/errors'
-import { resolveOnPath } from './adapters/line-spawn'
-import { HARNESS_REGISTRY, knownHarnesses } from './registry'
-
-export interface HarnessAvailability {
-  id: string
-  available: boolean
-  /** 进程内引擎(无外部 CLI,恒可用) */
-  inprocess: boolean
-  /** 进程型引擎:声明将拉起的命令(config 覆盖/设置缺省后) */
-  command: string | null
-  /** PATH 解析出的可执行文件绝对路径(未找到为 null) */
-  resolvedPath: string | null
-  /** 不可用原因(人话,可直接展示) */
-  error: string | null
-}
-
-const isPlainFile = (p: string): boolean => {
-  try {
-    return existsSync(p) && statSync(p).isFile()
-  }
-  catch {
-    return false
-  }
-}
-
-const isExecutableFile = (p: string): boolean => {
-  try {
-    accessSync(p, constants.X_OK)
-    return statSync(p).isFile()
-  }
-  catch {
-    return false
-  }
-}
-
-/** PATH 探测可执行文件;探测永不抛(坏 PATH 环境按未安装处理) */
-function probeExecutable(command: string): string | null {
-  if (!command) return null
-  // 显式路径(含目录分隔符或盘符)不再走 PATH
-  if (command.includes('/') || command.includes('\\') || /^[A-Za-z]:/.test(command)) {
-    return isPlainFile(command) ? command : null
-  }
-  if (process.platform === 'win32') return resolveOnPath(command)
-  for (const dir of (process.env.PATH ?? '').split(':').filter(Boolean)) {
-    const full = join(dir, command)
-    if (isExecutableFile(full)) return full
-  }
-  return null
-}
-
-const PROBE_TTL_MS = 30_000
-/** 缓存键 = 引擎+命令(命令不同探测结果不同,不能按引擎 id 独占) */
-const probeCache = new Map<string, { at: number, resolvedPath: string | null }>()
-
-export function checkHarnessAvailability(
-  harnessId: string,
-  config?: Record<string, unknown>,
-  opts?: { refresh?: boolean },
-): HarnessAvailability {
-  const def = HARNESS_REGISTRY[harnessId]
-  if (!def) {
-    return {
-      id: harnessId,
-      available: false,
-      inprocess: false,
-      command: null,
-      resolvedPath: null,
-      error: `未知 harness: ${harnessId}(可选 ${knownHarnesses().join('/')})`,
-    }
-  }
-  const probe = def.probe
-  if (!probe || probe.inprocess || !probe.command) {
-    return { id: harnessId, available: true, inprocess: true, command: null, resolvedPath: null, error: null }
-  }
-  const command = probe.command(config)
-  const key = `${harnessId}=${command}`
-  const cached = probeCache.get(key)
-  let resolvedPath: string | null
-  if (!opts?.refresh && cached && Date.now() - cached.at < PROBE_TTL_MS) {
-    resolvedPath = cached.resolvedPath
-  }
-  else {
-    resolvedPath = probeExecutable(command)
-    probeCache.set(key, { at: Date.now(), resolvedPath })
-  }
-  return {
-    id: harnessId,
-    available: resolvedPath !== null,
-    inprocess: false,
-    command,
-    resolvedPath,
-    error: resolvedPath ? null : `未找到可执行命令「${command}」:引擎 ${def.label} 未安装或不在 PATH 中`,
-  }
-}
-
-export function checkAllHarnessAvailability(opts?: { refresh?: boolean }): HarnessAvailability[] {
-  return Object.keys(HARNESS_REGISTRY).map(id => checkHarnessAvailability(id, undefined, opts))
-}
-
-/** 执行前强校验:未知 → 400 UNKNOWN_HARNESS;未安装 → 409 HARNESS_UNAVAILABLE(人话报错,前端可直接展示) */
-export function assertHarnessUsable(harness: string, config?: Record<string, unknown>): void {
-  if (!HARNESS_REGISTRY[harness]) {
-    throw new AppError(400, 'UNKNOWN_HARNESS', `未知 harness: ${harness}(可选 ${knownHarnesses().join('/')})`)
-  }
-  const a = checkHarnessAvailability(harness, config)
-  if (!a.available) {
-    throw new AppError(409, 'HARNESS_UNAVAILABLE', a.error ?? `执行引擎 ${harness} 不可用`)
-  }
-}
+/**
+ * HarnessAvailability —— 执行引擎环境可用性探测(单一事实源)。
+ *
+ * 两个消费面共用本模块:
+ *   - 前端选择面:GET /api/workshop/harnesses 的 available 字段(下拉禁用未安装项/仪表盘面板);
+ *   - 执行前强校验:manager 的模板增改/克隆入 channel/实例改引擎/任务直发/lead 派发
+ *     全部经 assertHarnessUsable,不可用直接 409,任务不再进入「起跑后失败」路径。
+ *
+ * 探测规则(与真实拉起同源,见 line-spawn.resolveExecutable):
+ *   - 进程内引擎(mock/claude SDK):无外部 CLI,恒可用;
+ *   - 进程型引擎(omp/opencode/codex/dsh):经 HarnessDef.probe 解析命令
+ *     (实例 config.command 覆盖 → 运行时设置缺省),再按 PATH/PATHEXT(unix 加 X_OK)
+ *     探测磁盘上的真实可执行文件;找不到 = 未安装。
+ * 探测结果按「引擎+命令」缓存 30s(fs 探测廉价但热路径避抖);refresh=1 强制重探。
+ */
+import { accessSync, constants, existsSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { AppError } from '../../../utils/errors'
+import { resolveOnPath } from './adapters/line-spawn'
+import { HARNESS_REGISTRY, knownHarnesses } from './registry'
+
+export interface HarnessAvailability {
+  id: string
+  available: boolean
+  /** 进程内引擎(无外部 CLI,恒可用) */
+  inprocess: boolean
+  /** 进程型引擎:声明将拉起的命令(config 覆盖/设置缺省后) */
+  command: string | null
+  /** PATH 解析出的可执行文件绝对路径(未找到为 null) */
+  resolvedPath: string | null
+  /** 不可用原因(人话,可直接展示) */
+  error: string | null
+}
+
+const isPlainFile = (p: string): boolean => {
+  try {
+    return existsSync(p) && statSync(p).isFile()
+  }
+  catch {
+    return false
+  }
+}
+
+const isExecutableFile = (p: string): boolean => {
+  try {
+    accessSync(p, constants.X_OK)
+    return statSync(p).isFile()
+  }
+  catch {
+    return false
+  }
+}
+
+/** PATH 探测可执行文件;探测永不抛(坏 PATH 环境按未安装处理) */
+function probeExecutable(command: string): string | null {
+  if (!command) return null
+  // 显式路径(含目录分隔符或盘符)不再走 PATH
+  if (command.includes('/') || command.includes('\\') || /^[A-Za-z]:/.test(command)) {
+    return isPlainFile(command) ? command : null
+  }
+  if (process.platform === 'win32') return resolveOnPath(command)
+  for (const dir of (process.env.PATH ?? process.env.Path ?? '').split(':').filter(Boolean)) {
+    const full = join(dir, command)
+    if (isExecutableFile(full)) return full
+  }
+  return null
+}
+
+const PROBE_TTL_MS = 30_000
+/** 缓存键 = 引擎+命令(命令不同探测结果不同,不能按引擎 id 独占) */
+const probeCache = new Map<string, { at: number, resolvedPath: string | null }>()
+
+export function checkHarnessAvailability(
+  harnessId: string,
+  config?: Record<string, unknown>,
+  opts?: { refresh?: boolean },
+): HarnessAvailability {
+  const def = HARNESS_REGISTRY[harnessId]
+  if (!def) {
+    return {
+      id: harnessId,
+      available: false,
+      inprocess: false,
+      command: null,
+      resolvedPath: null,
+      error: `未知 harness: ${harnessId}(可选 ${knownHarnesses().join('/')})`,
+    }
+  }
+  const probe = def.probe
+  if (!probe || probe.inprocess || !probe.command) {
+    return { id: harnessId, available: true, inprocess: true, command: null, resolvedPath: null, error: null }
+  }
+  const command = probe.command(config)
+  const key = `${harnessId}=${command}`
+  const cached = probeCache.get(key)
+  let resolvedPath: string | null
+  if (!opts?.refresh && cached && Date.now() - cached.at < PROBE_TTL_MS) {
+    resolvedPath = cached.resolvedPath
+  }
+  else {
+    resolvedPath = probeExecutable(command)
+    probeCache.set(key, { at: Date.now(), resolvedPath })
+  }
+  return {
+    id: harnessId,
+    available: resolvedPath !== null,
+    inprocess: false,
+    command,
+    resolvedPath,
+    error: resolvedPath ? null : `未找到可执行命令「${command}」:引擎 ${def.label} 未安装或不在 PATH 中`,
+  }
+}
+
+export function checkAllHarnessAvailability(opts?: { refresh?: boolean }): HarnessAvailability[] {
+  return Object.keys(HARNESS_REGISTRY).map(id => checkHarnessAvailability(id, undefined, opts))
+}
+
+/** 执行前强校验:未知 → 400 UNKNOWN_HARNESS;未安装 → 409 HARNESS_UNAVAILABLE(人话报错,前端可直接展示) */
+export function assertHarnessUsable(harness: string, config?: Record<string, unknown>): void {
+  if (!HARNESS_REGISTRY[harness]) {
+    throw new AppError(400, 'UNKNOWN_HARNESS', `未知 harness: ${harness}(可选 ${knownHarnesses().join('/')})`)
+  }
+  const a = checkHarnessAvailability(harness, config)
+  if (!a.available) {
+    throw new AppError(409, 'HARNESS_UNAVAILABLE', a.error ?? `执行引擎 ${harness} 不可用`)
+  }
+}

package/server/services/workshop/agents/harness-terminal/api.ts

@@ -0,0 +1,197 @@
+/**
+ * 对外 API:挂接/摘除 tap、退出标记、查询与快照
+ * (由 server/services/workshop/agents/harness-terminal.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { OmpRpcClient } from '../adapters/omp-rpc-client'
+import type { TermFrame, TermSessionMeta, TerminalHitlDialog } from '../../../../../shared/terminal-protocol'
+import type { TerminalSession } from './shared'
+import { broadcastState, flushNow, handleUiRequest, pushFrame, setState } from './session'
+import { clearParkTimer } from './park'
+import { getHitlRegistry } from '../hitl-registry'
+import { sanitizeFrame } from './sanitize'
+import { sessions } from './shared'
+
+// ===== 对外 API =====
+
+/**
+ * 给已 spawn 的 omp 客户端挂终端镜像 tap(omp-agent ensureClient 调用)。
+ * 同 pid 重复 attach(进程复用)幂等:先卸旧 tap。
+ */
+export function attachTerminalTap(
+  client: OmpRpcClient,
+  meta: { pid: number, harness: string, agentId: string, channelId: string, name: string, role: 'lead' | 'worker' },
+): void {
+  detachTerminalTap(meta.pid)
+  const session: TerminalSession = {
+    meta: {
+      pid: meta.pid,
+      harness: meta.harness,
+      agentId: meta.agentId,
+      channelId: meta.channelId,
+      name: meta.name,
+      role: meta.role,
+      startedAt: Date.now(),
+    },
+    client,
+    seq: 0,
+    ring: [],
+    listeners: new Set(),
+    running: false,
+    streaming: false,
+    alive: true,
+    exitCode: null,
+    pendingHitl: null,
+    parkTimer: null,
+    unsubRaw: null,
+    batch: [],
+    batchTimer: null,
+  }
+
+  session.unsubRaw = client.onRawFrame((frame) => {
+    const type = frame.type as string
+    // 回合/流式状态机(输入路由依据)
+    if (type === 'agent_start') {
+      setState(session, { running: true })
+    }
+    if (type === 'message_update') {
+      setState(session, { running: true, streaming: true })
+    }
+    if (type === 'message_end' || type === 'turn_end') {
+      setState(session, { streaming: false })
+    }
+    if (type === 'agent_end' && frame.isTerminal !== false) {
+      setState(session, { running: false, streaming: false })
+    }
+    if (type === 'extension_ui_request') {
+      handleUiRequest(session, frame)
+    }
+    pushFrame(session, sanitizeFrame(frame))
+  })
+
+  sessions.set(meta.pid, session)
+  pushFrame(session, {
+    type: '__terminal_notice',
+    level: 'info',
+    message: `终端镜像已接入 omp PID ${meta.pid}(${meta.role} ${meta.name}@${meta.channelId?.slice(0, 8) ?? '?'})`,
+  })
+}
+
+/** 卸载 tap(客户端 dispose / 进程复用;保留缓冲供事后查看) */
+export function detachTerminalTap(pid: number): void {
+  const session = sessions.get(pid)
+  if (!session) return
+  session.unsubRaw?.()
+  session.unsubRaw = null
+  session.client = null as unknown as OmpRpcClient
+}
+
+/** 进程退出标记(exit 事件 / 强杀路径共用;幂等,缓冲保留) */
+export function markTerminalSessionExit(pid: number, exitCode: number | null): void {
+  const session = sessions.get(pid)
+  if (!session || !session.alive) return
+  detachTerminalTap(pid)
+  session.alive = false
+  session.exitCode = exitCode
+  if (session.pendingHitl) {
+    getHitlRegistry().resolve('omp-dialog', session.pendingHitl.id, 'cancelled')
+    session.pendingHitl = null
+  }
+  clearParkTimer(session)
+  session.running = false
+  session.streaming = false
+  flushNow(session)
+  pushFrame(session, {
+    type: '__terminal_notice',
+    level: 'error',
+    message: `omp 进程已退出(code=${exitCode ?? '?'})`,
+  })
+  broadcastState(session)
+}
+
+export function hasTerminalSession(pid: number): boolean {
+  return sessions.has(pid)
+}
+
+/**
+ * 按 agent 解析其当前存活的终端会话 pid(omp lazy spawn:进程随首个任务启动,
+ * 未 spawn 时返回 null)。同 agent 多进程残留时取最新 attach 的。
+ */
+export function findLiveTerminalPidByAgent(channelId: string, agentId: string): number | null {
+  let best: { pid: number, at: number } | null = null
+  for (const [pid, s] of sessions) {
+    if (!s.alive || s.meta.agentId !== agentId) continue
+    if (channelId && s.meta.channelId !== channelId) continue
+    if (!best || s.meta.startedAt > best.at) best = { pid, at: s.meta.startedAt }
+  }
+  return best?.pid ?? null
+}
+
+/** 终端会话轻量视图(lanes / 监控面轮询用) */
+export interface TerminalSessionView {
+  pid: number
+  agentId: string | null
+  channelId: string | null
+  name: string | null
+  role: 'lead' | 'worker' | null
+  harness: string
+  alive: boolean
+  running: boolean
+  streaming: boolean
+  startedAt: number
+}
+
+/** 全部(或指定 channel 的)终端会话列表 */
+export function listTerminalSessions(channelId?: string): TerminalSessionView[] {
+  return [...sessions.values()]
+    .filter(s => !channelId || s.meta.channelId === channelId)
+    .map(s => ({
+      pid: s.meta.pid,
+      agentId: s.meta.agentId,
+      channelId: s.meta.channelId,
+      name: s.meta.name,
+      role: s.meta.role,
+      harness: s.meta.harness,
+      alive: s.alive,
+      running: s.running,
+      streaming: s.streaming,
+      startedAt: s.meta.startedAt,
+    }))
+}
+
+/** 惰性清理:退出超过 retentionMs 且无订阅者的会话(防泄漏;monitor 快照时调用) */
+export function sweepTerminalSessions(retentionMs = 60_000): void {
+  const now = Date.now()
+  for (const [pid, s] of sessions) {
+    if (!s.alive) {
+      const lastAt = s.ring.length > 0 ? Date.parse(s.ring[s.ring.length - 1]!.at) : s.meta.startedAt
+      if (Number.isFinite(lastAt) && now - lastAt > retentionMs && s.listeners.size === 0) {
+        sessions.delete(pid)
+      }
+    }
+  }
+}
+
+/** 快照式读取:meta + 状态 + 重放缓冲(WS open 用) */
+export function terminalSessionSnapshot(pid: number): {
+  meta: TermSessionMeta
+  alive: boolean
+  streaming: boolean
+  running: boolean
+  lastSeq: number
+  hitl: TerminalHitlDialog | null
+  replay: TermFrame[]
+} | null {
+  const session = sessions.get(pid)
+  if (!session) return null
+  return {
+    meta: session.meta,
+    alive: session.alive,
+    streaming: session.streaming,
+    running: session.running,
+    lastSeq: session.seq,
+    hitl: session.pendingHitl,
+    replay: [...session.ring],
+  }
+}
+
+/** WS 订阅(先回放缓冲,再接实时流) */

package/server/services/workshop/agents/harness-terminal/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Harness 终端会话 tap:帧净化 / 会话内部状态 / park 倒计时 / 对外 API 与 IO
+ *
+ * 由原单文件按职责拆分而来;此处保持**原文件的公开 API 与 import 路径不变**
+ * (目录 index 解析),外部调用方无需改动。
+ *
+ * 模块划分:
+ *   shared.ts              模块头 / 会话与 hub 状态类型 / 全局 hub
+ *   sanitize.ts            帧净化:内容抽取 / 截断 / 预览 / 敏感字段清洗
+ *   session.ts             会话内部:入帧缓冲 / 定时刷帧 / 广播 / 状态与 HITL 视图
+ *   park.ts                park 倒计时(无人观看挂起 / 接入暂停 / 待办过期)
+ *   api.ts                 对外 API:挂接/摘除 tap、退出标记、查询与快照
+ *   io.ts                  对外 IO:订阅 / 输入 / 中断 / UI 应答
+ */
+export { attachTerminalTap, detachTerminalTap, markTerminalSessionExit, hasTerminalSession, findLiveTerminalPidByAgent, listTerminalSessions, sweepTerminalSessions, terminalSessionSnapshot } from './api'
+export type { TerminalSessionView } from './api'
+export { subscribeTerminal, sendTerminalInput, abortTerminal, respondTerminalUi } from './io'

package/server/services/workshop/agents/harness-terminal/io.ts

@@ -0,0 +1,120 @@
+/**
+ * 对外 IO:订阅 / 输入 / 中断 / UI 应答
+ * (由 server/services/workshop/agents/harness-terminal.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { TerminalServerMessage } from '../../../../../shared/terminal-protocol'
+import type { TerminalSession } from './shared'
+import { armParkTimer, clearParkTimer } from './park'
+import { getHitlRegistry } from '../hitl-registry'
+import { log, sessions } from './shared'
+import { preview } from './sanitize'
+import { pushFrame } from './session'
+
+export function subscribeTerminal(
+  pid: number,
+  listener: (msg: TerminalServerMessage) => void,
+): (() => void) | null {
+  const session = sessions.get(pid)
+  if (!session) return null
+  const wasEmpty = session.listeners.size === 0
+  session.listeners.add(listener)
+  if (wasEmpty && session.pendingHitl) {
+    // 有人观看:暂停 park 倒计时(真 HITL 等待无上限;观看者离开后重新计时)
+    clearParkTimer(session)
+    getHitlRegistry().setParkDeadline('omp-dialog', session.pendingHitl.id, null)
+  }
+  return () => {
+    session.listeners.delete(listener)
+    // 订阅者归零时若还有待应答对话框:park 倒计时(超时自动取消;不再是秒取消)
+    if (session.listeners.size === 0 && session.pendingHitl) armParkTimer(session)
+  }
+}
+
+/**
+ * Human 文本输入(可靠注入,与 OmpRpcAgentImpl.steer 同兜底链):
+ *  - 空闲/回合已结束 → follow_up 开新回合;
+ *  - 回合流式中 → steer 同轮注入;
+ *  - 回合已开始但尚未输出(prompt 排队窗口)→ 短等输出开始再 steer,
+ *    期间回合结束则转 follow_up。
+ */
+export async function sendTerminalInput(pid: number, text: string): Promise<void> {
+  const session = sessions.get(pid)
+  if (!session || !session.alive) throw new Error('终端会话不可用(进程未启动或已退出)')
+  pushFrame(session, { type: '__human_input', text })
+  try {
+    if (session.streaming) {
+      await session.client.send({ type: 'steer', message: text })
+      return
+    }
+    if (session.running) {
+      const deadline = Date.now() + 8_000
+      while (Date.now() < deadline && session.running && !session.streaming) {
+        const { promise, resolve } = Promise.withResolvers()
+        setTimeout(resolve, 150)
+        await promise
+      }
+      if (session.streaming && session.running) {
+        await session.client.send({ type: 'steer', message: text })
+        return
+      }
+    }
+    await session.client.send({ type: 'follow_up', message: text })
+  }
+  catch (err) {
+    pushFrame(session, {
+      type: '__terminal_notice',
+      level: 'error',
+      message: `输入注入失败: ${err instanceof Error ? err.message : String(err)}`,
+    })
+    throw err
+  }
+}
+
+/** 中止当前回合(omp abort) */
+export async function abortTerminal(pid: number): Promise<void> {
+  const session = sessions.get(pid)
+  if (!session || !session.alive) throw new Error('终端会话不可用')
+  pushFrame(session, { type: '__terminal_notice', level: 'warning', message: '人类中止了当前回合(abort)' })
+  await session.client.send({ type: 'abort' })
+}
+
+/** HITL 对话框应答(extension_ui_response side-channel 直写 stdin) */
+export function respondTerminalUi(
+  pid: number,
+  response: { id: string, value?: string, confirmed?: boolean, cancelled?: boolean },
+): void {
+  const session = sessions.get(pid)
+  if (!session) throw new Error('终端会话不可用')
+  respondUi(session, response)
+  pushFrame(session, {
+    type: '__terminal_notice',
+    level: 'info',
+    message: `HITL 应答已提交(${response.cancelled ? '取消' : response.confirmed !== undefined ? String(response.confirmed) : `"${preview(response.value ?? '', 80)}"`})`,
+  })
+}
+
+export function respondUi(
+  session: TerminalSession,
+  response: { id: string, value?: string, confirmed?: boolean, cancelled?: boolean },
+): void {
+  if (session.pendingHitl && session.pendingHitl.id === response.id) session.pendingHitl = null
+  clearParkTimer(session)
+  const frame: Record<string, unknown> = { type: 'extension_ui_response', id: response.id }
+  if (response.cancelled) {
+    frame.cancelled = true
+  }
+  else if (response.confirmed !== undefined) {
+    frame.confirmed = response.confirmed
+  }
+  else {
+    frame.value = response.value ?? ''
+  }
+  try {
+    session.client.writeRaw(frame)
+  }
+  catch (err) {
+    log.error(`[harness-terminal] extension_ui_response 写入失败(pid=${session.meta.pid}):`, err)
+  }
+  // 全局待办落定(expired 收敛路径已先行 resolve,此处幂等 no-op)
+  getHitlRegistry().resolve('omp-dialog', response.id, response.cancelled ? 'cancelled' : 'answered')
+}

package/server/services/workshop/agents/harness-terminal/park.ts

@@ -0,0 +1,55 @@
+/**
+ * park 倒计时(无人观看挂起 / 接入暂停 / 待办过期)
+ * (由 server/services/workshop/agents/harness-terminal.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { TerminalSession } from './shared'
+import { getHitlRegistry } from '../hitl-registry'
+import { pushFrame } from './session'
+import { respondUi } from './io'
+import { securityHitlTimeoutMs } from '../../settings'
+
+// ===== park 倒计时(无人观看时挂起等待;有人接入暂停) =====
+
+/** 零订阅 park 窗口(security.hitl_timeout_ms;0 = 恢复旧的"无人即秒取消") */
+export const HITL_PARK_MS = (): number => securityHitlTimeoutMs()
+
+export function clearParkTimer(session: TerminalSession): void {
+  if (session.parkTimer) {
+    clearTimeout(session.parkTimer)
+    session.parkTimer = null
+  }
+}
+
+/** 进入 park(仅零订阅且有待答对话框时生效;TTL<=0 立即取消 = 旧行为) */
+export function armParkTimer(session: TerminalSession): void {
+  clearParkTimer(session)
+  if (!session.pendingHitl || session.listeners.size > 0) return
+  const ttl = HITL_PARK_MS()
+  if (ttl <= 0) {
+    expirePendingHitl(session, true)
+    return
+  }
+  getHitlRegistry().setParkDeadline('omp-dialog', session.pendingHitl.id, new Date(Date.now() + ttl).toISOString())
+  session.parkTimer = setTimeout(() => {
+    session.parkTimer = null
+    if (session.pendingHitl && session.listeners.size === 0) expirePendingHitl(session)
+  }, ttl)
+  session.parkTimer.unref?.()
+}
+
+/** park 到期(或 TTL=0 立即):超时收敛 —— 先落定 expired,再走 cancelled 应答写 omp stdin */
+export function expirePendingHitl(session: TerminalSession, immediate = false): void {
+  const hitl = session.pendingHitl
+  if (!hitl) return
+  session.pendingHitl = null
+  clearParkTimer(session)
+  getHitlRegistry().resolve('omp-dialog', hitl.id, 'expired')
+  respondUi(session, { id: hitl.id, cancelled: true })
+  pushFrame(session, {
+    type: '__terminal_notice',
+    level: 'warning',
+    message: immediate
+      ? `HITL 对话框(${hitl.method} "${hitl.title.slice(0, 40)}")无人接入,已自动取消`
+      : `HITL 对话框(${hitl.method} "${hitl.title.slice(0, 40)}")park 超时无人处理,已自动取消`,
+  })
+}