sintbot 1.0.16 → 1.3.0

package/src/agent/runner.js

@@ -1,16 +1,18 @@
-// Runner dispatch — selects the AgentRunner by provider so the rest of sbot (engine,
-// CLI, UI server) only ever calls one `runTurn` and stays backend-agnostic. A provider
-// with `runner: "codex"` drives OpenAI Codex CLI (GPT; DESIGN §1); everything
-// else drives Claude Code. The caller's `bin` is the Claude bin (cfg.agent.bin) — override
-// it to the codex bin when routing there. probeVersion (the Claude-bin startup probe) is
-// re-exported; codex has its own probe via codexcode.probeVersion (used by health.js).
+// Runner dispatch — selects the AgentRunner by provider so the rest of SintBot calls one
+// `runTurn`. Codex uses App Server by default and `codex exec` when the group
+// explicitly disables busy follow-up; all other providers use Claude Code. The caller's `bin` is
+// the Claude bin (cfg.agent.bin) — override it when routing to Codex.
 
 const claudeAgent = require('./claudecode')
 const codexAgent = require('./codexcode')
+const codexApp = require('./codexapp')
+const { routeBackend } = require('./privatecore')
 
 function runTurn(opts) {
-  if (opts && opts.provider && opts.provider.runner === 'codex') {
-    return codexAgent.runTurn({ ...opts, bin: (opts.provider && opts.provider.bin) || 'codex' })
+  const route = routeBackend(opts && opts.provider && opts.provider.runner, opts && opts.codexApp, opts && opts.codexSteer, opts && opts.codexProjectDocFallback)
+  if (route !== 'claude') {
+    const codexOpts = { ...opts, bin: (opts.provider && opts.provider.bin) || 'codex' }
+    return route === 'codex-app' ? codexApp.runTurn(codexOpts) : codexAgent.runTurn(codexOpts)
   }
   return claudeAgent.runTurn(opts)
 }

package/src/agent/winexec.js

@@ -11,19 +11,49 @@
 // same as calling the bin directly.
 
 const fs = require('node:fs')
+const os = require('node:os')
 const path = require('node:path')
 
 const IS_WIN = process.platform === 'win32'
 
+const isFile = (p) => { try { return fs.statSync(p).isFile() } catch { return false } }
+
+// nvm 把每个 node 版本各装一套,bin 目录名里带版本号;新到旧排,先试最近装的那套
+function nvmBinDirs(home) {
+  const root = path.join(home, '.nvm', 'versions', 'node')
+  try { return fs.readdirSync(root).sort().reverse().map((v) => path.join(root, v, 'bin')) } catch { return [] }
+}
+
+// 配置钉死的绝对路径指空时,找**同一个程序**的另一份 —— 不切模型、不清会话、不报错。
+// 典型情况:CLI 自更新把新版装进 nvm 前缀、homebrew 那份被清掉,配置钉的路径指空
+// ⇒ 每轮都失败,而新版明明就在 ~/.nvm/…/bin 里。候选顺序 = PATH 各目录 → 原生安装器 ~/.local/bin →
+// homebrew / usr-local → nvm 各版本。只管「绝对路径且文件不在」;裸名字照旧交给 PATH。
+// 返回 { bin, fallback }:fallback 非空 = 这次用的不是配置那条,调用方记一行日志让人去改配置。
+const FIXED_DIRS = ['/opt/homebrew/bin', '/usr/local/bin'] // 两个常见全局前缀;单测把它换成空,免得本机真实安装混进沙箱
+function locateBin(bin, { fixedDirs = FIXED_DIRS } = {}) {
+  if (!bin || !path.isAbsolute(bin) || isFile(bin)) return { bin, fallback: null }
+  const home = os.homedir()
+  const dirs = [...(process.env.PATH || '').split(path.delimiter), path.join(home, '.local', 'bin'), ...fixedDirs, ...nvmBinDirs(home)]
+  const name = path.basename(bin)
+  for (const d of dirs) {
+    if (!d) continue
+    const p = path.join(d, name)
+    if (p !== bin && isFile(p)) return { bin: p, fallback: p }
+  }
+  return { bin, fallback: null }
+}
+
 function resolveSpawn(bin, args) {
-  if (!IS_WIN) return { file: bin, spawnArgs: args }
+  const loc = locateBin(bin) // 所有起 agent 进程的地方(轮次 / 旗子探针 / 版本探针 / 登录态探针)都经这里,一处兜底全覆盖
+  bin = loc.bin
+  if (!IS_WIN) return { file: bin, spawnArgs: args, fallback: loc.fallback }
   const resolved = resolveWinExecutable(bin)
-  if (!resolved) return { file: bin, spawnArgs: args } // not found → let ENOENT surface with the caller's hint
+  if (!resolved) return { file: bin, spawnArgs: args, fallback: loc.fallback } // not found → let ENOENT surface with the caller's hint
   const ext = path.extname(resolved).toLowerCase()
   if (ext === '.cmd' || ext === '.bat') {
-    return { file: process.env.ComSpec || 'cmd.exe', spawnArgs: ['/d', '/s', '/c', resolved, ...args] }
+    return { file: process.env.ComSpec || 'cmd.exe', spawnArgs: ['/d', '/s', '/c', resolved, ...args], fallback: loc.fallback }
   }
-  return { file: resolved, spawnArgs: args } // real .exe → spawn directly, cleanest
+  return { file: resolved, spawnArgs: args, fallback: loc.fallback } // real .exe → spawn directly, cleanest
 }
 
 // A minimal `where`: resolve a bare command against PATH + PATHEXT. PATHEXT order
@@ -47,4 +77,4 @@ function resolveWinExecutable(bin) {
   return null
 }
 
-module.exports = { IS_WIN, resolveSpawn, resolveWinExecutable }
+module.exports = { IS_WIN, resolveSpawn, resolveWinExecutable, locateBin }

package/src/c2install.js

@@ -0,0 +1,117 @@
+'use strict'
+
+// First-install filesystem preparation only. Existing authorities and legacy
+// state are never adopted, cleared, migrated or replayed by this entry.
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { loadConfig, platformsConfigured } = require('./config')
+const { C2DurableJournal } = require('./core/c2durablejournal')
+const { validatePersistentState } = require('./core/c2persiststate')
+const { validatePersistentReceipts, validatePersistentRelation } = require('./core/c2persistrelation')
+const VALIDATORS = { validateState: validatePersistentState,
+  validateReceipts: validatePersistentReceipts, validateRelation: validatePersistentRelation }
+
+function loadInstallation(explicitConfig) {
+  const stateDir = path.join(os.homedir(), '.sbot')
+  const file = process.env.SBOT_C2_V2_JOURNAL || path.join(stateDir, 'c2-v2.log')
+  if (!path.isAbsolute(file) || file !== path.resolve(file) ||
+      path.dirname(file) !== stateDir || !/^c2-v2(?:[._-][a-zA-Z0-9._-]+)?\.log$/.test(path.basename(file))) {
+    throw new Error('The journal must be a c2-v2*.log file directly in the installation state directory')
+  }
+  const configFile = explicitConfig || process.env.SBOT_CONFIG || path.join(stateDir, 'config.json')
+  if (!path.isAbsolute(configFile) || !fs.existsSync(configFile)) {
+    throw new Error('An existing configuration file with an absolute path is required')
+  }
+  const cfg = loadConfig(configFile)
+  const configured = platformsConfigured(cfg)
+  const groups = Object.entries(cfg.groups || {})
+  if (groups.length !== 1) throw new Error('This release requires exactly one explicit Feishu group')
+  const [serviceChatId, group] = groups[0]
+  const provider = cfg.providers?.[group?.provider || cfg.defaultProvider]
+  if (path.resolve(cfg._path || '') !== path.resolve(configFile) ||
+      !configured.feishu || configured.wecom || configured.slack || cfg.wecom || cfg.slack ||
+      (cfg._groupPlatform?.inferred || []).length ||
+      !/^oc_[A-Za-z0-9_-]{1,124}$/.test(serviceChatId) || !group ||
+      group.platform !== 'feishu' || group.paused || group.board ||
+      group.crons && (!Array.isArray(group.crons) || group.crons.length) ||
+      provider?.runner !== 'codex' || group.codexSteer !== false || group.codexApp === true ||
+      cfg.alerts?.chatId || cfg.ui && cfg.ui.enabled !== false) {
+    throw new Error('This release accepts one explicit Feishu Codex message route, with codexSteer:false and without canvas, scheduled tasks, console or synthetic sources')
+  }
+  if (cfg.feishu.onlyWhenMentioned === true &&
+      !/^ou_[a-zA-Z0-9_-]+$/.test(cfg.feishu.botOpenId || '')) {
+    throw new Error('Mention-only messages require the Feishu botOpenId; otherwise set onlyWhenMentioned:false for the dedicated group')
+  }
+  if (typeof group.workdir !== 'string' || !path.isAbsolute(group.workdir) ||
+      !fs.existsSync(group.workdir) || !fs.statSync(group.workdir).isDirectory()) {
+    throw new Error('The group workdir must be an existing absolute project directory')
+  }
+  return { stateDir, file, cfg, groups, serviceChatId, provider }
+}
+
+function assertPrivateDirectory(dir) {
+  const stat = fs.lstatSync(dir)
+  if (!stat.isDirectory() || stat.isSymbolicLink() ||
+      typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+    throw new Error('The installation state directory must be a real directory owned by this user')
+  }
+}
+
+function absent(file, label) {
+  try { fs.lstatSync(file) } catch (error) { if (error.code === 'ENOENT') return; throw error }
+  throw new Error(`${label} already exists; initialization never overwrites or migrates existing state`)
+}
+
+function assertFirstInstall(stateDir, file) {
+  assertPrivateDirectory(stateDir)
+  for (const name of ['state.json', 'pending-turns.json', 'engine-receipts.json']) {
+    absent(path.join(stateDir, name), name)
+  }
+  absent(file, 'Journal')
+  // An independently named journal must not make existing authority disappear.
+  if (fs.readdirSync(stateDir).some(name => /^c2-v2.*\.log$/.test(name))) {
+    throw new Error('An existing journal requires review; initialization cannot replace its authority')
+  }
+}
+
+function initializeInstallation(explicitConfig) {
+  const { stateDir, file } = loadInstallation(explicitConfig)
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 })
+  assertFirstInstall(stateDir, file)
+  const lockFile = path.join(stateDir, 'daemon.lock')
+  // Unlike normal start, initialization refuses even stale locks.
+  absent(lockFile, 'Service lock')
+  let fd
+  let ownsLock = false
+  try {
+    fd = fs.openSync(lockFile, 'wx', 0o600)
+    ownsLock = true
+    fs.writeSync(fd, String(process.pid))
+    fs.fsyncSync(fd)
+    fs.closeSync(fd); fd = undefined
+    assertFirstInstall(stateDir, file)
+    fs.chmodSync(stateDir, 0o700)
+    C2DurableJournal.initialize(file, {
+      state: { version: 2, seq: 0, lanes: {} },
+      receipts: { pending: [], completed: [] },
+    }, VALIDATORS)
+    const journal = C2DurableJournal.open(file, VALIDATORS)
+    const snapshot = journal.snapshot()
+    if (journal.blocked || snapshot.cursor !== 0 || snapshot.eventCount !== 0 ||
+        snapshot.receipts.pending.length || snapshot.receipts.completed.length ||
+        snapshot.effects.size || snapshot.notices.size || Object.keys(snapshot.state.lanes).length) {
+      throw new Error('New journal verification failed; preserve the file for review')
+    }
+    return file
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd)
+    if (ownsLock) {
+      try {
+        if (fs.readFileSync(lockFile, 'utf8').trim() === String(process.pid)) fs.unlinkSync(lockFile)
+      } catch { /* Do not remove a lock that no longer belongs to this operation. */ }
+    }
+  }
+}
+
+module.exports = { loadInstallation, initializeInstallation, assertPrivateDirectory }

