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

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

@@ -0,0 +1,161 @@
+# Claude 后端（实验性）
+
+[文档索引](README.md) · [English](claude-backend.en.md)
+
+dsh-TUI 可以把会话跑在 Claude Agent 后端上，而不是 DeepSeek Harness 智能体：界面
+还是同一个，背后由 Claude Agent SDK 驱动 Claude Code CLI。项目里的 `CLAUDE.md`、
+设置、hooks、MCP 服务器和插件按 CLI 自己的方式加载。这个后端仍是实验性的，实现
+细节见[多后端架构](agent-backend-design.md)。
+
+## 启用
+
+需要：
+
+- Claude Agent SDK。它是可选依赖，默认不装。最省事的装法：打开内核选择器（启动页
+  「内核」或 `/kernel`），对未安装的 Claude 行按 Enter，按引导一键安装——dsh-TUI
+  自己定位 profile 目录，用 pnpm 装锁定版本的 SDK，装完该行即变亮可选（独立构建
+  与无 profile 的启动给手动指引）。手动等价形式，在 dsh-tui 的 profile 目录（默认
+  `~/.dsh/profiles/dsh-tui`，设置了 `DSH_HOME` 时是 `$DSH_HOME/profiles/dsh-tui`）
+  执行一次：
+
+  ```sh
+  cd ~/.dsh/profiles/dsh-tui && pnpm add @anthropic-ai/claude-agent-sdk@0.3.287
+  ```
+
+- 一份 Claude 凭据，见下面的「登录」。
+- `claude` 命令不是必需的：`PATH` 上有能运行的 `claude` 就用它（与你平时用的 CLI 同版本、
+  同一个会话库），否则用 SDK 自带的二进制。
+
+选择后端，任选一种：
+
+- 启动页的「内核」入口、右下角的内核区，或在会话里输入 `/kernel`，打开内核选择器。
+  选中另一个内核后 dsh-TUI 记住选择（`~/.dsh-tui/kernel.json`）并重启，在新内核里开
+  一个新会话；原来的会话仍可在 `/resume` 找到。回合进行中不能切换。SDK 没装或没有
+  凭据时，选择器会把 Claude 标为「未安装」或「未登录」。
+- `dsh-tui --backend claude`（只对这一次启动生效）。
+- 在 dsh-tui 的配置行写 `backend: claude`。
+
+显式的 `--backend` 与配置行优先于选择器记住的选择。
+
+## 登录
+
+按以下顺序选用凭据，`/login` 会显示当前会话用的是哪一种：
+
+1. `/channel` 里激活的渠道（见[渠道档案](interaction.md#渠道档案channel仅-claude)）。
+2. dsh-auth 的 `anthropic` 订阅登录，即 `/provider` 里的同一套 OAuth。在 Claude
+   会话里执行 `/login` 会直接打开它，登录后重连会话（回合进行中则等回合结束）。使用它时
+   不把环境里的 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 交给 CLI，免得旧的 key
+   盖过你刚做的登录。
+3. 环境里的 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`，或云厂商路由的环境变量。
+4. 本机已有的 `claude login`。
+
+订阅登录只用于 Anthropic 官方 API。`ANTHROPIC_BASE_URL`（环境变量或 Claude 设置的
+`env`）指向 `https://api.anthropic.com` 以外的地址，或配置了 Unix 套接字、云厂商或网关
+路由、`apiKeyHelper` 时，dsh-TUI 不使用订阅令牌，环境原样交给 CLI，`/login` 显示当前
+路由。令牌快过期时在启动 CLI 前刷新；会话中被 CLI 拒绝时刷新一次并以同一会话重连，
+还不行就提示你 `/login`。令牌不会写进日志。
+
+## 和 DSH 后端相比
+
+可用，行为与 DSH 一致：流式回复、思考（模型不给正文时只显示 token 数）、工具卡、
+`Ctrl+C` 中断、排队消息与 `Esc` 暂存、`/new`、`/status`、`/export`、`!cmd` / `!!cmd`、
+IDE 选区、状态栏的 git 分支、`/clear`（只清屏，Claude 保留上下文）。
+
+可用，但由 Claude 提供：
+
+| 功能 | 说明 |
+| --- | --- |
+| `/model` | Claude 自己的模型列表，不带 provider 前缀（`/model sonnet`）；选择会记住，用于之后的新会话 |
+| `/effort` | 当前模型声明的档位；不支持 effort 的模型没有可选项 |
+| `/permission`、`Shift+Tab` | Claude 的权限模式，见下文 |
+| `/compact`、`/context` | Claude 的压缩与上下文报告 |
+| `/mcp` | 服务器状态；`/mcp reconnect <服务器>`、`/mcp toggle <服务器> on\|off`，服务器名可补全 |
+| `/cost`、状态栏费用 | Claude 上报的美元费用；悬停费用字段可看订阅用量（5 小时 / 7 天） |
+| `/doctor` | CLI 路径与版本、SDK 版本、起始权限模式、凭据与账户 |
+| `/rename`、`/color` | 标题写进 Claude 的会话列表；强调色由 dsh-TUI 按会话保存 |
+| `/btw`、`/recap` | 在对话的一次性副本上问一个问题（无工具、单轮、不写入转录），每次一次模型调用；打开会话时不自动回顾 |
+| Claude 自己的斜杠命令 | 出现在补全里，原样发给 Claude；与 dsh-TUI 内置命令同名的，以内置命令为准 |
+| `/channel` | 仅 Claude：中转渠道的模型名与连接，见[渠道档案](interaction.md#渠道档案channel仅-claude) |
+
+`/init` 委托 Claude 原生初始化命令。`/logout` 只清理 dsh-auth 保存的 Anthropic 登录，不调用 Claude 原生登出；已有进程缓存的托管令牌在正常重启后停止使用。
+
+不可用（不出现在补全里，直接输入会提示不可用，不会发给模型）：`/tree`、`/agentview`、
+`/bg`、`/home`、`/workspace`、`/preset`、`/provider`、`/balance`、`/config`、
+`/reload`、`/setup`、`/migrate`、`/skills`、`/plugins`、`/hooks`、
+`/add-dir`、`/goal`（Claude 没有目标能力）。DSH 组合注册的其他命令（如 `/plan`）也不会出现。
+
+启动时仍先到启动页；首启引导和工作区首页只在 DSH 下出现。带恢复目标的启动直接进入
+会话。
+
+## 审批与提问
+
+- 工具审批用和 DSH 相同的面板：允许一次、始终允许、拒绝。「始终允许」只在 CLI 给出
+  建议时出现，标签写明 CLI 会记住什么（例如本会话自动接受编辑，或本项目的一条权限
+  规则）；记住由 CLI 完成，dsh-TUI 不写任何设置文件。焦点移到「拒绝」行（`↓` / `Tab`）
+  后可以输入拒绝理由，此时「始终允许」没有数字快捷键，移过去按 `Enter`。
+- 模型的提问（`AskUserQuestion`）用问卷面板；计划模式交出的计划打开计划评审：批准并
+  自动接受编辑、批准但逐个确认编辑，或带反馈继续规划。
+- MCP 服务器请求输入时也走问卷：表单每个字段一题，按字段约束校验，无效的回答带原因
+  重问，最后选「发送」或「拒绝」。需要浏览器操作的服务器会给出链接。
+- 模型拒绝请求且配置了回退模型时，会询问是否用回退模型重试。
+- 以上都可以按 `Esc` 取消。
+
+## 权限模式
+
+`/permission` 列出 Claude 的模式：`default`（逐个询问）、`acceptEdits`（自动接受编辑）、
+`plan`（只读规划）、`bypassPermissions`（跳过全部确认），模型支持时还有 `auto`。
+`Shift+Tab` 在 default → acceptEdits → plan（→ auto）之间循环，永远不会进入
+`bypassPermissions`，它只能在 `/permission` 里明确选择。
+
+`/permission` 的选择会记住（`~/.dsh-tui/backends/claude/prefs.json`），下一个会话按它
+启动，`bypassPermissions` 除外：它只在当前会话有效，新会话不会沿用，启动时提示一次，
+需要时再用 `/permission` 打开。起始模式的优先级：环境变量
+`DSH_TUI_CLAUDE_PERMISSION_MODE`（唯一能直接以 bypass 启动的方式）> 记住的选择 >
+Claude 设置 > `default`。Claude 设置里的 `defaultMode: bypassPermissions` 会降为
+`default` 并提示，克隆来的仓库不能悄悄关掉所有确认。
+
+## 会话
+
+- `/resume` 打开会话浏览器，列出你的 Claude 会话，默认显示当前项目，也可以看全部项目。
+  dsh-TUI 创建的会话也在其中（Claude Code 自己的 `/resume` 选择器不显示它们，要用
+  `claude --resume <id>` 打开）。`Enter` 恢复（先回放历史再继续），`Ctrl+R` 重命名，
+  `Ctrl+D` 删除；当前会话和另一个 dsh-TUI 终端正在用的会话不能删。置顶按后端分开保存。
+- 从 shell 恢复：`dsh-tui --backend claude --resume <id>`；不带 id 时恢复本机最近一次
+  用过的 Claude 会话。退出时 dsh-TUI 会打印这条命令。另一个 dsh-TUI 终端已打开的会话会
+  被拒绝；`--resume` 打不开时直接报错，不会改开新会话。状态栏的短会话 id 就是
+  `--resume` 用的 id。
+- `/fork` 写一份之后可以恢复的副本，当前会话不变。
+- 双击 `Esc` 回退到之前的某条提问：回退对话（在截到该提问之前的副本里继续，提问回到
+  输入框）、恢复 Claude 之后改过的文件（用 Claude 的文件检查点，确认前先预览），或两者
+  都做。
+- Claude 自己重置对话时（退出计划模式并选择清空上下文），视图、子代理和后台任务一起清空
+  并提示，会话以 Claude 给的新 id 继续。
+- 压缩过的会话恢复后，顶部有「加载更早消息」，每次找回一段被压缩掉的对话，只读
+  Claude 自己的转录文件。长会话为限制内存会折叠旧行，同一入口也能把它们找回来。
+
+## 子代理与后台任务
+
+- 每次 `Agent` 委派在对话里是一张子代理卡片，子代理的文本、工具调用和 token 数只进
+  卡片，不进主对话。`/agents` 列出全部，`Ctrl+A` 打开子代理面板与详情，可以停止运行中
+  的子代理。
+- Claude 在后台运行的命令（带 `run_in_background` 的 `Bash`，或运行中被转到后台的
+  命令）显示为任务卡并点亮状态栏的任务标记，`/jobs` 列出全部，连按两次 `k` 停止。卡片
+  和面板在屏幕上时显示任务输出文件的末尾（只读最后 64 KiB，每秒最多一次）。
+- 中断回合不会停止后台任务。Claude 不再报告的任务或子代理显示为「状态未知」。
+
+## 图片
+
+粘贴图片或 `@` 引用图片文件（PNG、JPEG、GIF、WebP）即随消息发送。限制：每张最多
+5 MiB、每边最多 2000 像素、最多 400 万像素；每条消息最多 20 张、合计 20 MiB。超出尺寸的
+图片在装有 sharp 时会自动缩小。暂存的图片只放在内存里。恢复的会话会显示提问里带过的
+图片。
+
+## 已知限制
+
+- 一个 dsh-TUI 进程只用一个后端，切换要经 `/kernel` 重启。
+- 侧栏的工作区面板在 Claude 会话下提示不支持，轨迹面板为空。
+- 不支持 `/add-dir`；拒答对话框只有「重试」和「取消」；需要浏览器操作的 MCP 请求不会
+  自动打开浏览器。
+- 同时用普通 `claude --resume` 打开同一个会话，dsh-TUI 察觉不到。
+- 在第三方客户端里使用 claude.ai 订阅登录受 Anthropic 的条款约束；如有顾虑，改用
+  API key。

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

@@ -0,0 +1,297 @@
+# Native Codex backend (experimental)
+
+[Documentation index](README.md) · [中文](codex-backend.md) · [Agent backends](agent-backend-design.md)
+
+dsh-TUI can be a frontend for your local Codex: the same interface, with sessions driven by
+`codex app-server`, not the DSH Agent or a generic OpenAI API adapter. Codex loads its own
+configuration, login, `AGENTS.md`, skills, hooks and MCP servers. Threads are shared with the
+official CLI, with no history migration required. `dsh-tui migrate codex` is different: it
+imports history into **DSH**, rather than opening a native Codex thread.
+
+> This guide describes the development branch, not a released version. The protocol
+> validation baseline is **codex-cli 0.160.1**; the minimum is **0.144.0**. Other versions
+> may show a drift warning; the minimum does not guarantee every advanced API. Controls,
+> lifecycle and advanced features follow the capabilities actually declared by the backend.
+> Protocol/fake-app-server regressions and credential-free offline checks do not prove real
+> ChatGPT login, live model turns or real-TTY behavior; those were not run in this round.
+> The verified scope is listed at the end, with implementation/live evidence in the
+> [progress log](codex-backend-progress.md) (Chinese).
+
+## Install and start
+
+Install dsh-TUI using the [installation guide](getting-started.en.md), then install your own Codex:
+
+```sh
+npm install -g @openai/codex@0.160.1
+codex --version
+dsh-tui --backend codex
+```
+
+- dsh-TUI neither bundles the Codex binary nor requires `@openai/codex-sdk`.
+- Codex is discovered on `PATH`; set `CODEX_EXECUTABLE` to choose an executable. On Windows,
+  npm installations resolve to the real `codex.exe`, not just the launcher wrapper.
+- Select Codex through the launchpad kernel entry or `/kernel` to remember the choice. One
+  process uses one backend; switching restarts it and is unavailable during a turn. You
+  can also set `backend: codex` on the dsh-tui configuration row or use
+  `DSH_TUI_BACKEND=codex`. Explicit launch choices take precedence over the remembered one.
+- Your `$CODEX_HOME` (default `~/.codex`) and official configuration still apply. dsh-TUI
+  **does not write `~/.codex/config.toml`**. Its model, effort and permission choices live
+  in `~/.dsh-tui/backends/codex/prefs.json` and apply through per-thread requests.
+- Backend identification/title displays Codex. With the brand setting on `auto` (the
+  default) the whole look goes lavender: the CODEX title, the "Build anything with Codex"
+  tagline and the `codex-lavender`/`codex-paper` theme pair (monochrome base with lavender
+  accents, following your terminal's lightness). A manual `/theme` pick or a pinned
+  `dsh-tui.brand` value is never overridden. The portrait slot shows the lavender demon
+  sprite (`assets/codex-girl/`, rendered as a real image via Kitty/Sixel; a click swaps in
+  the red-button variant for a few seconds, with a character-art fallback when the terminal
+  cannot show images).
+
+Resume a thread created by the official client or dsh-TUI:
+
+```sh
+dsh-tui --backend codex --resume <thread-id>
+dsh-tui --backend codex --resume   # last Codex thread used by this dsh-TUI installation
+codex resume <thread-id>           # return to the official frontend; release its writer first
+```
+
+Failed resume reports an error; it does not silently create a new conversation. Resume
+uses the thread’s recorded working directory by default. The official selector may filter
+by directory and default provider; select all directories/providers or use the id directly.
+Two Codex writers cannot open the same thread concurrently. After an official frontend
+exits, its background app-server may retain the writer lock. When resuming with native
+credentials, dsh-TUI tries the official `app-server proxy` to rejoin that server's already
+loaded **idle** thread, using the background server's configuration and login while
+restoring the original history and working directory. Exiting dsh-TUI disconnects its
+proxy; the background server keeps running.
+
+Running turns, pending approvals, managed subscription tokens and explicit `/channel`
+connections retain the occupancy protection. The latter two use private app-server
+processes and never inject credentials into the shared background server. If the server
+is not running, its proxy is unavailable or it does not hold the target thread, resume
+keeps the original error without starting a daemon or creating a replacement conversation.
+If an “active writer” error remains, finish the operation in the frontend holding that
+thread; do not delete locks or terminate someone else's process.
+
+## Login and credentials
+
+### Selection order
+
+1. **The active `/channel` connection**: use its Responses API endpoint and key; do not
+   inject subscription tokens.
+2. **dsh-auth `openai-codex` ChatGPT subscription login**: only on a confirmed first-party
+   OpenAI route, through the official externally managed `chatgptAuthTokens` mode. Tokens
+   passed to Codex stay in memory, not Codex `auth.json`; app-server requests refreshes.
+3. **Your native Codex credentials**: Codex reads its own `$CODEX_HOME` credential file or
+   keychain, environment variables and provider configuration. dsh-TUI does not copy,
+   change or reinterpret them.
+4. With no credentials you can still open the UI, but need `/login` before a model call.
+
+Subscription tokens are not sent to relays. Custom `model_provider`, overridden provider
+base URLs, a non-official `OPENAI_BASE_URL`, or unreadable configuration prevent injection; the environment
+is handed to Codex unchanged. Non-first-party routes should use their own provider
+credentials or a channel key. Account status shows only credential source, subscription
+type and host, not an email address or key.
+
+### The three `/login` methods
+
+| Method | Purpose and storage |
+| --- | --- |
+| Built-in ChatGPT OAuth | Uses the standard profile’s dsh-auth login wizard; omitted if that OAuth service is absent. dsh-auth manages credentials; the external token passed to Codex is not written to Codex’s credential file |
+| Codex device code | Follow the displayed verification link and one-time code in a browser. Codex manages native login storage; cancel the wait in the UI if needed |
+| OpenAI API key | Enter it in a masked field. **It is written to your own Codex credential store**, not kept as a temporary in-memory key. Put relay keys in `/channel` instead of treating them as first-party login |
+
+Success follows the server’s login result, not the immediate `account/login/start` reply.
+Failed refresh or managed-token login prompts for `/login` and stops injection. It **does
+not call `account/logout` or delete your existing native Codex login**. `/logout` delegates
+only to the host OAuth service to remove the matching `openai-codex` dsh-auth credential.
+It does not remove channel keys, other providers or native login. The running app-server
+may retain an already-loaded managed token: **restart dsh-TUI normally to stop using it**.
+Logout does not interrupt, reconnect or modify official configuration. Manage native
+login with the official Codex client in your own external terminal.
+
+Using ChatGPT subscription tokens in third-party clients is subject to OpenAI’s terms.
+External token management is an official app-server interface, not a project guarantee
+that every subscription/workspace allows third-party frontends. Login paths without a real
+account check remain unverified; use an API key if concerned. Never post credentials or
+account information in issues, logs or documentation.
+
+## Relay channels: `/channel`
+
+Channels support an **OpenAI-compatible Responses API** (`wireApi: responses`), not Chat
+Completions endpoints. Use `/channel` to select/create a profile, configure a connection
+and exact model-name mappings. Import from the current Codex provider settings is available
+when its environment key can be read. Mappings are exact replacements, not Claude model tiers.
+
+- Metadata lives in `~/.dsh-tui/backends/codex/channels.json`; it contains only a `tokenRef`.
+  The key is stored in the DSH credential store, not that JSON. Do not put keys in `env` or URLs.
+- Base URLs must use HTTPS; HTTP is allowed only for `localhost` and `127.0.0.1`. Usernames/
+  passwords, query strings, fragments and credential-looking path segments such as `sk-`,
+  `key=` or long random strings are rejected.
+- Provider definitions use `codex app-server -c ...` process arguments. Keys only enter the
+  child environment. **The endpoint hostname and non-secret provider arguments may be
+  visible to other local users in process listings.** Environment variables are not secret
+  from administrators either. Use trusted machines and endpoints.
+- An incomplete active connection, missing key or unsafe URL refuses startup instead of
+  silently falling back to subscription login.
+- Do not mix relay and ChatGPT login. `/login` asks you to address an active channel first.
+  A connection change follows the UI restart flow, resuming the thread with the new
+  provider/credential environment without interrupting an active turn. Mapping-only
+  profile switches may avoid restart. Do not change connections during an active turn.
+
+## Models, reasoning effort, Plan and permissions
+
+`/model` lists Codex’s models and channel mappings. `/effort` offers only the current model’s
+actual supported levels; not every model has `xhigh`. Model switching handles incompatible
+effort levels; default effort is delegated to the model. Idle changes apply immediately;
+changes during a turn apply to the next one, not to reasoning already in progress.
+
+**Collaboration mode and permissions are orthogonal.** `/permission` reuses the existing picker:
+
+| Option | Approval and sandbox |
+| --- | --- |
+| Read Only (`read-only`) | On-request approvals, read-only sandbox |
+| Default (`auto`) | On-request approvals, workspace-write sandbox |
+| Full Access (`full-access`) | No approval prompts or file sandbox; requires an explicit selection |
+| Plan (`plan`) | Planning collaboration mode; keeps the underlying permission preset rather than replacing its sandbox |
+
+- **`Shift+Tab` only toggles Plan**, returning to the previous permission preset when leaving
+  it. It does not cycle into Full Access.
+- `/plan` enters Plan; `/plan <task>` enters it and submits the task. Choosing an explicit
+  permission preset returns to Default collaboration. Plan does not mean all tools are
+  forbidden: the actual security boundary remains Codex’s permission policy.
+- Defaults resolve per field: an explicit dsh-TUI choice > your Codex configuration >
+  `auto` when unset. An unreadable configuration is not overwritten with `auto`.
+- Completed plans offer implementation, implementation with cleared context, or staying
+  in Plan/continuing with feedback. Clearing context continues in a new thread, preserving
+  the original. Plan approval does not silently enable Full Access.
+- Command, file, network and permission approvals use server-provided choices. Allow-once,
+  session allowance or remembered rules appear only when supported. Questions and MCP forms
+  share the existing panel, with secret answers masked.
+
+## Daily commands and input
+
+| Entry | Behavior |
+| --- | --- |
+| `Enter` / `Tab` / `Ctrl+Enter` while working | Steer / queue a follow-up / interrupt and send now; non-steerable turns fall back to follow-up |
+| `Esc` / `Ctrl+C` | Dismiss the focused panel or interrupt. Cancelling a model question also interrupts its turn rather than leaving it hung |
+| `/review` | Review uncommitted changes inline; requires idle state and consumes model usage |
+| `/review base <branch>` / `/review commit <sha>` | Review against a branch or commit; other arguments are custom review instructions |
+| `/diff` | Latest turn’s aggregated diff; otherwise try Git diff against the remote, then show an empty-state notice |
+| `/<skill-name> [arguments]` | Invoke a discovered, enabled Codex skill; completion updates as skills change. Local commands take precedence on name collisions |
+| `/init` | Submit Codex’s AGENTS.md initialization prompt, not the DSH template generator; a model turn with normal approvals/usage |
+| `/mcp` | Codex MCP status and tool counts, with reconnect but no runtime toggle |
+| `/usage` | Server-reported quota windows, utilization, reset times and credits; relays may not provide them |
+| `/status`, `/context`, `/compact` | Status, raw context readings, Codex compaction; unavailable category details are not invented |
+| `/new`, `/clear`, `/export` | New thread, clear the view only, export the current transcript. `/clear` **does not reset context** |
+| `!cmd` / `!!cmd` | dsh-TUI’s local shell / include output in a follow-up, not a verbatim copy of the official `!` persistence semantics |
+
+File cards use real hunk line numbers. Running command cards show a bounded live output
+tail; use `Ctrl+O` for details. Official `userShell` turns in history appear as terminal cards.
+
+### Reading context and quota
+
+The context bar follows the official 12,000-token baseline (`T` is the most recent
+`last.totalTokens`, not cumulative billed tokens; `W` is the model window):
+
+```text
+effective = max(0, W - 12000)
+used      = max(0, T - 12000)
+used share = used / effective       # when effective > 0
+remaining share = 1 - used share
+```
+
+Display handles unknown/invalid windows; `/context` keeps the raw `T / W` reading. Token
+ledger totals, subscription quota and context occupancy are different quantities. Codex
+transcripts do not normally retain full billed usage, so resuming history does not invent
+past tokens/cost. Fresh usage notifications update the readings.
+
+## Session lifecycle
+
+- `/resume` opens the native-thread browser, grouped by project, with all-project browsing.
+  `Enter` resumes, `Ctrl+R` renames and `Ctrl+D` **archives**. Confirmation and completion
+  say the transcript is retained, not physically deleted. Current, occupied or active-worker
+  threads cannot be archived. The catalog lists up to 500 recent ordinary threads, excluding
+  ephemeral forks and child threads from the main list.
+- `/rename` changes the official thread title; `/color` stores a session accent, not a global theme.
+- `/fork` creates a resumable copy without switching. Double `Esc` or `/rewind` conversation
+  rewind creates a copy before the selected question, returns the question to the composer
+  and preserves the original. Rewinding the first question creates an empty thread. **File-only
+  and conversation+files rewind are unsupported**; the Git working tree does not revert.
+- Resume replays the newest 20 full turns before live continuation. Load older messages uses
+  prefetched full-item pages, not tool-omitting summaries. Retry when prefetch is still pending;
+  repeated failure reports a notice. Active resume deduplicates redelivered approvals and
+  never invents usage absent from history.
+
+## Images
+
+Paste images or mention PNG/JPEG/GIF/WebP files with `@`. Limits: **20 MiB per image**,
+**2048 pixels per side**, **2048 × 2048 pixels**, **20 images per message**, and **50 MiB
+per message**. Staging checks the capability limits; sending rereads and checks the image.
+Resize rejected images as prompted rather than assuming an unsent attachment was handled.
+
+Inputs are data URLs persisted with the thread, not disposable clipboard paths. Resume
+shows persisted input images; missing historical localImage files show unavailable
+placeholders without automatically downloading remote images. Codex imageView and completed
+imageGeneration results also display images: `savedPath` takes precedence over embedded data.
+Real model vision and image generation were not tested in this round.
+
+## Subagents and background tasks
+
+- `/agents` or `Ctrl+A` opens the subagent panel. Child text, tools and usage stay in its
+  card/details, not the parent transcript. Details load paginated history on demand; you can
+  interrupt active subagents belonging to the current session.
+- Messaging is **parent-mediated**: the parent model relays it through Codex `send_input`,
+  not a direct child-inbox operation. A receipt means issued, not necessarily read or
+  executed. Cross-parent history/control access is refused.
+- `/jobs` shows unified-exec background terminals with the existing stop controls. Inventory
+  refreshes at turn boundaries and polls about every **2 seconds** while terminals remain
+  live. This is experimental: unsupported methods disable the capability with a notice.
+- Output is the **last 64 KiB observed by this session**, not arbitrary historical output
+  file access. A resumed terminal may have no observed output. Only a complete inventory
+  establishes disappearance. Without a native exit code, completion summaries explicitly say
+  **exit unknown**; they do not imply exit 0 or success.
+- Interrupting the model turn and stopping a background terminal are separate actions.
+
+## Goals, side queries and hooks
+
+| Entry | Behavior |
+| --- | --- |
+| `/goal` | Current goal, phase, token/time budget; values come from Codex |
+| `/goal <objective>`, `/goal edit <objective>` | Set or replace a native goal |
+| `/goal --budget 50k <objective>` | Token budget, also accepting 50000 or 1.5m |
+| `/goal pause`, `/goal resume`, `/goal clear` | Pause, resume or clear; no duplicate DSH round loop |
+| `/btw <question>`, `/recap` | One model call on an ephemeral fork, without writing the parent thread or persistent session list |
+| Hooks | hookPrompt as injected input; start/completion/failure notices, using Codex configuration rather than the DSH `/hooks` manager |
+
+usageLimited/budgetLimited goals show a blocked state and reason. Unsupported goal APIs
+do not expose the capability. `/btw`/`/recap` use a read-only sandbox with no approval
+escalation, request answer-only behavior and reject tool/approval requests. Cancellation
+interrupts the temporary turn and unsubscribes the fork. They consume model quota, not
+free local summaries. Ephemeral fork creation/non-persistence was checked offline; actual
+side-query model answers were not tested in this round.
+
+## Limitations and troubleshooting
+
+- `/skills` and `/hooks` are DSH management entries, not Codex skill/hook management. Invoke
+  Codex skills as `/<skill-name>` from completion; unavailable local commands are not model passthrough.
+- DSH presets, providers, workspace home, migration management and `/tree` are not Codex
+  capabilities. Unsupported commands are marked unavailable rather than silently executed.
+- This scope does not add every official slash alias, voice, apps/plugins management,
+  worktree/daemon, pets, memories, remote control or physical deletion. Theme/companion
+  choices remain dsh-TUI settings; native compatibility does not replace the palette.
+- `/doctor` reports executable/version, drift, Codex home, credential source, provider host,
+  sandbox issues and unknown protocol items. If Linux lacks bubblewrap, install it as
+  prompted and keep the needed sandbox; do not choose Full Access merely to hide an error.
+  Operating-system sandbox behavior belongs to official Codex.
+- 401/login failure: check the channel/route, then `/login`. Quota limits: `/usage`. Context
+  limits: `/compact`. “Active writer”: exit that session in the other terminal first.
+- An app-server exit triggers reconnection notices; failed reconnection leaves a read-only
+  session rather than pretending inputs were delivered.
+- Bug reports should include versions, platform, minimal steps and redacted diagnostics
+  only. Exports and raw ANSI/debug logs may contain text, paths or secrets; do not publish them raw.
+
+## Verification in this round
+
+- The real official 0.160.1 app-server passed nine offline checks under an isolated home: handshake/home isolation, thread creation, model listing, zero-context reading, orthogonal permission/Plan settings, persistent rename, ephemeral fork, full-page resume and archive. There was no model turn or charge and no write to user ~/.codex/config.toml.
+- Protocol/mapping, controls, lifecycle and advanced interfaces use fake-app-server and redacted-fixture regressions. Focused tests also drive the real headless browser for archive/default-delete semantics and the production channel for host OAuth-only logout. They prove wiring, state and boundaries, not acceptance of every real account/model request.
+- Not run in this round: real ChatGPT OAuth/device-code/API-key login, credentialed model turns, real vision/subagent/background-terminal/goal/side-query turns, or real-TTY inline/fullscreen/narrow-terminal interaction. Missing credentials or an interactive terminal are recorded as unverified, not passed; see the progress log for exact results.