@mortiseai/stem 0.0.22 → 0.0.24

package/bin/stem-supervisor-lib.mjs

@@ -2,16 +2,38 @@
 // 独立成库的唯一理由:入口脚本 import 即执行,smoke 无法直接测;这里的函数
 // 全部纯逻辑/可注入,scripts/smoke-supervisor.ts 逐项锁语义。
 import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { homedir, tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { homedir } from 'node:os'
 import { spawn, spawnSync } from 'node:child_process'
 
 // 配置类错误的专用退出码(stem-entry-cli 侧同值):见 78 不重启。
 export const EXIT_CODE_CONFIG = 78
+// Child completed an in-process memory cleanup, persisted resumable state, and asks the
+// supervisor to replace the allocator/process without classifying the event as a crash.
+export const EXIT_CODE_MEMORY_RESTART = 75
 export const CRASH_WINDOW_MS = 60_000
 export const CRASH_GIVE_UP_COUNT = 3
 export const RESTART_BACKOFF_MAX_MS = 10_000
 
+const pad2 = n => String(n).padStart(2, '0')
+
+/** 与子进程默认日志布局一致：日期分桶，桶内按本地时分秒 + sessionId 排序。 */
+export function buildSessionLogDir(cwd, sessionId, startedAt = new Date()) {
+  const d = startedAt instanceof Date ? startedAt : new Date(startedAt)
+  const date = `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`
+  const time = `${pad2(d.getHours())}-${pad2(d.getMinutes())}-${pad2(d.getSeconds())}`
+  return join(cwd, 'logs', date, `${time}-${sessionId}`)
+}
+
+/** Supervisor 与子进程交换会话 ID 的短生命周期文件也统一落 Stem storage。 */
+function createSupervisorAnnounceFile(cwd) {
+  const configured = String(process.env.STEM_STORAGE_DIR ?? '').trim()
+  const storageRoot = configured ? resolve(cwd, configured) : join(cwd, 'mstem-storage')
+  const tmpRoot = join(storageRoot, 'tmp', 'supervisor')
+  mkdirSync(tmpRoot, { recursive: true })
+  return join(mkdtempSync(join(tmpRoot, 'session-')), 'session.json')
+}
+
 /** 从 argv 剥离 --resume/-r(supervisor 重启时按通告会话重挂)。 */
 export function stripResumeFlag(argv) {
   const out = []
@@ -68,15 +90,22 @@ export function restartPrompt(isZh, crashInfo) {
     : `[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']
+export function memoryRestartPrompt(isZh) {
+  return isZh
+    ? '[系统] 内存保护已完成清理并受控重启。本会话对话、todo 与任务现场已从磁盘恢复。请先核对当前 todo 和实际文件状态，然后从未完成项继续执行；不要重复已完成的工作，也不要只回复确认性文字。'
+    : '[system] Memory protection completed cleanup and a controlled restart. The conversation, todo, and task state were restored from disk. Verify the current todo and actual files, then continue from the unfinished work. Do not redo completed work or reply with an acknowledgement only.'
+}
 
-/** 注入续跑 prompt 到队列 sidecar(userPromptQueueStore 格式;resume 分支自动
- *  再水合、经 idle-gate 依次执行)。cleanExit: true 让 resume 端静默续跑而非弹
- *  y/n 确认 — 无人值守是看护的前提;连崩风暴由退避与 3 次放弃兜底。既有排队
- *  prompt 保留在后(按前缀去重防多次崩溃堆叠)。 */
-export function injectRestartPrompt(queuePath, isZh, crashInfo) {
-  const prompt = restartPrompt(isZh, crashInfo)
+// 注入队列的去重前缀:文案带崩溃原因(逐次可变),不能再按全串相等去重。
+const RESTART_PROMPT_PREFIXES = [
+  '[系统] 进程异常退出',
+  '[系统] 进程因异常',
+  '[系统] 内存保护已完成清理并受控重启',
+  '[system] The process',
+  '[system] Memory protection completed cleanup and a controlled restart',
+]
+
+function injectResumePrompt(queuePath, prompt) {
   let existing = []
   try {
     const parsed = JSON.parse(readFileSync(queuePath, 'utf8'))
@@ -95,8 +124,20 @@ export function injectRestartPrompt(queuePath, isZh, crashInfo) {
   } catch { return false }
 }
 
+/** 注入续跑 prompt 到队列 sidecar(userPromptQueueStore 格式;resume 分支自动
+ *  再水合、经 idle-gate 依次执行)。cleanExit: true 让 resume 端静默续跑而非弹
+ *  y/n 确认 — 无人值守是看护的前提;连崩风暴由退避与 3 次放弃兜底。既有排队
+ *  prompt 保留在后(按前缀去重防多次崩溃堆叠)。 */
+export function injectRestartPrompt(queuePath, isZh, crashInfo) {
+  return injectResumePrompt(queuePath, restartPrompt(isZh, crashInfo))
+}
+
+export function injectMemoryRestartPrompt(queuePath, isZh) {
+  return injectResumePrompt(queuePath, memoryRestartPrompt(isZh))
+}
+
 /** 崩溃标记(2026-08-13 事故:崩溃现场零证据,连退出信号都没记)。
- *  落 `logs/<sessionId>/crash.json`(2026-08-18 起与该会话的 supervisor.log /
+ *  落日期/时间会话目录的 crash.json(与该会话的 supervisor.log /
  *  debug 日志 / 堆快照同目录归档;此前散在 queue sidecar 目录难找易丢)。
  *  crashes 数组保最近 20 条,下次排查直接看这里而不用翻 supervisor stderr。
  *  写失败静默(标记是诊断增强,不能反过来阻断重启)。 */
@@ -162,8 +203,8 @@ export function stripModelFlag(argv) {
 }
 
 /** 崩溃堆快照清理:跨给定目录扫描 Heap.*.heapsnapshot,按 mtime 只保最新
- *  keep 份(快照 GB 级,防 24h 连跑占满磁盘)。2026-08-18 起快照按会话归档进
- *  logs/<sessionId>/,清理从"cwd 内只留 1 份"改为"cwd + logs/ + 各会话目录
+ *  keep 份(快照 GB 级,防 24h 连跑占满磁盘)。快照按会话归档进日期目录，
+ *  清理从"cwd 内只留 1 份"改为"cwd + logs/ + 各日期/会话目录
  *  全局保最新 3 份"— 老会话的取证快照不再被下一次崩溃立即冲掉。 */
 export function cleanupHeapSnapshots(dirs, keep = 3) {
   const found = []
@@ -182,43 +223,54 @@ export function cleanupHeapSnapshots(dirs, keep = 3) {
   }
 }
 
-/** 遗留平铺会话日志归位:分会话目录改造(2026-08-18)前,debug 日志平铺在
- *  logs/ 顶层(`<YYYY-MM-DD_HH-MM>_<sessionId>.txt`)。按文件名内嵌的会话 id
- *  搬进 logs/<sessionId>/ —— 会话目录必须是该会话日志全集(提 bug 只拷一个
- *  目录)。supervisor.log / 无关文件不动;搬失败(占用中)留待下次。 */
+/** 遗留平铺会话日志归位:旧 debug 日志平铺在 logs/ 顶层
+ *  (`<YYYY-MM-DD_HH-MM>_<sessionId>.txt`)。按文件名迁入
+ *  `logs/<YYYY-MM-DD>/<HH-MM-00-sessionId>/`，并改成新的时间前缀文件名。
+ *  supervisor.log / 无关文件不动;搬失败(占用中)留待下次。 */
 export function relocateLegacySessionLogs(logsDir) {
   let entries
   try { entries = readdirSync(logsDir, { withFileTypes: true }) } catch { return [] }
   const moved = []
   for (const e of entries) {
     if (!e.isFile()) continue
-    const m = /^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}_([A-Za-z0-9-]+)\.txt$/.exec(e.name)
+    const m = /^(\d{4}-\d{2}-\d{2})_(\d{2})-(\d{2})_([A-Za-z0-9-]+)\.txt$/.exec(e.name)
     if (!m) continue
     try {
-      const dest = join(logsDir, m[1])
+      const name = `${m[2]}-${m[3]}-00-${m[4]}`
+      const dest = join(logsDir, m[1], name)
       mkdirSync(dest, { recursive: true })
-      renameSync(join(logsDir, e.name), join(dest, e.name))
-      moved.push(join(dest, e.name))
+      const target = join(dest, `${name}.txt`)
+      renameSync(join(logsDir, e.name), target)
+      moved.push(target)
     } catch { /* 占用中/权限失败,下次启动再收 */ }
   }
   return moved
 }
 
 /** 堆快照可能出现的目录:cwd(V8 默认 / --diagnostic-dir 建目录失败回落)、
- *  logs/(--diagnostic-dir 落点)、logs/ 下各会话归档目录。 */
+ *  logs/(--diagnostic-dir 落点)、logs/ 下日期与会话归档目录。 */
 export function heapSnapshotDirs(cwd) {
   const logsDir = join(cwd, 'logs')
   const dirs = [cwd, logsDir]
-  try {
-    for (const e of readdirSync(logsDir, { withFileTypes: true })) {
-      if (e.isDirectory()) dirs.push(join(logsDir, e.name))
+  const pending = [logsDir]
+  // 只跟随真实目录，不跟符号链接；加上限避免异常目录树拖住启动。
+  while (pending.length > 0 && dirs.length < 10_000) {
+    const parent = pending.pop()
+    let entries
+    try { entries = readdirSync(parent, { withFileTypes: true }) } catch { continue }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue
+      const child = join(parent, e.name)
+      dirs.push(child)
+      pending.push(child)
+      if (dirs.length >= 10_000) break
     }
-  } catch { /* logs/ 不存在 */ }
+  }
   return dirs
 }
 
 /** 崩溃堆快照按会话归档:把散落在 fromDirs(cwd / logs/ 顶层)的
- *  Heap.*.heapsnapshot 搬进 logs/<sessionId>/,与该会话的 crash.json /
+ *  Heap.*.heapsnapshot 搬进日期/时间会话目录,与该会话的 crash.json /
  *  supervisor.log 放一起。搬失败(占用中/跨设备)留在原地由清理兜底。 */
 export function relocateHeapSnapshots(fromDirs, destDir) {
   const moved = []
@@ -295,13 +347,18 @@ export function attachDiagnosticReport(markerDir, reportPath) {
   } catch { return false }
 }
 
-function defaultSpawnChild(args, env) {
+function defaultSpawnChild(args, env, launch = {}) {
   // 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 })
+  const command = launch.command || process.execPath
+  const child = spawn(command, args, {
+    stdio: ['inherit', 'inherit', 'pipe'],
+    env,
+    cwd: launch.cwd,
+  })
   child.stderr?.on('data', chunk => {
     tail.push(chunk)
     try { process.stderr.write(chunk) } catch { /* 终端已关闭等,透传失败无害 */ }
@@ -319,14 +376,19 @@ function defaultSpawnChild(args, env) {
       child.on('exit', (code, signal) => {
         setTimeout(() => resolve({ code, signal }), 2000)
       })
-      child.on('error', () => resolve({ code: 1, signal: null }))
+      child.on('error', error => {
+        const message = `stem: failed to start child command ${command}: ${error.message}\n`
+        tail.push(message)
+        try { process.stderr.write(message) } catch { /* terminal already closed */ }
+        resolve({ code: EXIT_CODE_CONFIG, signal: null })
+      })
     }),
   }
 }
 
 /**
  * 看护主循环。overrides 供 smoke 注入:
- *   spawnChild(args, env) → {pid, exited: Promise<{code, signal}>}
+ *   spawnChild(args, env, {command, cwd}) → {pid, exited: Promise<{code, signal}>}
  *   sleep(ms) / log(text) / now() / cwd
  * 返回最终退出码。
  */
@@ -334,14 +396,17 @@ export async function runSupervisor(distEntry, argv, options = {}) {
   const {
     isZh = true,
     nodeFlags = [],
+    childCommand = process.execPath,
+    childPrefixArgs = null,
+    childCwd = undefined,
     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'),
+    announceFile = createSupervisorAnnounceFile(cwd),
     // supervisor 自身诊断的持久化落点(2026-08-17 事故:崩溃信息只写终端,滚屏即丢)。
-    // 缺省 null = 动态解析:会话已知 → logs/<sessionId>/supervisor.log,
+    // 缺省 null = 动态解析:会话已知 → 日期/时间会话目录/supervisor.log,
     // 未知(死在首次通告前且无 --resume)→ logs/supervisor.log 顶层兜底。
     // 显式传入(smoke 注入)则固定用该路径。
     supervisorLogPath = null,
@@ -357,14 +422,21 @@ export async function runSupervisor(distEntry, argv, options = {}) {
     },
     installSignalHandlers = true,
   } = options
+  const launchPrefixArgs = Array.isArray(childPrefixArgs)
+    ? [...childPrefixArgs]
+    : [...nodeFlags, distEntry]
+  const supervisorStartedAt = new Date(now())
 
   // log() 只写终端;logLine() 同时 append 到 supervisor.log(ISO 时间戳)—
   // 崩溃路径一律用 logLine,子进程日志闸门(STEM_DEBUG)关着时这里仍有据可查。
-  // 路径每次写时解析:resumeId 随通告更新,崩溃日志落到崩溃会话自己的目录。
+  // 路径每次写时解析:activeSessionLogDir 随子进程通告更新,崩溃日志落到
+  // 子进程 debug 日志所在的同一个日期/时间会话目录。
   const supervisorLogFile = () => {
     if (supervisorLogPath) return supervisorLogPath
-    return resumeId
-      ? join(cwd, 'logs', resumeId, 'supervisor.log')
+    return activeSessionLogDir
+      ? join(activeSessionLogDir, 'supervisor.log')
+      : resumeId
+        ? join(buildSessionLogDir(cwd, resumeId, supervisorStartedAt), 'supervisor.log')
       : join(cwd, 'logs', 'supervisor.log')
   }
   const logFileOnly = text => {
@@ -383,7 +455,9 @@ export async function runSupervisor(distEntry, argv, options = {}) {
   try { stemVersion = JSON.parse(readFileSync(join(dirname(distEntry), '..', 'package.json'), 'utf8')).version ?? null } catch { /* smoke 假路径等 */ }
 
   let { baseArgs, resumeId } = stripResumeFlag(argv)
+  let activeSessionLogDir = null
   let crashTimes = []
+  let memoryRestartTimes = []
   let childAlive = false
   // 崩溃前子进程通告的实时 permission mode(Shift+Tab 切换会更新通告)—
   // 重启时经 --permission-mode 复原,argv 中的启动值被剥离让位。
@@ -406,7 +480,13 @@ export async function runSupervisor(distEntry, argv, options = {}) {
       const p = JSON.parse(readFileSync(announceFile, 'utf8'))
       if (p && p.v === 1 && typeof p.sessionId === 'string') parsed = p
     } catch { return }
-    if (!parsed || parsed.sessionId === announcedSid) return
+    if (!parsed) return
+    // logDir 由子进程计算，包含精确到秒的会话起点；旧版通告没有该字段时
+    // 才由 supervisor 以自身启动时间构造兼容落点。
+    activeSessionLogDir = typeof parsed.logDir === 'string' && parsed.logDir
+      ? resolve(cwd, parsed.logDir)
+      : buildSessionLogDir(cwd, parsed.sessionId, supervisorStartedAt)
+    if (parsed.sessionId === announcedSid) return
     announcedSid = parsed.sessionId
     resumeId = parsed.sessionId
     logFileOnly(isZh
@@ -429,7 +509,7 @@ export async function runSupervisor(distEntry, argv, options = {}) {
     cleanupHeapSnapshots(heapSnapshotDirs(cwd))
     let effectiveBase = permissionModeFromAnnounce ? stripPermissionModeFlag(baseArgs) : baseArgs
     if (modelFromAnnounce !== null) effectiveBase = stripModelFlag(effectiveBase)
-    const args = [...nodeFlags, distEntry, ...effectiveBase]
+    const args = [...launchPrefixArgs, ...effectiveBase]
     if (permissionModeFromAnnounce) args.push('--permission-mode', permissionModeFromAnnounce)
     if (modelFromAnnounce) args.push('--model', modelFromAnnounce)
     if (resumeId) args.push('--resume', resumeId)
@@ -437,7 +517,7 @@ export async function runSupervisor(distEntry, argv, options = {}) {
       ...process.env,
       STEM_SUPERVISED: '1',
       STEM_SESSION_ANNOUNCE_FILE: announceFile,
-    })
+    }, { command: childCommand, cwd: childCwd })
     childAlive = true
     currentPid = child.pid ?? null
     const lifecycleTimer = setInterval(checkAnnounceForLifecycle, 2000)
@@ -458,9 +538,50 @@ export async function runSupervisor(distEntry, argv, options = {}) {
         : 'stem: exited with a configuration error (code 78); supervisor will not restart. Fix the configuration and run again.')
       return EXIT_CODE_CONFIG
     }
+    if (code === EXIT_CODE_MEMORY_RESTART) {
+      const t = now()
+      memoryRestartTimes = memoryRestartTimes.filter(x => t - x < CRASH_WINDOW_MS)
+      memoryRestartTimes.push(t)
+      resetTerminalFn()
+      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 || typeof announce.queuePath !== 'string') {
+        logLine(isZh
+          ? 'stem: 子进程请求内存恢复重启，但没有有效会话通告；为避免丢失上下文，已停止自动重启。'
+          : 'stem: child requested a memory recovery restart without a valid session announcement; automatic restart stopped to avoid losing context.')
+        return EXIT_CODE_MEMORY_RESTART
+      }
+      resumeId = announce.sessionId
+      if (typeof announce.permissionMode === 'string' && announce.permissionMode) {
+        permissionModeFromAnnounce = announce.permissionMode
+      }
+      if (typeof announce.model === 'string') modelFromAnnounce = announce.model
+      for (const p of Array.isArray(announce.jsonlPaths) ? announce.jsonlPaths : []) {
+        if (typeof p === 'string' && existsSync(p) && repairJsonlTail(p)) {
+          logLine(isZh ? `stem: 已修补会话记录 ${p}` : `stem: repaired session log ${p}`)
+          break
+        }
+      }
+      if (memoryRestartTimes.length >= CRASH_GIVE_UP_COUNT) {
+        logLine(isZh
+          ? `stem: 60 秒内连续请求内存恢复重启 ${memoryRestartTimes.length} 次，停止自动重启。`
+          : `stem: memory recovery restart requested ${memoryRestartTimes.length} times within 60s; giving up on auto-restart.`)
+        return EXIT_CODE_MEMORY_RESTART
+      }
+      injectMemoryRestartPrompt(announce.queuePath, isZh)
+      onCrashCleanupPid(child.pid)
+      logLine(isZh
+        ? `stem: 内存清理后仍处于硬水位，已保存会话 ${resumeId}，正在受控重启并自动续接…`
+        : `stem: memory remained above the hard limit after cleanup; session ${resumeId} was saved and will resume after a controlled restart…`)
+      await sleep(250)
+      continue
+    }
 
     // 崩溃路径。先读会话通告拿会话身份 — 所有崩溃落盘(supervisor.log /
-    // crash.json / 堆快照)都按 logs/<sessionId>/ 分目录归档,身份必须先到手;
+    // crash.json / 堆快照)都按日期/时间会话目录归档,身份必须先到手;
     // 子进程死在通告前 → 沿用现有 resumeId(可能为 null → 落 logs/ 顶层兜底)。
     const t = now()
     crashTimes = crashTimes.filter(x => t - x < CRASH_WINDOW_MS)
@@ -481,7 +602,9 @@ export async function runSupervisor(distEntry, argv, options = {}) {
       if (typeof announce.model === 'string') modelFromAnnounce = announce.model
     }
     // 本次崩溃的会话归档目录(crash.json / 堆快照 / supervisor.log 共用)。
-    const sessionDir = resumeId ? join(cwd, 'logs', resumeId) : null
+    const sessionDir = resumeId
+      ? (activeSessionLogDir ?? buildSessionLogDir(cwd, resumeId, new Date(t)))
+      : null
     // 堆快照按会话归档:V8 落在 --diagnostic-dir(logs/)或 cwd(旧默认 /
     // 建目录失败回落),搬进崩溃会话自己的目录,免得被后续清理当无主快照收走。
     if (sessionDir) relocateHeapSnapshots([cwd, join(cwd, 'logs')], sessionDir)
@@ -514,6 +637,7 @@ export async function runSupervisor(distEntry, argv, options = {}) {
       }
       writeCrashMarker(sessionDir, announce.sessionId, { code, signal }, t, {
         stderrTail: stderrTail8k,
+        command: childCommand,
         args,
         nodeVersion: process.version,
         stemVersion,
@@ -540,8 +664,8 @@ export async function runSupervisor(distEntry, argv, options = {}) {
 
     const delayMs = Math.min(1000 * 2 ** (crashTimes.length - 1), RESTART_BACKOFF_MAX_MS)
     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)`)
+      ? `stem: 进程异常退出(code=${code ?? '-'}, signal=${signal ?? '-'}),${Math.round(delayMs / 1000)}s 后自动恢复会话${resumeId ? ` ${resumeId}` : ''}…(STEM_SUPERVISOR_OFF=1 可关闭看护)`
+      : `stem: process crashed (code=${code ?? '-'}, signal=${signal ?? '-'}); resuming session${resumeId ? ` ${resumeId}` : ''} in ${Math.round(delayMs / 1000)}s… (set STEM_SUPERVISOR_OFF=1 to disable)`)
     await sleep(delayMs)
 
     // macOS 信号死亡 → ReportCrash 异步生成 .ips 报告(实测崩溃后 ~5s 才落盘,

package/bin/stem.mjs

@@ -6,14 +6,16 @@
 // (OOM FATAL ERROR 在进程内不可拦截:同步分配风暴会锁死事件循环,任何 JS 层
 // 守护都没有执行机会)时自动:修补会话 JSONL 尾部(崩溃可能截断半行,不修则
 // --resume 直接拒载)→ 注入自包含续跑 prompt 到队列 sidecar → --resume 同一
-// 会话重启。正常退出(exit 0)与配置错误(exit 78)不重启;60 秒内连崩 3 次
-// 放弃。STEM_NO_SUPERVISOR=1 退回单次直跑;实现与语义锁定见
+// 会话重启。内存清理后 RSS 仍在硬档时以 exit 75 请求受控续接重启；正常退出
+// (exit 0)与配置错误(exit 78)不重启。60 秒内连崩/连续内存重启 3 次放弃。
+// STEM_SUPERVISOR_OFF=1 退回单次直跑;实现与语义锁定见
 // bin/stem-supervisor-lib.mjs 与 scripts/smoke-supervisor.ts。
 import { existsSync, mkdirSync, realpathSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { devNull, totalmem } from 'node:os'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { spawnSync } from 'node:child_process'
+import { resolveBunCommand, shouldSupervise } from './stem-launcher-lib.mjs'
 
 // realpath:npm link / 全局 bin 软链下定位真实包根,而非软链父目录。
 const selfPath = realpathSync(fileURLToPath(import.meta.url))
@@ -57,11 +59,13 @@ function heapLimitMB() {
 
 /** 子进程 node flags:heap 上限(未显式配置时)+ OOM 前堆快照(可关)。 */
 function childNodeFlags() {
-  const flags = []
+  // Memory recovery performs an explicit collection after releasing transcript/render caches,
+  // then re-samples RSS before deciding whether a process replacement is necessary.
+  const flags = ['--expose-gc']
   if (!heapConfigured()) flags.push(`--max-old-space-size=${heapLimitMB()}`)
   // OOM 前自动堆快照:定位"未知同步分配风暴"元凶的唯一现实手段(手动
   // /heapdump 在同步爆发下来不及)。代价是崩溃时写数 GB 快照;supervisor
-  // 崩溃后按会话归档进 logs/<sessionId>/,每轮 spawn 前跨目录清理保最新
+  // 崩溃后按会话归档进 logs/<日期>/<时分秒-sessionId>/,每轮 spawn 前跨目录清理保最新
   // 3 份。STEM_HEAP_SNAPSHOT=0 关闭。
   if (
     process.env.STEM_HEAP_SNAPSHOT !== '0' &&
@@ -69,7 +73,7 @@ function childNodeFlags() {
   ) {
     flags.push('--heapsnapshot-near-heap-limit=1')
     // 快照定向到 <cwd>/logs/(V8 默认写 cwd,散落且被误当项目文件);supervisor
-    // 崩溃后再按会话归档进 logs/<sessionId>/。注意 --diagnostic-dir 指向的目录
+    // 崩溃后再按会话归档进日期/时间会话目录。注意 --diagnostic-dir 指向的目录
     // 必须已存在 —— 实测(node 25)目录缺失时 V8 写快照直接原生断言崩溃,
     // 所以先建目录,建失败就不加 flag 回落 cwd 默认。
     if (!(process.env.NODE_OPTIONS ?? '').includes('--diagnostic-dir')) {
@@ -83,18 +87,9 @@ function childNodeFlags() {
   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')
+const argv = process.argv.slice(2)
 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() }))
@@ -103,25 +98,37 @@ if (process.env.STEM_DEV !== '1' && existsSync(distEntry)) {
     // 子任务场景会 OOM。V8 堆参数只能在进程启动时生效;用户已显式配置时同进程直跑。
     await import(pathToFileURL(distEntry).href)
   } else {
-    // 非看护场景(fast-echo / SDK 桥 / STEM_NO_SUPERVISOR)单次 re-exec,
+    // 非看护场景(fast-echo / SDK 桥 / STEM_SUPERVISOR_OFF)单次 re-exec,
     // 把 --max-old-space-size 带给真正的 CLI 进程。
     const result = spawnSync(
       process.execPath,
-      [`--max-old-space-size=${heapLimitMB()}`, distEntry, ...argv],
+      ['--expose-gc', `--max-old-space-size=${heapLimitMB()}`, distEntry, ...argv],
       { stdio: 'inherit' },
     )
     process.exit(result.status ?? 1)
   }
 } else {
-  // dev 模式:bun 直跑源码。bun 会自动加载 cwd 下的 .env,跳过时显式指向空设备。
+  // dev 模式:父启动器仍留在 Node 中看护，子进程才由 Bun 直跑源码。
+  // Bun 会自动加载 cwd 下的 .env,跳过时显式指向空设备。
   const envFlag = skipDotenv
     ? [`--env-file=${devNull}`]
     : existsSync(envFile)
       ? ['--env-file=.env']
       : []
+  const devPrefixArgs = [...envFlag, './src/stem-entry/stem-entry-cli.tsx']
+  const bunCommand = resolveBunCommand()
+  if (shouldSupervise(argv)) {
+    const { runSupervisor } = await import(pathToFileURL(join(rootDir, 'bin', 'stem-supervisor-lib.mjs')).href)
+    process.exit(await runSupervisor(distEntry, argv, {
+      isZh,
+      childCommand: bunCommand,
+      childPrefixArgs: devPrefixArgs,
+      childCwd: rootDir,
+    }))
+  }
   const result = spawnSync(
-    'bun',
-    [...envFlag, './src/stem-entry/stem-entry-cli.tsx', ...process.argv.slice(2)],
+    bunCommand,
+    [...devPrefixArgs, ...argv],
     { cwd: rootDir, stdio: 'inherit' },
   )
   if (result.error && result.error.code === 'ENOENT') {