sintbot 1.3.0 → 1.4.1

package/src/c2incident.js

@@ -0,0 +1,125 @@
+'use strict'
+
+// Operator tool for a group the service holds after an unresolved fault.
+// With the service stopped and the writer lock held, it moves that group's
+// journal unchanged under <data>/incidents/, records the source messages it
+// left unsettled and the receipts it had settled, then gives the group a new
+// empty journal under the same mapped name. Nothing is settled, rewritten,
+// replayed or notified; every later start refuses those messages from
+// incident.json (see loadC2IncidentQuarantine).
+const fs = require('node:fs')
+const path = require('node:path')
+const { createHash } = require('node:crypto')
+const { C2DurableJournal } = require('./core/c2durablejournal')
+const { assertJournalScope, assertPrivateDirectory, VALIDATORS } = require('./c2install')
+
+const GROUP_ID = /^oc_[A-Za-z0-9_-]{1,124}$/
+const FEISHU_MESSAGE_ID = /^om_[A-Za-z0-9_-]{1,124}$/
+const SCHEMA = 'sbot-c2-incident-seal-v1'
+
+const sha256 = file => createHash('sha256').update(fs.readFileSync(file)).digest('hex')
+function privateFile(file, label) {
+  const st = fs.lstatSync(file)
+  if (!st.isFile() || st.isSymbolicLink() ||
+      typeof process.getuid === 'function' && st.uid !== process.getuid() ||
+      process.platform !== 'win32' && (st.mode & 0o077)) {
+    throw new Error(`${label} is not a private regular file owned by this user; preserve it and review`)
+  }
+  return st
+}
+function writeNew(file, value) {
+  const fd = fs.openSync(file, 'wx', 0o600)
+  try { fs.writeSync(fd, JSON.stringify(value, null, 2) + '\n'); fs.fsyncSync(fd) }
+  finally { fs.closeSync(fd) }
+}
+function fsyncDir(dir) {
+  const fd = fs.openSync(dir, 'r')
+  try { fs.fsyncSync(fd) } finally { fs.closeSync(fd) }
+}
+const pad = n => String(n).padStart(2, '0')
+function stamp(ms) {
+  const d = new Date(ms)
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`
+}
+
+function sealC2GroupIncident({ installation, chatId, reason = 'operator sealed a held group',
+  now = Date.now, acquireLock = require('./core/instancelock').acquire, version = '' } = {}) {
+  if (typeof chatId !== 'string' || !GROUP_ID.test(chatId)) {
+    throw new Error('Name the held group with --group oc_…')
+  }
+  if (typeof reason !== 'string' || !reason.trim() || reason.length > 500) {
+    throw new Error('The incident reason must be 1 to 500 characters')
+  }
+  const { stateDir, routes } = installation || {}
+  const route = routes?.find(item => item.chatId === chatId)
+  if (!route) throw new Error('This group is not in the configuration')
+  if ((installation.addedRoutes || []).some(item => item.chatId === chatId)) {
+    throw new Error('This group has no journal yet; nothing to seal')
+  }
+  assertPrivateDirectory(stateDir)
+  const lockFile = path.join(stateDir, 'daemon.lock')
+  const lock = acquireLock(lockFile)
+  if (!lock?.ok) throw new Error('The service is running; stop it before sealing an incident')
+  const held = () => {
+    try { return fs.readFileSync(lockFile, 'utf8').trim() === String(process.pid) } catch { return false }
+  }
+  try {
+    const file = route.file
+    const stat = privateFile(file, 'The group journal')
+    const before = { sha256: sha256(file), bytes: stat.size }
+    let journal
+    try { journal = C2DurableJournal.open(file, VALIDATORS) } catch (error) {
+      throw new Error(`The group journal cannot be read (${error.message}); preserve it unchanged and review it manually`)
+    }
+    const snapshot = assertJournalScope(journal, chatId)
+    let settled = true
+    try { assertJournalScope(journal, chatId, { requireSettled: true }) } catch { settled = false }
+    if (settled) throw new Error('This group journal is settled; nothing to seal. Start the service normally')
+    if (sha256(file) !== before.sha256) {
+      throw new Error('Opening the group journal changed it; preserve every file for review')
+    }
+    const pending = snapshot.receipts.pending
+    if (pending.some(item => item.source !== 'message' || !FEISHU_MESSAGE_ID.test(item.sourceId))) {
+      throw new Error('The journal holds a receipt that is not a Feishu message; review it manually')
+    }
+    const incidents = path.join(stateDir, 'incidents')
+    fs.mkdirSync(incidents, { recursive: true, mode: 0o700 })
+    fs.chmodSync(incidents, 0o700)
+    const sealedAt = now()
+    const dir = path.join(incidents, `${stamp(sealedAt)}-group-${chatId.slice(-8)}`)
+    fs.mkdirSync(dir, { mode: 0o700 })
+    writeNew(path.join(dir, 'incident.json'), { schema: SCHEMA, chatId,
+      journal: path.basename(file), sha256: before.sha256, bytes: before.bytes,
+      cursor: snapshot.cursor,
+      pending: pending.map(item => ({ id: item.id, sourceId: item.sourceId })),
+      completedReceiptIds: snapshot.receipts.completed.map(item => item.id),
+      sealedAt, reason: reason.trim(),
+      handling: 'frozen unchanged; receipts not settled; turn not replayed; source messages refused at admission from incident.json',
+      tool: 'sintbot incident seal', version })
+    if (!held()) throw new Error('The writer lock was lost before sealing; preserve every file for review')
+    const sealed = path.join(dir, path.basename(file))
+    fs.renameSync(file, sealed)
+    fsyncDir(stateDir); fsyncDir(dir)
+    if (sha256(sealed) !== before.sha256 || fs.existsSync(file)) {
+      throw new Error('The sealed journal differs; preserve every file for review')
+    }
+    if (!held()) throw new Error('The writer lock was lost before the new journal; preserve every file for review')
+    C2DurableJournal.initialize(file, { state: { version: 2, seq: 0, lanes: {} },
+      receipts: { pending: [], completed: [] } }, VALIDATORS)
+    fs.chmodSync(file, 0o600)
+    const fresh = C2DurableJournal.open(file, VALIDATORS)
+    const empty = assertJournalScope(fresh, chatId, { requireSettled: true })
+    if (fresh.blocked || empty.cursor !== 0 || empty.eventCount !== 0 ||
+        empty.receipts.pending.length || empty.receipts.completed.length ||
+        empty.effects.size || empty.notices.size || Object.keys(empty.state.lanes).length) {
+      throw new Error('New group journal verification failed; preserve every file for review')
+    }
+    const result = Object.freeze({ incident: dir, sealed, sealedSha256: before.sha256,
+      newJournal: file, newJournalSha256: sha256(file),
+      refusedSources: pending.length, settledRemembered: snapshot.receipts.completed.length })
+    writeNew(path.join(dir, 'result.json'), result)
+    return result
+  } finally { lock.release() }
+}
+
+module.exports = { sealC2GroupIncident }

package/src/c2install.js

@@ -5,49 +5,222 @@
 const fs = require('node:fs')
 const os = require('node:os')
 const path = require('node:path')
-const { loadConfig, platformsConfigured } = require('./config')
+const { createHash } = require('node:crypto')
+const { isDeepStrictEqual } = require('node:util')
+const { loadConfig, normalizeConfig, 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 GROUP_ID = /^oc_[A-Za-z0-9_-]{1,124}$/
+const MANIFEST = 'c2-groups.json'
+const SUPPORTED_RUNNERS = Object.freeze(['codex', 'claude'])
+
+// The executable a route will spawn must answer --version before the route
+// can serve. Successful probes are cached per executable for this process.
+const probedExecutables = new Set()
+function assertRunnerExecutable(provider, cfg, { spawnSync = require('node:child_process').spawnSync } = {}) {
+  const isCodex = provider?.runner === 'codex'
+  if (!isCodex && provider?.runner !== 'claude') throw new Error('Unsupported model runner')
+  const bin = isCodex ? (provider.bin || 'codex') : (cfg?.agent?.bin || 'claude')
+  const key = `${provider.runner}\0${bin}`
+  if (probedExecutables.has(key)) return true
+  const probe = spawnSync(bin, ['--version'], {
+    encoding: 'utf8', timeout: 10_000, maxBuffer: 64 * 1024,
+    env: { ...process.env, ...(provider.env || {}) } })
+  if (probe.error || probe.status !== 0 || !(isCodex ? /codex/i : /claude/i).test(probe.stdout || '')) {
+    throw new Error(isCodex
+      ? 'Codex executable preflight failed; install and sign in to Codex, then check the configured executable.'
+      : 'Claude Code executable preflight failed; install and sign in to Claude Code, then check the configured executable.')
+  }
+  probedExecutables.add(key)
+  return true
+}
+
+function installationStateDir(dataDir) {
+  const stateDir = dataDir === undefined ? path.join(os.homedir(), '.sbot') : dataDir
+  if (typeof stateDir !== 'string' || !path.isAbsolute(stateDir) ||
+      stateDir !== path.resolve(stateDir) || stateDir === path.parse(stateDir).root) {
+    throw new Error('The data directory must be a normalized absolute private directory')
   }
+  return stateDir
+}
+
+function loadInstallation(explicitConfig, { dataDir, allowAddedGroups = false } = {}) {
+  const stateDir = installationStateDir(dataDir)
   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)
+  return resolveInstallation(loadConfig(configFile), configFile, stateDir, { allowAddedGroups })
+}
+
+function loadInstallationFromRaw(raw, configFile, { dataDir, allowAddedGroups = false } = {}) {
+  const stateDir = installationStateDir(dataDir)
+  if (typeof configFile !== 'string' || !path.isAbsolute(configFile)) {
+    throw new Error('Configuration requires an absolute path')
+  }
+  return resolveInstallation(normalizeConfig(raw, configFile, { registerSecrets: false }), configFile, stateDir,
+    { allowAddedGroups })
+}
+
+// An online group addition may extend the persisted mapping: every mapped
+// group keeps its exact journal and each new group has no journal file yet.
+function mappingExtends(persisted, manifest, stateDir) {
+  const groups = Array.isArray(persisted?.groups) ? persisted.groups : null
+  if (!groups || persisted.version !== 1 ||
+      !isDeepStrictEqual({ ...persisted, groups: manifest.groups }, manifest) ||
+      !groups.every(group => manifest.groups.some(item => isDeepStrictEqual(item, group)))) return false
+  return manifest.groups.filter(item => !groups.some(group => group.chatId === item.chatId))
+    .every(item => !fs.existsSync(path.join(stateDir, item.journal)))
+}
+
+function resolveInstallation(cfg, configFile, stateDir, { allowAddedGroups = false } = {}) {
   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]
+  const groups = Object.entries(cfg.groups || {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+  if (groups.length < 1 || groups.length > 32) {
+    throw new Error('This release requires 1 to 32 explicit Feishu groups')
+  }
   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')
+      (cfg._groupPlatform?.inferred || []).length || cfg.alerts?.chatId) {
+    throw new Error('This release accepts explicit Feishu message routes without synthetic sources')
   }
+  if (!Number.isSafeInteger(cfg.agent.maxConcurrent) || cfg.agent.maxConcurrent < 1 ||
+      cfg.agent.maxConcurrent > 32) throw new Error('maxConcurrent must be an integer from 1 to 32')
   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')
+    throw new Error('Mention-only messages require the Feishu botOpenId; otherwise set onlyWhenMentioned:false')
+  }
+  const override = process.env.SBOT_C2_V2_JOURNAL
+  if (override && groups.length !== 1) throw new Error('A shared journal override cannot be used for multiple groups')
+  // A persisted mapping keeps each group's journal name, so a one-group
+  // installation (c2-v2.log) can grow without renaming live authority.
+  const manifestFile = path.join(stateDir, MANIFEST)
+  let persisted = null
+  if (fs.existsSync(manifestFile)) {
+    const st = fs.lstatSync(manifestFile)
+    if (!st.isFile() || st.isSymbolicLink() ||
+        typeof process.getuid === 'function' && st.uid !== process.getuid()) {
+      throw new Error('Group journal mapping is not an owned regular file')
+    }
+    persisted = JSON.parse(fs.readFileSync(manifestFile, 'utf8'))
   }
-  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')
+  const mappedJournal = new Map((Array.isArray(persisted?.groups) ? persisted.groups : [])
+    .filter(item => item && typeof item.chatId === 'string' && typeof item.journal === 'string')
+    .map(item => [item.chatId, item.journal]))
+  // A provider without an explicit runner has always meant Claude Code. The
+  // durable route requires the explicit name, so normalize it in memory only.
+  for (const provider of Object.values(cfg.providers || {})) {
+    if (provider && typeof provider === 'object' && provider.runner === undefined) provider.runner = 'claude'
+  }
+  const routes = groups.map(([chatId, group]) => {
+    if (!GROUP_ID.test(chatId) || !group || group.platform !== 'feishu') {
+      throw new Error('Every configured group must have an explicit Feishu identity')
+    }
+    if (group.paused !== undefined && typeof group.paused !== 'boolean') {
+      throw new Error('Group paused must be a boolean')
+    }
+    if (group.codexSteer !== undefined && typeof group.codexSteer !== 'boolean') {
+      throw new Error('Group codexSteer must be a boolean')
+    }
+    const provider = cfg.providers?.[group.provider || cfg.defaultProvider]
+    // Paused routes keep their original metadata, but cannot execute it. They
+    // must pass the full active-route checks before a later restart enables them.
+    if (!group.paused && (group.board ||
+        group.crons && (!Array.isArray(group.crons) || group.crons.length) ||
+        !SUPPORTED_RUNNERS.includes(provider?.runner) || group.codexApp === true)) {
+      throw new Error('Active groups require Codex or Claude Code without canvas, scheduled tasks or desktop App integration')
+    }
+    if (!group.paused && (typeof group.workdir !== 'string' || !path.isAbsolute(group.workdir) ||
+        !fs.existsSync(group.workdir) || !fs.statSync(group.workdir).isDirectory())) {
+      throw new Error('Each active group workdir must be an existing absolute project directory')
+    }
+    const base = mappedJournal.get(chatId) || (groups.length === 1 ? 'c2-v2.log' :
+      `c2-v2-group-${createHash('sha256').update(chatId).digest('hex').slice(0, 24)}.log`)
+    const file = override || path.join(stateDir, base)
+    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')
+    }
+    return { chatId, group, provider, file, paused: group.paused === true }
+  })
+  if (!routes.some(route => !route.paused)) throw new Error('At least one configured group must be active')
+  const manifest = { version: 1, groups: routes.map(({ chatId, file }) => ({ chatId, journal: path.basename(file) })) }
+  let addedRoutes = []
+  if (persisted) {
+    if (persisted.migrationSha256 !== undefined) {
+      if (!/^[a-f0-9]{64}$/.test(persisted.migrationSha256)) {
+        throw new Error('Group journal migration binding is invalid')
+      }
+      manifest.migrationSha256 = persisted.migrationSha256
+    }
+    if (!isDeepStrictEqual(persisted, manifest)) {
+      if (!(allowAddedGroups && mappingExtends(persisted, manifest, stateDir))) {
+        throw new Error('Group journal mapping differs; preserve existing authority and review configuration migration')
+      }
+      addedRoutes = routes.filter(route => !mappedJournal.has(route.chatId))
+    }
+    const expected = new Set(routes.map(route => path.basename(route.file)))
+    if (fs.readdirSync(stateDir).some(name => /^c2-v2.*\.log$/.test(name) && !expected.has(name))) {
+      throw new Error('Unmapped existing journal requires review; no authority may be silently ignored')
+    }
+  }
+  if (routes.length === 1 && !persisted && fs.existsSync(stateDir)) {
+    const selected = path.basename(routes[0].file)
+    if (fs.readdirSync(stateDir).some(name => /^c2-v2.*\.log$/.test(name) && name !== selected)) {
+      throw new Error('Unmapped existing journal requires review; legacy single-group authority cannot hide other logs')
+    }
+  }
+  const first = routes[0]
+  return { stateDir, file: first.file, cfg, groups, routes, addedRoutes,
+    serviceChatId: first.chatId, provider: first.provider, manifestFile, manifest }
+}
+
+function assertJournalScope(journal, chatId, { requireSettled = false } = {}) {
+  if (!GROUP_ID.test(chatId)) throw new Error('Journal group identity invalid')
+  const snap = journal.snapshot()
+  for (const lanes of Object.values(snap.state.lanes)) {
+    if (Object.keys(lanes).some(scope => scope !== chatId)) throw new Error('Journal contains another group scope')
+  }
+  if (snap.receipts.pending.some(receipt => receipt.chatId !== chatId) ||
+      [...snap.notices.values()].some(notice => notice.chatId !== chatId) ||
+      [...snap.effects.keys()].some(id => journal.effectDescriptor(id)?.scope !== chatId) ||
+      journal.runnerClosedProofs().some(proof => proof.chatId !== chatId) ||
+      journal.runnerNotStartedProofs().some(proof => proof.chatId !== chatId)) {
+    throw new Error('Journal receipts or effects belong to another group')
+  }
+  if (requireSettled && (snap.receipts.pending.length ||
+      [...snap.effects.values()].some(status => status !== 'acked') ||
+      [...snap.notices.values()].some(notice => ['attempting', 'unknown'].includes(notice.status)) ||
+      Object.values(snap.state.lanes.turn || {}).some(lane => lane.active !== null) ||
+      Object.values(snap.state.lanes.handoff || {}).some(lane => lane.phase !== 'idle') ||
+      Object.values(snap.state.lanes.lifecycle || {}).some(lane => lane.busy || lane.controller) ||
+      Object.values(snap.state.lanes.queue || {}).some(lane => lane.queue.length) ||
+      Object.values(snap.state.lanes.session || {}).some(lane => lane.settled !== true) ||
+      ['terminal', 'stopIntent', 'cardCleanup', 'steer'].some(domain => Object.keys(snap.state.lanes[domain] || {}).length))) {
+    throw new Error('Group journal has unresolved work; preserve it and explicitly review recovery')
+  }
+  return snap
+}
+
+function assertInstallationJournals(installation) {
+  const { routes, manifestFile } = installation
+  if (routes.length > 1 && !fs.existsSync(manifestFile)) {
+    throw new Error('No initialized journal mapping; initialize a new data directory or review existing state migration')
+  }
+  const adding = new Set((installation.addedRoutes || []).map(route => route.chatId))
+  for (const route of routes) {
+    if (adding.has(route.chatId)) continue
+    let st
+    try { st = fs.lstatSync(route.file) } catch {}
+    if (!st?.isFile() || st.isSymbolicLink() ||
+        typeof process.getuid === 'function' && st.uid !== process.getuid()) {
+      throw new Error('No initialized journal; initialize a new installation and preserve existing state')
+    }
   }
-  return { stateDir, file, cfg, groups, serviceChatId, provider }
 }
 
 function assertPrivateDirectory(dir) {
@@ -68,6 +241,7 @@ function assertFirstInstall(stateDir, file) {
   for (const name of ['state.json', 'pending-turns.json', 'engine-receipts.json']) {
     absent(path.join(stateDir, name), name)
   }
+  absent(path.join(stateDir, MANIFEST), 'Group journal mapping')
   absent(file, 'Journal')
   // An independently named journal must not make existing authority disappear.
   if (fs.readdirSync(stateDir).some(name => /^c2-v2.*\.log$/.test(name))) {
@@ -75,8 +249,9 @@ function assertFirstInstall(stateDir, file) {
   }
 }
 
-function initializeInstallation(explicitConfig) {
-  const { stateDir, file } = loadInstallation(explicitConfig)
+function initializeInstallation(explicitConfig, options) {
+  const installation = loadInstallation(explicitConfig, options)
+  const { stateDir, file, routes, manifestFile, manifest } = installation
   fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 })
   assertFirstInstall(stateDir, file)
   const lockFile = path.join(stateDir, 'daemon.lock')
@@ -92,17 +267,25 @@ function initializeInstallation(explicitConfig) {
     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')
+    for (const route of routes) {
+      C2DurableJournal.initialize(route.file, {
+        state: { version: 2, seq: 0, lanes: {} },
+        receipts: { pending: [], completed: [] },
+      }, VALIDATORS)
+      const journal = C2DurableJournal.open(route.file, VALIDATORS)
+      const snapshot = assertJournalScope(journal, route.chatId, { requireSettled: true })
+      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')
+      }
     }
+    // Last write commits the complete mapping. A partial initialization is
+    // deliberately preserved and rejected, never silently retried or erased.
+    const mappingFd = fs.openSync(manifestFile, 'wx', 0o600)
+    try { fs.writeSync(mappingFd, JSON.stringify(manifest, null, 2) + '\n'); fs.fsyncSync(mappingFd) }
+    finally { fs.closeSync(mappingFd) }
+
     return file
   } finally {
     if (fd !== undefined) fs.closeSync(fd)
@@ -114,4 +297,31 @@ function initializeInstallation(explicitConfig) {
   }
 }
 
-module.exports = { loadInstallation, initializeInstallation, assertPrivateDirectory }
+// Start-time registration of groups added to the configuration: each gets an
+// empty verified journal, then the mapping is extended in one replacement.
+// Existing journals are never touched; a group with legacy history is refused.
+function registerAddedGroups(installation) {
+  const { stateDir, addedRoutes = [], manifestFile, manifest } = installation
+  if (!addedRoutes.length) return []
+  const { assertNoLegacyGroupState } = require('./c2migration')
+  for (const route of addedRoutes) assertNoLegacyGroupState({ stateDir, chatId: route.chatId })
+  for (const route of addedRoutes) {
+    absent(route.file, 'Journal for a newly added group')
+    C2DurableJournal.initialize(route.file, {
+      state: { version: 2, seq: 0, lanes: {} }, receipts: { pending: [], completed: [] },
+    }, VALIDATORS)
+    const journal = C2DurableJournal.open(route.file, VALIDATORS)
+    const snapshot = assertJournalScope(journal, route.chatId, { requireSettled: true })
+    if (journal.blocked || snapshot.cursor !== 0 || snapshot.eventCount !== 0) {
+      throw new Error('New group journal verification failed; preserve the file for review')
+    }
+  }
+  const { atomicWriteJSON } = require('./core/store')
+  atomicWriteJSON(manifestFile, manifest, { mode: 0o600 })
+  installation.addedRoutes = []
+  return addedRoutes.map(route => route.chatId)
+}
+
+module.exports = { registerAddedGroups, loadInstallation, loadInstallationFromRaw, initializeInstallation, assertPrivateDirectory,
+  assertJournalScope, assertInstallationJournals, assertRunnerExecutable, SUPPORTED_RUNNERS, MANIFEST,
+  VALIDATORS }

package/src/c2migration.js

@@ -0,0 +1,100 @@
+'use strict'
+
+// Admission boundary for a reviewed legacy cut. This never settles an old
+// receipt or replays an effect; it only verifies immutable migration evidence
+// and excludes pre-cut platform messages before durable receipt admission.
+const fs = require('node:fs')
+const path = require('node:path')
+const { createHash } = require('node:crypto')
+const { isDeepStrictEqual } = require('node:util')
+const SHA = /^[a-f0-9]{64}$/
+const CHAT = /^oc_[A-Za-z0-9_-]{1,124}$/
+const SOURCE = /^om_[A-Za-z0-9_-]{1,124}$/
+const sha = bytes => createHash('sha256').update(bytes).digest('hex')
+const fail = () => { throw new Error('C2 migration evidence or admission fence differs; preserve all authorities') }
+function readPrivate(file) {
+  const stat = fs.lstatSync(file)
+  if (!stat.isFile() || stat.isSymbolicLink() ||
+      typeof process.getuid === 'function' && stat.uid !== process.getuid() ||
+      process.platform !== 'win32' && (stat.mode & 0o077)) fail()
+  return fs.readFileSync(file)
+}
+function loadC2MigrationFence({ stateDir, routes } = {}) {
+  if (!path.isAbsolute(stateDir || '') || !Array.isArray(routes) || !routes.length) fail()
+  const mappingFile = path.join(stateDir, 'c2-groups.json')
+  const fenceFile = path.join(stateDir, 'c2-migration.json')
+  let mapping
+  if (fs.existsSync(mappingFile)) mapping = JSON.parse(readPrivate(mappingFile))
+  const expectedHash = mapping?.migrationSha256
+  if (expectedHash === undefined && !fs.existsSync(fenceFile) &&
+      !fs.existsSync(path.join(stateDir, 'legacy-evidence'))) return null
+  if (!SHA.test(expectedHash || '')) fail()
+  const bytes = readPrivate(fenceFile)
+  if (sha(bytes) !== expectedHash) fail()
+  const fence = JSON.parse(bytes)
+  const expectedGroups = routes.map(route => ({ chatId: route.chatId, journal: path.basename(route.file) }))
+    .sort((a, b) => a.chatId < b.chatId ? -1 : a.chatId > b.chatId ? 1 : 0)
+  // Groups bound after the cut extend the mapping; every migrated group must
+  // keep its exact journal, and an added group must have no legacy state.
+  const fenced = Array.isArray(fence.groups) ? fence.groups : []
+  const expectedById = new Map(expectedGroups.map(group => [group.chatId, group]))
+  if (mapping.version !== 1 || fence.schema !== 'sbot-c2-legacy-migration-v1' ||
+      !fenced.length || new Set(fenced.map(group => group?.chatId)).size !== fenced.length ||
+      fenced.some(group => !isDeepStrictEqual(expectedById.get(group?.chatId), group)) ||
+      !isDeepStrictEqual(mapping.groups, expectedGroups) ||
+      !Number.isSafeInteger(fence.createdAt) || fence.createdAt <= 0 ||
+      !Array.isArray(fence.evidence) || !fence.evidence.length ||
+      !Array.isArray(fence.fences) || fence.fences.length !== fenced.length) fail()
+  const evidenceDir = path.join(stateDir, 'legacy-evidence')
+  const dirStat = fs.lstatSync(evidenceDir)
+  if (!dirStat.isDirectory() || dirStat.isSymbolicLink() ||
+      typeof process.getuid === 'function' && dirStat.uid !== process.getuid() ||
+      process.platform !== 'win32' && (dirStat.mode & 0o077)) fail()
+  const names = new Set()
+  for (const item of fence.evidence) {
+    if (!item || typeof item.file !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,160}$/.test(item.file) ||
+        !SHA.test(item.sha256 || '') || names.has(item.file)) fail()
+    names.add(item.file)
+    if (sha(readPrivate(path.join(evidenceDir, item.file))) !== item.sha256) fail()
+  }
+  for (const required of ['state-before.json', 'config-before.json', 'service-before.plist', 'review.json']) {
+    if (!names.has(required)) fail()
+  }
+  const legacy = JSON.parse(readPrivate(path.join(evidenceDir, 'state-before.json')))
+  const watermarks = new Map(), excluded = new Map()
+  for (const item of fence.fences) {
+    if (!item || !CHAT.test(item.chatId || '') || watermarks.has(item.chatId) ||
+        !fenced.some(group => group.chatId === item.chatId) ||
+        !Number.isSafeInteger(item.watermark) || item.watermark < 0 ||
+        item.watermark !== (legacy.groups?.[item.chatId]?.watermark || 0) ||
+        !Array.isArray(item.sourceIds) || item.sourceIds.length > 100_000 ||
+        item.sourceIds.some(id => !SOURCE.test(id)) || new Set(item.sourceIds).size !== item.sourceIds.length) fail()
+    watermarks.set(item.chatId, item.watermark)
+    excluded.set(item.chatId, new Set(item.sourceIds))
+  }
+  for (const group of expectedGroups) {
+    if (!watermarks.has(group.chatId) && legacy.groups?.[group.chatId] !== undefined) fail()
+  }
+  return Object.freeze({
+    sourceIds: Object.freeze([...new Set(fence.fences.flatMap(item => item.sourceIds))]),
+    watermarks: Object.freeze(Object.fromEntries(watermarks)),
+    rejects(message) {
+      if (!watermarks.has(message?.chatId)) return false
+      if (excluded.get(message.chatId).has(message.msgId)) return true
+      return !Number.isSafeInteger(message.createTimeMs) || message.createTimeMs <= watermarks.get(message.chatId)
+    },
+  })
+}
+// A group bound online after a reviewed cut must not carry legacy state:
+// its old messages would have no admission fence.
+function assertNoLegacyGroupState({ stateDir, chatId } = {}) {
+  if (!path.isAbsolute(stateDir || '') || !CHAT.test(chatId || '')) fail()
+  const file = path.join(stateDir, 'legacy-evidence', 'state-before.json')
+  if (!fs.existsSync(path.join(stateDir, 'c2-migration.json')) && !fs.existsSync(file)) return true
+  const legacy = JSON.parse(readPrivate(file))
+  if (legacy.groups?.[chatId] !== undefined) {
+    throw new Error('This group has legacy history; review its migration before binding it again')
+  }
+  return true
+}
+module.exports = { loadC2MigrationFence, assertNoLegacyGroupState }