@mortiseai/stem 0.0.12 → 0.0.14

package/bin/stem-supervisor-lib.mjs

@@ -0,0 +1,212 @@
+// supervisor 逻辑库(2026-08-12 OOM 治理)— bin/stem.mjs 的看护实现。
+// 独立成库的唯一理由:入口脚本 import 即执行,smoke 无法直接测;这里的函数
+// 全部纯逻辑/可注入,scripts/smoke-supervisor.ts 逐项锁语义。
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { spawn, spawnSync } from 'node:child_process'
+
+// 配置类错误的专用退出码(stem-entry-cli 侧同值):见 78 不重启。
+export const EXIT_CODE_CONFIG = 78
+export const CRASH_WINDOW_MS = 60_000
+export const CRASH_GIVE_UP_COUNT = 3
+export const RESTART_BACKOFF_MAX_MS = 10_000
+
+/** 从 argv 剥离 --resume/-r(supervisor 重启时按通告会话重挂)。 */
+export function stripResumeFlag(argv) {
+  const out = []
+  let resumeId = null
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--resume' || a === '-r') {
+      const next = argv[i + 1]
+      if (next !== undefined && !next.startsWith('-')) { resumeId = next; i++ }
+      continue
+    }
+    if (a.startsWith('--resume=')) { resumeId = a.slice('--resume='.length); continue }
+    out.push(a)
+  }
+  return { baseArgs: out, resumeId }
+}
+
+/** 崩溃截断的 JSONL 尾部修补:从尾剔除解析失败的行,直到最后一行是合法 JSON。
+ *  返回 true = 有修补并已重写。 */
+export function repairJsonlTail(path) {
+  let raw
+  try { raw = readFileSync(path, 'utf8') } catch { return false }
+  if (!raw) return false
+  const lines = raw.split('\n')
+  while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop()
+  let dropped = 0
+  while (lines.length > 0) {
+    try { JSON.parse(lines[lines.length - 1]); break } catch { lines.pop(); dropped++ }
+  }
+  if (dropped === 0) return false
+  try {
+    writeFileSync(path, lines.length > 0 ? lines.join('\n') + '\n' : '')
+    return true
+  } catch { return false }
+}
+
+/** 自包含续跑 prompt:恢复的 transcript 无工具轨迹,"继续"两个字会让模型空转
+ *  (2026-08-07 实测)— 必须指回 todo/计划文档重建进度认知。 */
+export function restartPrompt(isZh) {
+  return isZh
+    ? '[系统] 进程因异常(疑似内存溢出)已自动重启,本会话对话已从磁盘恢复,但工具执行轨迹与中间状态未保留。请先读取当前 todo 列表与相关任务/计划文档核对实际进度(必要时用命令验证已完成的部分),然后从未完成项继续执行;不要重复已完成的工作,也不要只回复确认性文字。'
+    : '[system] The process crashed (likely OOM) and was restarted automatically. The conversation was restored from disk, but tool execution traces and intermediate state were lost. First read the current todo list and any task/plan documents to verify actual progress (validate completed parts with commands if needed), then continue from the unfinished items. Do not redo completed work or reply with acknowledgements only.'
+}
+
+/** 注入续跑 prompt 到队列 sidecar(userPromptQueueStore 格式;resume 分支自动
+ *  再水合、经 idle-gate 依次执行)。cleanExit: true 让 resume 端静默续跑而非弹
+ *  y/n 确认 — 无人值守是看护的前提;连崩风暴由退避与 3 次放弃兜底。既有排队
+ *  prompt 保留在后(去重防多次崩溃堆叠)。 */
+export function injectRestartPrompt(queuePath, isZh) {
+  const prompt = restartPrompt(isZh)
+  let existing = []
+  try {
+    const parsed = JSON.parse(readFileSync(queuePath, 'utf8'))
+    if (parsed && parsed.v === 1 && Array.isArray(parsed.queue)) {
+      existing = parsed.queue.filter(x => typeof x === 'string' && x !== prompt)
+    }
+  } catch { /* 无文件/坏文件 → 全新队列 */ }
+  try {
+    mkdirSync(dirname(queuePath), { recursive: true })
+    writeFileSync(
+      queuePath,
+      JSON.stringify({ v: 1, savedAtMs: Date.now(), queue: [prompt, ...existing], cleanExit: true }, null, 2) + '\n',
+    )
+    return true
+  } catch { return false }
+}
+
+/** 崩溃堆快照清理:只保留最新一份 Heap.*.heapsnapshot(防 24h 连跑占满磁盘)。 */
+export function cleanupHeapSnapshots(dir) {
+  let entries
+  try { entries = readdirSync(dir).filter(f => /^Heap\..*\.heapsnapshot$/.test(f)) } catch { return }
+  if (entries.length <= 1) return
+  const withTime = entries.map(f => {
+    try { return { f, t: statSync(join(dir, f)).mtimeMs } } catch { return { f, t: 0 } }
+  }).sort((a, b) => b.t - a.t)
+  for (const { f } of withTime.slice(1)) {
+    try { rmSync(join(dir, f), { force: true }) } catch { /* 占用中等失败静默 */ }
+  }
+}
+
+/** 崩溃现场的终端复位:OOM abort 不走 ink 的退出钩子,raw mode / alt screen /
+ *  mouse tracking 可能全部残留 — 下一个子进程起来前主动复位。 */
+export function resetTerminal() {
+  try {
+    process.stdout.write('\x1b[?1049l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?2004l\x1b[?25h')
+  } catch { /* 输出失败无害 */ }
+  try { process.stdin.setRawMode?.(false) } catch { /* 非 TTY / 已复位 */ }
+}
+
+function defaultSpawnChild(args, env) {
+  const child = spawn(process.execPath, args, { stdio: 'inherit', env })
+  return {
+    pid: child.pid,
+    exited: new Promise(resolve => {
+      child.on('exit', (code, signal) => resolve({ code, signal }))
+      child.on('error', () => resolve({ code: 1, signal: null }))
+    }),
+  }
+}
+
+/**
+ * 看护主循环。overrides 供 smoke 注入:
+ *   spawnChild(args, env) → {pid, exited: Promise<{code, signal}>}
+ *   sleep(ms) / log(text) / now() / cwd
+ * 返回最终退出码。
+ */
+export async function runSupervisor(distEntry, argv, options = {}) {
+  const {
+    isZh = true,
+    nodeFlags = [],
+    spawnChild = defaultSpawnChild,
+    sleep = ms => new Promise(r => setTimeout(r, ms)),
+    log = text => { try { process.stderr.write(`\x1b[2;38;2;156;163;175m${text}\x1b[0m\n`) } catch { /* ignore */ } },
+    now = Date.now,
+    cwd = process.cwd(),
+    announceFile = join(mkdtempSync(join(tmpdir(), 'stem-supervisor-')), 'session.json'),
+    resetTerminalFn = resetTerminal,
+    onCrashCleanupPid = pid => {
+      // Windows 下 best-effort 清理子进程树残留(MCP npx/uvx 僵尸);根进程已死时
+      // taskkill 可能报错,静默即可。
+      if (process.platform === 'win32' && pid) {
+        try { spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' }) } catch { /* ignore */ }
+      }
+    },
+    installSignalHandlers = true,
+  } = options
+
+  let { baseArgs, resumeId } = stripResumeFlag(argv)
+  let crashTimes = []
+  let childAlive = false
+
+  if (installSignalHandlers) {
+    // Windows CTRL_C_EVENT 广播父子都收:父进程吞掉,让子进程自己处理(单击中断 /
+    // 双击退出 → exit 0 → 看护正常收口)。子进程不存活时(退避等待期)按用户退出处理。
+    process.on('SIGINT', () => { if (!childAlive) process.exit(130) })
+    process.on('SIGTERM', () => process.exit(143))
+  }
+
+  for (;;) {
+    cleanupHeapSnapshots(cwd)
+    const args = [...nodeFlags, distEntry, ...baseArgs]
+    if (resumeId) args.push('--resume', resumeId)
+    const child = spawnChild(args, {
+      ...process.env,
+      STEM_SUPERVISED: '1',
+      STEM_SESSION_ANNOUNCE_FILE: announceFile,
+    })
+    childAlive = true
+    const { code, signal } = await child.exited
+    childAlive = false
+
+    if (code === 0) return 0
+    if (code === EXIT_CODE_CONFIG) {
+      log(isZh
+        ? 'stem: 配置错误退出(code 78),看护不重启 — 请修正配置后重新运行。'
+        : 'stem: exited with a configuration error (code 78); supervisor will not restart. Fix the configuration and run again.')
+      return EXIT_CODE_CONFIG
+    }
+
+    // 崩溃路径。60 秒窗口内连崩 3 次 → 放弃(配置外的持续性故障,重启无益)。
+    const t = now()
+    crashTimes = crashTimes.filter(x => t - x < CRASH_WINDOW_MS)
+    crashTimes.push(t)
+    resetTerminalFn()
+    if (crashTimes.length >= CRASH_GIVE_UP_COUNT) {
+      log(isZh
+        ? `stem: 60 秒内连续崩溃 ${crashTimes.length} 次(code=${code ?? '-'}, signal=${signal ?? '-'}),停止自动重启。`
+        : `stem: crashed ${crashTimes.length} times within 60s (code=${code ?? '-'}, signal=${signal ?? '-'}); giving up on auto-restart.`)
+      return typeof code === 'number' && code !== 0 ? code : 1
+    }
+
+    // 会话通告(子进程在每个会话切换点写):拿到真实 sessionId 与 sidecar 路径,
+    // 修补崩溃截断的 JSONL 尾部 + 注入续跑队列。子进程死在通告前 → 沿用现有 resumeId。
+    let announce = null
+    try {
+      const parsed = JSON.parse(readFileSync(announceFile, 'utf8'))
+      if (parsed && parsed.v === 1 && typeof parsed.sessionId === 'string') announce = parsed
+    } catch { /* ignore */ }
+    if (announce) {
+      resumeId = announce.sessionId
+      for (const p of Array.isArray(announce.jsonlPaths) ? announce.jsonlPaths : []) {
+        if (typeof p === 'string' && existsSync(p) && repairJsonlTail(p)) {
+          log(isZh ? `stem: 已修补崩溃截断的会话记录 ${p}` : `stem: repaired crash-truncated session log ${p}`)
+          break
+        }
+      }
+      if (typeof announce.queuePath === 'string') injectRestartPrompt(announce.queuePath, isZh)
+    }
+
+    onCrashCleanupPid(child.pid)
+
+    const delayMs = Math.min(1000 * 2 ** (crashTimes.length - 1), RESTART_BACKOFF_MAX_MS)
+    log(isZh
+      ? `stem: 进程异常退出(code=${code ?? '-'}, signal=${signal ?? '-'}),${Math.round(delayMs / 1000)}s 后自动恢复会话${resumeId ? ` ${resumeId}` : ''}…(STEM_NO_SUPERVISOR=1 可关闭看护)`
+      : `stem: process crashed (code=${code ?? '-'}, signal=${signal ?? '-'}); resuming session${resumeId ? ` ${resumeId}` : ''} in ${Math.round(delayMs / 1000)}s… (set STEM_NO_SUPERVISOR=1 to disable)`)
+    await sleep(delayMs)
+  }
+}

package/bin/stem.mjs

@@ -1,6 +1,14 @@
 #!/usr/bin/env node
 // 跨平台启动器(macOS / Linux / Windows):npm 全局安装经 cmd-shim / 软链均可调用。
 // 语义对齐旧 bin/stem bash 版:CALLER_DIR 透传、.env 仅补缺不覆盖、STEM_DEV 走 bun 源码。
+//
+// 看护模式(2026-08-12 OOM 治理):交互式 TUI 默认由本进程看护 — 子进程崩溃
+// (OOM FATAL ERROR 在进程内不可拦截:同步分配风暴会锁死事件循环,任何 JS 层
+// 守护都没有执行机会)时自动:修补会话 JSONL 尾部(崩溃可能截断半行,不修则
+// --resume 直接拒载)→ 注入自包含续跑 prompt 到队列 sidecar → --resume 同一
+// 会话重启。正常退出(exit 0)与配置错误(exit 78)不重启;60 秒内连崩 3 次
+// 放弃。STEM_NO_SUPERVISOR=1 退回单次直跑;实现与语义锁定见
+// bin/stem-supervisor-lib.mjs 与 scripts/smoke-supervisor.ts。
 import { existsSync, realpathSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { devNull } from 'node:os'
@@ -20,21 +28,57 @@ if (!skipDotenv && existsSync(envFile)) {
   process.loadEnvFile(envFile)
 }
 
-const distEntry = join(rootDir, 'dist', 'cli.mjs')
-if (process.env.STEM_DEV !== '1' && existsSync(distEntry)) {
-  // 长会话内存水位高(UI 历史 + 渲染缓冲),Node 默认老生代上限 ~4GB 在大并发
-  // 子任务场景会 OOM。V8 堆参数只能在进程启动时生效,所以未显式配置时 re-exec
-  // 一次,把 --max-old-space-size=8192 带给真正的 CLI 进程;用户自己的
-  // NODE_OPTIONS / execArgv 配置优先,不覆盖。
-  const heapConfigured =
+const isZh = !(process.env.STEM_LOCALE ?? process.env.LANG ?? 'zh').toLowerCase().startsWith('en')
+
+/** 用户显式 heap 配置探测 — 有则不覆盖(用户的 NODE_OPTIONS/execArgv 优先)。 */
+function heapConfigured() {
+  return (
     process.execArgv.some(a => a.includes('--max-old-space-size')) ||
     (process.env.NODE_OPTIONS ?? '').includes('--max-old-space-size')
-  if (heapConfigured) {
+  )
+}
+
+/** 子进程 node flags:heap 上限(未显式配置时)+ OOM 前堆快照(可关)。 */
+function childNodeFlags() {
+  const flags = []
+  if (!heapConfigured()) flags.push('--max-old-space-size=8192')
+  // OOM 前自动堆快照:定位"未知同步分配风暴"元凶的唯一现实手段(手动
+  // /heapdump 在同步爆发下来不及)。代价是崩溃时写数 GB 快照;supervisor
+  // 每轮 spawn 前清理只留最新一份。STEM_HEAP_SNAPSHOT=0 关闭。
+  if (
+    process.env.STEM_HEAP_SNAPSHOT !== '0' &&
+    !(process.env.NODE_OPTIONS ?? '').includes('--heapsnapshot-near-heap-limit')
+  ) {
+    flags.push('--heapsnapshot-near-heap-limit=1')
+  }
+  return flags
+}
+
+/** 看护适用性:交互式 TUI 才看护;fast-echo / SDK 桥 / 已被看护的子进程不看。 */
+function shouldSupervise(argv) {
+  if (process.env.STEM_NO_SUPERVISOR === '1') return false
+  if (process.env.STEM_SUPERVISED === '1') return false
+  if (!process.stdout.isTTY || !process.stdin.isTTY) return false
+  const nonInteractive = new Set(['--help', '-h', '--version', '-v', '--print'])
+  return !argv.some(a => nonInteractive.has(a) || a === '--sdk-url' || a.startsWith('--sdk-url='))
+}
+
+const distEntry = join(rootDir, 'dist', 'cli.mjs')
+if (process.env.STEM_DEV !== '1' && existsSync(distEntry)) {
+  const argv = process.argv.slice(2)
+  if (shouldSupervise(argv)) {
+    const { runSupervisor } = await import(pathToFileURL(join(rootDir, 'bin', 'stem-supervisor-lib.mjs')).href)
+    process.exit(await runSupervisor(distEntry, argv, { isZh, nodeFlags: childNodeFlags() }))
+  } else if (heapConfigured()) {
+    // 长会话内存水位高(UI 历史 + 渲染缓冲),Node 默认老生代上限 ~4GB 在大并发
+    // 子任务场景会 OOM。V8 堆参数只能在进程启动时生效;用户已显式配置时同进程直跑。
     await import(pathToFileURL(distEntry).href)
   } else {
+    // 非看护场景(fast-echo / SDK 桥 / STEM_NO_SUPERVISOR)单次 re-exec,
+    // 把 --max-old-space-size 带给真正的 CLI 进程。
     const result = spawnSync(
       process.execPath,
-      ['--max-old-space-size=8192', distEntry, ...process.argv.slice(2)],
+      ['--max-old-space-size=8192', distEntry, ...argv],
       { stdio: 'inherit' },
     )
     process.exit(result.status ?? 1)
@@ -53,13 +97,12 @@ if (process.env.STEM_DEV !== '1' && existsSync(distEntry)) {
   )
   if (result.error && result.error.code === 'ENOENT') {
     // i18n: 启动器双语(CLI 还没起来,无法走 JS catalog)
-    const locale = (process.env.STEM_LOCALE ?? process.env.LANG ?? 'zh').toLowerCase()
     console.error(
-      locale.startsWith('en')
-        ? "stem: dist/cli.mjs not found and 'bun' is not on PATH.\n" +
-          "Run 'bun run build' in the repo, or install bun (https://bun.sh) to use dev mode."
-        : 'stem: 未找到 dist/cli.mjs,且 PATH 中没有 \'bun\'。\n' +
-          "请在仓库根目录执行 'bun run build',或安装 bun (https://bun.sh) 以使用 dev 模式。",
+      isZh
+        ? 'stem: 未找到 dist/cli.mjs,且 PATH 中没有 \'bun\'。\n' +
+          "请在仓库根目录执行 'bun run build',或安装 bun (https://bun.sh) 以使用 dev 模式。"
+        : "stem: dist/cli.mjs not found and 'bun' is not on PATH.\n" +
+          "Run 'bun run build' in the repo, or install bun (https://bun.sh) to use dev mode.",
     )
     process.exit(1)
   }