Merge latest master into PR 555

# Conflicts: # docs/architecture.i18n.yaml # docs/core-data-structures/core.i18n.yaml # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # packages/client/runtime/README.i18n.yaml # packages/client/ui-conversation/README.i18n.yaml # packages/client/ui-conversation/src/client/chat/MessageItem.tsx # packages/compact/compact-basic/README.i18n.yaml # packages/ui/tui/README.i18n.yaml
2026-07-31 19:39:22 +08:00
parent cc88018cd4 9b1486f90f
commit 09b7fcfd4f
187 changed files with 5806 additions and 657 deletions
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/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 apps/cli/README.md
-README.md: aee08225febe34bb10ee1001c798db9d7daa8905
-README.zh.md: 8f38fd342a0433ca5f7645f896b81aa5392033ae
+README.md: 43524950ae7d3379406a0c859b6449f0697d204b
+README.zh.md: 01954f1229a6f4d076155d42566ed29d568631ca
--- a/apps/cli/README.md
+++ b/apps/cli/README.md
@@ -12,6 +12,7 @@ The TUI surface:
 - treats the **invoking directory** as the workspace — sessions, relative paths, and workspace instructions resolve from the cwd (`dsh meta` is the sole exception, below);
 - tells the agent where its own source lives: after boot it adds a prompt section naming this harness checkout, resolved from the launcher's real path so it holds under a PATH symlink and an arbitrary cwd, so the self-referential `cordis` toolset can read and modify it;
 - applies the personal overlay from `~/.dsh` (see [app-boot's Personal config](../../packages/ui/app-boot/README.md#personal-config)): `config.yaml` patches the booted tree, while `.env` there is the credential provider's own store (never hoisted into the environment, so keys stay rotatable). Environment precedence is ambient > project `.env`.
+- registers bare `/compact`: while the agent is idle, it summarizes useful older history even below automatic pressure, rejects arguments, and reports success only after the standalone replacement bracket is durable. A prompt submitted during compaction keeps its queue identity and starts after that checkpoint; injected context remains visible.

 `dsh meta` is that same TUI with this harness checkout as the workspace, so working on dsh itself needs no `cd`. It chdirs to the checkout root — resolved from the launcher's real path, the same root the source-path prompt section names — after the environment is settled, so precedence is unchanged while the session cwd and HMR watch root move together. Meta always starts a fresh session and accepts no default-surface options; use ordinary `dsh --resume <id>` to resume a persisted session.

@@ -23,9 +24,9 @@ The Web and headless surfaces boot `base.cordis.yml` plus `web.cordis.yml`, then

 The shipped TUI and Web compositions register the native DeepSeek adapter plus pi-ai OpenAI and Anthropic profiles. Credentials and endpoint overrides come from the provider-standard `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`, `OPENAI_API_KEY` / `OPENAI_BASE_URL`, and `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` pairs in the boot's layered environment.

-The Web/headless composition also registers only `web_search`. Search uses DeepSeek's Anthropic-compatible Messages endpoint, resolves the same `DEEPSEEK_API_KEY` reference for every call, and accepts the separate `DEEPSEEK_SEARCH_BASE_URL` endpoint override; each search is an auxiliary model request with its own latency and token cost. `web_fetch` remains disabled and the composition mounts no default fetch provider, so deployments that need arbitrary page retrieval must opt in through an overlay. The TUI composition does not mount Web tools by default. The deployment decision and its security boundary live in the [default Web search Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md).
+Every surface also registers `web_search` and only `web_search`. Search uses DeepSeek's Anthropic-compatible Messages endpoint, resolves the same `DEEPSEEK_API_KEY` reference for every call, and accepts the separate `DEEPSEEK_SEARCH_BASE_URL` endpoint override; each search is an auxiliary model request with its own latency and token cost. `web_fetch` remains disabled and the composition mounts no default fetch provider, so deployments that need arbitrary page retrieval must opt in through an overlay. The deployment decision and its security boundary live in the [default Web search Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md).

-`DSH_TOOLS_MODE` selects the tool presentation mode for the whole Web/headless process: `native` (the schema default when unset), `code` (the `run_code`-only Code Mode wire), or `both`; any other value fails loud at boot through the `dsh-tools` config schema. It is a TEMPORARY seam — process-wide because Loader composition is static — and is removed once the web UI owns per-session tool-mode selection; the TUI surface ignores it (its config tree pins its own mode).
+`DSH_TOOLS_MODE` selects the tool presentation mode for the whole Web/headless process: `native` (the schema default when unset), `code` (the `run_code`-only Code Mode wire), or `both`; any other value fails loud at boot through the `dsh-tools` config schema. It is a TEMPORARY seam — process-wide because Loader composition is static — and is removed once the web UI owns per-session tool-mode selection; the TUI surface ignores it and pins `native`.

 [`core-web.cordis.yml`](config/core-web.cordis.yml) is an opt-in `dsh web --config` overlay that keeps the shipped Web host, browser, Workspace, persistence, and permission composition while reducing the default native model surface to owner-scoped persistent `bash` and `str_replace_editor`. The PTY backend and editor consume the existing Web sandbox and filesystem providers. An open persistent shell prevents changing that session's permission mode until the shell closes, so a shell created under wider access cannot survive a downgrade. `DSH_TOOLS_MODE` still controls native/Code Mode presentation for the resulting two-tool registry.

@@ -37,6 +38,23 @@ pnpm run dsh web --config apps/cli/config/core-web.cordis.yml

 Every `dsh` surface — TUI, Web, and headless — reports session telemetry by default (the row lives in the shared `base.cordis.yml`): every session-log event streams as OTLP/HTTP log records to `https://harness-telemetry.deepseeksvc.com/v1/logs` on a 10-second batch cadence. `DSH_TELEMETRY_OTLP_URL` points the exporter at a different collector; setting `DSH_TELEMETRY_DISABLED` to ANY non-empty value — including `0` or `false` — disables the row before it loads (a privacy switch prefers off-by-mistake over on-by-mistake). No redaction rule is mounted in this composition yet: exported records are the raw captured copy, including message text, tool arguments and results, and the session's working-directory path. The deployment rulings live in the [web-telemetry-default-mount Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md).

+MCP servers are not a shipped default, because a default would have to name one: `@deepseek-ai/dsh-mcp-client` mounts exactly one server per row and spawns it as a child process, outside `ctx.bash` and so outside the sandbox policy. The package is a runtime dependency of this CLI, so an installed `dsh` can mount your own servers from `$DSH_HOME/config.yaml` or a `--config` overlay without a source checkout:
+
+```yaml
+- insert:
+    - id: mcp-github
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: github
+        transport: stdio
+        command: npx
+        args: ['-y', '@modelcontextprotocol/server-github']
+        env:
+          GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN
+```
+
+The model then sees `mcp__github__*`. See the [mcp-client README](../../packages/mcp/mcp-client/README.md) for the Streamable HTTP transport and the full field table.
+
 ## Install (developer machine)

 Symlink the source-running launcher onto your PATH; it resolves the checkout through its own real path, so code changes apply on the next launch with no build step:
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -12,6 +12,7 @@ TUI 界面：
 - 将 **调用目录** 视为 workspace：会话、相对路径和 workspace 指令都从 cwd 解析（`dsh meta` 是唯一例外，见下文）；
 - 告知 agent 自身源码所在位置：启动后添加一个命名此 harness checkout 的提示词段。该路径从启动器的真实路径解析，因此在 PATH 符号链接和任意 cwd 下仍然有效，使自指的 `cordis` 工具集可以读取并修改它；
 - 应用 `~/.dsh` 中的个人覆盖（参见 [app-boot 的个人配置](../../packages/ui/app-boot/README.md#personal-config)）：`config.yaml` 修补已启动的树，而那里的 `.env` 是凭据 provider 自己的存储（绝不会被提升进环境，因此密钥始终可轮换）。环境优先级为环境中已有的值 > 项目 `.env`。
+- 注册裸 `/compact`：agent 空闲时，即使未达到自动压力，也会摘要有效的较早历史；该命令拒绝参数，并只在独立替换标记对持久化后报告成功。压缩（compaction）期间提交的提示词保留其队列身份，并在该检查点之后启动；注入的上下文仍保持可见。

 `dsh meta` 是以本 harness checkout 为 workspace 的同一个 TUI，因此开发 dsh 自身无需 `cd`。它在环境确定之后才 chdir 到 checkout 根目录（从启动器的真实路径解析，与源码路径提示词段所指的根目录相同），因此环境优先级不变，而会话 cwd 与 HMR 监视根目录会一并移动。Meta 始终创建新会话，不接受默认界面的任何选项；恢复已持久化会话应使用普通的 `dsh --resume <id>`。

@@ -23,9 +24,9 @@ Web 和无头界面启动 `base.cordis.yml` 与 `web.cordis.yml`，随后应用

 已交付的 TUI 和 Web 组合会注册原生 DeepSeek 适配器，以及 pi-ai 的 OpenAI 和 Anthropic 提供方配置。凭据和端点覆盖来自启动分层环境中的提供方标准变量对：`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`、`OPENAI_API_KEY` / `OPENAI_BASE_URL` 和 `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`。

-Web／无头组合还只会注册 `web_search`。搜索使用 DeepSeek 的 Anthropic 兼容 Messages 端点，每次调用都会解析同一个 `DEEPSEEK_API_KEY` 凭据引用，并接受独立的 `DEEPSEEK_SEARCH_BASE_URL` 端点覆盖；每次搜索都是一次辅助模型请求，会产生独立的延迟与 token 成本。`web_fetch` 仍处于禁用状态，组合也未挂载默认抓取提供方；需要任意页面抓取能力的部署必须通过覆盖层选择启用。TUI 组合默认不挂载 Web 工具。部署决策及其安全边界见[默认 Web 搜索 Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md)。
+每个界面也都只注册 `web_search` 这一个 Web 工具。搜索使用 DeepSeek 的 Anthropic 兼容 Messages 端点，每次调用都会解析同一个 `DEEPSEEK_API_KEY` 凭据引用，并接受独立的 `DEEPSEEK_SEARCH_BASE_URL` 端点覆盖；每次搜索都是一次辅助模型请求，会产生独立的延迟与 token 成本。`web_fetch` 仍处于禁用状态，组合也未挂载默认抓取提供方；需要任意页面抓取能力的部署必须通过覆盖层选择启用。部署决策及其安全边界见[默认 Web 搜索 Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-default-search.md)。

-`DSH_TOOLS_MODE` 为整个 Web／无头进程选择工具呈现模式：可选值为 `native`（未设置时的 schema 默认值）、`code`（仅含 `run_code` 的 Code Mode 协议接口）或 `both`；任何其他值都会经由 `dsh-tools` 配置 schema 在启动时明确报错。它是一个临时 seam：Loader 组合是静态的，因此该设置作用于整个进程；待 Web UI 负责逐会话工具模式选择后便会移除。TUI 界面会忽略该变量（其配置树固定了自身模式）。
+`DSH_TOOLS_MODE` 为整个 Web／无头进程选择工具呈现模式：`native`（未设置时的 schema 默认值）、`code`（仅含 `run_code` 的 Code Mode 线路）或 `both`；任何其他值都会经由 `dsh-tools` 配置 schema 在启动时明确报错。它是一个临时 seam——Loader 组合是静态的，因此该设置作用于整个进程——待 Web UI 负责逐会话工具模式选择后便会移除；TUI 界面会忽略该变量并固定为 `native`。

 [`core-web.cordis.yml`](config/core-web.cordis.yml) 是一个可选启用的 `dsh web --config` 覆盖层：它保留已交付的 Web 宿主、浏览器、Workspace、持久化与权限组合，同时将默认的原生模型界面精简为以所有者为作用域的持久 `bash` 以及 `str_replace_editor`。PTY 后端和编辑器分别消费现有的 Web 沙箱与文件系统提供方。持久 shell 处于打开状态时，会阻止所属会话更改权限模式；因此，在较宽权限下创建的 shell 无法在降权后继续存活。`DSH_TOOLS_MODE` 仍控制由此得到的双工具注册表采用原生／Code Mode 呈现。

@@ -37,6 +38,23 @@ pnpm run dsh web --config apps/cli/config/core-web.cordis.yml

 每个 `dsh` 界面——TUI、Web 与无头——都默认上报会话遥测（该行位于共享的 `base.cordis.yml`）：每条会话日志事件以 OTLP/HTTP 日志记录的形式、按 10 秒批处理节奏流向 `https://harness-telemetry.deepseeksvc.com/v1/logs`。`DSH_TELEMETRY_OTLP_URL` 可将 exporter 指向其他 collector；将 `DSH_TELEMETRY_DISABLED` 设为**任意非空值**——包括 `0` 或 `false`——都会在该行加载前将其关停（隐私开关取「宁可误关、不可误开」）。该组合当前未挂载任何脱敏规则：导出记录即原始捕获副本，包含消息正文、工具参数与结果、以及会话工作目录路径。部署口径见 [web-telemetry-default-mount Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)。

+MCP 服务器不是交付默认值,因为默认值必须点名一台:`@deepseek-ai/dsh-mcp-client` 每一行只挂载一台服务器,并把它作为子进程 spawn,该进程不经 `ctx.bash`,因此也不受沙箱策略约束。该包是本 CLI 的运行时依赖,所以已安装的 `dsh` 无需源码检出即可从 `$DSH_HOME/config.yaml` 或 `--config` 覆盖层挂载你自己的服务器:
+
+```yaml
+- insert:
+    - id: mcp-github
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: github
+        transport: stdio
+        command: npx
+        args: ['-y', '@modelcontextprotocol/server-github']
+        env:
+          GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN
+```
+
+模型随后会看到 `mcp__github__*`。Streamable HTTP 传输与完整字段表见 [mcp-client README](../../packages/mcp/mcp-client/README.md)。
+
 ## 安装（开发机）

 将从源码运行的启动器符号链接到 PATH 上；它通过自身真实路径解析 checkout，因此代码更改会在下次启动时生效，无需构建：
--- a/apps/cli/composition.md
+++ b/apps/cli/composition.md
@@ -78,6 +78,8 @@ flowchart LR
  cfg --> plugin_tui_token_meter
  plugin_tui_compact_basic["compact-basic<br/>@deepseek-ai/dsh-compact-basic"]
  cfg --> plugin_tui_compact_basic
+  plugin_tui_command_compact["command-compact<br/>@deepseek-ai/dsh-command-compact"]
+  cfg --> plugin_tui_command_compact
  plugin_tui_subagent["subagent<br/>@deepseek-ai/dsh-subagent"]
  cfg --> plugin_tui_subagent
  plugin_tui_subagent_spawn["subagent-spawn<br/>@deepseek-ai/dsh-subagent-spawn"]
@@ -98,6 +100,28 @@ flowchart LR
  cfg --> plugin_tui_spill_local
  plugin_tui_spill_policy["spill-policy<br/>@deepseek-ai/dsh-spill-policy"]
  cfg --> plugin_tui_spill_policy
+  plugin_tui_session_checkpoint_policy["session-checkpoint-policy<br/>@deepseek-ai/dsh-session-checkpoint-policy"]
+  cfg --> plugin_tui_session_checkpoint_policy
+  plugin_tui_tool_result_prune["tool-result-prune<br/>@deepseek-ai/dsh-compact-tool-result-prune"]
+  cfg --> plugin_tui_tool_result_prune
+  plugin_tui_tool_todo["tool-todo<br/>@deepseek-ai/dsh-tool-todo"]
+  cfg --> plugin_tui_tool_todo
+  plugin_tui_tool_goal["tool-goal<br/>@deepseek-ai/dsh-tool-goal"]
+  cfg --> plugin_tui_tool_goal
+  plugin_tui_tool_ralph["tool-ralph<br/>@deepseek-ai/dsh-tool-ralph"]
+  cfg --> plugin_tui_tool_ralph
+  plugin_tui_tool_session_query["tool-session-query<br/>@deepseek-ai/dsh-tool-session-query"]
+  cfg --> plugin_tui_tool_session_query
+  plugin_tui_tool_str_replace_editor["tool-str-replace-editor<br/>@deepseek-ai/dsh-tool-str-replace-editor"]
+  cfg --> plugin_tui_tool_str_replace_editor
+  plugin_tui_repeat_tool_guard["repeat-tool-guard<br/>@deepseek-ai/dsh-repeat-tool-guard"]
+  cfg --> plugin_tui_repeat_tool_guard
+  plugin_tui_web["web<br/>@deepseek-ai/dsh-web"]
+  cfg --> plugin_tui_web
+  plugin_tui_web_search_deepseek["web-search-deepseek<br/>@deepseek-ai/dsh-web-search-deepseek"]
+  cfg --> plugin_tui_web_search_deepseek
+  plugin_tui_tool_web["tool-web<br/>@deepseek-ai/dsh-tool-web"]
+  cfg --> plugin_tui_tool_web
  plugin_tui_tools["tools<br/>@deepseek-ai/dsh-tools"]
  cfg --> plugin_tui_tools
  plugin_tui_system_prompt["system-prompt<br/>@deepseek-ai/dsh-system-prompt"]
@@ -147,6 +171,7 @@ flowchart LR
 | `plan-mode` | `@deepseek-ai/dsh-plan-mode` |
 | `token-meter` | `@deepseek-ai/dsh-token-meter` |
 | `compact-basic` | `@deepseek-ai/dsh-compact-basic` |
+| `command-compact` | `@deepseek-ai/dsh-command-compact` |
 | `subagent` | `@deepseek-ai/dsh-subagent` |
 | `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |
 | `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` |
@@ -157,6 +182,17 @@ flowchart LR
 | `timeout-policy` | `@deepseek-ai/dsh-timeout-policy` |
 | `spill-local` | `@deepseek-ai/dsh-spill-local` |
 | `spill-policy` | `@deepseek-ai/dsh-spill-policy` |
+| `session-checkpoint-policy` | `@deepseek-ai/dsh-session-checkpoint-policy` |
+| `tool-result-prune` | `@deepseek-ai/dsh-compact-tool-result-prune` |
+| `tool-todo` | `@deepseek-ai/dsh-tool-todo` |
+| `tool-goal` | `@deepseek-ai/dsh-tool-goal` |
+| `tool-ralph` | `@deepseek-ai/dsh-tool-ralph` |
+| `tool-session-query` | `@deepseek-ai/dsh-tool-session-query` |
+| `tool-str-replace-editor` | `@deepseek-ai/dsh-tool-str-replace-editor` |
+| `repeat-tool-guard` | `@deepseek-ai/dsh-repeat-tool-guard` |
+| `web` | `@deepseek-ai/dsh-web` |
+| `web-search-deepseek` | `@deepseek-ai/dsh-web-search-deepseek` |
+| `tool-web` | `@deepseek-ai/dsh-tool-web` |
 | `tools` | `@deepseek-ai/dsh-tools` |
 | `system-prompt` | `@deepseek-ai/dsh-system-prompt` |
 | `agent-loop` | `@deepseek-ai/dsh-agent-loop` |
--- a/apps/cli/config/base.cordis.yml
+++ b/apps/cli/config/base.cordis.yml
@@ -204,6 +204,11 @@
 - id: compact-basic
  name: '@deepseek-ai/dsh-compact-basic'

+# Human `/compact`: one useful reduction below the automatic threshold. Backend
+# independent, so it follows whichever compaction service this leaf mounts.
+- id: command-compact
+  name: '@deepseek-ai/dsh-command-compact'
+
 - id: subagent
  name: '@deepseek-ai/dsh-subagent'

@@ -248,6 +253,74 @@
  config:
    maxInlineBytes: 50000

+# Durability checkpoints before each model request and top-level dispatch.
+- id: session-checkpoint-policy
+  name: '@deepseek-ai/dsh-session-checkpoint-policy'
+
+# Compacts oversized tool results before the broader conversation compactor
+# runs, preserving the model-visible result within the configured budget.
+- id: tool-result-prune
+  name: '@deepseek-ai/dsh-compact-tool-result-prune'
+  config:
+    thresholdChars: 8192
+    headChars: 4096
+    tailChars: 1024
+
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'
+
+# Persisted same-session goals reach the model and the slash menu here; the
+# domain, driver, and `/goal` command are above.
+- id: tool-goal
+  name: '@deepseek-ai/dsh-tool-goal'
+
+# Fresh-agent Ralph iteration over a build-time-fixed script.
+- id: tool-ralph
+  name: '@deepseek-ai/dsh-tool-ralph'
+  config:
+    subagentProvider: spawn
+    maxRounds: 64
+
+- id: tool-session-query
+  name: '@deepseek-ai/dsh-tool-session-query'
+  config:
+    maxSearchResults: 100
+    searchTimeoutMs: 30000
+
+- id: tool-str-replace-editor
+  name: '@deepseek-ai/dsh-tool-str-replace-editor'
+  config:
+    maxOutputChars: 16000
+
+# Consecutive-repeat reminders on the tool chain.
+- id: repeat-tool-guard
+  name: '@deepseek-ai/dsh-repeat-tool-guard'
+  config:
+    thresholds: [3, 5, 8]
+    argumentsPreviewChars: 500
+
+# Every surface enables the stable web_search model surface. DeepSeek search
+# resolves the same DEEPSEEK_API_KEY credential the Models page manages for
+# chat, at each search; its Messages endpoint is separate from the
+# chat-completions endpoint, so it takes its own base-URL override. Fetch stays
+# disabled and no fetch provider is mounted: that provider defers SSRF
+# protection and the model would choose the request target.
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: deepseek-official
+
+- id: web-search-deepseek
+  name: '@deepseek-ai/dsh-web-search-deepseek'
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
+
+- id: tool-web
+  name: '@deepseek-ai/dsh-tool-web'
+  config:
+    fetch: false
+
 # ── rows every surface mounts, whose values each overlay states ──────────────

 # The tool registry. Presentation mode is a surface choice, so each overlay
--- a/apps/cli/config/core-web.cordis.yml
+++ b/apps/cli/config/core-web.cordis.yml
@@ -37,6 +37,20 @@
 - id: tool-todo
  disabled: true

+# These consumers are shared defaults on the ordinary shipped surfaces, but
+# this opt-in profile keeps exactly its two named tools.
+- id: tool-goal
+  disabled: true
+
+- id: tool-ralph
+  disabled: true
+
+- id: tool-session-query
+  disabled: true
+
+- id: tool-str-replace-editor
+  disabled: true
+
 # The matching browser controls must not offer host tools that this profile
 # omits. ui-question's host half owns the ask_user_question registration.
 - id: ui-plan
--- a/apps/cli/config/tui.cordis.yml
+++ b/apps/cli/config/tui.cordis.yml
@@ -71,29 +71,17 @@
    - id: agent-loop-invariant
      name: '@deepseek-ai/dsh-agent-loop/invariant'

-    - id: session-checkpoint-policy
-      name: '@deepseek-ai/dsh-session-checkpoint-policy'
-
    # The derived query index behind `/resume`. The launcher provides a unique
    # process-local path because this SQLite backend has one writer owner; the
    # project-local fallback applies when no launcher sets the typed slot.
    - id: session-reference
      name: '@deepseek-ai/dsh-session-reference'

-    # Compacts oversized tool results before the broader conversation compactor
-    # runs, preserving the model-visible result within the configured budget.
-    - id: tool-result-prune
-      name: '@deepseek-ai/dsh-compact-tool-result-prune'
-
-    # Persisted same-session goals reach the model and the slash menu here; the
-    # domain, driver, and `/goal` command are in the base.
-    - id: tool-goal
-      name: '@deepseek-ai/dsh-tool-goal'
-
-    # A separate fixed consumer demonstrates fresh-agent Ralph iteration without
-    # changing the workflow tool or same-session goal behavior.
-    - id: tool-ralph
-      name: '@deepseek-ai/dsh-tool-ralph'
+    # Terminal-multiplexer context, mounted only where a terminal exists.
+    - id: tmux-context
+      name: '@deepseek-ai/dsh-tmux-context'
+      config:
+        refreshIntervalMs: 900000

    # The keyboard-backed provider behind ask_user_question and the plan-mode
    # review, and the front door it renders inside.
--- a/apps/cli/config/web.cordis.yml
+++ b/apps/cli/config/web.cordis.yml
@@ -80,28 +80,6 @@
 - id: fs-local
  disabled: true

-# The Web/headless product enables only the stable web_search model surface.
-# DeepSeek search resolves the same DEEPSEEK_API_KEY credential the Models page
-# manages for chat, at each search; its Messages endpoint is separate from the
-# chat-completions endpoint. Fetch remains disabled and no default fetch
-# provider is mounted.
- insert:
-    - id: web
-      name: '@deepseek-ai/dsh-web'
-      config:
-        searchProvider: deepseek-official
-
-    - id: web-search-deepseek
-      name: '@deepseek-ai/dsh-web-search-deepseek'
-      config:
-        apiKeyEnv: DEEPSEEK_API_KEY
-        baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
-
-    - id: tool-web
-      name: '@deepseek-ai/dsh-tool-web'
-      config:
-        fetch: false
-
 # ── web-only host rows, the transport layer, and the browser roster ─────────

 # `dshClient` rows are the browser roster the modules node half scans into
@@ -135,9 +113,6 @@
        writeEveryEvents: 200
        writeIntervalMs: 5000

-    - id: tool-todo
-      name: '@deepseek-ai/dsh-tool-todo'
-
    # Resolve bind host, SSH launch, and display once at boot, then mount the
    # matching dual-face directory picker. Mount -native or -browse directly in
    # an overlay to pin the interaction.
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -48,6 +48,7 @@
    "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^",
    "@deepseek-ai/dsh-client-ui-workspace": "workspace:^",
    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
+    "@deepseek-ai/dsh-command-compact": "workspace:^",
    "@deepseek-ai/dsh-command-goal": "workspace:^",
    "@deepseek-ai/dsh-commands": "workspace:^",
    "@deepseek-ai/dsh-compact-basic": "workspace:^",
@@ -73,6 +74,7 @@
    "@deepseek-ai/dsh-paths": "workspace:^",
    "@deepseek-ai/dsh-permission": "workspace:^",
    "@deepseek-ai/dsh-plan-mode": "workspace:^",
+    "@deepseek-ai/dsh-repeat-tool-guard": "workspace:^",
    "@deepseek-ai/dsh-pty": "workspace:^",
    "@deepseek-ai/dsh-pty-local": "workspace:^",
    "@deepseek-ai/dsh-sandbox-local": "workspace:^",
@@ -104,6 +106,7 @@
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tasks-local": "workspace:^",
    "@deepseek-ai/dsh-timeout-policy": "workspace:^",
+    "@deepseek-ai/dsh-tmux-context": "workspace:^",
    "@deepseek-ai/dsh-token-meter": "workspace:^",
    "@deepseek-ai/dsh-tool-ask-user": "workspace:^",
    "@deepseek-ai/dsh-tool-bash": "workspace:^",
@@ -113,6 +116,7 @@
    "@deepseek-ai/dsh-tool-fs-search": "workspace:^",
    "@deepseek-ai/dsh-tool-goal": "workspace:^",
    "@deepseek-ai/dsh-tool-ralph": "workspace:^",
+    "@deepseek-ai/dsh-tool-session-query": "workspace:^",
    "@deepseek-ai/dsh-tool-skill": "workspace:^",
    "@deepseek-ai/dsh-tool-str-replace-editor": "workspace:^",
    "@deepseek-ai/dsh-tool-subagent": "workspace:^",
--- a/apps/cli/tests/fixtures/composition-echo-llm.ts
+++ b/apps/cli/tests/fixtures/composition-echo-llm.ts
@@ -0,0 +1,51 @@
+import type { Context } from 'cordis'
+import type {
+  GenerateOptions,
+  LlmModelInfo,
+  LlmResolvedModelInfo,
+  StreamChunk,
+} from '@deepseek-ai/dsh-llm'
+import { LlmAdapter } from '@deepseek-ai/dsh-llm'
+
+/** Terminal marker the preset smoke waits for before it asks the TUI to exit. */
+export const COMPOSITION_REPLY_TEXT = 'Shipped composition acknowledged.'
+
+// Provider id and model the keyless tail routes `main` to; that overlay is the
+// only caller, so the pair lives here as plain constants.
+const COMPOSITION_PROVIDER = 'composition-keyless'
+const COMPOSITION_MODEL = 'composition-keyless-model'
+
+/**
+ * Network-free adapter for the shipped-composition smoke. It answers every
+ * request — tool-ful agent turns and the tool-less auxiliary calls alike — with
+ * one fixed text and never calls a tool, because the assertion under test is the
+ * assembled tool catalog the loop logs, not any tool's behavior.
+ */
+class CompositionEchoAdapter extends LlmAdapter {
+  override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
+    return Promise.resolve([{ provider, id: COMPOSITION_MODEL, name: 'Preset Keyless' }])
+  }
+
+  override resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo> {
+    return Promise.resolve({ provider, id: model, name: 'Preset Keyless', context: { contextWindow: 128_000 } })
+  }
+
+  override async * stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    yield { type: 'block-start', index: 0, blockType: 'text' }
+    for (const char of COMPOSITION_REPLY_TEXT) yield { type: 'text-delta', index: 0, text: char }
+    yield { type: 'block-end', index: 0, block: { type: 'text', text: COMPOSITION_REPLY_TEXT } }
+    yield { type: 'usage', usage: { inputTokens: 20, outputTokens: COMPOSITION_REPLY_TEXT.length } }
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+}
+
+export const name = 'composition-echo-llm'
+export const inject = ['llm']
+
+/**
+ * Register the network-free adapter the shipped-composition smoke routes through.
+ * @param ctx - the loader-mounted plugin context.
+ */
+export function apply(ctx: Context): void {
+  ctx.llm.registerAdapter([COMPOSITION_PROVIDER], new CompositionEchoAdapter())
+}
--- a/apps/cli/tests/fixtures/composition-keyless-tail.cordis.yml
+++ b/apps/cli/tests/fixtures/composition-keyless-tail.cordis.yml
@@ -0,0 +1,52 @@
+# Keyless tail for the shipped-composition smoke, applied as `--config` so the
+# launcher boots `base.cordis.yml` + `tui.cordis.yml` and then this file.
+#
+# Everything below is test isolation, never composition under test: the model is
+# replaced so no request leaves the process, the settle marker gates the smoke's
+# first prompt, and the session artifacts move into the smoke's temporary
+# workspace so the log inspection can read them.
+
+# A patch's `name` is an assertion rather than a replacement, so the base
+# adapter row is disabled and the scripted one inserted. Relative specifiers
+# resolve against the INCLUDED file's directory (apps/cli/config), not this
+# file's, because the include moves baseUrl there.
+- id: llm-deepseek
+  disabled: true
+
+- insert:
+    - id: composition-echo-llm
+      name: '../tests/fixtures/composition-echo-llm.ts'
+    - id: composition-settled
+      name: '../tests/fixtures/composition-settled.ts'
+
+- id: agent-loop
+  config:
+    agents:
+      - id: main
+        provider: composition-keyless
+        model: composition-keyless-model
+        cwd: !!js process.cwd()
+
+- id: session-persistence-jsonl
+  config:
+    root: './.sessions'
+    compression: none
+
+- id: session-query-sqlite
+  config:
+    path: './.sessions/session-query.db'
+
+# The title call is a second, tool-less request that would race the log
+# inspection for no coverage: the catalog under test rides the agent turn.
+- id: session-title-llm
+  disabled: true
+
+- id: tui
+  config:
+    sessionId: !!js configuredAgentIdentities?.main?.id ?? 'main'
+    welcome: 'composition smoke ready.'
+    showReasoning: true
+
+# HMR watches the repository; a PTY subprocess test must not start a watcher.
+- id: hmr
+  disabled: true
--- a/apps/cli/tests/fixtures/composition-settled.ts
+++ b/apps/cli/tests/fixtures/composition-settled.ts
@@ -0,0 +1,24 @@
+import type { Context } from 'cordis'
+
+/**
+ * Marker the shipped-composition smoke gates its first prompt on. The TUI renders as soon as
+ * its own fiber starts, so a prompt typed at the banner can reach the loop while
+ * later rows — tool plugins, persistence — are still activating, and would
+ * assemble a partial catalog. Waiting for this line makes the turn observe the
+ * settled tree.
+ */
+export const COMPOSITION_SETTLED_MARKER = 'COMPOSITION_TREE_SETTLED'
+
+export const name = 'composition-settled'
+
+/**
+ * Announce settled Loader activation on the terminal byte stream, after every
+ * entry in the booted tree has started. The write is detached: awaiting the
+ * Loader from inside an entry would wait on this entry's own activation.
+ * @param ctx - the loader-mounted plugin context.
+ */
+export function apply(ctx: Context): void {
+  void ctx.loader.await().then(() => {
+    process.stdout.write(`\n${COMPOSITION_SETTLED_MARKER}\n`)
+  })
+}
--- a/apps/cli/tests/shipped-composition.e2e.ts
+++ b/apps/cli/tests/shipped-composition.e2e.ts
@@ -0,0 +1,124 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS } from '@deepseek-ai/dsh-loader-smoke'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { COMPOSITION_REPLY_TEXT } from './fixtures/composition-echo-llm.ts'
+import { COMPOSITION_SETTLED_MARKER } from './fixtures/composition-settled.ts'
+import { runTuiPtySmoke } from './pty-harness.ts'
+
+const dshBinScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+// An overlay over the shipped tree, so the catalog under test is the one
+// `base.cordis.yml` + `tui.cordis.yml` assemble; the tail only swaps the model
+// and redirects session artifacts.
+const keylessTail = fileURLToPath(new URL('./fixtures/composition-keyless-tail.cordis.yml', import.meta.url))
+
+/**
+ * The catalog the shipped `dsh` TUI puts in front of the model, as the loop
+ * logged it, minus the ripgrep-dependent pair below.
+ * The absences are the composition's security decisions, not incidental gaps:
+ * the `cordis_*` toolset executes model-written JavaScript that no sandbox row
+ * confines, `web_fetch` chooses its own request target, and `mcp_*` servers
+ * spawn outside `ctx.bash`. The composition Agent Note owns the rationale and
+ * its sources.
+ */
+const EXPECTED_TUI_TOOLS = [
+  'ask_user_question',
+  'bash',
+  'create_goal',
+  'edit',
+  'exit_plan_mode',
+  'get_goal',
+  'ralph',
+  'read',
+  'session_event_read',
+  'session_event_search',
+  'session_event_trace',
+  'session_search',
+  'session_trace',
+  'skill',
+  'str_replace_editor',
+  'subagent',
+  'subagent_fork',
+  'task_kill',
+  'task_list',
+  'task_output',
+  'todo_write',
+  'update_goal',
+  'web_search',
+  'workflow',
+  'write',
+]
+
+/**
+ * `glob` and `grep` come from `dsh-tool-fs-search`, which probes `command -v rg`
+ * through the mounted bash executor at load and registers neither tool when
+ * ripgrep is absent. That is a host dependency, not a composition decision, so the
+ * pair is asserted separately — present together or absent together.
+ */
+const RIPGREP_TOOLS = ['glob', 'grep']
+
+/** The assembled request header the smoke asserts on. */
+interface LoggedHeader {
+  /** Assembled tool names, sorted. */
+  names: string[]
+  /** `bash`'s assembled parameter properties; the escalation pair is present only under a confining executor. */
+  bashArguments: Record<string, unknown>
+}
+
+/**
+ * Read the request header the loop assembled for its first request from the
+ * session log the smoke's workspace persisted — the model-visible composition
+ * itself, not a registry projection taken beside it.
+ * @param cwd - the smoke's temporary workspace.
+ * @returns the assembled catalog, system prompt, and `bash` argument shape.
+ */
+async function loggedHeader(cwd: string): Promise<LoggedHeader> {
+  const sessionsDir = join(cwd, '.sessions')
+  const entries = await readdir(sessionsDir, { recursive: true })
+  // A single keyless run writes one session log.
+  const logRelPath = entries.find(name => name.endsWith('.jsonl'))
+  if (logRelPath === undefined) throw new Error(`no session log written under ${sessionsDir}`)
+  const lines = (await readFile(join(sessionsDir, logRelPath), 'utf8')).split('\n').filter(Boolean)
+  for (const line of lines) {
+    const event = JSON.parse(line) as SessionEvent
+    if (event.type !== 'request/header') continue
+    const tools = event.data.header.tools ?? []
+    const bash = tools.find(schema => schema.name === 'bash')
+    return {
+      names: tools.map(schema => schema.name).sort(),
+      bashArguments: (bash?.parameters as { properties?: Record<string, unknown> } | undefined)?.properties ?? {},
+    }
+  }
+  throw new Error(`session log ${logRelPath} has no request/header event`)
+}
+
+describe('shipped dsh composition (real Loader tree in a PTY)', () => {
+  it('assembles exactly the shipped TUI catalog', async () => {
+    let observed: LoggedHeader | undefined
+    const output = await runTuiPtySmoke({
+      label: 'dsh shipped composition',
+      tempDirPrefix: 'dsh-shipped-tui-',
+      binScript: dshBinScript,
+      tsconfigPath,
+      configPath: keylessTail,
+      env: { DEEPSEEK_API_KEY: 'keyless-composition-no-call', DSH_TELEMETRY_DISABLED: '1' },
+      // Artifact CI builds and smokes concurrently on a contended runner.
+      ...(process.env.DSH_EXAMPLE_MODE === 'lib' ? { timeoutMs: 60_000 } : {}),
+      actions: [
+        { waitFor: COMPOSITION_SETTLED_MARKER, send: 'Describe the shipped composition.\r' },
+        { waitFor: COMPOSITION_REPLY_TEXT, send: '/exit\r' },
+      ],
+      inspect: async (cwd) => { observed = await loggedHeader(cwd) },
+    })
+    expect(output).toContain(COMPOSITION_REPLY_TEXT)
+    expect(observed?.names.filter(name => !RIPGREP_TOOLS.includes(name))).toEqual(EXPECTED_TUI_TOOLS)
+    expect([[], RIPGREP_TOOLS]).toContainEqual(observed?.names.filter(name => RIPGREP_TOOLS.includes(name)))
+    // The TUI mounts the unrestricted local executors, so `tool-bash` emits no
+    // escalation pair. Pinning its absence keeps a later sandbox change from
+    // arriving here unannounced.
+    expect(Object.keys(observed?.bashArguments ?? {})).not.toContain('sandbox_permissions')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})
--- a/apps/cli/tests/snapshots/queued-manual-compact/terminal.expected.txt
+++ b/apps/cli/tests/snapshots/queued-manual-compact/terminal.expected.txt
@@ -0,0 +1,128 @@
+terminal 100x36 buffer=normal length=66 base=30 viewport=30
+lifecycle started=1 stopped=0 progress=inactive
+title "Reply with exactly the word: — DSH TUI snapshot"
+cursor hidden column=7 viewportRow=35 bufferRow=65
+buffer
+0| " DEEPSEEK HARNESS"
+  style 1-8 fg=bright-magenta bold
+  style 10-16 bold
+1| " Reply with exactly the word:"
+  style 1-28 dim
+2| " main-session"
+  style 1-12 dim
+3| <blank>
+4| "Context · snapshot-seed"
+  style 0-22 dim
+5| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+6| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+7| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+8| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+9| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+10| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+11| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+12| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+13| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+14| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+15| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+16| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+17| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+18| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-99 dim
+19| "Older snapshot context. Older snapshot context. Older snapshot context. Older snapshot context.     "
+  style 0-94 dim
+20| <blank>
+21| "You                                                                                                 "
+  style 0-2 fg=bright-magenta bold underline
+22| "Reply with exactly the word: ONE. No tools.                                                         "
+23| <blank>
+24| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+25| "Reasoning                                                                                           "
+  style 0-8 dim italic
+26| "The user wants me to reply with exactly the word \"ONE\" and use no tools.                            "
+  style 0-71 dim italic
+27| "ONE                                                                                                 "
+28| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+29| <blank>
+30| "Keyboard shortcuts                                                                                  "
+  style 0-17 fg=bright-magenta bold
+31| "Enter send • Shift/Alt+Enter newline • Up/Down prompt history                                       "
+  style 0-60 dim
+32| "Esc cancel turn • Ctrl+O cycle cards (collapse/expand/hide) • Ctrl+R toggle reasoning • Ctrl+L      "
+  style 0-99 dim
+33| "redraw                                                                                              "
+  style 0-5 dim
+34| "Ctrl+C cancel while running; clear input or exit while idle • Ctrl+D exit                           "
+  style 0-72 dim
+35| "                                                                                                    "
+36| "/clear — Clear the transcript view (session history is unchanged)                                   "
+  style 0-64 dim
+37| "/compact — Compact older conversation history                                                       "
+  style 0-44 dim
+38| "/exit — Exit after the active turn reaches idle                                                     "
+  style 0-46 dim
+39| "/help — Show keyboard shortcuts and commands                                                        "
+  style 0-43 dim
+40| "/model [[provider/]model] — Show or switch this session's model                                     "
+  style 0-62 dim
+41| "/palette — Show every color and attribute role this terminal renders                                "
+  style 0-67 dim
+42| "/quit — Exit after the active turn reaches idle                                                     "
+  style 0-46 dim
+43| "/reload — EXPERIMENTAL (dev): re-read loader config files and apply the diff (idle only)            "
+  style 0-87 dim
+44| "/resume — List this workspace's resumable sessions                                                  "
+  style 0-49 dim
+45| "/status — Show session diagnostics, system prompt, and registered tools                             "
+  style 0-70 dim
+46| "/skill:<name> [instructions] — load a skill into the conversation                                   "
+  style 0-64 dim
+47| <blank>
+48| "Context · snapshot-injector"
+  style 0-26 dim
+49| "Injected while compaction was running.                                                              "
+  style 0-37 dim
+50| <blank>
+51| "… earlier context was compacted …                                                                   "
+  style 0-32 dim
+52| <blank>
+53| "You                                                                                                 "
+  style 0-2 fg=bright-magenta bold underline
+54| "Reply with exactly the word: TWO. No tools.                                                         "
+55| <blank>
+56| "Compacted 2 history items (~387 tokens).                                                            "
+  style 0-39 dim
+57| <blank>
+58| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+59| "Reasoning                                                                                           "
+  style 0-8 dim italic
+60| "The user wants me to reply with exactly the word \"TWO\" and no tools.                                "
+  style 0-67 dim italic
+61| "TWO                                                                                                 "
+62| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+63| <blank>
+64| "/workspace/project  deepseek-v4-flash  ↑2.9k ↓41  cache 49%  3% cont"
+  style 0-49 fg=bright-magenta bold
+  style 52-68 dim
+  style 71-90 dim
+  style 93-99 dim
+65| " dsh ◍                                                                                              "
+  style 1-3 fg=bright-magenta bold
+  style 5-6 dim
+  style 7-7 inverse
--- a/apps/cli/tests/tui.snapshot.ts
+++ b/apps/cli/tests/tui.snapshot.ts
@@ -11,8 +11,12 @@ import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import WorkerCodeRuntime from '@deepseek-ai/dsh-code-runtime-worker'
 import CommandService from '@deepseek-ai/dsh-commands'
+import * as CommandCompact from '@deepseek-ai/dsh-command-compact'
+import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
+import type { SummarizationInput } from '@deepseek-ai/dsh-compact-basic/src/summarizer.ts'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 import { installLlmReplay, parseSessionLog } from '@deepseek-ai/dsh-llm-replay'
@@ -45,6 +49,8 @@ type ScenarioInteraction = 'skill-invocation-policy'

 interface Scenario {
  name: string
+  /** Replay fixture owned by an earlier scenario, for a derived presentation case. */
+  fixture?: string
  composition: Composition
  expectedTools: string[]
  expectedEventCounts?: Record<string, number>
@@ -68,6 +74,13 @@ interface Scenario {
  spillMaxInlineBytes?: number
  /** Run scenario-specific terminal input instead of replaying recorded user prompts. */
  interaction?: ScenarioInteraction
+  /**
+   * Mount a deterministic compaction backend plus `/compact`, then run the
+   * human command with a held summary while a prompt and injected context
+   * arrive. Proves queued input waits for the standalone bracket's durability
+   * checkpoint instead of racing the replacement.
+   */
+  manualCompact?: boolean
 }

 const SCENARIOS: Scenario[] = [
@@ -80,6 +93,14 @@ const SCENARIOS: Scenario[] = [
    leavePlanModeAfterFirstTurn: true,
    recorded: true,
  },
+  {
+    name: 'queued-manual-compact',
+    fixture: 'multi-turn-conversation',
+    composition: 'native',
+    expectedTools: [],
+    recorded: false,
+    manualCompact: true,
+  },
  {
    name: 'todo-plan',
    composition: 'native',
@@ -149,6 +170,44 @@ function snapshotModeFromEnv(value: string | undefined): SnapshotMode {

 const MODE = snapshotModeFromEnv(process.env.DSH_SNAPSHOT)
 const observedScenarios = new Set<string>()
+const workerState = Reflect.get(globalThis, '__vitest_worker__') as
+  | { readonly config?: { readonly testNamePattern?: RegExp } }
+  | undefined
+// Worker argv omits the parent CLI's `-t`; the serialized runner config is the
+// authoritative distinction between a focused replay and the full suite.
+const TEST_NAME_FILTERED = workerState?.config?.testNamePattern !== undefined
+
+/**
+ * Deterministic keyless summary that pauses so the scenario can submit a real
+ * prompt and inject context while manual compaction holds turn admission.
+ */
+class DeferredSnapshotCompactService extends BasicCompactService {
+  readonly summaryStarted = Promise.withResolvers<undefined>()
+  readonly releaseSummary = Promise.withResolvers<undefined>()
+
+  override async summarize(
+    _input: SummarizationInput,
+    _agent: Agent,
+    signal?: AbortSignal,
+  ): Promise<{ summary: [{ type: 'text'; text: string }]; provider: string; model: string }> {
+    this.summaryStarted.resolve(undefined)
+    await this.releaseSummary.promise
+    signal?.throwIfAborted()
+    return {
+      summary: [{ type: 'text', text: 'Keyless manual compaction checkpoint.' }],
+      provider: 'snapshot',
+      model: 'snapshot-compactor',
+    }
+  }
+}
+
+/** Seed between-turn model-visible history without inventing a loop execution. */
+function seedCompactableHistory(agent: Agent): void {
+  agent.inject(createUserMessage({
+    content: [{ type: 'text', text: 'Older snapshot context. '.repeat(60) }],
+    source: { kind: 'plugin', plugin: 'snapshot-seed' },
+  }))
+}

 function snapshotDisplayPath(displayPath: string, cwd: string, displayCwd: string): string {
  const rel = relative(cwd, displayPath)
@@ -161,10 +220,15 @@ function scenarioDir(scenario: Scenario): string {
  return join(SNAPSHOTS_DIR, scenario.name)
 }

+/** Directory owning the replay fixture: the scenario's own, or the one it derives from. */
+function fixtureDir(scenario: Scenario): string {
+  return join(SNAPSHOTS_DIR, scenario.fixture ?? scenario.name)
+}
+
 function childFixturePaths(scenario: Scenario): string[] {
  return Array.from(
    { length: scenario.childSessions ?? 0 },
-    (_, index) => join(scenarioDir(scenario), `session.${index + 1}.jsonl`),
+    (_, index) => join(fixtureDir(scenario), `session.${index + 1}.jsonl`),
  )
 }

@@ -206,6 +270,24 @@ async function settleTerminal(terminal: HeadlessTerminal): Promise<void> {
  if (stable < 3) throw new Error('TUI frames did not quiesce within 200ms')
 }

+/** Bound deterministic in-process coordination waits with actionable state. */
+async function snapshotDeadline<T>(
+  operation: Promise<T>,
+  detail: () => string,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([
+      operation,
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => { reject(new Error(detail())) }, 5_000)
+      }),
+    ])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+
 async function mountScenarioContext(
  scenario: Scenario,
  cwd: string,
@@ -232,6 +314,9 @@ async function mountScenarioContext(
    skills: { local: { agentsHome: join(cwd, '.agents') } },
  })
  await ctx.plugin(TokenMeterService)
+  if (scenario.manualCompact === true) {
+    await ctx.plugin(DeferredSnapshotCompactService, { auto: false })
+  }
  await ctx.plugin(LocalSubprocessService)
  await ctx.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 })
  await ctx.plugin(SnapshotLocalFileSystem, { cwd: '/' })
@@ -249,6 +334,7 @@ async function mountScenarioContext(
  await ctx.plugin(ToolWorkflow)
  await ctx.plugin(ToolRalph)
  await ctx.plugin(CommandService)
+  if (scenario.manualCompact === true) await ctx.plugin(CommandCompact)
  if (scenario.enterPlanMode === true) {
    await ctx.plugin(PlanModeService, { section: 'Snapshot plan mode instructions.' })
  }
@@ -276,9 +362,9 @@ interface ScenarioResult {
 }

 async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
-  const clock = vi.spyOn(Date, 'now').mockReturnValue(new Date(2026, 6, 21, 12, 0, 0).getTime())
-  const dir = scenarioDir(scenario)
-  const fixtureFile = join(dir, 'session.jsonl')
+  const snapshotTime = new Date(2026, 6, 21, 12, 0, 0).getTime()
+  const clock = vi.spyOn(Date, 'now').mockReturnValue(snapshotTime)
+  const fixtureFile = join(fixtureDir(scenario), 'session.jsonl')
  const childFiles = childFixturePaths(scenario)
  const prompts = userPrompts(await readFile(fixtureFile, 'utf8'))
  if (scenario.interaction === undefined) {
@@ -292,7 +378,7 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
  const terminal = new HeadlessTerminal(100, 36)
  try {
    if (scenario.seedWorkspace === true) {
-      const source = join(scenarioDir(scenario), 'workspace')
+      const source = join(fixtureDir(scenario), 'workspace')
      await cp(source, cwd, { recursive: true })
    }
    ctx = await mountScenarioContext(scenario, cwd, displayCwd, fixtureFile, childFiles)
@@ -308,6 +394,7 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
      agentOptions: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
    })
    const agent: Agent = handle.agent
+    if (scenario.manualCompact === true) seedCompactableHistory(agent)
    controller = createTuiChat(ctx, {
      sessionId: 'main-session',
      theme: { color: true },
@@ -380,6 +467,14 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
    }

    let remainingPrompts = prompts
+    let queuedPrompt: string | undefined
+    let manualOrder: string[] | undefined
+    let manualCommandId: string | undefined
+    if (scenario.manualCompact === true) {
+      expect(prompts.length, 'queued manual compaction needs a second replayed prompt').toBeGreaterThanOrEqual(2)
+      queuedPrompt = prompts.at(-1)
+      remainingPrompts = prompts.slice(0, -1)
+    }
    if (scenario.enterPlanMode === true) {
      const firstPrompt = prompts[0]!
      terminal.send(`/plan ${firstPrompt}`)
@@ -396,12 +491,93 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
    }

    for (const prompt of remainingPrompts) {
+      const admitted = agent.session.events.filter(event =>
+        event.type === 'user/message' && event.data.source.kind === 'user').length
      terminal.send(prompt)
      terminal.send('\r')
+      await terminal.flush()
+      await expect.poll(() => agent.session.events.filter(event =>
+        event.type === 'user/message' && event.data.source.kind === 'user').length).toBe(admitted + 1)
      await agent.whenIdle()
      await settleTerminal(terminal)
    }

+    if (scenario.manualCompact === true && queuedPrompt !== undefined) {
+      terminal.send('/help')
+      terminal.send('\r')
+      await settleTerminal(terminal)
+      expect(await terminal.snapshot({ includeScrollback: true }))
+        .toContain('/compact — Compact older conversation history')
+
+      const compact = ctx.compact as DeferredSnapshotCompactService
+      const inbox: string[] = []
+      manualOrder = []
+      ctx.on('agent/inbox/enqueue', (subject, item) => {
+        if (subject === agent) inbox.push(`enqueue:${item.placement}:${item.id}`)
+      })
+      ctx.on('agent/inbox/dequeue', (subject, message) => {
+        if (subject === agent) inbox.push(`dequeue:${message.id}`)
+      })
+      ctx.on('session/event', (session, event) => {
+        if (session !== agent.session) return
+        if (event.type === 'command/run' && event.data.name === 'compact') {
+          manualCommandId = event.data.commandId
+          manualOrder?.push('command/run')
+        }
+        if (event.type === 'command/done' && event.data.commandId === manualCommandId) {
+          manualOrder?.push('command/done')
+        }
+        if (event.type.startsWith('compact/')) manualOrder?.push(event.type)
+        if (event.type === 'user/message'
+          && event.data.source.kind === 'plugin'
+          && event.data.source.plugin === 'compact') manualOrder?.push('checkpoint')
+        if (event.type === 'turn/start') manualOrder?.push(`turn/start:${event.data.trigger.kind}`)
+      })
+      ctx.on('session/flush', (session) => {
+        if (session === agent.session) manualOrder?.push('flush')
+      })
+
+      terminal.send('/compact')
+      terminal.send('\r')
+      await terminal.flush()
+      await snapshotDeadline(compact.summaryStarted.promise, () =>
+        `manual summary did not start; status=${agent.status}; tail=${
+          agent.session.events.slice(-8).map(event => event.type).join(',')
+        }`)
+      clock.mockReturnValue(snapshotTime + 1_000)
+      await settleTerminal(terminal)
+      await expect.poll(() => terminal.snapshot()).toContain('dsh ⊙')
+      await expect.poll(() => terminal.snapshot()).toContain('Context being compacted 1.0s')
+      const liveCompaction = await terminal.snapshot()
+      expect(liveCompaction.indexOf('Context being compacted 1.0s')).toBeLessThan(liveCompaction.indexOf('dsh ⊙'))
+      clock.mockReturnValue(snapshotTime)
+
+      // Real keystrokes: the prompt keeps its ordinary queue identity while
+      // admission is reserved, and an injection appends immediately.
+      terminal.send(queuedPrompt)
+      terminal.send('\r')
+      await terminal.flush()
+      await expect.poll(() => inbox.length).toBe(1)
+      agent.inject(createUserMessage({
+        content: [{ type: 'text', text: 'Injected while compaction was running.' }],
+        source: { kind: 'plugin', plugin: 'snapshot-injector' },
+      }))
+      expect(inbox[0]).toMatch(/^enqueue:queued:/u)
+      expect(agent.status).toBe('idle')
+      expect(agent.session.events.some(event => event.type === 'user/message'
+        && event.data.source.kind === 'user'
+        && event.data.content.some(block => block.type === 'text' && block.text === queuedPrompt))).toBe(false)
+
+      const idle = agent.whenIdle()
+      compact.releaseSummary.resolve(undefined)
+      await snapshotDeadline(idle, () =>
+        `manual compaction did not reach idle; status=${agent.status}; order=${manualOrder?.join(',') ?? ''}; tail=${
+          agent.session.events.slice(-12).map(event => event.type).join(',')
+        }`)
+      await settleTerminal(terminal)
+      expect(inbox).toEqual([inbox[0], `dequeue:${inbox[0]?.slice('enqueue:queued:'.length) ?? ''}`])
+    }
+
    const events: SessionEvent[] = [...agent.session.events]
    const firstHeader = events.find(event => event.type === 'request/header')
    expect(firstHeader?.type === 'request/header' && firstHeader.data.header.system)
@@ -437,6 +613,87 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
      expect(events.filter(event => event.type === 'user/message' && event.data.source.kind === 'plugin').map(event => (event.data as { content: unknown }).content))
        .toContainEqual([{ type: 'text', text: 'The user switched this session back to the default mode.' }])
    }
+    if (scenario.manualCompact === true) {
+      const compactStart = events.find(event => event.type === 'compact/start')
+      const compactSummary = events.find(event => event.type === 'compact/summary')
+      const compactCheckpoint = events.find(event => event.type === 'user/message'
+        && event.data.source.kind === 'plugin' && event.data.source.plugin === 'compact')
+      const injectedEvent = events.find(event => event.type === 'user/message'
+        && event.data.source.kind === 'plugin' && event.data.source.plugin === 'snapshot-injector')
+      const compactEnd = events.find(event => event.type === 'compact/end')
+      expect(compactStart?.data.turn).toBeNull()
+      expect(compactEnd?.data.turn).toBeNull()
+      expect(events.filter(event => event.type === 'compact/summary')).toHaveLength(1)
+      if (compactStart === undefined || compactSummary === undefined
+        || compactCheckpoint === undefined || injectedEvent === undefined
+        || compactEnd === undefined) {
+        throw new Error('manual compaction snapshot is missing its durable marker, summary, checkpoint, or injection')
+      }
+      // The markers are time points, not an exclusive container: unrelated
+      // idle injection is allowed between them while the selected span stays stable.
+      expect(compactStart.seq).toBeLessThan(injectedEvent.seq)
+      expect(injectedEvent.seq).toBeLessThan(compactSummary.seq)
+      expect(compactSummary.seq).toBeLessThan(compactCheckpoint.seq)
+      expect(compactCheckpoint.seq).toBeLessThan(compactEnd.seq)
+
+      const manualTimeline = manualOrder ?? []
+      const commandRunIndex = manualTimeline.indexOf('command/run')
+      const compactStartIndex = manualTimeline.indexOf('compact/start')
+      const compactEndIndex = manualTimeline.indexOf('compact/end')
+      const firstFlushIndex = manualTimeline.indexOf('flush')
+      const queuedTurnIndex = manualTimeline.indexOf('turn/start:message')
+      const commandDoneIndex = manualTimeline.indexOf('command/done')
+      expect(manualTimeline.filter(item => item === 'command/run')).toHaveLength(1)
+      expect(manualTimeline.filter(item => item === 'command/done')).toHaveLength(1)
+      expect(compactStartIndex).toBeGreaterThan(commandRunIndex)
+      expect(compactEndIndex).toBeGreaterThan(compactStartIndex)
+      expect(firstFlushIndex).toBeGreaterThan(compactEndIndex)
+      expect(queuedTurnIndex).toBeGreaterThan(firstFlushIndex)
+      expect(commandDoneIndex).toBeGreaterThan(firstFlushIndex)
+
+      const commandRun = events.find(event => event.type === 'command/run'
+        && event.data.name === 'compact')
+      const commandRunId = commandRun?.type === 'command/run'
+        ? commandRun.data.commandId
+        : undefined
+      const commandDone = events.find(event => event.type === 'command/done'
+        && event.data.commandId === commandRunId)
+      expect(commandRun?.type === 'command/run' && commandRun.data).toEqual({
+        commandId: commandRunId,
+        name: 'compact',
+        args: '',
+        source: { kind: 'user' },
+      })
+      expect(commandDone?.type === 'command/done' && commandDone.data).toEqual({
+        commandId: commandRunId,
+        kind: 'success',
+        text: 'Compacted 2 history items (~387 tokens).',
+      })
+      expect(commandRun !== undefined && commandRun.seq < compactStart.seq).toBe(true)
+      expect(commandDone !== undefined && commandDone.seq > compactEnd.seq).toBe(true)
+      expect(agent.session.surface.nodes).not.toContain(commandRun?.seq)
+      expect(agent.session.surface.nodes).not.toContain(commandDone?.seq)
+
+      // The command line itself never becomes a prompt.
+      expect(events.some(event => event.type === 'user/message'
+        && event.data.source.kind === 'user'
+        && event.data.content.some(block => block.type === 'text' && block.text.trim() === '/compact'))).toBe(false)
+      const derived = agent.session.deriveMessages().map(message => message.content
+        .map(block => block.type === 'text' ? block.text : '')
+        .join(''))
+      const checkpoint = derived.findIndex(text => text.includes('Keyless manual compaction checkpoint.'))
+      const injected = derived.findIndex(text => text.includes('Injected while compaction was running.'))
+      const queued = derived.findIndex(text => text === queuedPrompt)
+      expect(checkpoint).toBe(0)
+      expect(injected).toBeGreaterThan(checkpoint)
+      expect(queued).toBeGreaterThan(injected)
+      expect(derived).not.toContain('/compact')
+      expect(derived).not.toContain('Compacted 2 history items (~387 tokens).')
+      expect(derived.filter(text => text.includes('Injected while compaction was running.'))).toHaveLength(1)
+      expect(compactSummary.data.shadowedSeqs).not.toContain(injectedEvent.seq)
+      const queuedTurn = events.findLast(event => event.type === 'turn/start')
+      expect(queuedTurn !== undefined && compactEnd.seq < queuedTurn.seq).toBe(true)
+    }
    if (scenario.spillMaxInlineBytes !== undefined) {
      // The REAL pipeline ran (tools execute on replay too): the durable
      // dispatch copy is bounded to a preview + locator under the run cwd,
@@ -514,7 +771,23 @@ describe('TUI recorded-session terminal snapshots', () => {
 })

 afterAll(async () => {
-  expect([...observedScenarios].sort()).toEqual(SCENARIOS.map(scenario => scenario.name).sort())
+  const scenarioNames = SCENARIOS.map(scenario => scenario.name).sort()
+  const observedNames = [...observedScenarios].sort()
+  if (TEST_NAME_FILTERED) {
+    expect(observedNames).not.toHaveLength(0)
+    expect(scenarioNames).toEqual(expect.arrayContaining(observedNames))
+  } else {
+    expect(observedNames).toEqual(scenarioNames)
+  }
+  for (const [index, scenario] of SCENARIOS.entries()) {
+    if (scenario.fixture === undefined) continue
+    const sourceIndex = SCENARIOS.findIndex(candidate => candidate.name === scenario.fixture)
+    expect(sourceIndex, `${scenario.name} fixture source ${scenario.fixture} must exist`).toBeGreaterThanOrEqual(0)
+    expect(sourceIndex, `${scenario.name} fixture source must precede it`).toBeLessThan(index)
+    const source = SCENARIOS[sourceIndex]
+    expect(source?.fixture, `${scenario.name} fixture source must own its replay files`).toBeUndefined()
+    expect(source?.recorded, `${scenario.name} fixture source must be recordable`).toBe(true)
+  }
  const directories = (await readdir(SNAPSHOTS_DIR, { withFileTypes: true }))
    .filter(entry => entry.isDirectory())
    .map(entry => entry.name)
@@ -522,14 +795,14 @@ afterAll(async () => {
  expect(directories).toEqual(SCENARIOS.map(scenario => scenario.name).sort())
  for (const scenario of SCENARIOS) {
    const expected = [
-      'session.jsonl',
+      ...scenario.fixture === undefined ? ['session.jsonl'] : [],
      'terminal.expected.txt',
-      ...scenario.seedWorkspace === true ? ['workspace'] : [],
+      ...scenario.seedWorkspace === true && scenario.fixture === undefined ? ['workspace'] : [],
      ...Array.from({ length: scenario.childSessions ?? 0 }, (_, index) => `session.${index + 1}.jsonl`),
    ].sort()
    expect((await readdir(scenarioDir(scenario))).sort()).toEqual(expected)
    for (const fixture of ['session.jsonl', ...childFixturePaths(scenario).map(path => basename(path))]) {
-      const content = await readFile(join(scenarioDir(scenario), fixture), 'utf8')
+      const content = await readFile(join(fixtureDir(scenario), fixture), 'utf8')
      expect(scrubRequestHeaders(content), `${scenario.name}/${fixture} carries request-header bulk`).toBe(content)
    }
  }