@deepseek-harness-tui/dsh-tui 0.13.0 → 0.14.1

package/README.md

@@ -31,8 +31,9 @@
 - **Mermaid diagrams** — ````mermaid ```` fences drawn as Unicode diagrams.
 - **LaTeX math** — `$…$` and `$$…$$` formulas as Unicode text, fractions and limits stacked in display blocks; `mathRendering: image` typesets block and one-row inline formulas as terminal images on graphics terminals.
 - **Timeline rail** — every turn clickable; timeline / scrollbar / hidden gutter.
-- **Side panel** — `Ctrl+B` splits the chat with a panel column (todo / jobs) once the terminal is wide enough; narrow terminals and inline mode keep today's full-screen panels.
+- **Side panel** — `Ctrl+B` splits the chat with a panel column once the terminal is wide enough; all eight built-in panels are enabled by default. Narrow terminals and inline mode keep full-screen panels.
 - **Live state** — activity animation, context bar, TPS, cache hit rate, effort, tokens, session cost estimate (main + subagents), Git and session metadata.
+  Context-bar fill follows backend occupancy; colors estimate content composition. Compaction clears obsolete estimates, and missing composition displays a single used block.
 - **One session manager** — `/resume` `/home` `/agentview` `/bg` `⌸`.
 - **Session workflow** — `/new` `/compact` `/export` `/btw`, model hot-switch, fork, rewind, vim, fullscreen draft editor.
 - **IDE selection channel** — a VS Code selection lands in the prompt.
