@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/bin/gotry-inner.js

@@ -29,6 +29,8 @@ import {
   selectDshRuntime,
   supportsNodeVersion,
 } from './gotry-runtime-resolution.js'
+import { onboardingSkipReason, orchestrateWebLaunch } from './gotry-bootstrap.js'
+import { spawnOwnedChild, terminateOwnedChild } from './gotry-process-liveness.js'
 
 const here = dirname(fileURLToPath(import.meta.url))
 const repoRoot = join(here, '..')
@@ -81,6 +83,9 @@ if (help) {
 
 Usage:
   gotry web                          # dsh Web UI on http://127.0.0.1:3080
+    # (interactive TTY) 启动前若发现可自动安装的可选能力,问一次是否配置;
+    # 确认复用 doctor --fix 幂等安装,拒绝立即继续。CI/非 TTY/全健康不弹问。
+    # 跳过该问: --no-onboarding 或 GOTRY_ONBOARDING_SKIP=1
   gotry setup                        # 扩展就位检查/指引(商店一键装)
   gotry setup calendar               # 可选日历(CalDAV 工作窗口)挂载开关:默认关;--off 关闭;--status 查看
   gotry doctor                       # 可选依赖体检:扩展/agent-reach/hbcli/flyai/sidebar 状态 + 补装指引
@@ -248,6 +253,9 @@ function projectBenchmarkPatch(raw, entryPath, configPath) {
 // can make dsh fail while assembling the first request.  Require the exact
 // source shape before replacing it; malformed or ambiguous prompt config must
 // fail closed rather than being partially interpreted.
+// Target dsh-system-prompt Config exposes only personaPrefix / personaSuffix;
+// the legacy `persona:` key does not project through. Validate against the
+// current personaPrefix key.
 function projectBenchmarkSystemPrompt(lines) {
   const rootStarts = lines.map((line, index) => /^-\s+/.test(line) ? index : -1).filter(index => index >= 0)
   const rootItems = rootStarts.map((itemStart, index) => lines.slice(itemStart, rootStarts[index + 1] ?? lines.length))
@@ -260,7 +268,12 @@ function projectBenchmarkSystemPrompt(lines) {
   while (end < lines.length && (lines[end].trim() === '' || /^\s/.test(lines[end]) || lines[end].trim().startsWith('#'))) end += 1
   const item = lines.slice(start, end)
   const configIndexes = item.map((line, index) => /^ {2}config:\s*$/.test(line) ? index : -1).filter(index => index >= 0)
-  const personaIndexes = item.map((line, index) => /^ {4}persona:\s*>-\s*$/.test(line) ? index : -1).filter(index => index >= 0)
+  const personaIndexes = item.map((line, index) => /^ {4}personaPrefix:\s*>-\s*$/.test(line) ? index : -1).filter(index => index >= 0)
+  // Reject any leftover legacy `persona:` field under config: — it would be
+  // silently dropped by the target Config and leave the kernel persona-less.
+  // The minimal kernel must project through personaPrefix only.
+  const legacyPersonaIndexes = item.map((line, index) => /^ {4}persona:\s*>-\s*$/.test(line) ? index : -1).filter(index => index >= 0)
+  if (legacyPersonaIndexes.length !== 0) throw new Error('benchmark system-prompt legacy persona key not allowed under target 0.1.5-rc.1')
   if (configIndexes.length !== 1 || personaIndexes.length !== 1 || personaIndexes[0] <= configIndexes[0]) {
     throw new Error('benchmark system-prompt config violation')
   }
@@ -268,7 +281,7 @@ function projectBenchmarkSystemPrompt(lines) {
   const blockEnd = item.slice(persona + 1).findIndex(line => line.trim() !== '' && !/^\s{6,}/.test(line))
   const contentEnd = blockEnd < 0 ? item.length : persona + 1 + blockEnd
   if (contentEnd === persona + 1 || item.slice(persona + 1, contentEnd).some(line => line.trim() !== '' && !/^\s{6,}/.test(line))) {
-    throw new Error('benchmark system-prompt persona violation')
+    throw new Error('benchmark system-prompt personaPrefix block violation')
   }
   const before = item.slice(1, configIndexes[0]).filter(line => line.trim() !== '' && !line.trim().startsWith('#'))
   const between = item.slice(configIndexes[0] + 1, persona).filter(line => line.trim() !== '' && !line.trim().startsWith('#'))
@@ -277,7 +290,7 @@ function projectBenchmarkSystemPrompt(lines) {
   const replacement = [
     '- id: system-prompt',
     '  config:',
-    '    persona: >-',
+    '    personaPrefix: >-',
     '      You are GoTry, a task-agnostic travel planning assistant.',
     '      Use only the current conversation and tools available in this benchmark session.',
   ]
@@ -367,9 +380,10 @@ if (benchmarkEnvironmentConfig) {
 }
 // dsh-map-tools 宿主插件(地图/路线/POI,零 key 走 OSM/OSRM):tarball 随包 vendor,
 // repo 工作副本走 runtime workspace 链接/依赖解析;都找不到就整块剔除 patch 条目
-// (缺地图不挡旅行规划)。不能改成 npm 依赖:其 peerDependencies 要求
-// dsh-settings/dsh-tools >=0.1.2-rc.1,与本包锁定的 0.1.2-alpha.3 家族在 npm
-// 严格 peer 解析下 ERESOLVE,会直接弄坏 npx 安装。
+// (缺地图不挡旅行规划)。保持 vendored 形态而非 npm 依赖:历史上游 peerDependencies
+// (dsh-settings/dsh-tools >=0.1.2-rc.1)与锁定的 0.1.2-alpha.3 家族在 npm 严格 peer
+// 解析下 ERESOLVE;当前锁定 0.1.5-rc.1 家族,vendored 副本 peerDependencies 已
+// 对齐 0.1.5-rc.1,继续以 vendored 形态复用同一份适配补丁与七工具接线。
 let mapEntry = ''
 if (!benchmarkEnvironmentConfig) {
   const vendoredMap = join(repoRoot, 'ts/dsh-runtime/vendor/dsh-map-tools/lib/index.js')
@@ -423,7 +437,7 @@ if (mapEntry) {
 // 未配置的日历工具是纯负资产(会话中段才撞「未配置 username」报错),gotry 对它的
 // 唯一诉求(工作窗口)由访谈首轮覆盖。挂载与否由 **setup 状态面**决定(founder
 // 2026-09-03 纠偏:禁止环境变量控制产品行为;可选依赖进 setup 状态管理,与扩展
-// manifest 同居 ~/.gotry)——`npx gotry setup calendar` 写 ~/.gotry/calendar.json,
+// manifest 同居 ~/.gotry)——`npx @danceiny/gotry setup calendar` 写 ~/.gotry/calendar.json,
 // `--off` 删除恢复默认;doctor 报告三态。
 let calEnabled = false
 try {
@@ -479,17 +493,86 @@ const cleanupPatch = () => {
   rmSync(patchDir, { recursive: true, force: true })
 }
 process.once('exit', cleanupPatch)
-let child = null
-const terminateOnSignal = (signal, listener) => {
-  cleanupPatch()
-  if (child && !child.killed) child.kill(signal)
-  process.off(signal, listener)
-  process.kill(process.pid, signal)
+// 信号转发(issue #267 P1):spawnSync 阻塞 JS,信号处理器无法服务、finally 也跑不到。
+// 故 web-onboarding 子调用改 awaited spawn。SIGINT/SIGTERM 转发在 onboarding **之前**注册一次,
+// 并贯穿后续 dsh web 子进程的整个生命周期——服务管理器只向父进程发 SIGTERM 时,无论当前活跃的是
+// onboarding 子进程组还是 dsh 子,都收到同一信号。收到信号时:终止当前活跃子进程/进程组,
+// 等待 bounded close/reap,清 patch + 私有 result 目录(均幂等),移除本监听器,再向自己重发信号恢复原生终止语义。
+// signalHandling 护栏防递归/重复处理(重发信号不再二次进入本回调)。setup/doctor 的 spawnSync 不在此窗口,保持不变。
+let child = null                  // dsh web 子进程(launchWeb 后)
+let childGroupPid = null          // POSIX dsh child process-group leader
+let onboardingChild = null        // onboarding 子进程(运行中时);POSIX 下独立进程组
+let onboardingChildGroupPid = null
+let onboardingResultDir = null    // 私有结果目录;信号/正常/错误路径都清
+// outer grace 必须大于 bootstrap installer cleanup budget(2s TERM + 1s SIGKILL wait)。
+// 否则 stubborn installer 忽略 TERM 时,inner 可能先杀 bootstrap,导致 bootstrap 来不及 SIGKILL
+// 它自己 detached 出去的 installer 进程组。
+const ONBOARDING_TERM_GRACE_MS = 5_000
+const ONBOARDING_KILL_WAIT_MS = 1_000
+const cleanupOnboardingResult = () => {
+  if (!onboardingResultDir) return
+  const d = onboardingResultDir
+  onboardingResultDir = null
+  try { rmSync(d, { recursive: true, force: true }) } catch { /* ignore */ }
+}
+const onboardingChildTimeoutMs = (() => {
+  const raw = process.env.GOTRY_ONBOARDING_CHILD_TIMEOUT_MS
+  if (raw === undefined || raw === '') return 300_000
+  if (!/^[1-9]\d*$/.test(raw)) return 300_000
+  const n = Number(raw)
+  return Number.isSafeInteger(n) && n > 0 ? n : 300_000
+})()
+let signalHandling = false
+const signalListeners = new Map()
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+const signalChild = (proc, sig, groupPid = null) => {
+  if (!proc) return
+  if (process.platform !== 'win32' && groupPid) {
+    try { process.kill(-groupPid, sig); return } catch { /* fallback */ }
+  }
+  try { proc.kill(sig) } catch { /* ignore */ }
+}
+const terminateChildBounded = async (proc, sig, groupPid = null, graceMs = ONBOARDING_TERM_GRACE_MS, killMs = ONBOARDING_KILL_WAIT_MS) => {
+  await terminateOwnedChild({ child: proc, groupPid, signal: sig, termGraceMs: graceMs, killWaitMs: killMs })
+}
+const registerSignalForwarding = () => {
+  if (signalListeners.size) return
+  for (const sig of ['SIGINT', 'SIGTERM']) {
+    const listener = () => {
+      if (signalHandling) return            // 防递归:重发信号不再二次进入
+      signalHandling = true
+      void (async () => {
+        const active = onboardingChild || child
+        const groupPid = onboardingChild ? onboardingChildGroupPid : childGroupPid
+        cleanupPatch()
+        cleanupOnboardingResult()
+        await terminateChildBounded(active, sig, groupPid)
+        for (const [s, l] of signalListeners) process.off(s, l)
+        signalListeners.clear()
+        process.kill(process.pid, sig)       // 移除监听器后重发 → 原生终止语义
+        await sleep(2_000)
+        process.exit(128 + (sig === 'SIGINT' ? 2 : 15))
+      })()
+    }
+    process.on(sig, listener)
+    signalListeners.set(sig, listener)
+  }
+}
+
+const unregisterSignalForwarding = () => {
+  for (const [s, l] of signalListeners) process.off(s, l)
+  signalListeners.clear()
 }
 // LLM key 由 dsh 宿主管理(凭证是用户资产,UI 在 dsh 里;gotry 不拦截启动期,
 // 不在用户面前展示任何 key 配置引导),此处直接放手 spawn dsh。
+const webPortArgs = (() => {
+  if (mode !== 'web') return []
+  const portIndex = rest.indexOf('--port')
+  const port = portIndex >= 0 ? rest[portIndex + 1] : undefined
+  return port !== undefined && /^(?:0|[1-9]\d*)$/.test(port) ? ['--port', port] : []
+})()
 const binJs = mode === 'web'
-  ? ['web', '--patch', patchPath, ...(process.argv.includes('--no-open') ? ['--no-open'] : [])]
+  ? ['web', '--patch', patchPath, ...(process.argv.includes('--no-open') ? ['--no-open'] : []), ...webPortArgs]
   : ['--profile', 'headless', '--patch', patchPath, ...rest]
 
 const childEnv = { ...process.env }
@@ -517,21 +600,106 @@ const childStdio = mode === 'web'
 let benchmarkCapturedBytes = 0
 let benchmarkDiagnosticBuffer = Buffer.alloc(0)
 let benchmarkOutputTruncated = false
-// 启动一次性 doctor 摘要(issue #114,design §3.1③):分离子进程后台跑只读体检,
-// 有待处理项打一行 stderr(stderr 继承,不污染 stdout;benchmark 面保持零杂音)。
-// detached+unref:不阻塞不拖慢启动;inner 生命周期天然一次,不重复刷;失败静默。
-if (!benchmarkEnvironmentConfig) {
-  try {
-    spawn(process.execPath, [join(here, 'gotry-bootstrap.js'), 'doctor', '--summary'], {
-      detached: true,
-      stdio: ['ignore', 'ignore', 'inherit'],
-    }).unref()
-  } catch { /* 体检不可用不挡启动 */ }
-}
-child = spawn(process.execPath, [dshBin, ...binJs], {
-  stdio: childStdio,
-  env: childEnv,
-  cwd: dshCwd,
+// issue #258:`gotry web` 启动前的交互式 onboarding——每次符合条件的启动评估一次、至多问一次,
+// 无跨启动持久确认(每次 web 启动独立判定;不写「已问过」标记)。仅交互式 TTY + 有可自动安装
+// 缺项时问一次;y 复用 doctor --fix 幂等安装器,不建第二套;n 立即继续 web)。
+// CI/benchmark/非 TTY/全健康/GOTRY_SETUP_SKIP=1/GOTRY_ONBOARDING_SKIP=1/--no-onboarding
+// 均零 prompt 零安装,仍启 web;永不 postinstall 或后台任务里安装。无 auto 但有需用户操作/
+// 不可用缺项时(如 win32 平台不支持自动安装),onboarding 渲染分类计划与原因、不 prompt 不安装,
+// 标记 reported;orchestrateWebLaunch 据此抑制重复的 detached doctor 摘要(design §3.1③,#114)。
+// 编排走 orchestrateWebLaunch(显式注入依赖的 E2E 边界缝,bootstrap-tests 跨边界单测同款):
+// bootstrap 以 `onboarding --result-file=…` 异步 inherit 跑(awaited spawn,POSIX 下独立进程组——
+// 使 JS 能服务 SIGINT/SIGTERM 并在信号路径清 patch+result 目录、reap installer 子树);result JSON 告知是否 prompt /
+// reported,用以抑制重复的启动摘要行。yes/no/失败/跳过/已 reported 均继续到 launchWeb(spawn dsh web)。
+const onboardingSkip = onboardingSkipReason({
+  mode,
+  benchmark: Boolean(benchmarkEnvironmentConfig),
+  env: process.env,
+  argv: process.argv,
+  isTTY: process.stdin.isTTY,
+})
+// 一次性注册信号转发,覆盖 onboarding + dsh child 全生命周期(dsh close/error 时注销)。
+registerSignalForwarding()
+await orchestrateWebLaunch({
+  onboardingSkip,
+  runOnboarding: async () => {
+    // result 通道硬化:不在 os.tmpdir 下放可预测文件名——mkdtempSync 建 0700 私有目录,
+    // result.json 放其内;bootstrap 以 mode 0600 + flag wx 写(存在路径/符号链接永不覆盖,
+    // 防 symlink 互换攻击)。子调用改 awaited spawn(非 spawnSync)使 JS 能服务信号;
+    // 信号/正常/错误路径都清目录(幂等),详见上方 registerSignalForwarding/cleanupOnboardingResult。
+    let resultDir = null
+    try {
+      resultDir = mkdtempSync(join(tmpdir(), 'gotry-onboarding-'))
+      onboardingResultDir = resultDir
+      const resultFile = join(resultDir, 'result.json')
+      // 信号转发在 onboarding 之前注册一次,贯穿后续 dsh web 整个生命周期(见上方 registerSignalForwarding);
+      // onboarding 正常结束后不注销——服务管理器只向父进程发信号时,当前活跃子进程(onboarding 或 dsh)均收到。
+      registerSignalForwarding()
+      const detachedOnboarding = process.platform !== 'win32'
+      const oc = spawn(process.execPath, [join(here, 'gotry-bootstrap.js'), 'onboarding', `--result-file=${resultFile}`], {
+        stdio: 'inherit',
+        detached: detachedOnboarding,
+      })
+      onboardingChild = oc
+      onboardingChildGroupPid = detachedOnboarding ? oc.pid : null
+      // onboarding 永不挡 web:保留 spawnSync 原有的 300s 上限(可经 GOTRY_ONBOARDING_CHILD_TIMEOUT_MS 注入以供
+      // 确定性测试,生产默认 300_000)。超时即 SIGTERM(2s 后 SIGKILL 兜底),settle 恰好一次于 close/error/timeout;
+      // 之后继续 web(prompted:false),不留进程/目录(finally 清 result,信号路径清 patch+result)。
+      await new Promise((resolve) => {
+        let done = false
+        let killTimer = null
+        const timer = setTimeout(() => {
+          process.stderr.write(`[gotry] onboarding child timeout after ${onboardingChildTimeoutMs}ms; continuing to web\n`)
+          signalChild(oc, 'SIGTERM', onboardingChildGroupPid)
+          killTimer = setTimeout(() => { if (!done) signalChild(oc, 'SIGKILL', onboardingChildGroupPid) }, ONBOARDING_TERM_GRACE_MS)
+        }, onboardingChildTimeoutMs)
+        const finish = () => { if (done) return; done = true; clearTimeout(timer); if (killTimer) clearTimeout(killTimer); resolve() }
+        oc.once('close', finish)
+        oc.once('error', (error) => {
+          process.stderr.write(`[gotry] onboarding child spawn failed: ${error.code || error.name || 'error'}; continuing to web\n`)
+          finish()
+        })
+      })
+      if (signalHandling) await new Promise(() => {})
+      onboardingChild = null
+      onboardingChildGroupPid = null
+      if (existsSync(resultFile)) {
+        try { return JSON.parse(readFileSync(resultFile, 'utf-8')) }
+        catch { return { prompted: false } }
+      }
+      return { prompted: false }
+    } catch {
+      process.stderr.write('[gotry] onboarding setup failed; continuing to web\n')
+      return { prompted: false }
+    } finally {
+      onboardingChild = null
+      onboardingChildGroupPid = null
+      if (resultDir) { try { rmSync(resultDir, { recursive: true, force: true }) } catch { /* ignore */ } }
+      onboardingResultDir = null
+    }
+  },
+  // 启动一次性 doctor 摘要(issue #114,design §3.1③):分离子进程后台跑只读体检,
+  // 有待处理项打一行 stderr(stderr 继承,不污染 stdout;benchmark 面保持零杂音)。
+  // onboarding 已 prompt 时 orchestrateWebLaunch 已抑制本回调(不重复)。
+  runSummary: () => {
+    if (benchmarkEnvironmentConfig) return
+    try {
+      spawn(process.execPath, [join(here, 'gotry-bootstrap.js'), 'doctor', '--summary'], {
+        detached: true,
+        stdio: ['ignore', 'ignore', 'inherit'],
+      }).unref()
+    } catch { /* 体检不可用不挡启动 */ }
+  },
+  // dsh web 启动边界:launchWeb 即 inner 跨过 onboarding 后到达的 web 启动标记。
+  launchWeb: async () => {
+    const owned = spawnOwnedChild(process.execPath, [dshBin, ...binJs], {
+      stdio: childStdio,
+      env: childEnv,
+      cwd: dshCwd,
+    })
+    child = owned.child
+    childGroupPid = owned.groupPid
+  },
 })
 if (benchmarkStdout) {
   const maxBytes = Math.max(1, Number(benchmarkTerminalConfig?.max_bytes ?? 1))
@@ -569,8 +737,37 @@ const reportBenchmarkFailure = reason => {
   process.stderr.write(`[gotry] benchmark terminal output unavailable (${reason})\n`)
 }
 
-child.on('close', (code, signal) => {
+let childLifecycleHandled = false
+let childCleanupPromise = null
+// `close` may be delayed by a descendant which inherited dsh's stdio pipe.
+// Always start bounded TERM→KILL cleanup from `exit` so the owned group is
+// reaped before any close/parser wait. The benchmark zero-success close path
+// still parses the already-captured stdout buffer unchanged; cleanup runs
+// fire-and-forget in the background and stays bounded by ONBOARDING bounds.
+const startChildCleanup = () => {
+  if (childCleanupPromise || !child) return childCleanupPromise
+  childCleanupPromise = terminateOwnedChild({
+    child,
+    groupPid: childGroupPid,
+    signal: 'SIGTERM',
+    termGraceMs: ONBOARDING_TERM_GRACE_MS,
+    killWaitMs: ONBOARDING_KILL_WAIT_MS,
+  })
+  return childCleanupPromise
+}
+child.on('exit', (code, signal) => {
+  void startChildCleanup()
+})
+child.on('close', async (code, signal) => {
+  if (childLifecycleHandled) return
+  childLifecycleHandled = true
   cleanupPatch()
+  if (signalHandling) return
+  unregisterSignalForwarding()
+  // Non-benchmark web/headless children are owned through both normal and
+  // anomalous exits. The promise was normally started by `exit`; retaining
+  // this close fallback covers runtimes that report close without exit.
+  if (!benchmarkStdout || code !== 0 || signal) await startChildCleanup()
   if (benchmarkStdout) {
     const captured = Buffer.concat(benchmarkStdout).toString('utf8')
     if (code !== 0 || signal || benchmarkOutputTruncated) {
@@ -613,21 +810,43 @@ child.on('close', (code, signal) => {
     // D-NEW 护栏:dsh 异常退出也写一条 incident,留现场而非沉默
     // dist 模式 import JS(node_modules 下的 .ts 会被 Node 拒 strip)
     const incidentModule = distModuleMode && existsSync(join(repoRoot, 'dist/capabilities/incident-log.js'))
-      ? '../dist/capabilities/incident-log.js'
-      : '../ts/capabilities/incident-log.ts'
-    import(incidentModule).then(({ recordIncident }) => {
+      ? join(repoRoot, 'dist/capabilities/incident-log.js')
+      : join(repoRoot, 'ts/capabilities/incident-log.ts')
+    try {
+      const { recordIncident } = await import(pathToFileURL(incidentModule).href)
       recordIncident({
         ts: new Date().toISOString(),
         kind: 'plugin_error',
         message: `gotry spawn exit: ${mode} code=${code} signal=${signal}`,
         source: 'gotry-cli',
-      }, repoRoot).catch(() => {})
-    }).catch(() => {}) // module 找不到时静默
+      }, repoRoot)
+    } catch { /* diagnostics remain best-effort; fatal exit is preserved */ }
+  }
+  if (signal) {
+    try { process.kill(process.pid, signal) } catch { process.exit(1) }
+    return
   }
   process.exit(code ?? 1)
 })
-child.on('error', (e) => {
+child.on('error', async (e) => {
+  if (childLifecycleHandled) return
+  childLifecycleHandled = true
   cleanupPatch()
+  if (signalHandling) return
+  unregisterSignalForwarding()
+  await startChildCleanup()
+  try {
+    const incidentModule = distModuleMode && existsSync(join(repoRoot, 'dist/capabilities/incident-log.js'))
+      ? join(repoRoot, 'dist/capabilities/incident-log.js')
+      : join(repoRoot, 'ts/capabilities/incident-log.ts')
+    const { recordIncident } = await import(pathToFileURL(incidentModule).href)
+    recordIncident({
+      ts: new Date().toISOString(),
+      kind: 'plugin_error',
+      message: `gotry spawn error: ${e instanceof Error ? e.message : String(e)}`,
+      source: 'gotry-cli',
+    }, repoRoot)
+  } catch { /* diagnostics remain best-effort; fatal exit is preserved */ }
   if (benchmarkEnvironmentConfig) {
     reportBenchmarkFailure('child_spawn_failure')
     return

package/bin/gotry-process-liveness.d.ts

@@ -0,0 +1,27 @@
+import type { ChildProcess, SpawnOptions } from 'node:child_process'
+
+export interface OwnedChild {
+  child: ChildProcess
+  groupPid: number | null
+}
+
+export interface OwnedChildCleanupResult {
+  childExited: boolean
+  groupEmpty: boolean
+  forced: boolean
+}
+
+export interface OwnedChildCleanupOptions {
+  child?: ChildProcess | null
+  groupPid?: number | null
+  signal?: NodeJS.Signals
+  termGraceMs?: number
+  killWaitMs?: number
+}
+
+export declare function spawnOwnedChild(command: string, args: readonly string[], options?: SpawnOptions): OwnedChild
+export declare function signalOwnedChild(child: ChildProcess | null | undefined, signal: NodeJS.Signals, groupPid?: number | null): void
+export declare function isOwnedProcessGroupEmpty(groupPid: number | null): boolean
+export declare function waitForOwnedChildQuiescence(child: ChildProcess, groupPid?: number | null, timeoutMs?: number): Promise<boolean>
+export declare function terminateOwnedChild(options?: OwnedChildCleanupOptions): Promise<OwnedChildCleanupResult>
+export declare const PROCESS_LIVENESS_BOUNDS: Readonly<{ termGraceMs: number; killWaitMs: number }>

package/bin/gotry-process-liveness.js

@@ -0,0 +1,97 @@
+/**
+ * GoTry-owned lifecycle for one externally spawned dsh child.
+ *
+ * The dsh CLI is an external process boundary. On POSIX we make it the
+ * leader of its own process group so a parent-only signal or a failed dsh
+ * child cannot strand descendants. This module owns only bounded signalling
+ * and quiescence observation; incident formatting remains in the existing
+ * GoTry incident writer.
+ */
+
+import { spawn } from 'node:child_process'
+
+const DEFAULT_TERM_GRACE_MS = 5_000
+const DEFAULT_KILL_WAIT_MS = 1_000
+const POLL_MS = 20
+
+/** Spawn a child in a private process group where the host supports it. */
+export function spawnOwnedChild(command, args, options = {}) {
+  const child = spawn(command, args, {
+    ...options,
+    detached: process.platform !== 'win32',
+  })
+  return {
+    child,
+    groupPid: process.platform !== 'win32' ? (child.pid ?? null) : null,
+  }
+}
+
+/** Signal the child group, falling back to the direct child when necessary. */
+export function signalOwnedChild(child, signal, groupPid = null) {
+  if (!child) return
+  if (process.platform !== 'win32' && groupPid !== null) {
+    try {
+      process.kill(-groupPid, signal)
+      return
+    } catch {
+      // The group can disappear between observation and delivery. Try the
+      // direct handle as a best-effort race fallback.
+    }
+  }
+  try { child.kill(signal) } catch { /* exit races are contained */ }
+}
+
+function childExited(child) {
+  return child.exitCode !== null || child.signalCode !== null
+}
+
+function groupEmpty(groupPid) {
+  if (process.platform === 'win32' || groupPid === null) return true
+  try {
+    process.kill(-groupPid, 0)
+    return false
+  } catch (error) {
+    return error?.code === 'ESRCH'
+  }
+}
+
+/** Expose the same group-emptiness fact used by the bounded cleanup proof. */
+export function isOwnedProcessGroupEmpty(groupPid) {
+  return groupEmpty(groupPid)
+}
+
+/** Wait for the direct child and, on POSIX, its whole private group. */
+export async function waitForOwnedChildQuiescence(child, groupPid = null, timeoutMs = DEFAULT_TERM_GRACE_MS) {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() <= deadline) {
+    if (childExited(child) && groupEmpty(groupPid)) return true
+    await new Promise((resolve) => setTimeout(resolve, POLL_MS))
+  }
+  return childExited(child) && groupEmpty(groupPid)
+}
+
+/**
+ * Bounded TERM → KILL cleanup for one owned child group. It resolves only
+ * after the direct child and group are observed empty, or after the bound.
+ */
+export async function terminateOwnedChild({
+  child,
+  groupPid = null,
+  signal = 'SIGTERM',
+  termGraceMs = DEFAULT_TERM_GRACE_MS,
+  killWaitMs = DEFAULT_KILL_WAIT_MS,
+} = {}) {
+  if (!child) return { childExited: true, groupEmpty: true, forced: false }
+  signalOwnedChild(child, signal, groupPid)
+  if (await waitForOwnedChildQuiescence(child, groupPid, termGraceMs)) {
+    return { childExited: true, groupEmpty: true, forced: false }
+  }
+  signalOwnedChild(child, 'SIGKILL', groupPid)
+  const empty = await waitForOwnedChildQuiescence(child, groupPid, killWaitMs)
+  return { childExited: childExited(child), groupEmpty: empty, forced: true }
+}
+
+export const PROCESS_LIVENESS_BOUNDS = Object.freeze({
+  termGraceMs: DEFAULT_TERM_GRACE_MS,
+  killWaitMs: DEFAULT_KILL_WAIT_MS,
+})

package/bin/gotry-runtime-resolution.d.ts

@@ -8,7 +8,7 @@ export type DshRuntime = {
   source: 'root'
 }
 
-export const REQUIRED_BENCHMARK_DSH_VERSION: '0.1.2-alpha.3'
+export const REQUIRED_BENCHMARK_DSH_VERSION: '0.1.5-rc.1'
 
 export function readDshPackage(bin: string): Omit<DshRuntime, 'source'> | null
 export function resolveDshPackage(resolver: DshResolver): Omit<DshRuntime, 'source'> | null

package/bin/gotry-runtime-resolution.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
-export const REQUIRED_BENCHMARK_DSH_VERSION = '0.1.2-alpha.3'
+export const REQUIRED_BENCHMARK_DSH_VERSION = '0.1.5-rc.1'
 
 export function readDshPackage(bin) {
   try {
@@ -34,7 +34,7 @@ export function selectDshRuntime({ rootResolver }) {
   if (root) return { ...root, source: 'root' }
   // D-27 清偿(issue #120):legacy vendored 回退路径已移除——该形态的 Node 兼容窗口
   // 断裂(Round 5 起「不承诺可运行」),解析成功只会把「dsh 缺失」变成下游玄学失败。
-  // 唯一受支持形态 = root manifest / 依赖解析(216 精确依赖闭包);找不到即 fail-closed,
+  // 唯一受支持形态 = root manifest / 依赖解析(232 精确依赖闭包);找不到即 fail-closed,
   // 由调用方给明确重装指引。benchmark 原本就禁用回退,语义不变(入参保留以稳调用面)。
   return null
 }