fix(app-boot): release the terminal before a fatal load exit

A dsh launch whose config failed validation returned the user to a broken
shell: typing was invisible and the next command was mangled by a stray
Device Attributes reply (1;2;4cecho ...).

The Loader mounts entries concurrently, so ui-tui can already hold the
terminal (raw mode, bracketed paste, keyboard protocol, plus an in-flight
DA query) when a sibling entry rejects on its own config. installFailLoud
wrote its diagnostic and exited immediately, so nothing disposed the tree
and ProcessTerminal.stop() never ran.

Give installFailLoud an optional release teardown, awaited between the
diagnostic and the exit and bounded by FAIL_LOUD_RELEASE_TIMEOUT_MS. The
TUI launcher passes one that disposes the root context, reaching the same
shutdown() the /exit path already uses (drainInput() + ui.stop()). The
context is captured in boot()'s prepare hook because the rejection arrives
while boot() is still in flight.

Bins that pass no release keep the previous behavior exactly.

packages/ui/app-boot/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/ui/app-boot/README.md
-README.md: ebd8e0842b934f6887e3c122e781c1d0f13bb5d3
-README.zh.md: ccd897d48178482aa74d0eb73505e26ec3a08d6c
+README.md: ba5cf9a05b456e2d72abe1e2a65b64825ceef1a5
+README.zh.md: d2f2b2d2c93b1ecb9fb4fad085d4abd663440108

packages/ui/app-boot/README.md

@@ -8,7 +8,8 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-c
 |---|---|
 | `resolveConfigPath(path, snapshotMode, cwd?)` | Absolute config path; `snapshotMode === 'replay'` swaps a `cordis.yml`/`.yaml` basename for its sibling `cordis.snapshot.yml` |
 | `loadEnv(binName, dir?, warn?)` | Load the gitignored `.env` (Node `process.loadEnvFile`); absent file is fine, an unloadable one warns a single labelled line (default: stderr) |
