@danceiny/gotry 0.0.1-rc.8 → 0.2.0-rc.27

package/ts/capabilities/hbcli.ts

@@ -12,10 +12,12 @@
  * 估算必须显式标记。这是 L4 与 L1 透明卡片的接缝。
  */
 
-import { spawn } from 'node:child_process'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { spawnBounded } from './spawn-bounded.ts'
 
 export interface HbcliCallOptions {
-  /** hbcli 二进制路径(默认 'hbcli',依赖 PATH) */
+  /** hbcli 二进制路径(默认 'hbcli',依赖 PATH;~/.local/bin 等已知安装位自动回退) */
   hbcliBin?: string
   /** 超时(ms) */
   timeoutMs?: number
@@ -23,6 +25,8 @@ export interface HbcliCallOptions {
   token?: string
   /** 环境(uat/prod/dev);默认 uat */
   env?: 'uat' | 'prod' | 'dev'
+  /** 宿主取消信号(exec.signal);abort → SIGTERM,500ms 后 SIGKILL 有界回收 */
+  signal?: AbortSignal
 }
 
 export interface HbcliCallResult {
@@ -43,76 +47,121 @@ export interface HbcliCallResult {
   error?: string
 }
 
+/**
+ * hbcli 二进制候选路径(gotry setup 按官方脚本装到 ~/.local/bin/hbcli,
+ * symlink 指向 ~/.staicli/current/hbcli——当 PATH 不含 ~/.local/bin 时裸名
+ * spawn 仍 ENOENT,按已知安装位回退)。仅对默认名 'hbcli' 扩展;显式自定义
+ * 名(如测试注入的不存在路径)不扩展,保持配置即所用的可测性。
+ */
+export function hbcliBinCandidates(bin: string, homeDir: string = homedir()): string[] {
+  if (bin !== 'hbcli') return [bin]
+  return [bin, join(homeDir, '.local/bin/hbcli'), join(homeDir, '.staicli/current/hbcli')]
+}
+
+/** 单个候选的一次 spawn 封装:失败不抛,返回降级结果(spawnError 标记 ENOENT 类失败供上层换候选) */
+async function attemptHbcli(
+  bin: string,
+  args: string[],
+  opts: Required<Pick<HbcliCallOptions, 'timeoutMs' | 'env'>> & { envVars: Record<string, string>; signal?: AbortSignal },
+): Promise<HbcliCallResult & { spawnError?: boolean }> {
+  const started = Date.now()
+  const r = await spawnBounded(bin, args, {
+    env: { ...process.env, ...opts.envVars },
+    timeoutMs: opts.timeoutMs,
+    signal: opts.signal,
+  })
+  const latencyMs = Date.now() - started
+  const ts = new Date().toISOString()
+  const cleanupError = r.groupReaped === false ? 'process group cleanup incomplete' : undefined
+  if (r.aborted) {
+    return {
+      via: 'hbcli-error', exitCode: r.code ?? -1, result: null,
+      evidence: `[实时API:hbcli@abort@${ts}]`,
+      stderr: r.stderr.slice(0, 2000), latencyMs,
+      error: ['aborted by host signal', cleanupError].filter(Boolean).join('; '),
+    }
+  }
+  if (r.error || r.groupReaped === false || r.code !== 0) {
+    const error = [r.error, r.stderr.trim().slice(0, 200), cleanupError].filter(Boolean).join('; ')
+    const failureKind = r.timedOut ? 'timeout' : /ENOENT/.test(r.error ?? '') ? 'spawn_error' : 'error'
+    return {
+      via: 'hbcli-error', exitCode: r.code ?? -1, result: null,
+      evidence: `[实时API:hbcli@${failureKind}@${ts}]`,
+      stderr: r.stderr.slice(0, 2000),
+      latencyMs, error: error || `exit ${r.code}`,
+      spawnError: /ENOENT/.test(r.error ?? ''),
+    }
+  }
+  // 尝试 JSON 解析
+  const jStart = r.stdout.search(/[\{\[]/)
+  const jsonStr = jStart >= 0 ? r.stdout.slice(jStart) : ''
+  let result: unknown = null
+  if (jsonStr) {
+    try { result = JSON.parse(jsonStr) } catch { /* 非 JSON 输出,留给调用方处理 */ }
+  }
+  return {
+    via: 'hbcli-realtime', exitCode: 0, result,
+    evidence: `[实时API:hbcli@${ts}]`,
+    stdout: r.stdout.slice(0, 2000), latencyMs,
+  }
+}
+
 /** 通用 hbcli JSON 调用封装:失败不抛,而是返回降级结果 */
 export async function callHbcliJson(
   args: string[],
   opts: HbcliCallOptions = {},
 ): Promise<HbcliCallResult> {
-  const started = Date.now()
-  const bin = opts.hbcliBin ?? 'hbcli'
-  const timeoutMs = opts.timeoutMs ?? 15_000
   const env = opts.env ?? 'uat'
   const envVars: Record<string, string> = { HOTELBYTE_ENV: env }
   if (opts.token) envVars['HOTELBYTE_TOKEN'] = opts.token
+  const callOpts = { timeoutMs: opts.timeoutMs ?? 15_000, env, envVars, signal: opts.signal }
+  const candidates = hbcliBinCandidates(opts.hbcliBin ?? 'hbcli')
+  // abort 状态不可触发 fallback 候选;spawn 前的 pre-aborted 调用整体零 spawn
+  if (opts.signal?.aborted) {
+    return attemptHbcli(candidates[0]!, args, callOpts)
+  }
+  let last: HbcliCallResult & { spawnError?: boolean } | undefined
+  for (const bin of candidates) {
+    last = await attemptHbcli(bin, args, callOpts)
+    // spawn 级失败(ENOENT 等)且还有候选 → 换下一个已知安装位;其余失败(退码/超时/abort)无重试意义
+    if (!(last.spawnError && candidates.indexOf(bin) < candidates.length - 1)) return last
+  }
+  return last!
+}
 
-  return new Promise((resolve) => {
-    let stdout = ''
-    let stderr = ''
-    let settled = false
-    const child = spawn(bin, args, { env: { ...process.env, ...envVars } })
-    const timer = setTimeout(() => {
-      if (!settled) {
-        settled = true
-        child.kill('SIGKILL')
-        resolve({
-          via: 'hbcli-error', exitCode: -1, result: null,
-          evidence: `[实时API:hbcli@timeout@${new Date().toISOString()}]`,
-          latencyMs: Date.now() - started, error: `timeout after ${timeoutMs}ms`,
-        })
-      }
-    }, timeoutMs)
-    child.stdout.on('data', (d: Buffer) => { stdout += d.toString() })
-    child.stderr.on('data', (d: Buffer) => { stderr += d.toString() })
-    child.on('close', (code) => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      const latencyMs = Date.now() - started
-      if (code !== 0) {
-        // 不抛错,降级返回。证据链显式标注:实时 API 调用失败+原因+时间戳。
-        resolve({
-          via: 'hbcli-error', exitCode: code ?? -1, result: null,
-          evidence: `[实时API:hbcli@error@${new Date().toISOString()}]`,
-          stderr: stderr.slice(0, 2000),
-          latencyMs, error: stderr.trim().slice(0, 200) || `exit ${code}`,
-        })
-        return
-      }
-      // 尝试 JSON 解析
-      const jStart = stdout.search(/[\{\[]/)
-      const jsonStr = jStart >= 0 ? stdout.slice(jStart) : ''
-      let result: unknown = null
-      if (jsonStr) {
-        try { result = JSON.parse(jsonStr) } catch { /* 非 JSON 输出,留给调用方处理 */ }
-      }
-      resolve({
-        via: 'hbcli-realtime', exitCode: 0, result,
-        evidence: `[实时API:hbcli@${new Date().toISOString()}]`,
-        stdout: stdout.slice(0, 2000), latencyMs,
-      })
-    })
-    child.on('error', (e) => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      // ENOENT (二进制不存在) 等也走降级路径
-      resolve({
-        via: 'hbcli-error', exitCode: -1, result: null,
-        evidence: `[实时API:hbcli@spawn_error@${new Date().toISOString()}]`,
-        latencyMs: Date.now() - started, error: (e as Error).message,
-      })
-    })
-  })
+/** 上游 i18n 名称容错读取(zh 优先,中文优先产品口径;回退 en/ar) */
+function i18nName(v: { zh?: string; en?: string; ar?: string } | string | undefined): string {
+  if (!v) return ''
+  if (typeof v === 'string') return v
+  return v.zh || v.en || v.ar || ''
+}
+
+/**
+ * 实时 hotelList 响应 → 模型可读紧凑行(id/名称/星级/最低价)。
+ * issue #195:render 面只透 summary,若 summary 不含数据,模型只看到
+ * 「实时返回」四个字——工具调用等于白调。id 必须在行内,hotel-rates 的入参
+ * 就来自这里。上游 wire:HotelListResp{list:[Hotel{id,name:{en,zh},star,minPrice:{amount,currency}}]}。
+ */
+function hotelLines(result: unknown, max = 8): string {
+  const list = (result as { list?: unknown } | null)?.list
+  if (!Array.isArray(list) || list.length === 0) return ''
+  const lines: string[] = []
+  for (const item of list.slice(0, max)) {
+    const h = item as {
+      id?: string | number
+      name?: { zh?: string; en?: string; ar?: string }
+      star?: number
+      minPrice?: { amount?: number; currency?: string }
+    }
+    const name = i18nName(h.name) || `hotel ${h.id ?? '?'}`
+    const star = typeof h.star === 'number' && h.star > 0 ? ` ${h.star}★` : ''
+    const price = h.minPrice && typeof h.minPrice.amount === 'number'
+      ? ` 低至 ${h.minPrice.amount}${h.minPrice.currency ? ` ${h.minPrice.currency}` : ''}`
+      : ''
+    lines.push(`- id=${h.id ?? '?'} ${name}${star}${price}`)
+  }
+  if (list.length > max) lines.push(`…(共 ${list.length} 家,仅列前 ${max})`)
+  return lines.join('\n')
 }
 
 /** 高层语义化封装:酒店列表查询(down-tier to 静态包 + 证据链标注) */
@@ -120,29 +169,70 @@ export async function searchHotels(
   query: { destination: string; checkIn?: string; checkOut?: string; adults?: number },
   opts: HbcliCallOptions & { fallbackPath?: string } = {},
 ): Promise<HbcliCallResult & { hotels?: unknown; summary: string }> {
-  // 旗标对齐上游 CLI v0.3.0(命令树扁平化后):--destination-name + --room-occupancies;
-  // hotel-list 无日期旗标(房价按上游当前窗口),checkIn/checkOut 留给 hotel-rates 跟进
+  // 旗标对齐上游 CLI(hotelbyte-com/hotelbyte-cli):--destination-name + --room-occupancies;
+  // hotel-list 支持日期旗标(--check-in/--check-out,上游帮助文档在册)——issue #195 教训:
+  // 「日期不传上游」会让实时价退化为当前窗口价,用户要下周五的房给的是今天的价。
   const hbArgs = ['search', 'hotel-list', '--json', '--page-size', '10']
   if (query.destination) hbArgs.push('--destination-name', query.destination)
+  if (query.checkIn) hbArgs.push('--check-in', query.checkIn)
+  if (query.checkOut) hbArgs.push('--check-out', query.checkOut)
   if (query.adults) hbArgs.push('--room-occupancies', JSON.stringify([{ adultCount: query.adults, childrenAges: [] }]))
   const live = await callHbcliJson(hbArgs, opts)
+  // 取消立即结束:不读静态包、不产出命中/无结果/估算,也不计上游故障
+  if (opts.signal?.aborted || /abort/i.test(live.error ?? '')) {
+    const ts = new Date().toISOString()
+    const cleanupError = /cleanup incomplete/i.test(live.error ?? '') ? `; ${live.error}` : ''
+    return {
+      via: 'hbcli-error', exitCode: live.exitCode, result: null,
+      evidence: `[实时API:hbcli@abort@${ts}]`,
+      latencyMs: live.latencyMs, error: `aborted by host signal${cleanupError}`, summary: `酒店「${query.destination}」检索已取消,未产生事实`,
+    }
+  }
   if (live.via === 'hbcli-realtime') {
-    return { ...live, hotels: live.result, summary: `${query.destination}:hbcli 实时返回${query.checkIn || query.checkOut ? '(日期不传上游 list,以当前窗口房价返回)' : ''}` }
+    // summary 即模型面(render 只透 summary):必须自带紧凑数据行 + 证据链,
+    // 否则模型只看到「实时返回」占位一句话(issue #195 实锤)。
+    const list = (live.result as { list?: unknown[] } | null)?.list
+    const n = Array.isArray(list) ? list.length : 0
+    const dateTag = query.checkIn
+      ? `入住 ${query.checkIn}${query.checkOut ? ` → 退房 ${query.checkOut}` : ''}`
+      : '未传日期(上游按当前窗口价)'
+    const lines = hotelLines(live.result)
+    const summary = `${query.destination}:hbcli 实时 ${n} 家(${dateTag})${lines ? `\n${lines}` : ''}\n${live.evidence}`
+    return { ...live, hotels: live.result, summary }
   }
-  // 降级:读静态包
+  // 降级原因人话化(issue #24):hbcli 未安装时按 gotry setup 指引(npm 安装期已
+  // 自动跑过官方脚本;PATH 未含 ~/.local/bin 时上方候选路径也已兜住),
+  // 裸 "spawn hbcli ENOENT" 读起来像工具坏了——实际静态包降级是设计行为
+  const rawReason = live.error ?? live.via
+  const reason = /ENOENT/i.test(rawReason) ? '未安装 hbcli(可选实时源;npx @danceiny/gotry setup 可按官方脚本安装)' : rawReason
+  // 降级:读静态包,按目的地过滤命中的住宿块(issue #24)——整包倾倒会把无关场景
+  // (深圳/普吉/曼谷/云南/大理混装)灌给模型且不指明哪块相关;包内无该目的地时明示
+  // 「无数据」而不是伪装成可用结果。
   const fallback = opts.fallbackPath
   if (fallback) {
     try {
       const { readFile } = await import('node:fs/promises')
-      const pack = JSON.parse(await readFile(fallback, 'utf-8')) as Record<string, unknown>
+      const pack = JSON.parse(await readFile(fallback, 'utf-8')) as { stays?: unknown[] } & Record<string, unknown>
+      const kw = query.destination.trim()
+      const stays = Array.isArray(pack.stays) ? pack.stays : []
+      const matched = kw ? stays.filter(s => JSON.stringify(s).includes(kw)) : stays
+      if (matched.length) {
+        return {
+          ...live,
+          hotels: { stays: matched },
+          // summary 即模型面:静态块内容(note/options/recommendation)直接内联,
+          // 模型不必再猜「命中 N 块」里有什么(issue #195)
+          summary: `${query.destination}:hbcli 实时源不可用(${reason}),已降级到静态包(公开渠道估算,非实时),命中 ${matched.length} 个住宿块:\n${JSON.stringify(matched).slice(0, 1600)}`,
+        }
+      }
       return {
         ...live,
-        hotels: pack,
-        summary: `${query.destination}:hbcli 不可用(${live.error ?? live.via}),降级到静态包`,
+        hotels: null,
+        summary: `${query.destination}:hbcli 实时源不可用(${reason}),且静态包无「${query.destination}」住宿数据(静态包仅覆盖内置场景)`,
       }
     } catch { /* 静态包读不到也优雅降级 */ }
   }
-  return { ...live, summary: `${query.destination}:hbcli 不可用且无静态包(仅返回错误)` }
+  return { ...live, summary: `${query.destination}:hbcli 实时源不可用(${reason})且无静态包(仅返回错误)` }
 }
 
 /** 高层语义化封装:目的地列表(无数据依赖,通常 hbcli dest 命令可独立调通) */
@@ -150,3 +240,95 @@ export async function listDestinations(opts: HbcliCallOptions = {}): Promise<Hbc
   const r = await callHbcliJson(['search', 'destinations', '--json'], opts)
   return { ...r, destinations: r.result }
 }
+
+/**
+ * 高层语义化封装:房型报价(hotel-rates;上游 hotelRates 创建后端 session,
+ * 产出带 RatePkgId 的房型列表——check-avail 与 book 的入参来源)。
+ *
+ * 价格面无静态降级(fail-closed):hotel-list 的静态包降级是定性住宿信息,
+ * 房价是钱——估算价格冒充实时价是红线;不可用就诚实失败,证据链标注,
+ * 与 bookable-facts 证据分级(live_inventory 才可进确认卡)同口径。
+ */
+export async function hotelRates(
+  query: {
+    hotelId: string
+    checkIn?: string
+    checkOut?: string
+    adults?: number
+    countryCode?: string
+    nationalityCode?: string
+    residencyCode?: string
+  },
+  opts: HbcliCallOptions = {},
+): Promise<HbcliCallResult & { rates?: unknown; summary: string }> {
+  const hbArgs = ['search', 'hotel-rates', '--json', '--hotel-id', query.hotelId]
+  if (query.checkIn) hbArgs.push('--check-in', query.checkIn)
+  if (query.checkOut) hbArgs.push('--check-out', query.checkOut)
+  if (query.countryCode) hbArgs.push('--country-code', query.countryCode)
+  if (query.nationalityCode) hbArgs.push('--nationality-code', query.nationalityCode)
+  if (query.residencyCode) hbArgs.push('--residency-code', query.residencyCode)
+  if (query.adults) hbArgs.push('--room-occupancies', JSON.stringify([{ adultCount: query.adults, childrenAges: [] }]))
+  const live = await callHbcliJson(hbArgs, opts)
+  const summary = live.via === 'hbcli-realtime'
+    ? `hotel ${query.hotelId}:hbcli 实时报价${query.checkIn ? `(${query.checkIn} → ${query.checkOut ?? '?'})` : ''}`
+    : `hotel ${query.hotelId}:hbcli 实时报价不可用(${live.error ?? live.via});价格面无静态降级,fail-closed 不估算`
+  return { ...live, rates: live.result, summary }
+}
+
+/** 高层语义化封装:下单前实时验价(check-avail;入参 RatePkgId 来自 hotel-rates 产物)。价格面同上:不可用即诚实失败。 */
+export async function checkAvail(
+  query: { ratePkgId: string },
+  opts: HbcliCallOptions = {},
+): Promise<HbcliCallResult & { avail?: unknown; summary: string }> {
+  const live = await callHbcliJson(['search', 'check-avail', '--json', '--rate-pkg-id', query.ratePkgId], opts)
+  const summary = live.via === 'hbcli-realtime'
+    ? `ratePkg ${query.ratePkgId}:hbcli 实时验价(库存与价格以后端为准)`
+    : `ratePkg ${query.ratePkgId}:hbcli 实时验价不可用(${live.error ?? live.via});价格面无静态降级,fail-closed`
+  return { ...live, avail: live.result, summary }
+}
+
+/**
+ * C 端客户邮箱验证码登录(hotelbyte-cli auth customer-* 两步流;后端
+ * loginByCustomerEmailCode:验证通过即登录,新邮箱即注册,无需密码):
+ *   step 1 customerSendCode —— 邮箱收码(外发邮件动作,仅用户明示要登录/注册时调用);
+ *   step 2 customerLogin —— 用户从收件箱报码,验证即建档/登录。
+ *
+ * 与检索族的本质差异:customerLogin 写 hbcli 共享凭据仓(customer 档,
+ * ~/.staicli/credentials.json)——hbcli 侧 customer 档是最低优先级凭据(无
+ * portal/API-key 凭据时才生效),登录不劫持既有凭据。本层不透出 token 值
+ * (CLI 只回 token_saved,凭据留在 CLI 仓内,不进 gotry 会话/日志)。
+ * auth 命令族要求 hbcli 带 register 支持(npm 0.0.4 起;0.0.3 报 unknown
+ * command,经 hbcli-error 面优雅失败)。
+ */
+export async function customerSendCode(
+  email: string,
+  opts: HbcliCallOptions = {},
+): Promise<HbcliCallResult & { summary: string }> {
+  const live = await callHbcliJson(['--json', 'auth', 'customer-send-code', '--email', email], opts)
+  const r = live.result as { expiresIn?: number; nextTime?: string } | null
+  const summary = live.via === 'hbcli-realtime'
+    ? `验证码已发送到 ${email}${r?.expiresIn ? `(有效期 ${r.expiresIn} 秒)` : ''}——请让用户从邮箱查收并报码,再走 gotry_hotel_auth_login`
+    : `验证码发送失败(${live.error ?? live.via});服务端有发码限流,勿立即重试`
+  return { ...live, summary }
+}
+
+export async function customerLogin(
+  query: { email: string; code: string; ttl?: number; attributionToken?: string },
+  opts: HbcliCallOptions = {},
+): Promise<HbcliCallResult & { summary: string }> {
+  const hbArgs = ['--json', 'auth', 'customer-login', '--email', query.email, '--code', query.code]
+  if (query.ttl && query.ttl > 0) hbArgs.push('--ttl', String(query.ttl))
+  if (query.attributionToken) hbArgs.push('--attribution-token', query.attributionToken)
+  const live = await callHbcliJson(hbArgs, opts)
+  const r = live.result as { status?: string; attributionBound?: boolean } | null
+  let summary: string
+  if (live.via === 'hbcli-realtime' && r?.status === 'logged_in') {
+    const attribution = typeof r.attributionBound === 'boolean'
+      ? `;顾问归因绑定${r.attributionBound ? '成功' : '未成(登录不受影响,归因可重试)'}`
+      : ''
+    summary = `hotelbyte 客户登录成功(${query.email};新邮箱即注册${attribution})——凭据已存入 hbcli customer 档,后续酒店检索/报价走实时源`
+  } else {
+    summary = `hotelbyte 客户登录失败(${live.error ?? live.via});验证码是一次性凭据,失败后需重新发码`
+  }
+  return { ...live, summary }
+}

package/ts/capabilities/incident-log.ts

@@ -1,20 +1,17 @@
 /**
- * 进程级事故日志(D-NEW 护栏):fsync append-only JSONL。
+ * 进程级事故日志(D-NEW):同步、durable 的 JSONL 诊断记录。
  *
- * 目的: dsh 0.1.1-rc.1 只接 SIGINT/SIGTERM,缺 uncaughtException/unhandledRejection——
- * 任一插件 wasm/runtime 异常穿透到 node 层都会让整个 web UI 进程死亡,
- * 现场不存。这次(Z3 WASM mk_bool_var 崩溃)教训:连个取证都没有。
- *
- * 设计: 进程级 handler 同步写盘(fsync),尽量在进程被杀前留下事故证据。
- * handler 自身不再抛——再次抛出会绕过 handler,变成无声死亡。
+ * `uncaughtExceptionMonitor` 只观察 fatal 事故并留下证据；宿主仍决定
+ * 是否退出。GoTry 不吞掉 fatal 事件、不调用 process.exit、也不隐式重启。
+ * 工具 execute 的业务失败仍由 guardToolExecute 转成结构化失败返回。
  *
  * §11 状态面同步:事故日志是 gotry-state/incidents.jsonl,
- * 用户可见(README 第 x 节),可清理。
+ * 用户可见、可清理。
  */
 
-import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, writeFileSync } from 'node:fs'
 import { dirname, isAbsolute, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { pathToFileURL } from 'node:url'
 import type { ToolFailure } from '../src/tool-packet.ts'
 
 export type IncidentKind = 'uncaughtException' | 'unhandledRejection' | 'plugin_error' | 'tool_execute_error'
@@ -43,68 +40,104 @@ function ensureDir(path: string): void {
 
 let installed = false
 let logPath: string | null = null
+let activeMonitor: ((err: Error, origin: NodeJS.UncaughtExceptionOrigin) => void) | null = null
+
+function safeErrorMessage(value: unknown): string {
+  try {
+    if (value instanceof Error) return typeof value.message === 'string' ? value.message : '[error-without-message]'
+    if (typeof value === 'string') return value
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint' || typeof value === 'symbol') return String(value)
+    const json = JSON.stringify(value)
+    return typeof json === 'string' ? json : '[unprintable-error]'
+  } catch {
+    return '[unprintable-error]'
+  }
+}
+
+function safeErrorStack(value: unknown): string {
+  try {
+    const stack = (value as { stack?: unknown } | null | undefined)?.stack
+    return typeof stack === 'string' ? stack : ''
+  } catch {
+    return ''
+  }
+}
 
 /**
- * 写入一条事故并 fsync。同步执行——handler 内异步无效。
- * 自身 try/catch 自保,不让写入失败再抛一次把进程杀掉。
+ * 写入一条事故并 fsync。整个 append 使用同一个 fd，并保证所有失败路径
+ * 都尝试 close；返回 true 只表示写入、fsync、close 全部成功。
  */
 export function recordIncident(inc: Incident, stateRoot?: string): boolean {
   const target = stateRoot ? resolveIncidentsPath(stateRoot) : (logPath ?? resolveIncidentsPath('.'))
+  let fd: number | undefined
+  let closeAttempted = false
   try {
     ensureDir(target)
-    appendFileSync(target, JSON.stringify(inc) + '\n', { flag: 'a' })
-    // fsync: 让盘数据落定,免得被杀时缓冲丢
-    const fd = require('node:fs').openSync(target, 'a')
-    require('node:fs').fsyncSync(fd)
-    require('node:fs').closeSync(fd)
+    fd = openSync(target, 'a')
+    writeFileSync(fd, JSON.stringify(inc) + '\n', { encoding: 'utf8' })
+    fsyncSync(fd)
+    closeAttempted = true
+    closeSync(fd)
+    fd = undefined
     return true
   } catch {
-    // 绝对不能在这里抛——我们正在处理已经抛过一次的进程级错误
+    // 事故处理中的诊断失败绝不能再次抛出。
     return false
+  } finally {
+    if (fd !== undefined && !closeAttempted) {
+      closeAttempted = true
+      try { closeSync(fd) } catch { /* best effort close on a failed write */ }
+    }
   }
 }
 
 /**
- * 安装进程级护栏:进程整个生命周期仅生效一次(重复调用安全)。
- * 必须同步执行——异步发生在事件循环下一次,而 wasm 崩溃后已无下一轮。
- *
- * @returns 一个 disposer,卸载所有监听(测试场景使用)
+ * 安装进程级事故观察器。只挂 monitor，不改变 Node/dsh 的 fatal 行为。
+ * 进程整个生命周期仅生效一次；disposer 供宿主卸载和测试使用。
  */
 export function installProcessGuards(stateRoot: string, labels?: { uncaughtException?: string; unhandledRejection?: string }): () => void {
   if (installed) return () => { /* 已装,no-op */ }
   installed = true
   logPath = resolveIncidentsPath(stateRoot)
 
-  const uncaughtHandler = (err: Error, origin: NodeJS.UncaughtExceptionOrigin | 'uncaughtException') => {
-    recordIncident({
-      ts: new Date().toISOString(),
-      kind: 'uncaughtException',
-      message: (err?.message ?? String(err)).slice(0, 2000),
-      stack: (err?.stack ?? '').slice(0, 4000),
-      source: labels?.uncaughtException ?? String(origin),
-    }, stateRoot)
-    // 不调用 process.exit——让 dsh/上级容器的重启策略负责;
-    // 如果 dsh 不接住,我们至少留下事故记录。
-  }
-
-  const rejectionHandler = (reason: unknown, promise: Promise<unknown>) => {
-    const msg = reason instanceof Error ? reason.message : String(reason)
-    const stack = reason instanceof Error ? (reason.stack ?? '') : ''
-    recordIncident({
-      ts: new Date().toISOString(),
-      kind: 'unhandledRejection',
-      message: msg.slice(0, 2000),
-      stack: stack.slice(0, 4000),
-      source: labels?.unhandledRejection ?? 'promise',
-    }, stateRoot)
+  const monitor = (err: Error, origin: NodeJS.UncaughtExceptionOrigin) => {
+    try {
+      const kind: IncidentKind = origin === 'unhandledRejection' ? 'unhandledRejection' : 'uncaughtException'
+      const source = kind === 'unhandledRejection'
+        ? (labels?.unhandledRejection ?? 'promise')
+        : (labels?.uncaughtException ?? origin)
+      recordIncident({
+        ts: new Date().toISOString(),
+        kind,
+        message: safeErrorMessage(err).slice(0, 2000),
+        stack: safeErrorStack(err).slice(0, 4000),
+        source,
+      }, stateRoot)
+    } catch {
+      // Formatting must never replace the original fatal event. Keep a final
+      // plain fallback attempt for diagnostics, while the host retains control.
+      try {
+        recordIncident({
+          ts: new Date().toISOString(),
+          kind: origin === 'unhandledRejection' ? 'unhandledRejection' : 'uncaughtException',
+          message: '[incident-observer-fallback]',
+          source: 'incident-observer',
+        }, stateRoot)
+      } catch { /* observer is strictly best effort */ }
+    }
   }
 
-  process.on('uncaughtException', uncaughtHandler)
-  process.on('unhandledRejection', rejectionHandler)
+  process.on('uncaughtExceptionMonitor', monitor)
+  activeMonitor = monitor
+  let active = true
   return () => {
-    process.off('uncaughtException', uncaughtHandler)
-    process.off('unhandledRejection', rejectionHandler)
+    if (!active) return
+    active = false
+    if (activeMonitor !== monitor) return
+    process.off('uncaughtExceptionMonitor', monitor)
     installed = false
+    logPath = null
+    activeMonitor = null
   }
 }
 
@@ -112,24 +145,23 @@ export function installProcessGuards(stateRoot: string, labels?: { uncaughtExcep
  * 工具执行面异常隔离(D-NEW gotry 侧收尾):dsh 的一个工具 execute 抛错/拒绝
  * 会沿 cordis 传到主循环,拖垮整个会话。包装后:降级为结构化错误返回给 LLM、
  * 事故落盘,永不向上抛。落盘失败也不抛(双保险,仍返回结构化错误)。
- * 失败形状 = ToolFailure(RFC S1 observation envelope 的失败分支,编译期对齐)。
  */
 export function guardToolExecute<A, R>(name: string, stateRoot: string, execute: (args: A, exec: unknown) => R | Promise<R>): (args: A, exec: unknown) => Promise<R> {
   return async (args: A, exec: unknown): Promise<R> => {
     try {
       return await execute(args, exec)
     } catch (e) {
-      const err = e instanceof Error ? e : new Error(String(e))
+      const message = safeErrorMessage(e)
       recordIncident({
         ts: new Date().toISOString(),
         kind: 'tool_execute_error',
-        message: `${name}: ${err.message}`.slice(0, 2000),
-        stack: (err.stack ?? '').slice(0, 4000),
+        message: `${name}: ${message}`.slice(0, 2000),
+        stack: safeErrorStack(e).slice(0, 4000),
         source: name,
       }, stateRoot)
       const failure: ToolFailure = {
         ok: false,
-        summary: `gotry_${name} 内部错误(已隔离,会话继续): ${err.message.slice(0, 300)}`,
+        summary: `gotry_${name} 内部错误(已隔离,会话继续): ${message.slice(0, 300)}`,
         evidence: `[incident:tool_execute_error@${new Date().toISOString()}]`,
       }
       return failure as R
@@ -137,12 +169,9 @@ export function guardToolExecute<A, R>(name: string, stateRoot: string, execute:
   }
 }
 
-/** CLI 调试:从命令行单独跑查看当前进程是否已挂护栏 */
-if (import.meta.url === `file://${fileURLToPath(import.meta.url)}` && process.argv[2] === '--smoke') {
+/** CLI 调试:最小 fatal 子进程会留下事故证据并按 Node 原生语义非零退出。 */
+if (process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url && process.argv[2] === '--smoke') {
   const stateRoot = process.argv[3] ?? '.'
   installProcessGuards(stateRoot, { uncaughtException: 'smoke', unhandledRejection: 'smoke' })
-  writeFileSync(resolveIncidentsPath(stateRoot) + '.smoke', 'ok')
-  // 触发一次未捕获,应被写盘(不真正杀进程——进程继续跑完)
-  setTimeout(() => Promise.reject(new Error('intentional smoke-rejection')), 50)
-  setTimeout(() => { console.log('SMOKE OK'); process.exit(0) }, 500)
+  setTimeout(() => { throw new Error('intentional smoke-uncaught') }, 50)
 }