@twinsearth/dsh-master 0.0.0-stage → 3.2.9

package/src/superagent/pr-delivery.ts

@@ -0,0 +1,308 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+
+/**
+ * PR 交付通道（v3.2.5）。
+ *
+ * 安全边界：**Worker 永不持有 push 凭据**。分支必须已由宿主/分身 git 凭据推送到远端；
+ * 本模块只在拿到 `{branch, title, body}` 后用宿主配置的 token 调用 GitHub API 创建 PR，
+ * 并可用 `githubContentsPush()` 让宿主自己把文件推进一个新分支（token 只在宿主进程内）。
+ */
+
+const DEFAULT_API = 'https://api.github.com'
+const MAX_FILES = 30
+const MAX_TOTAL_BYTES = 2 * 1024 * 1024
+const PROTECTED = ['main', 'master', 'trunk', 'release', 'production', 'stable', 'develop']
+
+/** 统一读取响应体文本：真实 fetch 有 text()，测试替身/异常实现可能没有。 */
+async function readBody(response) {
+  try {
+    if (response && typeof response.text === 'function') return await response.text()
+    if (response && typeof response.json === 'function') return JSON.stringify(await response.json())
+  } catch { /* 读取失败按空处理 */ }
+  return ''
+}
+
+function trim(value) {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function splitRepo(repo) {
+  const text = trim(repo)
+  const parts = text.split('/')
+  if (parts.length !== 2 || !parts[0] || !parts[1]) return null
+  return { owner: parts[0], name: parts[1] }
+}
+
+/**
+ * @param {{token?:string, repo?:string, apiBase?:string, baseBranch?:string, fetchImpl?:Function, tokenHeader?:'bearer'|'token'}} [options]
+ */
+export function createPrDelivery(options = {}) {
+  const token = trim(options.token)
+  const repo = trim(options.repo)
+  const apiBase = (trim(options.apiBase) || DEFAULT_API).replace(/\/+$/, '')
+  const baseBranch = trim(options.baseBranch) || 'main'
+  const rawFetch = options.fetchImpl ?? fetch
+  const requestTimeoutMs = Math.max(20, Number(options.requestTimeoutMs ?? 15_000) || 15_000)
+  const fetchImpl = async (url, init = {}) => {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), requestTimeoutMs)
+    timer.unref?.()
+    try { return await rawFetch(url, { ...init, signal: controller.signal }) }
+    finally { clearTimeout(timer) }
+  }
+  const repoParts = splitRepo(repo)
+  const enabled = Boolean(token) && repoParts !== null
+
+  const headersOf = () => ({
+    'content-type': 'application/json',
+    accept: 'application/vnd.github+json',
+    authorization: `Bearer ${token}`,
+    'user-agent': 'dsh-master-router',
+  })
+
+
+  const branchError = (value, { allowProtected = false } = {}) => {
+    const name = trim(value)
+    if (!name || name.length > 200) return 'pr-branch-invalid'
+    if (name.includes(':') || name.startsWith('/') || name.endsWith('/') || name.includes('..') || name.includes('//')) return 'pr-branch-invalid'
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(name) || /[@~^\s?*\[\\]/.test(name) || name.endsWith('.lock')) return 'pr-branch-invalid'
+    if (!allowProtected && isProtectedBranch(name)) return 'pr-protected-branch'
+    return ''
+  }
+
+  const create = async (input = {}) => {
+    if (!enabled) return { ok: false, code: 'pr-disabled', error: 'github token/repo not configured' }
+    const branch = trim(input.branch)
+    const title = trim(input.title)
+    if (!branch) return { ok: false, code: 'pr-branch-required', error: 'branch must already be pushed' }
+    if (!title) return { ok: false, code: 'pr-title-required', error: 'title is required' }
+    const headError = branchError(branch)
+    if (headError) return { ok: false, code: headError, error: 'invalid or protected head branch' }
+    const base = trim(input.base) || baseBranch
+    if (isProtectedBranch(base) === false) return { ok: false, code: 'pr-base-not-trunk', error: 'base must be a protected trunk branch' }
+    try {
+      const response = await fetchImpl(`${apiBase}/repos/${repoParts.owner}/${repoParts.name}/pulls`, {
+        method: 'POST',
+        headers: headersOf(),
+        body: JSON.stringify({
+          title: title.slice(0, 200),
+          body: String(input.body ?? '').slice(0, 20_000),
+          head: branch,
+          base,
+          draft: input.draft === true,
+        }),
+      })
+      const text = await readBody(response)
+      if (!response.ok) {
+        return { ok: false, code: `pr-http-${response.status}`, error: text.slice(0, 200) }
+      }
+      let parsed = {}
+      try { parsed = JSON.parse(text) } catch { /* 保留兜底 */ }
+      return { ok: true, url: String(parsed.html_url ?? ''), number: Number(parsed.number ?? 0) }
+    } catch (error) {
+      return { ok: false, code: 'pr-network-error', error: String(error instanceof Error ? error.message : error) }
+    }
+  }
+
+  /**
+   * 宿主侧推送单个文件到新分支（Worker 没有凭据，只有宿主能调用）。
+   * @param {{branch:string, path:string, content:string, message?:string, base?:string}} input
+   */
+  const pushFile = async (input = {}) => {
+    if (!enabled) return { ok: false, code: 'pr-disabled', error: 'github token/repo not configured' }
+    const branch = trim(input.branch)
+    const filePath = trim(input.path)
+    if (!branch || !filePath) return { ok: false, code: 'push-input-invalid', error: 'branch and path are required' }
+    const headError = branchError(branch)
+    if (headError) return { ok: false, code: headError, error: 'invalid or protected push branch' }
+    const checkedPath = sanitizeRepoPath(filePath)
+    if (!checkedPath.ok) return { ok: false, code: checkedPath.code, error: 'path is outside the repository allowlist' }
+    try {
+      const base = trim(input.base) || baseBranch
+      const refResponse = await fetchImpl(`${apiBase}/repos/${repoParts.owner}/${repoParts.name}/git/ref/heads/${encodeURIComponent(base)}`, { headers: headersOf() })
+      if (!refResponse.ok) return { ok: false, code: 'push-base-missing', error: `base branch ${base} not readable` }
+      const ref = await refResponse.json()
+      const baseSha = String(ref?.object?.sha ?? '')
+      if (!baseSha) return { ok: false, code: 'push-base-sha-missing', error: 'base sha not found' }
+
+      const branchRef = await fetchImpl(`${apiBase}/repos/${repoParts.owner}/${repoParts.name}/git/ref/heads/${encodeURIComponent(branch)}`, { headers: headersOf() })
+      if (!branchRef.ok) {
+        const created = await fetchImpl(`${apiBase}/repos/${repoParts.owner}/${repoParts.name}/git/refs`, {
+          method: 'POST', headers: headersOf(), body: JSON.stringify({ ref: `refs/heads/${branch}`, sha: baseSha }),
+        })
+        if (!created.ok) {
+          const detail = await readBody(created)
+          return { ok: false, code: 'push-branch-create-failed', error: detail.slice(0, 200) }
+        }
+      }
+      const put = await fetchImpl(`${apiBase}/repos/${repoParts.owner}/${repoParts.name}/contents/${checkedPath.path.split('/').map(encodeURIComponent).join('/')}`, {
+        method: 'PUT',
+        headers: headersOf(),
+        body: JSON.stringify({
+          message: trim(input.message) || `chore: update ${filePath}`,
+          content: Buffer.from(String(input.content ?? ''), 'utf8').toString('base64'),
+          branch,
+        }),
+      })
+      const putText = await readBody(put)
+      if (!put.ok) return { ok: false, code: `push-http-${put.status}`, error: putText.slice(0, 200) }
+      return { ok: true, branch, path: filePath }
+    } catch (error) {
+      return { ok: false, code: 'push-network-error', error: String(error instanceof Error ? error.message : error) }
+    }
+  }
+
+  /** 受保护分支（不能作为 PR 的 head；也不能作为推送目标）。 */
+  const isProtectedBranch = (name) => PROTECTED.includes(String(trim(name)).toLowerCase())
+
+  /**
+   * 分支命名策略（v3.2.7）：`<prefix>/<source>-<ticket>-<hash8>`。
+   *   * prefix 默认 `superagent`，可配置；
+   *   * source/ticket 做字符白名单 + 长度截断，避免注入或超长 ref；
+   *   * 末尾 8 位 hash 保证同一 ticket 的重复交付落到同一分支（幂等）。
+   */
+  const branchForTicket = (ticketId, source) => {
+    const prefix = (trim(options.branchPrefix) || 'superagent').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '')
+    const safe = (value, max) => String(trim(value) || 'na').toLowerCase().replace(/[^A-Za-z0-9._-]+/g, '-').replace(/-{2,}/g, '-').replace(/^[-.]+|[-.]+$/g, '').slice(0, max) || 'na'
+    const sourceToken = safe(String(source ?? '').split(/[:#/]/)[0], 16)
+    const ticket = safe(ticketId, 40)
+    const hash = String(options.hashOf ? options.hashOf(String(ticketId ?? '')) : ticket).slice(0, 8).replace(/[^A-Za-z0-9]/g, '0')
+    const branch = `${prefix}/${sourceToken}-${ticket}-${hash}`
+    return branch
+  }
+
+  /** 仓库内路径白名单：禁止绝对路径、..、.git、CI 工作流。 */
+  const sanitizeRepoPath = (value) => {
+    if (/\u0000-\u001f/.test(String(value ?? ''))) return { ok: false, code: 'path-control' }
+    const raw = String(trim(value) ?? '').replace(/\\/g, '/')
+    if (!raw) return { ok: false, code: 'path-empty' }
+    if (raw.startsWith('/') || /^[A-Za-z]:/.test(raw)) return { ok: false, code: 'path-absolute' }
+    const parts = raw.split('/')
+    if (parts.some((part) => part === '..' || part === '' || part === '.')) return { ok: false, code: 'path-traversal' }
+    if (parts.some((part) => part.toLowerCase() === '.git')) return { ok: false, code: 'path-git' }
+    if (parts[0] === '.github' && parts[1] === 'workflows') return { ok: false, code: 'path-workflow' }
+    return { ok: true, path: parts.join('/') }
+  }
+
+  const refSha = async (branch) => {
+    const res = await fetchImpl(`${apiBase}/repos/${repoParts.owner}/${repoParts.name}/git/ref/heads/${encodeURIComponent(branch)}`, { headers: headersOf() })
+    if (!res.ok) return null
+    try { const body = await res.json(); return String(body?.object?.sha ?? '') || null } catch { return null }
+  }
+
+  const ensureBranch = async (branch, base) => {
+    const sha = await refSha(branch)
+    if (sha) return { ok: true, created: false }
+    const baseSha = await refSha(base)
+    if (!baseSha) return { ok: false, code: 'push-base-missing', error: `base branch ${base} not readable` }
+    const created = await fetchImpl(`${apiBase}/repos/${repoParts.owner}/${repoParts.name}/git/refs`, {
+      method: 'POST', headers: headersOf(), body: JSON.stringify({ ref: `refs/heads/${branch}`, sha: baseSha }),
+    })
+    if (!created.ok) {
+      const detail = await readBody(created)
+      // 并发场景下可能已被创建：再查一次
+      if (await refSha(branch)) return { ok: true, created: false }
+      return { ok: false, code: 'push-branch-create-failed', error: detail.slice(0, 200) }
+    }
+    return { ok: true, created: true }
+  }
+
+  /** 幂等 PR：先查 open PR（head=branch），已存在则复用。 */
+  const findOpenPr = async (branch) => {
+    const res = await fetchImpl(`${apiBase}/repos/${repoParts.owner}/${repoParts.name}/pulls?state=open&head=${encodeURIComponent(`${repoParts.owner}:${branch}`)}`, { headers: headersOf() })
+    if (!res.ok) return null
+    try {
+      const list = await res.json()
+      const item = Array.isArray(list) ? list[0] : null
+      return item ? { url: String(item.html_url ?? ''), number: Number(item.number ?? 0) } : null
+    } catch { return null }
+  }
+
+  const putFile = async (branch, repoPath, content, message) => {
+    const encoded = repoPath.split('/').map(encodeURIComponent).join('/')
+    // 已存在的文件必须带 sha，否则 GitHub 返回 422
+    const existing = await fetchImpl(`${apiBase}/repos/${repoParts.owner}/${repoParts.name}/contents/${encoded}?ref=${encodeURIComponent(branch)}`, { headers: headersOf() })
+    let sha = ''
+    if (existing.ok) {
+      try { sha = String((await existing.json())?.sha ?? '') } catch { sha = '' }
+    }
+    const put = await fetchImpl(`${apiBase}/repos/${repoParts.owner}/${repoParts.name}/contents/${encoded}`, {
+      method: 'PUT',
+      headers: headersOf(),
+      body: JSON.stringify({
+        message: trim(message) || `chore: ${repoPath}`,
+        content: Buffer.from(String(content ?? ''), 'utf8').toString('base64'),
+        branch,
+        ...(sha ? { sha } : {}),
+      }),
+    })
+    const detail = await readBody(put)
+    if (!put.ok) return { ok: false, code: `push-http-${put.status}`, error: detail.slice(0, 200) }
+    return { ok: true }
+  }
+
+  /**
+   * 自动交付（v3.2.7）：**分支由宿主推送**（Worker 无凭据）→ 建分支 → 逐文件提交 → 开 PR。
+   * 幂等：分支复用、已存在 open PR 直接复用，不重复开单。
+   *
+   * @param {{ticketId:string, source?:string, files:Array<{path:string, content:string}>,
+   *         title?:string, body?:string, base?:string, branch?:string, draft?:boolean}} input
+   */
+  const deliver = async (input = {}) => {
+    if (!enabled) return { ok: false, code: 'pr-disabled', error: 'github token/repo not configured' }
+    const files = Array.isArray(input.files) ? input.files : []
+    if (files.length === 0) return { ok: false, code: 'pr-no-files', error: 'no changed files to push' }
+    if (files.length > MAX_FILES) return { ok: false, code: 'pr-too-many-files', error: `${files.length} files exceeds ${MAX_FILES}` }
+    const branch = trim(input.branch) || branchForTicket(input.ticketId, input.source)
+    const headError = branchError(branch)
+    if (headError) return { ok: false, code: headError, error: 'invalid or protected delivery branch' }
+    const base = trim(input.base) || baseBranch
+    if (isProtectedBranch(base) === false) return { ok: false, code: 'pr-base-not-trunk', error: `base must be a protected trunk branch, got ${base}` }
+
+    const accepted = []
+    let total = 0
+    for (const file of files) {
+      const checked = sanitizeRepoPath(file?.path)
+      if (!checked.ok) return { ok: false, code: `pr-file-${checked.code}`, error: String(file?.path ?? '') }
+      const content = String(file?.content ?? '')
+      total += Buffer.byteLength(content, 'utf8')
+      if (total > MAX_TOTAL_BYTES) return { ok: false, code: 'pr-files-too-large', error: `payload exceeds ${MAX_TOTAL_BYTES} bytes` }
+      accepted.push({ path: checked.path, content })
+    }
+
+    const branchState = await ensureBranch(branch, base)
+    if (!branchState.ok) return branchState
+    for (const file of accepted) {
+      const pushed = await putFile(branch, file.path, file.content, trim(input.message) || `chore(superagent): ${input.ticketId ?? 'ticket'}`)
+      if (!pushed.ok) return { ...pushed, branch }
+    }
+    const existing = await findOpenPr(branch)
+    if (existing) return { ok: true, branch, url: existing.url, number: existing.number, reused: true, pushedFiles: accepted.map((f) => f.path) }
+    const pr = await create({ branch, title: trim(input.title) || `SuperAgent: ${input.ticketId ?? branch}`, body: input.body, base, draft: input.draft === true })
+    if (!pr.ok) return { ...pr, branch }
+    return { ok: true, branch, url: pr.url, number: pr.number, pushedFiles: accepted.map((f) => f.path) }
+  }
+
+  return {
+    enabled,
+    create,
+    sanitizeRepoPath,
+    isProtectedBranch,
+    pushFile,
+    deliver,
+    branchForTicket,
+    describe: () => ({
+      enabled,
+      repo: enabled ? repo : null,
+      apiBase,
+      baseBranch,
+      workerHoldsCredentials: false,
+      mode: 'host-pushes-branch-then-pr',
+      branchPrefix: trim(options.branchPrefix) || 'superagent',
+      maxFiles: MAX_FILES,
+      maxTotalBytes: MAX_TOTAL_BYTES,
+    }),
+  }
+}

package/src/superagent/router.ts

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+
+/**
+ * SuperAgent Router（v3.2.1）：事件 → 评估 → Ticket/Mandate → 派发 Worker。
+ *
+ * Router 常驻原身（essence），**不执行代码改动**：所有执行体通过 dispatching
+ * 适配器交给瓮城 fangForker.spawn（分身），本模块不做文件/进程操作。
+ * 纯核心逻辑（评估/建票）在 trust.mjs；本模块只做编排、去重、持久化与审计。
+ */
+
+import { evaluateEvent, normalizePolicy, describePolicy } from './trust.ts'
+import { publicTicket } from './types.ts'
+import { handleGithubWebhook } from './github.ts'
+import { handleFeishuWebhook } from './feishu.ts'
+
+const RECENT_LIMIT = 50
+const DEDUPE_LIMIT = 500
+
+/**
+ * @param {{
+ *  config?: object,
+ *  store: ReturnType<import('./ticket-store.ts').createTicketStore>,
+ *  dispatcher: {available:()=>boolean, describe:()=>(object), dispatch:(ticket:object)=>Promise<object>},
+ *  logger?: {info?:Function,warn?:Function},
+ * }} options
+ */
+export function createSuperagentRouter({ config = {}, store, dispatcher, logger = null, beforeDispatch = null } = {}) {
+  if (!store || typeof store.add !== 'function') throw new Error('superagent router: ticket store is required')
+  if (!dispatcher || typeof dispatcher.dispatch !== 'function') throw new Error('superagent router: dispatcher is required')
+  const basePolicy = normalizePolicy(config)
+  let trustMode = basePolicy.trustMode
+  let policy = Object.freeze({ ...basePolicy, trustMode })
+  const counters = {
+    received: 0, duplicate: 0, ignored: 0, observed: 0, accepted: 0, unavailable: 0, dispatched: 0, failed: 0,
+  }
+  const recent = []
+  const seenEvents = new Set()
+
+  const logInfo = (...args) => { try { logger?.info?.(...args) } catch { /* ignore */ } }
+  const logWarn = (...args) => { try { logger?.warn?.(...args) } catch { /* ignore */ } }
+
+  const pushRecent = (entry) => {
+    recent.unshift(Object.freeze({ at: Date.now(), ...entry }))
+    if (recent.length > RECENT_LIMIT) recent.length = RECENT_LIMIT
+  }
+  const rememberEvent = (eventId) => {
+    if (!eventId) return false
+    if (seenEvents.has(eventId)) return true
+    seenEvents.add(eventId)
+    if (seenEvents.size > DEDUPE_LIMIT) {
+      const first = seenEvents.values().next().value
+      seenEvents.delete(first)
+    }
+    return false
+  }
+
+  const router = {
+    trustMode: () => trustMode,
+    policy: () => describePolicy(policy),
+    /** 管理员/测试切换信任模式；不持久化（3.2.x 再接 configEditor）。 */
+    setTrustMode(value) {
+      const normalized = normalizePolicy({ ...basePolicy, trustMode: value }).trustMode
+      trustMode = normalized
+      policy = Object.freeze({ ...basePolicy, trustMode })
+      logInfo(`[superagent] trust mode -> ${trustMode}`)
+      return trustMode
+    },
+    /** 摄取一条已归一化事件（Webhook 适配器或测试调用）。 */
+    async ingest(event, { defer = false } = {}) {
+      counters.received += 1
+      if (rememberEvent(String(event?.eventId ?? ''))) {
+        counters.duplicate += 1
+        return { ok: true, decision: 'ignore', reason: 'duplicate-event', duplicate: true }
+      }
+      const dispatchAvailable = dispatcher.available() === true
+      const evaluated = evaluateEvent({ event, policy, dispatchAvailable })
+      if (evaluated.decision === 'ignore') {
+        counters.ignored += 1
+        const out = { ok: true, decision: 'ignore', reasons: evaluated.reasons, reason: evaluated.reason }
+        pushRecent({ ...out, eventId: String(event?.eventId ?? '') })
+        return out
+      }
+      const ticket = evaluated.ticket
+      if (evaluated.decision === 'observe') {
+        store.add(ticket, 'observed')
+        counters.observed += 1
+        const out = { ok: true, decision: 'observe', ticket: publicTicket(ticket, { status: 'observed' }) }
+        pushRecent({ decision: 'observe', ticketId: ticket.id, eventId: String(event?.eventId ?? '') })
+        return out
+      }
+      if (evaluated.decision === 'unavailable') {
+        store.add(ticket, 'unavailable', { reason: evaluated.reason })
+        counters.unavailable += 1
+        const out = {
+          ok: true, decision: 'unavailable', reason: evaluated.reason,
+          ticket: publicTicket(ticket, { status: 'unavailable' }),
+          dispatch: dispatcher.describe?.() ?? null,
+        }
+        pushRecent({ decision: 'unavailable', ticketId: ticket.id, reason: evaluated.reason })
+        return out
+      }
+      // accept → 配额检查 → 落库 pending → 派发；派发失败必须落 failed 而不是假装成功。
+      if (typeof beforeDispatch === 'function') {
+        let gate = null
+        try { gate = await beforeDispatch(ticket) } catch (error) { gate = { ok: false, reason: `quota-check-threw:${String(error?.message ?? error)}` } }
+        if (gate && gate.ok === false) {
+          const reason = String(gate.reason ?? 'dispatch-rejected')
+          store.add(ticket, 'unavailable', { reason })
+          counters.unavailable += 1
+          const out = {
+            ok: false, decision: 'unavailable', reason,
+            ticket: publicTicket(ticket, { status: 'unavailable' }),
+            quota: gate.quota ?? null,
+          }
+          pushRecent({ decision: 'unavailable', ticketId: ticket.id, reason })
+          return out
+        }
+      }
+      store.add(ticket, 'pending')
+      counters.accepted += 1
+      const run = async () => {
+        const dispatched = await dispatcher.dispatch(ticket)
+        const currentStatus = () => { try { return store.get(ticket.id)?.status ?? null } catch { return null } }
+        if (!dispatched || dispatched.ok !== true) {
+          if (!['done', 'failed', 'unavailable', 'observed', 'expired', 'abandoned'].includes(String(currentStatus()))) {
+            store.setStatus(ticket.id, 'failed', { code: dispatched?.code ?? 'dispatch-failed' })
+          }
+          counters.failed += 1
+          logWarn(`[superagent] dispatch failed for ${ticket.id}: ${dispatched?.code ?? 'unknown'}`)
+          const out = {
+            ok: false, decision: 'unavailable', reason: 'dispatch-failed',
+            code: dispatched?.code ?? 'dispatch-failed', error: dispatched?.error ?? 'dispatch failed',
+            ticket: publicTicket(ticket, { status: 'failed' }),
+          }
+          pushRecent({ decision: 'unavailable', ticketId: ticket.id, reason: out.code })
+          return out
+        }
+        const fork = dispatched.fork
+        // Worker 可能先于 dispatch() 返回完成（SSE/done 先到）；终态不能被 dispatched 覆盖。
+        if (['pending', 'dispatched', 'running'].includes(String(currentStatus()))) {
+          store.setStatus(ticket.id, 'dispatched', { fork })
+        }
+        counters.dispatched += 1
+        const out = {
+          ok: true, decision: 'accept',
+          ticket: publicTicket(ticket, { status: 'dispatched' }),
+          fork,
+          forkId: fork?.forkId ?? null,
+        }
+        pushRecent({ decision: 'accept', ticketId: ticket.id, forkId: out.forkId })
+        return out
+      }
+      if (defer === true) {
+        // v3.2.7：Webhook 立即返回 202，派发在后台执行（fork 预置 10–30s，GitHub Webhook 超时约 10s）。
+        void run().catch((error) => {
+          try { store.setStatus(ticket.id, 'failed', { code: 'dispatch-async-failed', error: String(error?.message ?? error) }) } catch { /* ignore */ }
+          logWarn(`[superagent] async dispatch failed for ${ticket.id}: ${String(error?.message ?? error)}`)
+        })
+        pushRecent({ decision: 'accept', ticketId: ticket.id, async: true })
+        return { ok: true, decision: 'accept', accepted: true, pending: true, ticket: publicTicket(ticket, { status: 'pending' }) }
+      }
+      return await run()
+    },
+    /** GitHub Webhook：验签 + 归一化 + ingest；HTTP 语义与 handleGithubWebhook 对齐。 */
+    async ingestGithubWebhook({ rawBody, headers, secret, mentionHandles, defer = true } = {}) {
+      const handled = handleGithubWebhook({ rawBody, headers, secret, mentionHandles })
+      if (handled.status !== 200 || !handled.body?.event) return handled
+      // v3.2.7：默认后台派发——Webhook 必须在 GitHub 的超时（~10s）内返回，而 fork 预置需 10–30s。
+      const result = await router.ingest(handled.body.event, { defer })
+      return { status: 202, body: result }
+    },
+    /** 飞书 Webhook：token/challenge + 归一化 + ingest。 */
+    async ingestFeishuWebhook({ payload, verificationToken, mentionHandles, encryptKey } = {}) {
+      const handled = handleFeishuWebhook({ payload, verificationToken, mentionHandles, encryptKey })
+      if (handled.status !== 200 || !handled.body?.event) return handled
+      const result = await router.ingest(handled.body.event, { defer: true })
+      return { status: 202, body: result }
+    },
+    status() {
+      return {
+        ok: true,
+        trustMode,
+        policy: describePolicy(policy),
+        dispatch: dispatcher.describe?.() ?? null,
+        persistence: store.persistence?.() ?? null,
+        counters: { ...counters },
+        tickets: store.counts(),
+        activeTickets: store.size(),
+      }
+    },
+    tickets(limit = 20) {
+      return { ok: true, items: store.list({ limit }).map((record) => ({ ...publicTicket(record.ticket), status: record.status, updatedAt: record.updatedAt })) }
+    },
+    recent(limit = 10) { return recent.slice(0, Math.max(1, Math.floor(Number(limit)) || 10)) },
+  }
+  return router
+}
+
+export { normalizePolicy, evaluateEvent }