@mortiseai/stem 0.0.15 → 0.0.17

package/bin/stem-supervisor-lib.mjs

@@ -1,9 +1,9 @@
 // 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 { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import { tmpdir } from 'node:os'
+import { homedir, tmpdir } from 'node:os'
 import { spawn, spawnSync } from 'node:child_process'
 
 // 配置类错误的专用退出码(stem-entry-cli 侧同值):见 78 不重启。
@@ -48,25 +48,41 @@ export function repairJsonlTail(path) {
   } catch { return false }
 }
 
+/** 崩溃原因短描述:supervisor 只有退出码/信号这一手证据,文案如实转述,
+ *  不再硬编码"疑似内存溢出"(2026-08-13 事故:heap 仅 850MB 时死亡,OOM 猜测
+ *  误导了定性;heapsnapshot 也因 8GB 阈值够不着而缺失)。 */
+export function crashCauseText(crashInfo, isZh) {
+  const signal = crashInfo && typeof crashInfo.signal === 'string' && crashInfo.signal ? crashInfo.signal : null
+  const code = crashInfo && typeof crashInfo.code === 'number' ? crashInfo.code : null
+  if (signal) return isZh ? `信号 ${signal}` : `signal ${signal}`
+  if (code !== null) return isZh ? `退出码 ${code}` : `exit code ${code}`
+  return isZh ? '原因未知' : 'unknown cause'
+}
+
 /** 自包含续跑 prompt:恢复的 transcript 无工具轨迹,"继续"两个字会让模型空转
  *  (2026-08-07 实测)— 必须指回 todo/计划文档重建进度认知。 */