package/src/config.js

@@ -40,7 +40,8 @@ const DEFAULTS = {
   // 写死会**覆盖 CLI 的默认**,于是每次 Anthropic 出新一代,sbot 的默认就悄悄落后一代
   // (2026-08-03 核对时正卡在 opus-4-8,而 CLI 默认已是 Opus 5)。要钉死型号在控制台选。
   providers: { claude: {} },
-  // "<chatId>": { workdir, provider?, model?, allowedTools?: [], disallowedTools?: [] }
+  // "<chatId>": { workdir, provider?, model?, codexSteer?: false, allowedTools?: [], disallowedTools?: [] }
+  // codexSteer defaults on for Codex groups; explicit false opts out.
   // — one project per group; permissions are scoped to that group's own workdir.
   groups: {},
 }

package/src/core/c2cardeffectbridge.js

@@ -0,0 +1,51 @@
+'use strict'
+
+const { C2DurableRuntime } = require('./c2durableruntime')
+
+const RECEIPT_ID = /^[0-9a-f]{32}$/
+const GENERATION = /^[0-9a-f]{32}$/
+
+function nonempty(value) { return typeof value === 'string' && value.length > 0 }
+
+// This is deliberately narrower than a generic Feishu success check. A card
+// or message ID is required when later operations depend on that target. The
+// live target and SDK response remain in memory; only the runtime's hashed
+// operation identity and effect outcome may enter its journal.
+function confirmCardOperation(response, operation) {
+  if (!operation || typeof operation !== 'object') return false
+  switch (operation.kind) {
+    case 'card.create':
+      return response?.code === 0 && nonempty(response?.data?.card_id)
+    case 'message.reply':
+    case 'message.create':
+      return response?.code === 0 &&
+        nonempty(response?.data?.message_id || response?.message_id)
+    case 'cardElement.content':
+      return response === true
+    case 'card.update':
+    case 'card.settings':
+    case 'message.delete':
+      return response?.code === 0
+    default:
+      return false
+  }
+}
+
+// Pass the returned function only as Feishu's explicit operationBoundary for
+// this one live turn. Normal card behavior is unaffected unless the caller
+// opts in; a failed or ambiguous operation must propagate instead of falling
+// through to a second SDK call.
+function createC2CardEffectBoundary({ runtime, receiptId, chatId, turnToken,
+  generation, verifyGeneration } = {}) {
+  if (!(runtime instanceof C2DurableRuntime) || !RECEIPT_ID.test(receiptId) ||
+      !nonempty(chatId) || !Number.isSafeInteger(turnToken) || turnToken <= 0 ||
+      !GENERATION.test(generation) || typeof verifyGeneration !== 'function' ||
+      verifyGeneration.constructor?.name === 'AsyncFunction') {
+    throw new TypeError('C2 card effect bridge needs a live turn authority')
+  }
+  return operation => runtime.performOutboundCardOperation({ receiptId, chatId,
+    turnToken, generation, verifyGeneration, operation,
+    confirm: confirmCardOperation })
+}
+
+module.exports = { createC2CardEffectBoundary, confirmCardOperation }

