sintbot 1.0.15 → 1.3.0

package/bin/sintbot-v2.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+'use strict'
+
+// Restricted macOS Feishu single-group entry. No legacy daemon or terminal
+// chat dispatch is reachable from this entry.
+const fs = require('node:fs')
+const path = require('node:path')
+const { parseArgs } = require('node:util')
+const { applyProxyEnv, chatPlatform } = require('../src/config')
+const { secureDataDir } = require('../src/core/datadir')
+const { StateStore } = require('../src/core/store')
+const { createFeishuPlatform, feishuClient } = require('../src/platform/feishu')
+const { createMultiPlatform } = require('../src/platform/multi')
+
+async function startService(rest) {
+  const { values } = parseArgs({ args: rest, allowPositionals: false,
+    options: { config: { type: 'string' }, ui: { type: 'boolean' },
+      'no-open': { type: 'boolean' }, 'ui-port': { type: 'string' },
+      'ui-host': { type: 'string' }, preflight: { type: 'boolean' } } })
+  const preflightOnly = values.preflight === true
+  if (values.ui || values['no-open'] || values['ui-port'] || values['ui-host']) {
+    throw new Error('C2 v2 single-group service has no durable UI route; remove UI options')
+  }
+  const { loadInstallation, assertPrivateDirectory } = require('../src/c2install')
+  const { stateDir, file, cfg, groups, serviceChatId, provider } = loadInstallation(values.config)
+  assertPrivateDirectory(stateDir)
+  let journalStat
+  try { journalStat = fs.lstatSync(file) } catch {}
+  if (!journalStat?.isFile() || journalStat.isSymbolicLink()) {
+    throw new Error('No initialized journal; use sintbot init for a new installation. Existing state must be reviewed before migration.')
+  }
+  applyProxyEnv(cfg)
+  const { spawnSync } = require('node:child_process')
+  const probe = spawnSync(provider.bin || 'codex', ['--version'], {
+    encoding: 'utf8', timeout: 10_000, maxBuffer: 64 * 1024,
+    env: { ...process.env, ...(provider.env || {}) },
+  })
+  if (probe.error || probe.status !== 0 || !/codex/i.test(probe.stdout || '')) {
+    throw new Error('Codex executable preflight failed; install and sign in to Codex, then check the configured executable.')
+  }
+  const runner = require('../src/agent/runner')
+  secureDataDir(stateDir)
+  const lockFile = path.join(stateDir, 'daemon.lock')
+  const lock = require('../src/core/instancelock').acquire(lockFile)
+  if (!lock.ok) throw new Error('C2 v2 development service cannot hold the single-writer lock')
+  let running = false
+  try {
+    // The old daemon records interrupted work here and consumes it on restart.
+    // Starting v2 while such a file exists would leave that work invisible;
+    // never consume, delete, or reinterpret it without an explicit migration.
+    for (const name of ['pending-turns.json', 'engine-receipts.json']) {
+      try {
+        fs.lstatSync(path.join(stateDir, name))
+      } catch (error) {
+        if (error.code === 'ENOENT') continue
+        throw error
+      }
+      throw new Error(`C2 v2 cannot start with legacy ${name}; preserve it and drain with the old service or use a reviewed migration`)
+    }
+    const { createC2V2SourceQuarantine } = require('../src/core/c2sourcequarantine')
+    const requireQuarantine = process.env.SBOT_C2_V2_REQUIRE_BLOCK_SOURCE_ID
+    if (requireQuarantine !== undefined &&
+        requireQuarantine !== '0' && requireQuarantine !== '1') {
+      throw new Error('C2 v2 source quarantine requirement must be 0 or 1')
+    }
+    const sourceQuarantine = createC2V2SourceQuarantine([
+      process.env.SBOT_C2_V2_BLOCK_SOURCE_ID,
+      process.env.SBOT_C2_V2_BLOCK_SOURCE_ID_2],
+      { required: requireQuarantine === '1' })
+    const assertWriterLock = () => {
+      try { return fs.readFileSync(lockFile, 'utf8').trim() === String(process.pid) }
+      catch { return false }
+    }
+    const { C2DurableJournal } = require('../src/core/c2durablejournal')
+    const { validatePersistentState } = require('../src/core/c2persiststate')
+    const { validatePersistentReceipts, validatePersistentRelation } = require('../src/core/c2persistrelation')
+    const { createC2ServiceStartGate } = require('../src/core/c2servicestartgate')
+    const { C2PayloadHandles } = require('../src/core/c2payloadhandles')
+    const { createC2LocalEffectExecutor, resolveC2LocalEffectTurn } =
+      require('../src/core/c2localeffectexecutor')
+    const { createFeishuRecoverySender } = require('../src/core/c2platformrecoverysender')
+    const journal = C2DurableJournal.open(file, { validateState: validatePersistentState,
+      validateReceipts: validatePersistentReceipts,
+      validateRelation: validatePersistentRelation })
+    const beforeRecovery = journal.snapshot()
+    if (preflightOnly && (beforeRecovery.receipts.pending.length !== 0 ||
+        Object.keys(beforeRecovery.state.lanes).length !== 0 ||
+        [...beforeRecovery.effects.values()].some(status => status !== 'acked') ||
+        [...beforeRecovery.notices.values()].some(notice =>
+          notice.status === 'attempting' || notice.status === 'unknown'))) {
+      throw new Error('C2 v2 service preflight requires a settled journal; use recovery in a controlled service window')
+    }
+    const limits = { maxEventCount: 100_000,
+      maxJournalBytes: 64 * 1024 * 1024,
+      maxCompletionEvents: 1_000, maxCompletionBytes: 8 * 1024 * 1024 }
+    const { routeBackend } = require('../src/agent/privatecore')
+    const { C2DurableRuntime } = require('../src/core/c2durableruntime')
+    const { coordinateC2GlobalFault } = require('../src/core/c2globalfault')
+    const closeChecks = {
+      claude: require('../src/agent/claudecode').isClosedRunnerResult,
+      'codex-exec': require('../src/agent/codexcode').isClosedRunnerResult,
+      'codex-app': require('../src/agent/codexapp').isClosedRunnerResult,
+    }
+    const validators = { validateState: validatePersistentState,
+      validateReceipts: validatePersistentReceipts,
+      validateRelation: validatePersistentRelation }
+    const createTransport = () => {
+      const client = feishuClient(cfg.feishu.appId, cfg.feishu.appSecret)
+      const adapter = createFeishuPlatform({ appId: cfg.feishu.appId,
+        appSecret: cfg.feishu.appSecret, botOpenId: cfg.feishu.botOpenId,
+        onlyWhenMentioned: cfg.feishu.onlyWhenMentioned === true,
+        ws: cfg.feishu.ws || {}, card: cfg.feishu.card || {}, client })
+      const platform = createMultiPlatform({ adapters: { feishu: adapter },
+        resolve: chatId => chatPlatform(cfg, chatId) })
+      const sender = createFeishuRecoverySender({ cfg, platform, client })
+      for (const [chatId] of groups) sender.resolveTarget({ id: '0'.repeat(32),
+        chatId, source: 'message', sourceId: 'om_c2_service_probe' })
+      return { platform, sender, stopPlatform: () => adapter.stop({ strict: true }) }
+    }
+    const buildBinding = async authorityJournal => {
+      const { platform, sender, stopPlatform } = createTransport()
+      const gate = createC2ServiceStartGate({ enabled: true,
+        journal: authorityJournal, assertWriterLock,
+        resolveTarget: sender.resolveTarget, send: sender.send,
+        singleNoticePerGroup: true, ...limits })
+      try {
+        await gate.start()
+        const runtime = gate.runtime
+        if (!runtime || runtime.blocked || !assertWriterLock()) {
+          throw new Error('C2 v2 development service recovery did not open ingress')
+        }
+        const handles = new C2PayloadHandles({ journal: authorityJournal })
+        handles.reopenAfterRecovery()
+        if (handles.blocked || runtime.snapshot().cursor !== authorityJournal.snapshot().cursor) {
+          throw new Error('C2 v2 development service payload authority differs after recovery')
+        }
+        const store = new StateStore(path.join(stateDir, 'state.json'))
+        const closedResults = new WeakSet()
+        const startTurn = async input => {
+          const backend = routeBackend(input.provider?.runner, input.codexApp,
+            input.codexSteer, input.codexProjectDocFallback)
+          const result = await runner.runTurn(input)
+          if (closeChecks[backend]?.(result) === true) closedResults.add(result)
+          return result
+        }
+        let engine
+        const applyLocalEffect = createC2LocalEffectExecutor({
+          journal: authorityJournal, store,
+          verifyFile: path.join(stateDir, 'verify.json'), assertWriterLock,
+          resolveTurn: identity => resolveC2LocalEffectTurn(engine, identity) })
+        const { Engine } = require('../src/core/v2engine')
+        engine = new Engine(cfg, { runner, store, log: message =>
+          process.stderr.write(`C2 v2 · ${message}\n`),
+        durableV2Runtime: runtime, durableV2Payloads: handles,
+        durableV2StartTurn: startTurn, durableV2ApplyLocalEffect: applyLocalEffect,
+        durableV2VerifyRunnerClosed: ({ result }) => !!result &&
+          typeof result === 'object' && closedResults.has(result),
+        durableV2AssertWriterLock: assertWriterLock,
+        durableV2Journal: authorityJournal, durableV2NormalRoute: true })
+        return { journal: authorityJournal, platform, sender, stopPlatform, gate,
+          runtime, handles, store, engine }
+      } catch (error) { gate.stop(); throw error }
+    }
+    let active = await buildBinding(journal)
+    if (preflightOnly) {
+      active.gate.stop()
+      process.stdout.write('SintBot startup preflight passed; Feishu socket stayed disconnected\n')
+      return
+    }
+    let stopping = false
+    let rebuilds = 0
+    let finishing = false
+    const finish = (reason, code, platformStopped, drained) => {
+      if (finishing) return
+      finishing = true
+      lock.release()
+      process.stderr.write(`C2 v2 · ${reason}; platform stopped=${platformStopped}; runner drained=${drained}\n`,
+        () => process.exit(code))
+    }
+    const activeTurns = snapshot => {
+      const lanes = snapshot.state.lanes
+      const turns = []
+      for (const chatId of new Set([...Object.keys(lanes.turn || {}),
+        ...Object.keys(lanes.handoff || {}),
+        ...Object.keys(lanes.lifecycle || {})])) {
+        const turn = lanes.turn?.[chatId]
+        const handoff = lanes.handoff?.[chatId]
+        const lifecycle = lanes.lifecycle?.[chatId]
+        if (turn?.active != null || handoff?.phase && handoff.phase !== 'idle' ||
+            lifecycle?.busy === true || lifecycle?.controller === true) {
+          turns.push({ chatId, turnToken: turn?.active ?? handoff?.turnToken ?? null })
+        }
+      }
+      return turns.sort((a, b) => a.chatId.localeCompare(b.chatId))
+    }
+    const launch = async binding => {
+      const onFatal = createC2ReceiptIngressFatalHook({
+        log: message => process.stderr.write(`C2 v2 · ${message}\n`),
+        shutdown: reason => shutdown(binding, reason, 1) })
+      const unsupported = source => () => {
+        void onFatal(new Error(`C2 v2 unsupported Feishu ${source} source`))
+      }
+      await binding.platform.start((msg, sourceAdapter) => {
+        if (binding !== active || binding.gate.blocked || !assertWriterLock()) {
+          throw new Error('C2 v2 development service ingress lost durable authority')
+        }
+        if (msg?.chatId !== serviceChatId) {
+          throw new Error('C2 v2 development service received a message outside its single group')
+        }
+        if (sourceQuarantine?.rejects(msg)) {
+          process.stderr.write('C2 v2 · quarantined historical source message before receipt\n')
+          return { quarantined: true }
+        }
+        return binding.engine.runDurableV2Message(msg, sourceAdapter)
+      }, { onFatal, onRecall: unsupported('recall'),
+        onReaction: unsupported('reaction'),
+        onCardAction: unsupported('card action'),
+        onBoardUpdated: unsupported('board update') })
+      process.stderr.write('SintBot single-group Feishu ingress connected\n')
+    }
+    const shutdown = async (binding, reason, code = 1) => {
+      if (stopping || binding !== active) return
+      stopping = true
+      binding.gate.stop()
+      binding.engine.shutdown()
+      let stopTimer
+      const platformStopped = await Promise.race([
+        Promise.resolve().then(() => binding.stopPlatform()).then(value => value === true, () => false),
+        new Promise(resolve => {
+          stopTimer = setTimeout(() => resolve(false), 2_000)
+        }),
+      ])
+      clearTimeout(stopTimer)
+      const drained = await binding.engine.drainDurableV2(12_000).catch(() => false)
+      // A failed route may have already settled, leaving a closed child and
+      // active durable receipt for global-fault reconciliation. A still-live
+      // route or child cannot be replaced, even if the drain timer expired.
+      const quiescent = [...binding.engine.rts.values()].every(rt =>
+        !rt.v2Controller && !rt.v2NormalRouteActive)
+      if (code === 0 || !platformStopped || !quiescent || !assertWriterLock() ||
+          rebuilds >= 1) {
+        finish(reason, code === 0 && platformStopped && drained ? 0 : 1,
+          platformStopped, drained)
+        return
+      }
+      rebuilds++
+      try {
+        const current = binding.journal.snapshot()
+        const turns = activeTurns(current)
+        const proofs = turns.length
+          ? binding.engine.durableV2ActiveFaultProofs?.(turns) || null : null
+        const result = await coordinateC2GlobalFault({
+          runtime: binding.runtime, journal: binding.journal, assertWriterLock,
+          abortTurn: turn => binding.engine.abortDurableV2FaultTurn?.(turn) === true,
+          activeTurnProofs: proofs,
+          createAuthority: () => {
+            const nextJournal = C2DurableJournal.open(file, validators)
+            const nextRuntime = new C2DurableRuntime({ journal: nextJournal,
+              resolveTarget: binding.sender.resolveTarget,
+              send: binding.sender.send, assertWriterLock,
+              singleNoticePerGroup: true, ...limits })
+            return { journal: nextJournal, runtime: nextRuntime }
+          } })
+        if (result.status !== 'recovered' || !assertWriterLock()) {
+          finish(`C2 v2 recovery sealed: ${result.reason || 'writer lock lost'}`,
+            1, platformStopped, drained)
+          return
+        }
+        result.runtime.close()
+        const next = await buildBinding(result.journal)
+        active = next
+        // A fatal callback may arrive synchronously while the fresh platform
+        // starts. It must not be swallowed by the old binding's stop guard.
+        stopping = false
+        await launch(next)
+        process.stderr.write('C2 v2 process-local authority rebuilt\n')
+      } catch (error) {
+        finish(`C2 v2 recovery failed: ${error?.message || String(error)}`,
+          1, platformStopped, drained)
+      }
+    }
+    process.on('SIGINT', () => { void shutdown(active, 'SIGINT', 0) })
+    process.on('SIGTERM', () => { void shutdown(active, 'SIGTERM', 0) })
+    process.on('exit', lock.release)
+    try {
+      await launch(active)
+      running = true
+    } catch (error) {
+      active.gate.stop()
+      active.engine.shutdown()
+      let timer
+      await Promise.race([
+        Promise.resolve().then(() => active.stopPlatform()).catch(() => false),
+        new Promise(resolve => { timer = setTimeout(resolve, 2_000) }),
+      ])
+      clearTimeout(timer)
+      await active.engine.drainDurableV2(12_000).catch(() => false)
+      throw error
+    }
+  } finally { if (!running) lock.release() }
+}
+
+// The opt-in receipt authority cannot keep accepting Feishu messages after
+// its ingress callback rejects. The adapter closes its socket first; the
+// daemon then aborts running turns and exits nonzero under the supervisor.
+function createC2ReceiptIngressFatalHook({ log, shutdown }) {
+  if (typeof log !== 'function' || typeof shutdown !== 'function') {
+    throw new TypeError('C2 receipt ingress fatal hook needs log and shutdown')
+  }
+  let fired = false
+  return error => {
+    if (fired) return
+    fired = true
+    log('C2 receipt ingress failed: ' + (error && error.message || String(error)))
+    return shutdown('C2 receipt ingress failed', 1)
+  }
+}
+
+function fail(message) {
+  process.stderr.write(`sintbot: ${message}\n`)
+  process.exitCode = 1
+}
+
+const HELP = `SintBot macOS Feishu single-group release
+Usage:
+  sintbot init [--config <absolute path>]
+  sintbot start [--config <absolute path>] [--preflight]
+  sintbot version
+  sintbot help
+
+Supports one explicit Feishu group using Codex. Start runs in the foreground.
+Initialization is for a new installation only; existing journals are never reset.
+Canvas, multiple groups, console, scheduled tasks, terminal chat and other platforms are unavailable.
+`
+
+async function main(argv = process.argv.slice(2)) {
+  const [sub, ...rest] = argv
+  if (sub === 'version' || sub === '--version' || sub === '-v') {
+    if (rest.length) throw new Error('version does not accept arguments')
+    process.stdout.write(require('../package.json').version + '\n')
+    return
+  }
+  if (!sub || sub === 'help' || sub === '--help' || sub === '-h' ||
+      ['init', 'start'].includes(sub) && rest.length === 1 && ['--help', '-h'].includes(rest[0])) {
+    process.stdout.write(HELP)
+    return
+  }
+  if (!['init', 'start'].includes(sub)) {
+    throw new Error(`${sub} is unavailable in this single-group release; use sintbot help`)
+  }
+  if (process.platform !== 'darwin') throw new Error('this release supports macOS only')
+  if (sub === 'init') {
+    const { values } = parseArgs({ args: rest, allowPositionals: false,
+      options: { config: { type: 'string' } } })
+    require('../src/c2install').initializeInstallation(values.config)
+    process.stdout.write('SintBot journal initialized; run sintbot start to connect the configured group.\n')
+    return
+  }
+  await startService(rest)
+}
+
+if (require.main === module) main().catch(error => fail(error?.message || String(error)))
+module.exports = { main, createC2ReceiptIngressFatalHook }

