sintbot 1.3.0 → 1.4.1

package/src/cdp.js

@@ -0,0 +1,254 @@
+'use strict'
+// 常驻浏览器的 CDP 客户端(Chrome DevTools Protocol)—— 控制台「接管浏览器」页的底座。
+//
+// 为什么自己写而不用 chrome-devtools-mcp:MCP 是给 agent 用的工具面(元素 uid、快照),接管页要的是
+// **原始画面 + 原始输入** —— 截屏推流(Page.startScreencast)与按坐标的鼠标 / 键盘事件(Input.*),
+// 且要在 daemon 进程里长连接、按需 attach 到某个标签页。MCP 没有这两样,也不该有(它面向 agent)。
+//
+// 传输:HTTP 端点(/json、/json/new …)走 node:http;协议通道走 WebSocket(`ws` 包 —— 飞书 SDK 已带同一份,
+// 声明进依赖是为了不靠提升的巧合;Node 18/20 没有全局 WebSocket)。`WebSocketImpl` 可注入 ⇒ 单测用假的。
+//
+// ⚠ 只连 cfg.browser.cdpUrl(默认本机 9222)。9222 只绑 localhost,但本机任意进程都能经它操控已登录的浏览器
+//   (docs/BROWSER.md 安全口径)—— 这里不再加门,门在控制台那层(登录 / 一次性链接)。
+
+const http = require('node:http')
+
+const DEFAULT_CDP_URL = 'http://127.0.0.1:9222'
+
+// —— HTTP 端点 ——
+function httpJSON(url, { method = 'GET', timeoutMs = 3000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url)
+    const req = http.request({ host: u.hostname, port: u.port || 80, path: u.pathname + u.search, method, timeout: timeoutMs }, (res) => {
+      let b = ''
+      res.setEncoding('utf8')
+      res.on('data', (c) => { b += c })
+      res.on('end', () => {
+        if (res.statusCode >= 400) return reject(new Error(`浏览器端点 ${u.pathname} 返回 HTTP ${res.statusCode}`)) // 文案可能原样到接管页 / 群里,不带协议名
+        if (!b.trim()) return resolve(null)
+        try { resolve(JSON.parse(b)) } catch { resolve(b) } // /json/close 之类返回纯文本
+      })
+    })
+    req.on('timeout', () => req.destroy(new Error('浏览器端点超时')))
+    req.on('error', reject)
+    req.end()
+  })
+}
+
+// 浏览器还活着吗:/json/version(Browser 字段形如 "Chrome/152.0.7977.83")
+const versionInfo = (cdpUrl = DEFAULT_CDP_URL, opts = {}) => httpJSON(`${cdpUrl}/json/version`, opts)
+
+// 页面型 target 清单(过滤掉 chrome:// / devtools:// / 扩展页这类不是「网页」的东西)
+async function listTargets(cdpUrl = DEFAULT_CDP_URL) {
+  const all = (await httpJSON(`${cdpUrl}/json`)) || []
+  return all
+    .filter((t) => t && t.type === 'page' && /^(https?:|about:|file:)/.test(String(t.url || '')))
+    .map((t) => ({ id: t.id, title: t.title || '', url: t.url || '', wsUrl: t.webSocketDebuggerUrl || '' }))
+}
+
+const newTarget = (cdpUrl, url) => httpJSON(`${cdpUrl}/json/new?${encodeURIComponent(url || 'about:blank')}`, { method: 'PUT' })
+const activateTarget = (cdpUrl, id) => httpJSON(`${cdpUrl}/json/activate/${encodeURIComponent(id)}`)
+const closeTarget = (cdpUrl, id) => httpJSON(`${cdpUrl}/json/close/${encodeURIComponent(id)}`)
+
+// —— 协议会话 ——
+// 一个 target 一条 ws。call() 按 id 配对回包;on() 收事件(Page.screencastFrame 之类)。
+// 超时 / 断线时把所有挂着的 call 一起拒掉,调用方不会悬着。
+class CdpSession {
+  constructor(wsUrl, { WebSocketImpl = null, timeoutMs = 15000 } = {}) {
+    this.wsUrl = wsUrl
+    this.WebSocketImpl = WebSocketImpl || require('ws')
+    this.timeoutMs = timeoutMs
+    this.ws = null
+    this.connected = false
+    this._id = 0
+    this._pending = new Map() // id -> { resolve, reject, timer }
+    this._handlers = new Map() // method -> Set(fn)
+    this._onClose = new Set()
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      const ws = new this.WebSocketImpl(this.wsUrl)
+      this.ws = ws
+      const fail = (e) => { if (!this.connected) reject(e instanceof Error ? e : new Error(String(e && e.message || e || '连不上浏览器'))) }
+      ws.on('open', () => { this.connected = true; resolve(this) })
+      ws.on('error', (e) => { fail(e); this._failAll(e) })
+      ws.on('close', () => { this.connected = false; this._failAll(new Error('浏览器连接已断开')); for (const fn of this._onClose) { try { fn() } catch {} } })
+      ws.on('message', (data) => this._onMessage(data))
+    })
+  }
+
+  _onMessage(data) {
+    let m
+    try { m = JSON.parse(typeof data === 'string' ? data : data.toString('utf8')) } catch { return }
+    if (m.id != null && this._pending.has(m.id)) {
+      const p = this._pending.get(m.id); this._pending.delete(m.id); clearTimeout(p.timer)
+      if (m.error) p.reject(new Error(`${p.method}: ${m.error.message || JSON.stringify(m.error)}`))
+      else p.resolve(m.result || {})
+      return
+    }
+    if (m.method) {
+      const hs = this._handlers.get(m.method)
+      if (hs) for (const fn of hs) { try { fn(m.params || {}) } catch (e) { /* 单个处理器出错不影响别的 */ } }
+    }
+  }
+
+  _failAll(e) {
+    for (const [, p] of this._pending) { clearTimeout(p.timer); p.reject(e) }
+    this._pending.clear()
+  }
+
+  call(method, params = {}) {
+    if (!this.connected || !this.ws) return Promise.reject(new Error('浏览器连接未就绪'))
+    const id = ++this._id
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { if (this._pending.delete(id)) reject(new Error(`${method} 超时`)) }, this.timeoutMs)
+      this._pending.set(id, { resolve, reject, timer, method })
+      try { this.ws.send(JSON.stringify({ id, method, params })) } catch (e) { this._pending.delete(id); clearTimeout(timer); reject(e) }
+    })
+  }
+
+  on(method, fn) { if (!this._handlers.has(method)) this._handlers.set(method, new Set()); this._handlers.get(method).add(fn); return () => this.off(method, fn) }
+  off(method, fn) { const hs = this._handlers.get(method); if (hs) hs.delete(fn) }
+  onClose(fn) { this._onClose.add(fn); return () => this._onClose.delete(fn) }
+
+  close() { this.connected = false; try { this.ws && this.ws.close() } catch {} ; this._failAll(new Error('已关闭')) }
+}
+
+// —— 截屏推流 ——
+// 帧只在页面重绘时才来(静止页面零流量),所以开流后先补一张 captureScreenshot 当首帧,免得人盯着空白。
+// ack 放在 onFrame 之后:消费方(SSE 写入)慢了,浏览器就攒着不发下一帧 —— 天然背压,不用自己丢帧。
+// 默认值的来由(2026-09-10 真机实测,手机尺寸):640 宽 / 45 质量一帧约 12 KB;everyNthFrame=2 把不限速时的 ~28 fps 压到一半,
+// 再由「onFrame 完成后才 ack」的背压按链路自然降到几帧每秒 —— 画面够顺、公网隧道与手机流量都扛得住。
+async function startScreencast(session, { maxWidth = 640, maxHeight = 1280, quality = 45, everyNthFrame = 2 } = {}, onFrame) {
+  await session.call('Page.enable')
+  const off = session.on('Page.screencastFrame', async (p) => {
+    try { await onFrame({ data: p.data, meta: p.metadata || {}, sessionId: p.sessionId }) } catch {}
+    try { await session.call('Page.screencastFrameAck', { sessionId: p.sessionId }) } catch {}
+  })
+  await session.call('Page.startScreencast', { format: 'jpeg', quality, maxWidth, maxHeight, everyNthFrame })
+  try { await seedFrame(session, { maxWidth, maxHeight, quality }, onFrame) } catch { /* 首帧补不上就等真帧 */ }
+  return async () => { off(); try { await session.call('Page.stopScreencast') } catch {} }
+}
+
+// 补一张首帧(开流时、以及后来才加入同一路推流的订阅者)。
+// ⚠ 首帧必须与推流帧同尺寸:captureScreenshot 默认按视口原尺寸出图,而推流帧被 maxWidth/maxHeight 缩过 ——
+//   两者不一致时,接管页在第二帧到来那一刻画面会跳一下,手指正按着的位置就漂了(2026-09-10 真机:拖滑块位移 0)。
+//   先读视口尺寸,按同样的比例给截图加 clip.scale。
+async function seedFrame(session, { maxWidth = 640, maxHeight = 1280, quality = 45 } = {}, onFrame) {
+  const lm = await session.call('Page.getLayoutMetrics')
+  const vv = (lm && (lm.cssVisualViewport || lm.visualViewport)) || {}
+  const cw = vv.clientWidth || 0, ch = vv.clientHeight || 0
+  const scale = cw > 0 && ch > 0 ? Math.min(1, maxWidth / cw, maxHeight / ch) : 1
+  const params = { format: 'jpeg', quality }
+  if (cw > 0 && ch > 0) params.clip = { x: 0, y: 0, width: cw, height: ch, scale }
+  const shot = await session.call('Page.captureScreenshot', params)
+  await onFrame({ data: shot.data, meta: { deviceWidth: cw, deviceHeight: ch, seed: true }, sessionId: null })
+}
+
+// 给 CLI 用:截某个标签页一张缩略图(接管卡片上的「卡在哪个页面」)。连一次、截一张、关掉;失败抛错由调用方决定要不要图。
+async function captureTarget(cdpUrl, targetId, { maxWidth = 640, quality = 60, WebSocketImpl = null } = {}) {
+  const targets = await listTargets(cdpUrl)
+  const t = targets.find((x) => x.id === targetId)
+  if (!t) throw new Error('这个标签页已经不在了')
+  const session = new CdpSession(t.wsUrl, { WebSocketImpl })
+  await session.connect()
+  try {
+    let data = null
+    await seedFrame(session, { maxWidth, maxHeight: maxWidth * 2, quality }, (f) => { data = f.data })
+    return { data, title: t.title, url: t.url }
+  } finally { session.close() }
+}
+
+// —— 输入:接管页发来的事件 → CDP 调用(纯函数,可测)——
+// 坐标一律是页面 CSS 像素(接管页按帧的 deviceWidth/Height 换算好再发),这里只做校验与翻译。
+const KEYS = {
+  Enter: { key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, text: '\r' },
+  Backspace: { key: 'Backspace', code: 'Backspace', windowsVirtualKeyCode: 8 },
+  Tab: { key: 'Tab', code: 'Tab', windowsVirtualKeyCode: 9 },
+  Escape: { key: 'Escape', code: 'Escape', windowsVirtualKeyCode: 27 },
+  Delete: { key: 'Delete', code: 'Delete', windowsVirtualKeyCode: 46 },
+  ArrowUp: { key: 'ArrowUp', code: 'ArrowUp', windowsVirtualKeyCode: 38 },
+  ArrowDown: { key: 'ArrowDown', code: 'ArrowDown', windowsVirtualKeyCode: 40 },
+  ArrowLeft: { key: 'ArrowLeft', code: 'ArrowLeft', windowsVirtualKeyCode: 37 },
+  ArrowRight: { key: 'ArrowRight', code: 'ArrowRight', windowsVirtualKeyCode: 39 },
+  Home: { key: 'Home', code: 'Home', windowsVirtualKeyCode: 36 },
+  End: { key: 'End', code: 'End', windowsVirtualKeyCode: 35 },
+  PageUp: { key: 'PageUp', code: 'PageUp', windowsVirtualKeyCode: 33 },
+  PageDown: { key: 'PageDown', code: 'PageDown', windowsVirtualKeyCode: 34 },
+}
+// 一次插入的文本上限:验证码 / 账号 / 一段地址都远小于此;更长的多半是误粘贴(整页文本),不该一股脑塞进输入框
+const MAX_TEXT = 4000
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? Math.round(v * 10) / 10 : null)
+
+// 非文本键必须带 windowsVirtualKeyCode:CDP 只凭 key/code 不会触发页面里按键盘码判断的逻辑(表单的 Enter 提交、退格删字)—— 与 puppeteer 的键表同款。
+// 坐标上限 20000 / 滚轮上限 5000:视口再大也到不了的值,只用来拦明显的垃圾输入(NaN、负数、乱填),不是精确边界。
+// 一个接管页事件 → 若干 { method, params };不认识 / 不合法 ⇒ null(调用方跳过,不报错,免得一个坏事件卡住整批)
+function inputToCdp(ev) {
+  if (!ev || typeof ev !== 'object') return null
+  const t = ev.t
+  if (t === 'text') {
+    const text = String(ev.text == null ? '' : ev.text)
+    if (!text || text.length > MAX_TEXT) return null
+    return [{ method: 'Input.insertText', params: { text } }]
+  }
+  if (t === 'key') {
+    const k = Object.prototype.hasOwnProperty.call(KEYS, String(ev.key)) ? KEYS[ev.key] : null // hasOwn:'__proto__' 之类的键名不能摸到原型
+    if (!k) return null
+    const mods = (ev.shift ? 8 : 0) | (ev.ctrl ? 2 : 0) | (ev.alt ? 1 : 0) | (ev.meta ? 4 : 0)
+    // Enter 的 text 让输入框真的换行 / 提交:keyDown 带 text 才触发 keypress 语义(与 puppeteer 同款)
+    const down = { type: k.text ? 'keyDown' : 'rawKeyDown', key: k.key, code: k.code, windowsVirtualKeyCode: k.windowsVirtualKeyCode, modifiers: mods }
+    if (k.text) down.text = k.text
+    return [{ method: 'Input.dispatchKeyEvent', params: down }, { method: 'Input.dispatchKeyEvent', params: { type: 'keyUp', key: k.key, code: k.code, windowsVirtualKeyCode: k.windowsVirtualKeyCode, modifiers: mods } }]
+  }
+  const x = num(ev.x), y = num(ev.y)
+  if (x == null || y == null || x < 0 || y < 0 || x > 20000 || y > 20000) return null
+  if (t === 'move') return [{ method: 'Input.dispatchMouseEvent', params: { type: 'mouseMoved', x, y, button: ev.down ? 'left' : 'none', buttons: ev.down ? 1 : 0 } }]
+  if (t === 'down') return [{ method: 'Input.dispatchMouseEvent', params: { type: 'mousePressed', x, y, button: 'left', buttons: 1, clickCount: 1 } }]
+  if (t === 'up') return [{ method: 'Input.dispatchMouseEvent', params: { type: 'mouseReleased', x, y, button: 'left', buttons: 0, clickCount: 1 } }]
+  if (t === 'tap') return [
+    { method: 'Input.dispatchMouseEvent', params: { type: 'mouseMoved', x, y, button: 'none', buttons: 0 } },
+    { method: 'Input.dispatchMouseEvent', params: { type: 'mousePressed', x, y, button: 'left', buttons: 1, clickCount: 1 } },
+    { method: 'Input.dispatchMouseEvent', params: { type: 'mouseReleased', x, y, button: 'left', buttons: 0, clickCount: 1 } },
+  ]
+  if (t === 'wheel') {
+    const dx = num(ev.dx) || 0, dy = num(ev.dy) || 0
+    if (Math.abs(dx) > 5000 || Math.abs(dy) > 5000) return null
+    return [{ method: 'Input.dispatchMouseEvent', params: { type: 'mouseWheel', x, y, deltaX: dx, deltaY: dy } }]
+  }
+  return null
+}
+
+// 一批事件按序下发;坏事件跳过(计入 skipped),CDP 报错(页面正在导航之类)记下继续,不中断整批。
+// 超过 max 时只丢 move / wheel(丢掉中间几步无伤),**down / up / key / text 一个都不能丢** —— 丢了 up 鼠标就卡在按下态
+// (对抗审查 🟡7);丢了多少报 dropped,让页面知道。
+function trimEvents(events, max) {
+  const list = Array.isArray(events) ? events : []
+  if (list.length <= max) return { list, dropped: 0 }
+  const must = list.filter((e) => e && e.t !== 'move' && e.t !== 'wheel')
+  const room = Math.max(0, max - must.length)
+  const soft = list.filter((e) => e && (e.t === 'move' || e.t === 'wheel'))
+  const keepSoft = new Set(soft.slice(soft.length - room)) // 留最近的几步,老的丢
+  const out = list.filter((e) => e && (e.t !== 'move' && e.t !== 'wheel' ? true : keepSoft.has(e))).slice(0, Math.max(max, must.length))
+  return { list: out, dropped: list.length - out.length }
+}
+async function dispatchInputs(session, events, { max = 200 } = {}) {
+  const { list, dropped } = trimEvents(events, max)
+  let sent = 0, skipped = 0, failed = 0
+  for (const ev of list) {
+    const calls = inputToCdp(ev)
+    if (!calls) { skipped++; continue }
+    for (const c of calls) { try { await session.call(c.method, c.params); sent++ } catch { failed++ } }
+  }
+  return { sent, skipped, failed, dropped }
+}
+
+// 接管页 → 页面坐标:帧图片的像素坐标按帧元数据里的视口尺寸(CSS px)线性换算;越界夹回
+function pointerToCss({ px, py, imgW, imgH, cssW, cssH }) {
+  if (!(imgW > 0) || !(imgH > 0) || !(cssW > 0) || !(cssH > 0)) return null
+  const x = Math.min(cssW, Math.max(0, (px / imgW) * cssW))
+  const y = Math.min(cssH, Math.max(0, (py / imgH) * cssH))
+  return { x: Math.round(x * 10) / 10, y: Math.round(y * 10) / 10 }
+}
+
+module.exports = { DEFAULT_CDP_URL, httpJSON, versionInfo, listTargets, newTarget, activateTarget, closeTarget, CdpSession, startScreencast, seedFrame, captureTarget, inputToCdp, dispatchInputs, trimEvents, pointerToCss, KEYS, MAX_TEXT }