package/src/core/c2cardterminalpath.js

@@ -0,0 +1,216 @@
+'use strict'
+
+// Opt-in, process-local composition for one message receipt. A streaming card's
+// earlier operations use independent outbound effects; its final card.update
+// belongs to the terminal finalReply effect and therefore cannot enter the
+// outbound executor a second time.
+const { createC2CardEffectBoundary, confirmCardOperation } = require('./c2cardeffectbridge')
+const { prepareTerminalEffectBridge, terminalReplyText } = require('./c2terminaleffectbridge')
+
+function prepareCardTerminalPath({ runtime, payloadHandles, platform, replyCtx,
+  receiptId, chatId, turnToken, generation, verifyGeneration,
+  applyLocalEffect, assertWriterLock, sendPlainReply = null, redactText = value => value,
+  now = Date.now } = {}) {
+  const receipt = runtime?.snapshot?.().receipts?.pending?.find(item => item.id === receiptId)
+  if (!receipt || receipt.source !== 'message' || receipt.chatId !== chatId ||
+      !replyCtx || replyCtx.chatId !== chatId ||
+      replyCtx.messageId !== receipt.sourceId ||
+      !platform || (typeof platform.createStreamingCard !== 'function' &&
+        typeof sendPlainReply !== 'function')) {
+    throw new TypeError('C2 card terminal path needs one exact message target')
+  }
+  if (sendPlainReply !== null && typeof sendPlainReply !== 'function') {
+    throw new TypeError('C2 plain reply needs one strict sender')
+  }
+  if (typeof redactText !== 'function' ||
+      redactText.constructor?.name === 'AsyncFunction') {
+    throw new TypeError('C2 card text redaction must be synchronous')
+  }
+  const targetCtx = Object.freeze({ ...replyCtx })
+  // Registration is durable before open() can expose any runner callback.
+  const terminal = prepareTerminalEffectBridge({ runtime, payloadHandles,
+    receiptId, chatId, turnToken, generation, verifyGeneration,
+    applyLocalEffect, assertWriterLock, now })
+  const operationBoundary = createC2CardEffectBoundary({ runtime, receiptId,
+    chatId, turnToken, generation, verifyGeneration })
+  let phase = 'prepared'
+  let card = null
+  let suppressedCard = false
+  const fail = error => { phase = 'closed'; runtime.close(); throw error }
+  const canUsePlain = before => {
+    if (!sendPlainReply || runtime.blocked) return false
+    const after = runtime.snapshot()
+    // The trusted platform adapter must route every card SDK call through the
+    // operation boundary. Once an outbound effect exists, even a rejected SDK
+    // response is ambiguous and a second delivery would risk a duplicate.
+    return after.cursor === before.cursor &&
+      after.effects.size === before.effects.size &&
+      [...after.effects.keys()].every(id => before.effects.has(id))
+  }
+
+  return Object.freeze({
+    async open({ suppressCard = false } = {}) {
+      if (phase !== 'prepared') throw new Error('C2 card terminal path already opened')
+      if (typeof suppressCard !== 'boolean') throw new TypeError('C2 card suppression must be boolean')
+      if (suppressCard) {
+        // A silent turn with no assistant output never exposed a card in v1.
+        // No platform operation or outbound effect is needed before settlement.
+        suppressedCard = true
+        phase = 'plain'
+        return false
+      }
+      phase = 'opening'
+      const before = runtime.snapshot()
+      if (typeof platform.createStreamingCard !== 'function') {
+        if (!canUsePlain(before)) return fail(new Error('C2 plain reply lacks unopened card proof'))
+        phase = 'plain'
+        return false
+      }
+      try {
+        card = await platform.createStreamingCard(targetCtx,
+          { operationKey: receiptId, operationBoundary })
+        if (!card && canUsePlain(before)) {
+          phase = 'plain'
+          return false
+        }
+        if (!card || typeof card.update !== 'function' ||
+            typeof card.flush !== 'function' || typeof card.finish !== 'function' ||
+            typeof card.recall !== 'function') {
+          throw new Error('C2 card terminal path has no durable card')
+        }
+        phase = 'open'
+        return true
+      } catch (error) {
+        if (canUsePlain(before)) {
+          phase = 'plain'
+          return false
+        }
+        return fail(error)
+      }
+    },
+    update(text) {
+      if (phase !== 'open' && phase !== 'plain') {
+        throw new Error('C2 card terminal path is not open')
+      }
+      if (suppressedCard) throw new Error('C2 suppressed card cannot stream an update')
+      if (typeof text !== 'string') throw new TypeError('C2 card update needs process-local text')
+      if (card) card.update(redactText(text))
+    },
+    async flushForTerminal() {
+      if (phase !== 'open' || !card || await card.flush() !== true) {
+        return fail(new Error('C2 stream frame flush unconfirmed'))
+      }
+      return true
+    },
+    cancellationTarget() {
+      if (!['open', 'recalled'].includes(phase) || !card ||
+          typeof card.durableTarget !== 'function') {
+        throw new Error('C2 cancellation card target unavailable')
+      }
+      const target = card.durableTarget()
+      if (target?.chatId !== chatId || !target.cardId || !target.msgId) {
+        throw new Error('C2 cancellation card target differs from turn')
+      }
+      return target
+    },
+    async recallForCancellation() {
+      if (phase === 'plain' && !card) {
+        phase = 'recalled'
+        return false
+      }
+      if (phase !== 'open' || !card) {
+        throw new Error('C2 cancellation has no open streaming card')
+      }
+      phase = 'recalling'
+      try {
+        if (await card.flush() !== true || await card.recall() !== true) {
+          throw new Error('C2 cancellation card recall unconfirmed')
+        }
+        phase = 'recalled'
+        return true
+      } catch (error) { return fail(error) }
+    },
+    async complete({ payload, replyText, paused = false, footer = '' } = {}) {
+      if (phase !== 'open' && phase !== 'plain') {
+        throw new Error('C2 card terminal path is not open')
+      }
+      phase = 'completing'
+      try {
+        const terminalPayload = payload && typeof payload === 'object' &&
+          !Array.isArray(payload) ? { ...payload } : null
+        if (!terminalPayload || terminalPayload.type !== 'finalizeEffectCommit' ||
+            terminalPayload.receiptId !== receiptId || terminalPayload.turnToken !== turnToken ||
+            typeof terminalPayload.quiet !== 'boolean' || terminalPayload.quiet !== receipt.quiet ||
+            typeof terminalPayload.resultText !== 'string' ||
+            typeof terminalPayload.bufferText !== 'string' ||
+            typeof footer !== 'string') {
+          throw new TypeError('C2 card terminal payload differs from running turn')
+        }
+        if (card && await card.flush() !== true) {
+          throw new Error('C2 card prior operations lack confirmed flush')
+        }
+        // Mirrors the private reducer's silent predicate. A posted card must
+        // be durably recalled before the zero-send quiet settlement.
+        const quiet = receipt.quiet || terminalPayload.resultText.trim() === 'NO_REPLY' ||
+          (!terminalPayload.resultText.trim() && terminalPayload.bufferText.trim() === 'NO_REPLY')
+        if (suppressedCard && !quiet) {
+          throw new Error('C2 suppressed card needs a silent terminal')
+        }
+        let result
+        if (quiet) {
+          if (replyText !== undefined) {
+            throw new Error('C2 quiet card cannot carry reply text')
+          }
+          if (card && await card.recall() !== true) {
+            throw new Error('C2 quiet card recall unconfirmed')
+          }
+          result = await terminal.complete({ payload: terminalPayload, paused })
+        } else {
+          if (typeof replyText !== 'string' || !replyText ||
+              replyText !== terminalReplyText(terminalPayload)) {
+            throw new TypeError('C2 visible card needs exact process-local final text')
+          }
+          const visibleText = redactText(replyText)
+          if (typeof visibleText !== 'string' || !visibleText) {
+            throw new TypeError('C2 visible card redaction removed final text')
+          }
+          result = await terminal.complete({ payload: terminalPayload, replyText, paused,
+            resolveTarget: item => ({ receiptId: item.id, chatId: item.chatId,
+              sourceId: item.sourceId, replyCtx: targetCtx }),
+            sendReply: async (target, text) => {
+              if (!card) {
+                // The caller supplies a strict single-call sender. The normal
+                // platform.reply has a hidden reply-to-direct-send retry and
+                // is therefore not suitable for a durable final effect.
+                return sendPlainReply(target, visibleText)
+              }
+              let calls = 0
+              const finished = await card.finish(visibleText, { footer,
+                terminalOperationBoundary: async operation => {
+                  if (!operation || operation.kind !== 'card.update' ||
+                      operation.cardId == null || typeof operation.invoke !== 'function' ||
+                      ++calls !== 1) {
+                    throw new Error('C2 final card needs exactly one update operation')
+                  }
+                  const response = await operation.invoke()
+                  if (!confirmCardOperation(response, operation)) {
+                    throw new Error('C2 final card update unconfirmed')
+                  }
+                  return response
+                },
+              })
+              return { finished, calls }
+            },
+            confirmReply: value => card
+              ? value?.finished === true && value.calls === 1
+              : value?.code === 0 && typeof (value.data?.message_id || value.message_id) === 'string' &&
+                !!(value.data?.message_id || value.message_id) })
+        }
+        phase = 'complete'
+        return result
+      } catch (error) { return fail(error) }
+    },
+  })
+}
+
+module.exports = { prepareCardTerminalPath }

