@mortiseai/stem 0.0.23 → 0.0.25

package/README.md

@@ -530,7 +530,7 @@ Stem 的三种核心业务模式:
 | 项目级共享产物(plan 与 wiki 同级、不插作用域段) | `<存储根>/plans/` | `<存储根>/plans/` |
 | 用户 settings | `~/.mstem.json` | `~/.mstem/H/settings.json` |
 | 项目配置(settings/skills/plugins/agents/workflows/hooks/mcp/llms/memory) | `<cwd>/.mstem/platform/...` | `<cwd>/.mstem/H/...` |
-| debug 日志 | `<cwd>/logs/` | `<cwd>/logs/`(统一,不分目录;sessionId 唯一) |
+| debug 日志 | `<cwd>/logs/<YYYY-MM-DD>/<HH-MM-SS-sessionId>/` | 同左(统一按日期/会话归档;sessionId 唯一) |
 
 - **env 覆盖 × 租户**:目录形根只有两个 env(`STEM_STORAGE_DIR` 重定向存储根、
   `STEM_DIR` 重定向项目配置根;不再有逐 kind 的独立重定向)。即使显式
@@ -559,7 +559,8 @@ Stem 的三种核心业务模式:
   (`.mstem/<scope>/<kind>/`)。会话数据的口径是完整的:会话/洞察四目录、
   task 快照与 workflow 日志(`projects/`)、洞察报告与洞察记忆
   —— 用户会话的全部落盘都在自己空间内,Group 与其他用户不可见。
-  (debug 日志例外:统一落 `<cwd>/logs/`,按唯一 sessionId 区分文件。)
+  (debug 日志例外:统一落 `<cwd>/logs/<YYYY-MM-DD>/<HH-MM-SS-sessionId>/`,
+  按日期与唯一 sessionId 区分会话。)
 - plan 与 wiki 是项目级独立作用域，不属于会话用户数据：分别落
   `<存储根>/plans/`、`<存储根>/wiki/`，不插 platform/tenant/user 段。
 - 五类资源(workflows / skills / plugins / memory / agents)同样绝对隔离:
@@ -628,7 +629,7 @@ Stem 的三种核心业务模式:
 
 ### 运行时开关 · `.mstem/settings.local.json` 的 `env` 段
 
-CLI 的全部运行时开关统一放 settings 级联的 **`env` 段**(不再使用 `.env`):
+CLI 子进程的运行时开关统一放 settings 级联的 **`env` 段**(不再使用 `.env`):
 入口启动时把 `env` 对象逐 key 注入 `process.env`,**仅补缺不覆盖** — shell
 显式 `export` 的同名变量仍最优先(CI/测试钩子用,如 `STEM_LLMS_PATH` /
 `STEM_SETTINGS_PATH`)。