@@ -171,11 +172,86 @@ Full guide: [Session migration](docs/migrate.en.md).
 
 **VS Code**: use the integrated terminal or the `dsh-tui-vscode` extension. See [VS Code guide](docs/vscode.en.md). **Herdr**: run `dsh-tui` in a [Herdr](https://herdr.dev) pane; `idle` / `working` / `blocked` are reported through its local integration API.
 
+### Experimental: Claude backend
+
+dsh-TUI can also run its session on Claude: the same interface, driving the
+Claude Code CLI through the Claude Agent SDK. Your project's `CLAUDE.md`,
+settings, hooks, MCP servers and plugins load as the CLI loads them.
+
+```sh
+# once, in the dsh-tui profile directory (the SDK is an optional dependency)
+cd ~/.dsh/profiles/dsh-tui && pnpm add @anthropic-ai/claude-agent-sdk@0.3.287
+dsh-tui --backend claude     # or pick Claude in /kernel; that choice is remembered
+```
+
+The easiest install: open the kernel picker (the launchpad "Kernel" entry or
+`/kernel`) and press Enter on the dim Claude row — the wizard locates the
+profile directory and installs the pinned SDK for you; the command above is
+its manual equivalent.
+
+- **Sign-in**: a `/channel` relay profile, your dsh-auth `anthropic` sign-in
+  (`/login`), `ANTHROPIC_API_KEY` or cloud-provider variables, or an existing
+  `claude login`, in that order. A `claude` on `PATH` is used when present,
+  otherwise the SDK's bundled binary.
+- **Works**: streaming, tool cards, approvals and questions, `/model`,
+  `/effort`, Claude's permission modes (`/permission`, `Shift+Tab`),
+  `/compact`, `/context`, `/mcp`, `/resume`, `/fork`, double-`Esc` rewind,
+  subagents, background jobs, images, `/btw`, and the USD cost Claude reports.
+- **Not available**: DSH-only commands such as `/tree`, `/preset`,
+  `/provider`, `/workspace`, `/agentview` and `/bg`. One process runs one
+  backend; `/kernel` switches by restarting into a new session.
+
+Details and known limitations: [Claude backend](docs/claude-backend.en.md).
+
+### Experimental: native Codex backend
+
+Run your own Codex through `codex app-server`, sharing its configuration,
+login, instructions, skills, hooks, MCP and native threads:
+
+```sh
+npm install -g @openai/codex@0.160.1
+dsh-tui --backend codex
+dsh-tui --backend codex --resume <thread-id>
+```
+
+Protocol baseline **0.160.1**, minimum **0.144.0**; other versions may show
+drift. `CODEX_EXECUTABLE` selects a binary; `/kernel` remembers the backend.
+`codex resume <id>` can open the same thread after the other writer exits.
+This is not `migrate codex`, which imports history into DSH.
+With native credentials, a writer conflict for an idle thread retained by the
+official background server triggers a reconnection to that server. Managed
+subscription credentials and `/channel` connections use private app-server processes.
+
+Streaming/tool cards, approvals, questions, steer/queue/interrupt, model and
+effort controls, Plan, `/review`, `/diff`, `/usage`, `/init`, skills and MCP
+share the existing UI. **Shift+Tab only toggles Plan**, keeping its underlying
+permission preset; Full Access requires an explicit choice. Existing Codex
+settings are respected, not overwritten with defaults. `/login` offers
+ChatGPT OAuth, a device code or an API key (the last writes to Codex’s own
+credential store). Relay `/channel` connections take precedence; managed
+subscription tokens are only injected on first-party routes. dsh-TUI does
+not write `~/.codex/config.toml` or log out your native Codex account.
+
+TPS includes hidden reasoning time and excludes tool execution time. Live
+text estimates are corrected when Codex reports output token usage.
+
+Native browsing/archive, fork/conversation rewind, paged history, images,
+subagents, polled background terminals, goals and `/btw`/`/recap` use the
+existing surfaces. `/logout` removes only the matching dsh-auth credential;
+already-loaded managed tokens require a normal restart, not native logout.
+The real 0.160.1 app-server passed nine credential-free offline checks and eight
+daemon-resume checks, with no model turn or charge; real subscription login, credentialed model calls
+and real-TTY interaction were not run. Only Codex identification/title
+changes automatically, not palette or companion.
+Using ChatGPT subscription tokens in third-party clients is subject to
+OpenAI’s terms. Full instructions and current boundaries:
+[Codex backend](docs/codex-backend.en.md).
+
 ## Keybindings & Mouse
 
-`Enter` send · `Tab` complete · `Ctrl+Enter` interrupt and send · `Alt+Up` recall the last message · `Esc` dismiss, double-`Esc` rewinds · `Ctrl+B` side panel · `Ctrl+O` details · `Ctrl+R` history (`↑`/`↓` and `Ctrl+R` are scoped to the current project) · `Ctrl+V` paste · `Ctrl+Shift+E` fullscreen draft editor · `?` shortcuts · `←` background the session.
+`Enter` send · `Tab` complete · `Ctrl+Enter` interrupt and send · `Alt+Up` recall the last message · `Esc` dismiss, double-`Esc` rewinds · `Ctrl+B` side panel · `Ctrl+O` details · `Ctrl+R` history (`↑`/`↓` and `Ctrl+R` are scoped to the current project) · `Ctrl+V` paste · `Ctrl+Shift+E` fullscreen draft editor · `?` shortcuts · `←` open the session manager (DSH backgrounds the current session first).
 
-While the model is working: `Enter` steers, `Tab` queues a follow-up, `Ctrl+Enter` interrupts and sends.
+While the model is working: `Enter` steers, `Tab` queues a follow-up, `Ctrl+Enter` interrupts and sends. Input that names a command is still a command — with or without arguments — so `/model` or `/new` reach their own gate (and the `/` overlay sinks the commands that affect the running conversation) instead of silently becoming an interruption; only text that is not a command — and a direct skill gesture such as `/skill-name …` — steers.
 
 On native Windows, fragmented Win32 input records are reassembled across short input delays instead of appearing as numeric protocol text. The platform check only reports that this machine might run the private mode (win32-input-mode); a bare `ESC[` fragment is held only after one record has actually been decoded, while a fragment whose own shape is already record-specific holds on its own (which is how even the first record can survive a split). Windows terminals that never enter the mode (mintty, GitBash) therefore keep the classic VT path: a lone `Esc` keeps its normal response time, and a letter typed after a timed-out `ESC[` is not swallowed.
 
@@ -197,7 +273,7 @@ Mouse (fullscreen): drag to select and copy, double/triple click to select a wor
 
 File paths in prose can open the file-action menu; automatic detection does not extract a path from inside a slash-delimited token such as `working/idle/needs-input` or a date such as `2024/01/15`.
 
-**Pasting**: native and bracketed paste keeps ordinary text and newlines, and never submits itself on arrival. On Windows terminals that deliver a paste as win32-input-mode key records, the residue is stripped at the entry point (a multi-line paste no longer leaves stray `_`) and pasted CRLF collapses to a single newline; genuine underscores and bracketed-paste text are untouched.
+**Pasting**: native and bracketed paste keeps ordinary text and newlines, and never submits itself on arrival. On Windows terminals that deliver a paste as win32-input-mode key records, a record stream leaked into the payload is decoded back into the characters its `Uc` field encodes — newlines included — so the composer's line count matches what was pasted; only records with no character meaning are stripped (a multi-line paste no longer leaves stray `_`), and a complete record is always consumed before an ESC-less tail, so no payload character is deleted along with an orphan escape. Pasted CRLF collapses to a single newline; genuine underscores and bracketed-paste text are untouched.
 
 **Dropped files**: a native Windows desktop drop (Windows Terminal / OpenConsole) arrives as an OSC 8 hyperlink; the parser restores its `file://` URI to a decoded local path before paste hygiene runs, so the `]8;id=…;` parameter bytes never reach the draft. Image paths enter the existing image staging pipeline; other files are inserted as a referenceable path (a path containing whitespace arrives in the composer's quoted `"…"` single-token form). Only `file://` URIs are restored, and it is fail-closed: a remote authority/UNC, a payload carrying several distinct URIs, or a URI that carries several tokens is refused and stays literal text rather than guessed.
 
@@ -207,11 +283,15 @@ Full reference: [Interaction and commands](docs/interaction.en.md).
 
 `/resume` · `/home` · `/agentview` · `/bg` · `⌸` open the same session manager: workspace rail, live state, filter, ★ pins. Also `/model` `/new` `/compact` `/export` `/btw` `/tree` `/fork` `/rewind` `/settings` `/setup` `/status` `/cost` `/jobs` `/skills` `/mcp` `/provider` `/auth` `/login` `/update`.
 
+In `/provider`'s model list, focus a model and press `Tab` to edit its context window, max output tokens, reasoning efforts, and image input capability.
+
 The session manager paints the last successful list immediately while it checks the persistence store for changes. Titles that require a deeper log scan appear first with a fallback name and update in place when recovery finishes.
 Removing a workspace registration keeps its sessions accessible under a "History only" directory in the rail.
 History-only directories offer edit and new-session actions; rename and remove are available for registered workspaces.
 
-**Background sessions**: `/bg` or `←` on an empty prompt; `Esc` returns. They run in this process and stop when the TUI exits. Logs survive.
+**Background jobs**: card headers open the focused task panel. Click the card body or use `Ctrl+O` to toggle the command between its first statement and full script. Commands and output use separate colored edges with `❯` (`>` on Windows) and `≡` on their first rows; output always stays at the latest two visible rows. `/jobs` and the side panel keep the full output scrollable, while `e` toggles the focused command. Consecutive blank script lines collapse to one.
+
+**Background sessions**: On the DSH backend, `/bg` or `←` on an empty prompt backgrounds the current session and opens the session manager; `Esc` returns to it. Background sessions run in this process and stop when the TUI exits. Logs survive. On Claude/Codex, those entries open the session manager without backgrounding the session.
 
 Full commands: [Interaction and commands](docs/interaction.en.md).
 

package/bin/dsh-tui.js

@@ -62,6 +62,8 @@ const ownPackage = readJson(join(ownDir, 'package.json'))
 const ownVersion = ownPackage?.name === '@deepseek-harness-tui/dsh-tui' ? ownPackage.version : undefined
 const PACKAGE = '@deepseek-harness-tui/dsh-tui'
 const PROFILE = 'dsh-tui'
+// Kept local so the launcher also works without compiled modules.
+const KERNEL_IDS = ['dsh', 'claude', 'codex']
 
 // 随包用户手册（guide/，见 scripts/build-guide.mjs）：交给 dsh 当内核
 // dsh-skill-filesystem 的随包技能根（rank 600 的 bundledSkillDir 默认取这个
@@ -464,6 +466,7 @@ const MSG = {
       `Options:\n` +
       `  --resume [id]          Resume the last (or the given) session\n` +
       `  -c, --continue         Same as --resume\n` +
+      `  --backend <id>         Agent backend: dsh | claude | codex (claude, codex: experimental)\n` +
       `  -- <prompt...>        Treat the remaining arguments as literal prompt text\n` +
       `  <path|url>             Open with the given workspace target\n\n` +
       `Leading DSH options (e.g. --dump-config, --patch <path>) are forwarded unchanged.\n` +
@@ -481,6 +484,7 @@ const MSG = {
       `选项：\n` +
       `  --resume [id]          恢复上次（或指定 id 的）会话\n` +
       `  -c, --continue         同 --resume\n` +
+      `  --backend <id>         Agent 后端：dsh | claude | codex（claude、codex 为实验性）\n` +
       `  -- <提示词...>         将剩余参数作为字面提示词\n` +
       `  <路径|URL>             以指定工作区目标启动\n\n` +
       `前置 DSH 选项（如 --dump-config、--patch <路径>）原样转发。\n` +
@@ -646,8 +650,7 @@ const runDoctorChecks = () => {
   return { hardFailure, lines }
 }
 // ─── safe 会话支撑（清单解析与报告渲染，交互/非交互共用）──────────────────────
-// 保护包：组合层模板与 TUI 本体，不进入卸载候选。两维度分类是 PR② 卸载
-// 功能将复用的唯一分类规则，不得合并简化（spec §6.1）。
+// Packages that profile repair and rescue must never remove.
 const PROTECTED_PLUGINS = new Set(['@deepseek-ai/dsh-base', PACKAGE])
 // dir 参数供救援 profile 复用同一套解析规则（两处 manifest 契约不许分叉）。
 const readProfileInventory = (dir = profileDir) => {
@@ -738,7 +741,7 @@ const forwardExit = child => {
 // 统一表示子进程结局；不在此处做任何退出决定——退出权在调用者（首启结算
 // 或 safe 菜单）。Windows 经 cmd()/shell:true 启动（见 cmd 注释），壳层
 // 观察到的 signal 不保证等同内部 dsh 的中断语义：判定一律只看数值 code，
-// 不从数值反推信号（spec §5.1）。
+// Do not infer a signal from the numeric exit code.
 const startDshSession = (dshArgs, profile = PROFILE, env = process.env) =>
   new Promise(resolve => {
     const child = spawn(...cmd('dsh', ['--profile', profile, ...dshArgs]), {
@@ -766,19 +769,76 @@ const rescueEnv = () => {
   return env
 }
 
+// ─── 最后运行记录 ────────────────────────────────────────────────────────────
+// TUI 把 {backendId,sessionId,cwd,attemptId} 写进 ~/.dsh-tui/last-run.json
+// （boot 写一次，退出时刷新，见 src/update.ts 的 writeLastRunRecord）。
+// 内核切换后本进程的 env 仍是原内核，安全模式重试若按 env 去读 resume.txt
+// 或其他后端偏好，会回到原内核，甚至拿 DSH 的会话 id 跨后端恢复；所以
+// 本次启动之后写下的记录优先。
+const readLastRunRecord = () => {
+  try {
+    const parsed = JSON.parse(readFileSync(join(homedir(), '.dsh-tui', 'last-run.json'), 'utf8'))
+    if (parsed === null || typeof parsed !== 'object') return undefined
+    if (!KERNEL_IDS.includes(parsed.backendId)) return undefined
+    if (typeof parsed.sessionId !== 'string' || typeof parsed.cwd !== 'string' || typeof parsed.attemptId !== 'string') return undefined
+    if (typeof parsed.updatedAt !== 'number' || !Number.isFinite(parsed.updatedAt)) return undefined
+    return parsed
+  } catch {
+    return undefined
+  }
+}
+// 记录 → 重试 env：DSH_TUI_BACKEND 与一次性的 DSH_TUI_BACKEND_HANDOFF（后者
+// 压过 Config 行）都设成记录里的内核；记录有可恢复的会话 id 才设
+// DSH_TUI_RESUME_SESSION，否则删掉继承来的值，在该内核上冷启动。
+const envFromLastRun = record => {
+  const env = { ...process.env }
+  env.DSH_TUI_BACKEND = record.backendId
+  env.DSH_TUI_BACKEND_HANDOFF = record.backendId
+  if (typeof record.sessionId === 'string' && record.sessionId.trim() !== '') {
+    env.DSH_TUI_RESUME_SESSION = record.sessionId
+  } else {
+    delete env.DSH_TUI_RESUME_SESSION
+  }
+  return env
+}
+// 首次 spawn 前记下的时刻：updatedAt 不早于它的记录是本次启动的 TUI 写的，
+// 更早的是上一次启动留下的。
+let launchChain = null
+const noteLaunchChain = () => {
+  launchChain = { startedAt: Date.now() }
+}
+
+// 非 DSH 内核的上次会话来自各自 backends/<id>/prefs.json 的 lastSession。
+const readBackendLastSession = backendId => {
+  try {
+    const prefs = JSON.parse(readFileSync(join(homedir(), '.dsh-tui', 'backends', backendId, 'prefs.json'), 'utf8'))
+    return typeof prefs?.lastSession === 'string' ? prefs.lastSession.trim() : ''
+  } catch {
+    return ''
+  }
+}
 // 安全模式「重试正常启动」的环境（菜单选项 1，首启 fallback 与 `safe` 共用）：
-// 崩溃往往发生在 TUI 的退出漏斗之前，此时 `~/.dsh-tui/resume.txt` 是"用户上
-// 一刻在哪个会话"的唯一线索（TUI 侧崩溃分支也会写它，见
-// src/dsh-adapter/plugin.ts 的退出漏斗）。不带这个变量重试等于开一个新的空会话
-// ——正是「会话丢了」的观感。已经显式设了该变量（用户自己 `--resume`）则不覆盖；
-// 指针缺失/不可读时保持冷启动语义。
+//   1. 本次启动之后写下的最后运行记录：崩溃时实际在跑的内核与会话，压过
+//      env 里的 --resume（内核切换是用户更新的选择）。
+//   2. 没有这样的记录（崩得太早，或旧版本不写）：env 里已有
+//      DSH_TUI_RESUME_SESSION 就照用；否则按 env 的后端读它的上次会话
+//      （resume.txt 或对应后端偏好文件），读不到就冷启动。
 const resumeEnvForRetry = () => {
+  const chain = launchChain
+  const record = readLastRunRecord()
+  if (record !== undefined && chain !== null && record.updatedAt >= chain.startedAt) {
+    return envFromLastRun(record)
+  }
   if (process.env.DSH_TUI_RESUME_SESSION !== undefined) return process.env
   let target = ''
-  try {
-    target = readFileSync(join(homedir(), '.dsh-tui', 'resume.txt'), 'utf8').trim()
-  } catch {
-    // 没有历史会话可恢复——静默冷启动。
+  if (KERNEL_IDS.includes(process.env.DSH_TUI_BACKEND) && process.env.DSH_TUI_BACKEND !== 'dsh') {
+    target = readBackendLastSession(process.env.DSH_TUI_BACKEND)
+  } else {
+    try {
+      target = readFileSync(join(homedir(), '.dsh-tui', 'resume.txt'), 'utf8').trim()
+    } catch {
+      // 没有历史会话可恢复——静默冷启动。
+    }
   }
   return target === '' ? process.env : { ...process.env, DSH_TUI_RESUME_SESSION: target }
 }
@@ -789,7 +849,7 @@ const isInteractive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY)
 
 // 子进程异常退出后终端可能停在脏状态（alt-screen/鼠标/隐藏光标——清理
 // 责任在 TUI 的 ink 退出路径，不保证完成）。进入询问/菜单前做最小恢复，
-// 仅为让后续界面可读，不承诺完整复原（spec §6.2）。
+// Reset the screen and mouse modes before prompting after a child exit.
 const restoreTerminalMinimal = () => {
   process.stdout.write('\x1b[?1049l\x1b[?1000l\x1b[?1006l\x1b[?25h')
 }
@@ -803,7 +863,7 @@ const askSafeEntry = async pendingExitCode => {
   // 与 runSafeSession.askChoice 同款 close 竞速：接口 close（上方 SIGINT
   // 处理器主动 close，或 TTY 的 Ctrl+D/EOF）时 question 可能永不结算——
   // 裸 await 会让 fallback 询问挂死（PTY 实测 Ctrl+C 下顶层 await 以退出
-  // 码 13 异常中止）。close 一律按取消，对齐 spec §6.2：Ctrl+C/Ctrl+D/EOF
+  // 码 13 异常中止）。close 一律按取消：Ctrl+C/Ctrl+D/EOF
   // 等价拒绝（按原退出码收束）。
   let answer
   try {
@@ -907,7 +967,7 @@ const runSafeSession = async ({ pendingExitCode = 0, retryDsh, extraLines, rescu
       // cold start = 手动入口无已规范化 args，按空参数冷启动。
       const replay = typeof retryDsh === 'function'
       console.log(L.retry + (replay ? L.replaySource : L.coldStartSource))
-      // 两来源共用 profileReady 前置（spec §4：重试不得隐式自举）。
+      // Both retry paths require a ready profile; neither bootstraps it.
       if (!profileReady()) { console.error(msg('safeListUnreadable')(msg('safeGuideLabels').notReadyReason)); continue }
       state.handingOff = true // 主动交接：此刻起的中断不算用户取消
       const settled = settleRetry(replay ? await retryDsh() : await startDshSession([]))
@@ -1223,7 +1283,7 @@ const checkProfileAlignment = installedVersion => {
 // ─── 子命令：safe（安全模式入口，两种角色同一段代码）──────────────────────────
 // 零 lib 依赖、不委托、不自举（对齐 doctor 的依赖边界，而非 update 的
 // profile-lib 路径）：profile 损坏时它必须仍可达。控制面只读；重试与
-// 修复动作语义见 safe 会话实现（spec §4/§5）。
+// Recovery and retry behavior lives in runSafeSession.
 // `safe --rescue` 是同一个救援动作的显式入口（不是新动作）：交互终端里
 // 等价于菜单选项 5（门禁 → 创建/复用 → 干净启动），非交互终端里只做
 // 门禁 + 创建/复用并报告结论（没有终端可交接时不启动 TUI），以便脚本与
@@ -1376,6 +1436,11 @@ if (!runningInsideProfile && ownVersion !== undefined && process.env.DSH_TUI_NO_
   const hostArgs = []
   const args = []
   const argv = process.argv.slice(2)
+  // Resume flags in command-line order: an explicit id, or `null` for a bare
+  // flag. Replayed after the whole line is read, with the original
+  // "each flag sets it, the last one wins" semantics — only a bare flag's
+  // source depends on the backend, which may be named after it.
+  const resumeFlags = []
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === '--') {
@@ -1396,6 +1461,18 @@ if (!runningInsideProfile && ownVersion !== undefined && process.env.DSH_TUI_NO_
         continue
       }
     }
+    // `--backend <id>`: which agent backend the app opens its session with
+    // (the row reads DSH_TUI_BACKEND; absent falls back to kernel.json, then dsh).
+    if (a === '--backend' || a.startsWith('--backend=')) {
+      const backend = a.startsWith('--backend=') ? a.slice('--backend='.length).trim() : (argv[i + 1] ?? '').trim()
+      if (a === '--backend' && argv[i + 1] !== undefined) i += 1
+      if (!KERNEL_IDS.includes(backend)) {
+        console.error(lang === 'zh' ? `未知的 --backend：${backend}（可选 ${KERNEL_IDS.join(' / ')}）` : `Unknown --backend: ${backend} (expected ${KERNEL_IDS.join(' or ')})`)
+        process.exit(2)
+      }
+      process.env.DSH_TUI_BACKEND = backend
+      continue
+    }
     if (a === '--resume' || a === '-c' || a === '--continue' || a.startsWith('--resume=')) {
       let sessionId = ''
       if (a.startsWith('--resume=')) {
@@ -1403,8 +1480,8 @@ if (!runningInsideProfile && ownVersion !== undefined && process.env.DSH_TUI_NO_
       } else if (a === '--resume' && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) {
         sessionId = argv[++i].trim()
       }
-      if (!sessionId) sessionId = readLastResumeTarget()
-      if (sessionId) setResumeEnv(sessionId)
+      // 裸 --resume：等整条命令行读完再决定（`--backend` 可能在它后面）。
+      resumeFlags.push(sessionId || null)
     } else if (
       process.env.DSH_TUI_WORKSPACE_TARGET === undefined
       && !a.startsWith('-')
@@ -1416,6 +1493,13 @@ if (!runningInsideProfile && ownVersion !== undefined && process.env.DSH_TUI_NO_
     }
   }
 
+  // 按出现顺序重放 --resume：裸 --resume 时 DSH 读 resume.txt（契约不变），
+  // 其他内核读各自的上次会话。
+  for (const flag of resumeFlags) {
+    const sessionId = flag ?? (KERNEL_IDS.includes(process.env.DSH_TUI_BACKEND) && process.env.DSH_TUI_BACKEND !== 'dsh' ? readBackendLastSession(process.env.DSH_TUI_BACKEND) : readLastResumeTarget())
+    if (sessionId) setResumeEnv(sessionId)
+  }
+
   // 启动：被委托场景下本副本自己的版本即对齐诊断所见的启动器代际。
   if (process.env.DSH_TUI_LAUNCHER_VERSION === undefined && ownVersion !== undefined) {
     process.env.DSH_TUI_LAUNCHER_VERSION = ownVersion
@@ -1424,5 +1508,7 @@ if (!runningInsideProfile && ownVersion !== undefined && process.env.DSH_TUI_NO_
   // DSH consumes its own --; only the app tail belongs behind it. Preserve
   // the app-level separator too, and replay this same argv on a safe retry.
   const firstArgs = [...hostArgs, ...(args.length > 0 ? ['--', ...args] : [])]
+  // 必须在首次 spawn 之前：本次启动的 TUI 写的记录都晚于这个时刻。
+  noteLaunchChain()
   settleFirstResult(await startDshSession(firstArgs), firstArgs)
 }

package/cordis.patch.yml

@@ -509,6 +509,8 @@
         preset: !!js process.env.DSH_TUI_PRESET ?? undefined
         workspace: !!js process.env.DSH_TUI_WORKSPACE_TARGET ?? undefined
         sessionId: !!js process.env.DSH_TUI_RESUME_SESSION ?? undefined
+        # Agent backend (`dsh-tui --backend claude` → DSH_TUI_BACKEND); unset → /kernel's remembered pick, else dsh.
+        backend: !!js process.env.DSH_TUI_BACKEND || undefined
 
     # Live working-line data source (thinking copy / running tool / turn
     # summary). Mounted through @deepseek-harness-tui/dsh-tui's own

package/cordis.yml

@@ -91,6 +91,8 @@
     #  feeds the chosen session id through this env var (see
     #  src/sessionHistory.ts for the launcher contract).
     sessionId: !!js process.env.DSH_TUI_RESUME_SESSION ?? undefined
+    # Agent backend (`dsh-tui --backend claude` → DSH_TUI_BACKEND); unset → /kernel's remembered pick, else dsh.
+    backend: !!js process.env.DSH_TUI_BACKEND || undefined
     workspace: !!js process.env.DSH_TUI_WORKSPACE_TARGET ?? undefined
 
 # The DeepSeek adapter. Shipped default: full thinking at max effort.

package/guide/dsh-tui-guide/SKILL.md

@@ -5,14 +5,14 @@ description: Use when the user asks about dsh-tui itself (usage, shortcuts, conf
 
 # dsh-tui 用户手册（索引）
 
-用户手册全文就在**本文件所在目录**——`skill` 工具返回的 `resourceBase`。共 8 篇，
+用户手册全文就在**本文件所在目录**——`skill` 工具返回的 `resourceBase`。共 10 篇，
 每篇中英各一份：中文文件名无后缀，英文加 `.en.md`。拿不到绝对路径时，用
 `glob` 在 dsh-tui 包里搜 `guide/dsh-tui-guide`。
 
 ## 怎么用
 
 1. **跟用户同语言**：中文提问读无后缀文件，英文提问读加后缀的那份；回答也用同一种语言。
-2. **先定位再读**：16 个文件合计约 290 KB，整篇读既慢又挤上下文。先 `grep` 关键词拿到命中行，
+2. **先定位再读**：20 个文件按主题分篇，整篇读既慢又挤上下文。先 `grep` 关键词拿到命中行，
    再用 `read` 带 `offset`/`limit` 只展开需要的那几段。
 3. **一次一到两篇**：按下面的路由表挑最贴近的；跨主题时再补第二篇。
 4. **给出处**：回答末尾写清来源（文件名 + 小节标题），用户能直接翻回去核对。
@@ -26,6 +26,8 @@ description: Use when the user asks about dsh-tui itself (usage, shortcuts, conf
 | 日常使用、键位、斜杠命令、会话与工作流、设置 | `user-guide.md` |
 | 输入框、鼠标、选中复制、粘贴、图片、问卷与审批 | `interaction.md` |
 | 配置覆盖层、TUI 开关、agent preset、模型路由、MCP | `configuration.md` |
+| Claude 后端：启用、登录、与 DSH 的差异、已知限制 | `claude-backend.md` |
+| Codex 后端：安装、登录、渠道、Plan、会话与原生能力 | `codex-backend.md` |
 | 主题、配色、自动检测、自定义主题 | `themes.md` |
 | 从 Claude Code / Codex / OMP / zcode / Grok 迁移会话 | `migrate.md` |
 | VS Code 集成、扩展、IDE 选区 | `vscode.md` |

package/guide/dsh-tui-guide/claude-backend.en.md

@@ -0,0 +1,203 @@
+# Claude backend (experimental)
+
+[Documentation index](README.md) · [中文](claude-backend.md)
+
+dsh-TUI can run its session on the Claude Agent backend instead of the DeepSeek
+Harness agent: the same interface, driving the Claude Code CLI through the Claude
+Agent SDK. Your project's `CLAUDE.md`, settings, hooks, MCP servers and plugins
+load the way the CLI loads them. The backend is still experimental; the
+implementation is described in [Agent backends](agent-backend-design.md)
+(Chinese).
+
+## Enabling it
+
+You need:
+
+- The Claude Agent SDK. It is an optional dependency and is not installed by
+  default. The easiest install: open the kernel picker (the launchpad "Kernel"
+  entry or `/kernel`) and press Enter on the dim Claude row — the wizard
+  locates the profile directory and installs the pinned SDK via pnpm; the row
+  lights up when it finishes (standalone builds and profile-less launches get
+  manual instructions). The manual equivalent, run once in the dsh-tui profile
+  directory (`~/.dsh/profiles/dsh-tui`, or `$DSH_HOME/profiles/dsh-tui` when
+  `DSH_HOME` is set):
+
+  ```sh
+  cd ~/.dsh/profiles/dsh-tui && pnpm add @anthropic-ai/claude-agent-sdk@0.3.287
+  ```
+
+- A Claude credential; see "Signing in" below.
+- The `claude` command is optional: a working `claude` on `PATH` is used (same
+  version and session store as the CLI you already use), otherwise the SDK's
+  bundled binary.
+
+To pick the backend, use any of:
+
+- The launchpad's Kernel entry, the kernel block in its bottom-right corner, or
+  `/kernel` inside a session, which open the kernel picker. Picking the other
+  kernel remembers the choice (`~/.dsh-tui/kernel.json`) and restarts dsh-TUI
+  into a new session on it; the old session stays in `/resume`. A running turn
+  blocks the switch. Without the SDK or a credential the picker marks Claude as
+  *Not installed* or *Not signed in*.
+- `dsh-tui --backend claude` (this launch only).
+- `backend: claude` in the dsh-tui config row.
+
+An explicit `--backend` or config value wins over the picker's remembered choice.
+
+## Signing in
+
+Credentials are used in this order; `/login` shows which one the session runs on:
+
+1. The active channel in `/channel` (see
+   [Channel profiles](interaction.en.md#channel-profiles-channel-claude-only)).
+2. Your dsh-auth `anthropic` sign-in, the same OAuth `/provider` offers. `/login`
+   in a Claude session opens it directly and reconnects the session afterwards
+   (after the running turn, if there is one). While it is used,
+   `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` from your environment are kept
+   away from the CLI so an old key cannot override the sign-in you just made.
+3. `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` or cloud-provider routing
+   variables in your environment.
+4. Your existing `claude login`.
+
+The subscription sign-in is used only for Anthropic's own API. When
+`ANTHROPIC_BASE_URL` (in your environment or a Claude settings `env`) points
+anywhere other than `https://api.anthropic.com`, or a Unix socket, a cloud
+provider or gateway route, or an `apiKeyHelper` is configured, dsh-TUI does not
+use the subscription token, passes your environment through untouched, and
+`/login` names the route instead. A token about to expire is refreshed before
+the CLI starts; if the CLI rejects it mid-session, dsh-TUI refreshes it and
+reconnects the same session once, then asks you to `/login`. Token material is
+never logged.
+
+## Compared with the DSH backend
+
+Works the same as on DSH: streaming replies, thinking (a token count only when the
+model sends no thinking text), tool cards, `Ctrl+C` cancel, queued messages and
+holding the queue on `Esc`, `/new`, `/status`, `/export`, `!cmd` / `!!cmd`, the IDE selection,
+the git branch in the status line, `/clear` (clears the view only; Claude keeps
+its context).
+
+Works, served by Claude:
+
+| Feature | Notes |
+| --- | --- |
+| `/model` | Claude's own model list, no provider prefix (`/model sonnet`); the choice is remembered for later sessions |
+| `/effort` | The levels the current model declares; none for a model without effort support |
+| `/permission`, `Shift+Tab` | Claude's permission modes, see below |
+| `/compact`, `/context` | Claude's compaction and context report |
+| `/mcp` | Server status; `/mcp reconnect <server>` and `/mcp toggle <server> on\|off`, server names complete |
+| `/cost`, status-line cost | The USD cost Claude reports; hover the cost field for subscription usage (5h / 7d) |
+| `/doctor` | CLI path and version, SDK version, start permission mode, credential and account |
+| `/rename`, `/color` | The title goes into Claude's session list; the accent is stored per session by dsh-TUI |
+| `/btw`, `/recap` | One question over a throwaway copy of the conversation (no tools, one turn, nothing written to the transcript), one model call each; no automatic recap when a session opens |
+| Claude's own slash commands | Listed in completion and sent to Claude as typed; where a name matches a dsh-TUI built-in, the built-in wins |
+| `/channel` | Claude only: model names and connection of a relay channel, see [Channel profiles](interaction.en.md#channel-profiles-channel-claude-only) |
+
+`/init` delegates to Claude's native initialization command. `/logout` only removes the Anthropic login stored by dsh-auth; it does not invoke native Claude logout. A running child may retain the managed token until a normal restart.
+
+Not available (hidden from completion; typing one shows a notice and nothing is
+sent to the model): `/tree`, `/agentview`, `/bg`, `/home`, `/workspace`,
+`/preset`, `/provider`, `/balance`, `/config`, `/reload`,
+`/setup`, `/migrate`, `/skills`, `/plugins`, `/hooks`, `/add-dir`,
+`/goal` (Claude has no goal capability). Other commands the DSH composition
+registers (such as `/plan`) do not appear either.
+
+Startup still lands on the launchpad; the first-run guide and the workspace home
+are DSH-only. A launch with a resume target goes straight into the session.
+
+## Approvals and questions
+
+- Tool approvals use the same panel as DSH: allow once, allow always, reject.
+  *Allow always* appears only when the CLI suggests a rule, and its label says
+  what the CLI will remember (for example auto-accepting edits for this session,
+  or a permission rule for this project); the CLI stores it, dsh-TUI writes no
+  settings file. With the focus on the reject row (`↓` / `Tab`) you can type a
+  reason to send with the rejection; *allow always* then has no digit shortcut,
+  so move to it and press `Enter`.
+- Questions from the model (`AskUserQuestion`) use the questionnaire. A plan from
+  plan mode opens the plan review: approve with auto-accepted edits, approve with
+  per-edit approval, or keep planning with feedback.
+- An MCP server asking for input uses the questionnaire too: one question per
+  form field, checked against the field (an invalid answer is asked again with the
+  reason), then *Send* or *Decline*. A server that needs a browser step shows its
+  link.
+- When the model declines a request and a fallback model is configured, a
+  question offers retrying on it.
+- `Esc` cancels any of these.
+
+## Permission modes
+
+`/permission` lists Claude's modes: `default` (ask each time), `acceptEdits`
+(auto-accept edits), `plan` (read-only planning), `bypassPermissions` (skip every
+check), plus `auto` where the model supports it. `Shift+Tab` cycles default →
+acceptEdits → plan (→ auto) and never reaches `bypassPermissions`; that one can
+only be picked explicitly in `/permission`.
+
+The `/permission` pick is remembered (`~/.dsh-tui/backends/claude/prefs.json`) and
+the next session starts in it, except `bypassPermissions`: it lasts for the current
+session only, a new session says once that it was not carried over, and you turn it
+on again with `/permission` when you want it. Start-mode precedence: the
+`DSH_TUI_CLAUDE_PERMISSION_MODE` environment variable (the only way to start in
+bypass) > the remembered pick > Claude settings > `default`. A
+`defaultMode: bypassPermissions` in Claude settings is downgraded to `default` with
+a notice, so a cloned repository cannot silently switch off every check.
+
+## Sessions
+
+- `/resume` opens the session browser on your Claude sessions, the current project
+  by default, all projects on request. Sessions dsh-TUI created are listed too
+  (Claude Code's own `/resume` picker hides them; open them there with
+  `claude --resume <id>`). `Enter` resumes (history is replayed, then the
+  conversation continues), `Ctrl+R` renames, `Ctrl+D` deletes; the open session and
+  one another dsh-TUI terminal is using cannot be deleted. Pins are kept per
+  backend.
+- From a shell: `dsh-tui --backend claude --resume <id>`; without an id it resumes
+  the last Claude session this install used. dsh-TUI prints that command on exit.
+  A session another dsh-TUI terminal has open is refused, and a `--resume` that
+  cannot open fails instead of starting a fresh session. The short session id in
+  the status line is the id `--resume` takes.
+- `/fork` writes a copy you can resume later; the open session is untouched.
+- Double-`Esc` rewinds to an earlier prompt: the conversation (continuing in a
+  copy cut just before it, with the prompt back in the input), the files Claude
+  edited since (restored from Claude's file checkpoints, previewed before you
+  confirm), or both.
+- When Claude itself resets the conversation (leaving plan mode with *clear
+  context*), the view, subagents and background jobs are cleared with a notice and
+  the session continues under the new id Claude gives it.
+- A session resumed after a compaction shows *load earlier* at the top; each use
+  brings back one compacted stretch, read-only from Claude's own transcript file.
+  Long sessions fold old rows to bound memory, and the same entry restores them.
+
+## Subagents and background jobs
+
+- Each `Agent` delegation is a subagent card in the transcript; its text, tool
+  calls and token count go into the card, never into the main conversation.
+  `/agents` lists them, `Ctrl+A` opens the subagent dashboard and its detail view,
+  where a running one can be stopped.
+- A command Claude runs in the background (`Bash` with `run_in_background`, or a
+  running command moved to the background) is a job card with the status-line job
+  marker; `/jobs` lists them, and `k` twice stops one. While on screen, the card and
+  the panel show the tail of the job's output file (read-only, the last 64 KiB, at
+  most once a second).
+- Interrupting a turn never stops a job. A job or subagent Claude stops reporting
+  shows as *status unknown*.
+
+## Images
+
+Paste an image or `@`-mention an image file (PNG, JPEG, GIF, WebP) and it is sent
+with the message. Limits: 5 MiB, 2000 px per side and 4 megapixels per image; 20
+images and 20 MiB per message. Oversized images are scaled down when sharp is
+available. Staged images are held in memory only. Resumed sessions show the images
+their prompts carried.
+
+## Known limitations
+
+- One dsh-TUI process runs one backend; switching restarts through `/kernel`.
+- In a Claude session the side panel's workspace panel reports it is unsupported
+  and the trajectory panel stays empty.
+- No `/add-dir`; the refusal dialog offers only *Retry* and *Cancel*; an MCP
+  request that needs a browser step does not open the browser for you.
+- dsh-TUI cannot tell when the same session is also open in a plain
+  `claude --resume`.
+- Using a claude.ai subscription sign-in in a third-party client is subject to
+  Anthropic's terms; use an API key if that is a concern.