package/src/core/c2durableingress.js

@@ -0,0 +1,148 @@
+'use strict'
+
+const { isDeepStrictEqual } = require('node:util')
+const { taskId } = require('./enginecheckpoint')
+const { platformMessageEventId } = require('./c2eventidentity')
+const { validatePersistentReceipts, validatePersistentRelation } = require('./c2persistrelation')
+const { EngineStepCoordinator } = require('./enginestepcoordinator')
+
+const RECEIPT_KEYS = ['id', 'source', 'chatId', 'sourceId', 'acceptedAt', 'quiet']
+const FLAGS = ['quiet', 'polled', 'synthetic', 'wantsAck', 'resetSessionAfter',
+  'emptyRetried', 'freshRetried', 'firstResumed', 'failedOver']
+const MESSAGE_ID = /^om_[A-Za-z0-9_-]{1,124}$/
+const SCOPE = /^[A-Za-z0-9_-]{1,128}$/
+
+function exactKeys(value, keys, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      Object.getPrototypeOf(value) !== Object.prototype ||
+      Reflect.ownKeys(value).length !== keys.length ||
+      Reflect.ownKeys(value).some(key => typeof key !== 'string' || !keys.includes(key) ||
+        !Object.getOwnPropertyDescriptor(value, key)?.enumerable ||
+        !Object.hasOwn(Object.getOwnPropertyDescriptor(value, key), 'value'))) {
+    throw new TypeError(`invalid C2 ${label}`)
+  }
+  return value
+}
+
+// Development-only first acceptance. The platform source ID must already be
+// stable, but its receipt is still a candidate here. Identity and receipt are
+// published only by the same fsynced queue transition; a crash before commit
+// leaves neither accepted. The daemon's single-writer lock is required.
+class C2DurableIngress {
+  #journal
+  #host
+  #startupBlocked
+  #gate = null
+
+  constructor(journal, { host = null } = {}) {
+    if (!journal || typeof journal.snapshot !== 'function' ||
+        typeof journal.hasEvent !== 'function' ||
+        typeof journal.appendTransition !== 'function') {
+      throw new TypeError('C2 durable ingress needs a journal')
+    }
+    this.#journal = journal
+    this.#host = host || new EngineStepCoordinator({ journal })
+    if (host && (typeof host.snapshot !== 'function' || typeof host.prepare !== 'function' ||
+        host.blocked || !isDeepStrictEqual(host.snapshot(), journal.snapshot().state))) {
+      throw new Error('C2 ingress coordinator differs from durable authority')
+    }
+    // A newly constructed adapter has no proof of prior payloads, callbacks
+    // or external effects. Only a fresh genesis may admit first acceptance;
+    // formal startup recovery must supply a separate verified reopen path.
+    const snapshot = journal.snapshot()
+    this.#startupBlocked = snapshot.cursor !== 0 ||
+      snapshot.receipts.pending.length !== 0 ||
+      Object.keys(snapshot.state.lanes).length !== 0
+  }
+
+  // Recovery may settle old receipts, but it cannot recreate lost payloads or
+  // runner handles. A new ingress adapter is authorized only by the opened
+  // startup gate and a completely quiescent durable snapshot.
+  static resumeAfterVerifiedRecovery({ journal, coordinator, gate } = {}) {
+    if (!journal || !coordinator || typeof coordinator.snapshot !== 'function' ||
+        coordinator.blocked ||
+        !gate || typeof gate.isClosed !== 'function' || gate.isClosed() !== false ||
+        journal.blocked) throw new Error('C2 ingress recovery gate is not verified open')
+    const snapshot = journal.snapshot()
+    if (snapshot.state?.version !== 2 || snapshot.cursor !== snapshot.state.seq ||
+        !isDeepStrictEqual(coordinator.snapshot(), snapshot.state) ||
+        !snapshot.effects || !(snapshot.effects instanceof Map) ||
+        !snapshot.notices || !(snapshot.notices instanceof Map)) {
+      throw new Error('C2 ingress differs from verified durable authority')
+    }
+    validatePersistentReceipts(snapshot.receipts)
+    validatePersistentRelation(snapshot.state, snapshot.receipts)
+    const lanes = snapshot.state.lanes
+    const unresolved = snapshot.receipts.pending.length > 0 ||
+      Object.values(lanes.queue || {}).some(lane => lane.queue.length > 0) ||
+      [...snapshot.effects].some(([effectId, status]) => status !== 'acked' &&
+        !(status === 'notStarted' && journal.runnerNotStartedProofs().some(proof =>
+          proof.dispatchEffectId === effectId && journal.hasEvent(
+            `sbot-c2-runner-not-started-commit-v1:${proof.receiptId}:${proof.turnToken}:${proof.generation}`)))) ||
+      [...snapshot.notices.values()].some(notice =>
+        notice.status === 'attempting' || notice.status === 'unknown') ||
+      Object.values(lanes.lifecycle || {}).some(lane => lane.busy || lane.controller) ||
+      Object.values(lanes.turn || {}).some(lane => lane.active !== null) ||
+      Object.values(lanes.terminal || {}).some(lane => lane.finalized) ||
+      Object.values(lanes.handoff || {}).some(lane => lane.phase !== 'idle') ||
+      Object.values(lanes.intake || {}).some(lane => lane.pending !== null) ||
+      Object.values(lanes.session || {}).some(lane => !lane.settled)
+    if (unresolved) throw new Error('C2 ingress has unresolved durable or host work')
+    const ingress = new C2DurableIngress(journal, { host: coordinator })
+    ingress.#startupBlocked = false
+    ingress.#gate = gate
+    return ingress
+  }
+
+  get blocked() { return this.#startupBlocked || this.#host.blocked || this.#journal.blocked ||
+    (this.#gate !== null && this.#gate.isClosed() !== false) }
+  snapshot() { return this.#journal.snapshot() }
+
+  enqueueMessage({ receipt, flags, front = false } = {}) {
+    if (this.blocked) throw new Error('C2 ingress closed pending startup recovery')
+    exactKeys(receipt, RECEIPT_KEYS, 'message receipt')
+    exactKeys(flags, FLAGS, 'queue flags')
+    if (receipt.source !== 'message' || typeof receipt.sourceId !== 'string' ||
+        !MESSAGE_ID.test(receipt.sourceId) || typeof receipt.chatId !== 'string' ||
+        !SCOPE.test(receipt.chatId) || ['__proto__', 'constructor', 'prototype'].includes(receipt.chatId) ||
+        receipt.id !== taskId(receipt) ||
+        flags.quiet !== receipt.quiet || flags.synthetic !== false ||
+        typeof front !== 'boolean') {
+      throw new TypeError('C2 ingress needs a stable platform message and matching flags')
+    }
+    for (const key of FLAGS) {
+      if (typeof flags[key] !== 'boolean') throw new TypeError(`invalid C2 queue flag ${key}`)
+    }
+    validatePersistentReceipts({ pending: [receipt], completed: [] })
+    const before = this.#journal.snapshot()
+    if (before.state.version !== 2 || this.#host.snapshot().seq !== before.cursor ||
+        !isDeepStrictEqual(this.#host.snapshot(), before.state)) {
+      throw new Error('C2 ingress differs from durable authority')
+    }
+    if (before.receipts.pending.some(item => item.id === receipt.id) ||
+        before.receipts.completed.some(item => item.id === receipt.id)) {
+      throw new Error('C2 message receipt already accepted')
+    }
+    const id = platformMessageEventId({ receiptId: receipt.id, domain: 'queue',
+      kind: 'enqueue', lookupReceipt: lookupId => lookupId === receipt.id ? receipt : null })
+    if (this.#journal.hasEvent(id)) throw new Error('C2 platform event already committed')
+    const job = { id: `receipt:job:${receipt.id}` }
+    for (const key of FLAGS) job[key] = flags[key]
+    const receipts = { pending: [...before.receipts.pending, structuredClone(receipt)],
+      completed: before.receipts.completed }
+    const prepared = this.#host.prepare({ id, domain: 'queue', scope: receipt.chatId,
+      ...(before.state.lanes.queue?.[receipt.chatId] ? {} : { seed: { queue: [] } }),
+      payload: { type: 'enqueue', job, front }, receipts,
+      validate: result => {
+        const lane = result.state?.lanes?.queue?.[receipt.chatId]
+        if (!lane || !Array.isArray(lane.queue) ||
+            lane.queue.filter(item => item.id === job.id).length !== 1 ||
+            result.effects.length !== 0) {
+          throw new Error('C2 ingress returned invalid queue result')
+        }
+      } })
+    return prepared.commit()
+  }
+}
+
+module.exports = { C2DurableIngress }