@@ -664,6 +665,7 @@ CLI 的全部运行时开关统一放 settings 级联的 **`env` 段**(不再使
 | `STEM_API_RETRY_INTERVAL_MS` | LLM 网络错误重试间隔(默认 60000,最多 10 次) |
 | `STEM_API_TIMEOUT_MS` | LLM 请求全局超时(平台未配 `timeoutMs` 时生效,默认 600000) |
 | `STEM_AUTO_COMPACT_TIMEOUT_MS` | 自动压缩摘要的独立硬截止(默认 60000);到时中止辅助摘要并继续主任务,不继承 LLM 的全局 10 分钟超时 |
+| `STEM_ADAPTIVE_TASK_CONTRACT_MODE` | 复杂/批量改动任务的自适应执行合同:`enforce`(默认,深度理解后硬门控并逐条绑定用户明确约束)、`observe`(同样规划但只审计不阻断)、`off`(关闭);未完成时回复独立的“继续/continue/resume”会恢复 scope、约束、步骤和原任务预算，版本化快照可随同一 workspace/session 的 `--resume` 恢复；磁盘恢复始终要求重新验收，若目标文件指纹漂移则退回深度理解并重提合同。合同验收命令失败时会在原回合提供有上限的自动修复机会并把推理升到 `xhigh`/`max`，成功重跑后自动清账，连续失败达到上限才允许收口为阻塞。运行中的 Bash 会对合同目标做前后指纹检查：发生修改即清除旧验收并要求干净重跑，后台启动的命令不会直接形成验收证据；验收还绑定 workspace 根目录、拒绝未写进 verifier 的隐藏 `cwd`/`env` 覆写，并只接受与 verifier 完整一致的 Bash 命令，需要子目录、环境变量或复合步骤时须原样写为 `cd path && ...` / `VAR=value ...`。Bash、PowerShell 与未声明只读的 MCP 工具还会经过有界 Git mutation manifest：既有脏文件在调用期间再次变化也可识别；发现合同范围外路径时不自动回滚或归因，而是冻结旧合同、升到 `max` 重新理解并要求带 `revisionReason` 重提合同。普通新请求会丢弃旧快照；旧开关 `STEM_ADAPTIVE_TASK_CONTRACT=0` 仍等价于 `off`。可运行 `bun run smoke:task-contract` 做无网络状态机检查 |
 | `STEM_PERMISSION_MODE` | 工具权限模式 `default\|allow\|plan\|bypassPermissions\|...` |
 | `STEM_MCP_CONNECT_TIMEOUT_MS` | MCP server 连接超时(默认 120000;首次 npx 拉包 + 浏览器冷启动可能很久) |
 | `STEM_MCP_CALL_TIMEOUT_MS` | MCP 单次工具调用超时(默认 120000;性能 trace 一类会很慢) |
@@ -677,6 +679,11 @@ CLI 的全部运行时开关统一放 settings 级联的 **`env` 段**(不再使
 | `STEM_TENANT` | **内部通道,勿手工设置** — 只由 `--tenant` flag 写入,env 段里的值会被入口忽略 |
 | `STEM_USER` | **内部通道,勿手工设置** — 只由 `--user` flag 写入,env 段里的值会被入口忽略 |
 
+> 启动器例外：`STEM_SUPERVISOR_OFF` 必须在 CLI 子进程读取
+> `settings.local.json` 之前生效，因此只从 shell 环境或 Stem 安装/源码根的
+> `.env` 读取。缺省或 `0` 开启 supervisor，`1` 关闭。`bun run dev`
+> 也经过 supervisor；直接执行 Bun 源码入口才会绕过。
+
 `STEM_STORAGE_DIR` / `STEM_DIR` 的取值支持两种形态:绝对路径、相对路径
 (相对当前工程路径 cwd 解析)——**不做 `~` home 展开**,`~/...` 不会被特殊
 处理,直接按相对路径拼接。会话聊天文件默认落
@@ -872,7 +879,7 @@ PATH: "uvx"`。常见修法:装上对应工具,或把 `command` 写成 `npx.cmd`
 
 ### 报障时请带上
 
-- `logs/<sessionId>/*.txt`(含 `[termProfile]`,一眼能看出终端画像)
+- `logs/<YYYY-MM-DD>/<HH-MM-SS-sessionId>/*.txt`(含 `[termProfile]`,一眼能看出终端画像)
 - 复现时加 `STEM_DEBUG_REPAINTS=1`,日志里会多出全屏重画的归因
 - 画面问题可加 `STEM_TTY_RECORD=<路径>`,把原始终端字节流录下来一并发回 —— 我们能在
   本地虚拟终端里按不同口径回放,把"猜"变成"量"

package/bin/stem-dev.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// 开发入口也必须经过 bin/stem.mjs，才能在 Bun 源码进程外保留 supervisor。
+process.env.STEM_DEV = '1'
+await import('./stem.mjs')

package/bin/stem-launcher-lib.mjs

@@ -0,0 +1,57 @@
+// 启动器纯判定逻辑。独立出来供 smoke 覆盖，避免 import bin/stem.mjs 时直接启动 CLI。
+
+import { existsSync } from 'node:fs'
+import { win32 } from 'node:path'
+
+export const SUPERVISOR_OFF_ENV = 'STEM_SUPERVISOR_OFF'
+
+/**
+ * Resolve Bun to a native executable that node:child_process can spawn directly.
+ *
+ * On Windows, a global `npm install -g bun` exposes bun.ps1/bun.cmd on PATH while
+ * the native executable lives under node_modules/bun/bin. PowerShell can invoke
+ * those shims, but spawn('bun') cannot, which otherwise surfaces as ENOENT.
+ */
+export function resolveBunCommand(options = {}) {
+  const {
+    env = process.env,
+    platform = process.platform,
+    fileExists = existsSync,
+  } = options
+  if (platform !== 'win32') return 'bun'
+
+  const candidates = []
+  const npmExecPath = String(env.npm_execpath ?? '').trim()
+  if (/^bun\.exe$/i.test(win32.basename(npmExecPath))) candidates.push(npmExecPath)
+
+  const pathValue = String(env.PATH ?? env.Path ?? '')
+  for (const rawDir of pathValue.split(win32.delimiter)) {
+    const dir = rawDir.trim().replace(/^"|"$/g, '')
+    if (!dir) continue
+    candidates.push(win32.join(dir, 'bun.exe'))
+    candidates.push(win32.join(dir, 'node_modules', 'bun', 'bin', 'bun.exe'))
+  }
+
+  const bunInstall = String(env.BUN_INSTALL ?? '').trim()
+  if (bunInstall) candidates.push(win32.join(bunInstall, 'bin', 'bun.exe'))
+  const userProfile = String(env.USERPROFILE ?? '').trim()
+  if (userProfile) candidates.push(win32.join(userProfile, '.bun', 'bin', 'bun.exe'))
+
+  return candidates.find(candidate => {
+    try { return fileExists(candidate) } catch { return false }
+  }) ?? 'bun'
+}
+
+/** 只有交互式 TUI 需要看护；显式关闭、子进程、无头模式均单次直跑。 */
+export function shouldSupervise(argv, options = {}) {
+  const {
+    env = process.env,
+    stdinIsTTY = process.stdin.isTTY,
+    stdoutIsTTY = process.stdout.isTTY,
+  } = options
+  if (env[SUPERVISOR_OFF_ENV] === '1') return false
+  if (env.STEM_SUPERVISED === '1') return false
+  if (!stdoutIsTTY || !stdinIsTTY) 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='))
+}

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') {