-export function restartPrompt(isZh) {
+export function restartPrompt(isZh, crashInfo) {
+  const cause = crashCauseText(crashInfo, 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.'
+    ? `[系统] 进程异常退出(${cause})已自动重启,本会话对话已从磁盘恢复,但工具执行轨迹与中间状态未保留。请先读取当前 todo 列表与相关任务/计划文档核对实际进度(必要时用命令验证已完成的部分),然后从未完成项继续执行;不要重复已完成的工作,也不要只回复确认性文字。`
+    : `[system] The process exited abnormally (${cause}) 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.`
 }
 
+// 注入队列的去重前缀:文案带崩溃原因(逐次可变),不能再按全串相等去重。
+const RESTART_PROMPT_PREFIXES = ['[系统] 进程异常退出', '[系统] 进程因异常', '[system] The process']
+
 /** 注入续跑 prompt 到队列 sidecar(userPromptQueueStore 格式;resume 分支自动
  *  再水合、经 idle-gate 依次执行)。cleanExit: true 让 resume 端静默续跑而非弹
  *  y/n 确认 — 无人值守是看护的前提;连崩风暴由退避与 3 次放弃兜底。既有排队
- *  prompt 保留在后(去重防多次崩溃堆叠)。 */
-export function injectRestartPrompt(queuePath, isZh) {
-  const prompt = restartPrompt(isZh)
+ *  prompt 保留在后(按前缀去重防多次崩溃堆叠)。 */
+export function injectRestartPrompt(queuePath, isZh, crashInfo) {
+  const prompt = restartPrompt(isZh, crashInfo)
   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)
+      existing = parsed.queue.filter(x =>
+        typeof x === 'string' && !RESTART_PROMPT_PREFIXES.some(p => x.startsWith(p)))
     }
   } catch { /* 无文件/坏文件 → 全新队列 */ }
   try {
@@ -79,6 +95,56 @@ export function injectRestartPrompt(queuePath, isZh) {
   } catch { return false }
 }
 
+/** 崩溃标记 sidecar(2026-08-13 事故:崩溃现场零证据,连退出信号都没记)。
+ *  与 queue sidecar 同目录,`<sessionId>.crash.json`;crashes 数组保最近 20 条,
+ *  下次排查直接看这里而不用翻 supervisor stderr。写失败静默(标记是诊断增强,
+ *  不能反过来阻断重启)。 */
+export function writeCrashMarker(queuePath, sessionId, crashInfo, nowMs, extras = {}) {
+  if (typeof queuePath !== 'string' || !queuePath) return false
+  const markerPath = queuePath.endsWith('.queue.json')
+    ? queuePath.slice(0, -'.queue.json'.length) + '.crash.json'
+    : join(dirname(queuePath), `${sessionId || 'session'}.crash.json`)
+  let crashes = []
+  try {
+    const parsed = JSON.parse(readFileSync(markerPath, 'utf8'))
+    if (parsed && parsed.v === 1 && Array.isArray(parsed.crashes)) crashes = parsed.crashes
+  } catch { /* 无文件/坏文件 → 全新标记 */ }
+  const entry = {
+    atMs: nowMs,
+    exitCode: crashInfo && typeof crashInfo.code === 'number' ? crashInfo.code : null,
+    signal: crashInfo && typeof crashInfo.signal === 'string' ? crashInfo.signal : null,
+  }
+  // 附加取证字段(2026-08-17 第五次崩溃:原生 SIGABRT 的 stderr 转储全部丢失,
+  // 只有 {exitCode, signal} 无法定因)— 全部可选、additive,v 保持 1,旧读方无感。
+  for (const [k, v] of Object.entries(extras)) {
+    if (v !== undefined && v !== null && v !== '') entry[k] = v
+  }
+  crashes.push(entry)
+  if (crashes.length > 20) crashes = crashes.slice(-20)
+  try {
+    mkdirSync(dirname(markerPath), { recursive: true })
+    writeFileSync(markerPath, JSON.stringify({ v: 1, sessionId: sessionId || null, crashes }, null, 2) + '\n')
+    return true
+  } catch { return false }
+}
+
+/** 从 argv 剥离 --permission-mode(重启时以通告里的实时模式为准 — 用户 Shift+Tab
+ *  切过的模式不在启动 argv 里,原样透传会把模式打回启动值,2026-08-13 事故实证
+ *  auto 崩后回落 default,自动续跑第一轮在降级权限下弹卡)。 */
+export function stripPermissionModeFlag(argv) {
+  const out = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--permission-mode') {
+      if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) i++
+      continue
+    }
+    if (a.startsWith('--permission-mode=')) continue
+    out.push(a)
+  }
+  return out
+}
+
 /** 崩溃堆快照清理:只保留最新一份 Heap.*.heapsnapshot(防 24h 连跑占满磁盘)。 */
 export function cleanupHeapSnapshots(dir) {
   let entries
@@ -101,12 +167,81 @@ export function resetTerminal() {
   try { process.stdin.setRawMode?.(false) } catch { /* 非 TTY / 已复位 */ }
 }
 
+/** stderr 尾部环形缓冲(2026-08-17 第五次崩溃:V8 fatal error 的原生转储直写
+ *  fd 2 打上 TUI 后丢失,`FATAL ERROR:` 首行是定因的唯一证据)。Buffer 数组累积,
+ *  超限从头丢弃;read() 返回尾部 utf8 文本。 */
+export function createStderrTail(maxBytes = 64 * 1024) {
+  const chunks = []
+  let total = 0
+  return {
+    push(chunk) {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))
+      chunks.push(buf)
+      total += buf.length
+      while (total > maxBytes && chunks.length > 1) total -= chunks.shift().length
+    },
+    read() {
+      const text = Buffer.concat(chunks).toString('utf8')
+      return text.length > maxBytes ? text.slice(-maxBytes) : text
+    },
+  }
+}
+
+/** 崩溃时刻之后生成的 macOS 原生崩溃报告(ReportCrash 对 SIGABRT/SIGSEGV 必产出,
+ *  含完整原生栈与 abort 原因)。只找不搬:报告数百 KB 且含系统信息。 */
+export function findDiagnosticReport(sinceMs, dir) {
+  let entries
+  try { entries = readdirSync(dir).filter(f => f.endsWith('.ips')) } catch { return null }
+  let best = null
+  for (const f of entries) {
+    try {
+      const t = statSync(join(dir, f)).mtimeMs
+      if (t >= sinceMs && (!best || t > best.t)) best = { f, t }
+    } catch { /* 读取中/权限失败跳过 */ }
+  }
+  return best ? join(dir, best.f) : null
+}
+
+/** 把 .ips 报告路径回填到 crash.json 最新一条崩溃条目(报告由 ReportCrash 异步
+ *  生成,writeCrashMarker 时通常还不存在,退避 sleep 后二次回填)。失败静默。 */
+export function attachDiagnosticReport(queuePath, sessionId, reportPath) {
+  if (typeof queuePath !== 'string' || !queuePath || !reportPath) return false
+  const markerPath = queuePath.endsWith('.queue.json')
+    ? queuePath.slice(0, -'.queue.json'.length) + '.crash.json'
+    : join(dirname(queuePath), `${sessionId || 'session'}.crash.json`)
+  try {
+    const parsed = JSON.parse(readFileSync(markerPath, 'utf8'))
+    if (!parsed || parsed.v !== 1 || !Array.isArray(parsed.crashes) || parsed.crashes.length === 0) return false
+    parsed.crashes[parsed.crashes.length - 1].diagnosticReport = reportPath
+    writeFileSync(markerPath, JSON.stringify(parsed, null, 2) + '\n')
+    return true
+  } catch { return false }
+}
+
 function defaultSpawnChild(args, env) {
-  const child = spawn(process.execPath, args, { stdio: 'inherit', env })
+  // stderr 走 pipe 而非 inherit:原生崩溃转储(V8 fatal / abort)绕过 JS 层拦截
+  // 直写 fd 2,inherit 时直接打上 TUI 且父进程零捕获(2026-08-17 事故)。pipe 后
+  // 实时透传回终端(行为不变)+ 环形缓冲留尾部作取证。TUI 渲染门只看 stdout/stdin
+  // 的 isTTY,stderr 非 TTY 的影响仅限着色(exitCleanup 的 hint 着色已改跟 stdout)。
+  const tail = createStderrTail()
+  const child = spawn(process.execPath, args, { stdio: ['inherit', 'inherit', 'pipe'], env })
+  child.stderr?.on('data', chunk => {
+    tail.push(chunk)
+    try { process.stderr.write(chunk) } catch { /* 终端已关闭等,透传失败无害 */ }
+  })
   return {
     pid: child.pid,
+    stderrTail: () => tail.read(),
     exited: new Promise(resolve => {
-      child.on('exit', (code, signal) => resolve({ code, signal }))
+      // 'close' 优先:exit 触发时 stderr pipe 可能还有未读完的崩溃转储,close 保证
+      // flush 完、stderrTail 不缺尾巴。但 close 会被继承了 stderr fd 的孙进程
+      // (MCP server 等)拖住 — 子进程死了管道还开着,close 迟迟不来(实测孙进程
+      // 活多久拖多久)→ 崩溃检测被无限延迟。所以 exit 后给 2s flush 宽限兜底,
+      // 两者先到先赢(resolve 幂等)。
+      child.on('close', (code, signal) => resolve({ code, signal }))
+      child.on('exit', (code, signal) => {
+        setTimeout(() => resolve({ code, signal }), 2000)
+      })
       child.on('error', () => resolve({ code: 1, signal: null }))
     }),
   }
@@ -128,6 +263,10 @@ export async function runSupervisor(distEntry, argv, options = {}) {
     now = Date.now,
     cwd = process.cwd(),
     announceFile = join(mkdtempSync(join(tmpdir(), 'stem-supervisor-')), 'session.json'),
+    // supervisor 自身诊断的持久化落点(2026-08-17 事故:崩溃信息只写终端,滚屏即丢)。
+    supervisorLogPath = join(cwd, 'logs', 'supervisor.log'),
+    // macOS ReportCrash 报告目录(smoke 可注入假目录)。
+    diagnosticReportsDir = join(homedir(), 'Library', 'Logs', 'DiagnosticReports'),
     resetTerminalFn = resetTerminal,
     onCrashCleanupPid = pid => {
       // Windows 下 best-effort 清理子进程树残留(MCP npx/uvx 僵尸);根进程已死时
@@ -139,9 +278,29 @@ export async function runSupervisor(distEntry, argv, options = {}) {
     installSignalHandlers = true,
   } = options
 
+  // log() 只写终端;logLine() 同时 append 到 supervisor.log(ISO 时间戳)—
+  // 崩溃路径一律用 logLine,子进程日志闸门(STEM_DEBUG)关着时这里仍有据可查。
+  const logFileOnly = text => {
+    if (!supervisorLogPath) return
+    try {
+      mkdirSync(dirname(supervisorLogPath), { recursive: true })
+      appendFileSync(supervisorLogPath, `${new Date(now()).toISOString()} ${text}\n`)
+    } catch { /* 诊断落盘失败不阻断看护 */ }
+  }
+  const logLine = text => {
+    log(text)
+    logFileOnly(text)
+  }
+  // stem 版本一次性读取(dist/cli.mjs → ../package.json),best-effort。
+  let stemVersion = null
+  try { stemVersion = JSON.parse(readFileSync(join(dirname(distEntry), '..', 'package.json'), 'utf8')).version ?? null } catch { /* smoke 假路径等 */ }
+
   let { baseArgs, resumeId } = stripResumeFlag(argv)
   let crashTimes = []
   let childAlive = false
+  // 崩溃前子进程通告的实时 permission mode(Shift+Tab 切换会更新通告)—
+  // 重启时经 --permission-mode 复原,argv 中的启动值被剥离让位。
+  let permissionModeFromAnnounce = null
 
   if (installSignalHandlers) {
     // Windows CTRL_C_EVENT 广播父子都收:父进程吞掉,让子进程自己处理(单击中断 /
@@ -152,7 +311,9 @@ export async function runSupervisor(distEntry, argv, options = {}) {
 
   for (;;) {
     cleanupHeapSnapshots(cwd)
-    const args = [...nodeFlags, distEntry, ...baseArgs]
+    const effectiveBase = permissionModeFromAnnounce ? stripPermissionModeFlag(baseArgs) : baseArgs
+    const args = [...nodeFlags, distEntry, ...effectiveBase]
+    if (permissionModeFromAnnounce) args.push('--permission-mode', permissionModeFromAnnounce)
     if (resumeId) args.push('--resume', resumeId)
     const child = spawnChild(args, {
       ...process.env,
@@ -176,8 +337,18 @@ export async function runSupervisor(distEntry, argv, options = {}) {
     crashTimes = crashTimes.filter(x => t - x < CRASH_WINDOW_MS)
     crashTimes.push(t)
     resetTerminalFn()
+    // stderr 尾部取证:pipe 捕获的原生崩溃转储(FATAL ERROR / abort 栈)。
+    // crash.json 里截 8KB;supervisor.log 无条件记一份 — 即便子进程死在首次
+    // announce 前(crash.json 写不了),这里也有据。
+    const stderrTail = typeof child.stderrTail === 'function' ? child.stderrTail() : ''
+    const stderrTail8k = stderrTail.length > 8 * 1024 ? stderrTail.slice(-8 * 1024) : stderrTail
+    if (stderrTail8k.trim()) {
+      logLine(isZh
+        ? `stem: 崩溃 stderr 尾部(code=${code ?? '-'}, signal=${signal ?? '-'}):\n${stderrTail8k}`
+        : `stem: crash stderr tail (code=${code ?? '-'}, signal=${signal ?? '-'}):\n${stderrTail8k}`)
+    }
     if (crashTimes.length >= CRASH_GIVE_UP_COUNT) {
-      log(isZh
+      logLine(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
@@ -192,21 +363,56 @@ export async function runSupervisor(distEntry, argv, options = {}) {
     } catch { /* ignore */ }
     if (announce) {
       resumeId = announce.sessionId
+      if (typeof announce.permissionMode === 'string' && announce.permissionMode) {
+        permissionModeFromAnnounce = announce.permissionMode
+      }
       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}`)
+          logLine(isZh ? `stem: 已修补崩溃截断的会话记录 ${p}` : `stem: repaired crash-truncated session log ${p}`)
           break
         }
       }
-      if (typeof announce.queuePath === 'string') injectRestartPrompt(announce.queuePath, isZh)
+      if (typeof announce.queuePath === 'string') {
+        // .tasks.json / .taskstate.json 的 mtime = 子进程最后一次任务落盘时刻,
+        // 用于回答"崩溃前它空闲了多久"(本次事故:空闲 8.5 分钟零遥测)。
+        const sidecarMtime = suffix => {
+          try { return statSync(announce.queuePath.replace(/\.queue\.json$/, suffix)).mtimeMs } catch { return undefined }
+        }
+        writeCrashMarker(announce.queuePath, announce.sessionId, { code, signal }, t, {
+          stderrTail: stderrTail8k,
+          args,
+          nodeVersion: process.version,
+          stemVersion,
+          announceUpdatedAtMs: typeof announce.updatedAtMs === 'number' ? announce.updatedAtMs : undefined,
+          tasksSnapshotMtimeMs: sidecarMtime('.tasks.json'),
+          taskStateMtimeMs: sidecarMtime('.taskstate.json'),
+        })
+        injectRestartPrompt(announce.queuePath, isZh, { code, signal })
+      }
     }
 
     onCrashCleanupPid(child.pid)
 
     const delayMs = Math.min(1000 * 2 ** (crashTimes.length - 1), RESTART_BACKOFF_MAX_MS)
-    log(isZh
+    logLine(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)
+
+    // macOS 信号死亡 → ReportCrash 异步生成 .ips 报告(实测崩溃后 ~5s 才落盘,
+    // 退避窗口等不到):崩溃后 8s 延迟扫描,找到就回填 crash.json 最新条目 +
+    // 落 supervisor.log。只写文件不写终端(此时新子进程 TUI 已接管屏幕);
+    // unref 不阻退出;只记路径不搬内容。
+    if (process.platform === 'darwin' && signal) {
+      const queuePathForAttach = announce && typeof announce.queuePath === 'string' ? announce.queuePath : null
+      const sessionForAttach = announce ? announce.sessionId : null
+      const scanTimer = setTimeout(() => {
+        const report = findDiagnosticReport(t, diagnosticReportsDir)
+        if (!report) return
+        logFileOnly(isZh ? `stem: 原生崩溃报告 ${report}` : `stem: native crash report ${report}`)
+        if (queuePathForAttach) attachDiagnosticReport(queuePathForAttach, sessionForAttach, report)
+      }, 8000)
+      scanTimer.unref?.()
+    }
   }
 }