package/docs/AI-ASSISTED-INSTALL.md

@@ -0,0 +1,19 @@
+# Install SintBot 1.3.0 with an AI assistant
+
+English · [简体中文](./zh-CN/AI-ASSISTED-INSTALL.md)
+
+Use the terminal on the Mac that will run SintBot. A cloud shell cannot install it on the user's Mac. Follow the [installation guide](./install.md); its supported route is one Feishu group, Codex and a foreground process.
+
+1. Check macOS, Node 22+, the actual Codex executable/login and any existing SintBot process. Do not print credentials. Preserve existing installations, configuration and state.
+2. Download and inspect the installer, run its `--dry-run`, then install the exact package into a new prefix. Continue within the user's authorization; ask only for missing decisions. The installer does not change Node, Codex, shell profiles or services.
+3. Use the executable under that prefix and verify it reports `1.3.0`. Do not substitute a globally installed command. A successful package install is not a successful group test.
+4. Prepare the single-group configuration in the install guide. Let the user enter secrets locally or use already authorized credential references without revealing them. Use an existing authorized Feishu app only when another process is not connected to it. If app setup or login requires the user, finish other independent preparation first.
+5. For fresh state only, run `init`, then `start --preflight`. Refusal due to old state or unresolved receipts is a stop condition: never delete files, fabricate a new authority or alter receipts to bypass it.
+6. Run the foreground service, send an authorized read-only group request and compare its response with the file. Stop cleanly and verify a restart. If no person is available, use an authorized test account to send the request; document the sender and do not call it independent human acceptance. A bot's own API message may be ignored and is not a substitute for an incoming user message.
+7. Stop temporary processes before ending the task. Report what was installed, what actually ran and any remaining setup. Do not register an automatic background service for this release.
+
+## Copyable request
+
+```text
+Install SintBot 1.3.0 on this Mac using the versioned, isolated installation guide. Preserve existing services, configuration, state and Codex account data. Do not expose credentials. Verify the actual installed executable and binary core, configure one Feishu group for Codex, and initialize only clean new state. Run the foreground preflight and an authorized read-only group test, check the result, then verify clean stop/restart. Do not use the old setup, console or service-install flow. Stop temporary processes when finished, and distinguish package installation from successful group acceptance.
+```

