sintbot 1.4.0 → 1.4.2

package/src/c2console.js

@@ -17,12 +17,15 @@ const WRITE_PATHS = ['/api/login', '/api/logout', '/api/logout/all',
   '/api/groups/order', '/api/groups/policy', '/api/groups/redact',
   '/api/groups/codex-steer', '/api/groups/pause', '/api/groups/stop',
   '/api/agent', '/api/provider-settings', '/api/codex/verify', '/api/usage/refresh',
-  '/api/inbox/dismiss', '/api/issues/status']
+  '/api/inbox/dismiss', '/api/issues/status',
+  // Software updates: check and ignore anywhere; install only when launchd
+  // manages this exact entry (the updater refuses every other run mode).
+  '/api/update/check', '/api/update/start', '/api/update/ignore']
 const SUPPORTED_RUNNERS = ['claude', 'codex']
 
-function createC2ConsoleFacade({ getBindings, getCapacity, getConfig,
+function createC2ConsoleFacade({ getBindings, getCapacity, getConfig, getHeld = () => new Map(),
   assertWriterLock, validateConfig, applyConfig, beforeWrite = () => true, now = Date.now } = {}) {
-  for (const callback of [getBindings, getCapacity, getConfig, assertWriterLock,
+  for (const callback of [getBindings, getCapacity, getConfig, getHeld, assertWriterLock,
     validateConfig, applyConfig, beforeWrite, now]) {
     if (typeof callback !== 'function') throw new TypeError('C2 console needs live authority and configuration hooks')
   }
@@ -32,7 +35,7 @@ function createC2ConsoleFacade({ getBindings, getCapacity, getConfig,
   const startedAt = now()
   const capabilities = Object.freeze({ mode: 'durable-v2',
     reason: '此操作尚未接入当前版本的持久处理流程，未执行。',
-    summary: '实时状态、认证管理、停止任务、绑定新群，以及空闲群的模型切换（Codex / Claude Code）和项目目录修改已接入；该群有任务或未结记录时不能修改。开新会话、解除绑定、控制台插话、定时任务、画布和升级暂不可用。',
+    summary: '实时状态、认证管理、停止任务、绑定新群、空闲群的模型切换（Codex / Claude Code）和项目目录修改，以及后台运行时的软件升级已接入；该群有任务或未结记录时不能修改。开新会话、解除绑定、控制台插话、定时任务和画布暂不可用。',
     allowed: { GET: READ_PATHS, POST: WRITE_PATHS } })
   function held() {
     if (assertWriterLock() !== true) throw new Error('服务写入权限已失效，操作未执行')
@@ -45,10 +48,12 @@ function createC2ConsoleFacade({ getBindings, getCapacity, getConfig,
   function getLiveState() {
     const cfg = getConfig()
     const capacity = getCapacity()
+    const heldGroups = getHeld()
     const groups = {}
     let queue = 0
     for (const [chatId, group] of Object.entries(cfg.groups || {})) {
       const binding = bindings().get(chatId)
+      const hold = heldGroups.get(chatId)
       const rt = binding?.engine?.rts.get(chatId)
       const snapshot = binding?.journal?.snapshot()
       const pending = snapshot?.receipts?.pending || []
@@ -63,14 +68,17 @@ function createC2ConsoleFacade({ getBindings, getCapacity, getConfig,
         waitingForCapacity: !!rt?.v2AdmissionPending,
         sinceMs: rt?.v2StartedAt ? Math.max(0, now() - rt.v2StartedAt) : 0,
         sessionId: binding?.engine?.store?.getSession(chatId) || '',
+        // A held group needs the operator: its last result is unknown.
+        ...(hold ? { held: true, heldReason: hold.reason, heldSinceMs: Math.max(0, now() - hold.since) } : {}),
       }
     }
     const activeBindingsReady = Object.entries(cfg.groups || {})
-      .filter(([, group]) => !group.paused).every(([chatId]) => bindings().has(chatId))
+      .filter(([chatId, group]) => !group.paused && !heldGroups.has(chatId))
+      .every(([chatId]) => bindings().has(chatId))
     return { running: assertWriterLock() === true && !capacity.closed && activeBindingsReady,
       uptimeMs: Math.max(0, now() - startedAt),
       concurrency: { active: capacity.active, max: capacity.maxConcurrent },
-      queue, waiting: capacity.waiting, groups }
+      queue, waiting: capacity.waiting, held: heldGroups.size, groups }
   }
   function getActivity() {
     const cfg = getConfig(), items = []
@@ -128,7 +136,7 @@ function createC2Console(options = {}) {
     throw new TypeError('C2 console requires explicit installation paths')
   }
   const facade = createC2ConsoleFacade(options)
-  const ui = createUiServer({ configPath, host, log, getConnHealth,
+  const ui = createUiServer({ configPath, host, log, getConnHealth, updater: options.updater || null,
     onHostChange: options.onHostChange,
     getLiveState: facade.getLiveState, control: facade.control, runtimePolicy: facade,
     issuesPath: path.join(stateDir, 'issues.jsonl'),

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

@@ -201,7 +201,7 @@ function assertJournalScope(journal, chatId, { requireSettled = false } = {}) {
       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('Paused group journal has unresolved work; preserve it and explicitly review recovery')
+    throw new Error('Group journal has unresolved work; preserve it and explicitly review recovery')
   }
   return snap
 }

package/src/c2multigroupservice.js

@@ -4,6 +4,9 @@ const { isC2InputRejection, answerC2InputRejection, rejectC2Input } = require('.
 const { coordinateC2GlobalFault } = require('./core/c2globalfault')
 
 const RECOVERING_NOTICE = '上一个任务出错，正在收尾，这条消息没有处理，请稍后重发。'
+const HELD_NOTICE = '本群上一个任务结果不明，已暂停处理，等待人工确认；其他群不受影响。'
+const UPGRADING_NOTICE = 'SintBot 正在升级，这条消息没有处理，请一分钟后重发。'
+const reasonOf = error => String(error?.message || error || 'unknown').slice(0, 300)
 
 // Turns a group binding still holds: a running turn, a non-idle handoff or a
 // busy lifecycle. Scoped to one group's own journal.
@@ -23,12 +26,20 @@ function activeTurns(snapshot) {
   return turns.sort((a, b) => a.chatId.localeCompare(b.chatId))
 }
 
+const runtimesOf = binding => binding?.engine?.rts instanceof Map ? [...binding.engine.rts.values()] : []
+
 // Process-local organization only. Each binding owns a distinct durable
 // authority; the transport and writer lease belong to this single process.
+// A fault that only one group's journal can explain holds that group: its
+// sealed binding stays as evidence, nothing is replayed or retried, and every
+// other group keeps serving. Only a shared resource (writer lease, transport,
+// model capacity) stops the process. `holds` lists groups whose journal could
+// not be opened before the service was created.
 function createC2MultiGroupService({ routes, assertWriterLock,
   createTransport, createBinding, onFatal = () => {}, closeCapacity = () => {},
   quarantine = null, stopTimeoutMs = 2_000, drainTimeoutMs = 12_000,
-  createRecoveryAuthority = null, log = () => {} } = {}) {
+  createRecoveryAuthority = null, holds = new Map(), sharedFault = () => null,
+  now = Date.now, log = () => {} } = {}) {
   if (!Array.isArray(routes) || !routes.length ||
       new Set(routes.map(route => route.chatId)).size !== routes.length ||
       routes.some(route => !route || typeof route.chatId !== 'string' ||
@@ -36,7 +47,9 @@ function createC2MultiGroupService({ routes, assertWriterLock,
       typeof assertWriterLock !== 'function' ||
       typeof createTransport !== 'function' || typeof createBinding !== 'function' ||
       typeof onFatal !== 'function' || typeof closeCapacity !== 'function' ||
-      typeof log !== 'function' ||
+      typeof log !== 'function' || typeof sharedFault !== 'function' ||
+      typeof now !== 'function' || !(holds instanceof Map) ||
+      [...holds.keys()].some(chatId => !routes.some(route => route.chatId === chatId)) ||
       createRecoveryAuthority !== null && typeof createRecoveryAuthority !== 'function' ||
       !Number.isSafeInteger(stopTimeoutMs) || stopTimeoutMs < 1 ||
       !Number.isSafeInteger(drainTimeoutMs) || drainTimeoutMs < 1) {
@@ -44,6 +57,10 @@ function createC2MultiGroupService({ routes, assertWriterLock,
   }
   const configured = new Map(routes.map(route => [route.chatId, route]))
   const bindings = new Map()
+  // chatId -> { reason, source: 'startup' | 'runtime', since, binding }
+  const suspended = new Map()
+  // Set while a console upgrade switches the service: no message is admitted.
+  let maintenance = false
   let transport = null
   let started = false
   let starting = false
@@ -92,7 +109,8 @@ function createC2MultiGroupService({ routes, assertWriterLock,
         () => transport.stopPlatform(), stopTimeoutMs) === true
       const drained = (await Promise.all([...bindings.values()].map(binding =>
         bounded(() => binding.engine.drainDurableV2(drainTimeoutMs), drainTimeoutMs + 100))))
-        .every(value => value === true)
+        .every(value => value === true) && [...suspended.values()].every(entry =>
+        runtimesOf(entry.binding).every(rt => !rt.v2Controller))
       return Object.freeze({ reason, code: code === 0 && startupStopped && platformStopped && drained ? 0 : 1,
         startupStopped, platformStopped, drained })
     })()
@@ -105,6 +123,22 @@ function createC2MultiGroupService({ routes, assertWriterLock,
     await onFatal(error, result)
     return result
   }
+  // Seal one group in place. Its binding and journal are kept unchanged as
+  // evidence; a later restart reopens it only through the normal recovery
+  // gate, or after its incident has been sealed by the operator.
+  function suspend(chatId, error, { source, binding = null }) {
+    if (suspended.has(chatId)) return suspended.get(chatId)
+    const entry = Object.freeze({ reason: reasonOf(error), source, since: now(), binding })
+    suspended.set(chatId, entry)
+    for (const sealed of new Set([binding, bindings.get(chatId)])) {
+      if (!sealed) continue
+      try { sealed.gate.stop() } catch {}
+      try { sealed.engine.shutdown() } catch {}
+    }
+    bindings.delete(chatId)
+    log(`group ${chatId}: held (${entry.reason}); other groups keep serving`)
+    return entry
+  }
   function allowed(chatId) {
     const route = configured.get(chatId)
     if (!route || route.paused === true) return false
@@ -155,6 +189,34 @@ function createC2MultiGroupService({ routes, assertWriterLock,
     work.then(() => recovering.delete(chatId), () => recovering.delete(chatId))
     return work
   }
+  // One group's route, recall or ingress failed. Close the failed turn when
+  // its journal proves every effect; otherwise hold the group alone. Returns
+  // 'recovered', 'held', 'fatal' (process stop begun) or 'stopping'.
+  async function groupFault(chatId, binding, error) {
+    const shared = () => !writerHeld() ? 'writer lock lost' : sharedFault()
+    if (shared()) { await fatal(error); return 'fatal' }
+    if (!started || stopPromise) return 'stopping'
+    if (suspended.has(chatId)) return 'held'
+    const current = bindings.get(chatId)
+    if (!binding || current !== binding && !failedBindings.has(binding)) {
+      // An error from a binding this service never published is not attributable.
+      await fatal(error); return 'fatal'
+    }
+    if (!createRecoveryAuthority) { await fatal(error); return 'fatal' }
+    try {
+      await recoverGroup(chatId, binding, error)
+    } catch (failure) {
+      log(`group ${chatId}: failed turn could not be closed: ${reasonOf(failure)}`)
+      if (shared()) { await fatal(failure); return 'fatal' }
+      if (!started || stopPromise) return 'stopping'
+      suspend(chatId, failure, { source: 'runtime', binding })
+    }
+    return suspended.has(chatId) ? 'held' : 'recovered'
+  }
+  function heldReply(msg, sourceAdapter) {
+    return answerC2InputRejection({ error: rejectC2Input('C2 group held',
+      { reason: 'group-held', notice: HELD_NOTICE }), msg, platform: sourceAdapter, log })
+  }
   // Open one more group on the live transport: a newly added route or one
   // paused since startup. It runs the same recovery gate as startup; only a
   // fully opened binding is published. Failure leaves the group unserved.
@@ -162,13 +224,16 @@ function createC2MultiGroupService({ routes, assertWriterLock,
     if (!route || typeof route.chatId !== 'string' || typeof route.file !== 'string') {
       return Promise.reject(new TypeError('C2 online route needs an explicit group and journal'))
     }
+    if (suspended.has(route.chatId)) {
+      return Promise.reject(new Error('This group is held after an unresolved fault; seal its incident and restart'))
+    }
     if (bindings.has(route.chatId)) return Promise.resolve(bindings.get(route.chatId))
     if (activating.has(route.chatId)) return activating.get(route.chatId)
     const opening = (async () => {
-      if (!started || starting || stopPromise) throw new Error('C2 service is not serving')
+      if (!started || starting || stopPromise || maintenance) throw new Error('C2 service is not serving')
       held()
       const binding = await createBinding({ route, transport })
-      if (!started || stopPromise || !writerHeld() ||
+      if (!started || stopPromise || !writerHeld() || suspended.has(route.chatId) ||
           !binding || !binding.gate || !binding.engine || binding.gate.blocked) {
         binding?.gate?.stop?.()
         binding?.engine?.shutdown?.()
@@ -184,40 +249,64 @@ function createC2MultiGroupService({ routes, assertWriterLock,
     return opening
   }
   function routeMessage(msg, sourceAdapter) {
+    const route = configured.get(msg?.chatId)
+    if (route && route.paused !== true && suspended.has(msg.chatId)) {
+      // A held group admits nothing; a replay of a sealed source stays silent.
+      if (quarantine?.rejects(msg)) return { quarantined: true }
+      if (started && !stopPromise) return heldReply(msg, sourceAdapter)
+    }
     // Foreign/paused group events are not faults and never get a receipt.
     if (!allowed(msg?.chatId)) return { ignored: true, reason: 'unconfigured-or-paused' }
     if (quarantine?.rejects(msg)) return { quarantined: true }
+    if (maintenance && started && !stopPromise) {
+      return answerC2InputRejection({ error: rejectC2Input('C2 service upgrading',
+        { reason: 'upgrading', notice: UPGRADING_NOTICE }), msg, platform: sourceAdapter, log })
+    }
     if (recovering.has(msg.chatId) && started && !stopPromise) {
       // The group's failed turn is being closed; nothing is admitted meanwhile.
       return answerC2InputRejection({ error: rejectC2Input('C2 group recovering',
         { reason: 'group-recovering', notice: RECOVERING_NOTICE }), msg, platform: sourceAdapter, log })
     }
+    let binding
     try {
       held()
-      const binding = bindings.get(msg.chatId)
-      if (!started || starting || stopPromise || !binding || binding.gate.blocked) {
+      binding = bindings.get(msg.chatId)
+      if (!started || starting || stopPromise || !binding) {
         throw new Error('C2 group ingress authority closed')
       }
+      if (binding.gate.blocked) {
+        // A turn still running under a closed authority delivers its own
+        // rejection; until then this message, which has no receipt, is
+        // refused. An idle closed group is closed as its own fault here.
+        if (runtimesOf(binding).some(rt => rt.v2NormalRouteActive)) {
+          return answerC2InputRejection({ error: rejectC2Input('C2 group closing',
+            { reason: 'group-recovering', notice: RECOVERING_NOTICE }), msg, platform: sourceAdapter, log })
+        }
+        return groupFault(msg.chatId, binding, new Error('C2 group ingress authority closed'))
+          .then(async outcome => {
+            if (outcome === 'held') return heldReply(msg, sourceAdapter)
+            if (outcome === 'recovered') {
+              return answerC2InputRejection({ error: rejectC2Input('C2 group recovered',
+                { reason: 'group-recovering', notice: RECOVERING_NOTICE }), msg, platform: sourceAdapter, log })
+            }
+            throw new Error('C2 group ingress authority closed')
+          })
+      }
       const running = binding.engine.runDurableV2Message(msg, sourceAdapter)
       return Promise.resolve(running).catch(async error => {
         // A refused command or premature /stop wrote nothing durable. Answer it
-        // once and keep every group serving; any other error stays fatal.
+        // once and keep every group serving.
         if (isC2InputRejection(error) && started && !stopPromise &&
             !binding.gate.blocked && writerHeld()) {
           log(`group ${msg.chatId}: refused input before receipt (${error.reason})`)
           return answerC2InputRejection({ error, msg, platform: sourceAdapter, log })
         }
-        // A closed model turn that failed (error or empty result) is closed for
-        // this group alone. Other errors from that same superseded binding are
-        // part of the same fault and wait for its recovery.
-        if (createRecoveryAuthority && started && !stopPromise &&
-            (failedBindings.has(binding) ||
-              error?.code === 'C2_V2_UNRESOLVED_TURN' && bindings.get(msg.chatId) === binding)) {
-          const recovered = await recoverGroup(msg.chatId, binding, error).then(() => true, failure => {
-            log(`group ${msg.chatId}: failed turn could not be closed: ${failure?.message || String(failure)}`)
-            return false
-          })
-          if (recovered) return { recovered: true, reason: 'group-fault-closed' }
+        // Any other route error belongs to this group alone unless a shared
+        // resource failed. Errors from a superseded binding join its fault.
+        if (started && !stopPromise) {
+          const outcome = await groupFault(msg.chatId, binding, error)
+          if (outcome === 'recovered') return { recovered: true, reason: 'group-fault-closed' }
+          if (outcome === 'held') return { held: true, reason: 'group-held' }
         }
         await fatal(error)
         throw error
@@ -236,15 +325,23 @@ function createC2MultiGroupService({ routes, assertWriterLock,
     }
   }
   function recall(event) {
+    if (suspended.has(event?.chatId)) return { ignored: true, reason: 'group-held' }
+    if (maintenance) return { ignored: true, reason: 'upgrading' }
     if (!allowed(event?.chatId)) return { ignored: true }
+    let binding
     try {
       held()
-      const binding = bindings.get(event.chatId)
+      binding = bindings.get(event.chatId)
       if (!started || stopPromise || !binding) return { ignored: true, reason: 'ingress-closed' }
       const handled = binding.engine.handleRecall?.(event) === true
       if (binding.runtime?.blocked) throw new Error('Recall closed its durable authority')
       return handled ? { handled: true } : { ignored: true, reason: 'unsupported-or-inactive-recall' }
-    } catch (error) { return fatal(error) }
+    } catch (error) {
+      if (!binding || !writerHeld() || !started || stopPromise) return fatal(error)
+      return groupFault(event.chatId, binding, error).then(outcome =>
+        outcome === 'recovered' || outcome === 'held'
+          ? { ignored: true, reason: `group-${outcome}` } : fatal(error))
+    }
   }
   async function start({ preflightOnly = false } = {}) {
     if (started || starting || stopPromise) throw new Error('C2 service already started or stopped')
@@ -260,9 +357,19 @@ function createC2MultiGroupService({ routes, assertWriterLock,
           typeof transport.stopPlatform !== 'function') {
         throw new TypeError('C2 transport lacks a single start/stop boundary')
       }
+      for (const [chatId, reason] of holds) suspend(chatId, reason, { source: 'startup' })
       for (const route of routes) {
-        if (route.paused) continue // Its settled journal is audited before start.
-        const binding = await createBinding({ route, transport })
+        if (route.paused || suspended.has(route.chatId)) continue // Paused journals are audited before start.
+        let binding
+        try {
+          binding = await createBinding({ route, transport })
+        } catch (error) {
+          held()
+          if (stopPromise) throw new Error('C2 service stopped during group recovery')
+          // This group's journal could not be recovered; it alone stays closed.
+          suspend(route.chatId, error, { source: 'startup' })
+          continue
+        }
         held()
         if (stopPromise) {
           binding?.gate?.stop?.()
@@ -273,11 +380,19 @@ function createC2MultiGroupService({ routes, assertWriterLock,
         if (!binding || !binding.gate || !binding.engine || binding.gate.blocked) {
           binding?.gate?.stop?.()
           binding?.engine?.shutdown?.()
-          throw new Error('C2 group binding did not open its durable authority')
+          suspend(route.chatId, 'C2 group binding did not open its durable authority', { source: 'startup' })
+          continue
         }
         bindings.set(route.chatId, binding)
       }
       held()
+      const heldList = [...suspended].map(([chatId, entry]) => `${chatId}: ${entry.reason}`)
+      if (preflightOnly && heldList.length) {
+        throw new Error(`Startup preflight would hold ${heldList.length} group(s): ${heldList.join('; ')}`)
+      }
+      if (heldList.length && !bindings.size) {
+        throw new Error(`Every active group is held: ${heldList.join('; ')}`)
+      }
       if (preflightOnly) {
         finishStartup()
         await stop('preflight', 0)
@@ -291,14 +406,30 @@ function createC2MultiGroupService({ routes, assertWriterLock,
         onCardAction: unsupported('card action'), onBoardUpdated: unsupported('board update') })
       held()
       if (stopPromise) throw new Error('C2 service stopped during connection')
-      return { groups: bindings.size, connected: true }
+      return { groups: bindings.size, connected: true, ...(suspended.size ? { held: heldGroups() } : {}) }
     } catch (error) {
       finishStartup()
       await stop('startup-failed', 1)
       throw error
     } finally { starting = false; finishStartup() }
   }
-  return { start, stop, routeMessage, addRoute, get bindings() { return new Map(bindings) } }
+  function heldGroups() {
+    return [...suspended].map(([chatId, entry]) => Object.freeze({ chatId,
+      reason: entry.reason, source: entry.source, since: entry.since }))
+  }
+  function beginMaintenance() {
+    if (!maintenance) log('upgrade: admission closed for the service switch')
+    maintenance = true
+  }
+  function endMaintenance() {
+    if (maintenance) log('upgrade: admission reopened')
+    maintenance = false
+  }
+  return { start, stop, routeMessage, addRoute, heldGroups, beginMaintenance, endMaintenance,
+    get inMaintenance() { return maintenance },
+    get bindings() { return new Map(bindings) },
+    get held() { return new Map([...suspended].map(([chatId, entry]) =>
+      [chatId, { reason: entry.reason, source: entry.source, since: entry.since }])) } }
 }
 
 module.exports = { createC2MultiGroupService }