package/src/config.js

@@ -83,6 +83,17 @@ function loadConfig(explicit) {
     }
   }
 
+  return normalizeConfig(user, p)
+}
+
+// The console validates proposed JSON before replacing the live file. Keep
+// normalization identical to disk loading without mutating the proposed object
+// or changing the live redaction registry during validation.
+function normalizeConfig(raw, p = null, { registerSecrets = true } = {}) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new TypeError('Configuration must be a JSON object')
+  }
+  const user = JSON.parse(JSON.stringify(raw))
   const cfg = {
     agent: { ...DEFAULTS.agent, ...(user.agent || {}) },
     timezone: normalizeTz(user.timezone || DEFAULTS.timezone), // 写错回退默认,不漂到主机时区
@@ -172,7 +183,7 @@ function loadConfig(explicit) {
   // 把配置里凭据的**值**登记给出站脱敏(src/core/redact.js 按值替换):每个 provider 的 apiKey、
   // provider env 里名字带 TOKEN / KEY / SECRET / PASSWORD 的值、飞书 appSecret。形状模式认不出的
   // 凭据(UUID 形的火山 key、裸十六进制的 appSecret)靠这条兜住;热重载走的也是这里 ⇒ 换 key 即换名单。
-  setKnownSecrets(collectSecretValues(cfg))
+  if (registerSecrets) setKnownSecrets(collectSecretValues(cfg))
 
   return cfg
 }
@@ -281,4 +292,4 @@ function chatPlatform(cfg, chatId) {
   return live.length === 1 ? live[0] : null
 }
 
-module.exports = { loadConfig, findConfigPath, defaultConfigPath, DEFAULTS, applyProxyEnv, deriveNoProxy, resolveSecret, platformsConfigured, inferChatPlatform, normalizeGroupPlatforms, chatPlatform, PLATFORMS }
+module.exports = { loadConfig, normalizeConfig, findConfigPath, defaultConfigPath, DEFAULTS, applyProxyEnv, deriveNoProxy, resolveSecret, platformsConfigured, inferChatPlatform, normalizeGroupPlatforms, chatPlatform, PLATFORMS }

package/src/core/c2durablejournal.js

@@ -458,7 +458,8 @@ function terminalSettlementCandidate(record, authority, requireLocal) {
   const { state, receipts, effects, attempts, descriptors, notices, local,
     validateState, validateReceipts, validateRelation } = authority
   const batchRecord = Object.hasOwn(record, 'batchReceiptIds')
-  if (Object.keys(record).sort().join(',') !==
+  const steerRecord = Object.hasOwn(record, 'steerReceiptIds')
+  if (Object.keys(record).filter(key => key !== 'steerReceiptIds').sort().join(',') !==
       (batchRecord
         ? 'batchReceiptIds,chatId,cursor,effectId,kind,receiptId,settledAt,status,turnToken'
         : 'chatId,cursor,effectId,kind,receiptId,settledAt,status,turnToken') ||
@@ -513,7 +514,14 @@ function terminalSettlementCandidate(record, authority, requireLocal) {
         requireLocal && !local.has(record.effectId)) {
     throw new Error('C2 terminal settlement effect attempt invalid')
   }
-  const candidate = completedBatch(receipts, receiptIds, record.settledAt)
+  const steered = lane.steerReceiptIds || []
+  if (steerRecord !== !!lane.steerReceiptIds || steerRecord && !isDeepStrictEqual(record.steerReceiptIds, steered) ||
+      steered.some(id => receiptIds.includes(id) || notices.has(id) ||
+        receipts.pending.find(item => item.id === id)?.chatId !== record.chatId ||
+        ![...descriptors.values()].some(effect => effect.domain === 'steer' && effect.type === 'callSteer' &&
+          effect.scope === record.chatId && effect.turnToken === record.turnToken && effect.receiptId === id &&
+          effects.get(effect.effectId) === 'acked'))) throw new Error('terminal steer settlement invalid')
+  const candidate = completedBatch(receipts, [...receiptIds, ...steered], record.settledAt)
   validateSnapshots({ state, receipts: candidate }, validateState, validateReceipts,
     validateRelation)
   validateReceiptProgress(receipts, candidate)
@@ -823,10 +831,9 @@ class C2DurableJournal {
   // after this settlement and terminal prune.
   settleTerminalEffect(value) {
     if (this.#blocked) throw new Error('C2 journal needs reopen after write failure')
-    noticeFields(value, value?.batchReceiptIds === undefined
-      ? ['effectId', 'receiptId', 'chatId', 'turnToken', 'status', 'settledAt']
-      : ['effectId', 'receiptId', 'chatId', 'turnToken', 'status', 'settledAt',
-        'batchReceiptIds'])
+    noticeFields(value, ['effectId', 'receiptId', 'chatId', 'turnToken', 'status', 'settledAt',
+      ...(value?.batchReceiptIds === undefined ? [] : ['batchReceiptIds']),
+      ...(value?.steerReceiptIds === undefined ? [] : ['steerReceiptIds'])])
     const record = { kind: 'terminalSettlement', cursor: this.#cursor, ...value }
     terminalSettlementCandidate(record, this.#settlementAuthority(), true)
     this.#append(record)
@@ -1235,14 +1242,23 @@ class C2DurableJournal {
         const item = exactJson(raw)
         if (!item || typeof item !== 'object' || Array.isArray(item) ||
             !['chatId,receiptId,settledAt,turnToken',
-              'batchReceiptIds,chatId,receiptId,settledAt,turnToken']
+              'batchReceiptIds,chatId,receiptId,settledAt,turnToken',
+              'chatId,receiptId,settledAt,steerReceiptIds,turnToken',
+              'batchReceiptIds,chatId,receiptId,settledAt,steerReceiptIds,turnToken']
               .includes(Object.keys(item).sort().join(','))) {
           throw new Error('invalid C2 checkpoint terminal settlement')
         }
         noticeIdentity(item.receiptId, item.chatId)
         noticeTime(item.settledAt)
         const descriptor = effectDescriptors.get(effectId)
-        const settledIds = item.batchReceiptIds || [item.receiptId]
+        if (item.steerReceiptIds !== undefined &&
+            (!Array.isArray(item.steerReceiptIds) || !item.steerReceiptIds.length || item.steerReceiptIds.length > 32 ||
+              item.steerReceiptIds.some(id => !RECEIPT_ID.test(id) ||
+                ![...effectDescriptors.values()].some(effect => effect.domain === 'steer' &&
+                  effect.type === 'callSteer' && effect.scope === item.chatId &&
+                  effect.turnToken === item.turnToken && effect.receiptId === id &&
+                  effects.get(effect.effectId) === 'acked')))) throw new Error('invalid C2 checkpoint steer settlement')
+        const settledIds = [...(item.batchReceiptIds || [item.receiptId]), ...(item.steerReceiptIds || [])]
         if (!Array.isArray(settledIds) || !settledIds.length ||
             new Set(settledIds).size !== settledIds.length ||
             !settledIds.includes(item.receiptId) ||
@@ -1428,7 +1444,8 @@ class C2DurableJournal {
       this.#terminalSettlements.set(record.effectId, { receiptId: record.receiptId,
         chatId: record.chatId, turnToken: record.turnToken, settledAt: record.settledAt,
         ...(record.batchReceiptIds === undefined ? {} : {
-          batchReceiptIds: [...record.batchReceiptIds] }) })
+          batchReceiptIds: [...record.batchReceiptIds] }),
+        ...(record.steerReceiptIds === undefined ? {} : { steerReceiptIds: [...record.steerReceiptIds] }) })
       return
     }
     if (record.kind === 'stopAckSettlement') {

package/src/core/c2durableruntime.js

@@ -320,6 +320,107 @@ class C2DurableRuntime {
   // A visible busy receipt remains pending after its queue acknowledgement.
   // The effect descriptor and target identity are durable before any send;
   // only the same process may turn one attempted call into an ACK.
+  prepareSteer({ receiptId, chatId, parentReceiptId, turnToken, generation, payloadHandles } = {}) {
+    const before = this.#completionCapacity()
+    const witness = this.#activeRuns.get(chatId)
+    const receipt = before.receipts.pending.find(item => item.id === receiptId)
+    const job = payloadHandles?.requireQueued(receiptId)
+    if (!RECEIPT_ID.test(receiptId || '') || !GENERATION.test(generation || '') ||
+        receipt?.chatId !== chatId || receipt.source !== 'message' || receipt.quiet ||
+        job?.msg?._c2ReceiptId !== receiptId || witness?.receiptId !== parentReceiptId ||
+        witness.turnToken !== turnToken || this.#journal.effectStatus(witness.dispatchEffectId) !== 'acked' ||
+        this.#journal.lookupRegistration(callbackRegistrationId({ receiptId: parentReceiptId,
+          generation, domain: 'atomicHandoff', kind: 'runnerAccepted' }))?.generation !== generation) {
+      throw new Error('C2 steer lacks accepted live parent and queued receipt')
+    }
+    const id = `sbot-c2-steer-v1:${receiptId}:${generation}:prepare`
+    try {
+      const result = this.#coordinator.transition({ id, domain: 'steer', scope: chatId,
+        payload: { type: 'prepare', receiptId, parentReceiptId, turnToken, generation },
+        validate: candidate => {
+          const effect = candidate.effects[0]
+          if (candidate.effects.length !== 1 || effect.type !== 'callSteer' ||
+              effect.receiptId !== receiptId || effect.turnToken !== turnToken ||
+              candidate.effectDescriptors[0].receiptId !== receiptId) throw new Error('C2 steer decision invalid')
+        } })
+      return { effectId: result.effects[0].effectId, receiptId, chatId,
+        parentReceiptId, turnToken, generation }
+    } catch (error) { this.close(); throw error }
+  }
+
+  commitSteerObservation({ receiptId, chatId, parentReceiptId, turnToken, generation, type } = {}) {
+    const before = this.#completionCapacity()
+    const entry = before.state.lanes.steer?.[chatId]?.entries.find(item => item.receiptId === receiptId)
+    const lane = before.state.lanes.steer?.[chatId]
+    if (!entry || lane.parentReceiptId !== parentReceiptId || lane.turnToken !== turnToken ||
+        lane.generation !== generation || !['accepted', 'rejected', 'landed'].includes(type) ||
+        this.#journal.effectStatus(entry.effectId) !== 'acked') throw new Error('C2 steer observation lacks confirmed RPC')
+    if (entry.status === 'landed' && type === 'landed') return false
+    try {
+      this.#coordinator.transition({ id: `sbot-c2-steer-v1:${receiptId}:${generation}:${type}`,
+        domain: 'steer', scope: chatId,
+        payload: { type, receiptId, parentReceiptId, turnToken, generation } })
+      return true
+    } catch (error) { this.close(); throw error }
+  }
+
+  async executeSteer(identity, { invoke, assertWriterLock } = {}) {
+    this.#completionCapacity()
+    const { effectId, receiptId, chatId, parentReceiptId, turnToken, generation } = identity || {}
+    const descriptor = this.#journal.effectDescriptor(effectId)
+    if (descriptor?.domain !== 'steer' || descriptor.type !== 'callSteer' ||
+        descriptor.scope !== chatId || descriptor.receiptId !== receiptId ||
+        descriptor.turnToken !== turnToken || this.#journal.effectStatus(effectId) !== 'pending' ||
+        typeof invoke !== 'function' || typeof assertWriterLock !== 'function' ||
+        assertWriterLock.constructor?.name === 'AsyncFunction' || assertWriterLock() !== true) {
+      throw new Error('C2 steer attempt lacks exact RPC authority')
+    }
+    const attemptedAt = this.#now()
+    try {
+      this.#journal.beginEffectAttempt({ effectId, attemptedAt })
+      let accepted, known = false
+      try {
+        accepted = await invoke()
+        known = typeof accepted === 'boolean' && this.#effectAuthorityReady && assertWriterLock() === true
+      } catch { /* A transport failure may already have delivered the message. */ }
+      this.#journal.recordEffectOutcome({ effectId, status: known ? 'acked' : 'unknown',
+        resolvedAt: Math.max(attemptedAt, this.#now()) })
+      if (!known) throw new Error('C2 steer outcome unknown; replay forbidden')
+      this.commitSteerObservation({ receiptId, chatId, parentReceiptId, turnToken, generation,
+        type: accepted ? 'accepted' : 'rejected' })
+      return accepted
+    } catch (error) { this.close(); throw error }
+  }
+
+  cancelClosedSteer({ chatId, parentReceiptId, turnToken, generation, assertWriterLock } = {}) {
+    const before = this.#completionCapacity()
+    const lane = before.state.lanes.steer?.[chatId]
+    if (!lane) return []
+    const closeEvidenceId = `sbot-c2-runner-closed-v1:${parentReceiptId}:${generation}`
+    const proof = this.#journal.lookupRunnerClosed(closeEvidenceId)
+    if (typeof assertWriterLock !== 'function' || assertWriterLock.constructor?.name === 'AsyncFunction' ||
+        assertWriterLock() !== true || proof?.chatId !== chatId || proof.receiptId !== parentReceiptId ||
+        proof.generation !== generation || proof.turnToken !== turnToken ||
+        lane.entries.some(entry => this.#journal.effectStatus(entry.effectId) !== 'acked')) {
+      throw new Error('C2 steer cancellation lacks exact closed RPC authority')
+    }
+    const ids = lane.entries.map(entry => entry.receiptId)
+    const settledAt = this.#now()
+    const receipts = { pending: before.receipts.pending.filter(item => !ids.includes(item.id)),
+      completed: [...before.receipts.completed, ...ids.map(id => ({ id, settledAt }))] }
+    try {
+      this.#coordinator.transition({ id: `sbot-c2-steer-cancel-v1:${parentReceiptId}:${generation}`,
+        domain: 'steer', scope: chatId, payload: { type: 'cancelAll', parentReceiptId,
+          turnToken, generation, runnerClosed: true, closeEvidenceId }, receipts,
+        validate: result => {
+          if (!isDeepStrictEqual(result.decision.cancelledReceiptIds, ids) || result.effects.length) {
+            throw new Error('C2 steer cancellation result invalid')
+          }
+        } })
+      return ids
+    } catch (error) { this.close(); throw error }
+  }
+
   prepareQueueNotice({ receiptId, chatId, payloadHandles } = {}) {
     const before = this.#completionCapacity()
     if (!RECEIPT_ID.test(receiptId || '') ||
@@ -2220,7 +2321,9 @@ class C2DurableRuntime {
     try {
       const result = this.#journal.settleTerminalEffect({ effectId, receiptId,
         chatId, turnToken, status: 'acked', settledAt,
-        ...(batchReceiptIds ? { batchReceiptIds: [...batchReceiptIds] } : {}) })
+        ...(batchReceiptIds ? { batchReceiptIds: [...batchReceiptIds] } : {}),
+        ...(before.state.lanes.terminal?.[chatId]?.steerReceiptIds ? {
+          steerReceiptIds: [...before.state.lanes.terminal[chatId].steerReceiptIds] } : {}) })
       pruneConfirmedTerminal({ journal: this.#journal,
         coordinator: this.#coordinator, scope: chatId })
       this.#terminalAwaitingSettlement.delete(chatId)

package/src/core/c2inputrejection.js

@@ -0,0 +1,45 @@
+'use strict'
+
+// User input the durable v2 route refuses before any receipt exists, such as
+// an unmigrated chat command or /stop with nothing to stop. No durable write
+// happened, so refusing it must not stop the service or sibling groups. Every
+// other route error keeps the existing fault contract and closes ingress.
+const CODE = 'C2_V2_INPUT_REJECTED'
+const FEISHU_MESSAGE_ID = /^om_[A-Za-z0-9_-]{1,124}$/
+
+function rejectC2Input(message, { reason, notice = null } = {}) {
+  if (typeof message !== 'string' || !message ||
+      typeof reason !== 'string' || !/^[a-z][a-z-]{0,40}$/.test(reason) ||
+      notice !== null && (typeof notice !== 'string' || !notice)) {
+    throw new TypeError('C2 input rejection needs a message, reason and optional notice')
+  }
+  const error = new Error(message)
+  error.code = CODE
+  error.reason = reason
+  error.notice = notice
+  return error
+}
+
+function isC2InputRejection(error) {
+  return !!error && error.code === CODE && typeof error.reason === 'string'
+}
+
+// One best-effort reply under the refused message. It is not a durable effect:
+// a failure is logged, never retried and never escalated to a fault.
+async function answerC2InputRejection({ error, msg, platform, log = () => {} } = {}) {
+  if (!isC2InputRejection(error)) throw new TypeError('C2 input rejection expected')
+  const target = msg?.replyCtx
+  let notified = false
+  if (error.notice && typeof platform?.replyOnce === 'function' &&
+      typeof msg?.chatId === 'string' && target?.chatId === msg.chatId &&
+      FEISHU_MESSAGE_ID.test(target?.messageId || '')) {
+    try {
+      const response = await platform.replyOnce(target, error.notice)
+      notified = response?.code === 0
+    } catch {}
+    if (!notified) log(`input rejection notice not confirmed (${error.reason})`)
+  }
+  return Object.freeze({ rejected: true, reason: error.reason, notified })
+}
+
+module.exports = { rejectC2Input, isC2InputRejection, answerC2InputRejection }

package/src/core/c2localeffectexecutor.js

@@ -132,7 +132,7 @@ function createC2LocalEffectExecutor({ journal, store, resolveTurn,
       ? ['effectId', 'success', 'type'] : ['effectId', 'type']
     if (Object.keys(effect).sort().join(',') !== required.join(',') ||
         effect.type !== descriptor.type ||
-        descriptor.type === 'verifyTurn' && effect.success !== true) {
+        descriptor.type === 'verifyTurn' && typeof effect.success !== 'boolean') {
       throw new Error('C2 local effect payload differs from durable descriptor')
     }
     const turn = resolveTurn({ chatId: descriptor.scope,
@@ -145,6 +145,17 @@ function createC2LocalEffectExecutor({ journal, store, resolveTurn,
       throw new Error('C2 local effect turn identity unavailable')
     }
     const chatId = descriptor.scope
+    if (effect.type === 'verifyTurn' && effect.success === false) {
+      const outcome = journal.snapshot().state.lanes.terminal?.[chatId]?.outcome
+      // A known quota failure says nothing about credential validity. The
+      // binary's failed verification intent is acknowledged without writing
+      // a false success or altering the previous credential-health record.
+      if (outcome?.status !== 'error' || outcome.quotaError !== true ||
+          outcome.sideEffects !== false) {
+        throw new Error('C2 local effect payload differs: failed verification lacks a supported quota outcome')
+      }
+      return true
+    }
     if (effect.type === 'clearTainted') {
       store.clearTainted(chatId)
       const disk = readJson(store.file)

package/src/core/c2payloadhandles.js

@@ -121,6 +121,17 @@ class C2PayloadHandles {
     return job
   }
 
+  takeSteer(id, chatId, effectId) {
+    const snapshot = authority(this.#journal)
+    const entry = snapshot.state.lanes.steer?.[chatId]?.entries.find(item => item.receiptId === id)
+    const receipt = pending(snapshot, id)
+    const job = this.#jobs.get(id)
+    if (this.blocked || !job || receipt?.chatId !== chatId || entry?.effectId !== effectId ||
+        entry.status !== 'pending' || queued(snapshot, id, chatId)) throw new Error('steer payload authority invalid')
+    this.#jobs.delete(id)
+    return job
+  }
+
   takeHandoff(id) {
     receiptId(id)
     if (this.blocked) throw new Error('C2 payload handles closed pending startup recovery')

package/src/core/c2persistrelation.js

@@ -115,7 +115,27 @@ function validatePersistentRelation(state, receipts) {
       }
     }
   }
+  for (const [scope, steer] of Object.entries(state.lanes.steer || {})) {
+    const parent = byId.get(steer.parentReceiptId)
+    if (!parent || parent.chatId !== scope || parent.source !== 'message' || parent.quiet ||
+        state.lanes.turn?.[scope]?.active !== steer.turnToken ||
+        state.lanes.handoff?.[scope]?.phase !== 'running' ||
+        state.lanes.handoff[scope].turnToken !== steer.turnToken) throw new TypeError('steer parent authority invalid')
+    for (const entry of steer.entries) {
+      const receipt = byId.get(entry.receiptId)
+      if (!receipt || receipt.chatId !== scope || receipt.source !== 'message' || receipt.quiet ||
+          allJobIds.has(`receipt:job:${entry.receiptId}`) ||
+          state.lanes.handoff[scope].acceptedReceiptIds.includes(entry.receiptId)) {
+        throw new TypeError('steer receipt authority invalid')
+      }
+    }
+  }
   for (const [scope, terminal] of Object.entries(state.lanes.terminal || {})) {
+    for (const id of terminal.steerReceiptIds || []) {
+      if (!byId.has(id) || byId.get(id) && byId.get(id).chatId !== scope || allJobIds.has(`receipt:job:${id}`)) {
+        throw new TypeError('terminal steer receipt invalid')
+      }
+    }
     if (!terminal.finalized || !terminal.batchReceiptIds) continue
     for (const id of terminal.batchReceiptIds) {
       if (!byId.has(id)) throw new TypeError('terminal batch receipt missing')