package/docs/install.md

@@ -0,0 +1,93 @@
+# Install SintBot 1.3.0
+
+English · [简体中文](./zh-CN/install.md)
+
+This release supports macOS, Node.js 22+, one Feishu group and Codex message turns. It runs in the foreground. Multiple groups, other chat platforms or model routes, the console, automatic service setup, scheduled tasks, terminal chat and whiteboards are not supported in 1.3.0.
+
+## 1. Prepare the Mac
+
+Use a terminal on the Mac where the project lives. Confirm Node.js 22+ and a working, authenticated Codex installation. Keep the existing Codex installation and account data. The SintBot installer does not install or log in to Codex and does not install Node.
+
+```bash
+node --version
+codex --version
+```
+
+If this Mac already runs SintBot, leave it running its current package and configuration. A separate package prefix is safe to install, but **1.3.0 does not automatically migrate existing state**. Its initialization refuses existing state, old receipts or an existing journal. Do not delete these files to bypass that check. Do not connect two processes to the same Feishu application.
+
+## 2. Install into a separate directory
+
+Download and inspect the installer, then run the same file:
+
+```bash
+curl -fsSL https://sintbot.com/install.sh -o /tmp/sintbot-install.sh
+bash /tmp/sintbot-install.sh --dry-run
+bash /tmp/sintbot-install.sh
+```
+
+It installs **sintbot@1.3.0** into `~/.local/share/sintbot/releases/1.3.0`, checks the actual executable, binary core and Feishu module, and leaves global packages, shell profiles, configuration and services untouched. It refuses an existing target directory. Use `--prefix /new/absolute/directory` for a different location. `--dry-run` makes no changes and does not fetch a package.
+
+Keep using the exact executable, so an older global command cannot be selected accidentally:
+
+```bash
+SINTBOT="$HOME/.local/share/sintbot/releases/1.3.0/bin/sintbot"
+"$SINTBOT" --version
+"$SINTBOT" help
+```
+
+The expected version is `1.3.0`. Installing the package does not start a bot.
+
+## 3. Configure one Feishu group
+
+Create a Feishu enterprise custom application on `open.feishu.cn`, enable its bot, grant message reception and reply permissions, choose long-connection event delivery, subscribe to message reception, publish the application and add its bot to your test group. Obtain that group's `oc_…` chat ID from Feishu. Use the China Feishu platform; international Lark is not supported.
+
+Enter the app ID and app secret locally as `FEISHU_APP_ID` and `FEISHU_APP_SECRET` environment variables in the terminal that will start SintBot. Do not paste the secret into chat or commit it to your repository. Environment references are resolved at startup; both values must be present in each new terminal session.
+
+Create the private configuration directory with `mkdir -p ~/.sbot && chmod 700 ~/.sbot`, then create `~/.sbot/config-1.3.0.json` with the following content. Replace the group ID and project path with actual values. The project must already exist. Keep exactly one group and the two explicit `false` flags.
+
+```json
+{
+  "defaultProvider": "codex",
+  "providers": { "codex": { "runner": "codex" } },
+  "feishu": {
+    "appId": "env:FEISHU_APP_ID",
+    "appSecret": "env:FEISHU_APP_SECRET",
+    "onlyWhenMentioned": false
+  },
+  "groups": {
+    "oc_REPLACE_WITH_YOUR_CHAT_ID": {
+      "platform": "feishu",
+      "provider": "codex",
+      "workdir": "/absolute/path/to/your/project",
+      "permissionMode": "dontAsk",
+      "codexSteer": false,
+      "codexApp": false
+    }
+  }
+}
+```
+
+Keep the configuration private (`chmod 600 ~/.sbot/config-1.3.0.json`). This example begins read-only and receives ordinary messages in this one group; use a dedicated test group. To require mentions instead, set `onlyWhenMentioned: true` and supply the actual app-specific `botOpenId`; startup rejects a missing bot ID. Do not add console, other-platform, scheduled-task or whiteboard settings from an older example. The full historical configuration schema is not the supported 1.3.0 setup.
+
+## 4. Initialize and start
+
+For a **new installation only**:
+
+```bash
+"$SINTBOT" init --config "$HOME/.sbot/config-1.3.0.json"
+"$SINTBOT" start --config "$HOME/.sbot/config-1.3.0.json" --preflight
+"$SINTBOT" start --config "$HOME/.sbot/config-1.3.0.json"
+```
+
+`init` creates a new persistent receipt journal at `~/.sbot/c2-v2.log`; it never resets an existing journal or migrates old state. Run it once. `--preflight` checks local configuration and assembly without starting the Feishu connection; it does not prove authentication or message delivery. `start` holds the single-writer lock and connects the configured group. Keep that terminal open.
+
+Send a message in the group and request the first line of the project's README. Check the returned line against the file. Press Ctrl-C and wait for the process to exit, then run the same `start` command again. Do not rerun `init` for normal restarts.
+
+## Stop, failure and upgrades
+
+- Stop with Ctrl-C and wait for shutdown. This version does not provide automatic login startup or a service-install command.
+- If a request fails or startup reports unresolved receipts, preserve the journal and state. Verify what happened before retrying. Do not clear unknown effects, overwrite the journal or run the same task again blindly.
+- The installer never replaces an earlier package. A version change still requires draining the old process, preserving configuration/state and checking receipt compatibility. A spare executable alone is not a safe rollback of state.
+- Existing multi-group installations remain on their previous release. A reviewed migration is required before replacing them with this single-group route.
+
+See the [AI-assisted guide](./AI-ASSISTED-INSTALL.md) if an assistant is performing the local steps.