-| `installFailLoud(binName, proc?)` | Turn a post-`boot()` unhandled Loader rejection into one labelled stderr line + `exit(1)`; returns the uninstaller (for tests) |
+| `installFailLoud(binName, proc?, release?)` | Turn a post-`boot()` unhandled Loader rejection into one labelled stderr line + `exit(1)`; the optional `release` teardown is awaited between the two (bounded by `FAIL_LOUD_RELEASE_TIMEOUT_MS`) so a terminal-owning surface restores the terminal before exit; returns the uninstaller (for tests) |
+| `FAIL_LOUD_RELEASE_TIMEOUT_MS` | How long `installFailLoud` waits for its `release` hook; a wedged disposer delays the fatal exit, never cancels it |
 | `assertEntriesLoaded(ctx, binName)` | Throw when a settled tree holds an enabled entry with no fiber, reporting every unresolved plugin name as a Cordis startup failure |
 | `assertEntriesActivated(ctx, binName)` | Include the `assertEntriesLoaded` check, then await every enabled entry after the Loader settles; throw with each failed plugin's original stack or each pending plugin's unresolved services |
 | `loadPersonalPatches(binName, dir?)` | Parse the optional `config.yaml` in the Harness home (default [`resolveDshHome()`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) — a top-level YAML array of include `PatchOptions` (id-targeted config overrides, `insert` lists, `!!js` allowed); absent file → `undefined`, an unreadable/unparsable/non-array file throws |
@@ -20,6 +21,8 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-c
 
 Two Loader failure classes require separate guards because tree settlement propagates neither to its caller. A failed plugin import leaves a fiber-less entry that `assertEntriesLoaded` turns into a `boot()` rejection naming every unresolved plugin. A plugin callback or config failure leaves a failed fiber because `loader.await()` settles lifecycle tasks without propagating that error; `assertEntriesActivated` awaits the fiber explicitly and includes its original stack in the startup rejection. Before throwing, the audit marks those exact rejection reasons through one process checkpoint so `installFailLoud` coalesces Loader's duplicate notification while every unrelated unhandled rejection remains fatal.
 
+The Loader mounts entries concurrently, so a surface can already own the terminal when a sibling entry rejects: exiting straight from the handler would leave raw mode, bracketed paste, and the keyboard protocol set on the user's shell, and an in-flight terminal query's reply would land as literal text at the next prompt. A terminal-owning bin therefore passes `release` to dispose the tree — running that surface's own shutdown — before the exit commits. `dsh` captures the root context in `boot()`'s `prepare` hook rather than from its return value, because the rejection arrives while `boot()` is still in flight.
+
 Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`, npm packages) resolve through the Cordis Loader's internal module loader. Repository bins install Loader's optional `node-addon-require-builtin` peer; external callers must supply it or install plugins where plain Node import resolution can find them. Relative specifiers resolve against the config directory without the native helper. The built `dsh-app-boot` artifact embeds the statically mounted Include implementation while leaving Loader external, so the include tree and host bind to one Loader peer. The `dsh` source launcher additionally maps manifest-declared workspace packages to their TypeScript source; its configuration gate requires every TUI/Web bare plugin to appear in the resolver manifest's `dependencies`. The bins' subprocess smokes exercise the internal-loader path, while this package's unit suite drives `boot()` in-process against configs with relative specifiers.
 
 This package carries no loader hooks and no dev-mode surface. The [`dsh` app](../../../apps/cli/README.md) owns its Node source-launch hook and consumes these helpers for the boot sequence; built consumers continue to use plain Node package resolution.

packages/ui/app-boot/README.zh.md

@@ -8,7 +8,8 @@
 |---|---|
 | `resolveConfigPath(path, snapshotMode, cwd?)` | 生成绝对配置路径；当 `snapshotMode === 'replay'` 时，把 basename 为 `cordis.yml`/`.yaml` 的文件替换为同级 `cordis.snapshot.yml` |
 | `loadEnv(binName, dir?, warn?)` | 加载已被 git 忽略的 `.env`（Node `process.loadEnvFile`）；文件不存在不影响启动，文件无法加载时输出一行带标签的警告（默认写入 stderr） |
-| `installFailLoud(binName, proc?)` | 将 `boot()` 之后未处理的 Loader rejection 转换为一行带标签的 stderr 消息并执行 `exit(1)`；返回卸载函数（供测试使用） |
+| `installFailLoud(binName, proc?, release?)` | 将 `boot()` 之后未处理的 Loader rejection 转换为一行带标签的 stderr 消息并执行 `exit(1)`；两者之间会等待可选的 `release` 拆卸回调（以 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 为上限），使持有终端的界面能在退出前恢复终端；返回卸载函数（供测试使用） |
+| `FAIL_LOUD_RELEASE_TIMEOUT_MS` | `installFailLoud` 等待其 `release` 回调的时长；卡住的 disposer 只会延迟致命退出，而不会取消它 |
 | `assertEntriesLoaded(ctx, binName)` | 树结算后，如果其中存在已启用但没有 fiber 的条目，则抛出异常，并以 Cordis 启动故障的形式报告每个未解析插件的名称 |
 | `assertEntriesActivated(ctx, binName)` | 先执行 `assertEntriesLoaded` 检查，再在 Loader 结算后等待每个已启用配置项；抛出的错误包含每个失败插件的原始错误堆栈，或每个等待中插件尚未解析的服务 |
 | `loadPersonalPatches(binName, dir?)` | 解析 Harness home 中可选的 `config.yaml`（默认使用 [`resolveDshHome()`](../../util/paths/README.md)：先取 `$DSH_HOME`，否则取 `~/.dsh`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 |
@@ -20,6 +21,8 @@
 
 Loader 树结算不会向调用方传播两类故障，因此需要分别保护。插件导入失败会留下没有 fiber 的配置项，`assertEntriesLoaded` 将其转换为 `boot()` rejection，并列出每个未解析插件。插件回调或配置失败则会留下失败的 fiber，因为 `loader.await()` 只结算生命周期任务，不传播该错误；`assertEntriesActivated` 会显式等待该 fiber，并把原始错误堆栈写入启动 rejection。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
 
+Loader 并发挂载各个条目，因此当某个同级条目 rejection 时，某个界面可能已经持有终端：此时直接从处理函数退出，会把 raw 模式、bracketed paste 和键盘协议残留在用户的 shell 上，而尚未返回的终端查询响应会在下一个提示符处显示为字面文本。因此，持有终端的 bin 会传入 `release` 来释放整棵树——执行该界面自身的 shutdown——然后才提交退出。`dsh` 在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值，因为 rejection 到达时 `boot()` 尚未结算。
+
 配置中的裸插件 specifier（`@deepseek-ai/dsh-*`、npm 包（package））通过 Cordis Loader 的内部模块 loader 解析。仓库 bin 会安装 Loader 的可选 peer `node-addon-require-builtin`；外部调用方必须提供该组件，或者把插件安装到普通 Node import 解析可以找到的位置。相对 specifier 无需原生 helper，并以配置目录为基准解析。构建后的 `dsh-app-boot` 产物内嵌静态挂载的 Include 实现，但仍将 Loader 保持为外部依赖，因此 include 树与 host 会绑定到同一个 Loader peer。`dsh` 源码启动器还会将 manifest（元数据清单）声明的 workspace 包映射到其 TypeScript 源码；其配置门禁要求每个 TUI／Web 裸插件都出现在解析所用 manifest 的 `dependencies` 中。bin 的子进程冒烟测试覆盖内部 loader 路径，而本包的单元测试套件会在进程内使用相对 specifier 配置驱动 `boot()`。
 
 此包不包含 loader 钩子，也不提供开发模式接口。[`dsh` 应用](../../../apps/cli/README.md)持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper；构建后的消费方仍使用普通 Node 包解析。

packages/ui/app-boot/src/index.ts

@@ -325,24 +325,69 @@ async function observeLoaderRejectionCheckpoint(reasons: readonly unknown[]): Pr
   }
 }
 
+/**
+ * How long {@link installFailLoud} waits for its `release` hook before exiting
+ * anyway. A wedged disposer must delay the fatal exit, never cancel it.
+ */
+export const FAIL_LOUD_RELEASE_TIMEOUT_MS = 2_000
+
 /**
  * Install before boot to turn a late unhandled plugin-init rejection into one
  * labelled stderr diagnostic and `exit(1)`. A rejection already included by
  * {@link assertEntriesActivated} is ignored during its process checkpoint;
  * every other rejection remains fatal. Stdout remains untouched for ACP; the
  * returned function removes the handler.
+ *
+ * The Loader mounts entries concurrently, so a surface that owns the terminal
+ * can already hold it when a sibling entry rejects. Exiting straight from the
+ * handler would strand raw mode, bracketed paste, and the keyboard protocol on
+ * the user's shell, and leave an in-flight terminal query's reply to land as
+ * literal text at the next prompt. `release` is the terminal owner's chance to
+ * hand it back; it is awaited under {@link FAIL_LOUD_RELEASE_TIMEOUT_MS}. The
+ * diagnostic is written before the release so the reason survives a disposer
+ * that repaints or clears the screen, and the handler uninstalls itself before
+ * releasing so a rejection from teardown cannot re-enter it.
  * @param binName - the diagnostic prefix on the fatal-failure line.
  * @param proc - the process slice to register on; tests inject a fake.
+ * @param release - optional teardown awaited before exit, used by a
+ *   terminal-owning surface to restore the terminal. Its own failure is
+ *   swallowed because the pending fatal exit already owns the outcome.
  * @returns the uninstaller that removes the rejection handler.
  */
-export function installFailLoud(binName: string, proc: FailLoudProcess = process): () => void {
+export function installFailLoud(
+  binName: string,
+  proc: FailLoudProcess = process,
+  release?: () => Promise<void> | void,
+): () => void {
   const handler = (err: unknown): void => {
     if (assembledActivationRejections.has(err)) return
     proc.stderr.write(`${binName}: fatal load failure: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`)
-    proc.exit(1)
+    if (release === undefined) {
+      proc.exit(1)
+      return
+    }
+    // The release runs plugin disposers, which may themselves reject. Without
+    // this the handler would re-enter and report a teardown failure as a second
+    // fatal load failure, hiding the real one.
+    uninstall()
+    void (async () => {
+      try {
+        await Promise.race([
+          (async () => release())(),
+          new Promise<void>((resolve) => {
+            setTimeout(resolve, FAIL_LOUD_RELEASE_TIMEOUT_MS).unref()
+          }),
+        ])
+      } catch {
+        // The terminal release failed; the fatal exit below is the outcome that
+        // matters, and no reporter runs after it.
+      }
+      proc.exit(1)
+    })()
   }
+  const uninstall = (): void => void proc.off('unhandledRejection', handler)
   proc.on('unhandledRejection', handler)
-  return () => void proc.off('unhandledRejection', handler)
+  return uninstall
 }
 
 /**

packages/ui/app-boot/tests/app-boot.spec.ts

@@ -5,7 +5,8 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import {
-  addHarnessSourceSection, assertEntriesActivated, assertEntriesLoaded, boot, HARNESS_SOURCE_SECTION,
+  addHarnessSourceSection, assertEntriesActivated, assertEntriesLoaded, boot,
+  FAIL_LOUD_RELEASE_TIMEOUT_MS, HARNESS_SOURCE_SECTION,
   installFailLoud, loadEnv, loadOverlayPatches, resolveConfigPath, type FailLoudProcess,
 } from '../src/index.ts'
 
@@ -162,6 +163,56 @@ describe('installFailLoud', () => {
     proc.handlers[0]!(error)
     expect(proc.exits).toEqual([1])
   })
+
+  // The Loader mounts entries concurrently, so a terminal-owning surface can
+  // already hold raw mode when a sibling entry rejects. Exiting without running
+  // its teardown strands the terminal on the user's shell.
+  it('awaits the release hook before exiting so the terminal owner can restore it', async () => {
+    const proc = fakeProc()
+    const order: string[] = []
+    installFailLoud(NAME, proc, async () => {
+      await Promise.resolve()
+      order.push('released')
+    })
+    proc.handlers[0]!(new Error('sibling entry rejected'))
+    expect(proc.written[0]).toContain(`${NAME}: fatal load failure: `)
+    // The release is in flight, so the exit has not committed yet.
+    expect(proc.exits).toEqual([])
+    await vi.waitFor(() => { expect(proc.exits).toEqual([1]) })
+    expect(order).toEqual(['released'])
+  })
+
+  it('still exits when the release hook rejects', async () => {
+    const proc = fakeProc()
+    installFailLoud(NAME, proc, () => Promise.reject(new Error('terminal stop failed')))
+    proc.handlers[0]!(new Error('boom'))
+    await vi.waitFor(() => { expect(proc.exits).toEqual([1]) })
+  })
+
+  it('exits without waiting when a release hook never settles', async () => {
+    vi.useFakeTimers()
+    try {
+      const proc = fakeProc()
+      installFailLoud(NAME, proc, () => new Promise<void>(() => {}))
+      proc.handlers[0]!(new Error('boom'))
+      expect(proc.exits).toEqual([])
+      await vi.advanceTimersByTimeAsync(FAIL_LOUD_RELEASE_TIMEOUT_MS)
+      expect(proc.exits).toEqual([1])
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  // Teardown runs plugin disposers, whose own rejection must not be reported as
+  // a second fatal load failure over the real one.
+  it('uninstalls the handler before releasing, so teardown cannot re-enter it', async () => {
+    const proc = fakeProc()
+    installFailLoud(NAME, proc, () => {})
+    proc.handlers[0]!(new Error('boom'))
+    expect(proc.handlers).toHaveLength(0)
+    await vi.waitFor(() => { expect(proc.exits).toEqual([1]) })
+    expect(proc.written).toHaveLength(1)
+  })
 })
 
 describe('assertEntriesLoaded', () => {