package/docs/zh-CN/AI-ASSISTED-INSTALL.md

@@ -0,0 +1,19 @@
+# 用 AI 助手安装 SintBot 1.3.0
+
+[English](../AI-ASSISTED-INSTALL.md) · 简体中文
+
+使用实际运行 SintBot 的 Mac 本地终端；云端终端不能替用户的 Mac 安装。按[安装指南](./install.md)操作，本版支持一个飞书群、Codex 与前台运行。
+
+1. 核对 macOS、Node 22 及以上、Codex 实际程序与登录、是否已有 SintBot 进程。不输出凭据，保留已有安装、配置和状态。
+2. 下载并检查安装器，运行 `--dry-run`，再装到全新目录。用户已经授权的步骤继续执行，只问缺失的决定。安装器不修改 Node、Codex、终端配置或服务。
+3. 使用独立目录中的实际入口，确认输出 `1.3.0`，不要误用全局旧命令。安装程序包成功不等于群测试成功。
+4. 按安装指南准备单群配置。让用户在本地输入密钥，或使用已经授权的凭据引用，不显示秘密。复用授权飞书应用时，确认没有另一个进程连接该应用。应用或登录需要本人操作时，先完成其他独立准备。
+5. 只有全新状态才能执行 `init`，然后执行 `start --preflight`。若已有旧状态或未结收据而拒绝启动，不得删文件、新造日志权威或篡改收据来绕过。
+6. 前台运行，用已经授权的账号在群内发只读请求，把回复和文件对照，再正常停止并验证重启。没有真人协助时可用授权测试账号发送，并记录实际发送方式，不称为独立真人验收；机器人自己发的接口消息可能被忽略，不能当作用户入站消息。
+7. 本轮临时进程用完停止。说明安装了什么、实际验证了什么、还缺什么。本版不注册自动后台服务。
+
+## 可复制的请求
+
+```text
+按独立目录安装指南，在这台 Mac 安装 SintBot 1.3.0。保留已有服务、配置、状态和 Codex 账号数据，不输出凭据。验证实际入口与二进制核心，配置一个飞书群使用 Codex，只对全新状态初始化。运行前台预检和已授权的只读群测试，对照结果，再验证正常停止与重启。不要用旧版向导、控制台或安装服务流程。完成后停止临时进程，并区分程序包安装与群验收结果。
+```

package/docs/zh-CN/install.md

@@ -0,0 +1,93 @@
+# 安装 SintBot 1.3.0
+
+[English](../install.md) · 简体中文
+
+本版支持 macOS、Node.js 22 及以上、一个飞书群和 Codex 消息轮次，以前台方式运行。多群、其他聊天平台或模型通道、控制台、自动后台服务、定时任务、终端聊天和画布不在 1.3.0 支持范围。
+
+## 1. 准备 Mac
+
+在项目所在 Mac 的本地终端操作，确认 Node.js 22 及以上、Codex 可以实际运行且已完成登录。保留已有 Codex 安装和账号数据。SintBot 安装器不安装或登录 Codex，也不安装 Node。
+
+```bash
+node --version
+codex --version
+```
+
+如果这台 Mac 已经运行 SintBot，保留原来的程序包与配置。可以把新包装到独立目录，但 **1.3.0 不自动迁移已有状态**。初始化会拒绝已有状态、旧收据或日志；不要删除它们来绕过检查。不要让两个进程连接同一个飞书应用。
+
+## 2. 安装到独立目录
+
+下载并检查安装脚本，再执行同一份文件：
+
+```bash
+curl -fsSL https://sintbot.com/install.sh -o /tmp/sintbot-install.sh
+bash /tmp/sintbot-install.sh --dry-run
+bash /tmp/sintbot-install.sh
+```
+
+脚本把精确的 **sintbot@1.3.0** 安装到 `~/.local/share/sintbot/releases/1.3.0`，验证实际入口、二进制核心和飞书模块，保留全局安装、终端配置、应用配置和服务。目标目录已存在时拒绝覆盖；可用 `--prefix /全新/绝对/目录` 指定其他位置。`--dry-run` 不修改文件，也不下载程序包。
+
+始终使用这一个实际入口，避免误用全局旧版本：
+
+```bash
+SINTBOT="$HOME/.local/share/sintbot/releases/1.3.0/bin/sintbot"
+"$SINTBOT" --version
+"$SINTBOT" help
+```
+
+版本输出应为 `1.3.0`。装好程序包不会自动启动机器人。
+
+## 3. 配置一个飞书群
+
+在 `open.feishu.cn` 创建企业自建应用，启用机器人，授予接收与回复消息的权限，事件订阅选择长连接，订阅消息接收事件，发布应用并把机器人加入测试群。从飞书取得该群的 `oc_…` 群 ID。本版使用中国区飞书，不支持国际版 Lark。
+
+在启动 SintBot 的本地终端中，把应用 ID 和应用密钥分别设为 `FEISHU_APP_ID`、`FEISHU_APP_SECRET` 环境变量。不要把密钥发进聊天或提交到仓库。配置中的环境变量引用在启动时解析；每次新开终端都需要保证这两个变量存在。
+
+先用 `mkdir -p ~/.sbot && chmod 700 ~/.sbot` 创建私有配置目录，再创建 `~/.sbot/config-1.3.0.json`，内容如下。把群 ID 和项目路径换成真实值；项目目录必须已存在。只留一个群，两个显式 `false` 不要省略。
+
+```json
+{
+  "defaultProvider": "codex",
+  "providers": { "codex": { "runner": "codex" } },
+  "feishu": {
+    "appId": "env:FEISHU_APP_ID",
+    "appSecret": "env:FEISHU_APP_SECRET",
+    "onlyWhenMentioned": false
+  },
+  "groups": {
+    "oc_REPLACE_WITH_YOUR_CHAT_ID": {
+      "platform": "feishu",
+      "provider": "codex",
+      "workdir": "/absolute/path/to/your/project",
+      "permissionMode": "dontAsk",
+      "codexSteer": false,
+      "codexApp": false
+    }
+  }
+}
+```
+
+限制配置文件权限（`chmod 600 ~/.sbot/config-1.3.0.json`）。示例采用只读权限，接收这一个群里的普通消息，请使用专用测试群。若只接收 @ 机器人的消息，须设 `onlyWhenMentioned: true` 并填入该应用实际的 `botOpenId`；缺少机器人 ID 会在启动前被拒绝。不要从旧示例复制控制台、其他平台、定时任务或画布配置；历史完整配置不代表 1.3.0 支持范围。
+
+## 4. 初始化并启动
+
+**仅全新安装**执行：
+
+```bash
+"$SINTBOT" init --config "$HOME/.sbot/config-1.3.0.json"
+"$SINTBOT" start --config "$HOME/.sbot/config-1.3.0.json" --preflight
+"$SINTBOT" start --config "$HOME/.sbot/config-1.3.0.json"
+```
+
+`init` 在 `~/.sbot/c2-v2.log` 创建持久收据日志，只运行一次；不会重置已有日志或迁移旧状态。`--preflight` 检查本地配置与装配，不建立飞书连接，也不能代替认证或消息送达验证。`start` 持有单写锁并连接所配群，需要保持终端开启。
+
+在群里直接发消息，要求读取项目 README 的第一行。把返回结果与文件对照。按 Ctrl-C 并等待退出，再用相同的 `start` 命令启动一次。正常重启不要重新执行 `init`。
+
+## 停止、故障和升级
+
+- 按 Ctrl-C 并等待退出；本版不提供登录自启或安装后台服务命令。
+- 任务失败或启动提示未结收据时，保留日志与状态，核对实际结果后再处置。不要清空未知效果、覆盖日志或盲目重发相同任务。
+- 安装器保留旧程序包，但切版本仍须排空旧进程、备份配置与状态、确认收据兼容。只有旧可执行文件不等于可以安全回退状态。
+- 已有多群安装继续用原版本，替换为单群路径前必须有经过核对的迁移方案。
+
+由助手操作时可用 [AI 辅助安装指南](./AI-ASSISTED-INSTALL.md)。