dsh-loop-engine 0.1.7-rc3 → 0.1.7-rc5

package/README.md

@@ -1,76 +1,77 @@
-# dsh-loop-engine
-
-[![npm version](https://img.shields.io/npm/v/dsh-loop-engine?color=cb3837)](https://www.npmjs.com/package/dsh-loop-engine)
-
-Pick the agent loop engine of **dsh web** the same way you pick a model — **per session**: the built-in `in-process` loop (the default), or one of the four hosted engines `claude-code`, `codex`, `pi`, `kimi`. The engine is the plugin's own per-session record, so **any open, idle session can be moved to another engine** — between two hosted engines it is an **in-place handover**, and a move involving `in-process` releases that session's agent and reloads the page (the `dsh web` process never restarts). Sessions are independent, so one chat can run Codex while another runs Kimi. None of this changes anything in the main repository.
-
-## Install
-
-```sh
-dsh plugin --profile web add dsh-loop-engine
-```
-
-Boot `dsh web` so the profile recomposes with the plugin, then open **Settings → Loop engine**. One boot is enough: the router retries for a bounded window while the base bundle's `agent-loop` row still holds the factory slot.
-
-> Installing rewrites one **engine-agnostic** managed block in `cordis.patch.yml`: it disables the base bundle's `agent-loop` row so the plugin's own router can own the process's single agent-factory slot, and every other byte you wrote in that file is preserved. Upgrading from an earlier release needs no hand edit — a block that named the one pinned engine is rewritten to this form on the next boot, and seeds the Settings default with that engine.
-
-> **pnpm users:** pnpm 10+ blocks dependency build scripts by default, so the install may fail with `ERR_PNPM_IGNORED_BUILDS` naming `esbuild`, `@google/genai`, and `protobufjs` (all reached through the engine SDKs). Allow them and retry — `pnpm approve-builds`, or `allowBuilds` in `pnpm-workspace.yaml`. Only the installing project can grant this; the plugin cannot pre-approve its own dependencies.
-
-### Running against a harness source checkout
-
-A **published** dsh needs no extra setup. Booting the harness from its **source checkout** (`cd deepseek-harness && pnpm dsh web`) takes one more step: bridge the profile's harness peer packages to the checkout source with `file:` shims, so both halves share one module instance (a scope minted through one instance is invisible to the other, and session resume fails with `agent-presets: refusing to compose an unscoped context`). The peer list includes `@deepseek-ai/dsh-agent-loop`. The runnable shim steps are in [docs/source-checkout.md](docs/source-checkout.md); why every `@deepseek-ai/*` package must stay a single instance is in [docs/architecture.md](docs/architecture.md). Installing the plugin as a local **`link:`** checkout sidesteps this entirely.
-
-## Version compatibility
-
-dsh-loop-engine is versioned **in lockstep with the harness it targets**: `<harness version>-rcN`. From `0.1.7-rc1` on, **one release serves two harness generations**: the 0.1.5 line (`>=0.1.5-rc.1 <0.1.6-0`, all sharing the old settings API) and the 0.1.7 line (`>=0.1.7-rc.1 <0.1.8-0`, whose `rc.1` and `rc.2` are both verified). It detects the running generation at load and takes the matching code path, so a single published package installs onto either. Every harness package it consumes declares that union range in `peerDependencies`; a harness outside it fails loudly at boot or session resume. Within a covered line a new `rc` needs no plugin release unless the API surfaces it depends on moved — `docs/compatibility.md` §1 lists the surfaces and the diff command that decides it. `0.1.5-rc3` … `0.1.5-rc5` target harness `0.1.5-rc.2`; `0.1.5-rc1`/`0.1.5-rc2` target `0.1.5-rc.1`; `1.0.0-rc8` … `1.0.0-rc15` target `0.1.2-rc.1`; `1.0.0-rc7` and earlier target `0.1.1-rc.2`.
-
-### Requirements
-
-- **Claude Code**: the Claude Code CLI installed and logged in on the host.
-- **Codex**: authenticated via `codex login` on the host, or a `CODEX_API_KEY` environment entry.
-- **Pi**: authenticated the way `pi` expects (its own `~/.pi/agent/auth.json`, or the provider's API-key environment variable such as `ANTHROPIC_API_KEY`).
-- **Kimi Code**: the `kimi` CLI installed and logged in (e.g. `kimi login`), and reachable on `PATH` (or pinned to an absolute path via `kimiBin` in the composition entry).
-- Running the harness from a source checkout needs the extra `dsh-agent-loop` `file:` shim above.
-
-## Usage
-
-**The engine is chosen per session.** Pick `Claude Code`, `Codex`, `Pi`, or `Kimi Code` on the new-session screen's preset chip (beside the workspace picker); keep the deployment's own default (usually `standard`) to run the built-in in-process loop. Different sessions can run different engines at the same time, and a child agent inherits the engine of the agent that spawned it.
-
-- **Settings → Loop engine** sets the default for **new** sessions only — it lands immediately, with no restart and no page reload, and sessions already running are unaffected. Choosing **In-process** restores whatever default the plugin replaced.
-- **Moving a session you are in** uses the composer's engine selector (enable *Show the engine selector in the chat page*), which calls the plugin's own `remote.loopEngine.select`. Any open, idle session can move — including one that has already run many turns.
-  - **Between two hosted engines the move is an in-place handover**: the session stays open, only the agent is replaced — it applies on the spot, with nothing to confirm.
-  - **A move involving `in-process` cannot be handed over in place** (the harness loop neither accepts a session it did not create nor hands a live one over), so the composer asks first: the switch reloads the page, and this page's scroll position and unsent draft go with it (the conversation record does not). On confirm the host RELEASES that session's agent and answers `reload: true`; the page reloads itself and reopens the same session, which is what makes the host build it on the recorded engine. The process never restarts.
-  - A session that is **mid-turn is refused** rather than interrupted, and a **subagent's** session cannot be moved at all.
-- **Models**: every hosted engine shares ONE `external` group in the model menu, holding exactly one entry, `default` — meaning "the engine decides". Picking a **real dsh model** hands it to the engine **with its endpoint and credential** (whether the engine can serve it is the engine's business — a refusal is reported, not swallowed). `in-process` sessions use dsh's models as usual.
-- **Uninstall**: `dsh plugin --profile web remove dsh-loop-engine`, then manually delete the plugin's managed block from the profile's `cordis.patch.yml` — the block outlives the plugin, and while it is present the base `agent-loop` row stays disabled, leaving the profile with no agent factory.
-
-### What a hosted engine takes over
-
-- Its preset is a copy of `standard` minus the dsh-native rows an external engine replaces — dsh's `/plan`, `/compact` (and auto-compaction), the model-facing goal tool, the human `/goal` command, and the dsh skill rows (one stripped preset per engine, under `$DSH_HOME/.agent-presets/loop-engine-<engine>/`).
-- The engine's own slash commands and skill catalog are registered into **that agent's own scope**, so two sessions on different engines never see each other's menus, and the whole surface is released with the agent.
-- Engine-agnostic dsh commands (`/export`, `/feedback`, `/permission`) keep working and stay.
-
-## Known limitations
-
-- **The engine record lives in the plugin's sidecar, `$DSH_HOME/.loop-engine/engines.json`, not in the session log.** Changing machine or `DSH_HOME` loses it, and the session falls back gracefully to the preset mapping. See [docs/per-session-engine.md](docs/per-session-engine.md) §5.5 and [docs/architecture.md](docs/architecture.md) §3.9.
-- **A move involving `in-process` reloads the page**, because the harness loop neither hands over a live session nor adopts one it did not create. See [docs/per-session-engine.md](docs/per-session-engine.md) §5.2/§5.4.
-- **The engine is settled at session creation / blank period**; once a turn has run, changing engines rebuilds that session's agent (idle only). See [docs/per-session-engine.md](docs/per-session-engine.md) §5.
-- **Old sessions carrying the legacy single preset id (`loop-engine`)** show as "legacy hosted engine" and need one rebuild before the new semantics take over. See [docs/per-session-engine.md](docs/per-session-engine.md) §7.
-- **Under a hosted engine a dsh model pick matters only if you pick a real dsh model** — `default` means "hand it back to the engine". See [docs/per-session-engine.md](docs/per-session-engine.md) §5.2.
-- **Same-engine sessions share that CLI's own auth directory**, with no lock added by the plugin. See [docs/per-session-engine.md](docs/per-session-engine.md) §6.
-- **Switching to `in-process` leaves the shared `external` provider group in the model menu** (the catalog is not scoped per session). See [docs/architecture.md](docs/architecture.md) §3.6.
-
-## Where the details live
-
-- [docs/per-session-engine.md](docs/per-session-engine.md) — the full user-visible behavior of per-session engines.
-- [docs/source-checkout.md](docs/source-checkout.md) — the `file:` shims a source-launched harness needs.
-- [docs/architecture.md](docs/architecture.md) — plugin core: the single factory slot, the managed block, routing, per-session engine facts, the provider route.
-- [docs/compatibility.md](docs/compatibility.md) — **start here when the harness upgrades**: every generation-dependent code site, the four techniques for spanning them, and the checklist for adding the next generation.
-- [docs/driver-core.md](docs/driver-core.md) — the shared driver infrastructure.
-- [docs/engine-claude.md](docs/engine-claude.md), [docs/engine-codex.md](docs/engine-codex.md), [docs/engine-kimi.md](docs/engine-kimi.md), [docs/engine-pi.md](docs/engine-pi.md) — per-engine internals.
-- [docs/optimization-backlog.md](docs/optimization-backlog.md) — known issues and the optimization list.
-- [docs/proposals/](docs/proposals/) — main-repo proposals: `append-ignorable-events.md`, `harness-agent-handover.md`, and the two model-selection ones (`dsh-model-into-hosted-engines.md`, `per-session-model-for-hosted-engines.md`).
-
-## License
-
-MIT
+# dsh-loop-engine
+
+[![npm version](https://img.shields.io/npm/v/dsh-loop-engine?color=cb3837)](https://www.npmjs.com/package/dsh-loop-engine)
+
+Pick the agent loop engine of **dsh web** the same way you pick a model — **per session**: the built-in `in-process` loop (the default), or one of the four hosted engines `claude-code`, `codex`, `pi`, `kimi`. The engine is the plugin's own per-session record, so **any open, idle session can be moved to another engine** — between two hosted engines it is an **in-place handover**, and a move involving `in-process` releases that session's agent and reloads the page (the `dsh web` process never restarts). Sessions are independent, so one chat can run Codex while another runs Kimi. None of this changes anything in the main repository.
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-loop-engine
+```
+
+Boot `dsh web` so the profile recomposes with the plugin, then open **Settings → Loop engine**. One boot is enough: the router retries for a bounded window while the base bundle's `agent-loop` row still holds the factory slot.
+
+> Installing rewrites one **engine-agnostic** managed block in `cordis.patch.yml`: it disables the base bundle's `agent-loop` row so the plugin's own router can own the process's single agent-factory slot, and every other byte you wrote in that file is preserved. Upgrading from an earlier release needs no hand edit — a block that named the one pinned engine is rewritten to this form on the next boot, and seeds the Settings default with that engine.
+
+> **pnpm users:** pnpm 10+ blocks dependency build scripts by default, so the install may fail with `ERR_PNPM_IGNORED_BUILDS` naming `esbuild`, `@google/genai`, and `protobufjs` (all reached through the engine SDKs). Allow them and retry — `pnpm approve-builds`, or `allowBuilds` in `pnpm-workspace.yaml`. Only the installing project can grant this; the plugin cannot pre-approve its own dependencies.
+
+### Running against a harness source checkout
+
+A **published** dsh needs no extra setup. Booting the harness from its **source checkout** (`cd deepseek-harness && pnpm dsh web`) takes one more step: bridge the profile's harness peer packages to the checkout source with `file:` shims, so both halves share one module instance (a scope minted through one instance is invisible to the other, and session resume fails with `agent-presets: refusing to compose an unscoped context`). The peer list includes `@deepseek-ai/dsh-agent-loop`. The runnable shim steps are in [docs/source-checkout.md](docs/source-checkout.md); why every `@deepseek-ai/*` package must stay a single instance is in [docs/architecture.md](docs/architecture.md). Installing the plugin as a local **`link:`** checkout sidesteps this entirely.
+
+## Version compatibility
+
+dsh-loop-engine is versioned **in lockstep with the harness it targets**: `<harness version>-rcN`. From `0.1.7-rc1` on, **one release serves two harness generations**: the 0.1.5 line (`>=0.1.5-rc.1 <0.1.6-0`, all sharing the old settings API) and the 0.1.7 line (`>=0.1.7-rc.1 <0.1.8-0`, whose `rc.1` and `rc.2` are both verified). It detects the running generation at load and takes the matching code path, so a single published package installs onto either. Every harness package it consumes declares that union range in `peerDependencies`; a harness outside it fails loudly at boot or session resume. Within a covered line a new `rc` needs no plugin release unless the API surfaces it depends on moved — `docs/compatibility.md` §1 lists the surfaces and the diff command that decides it. Read `rcN` as **this plugin's own release counter for that harness line**, not as the harness's `rc` number (`0.1.7-rc1` … `0.1.7-rc5` all serve `0.1.7-rc.1` and `0.1.7-rc.2`). `0.1.7-rc1` … `0.1.7-rc5` target harness `0.1.7-rc.2`; `0.1.5-rc3` … `0.1.5-rc5` target harness `0.1.5-rc.2`; `0.1.5-rc1`/`0.1.5-rc2` target `0.1.5-rc.1`; `1.0.0-rc8` … `1.0.0-rc15` target `0.1.2-rc.1`; `1.0.0-rc7` and earlier target `0.1.1-rc.2`.
+
+### Requirements
+
+- **Claude Code**: the Claude Code CLI installed and logged in on the host.
+- **Codex**: authenticated via `codex login` on the host, or a `CODEX_API_KEY` environment entry.
+- **Pi**: authenticated the way `pi` expects (its own `~/.pi/agent/auth.json`, or the provider's API-key environment variable such as `ANTHROPIC_API_KEY`).
+- **Kimi Code**: the `kimi` CLI installed and logged in (e.g. `kimi login`), and reachable on `PATH` (or pinned to an absolute path via `kimiBin` in the composition entry).
+- Running the harness from a source checkout needs the extra `dsh-agent-loop` `file:` shim above.
+
+## Usage
+
+**The engine is chosen per session.** Pick `Claude Code`, `Codex`, `Pi`, or `Kimi Code` on the new-session screen's preset chip (beside the workspace picker); keep the deployment's own default (usually `standard`) to run the built-in in-process loop. Different sessions can run different engines at the same time, and a child agent inherits the engine of the agent that spawned it.
+
+- **Settings → Loop engine** sets the default for **new** sessions only — it lands immediately, with no restart and no page reload, and sessions already running are unaffected. Choosing **In-process** restores whatever default the plugin replaced.
+- **Moving a session you are in** uses the composer's engine selector (enable *Show the engine selector in the chat page*), which calls the plugin's own `remote.loopEngine.select`. Any open, idle session can move — including one that has already run many turns.
+  - **Between two hosted engines the move is an in-place handover**: the session stays open, only the agent is replaced — it applies on the spot, with nothing to confirm.
+  - **A move involving `in-process` cannot be handed over in place** (the harness loop neither accepts a session it did not create nor hands a live one over), so the composer asks first: the switch reloads the page, and this page's scroll position and unsent draft go with it (the conversation record does not). On confirm the host RELEASES that session's agent and answers `reload: true`; the page reloads itself and reopens the same session, which is what makes the host build it on the recorded engine. The process never restarts.
+  - A session that is **mid-turn is refused** rather than interrupted, and a **subagent's** session cannot be moved at all.
+- **Models**: every hosted engine shares ONE `external` group in the model menu, holding exactly one entry, `default` — meaning "the engine decides". Picking a **real dsh model** hands it to the engine **with its endpoint and credential** (whether the engine can serve it is the engine's business — a refusal is reported, not swallowed). `in-process` sessions use dsh's models as usual.
+- **Uninstall**: `dsh plugin --profile web remove dsh-loop-engine`, then manually delete the plugin's managed block from the profile's `cordis.patch.yml` — the block outlives the plugin, and while it is present the base `agent-loop` row stays disabled, leaving the profile with no agent factory.
+
+### What a hosted engine takes over
+
+- Its preset is a copy of `standard` minus the dsh-native rows an external engine replaces — dsh's `/plan`, `/compact` (and auto-compaction), the model-facing goal tool, the human `/goal` command, and the dsh skill rows (one stripped preset per engine). The preset is a harness-generation-dependent artifact: a directory under `$DSH_HOME/.agent-presets/loop-engine-<engine>/` on the 0.1.5 line, and an `@deepseek-ai/dsh-agent-preset` row inserted into the profile patch on the 0.1.7 line, which no longer reads that directory. See [docs/architecture.md](docs/architecture.md) §3.5.
+- The engine's own slash commands and skill catalog are registered into **that agent's own scope**, so two sessions on different engines never see each other's menus, and the whole surface is released with the agent.
+- **Kimi Code and Codex keep ONE child process per session** (`kimi acp` / `codex app-server`), reused across steps — that is what saves a spawn per step, and it also means a session that finished a turn and is left alone keeps paying for that process (the harness does not release an agent at turn end). Claude Code and Pi spawn per step and hold nothing. Set `childIdleMs` (milliseconds) in the composition entry — the plugin's row in the profile's `cordis.patch.yml` — to shut an idle session's child down, respawning it on the next step; `0` or omitted keeps the child for the session's whole life, which is the default. It closes the child only: the agent, the session, and the page are untouched, so nothing reloads and `session/disposed` is never emitted. See [docs/driver-core.md](docs/driver-core.md) §7.8.
+- Engine-agnostic dsh commands (`/export`, `/feedback`, `/permission`) keep working and stay.
+
+## Known limitations
+
+- **The engine record lives in the plugin's sidecar, `$DSH_HOME/.loop-engine/engines.json`, not in the session log.** Changing machine or `DSH_HOME` loses it, and the session falls back gracefully to the preset mapping. See [docs/per-session-engine.md](docs/per-session-engine.md) §5.5 and [docs/architecture.md](docs/architecture.md) §3.9.
+- **A move involving `in-process` reloads the page**, because the harness loop neither hands over a live session nor adopts one it did not create. See [docs/per-session-engine.md](docs/per-session-engine.md) §5.2/§5.4.
+- **The engine is settled at session creation / blank period**; once a turn has run, changing engines rebuilds that session's agent (idle only). See [docs/per-session-engine.md](docs/per-session-engine.md) §5.
+- **Old sessions carrying the legacy single preset id (`loop-engine`)** show as "legacy hosted engine" and need one rebuild before the new semantics take over. See [docs/per-session-engine.md](docs/per-session-engine.md) §7.
+- **Under a hosted engine a dsh model pick matters only if you pick a real dsh model** — `default` means "hand it back to the engine". See [docs/per-session-engine.md](docs/per-session-engine.md) §5.2.
+- **Same-engine sessions share that CLI's own auth directory**, with no lock added by the plugin. See [docs/per-session-engine.md](docs/per-session-engine.md) §6.
+- **Switching to `in-process` leaves the shared `external` provider group in the model menu** (the catalog is not scoped per session). See [docs/architecture.md](docs/architecture.md) §3.6.
+
+## Where the details live
+
+- [docs/per-session-engine.md](docs/per-session-engine.md) — the full user-visible behavior of per-session engines.
+- [docs/source-checkout.md](docs/source-checkout.md) — the `file:` shims a source-launched harness needs.
+- [docs/architecture.md](docs/architecture.md) — plugin core: the single factory slot, the managed block, routing, per-session engine facts, the provider route.
+- [docs/compatibility.md](docs/compatibility.md) — **start here when the harness upgrades**: every generation-dependent code site, the four techniques for spanning them, and the checklist for adding the next generation.
+- [docs/driver-core.md](docs/driver-core.md) — the shared driver infrastructure.
+- [docs/engine-claude.md](docs/engine-claude.md), [docs/engine-codex.md](docs/engine-codex.md), [docs/engine-kimi.md](docs/engine-kimi.md), [docs/engine-pi.md](docs/engine-pi.md) — per-engine internals.
+- [docs/optimization-backlog.md](docs/optimization-backlog.md) — known issues and the optimization list.
+- [docs/proposals/](docs/proposals/) — main-repo proposals: `append-ignorable-events.md`, `harness-agent-handover.md`, and the two model-selection ones (`dsh-model-into-hosted-engines.md`, `per-session-model-for-hosted-engines.md`).
+
+## License
+
+MIT

package/README.zh.md

@@ -22,7 +22,7 @@ dsh plugin --profile web add dsh-loop-engine
 
 ## 版本兼容
 
-`dsh-loop-engine` 与它针对的 harness **同版本对齐**:`<harness version>-rcN`。自 `0.1.7-rc1` 起,**一个发布版本同时服务两代 harness**:0.1.5 线(`>=0.1.5-rc.1 <0.1.6-0`,三段 `rc` 共用同一套旧 settings API)与 0.1.7 线(`>=0.1.7-rc.1 <0.1.8-0`,其中 `rc.1` 与 `rc.2` 都已核对)。它在加载期探测当前是哪一代、走对应分支,所以同一份已发布产物在两代上都能安装运行。它消费的每个 harness 包都在 `peerDependencies` 里声明这个并集范围;超出范围会在启动或会话恢复时响亮地失败。在被覆盖的那条线里,新的 `rc` **不需要**插件跟版——除非它依赖的 API 面动了;`docs/compatibility.md` §1 列出了这些面与"要不要改代码"的那条判定命令。`0.1.5-rc3` … `0.1.5-rc5` 针对 harness `0.1.5-rc.2`;`0.1.5-rc1`/`0.1.5-rc2` 针对 `0.1.5-rc.1`;`1.0.0-rc8` … `1.0.0-rc15` 针对 `0.1.2-rc.1`;`1.0.0-rc7` 及更早针对 `0.1.1-rc.2`。
+`dsh-loop-engine` 与它针对的 harness **同版本对齐**:`<harness version>-rcN`。自 `0.1.7-rc1` 起,**一个发布版本同时服务两代 harness**:0.1.5 线(`>=0.1.5-rc.1 <0.1.6-0`,三段 `rc` 共用同一套旧 settings API)与 0.1.7 线(`>=0.1.7-rc.1 <0.1.8-0`,其中 `rc.1` 与 `rc.2` 都已核对)。它在加载期探测当前是哪一代、走对应分支,所以同一份已发布产物在两代上都能安装运行。它消费的每个 harness 包都在 `peerDependencies` 里声明这个并集范围;超出范围会在启动或会话恢复时响亮地失败。在被覆盖的那条线里,新的 `rc` **不需要**插件跟版——除非它依赖的 API 面动了;`docs/compatibility.md` §1 列出了这些面与"要不要改代码"的那条判定命令。`rcN` 读作**本插件对那条 harness 线的第 N 次发布号**,不是 harness 自己的 `rc` 号(`0.1.7-rc1` … `0.1.7-rc5` 都服务 `0.1.7-rc.1` 与 `0.1.7-rc.2`)。`0.1.7-rc1` … `0.1.7-rc5` 针对 harness `0.1.7-rc.2`;`0.1.5-rc3` … `0.1.5-rc5` 针对 harness `0.1.5-rc.2`;`0.1.5-rc1`/`0.1.5-rc2` 针对 `0.1.5-rc.1`;`1.0.0-rc8` … `1.0.0-rc15` 针对 `0.1.2-rc.1`;`1.0.0-rc7` 及更早针对 `0.1.1-rc.2`。
 
 ### 环境要求
 
@@ -46,7 +46,7 @@ dsh plugin --profile web add dsh-loop-engine
 
 ### 托管引擎接管什么
 
-- 它的预设是 `standard` 的副本,去掉了外部引擎会替代掉的 dsh 原生行——dsh 的 `/plan`、`/compact`(与自动压缩)、模型可见的 goal 工具、人类 `/goal` 命令、以及 dsh skill 行(每引擎一份剥离后的 preset,位于 `$DSH_HOME/.agent-presets/loop-engine-<engine>/`)。
+- 它的预设是 `standard` 的副本,去掉了外部引擎会替代掉的 dsh 原生行——dsh 的 `/plan`、`/compact`(与自动压缩)、模型可见的 goal 工具、人类 `/goal` 命令、以及 dsh skill 行(每引擎一份剥离后的 preset)。preset 的**载体随 harness 代际而变**:0.1.5 上是 `$DSH_HOME/.agent-presets/loop-engine-<engine>/` 目录,0.1.7 上是插进 profile patch 的一行 `@deepseek-ai/dsh-agent-preset`(0.1.7 已不再读那个目录)。详见 [docs/architecture.md](docs/architecture.md) §3.5。
 - 引擎自己的斜杠命令与技能目录会注册进**这个 agent 自己的 scope**,因此两个跑不同引擎的会话互相看不到对方的菜单,整份表面随 agent 一起回收。
 - 与引擎无关的 dsh 命令(`/export`、`/feedback`、`/permission`)照常可用、保留在菜单里。
 

package/lib/index.js

@@ -2389,6 +2389,34 @@ import { LlmError as LlmError3, createAssistantMessage as createAssistantMessage
 import { createScope as createScope2 } from "@deepseek-ai/dsh-scope";
 import { canonicalHeader as canonicalHeader2 } from "@deepseek-ai/dsh-session";
 
+// src/driver-core/idle-child.ts
+function createIdleChildCloser(options) {
+  const { idleMs, close, warn } = options;
+  let timer;
+  const cancel = () => {
+    if (timer === void 0) return;
+    clearTimeout(timer);
+    timer = void 0;
+  };
+  return {
+    arm: () => {
+      if (!(idleMs > 0)) return;
+      cancel();
+      timer = setTimeout(() => {
+        timer = void 0;
+        try {
+          close();
+        } catch (error) {
+          warn(`loop-engine: idle shutdown failed to close a child process: ${String(error)}`);
+        }
+      }, idleMs);
+      timer.unref?.();
+    },
+    cancel,
+    dispose: cancel
+  };
+}
+
 // src/engine-codex/model-handover.ts
 var CODEX_DSH_PROVIDER = "dsh";
 var CODEX_DSH_API_KEY_ENV = "DSH_LOOP_ENGINE_API_KEY";
@@ -2928,9 +2956,18 @@ var CodexAgent = class {
     this.phase = { kind: "idle", lastTurn };
     this.scope = createScope2(loopCtx, this);
     this.ctx = this.scope.ctx.extend({ agent: this });
+    this.idleChild = createIdleChildCloser({
+      idleMs: this.config.childIdleMs,
+      close: () => {
+        this.closeChild();
+      },
+      warn: (message) => {
+        loopCtx.logger.warn(message);
+      }
+    });
     this.scope.ctx.effect(() => () => {
-      this.appServer?.dispose();
-      this.appServer = void 0;
+      this.idleChild.dispose();
+      this.closeChild();
     }, "codex.appServerClient()");
   }
   loopCtx;
@@ -2982,6 +3019,17 @@ var CodexAgent = class {
    * must respawn the child rather than reuse one configured for another endpoint.
    */
   appServerConfig;
+  /**
+   * Countdown that shuts the child down once this agent has been idle past the
+   * configured window, so an idle session stops paying for a process nothing
+   * is driving. Armed and cancelled by {@link setPhase}.
+   */
+  idleChild;
+  /** Shut the cached child down; the next step's {@link appServerClient} spawns a fresh one. */
+  closeChild() {
+    this.appServer?.dispose();
+    this.appServer = void 0;
+  }
   /**
    * Return the cached app-server client, spawning one on first use, after a dead
    * process, or when the resolved dsh endpoint changed since the last spawn.
@@ -3075,6 +3123,8 @@ var CodexAgent = class {
   setPhase(next) {
     const previousStatus = this.status;
     this.phase = next;
+    if (next.kind === "idle") this.idleChild.arm();
+    else this.idleChild.cancel();
     const status = this.status;
     if (status !== previousStatus) {
       this.dispatch.emit("agent/status", { status });
@@ -3610,14 +3660,16 @@ var Config2 = z2.object({
   sandboxMode: z2.union([...CODEX_SANDBOX_MODES]),
   approvalPolicy: z2.union([...CODEX_APPROVAL_POLICIES]),
   env: z2.dict(z2.string()).default({}),
-  model: z2.string()
+  model: z2.string(),
+  childIdleMs: z2.number()
 });
 function resolveConfig2(config) {
   return {
     sandboxMode: config.sandboxMode,
     approvalPolicy: config.approvalPolicy,
     env: config.env ?? {},
-    model: config.model
+    model: config.model,
+    childIdleMs: config.childIdleMs ?? 0
   };
 }
 var CODEX_ENGINE_LABEL = "agentLoopCodex";
@@ -5122,9 +5174,18 @@ var KimiAgent = class {
     this.phase = { kind: "idle", lastTurn };
     this.scope = createScope4(loopCtx, this);
     this.ctx = this.scope.ctx.extend({ agent: this });
+    this.idleChild = createIdleChildCloser({
+      idleMs: this.config.childIdleMs,
+      close: () => {
+        this.closeChild();
+      },
+      warn: (message) => {
+        loopCtx.logger.warn(message);
+      }
+    });
     this.scope.ctx.effect(() => () => {
-      this.acp?.dispose();
-      this.acp = void 0;
+      this.idleChild.dispose();
+      this.closeChild();
     }, "kimi.acpClient()");
   }
   loopCtx;
@@ -5157,6 +5218,17 @@ var KimiAgent = class {
    * every step.
    */
   handoverEnvCache;
+  /**
+   * Countdown that shuts the child down once this agent has been idle past the
+   * configured window, so an idle session stops paying for a process nothing
+   * is driving. Armed and cancelled by {@link setPhase}.
+   */
+  idleChild;
+  /** Shut the cached child down; the next step's {@link acpClient} spawns a fresh one. */
+  closeChild() {
+    this.acp?.dispose();
+    this.acp = void 0;
+  }
   get status() {
     return this.phase.kind === "idle" || this.phase.kind === "maintenance" ? "idle" : "running";
   }
@@ -5164,6 +5236,8 @@ var KimiAgent = class {
   setPhase(next) {
     const previousStatus = this.status;
     this.phase = next;
+    if (next.kind === "idle") this.idleChild.arm();
+    else this.idleChild.cancel();
     const status = this.status;
     if (status !== previousStatus) {
       this.dispatch.emit("agent/status", { status });
@@ -5732,13 +5806,15 @@ var KIMI_DISPOSE_GRACE_MS = 3e3;
 var Config4 = z4.object({
   model: z4.string(),
   env: z4.dict(z4.string()).default({}),
-  bin: z4.string()
+  bin: z4.string(),
+  childIdleMs: z4.number()
 });
 function resolveConfig4(config) {
   return {
     model: config.model,
     env: config.env ?? {},
-    bin: kimiBinResolver(config.bin)
+    bin: kimiBinResolver(config.bin),
+    childIdleMs: config.childIdleMs ?? 0
   };
 }
 var KIMI_ENGINE_LABEL = "agentLoopKimi";
@@ -5856,6 +5932,64 @@ var MANAGED_HEADER = `# Managed by dsh-loop-engine: the deployment's "${SOURCE_P
 # from "${SOURCE_PRESET_ID}" on boot \u2014 hand edits are overwritten. The preset id
 # names the engine this session runs.
 `;
+var PRESET_ROWS_BEGIN = "# -- dsh-loop-engine presets --";
+var PRESET_ROWS_END = "# -- /dsh-loop-engine presets --";
+var ENGINE_PRESET_ORDER = 100;
+var PLUGIN_LIST_INDENT = " ".repeat(10);
+function pluginListLines(composition) {
+  const text = composition.replace(/\n+$/, "");
+  const lines = text.split("\n");
+  if (!lines.some((line) => line.startsWith("- "))) return ["        plugins: []"];
+  return ["        plugins:", ...lines.map((line) => line.trim() === "" ? "" : `${PLUGIN_LIST_INDENT}${line}`)];
+}
+function renderEnginePresetRow(engine, composition) {
+  const id = enginePresetId(engine);
+  return [
+    "- insert:",
+    `    - id: preset-${id}`,
+    `      name: '@deepseek-ai/dsh-agent-preset'`,
+    "      config:",
+    `        id: ${id}`,
+    `        order: ${ENGINE_PRESET_ORDER}`,
+    ...pluginListLines(stripPresetRows(composition))
+  ].join("\n");
+}
+function renderPresetRows(composition) {
+  return [
+    PRESET_ROWS_BEGIN,
+    "# One `@deepseek-ai/dsh-agent-preset` declaration per hosted engine: the",
+    `# deployment's "${SOURCE_PRESET_ID}" preset minus the dsh-native command/skill rows a`,
+    `# hosted loop engine replaces. Regenerated from "${SOURCE_PRESET_ID}" on boot \u2014 hand`,
+    "# edits are overwritten. The preset id names the engine a session runs.",
+    ...HOSTED_ENGINE_IDS.map((engine) => renderEnginePresetRow(engine, composition)),
+    `${PRESET_ROWS_END}
+`
+  ].join("\n");
+}
+function presetRowsSpan(text) {
+  const begin = text.indexOf(PRESET_ROWS_BEGIN);
+  if (begin === -1) return { head: text, tail: "", present: false, blankBefore: false };
+  const endAt = text.indexOf(PRESET_ROWS_END, begin);
+  const spanEnd = endAt === -1 ? text.length : endAt + PRESET_ROWS_END.length + 1;
+  const before = text.slice(0, begin);
+  const blankBefore = before.endsWith("\n\n");
+  return {
+    head: blankBefore ? before.slice(0, -1) : before,
+    tail: text.slice(spanEnd),
+    present: true,
+    blankBefore
+  };
+}
+function applyEnginePresetRows(text, composition) {
+  const region = renderPresetRows(composition);
+  const span = presetRowsSpan(text);
+  if (!span.present) {
+    if (text === "") return region;
+    return dropSeedPlaceholder(`${ensureTrailingNewline(text)}
+${region}`);
+  }
+  return dropSeedPlaceholder(`${span.head}${span.blankBefore ? "\n" : ""}${region}${span.tail}`);
+}
 function managedMetadata(engine) {
   return `name: ${ENGINE_DISPLAY_NAMES[engine]}
 description: ${ENGINE_DISPLAY_NAMES[engine]}, with the dsh-native commands and skills it replaces removed.
@@ -5937,6 +6071,18 @@ ${stripPresetRows(composition)}`;
   }
   return changed;
 }
+async function readTextOrEmpty(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+async function ensureEnginePresetRows(patchPath, source) {
+  const composition = await readComposition(source, SOURCE_PRESET_ID);
+  const current = await readTextOrEmpty(patchPath);
+  return writeIfDifferent(patchPath, applyEnginePresetRows(current, composition));
+}
 
 // src/router-loop.ts
 import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from "@deepseek-ai/dsh-agent-loop";
@@ -7428,6 +7574,7 @@ var Config5 = z6.object({
   piProvider: z6.string(),
   piThinking: z6.string(),
   kimiBin: z6.string(),
+  childIdleMs: z6.number(),
   // The live fields exist only on the 0.1.7 line; the 0.1.5 line carries the
   // selection in a settings section instead. The empty arm never runs when the
   // coverage job is on 0.1.7; the 0.1.5 dep set is exercised by
@@ -7444,6 +7591,10 @@ function resolvePatchPath(config) {
     config.patchFilename ?? "cordis.patch.yml"
   );
 }
+function authorHostedPresets(patchPath, presets) {
+  if (LEGACY_HARNESS) return ensureEnginePresets(resolveDshHome2(), presets);
+  return ensureEnginePresetRows(patchPath, presets);
+}
 function isMissing2(error) {
   return error?.code === "ENOENT";
 }
@@ -7494,7 +7645,8 @@ function codexConfig(config) {
     ...config.sandboxMode === void 0 ? {} : { sandboxMode: config.sandboxMode },
     ...config.approvalPolicy === void 0 ? {} : { approvalPolicy: config.approvalPolicy },
     ...config.env === void 0 ? {} : { env: config.env },
-    ...config.model === void 0 ? {} : { model: config.model }
+    ...config.model === void 0 ? {} : { model: config.model },
+    ...config.childIdleMs === void 0 ? {} : { childIdleMs: config.childIdleMs }
   };
 }
 function piConfig(config) {
@@ -7510,7 +7662,8 @@ function kimiConfig(config) {
   return {
     ...config.model === void 0 ? {} : { model: config.model },
     ...config.env === void 0 ? {} : { env: config.env },
-    ...config.kimiBin === void 0 ? {} : { bin: config.kimiBin }
+    ...config.kimiBin === void 0 ? {} : { bin: config.kimiBin },
+    ...config.childIdleMs === void 0 ? {} : { childIdleMs: config.childIdleMs }
   };
 }
 function apply(ctx, config) {
@@ -7611,7 +7764,7 @@ function apply(ctx, config) {
       let lastError;
       for (let attempt2 = 0; attempt2 <= PRESET_SOURCE_ATTEMPTS; attempt2 += 1) {
         try {
-          return await ensureEnginePresets(resolveDshHome2(), presets);
+          return await authorHostedPresets(patchPath, presets);
         } catch (error) {
           lastError = error;
           if (attempt2 < PRESET_SOURCE_ATTEMPTS) {

package/lib/types/driver-core/idle-child.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Idle shutdown for a driver's persistent child process.
+ *
+ * Two engines keep one child alive per session so a step never pays a spawn:
+ * Kimi's `kimi acp` and Codex's app-server. Nothing in the harness releases an
+ * agent when a turn ends — an agent lives as long as its session's scope — so
+ * that child outlives the work that needed it and an idle session keeps
+ * costing what its child costs (tens to hundreds of MB for a Node CLI). The
+ * closer arms a countdown whenever its owner goes idle and runs the owner's
+ * close when the countdown expires, so the next step's own lazy accessor
+ * spawns a fresh child.
+ *
+ * The closer is inert unless `idleMs` is positive: a deployment that does not
+ * configure idle shutdown keeps every child for the process's lifetime, which
+ * is the behaviour that predates this reasoner.
+ *
+ * This is deliberately NOT an agent release: disposing the agent emits
+ * `session/disposed`, which the browser half reads as "this session is gone"
+ * with no way back in that page's lifetime (`router-loop.ts` `move`). Closing
+ * the child leaves the agent, the session, and the page exactly where they are.
+ *
+ * @module dsh-loop-engine/driver-core/idle-child
+ */
+/** An armed-on-idle countdown that closes one child process. */
+export interface IdleChildCloser {
+    /**
+     * (Re)start the countdown. Called when the owner settles into an idle phase;
+     * a no-op while idle shutdown is disabled.
+     */
+    arm(): void;
+    /**
+     * Cancel a pending countdown, for the moment the child is needed again.
+     * Cancelling a countdown that never armed is a no-op.
+     */
+    cancel(): void;
+    /**
+     * Cancel the countdown and drop the timer. Called from the owner's teardown,
+     * so a disposed agent never closes a child through a stale callback.
+     */
+    dispose(): void;
+}
+/** Input of {@link createIdleChildCloser}. */
+export interface IdleChildCloserOptions {
+    /** Idle window in milliseconds; zero or less leaves the child alone forever. */
+    readonly idleMs: number;
+    /** Close the child; the owner's next accessor call spawns a fresh one. */
+    readonly close: () => void;
+    /** Report a failing close without letting it escape the countdown. */
+    readonly warn: (message: string) => void;
+}
+/**
+ * Build one owner's idle countdown.
+ * @param options - the idle window, the close to run, and a diagnostic sink.
+ * @returns the closer, inert while the idle window is not positive.
+ */
+export declare function createIdleChildCloser(options: IdleChildCloserOptions): IdleChildCloser;
+//# sourceMappingURL=idle-child.d.ts.map

package/lib/types/engine-codex/agent.d.ts

@@ -70,7 +70,15 @@ export declare class CodexAgent implements Agent {
      * must respawn the child rather than reuse one configured for another endpoint.
      */
     private appServerConfig;
+    /**
+     * Countdown that shuts the child down once this agent has been idle past the
+     * configured window, so an idle session stops paying for a process nothing
+     * is driving. Armed and cancelled by {@link setPhase}.
+     */
+    private readonly idleChild;
     constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig);
+    /** Shut the cached child down; the next step's {@link appServerClient} spawns a fresh one. */
+    private closeChild;
     /**
      * Return the cached app-server client, spawning one on first use, after a dead
      * process, or when the resolved dsh endpoint changed since the last spawn.

package/lib/types/engine-codex/loop.d.ts

@@ -40,6 +40,12 @@ export interface Config {
     env?: Record<string, string>;
     /** Fallback model for the app-server thread, used when the session selects none; Codex native settings own the model when omitted. */
     model?: string;
+    /**
+     * Idle window in milliseconds before a session's `codex app-server` child is
+     * shut down, spawned again by the next step. Omitted or non-positive keeps
+     * the child for the session's whole life.
+     */
+    childIdleMs?: number;
 }
 /** Schema of the Codex loop plugin configuration. */
 export declare const Config: z<Config>;

package/lib/types/engine-codex/types.d.ts

@@ -15,5 +15,12 @@ export interface ResolvedConfig {
     readonly approvalPolicy: CodexApprovalPolicy | undefined;
     readonly env: Record<string, string>;
     readonly model: string | undefined;
+    /**
+     * How long an idle session keeps its `codex app-server` child, in
+     * milliseconds; zero or less keeps it for the session's whole life. See
+     * `driver-core/idle-child.ts` for why the child, and not the agent, is what
+     * gets released.
+     */
+    readonly childIdleMs: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/types/engine-kimi/agent.d.ts

@@ -56,7 +56,15 @@ export declare class KimiAgent implements Agent {
      * every step.
      */
     private handoverEnvCache;
+    /**
+     * Countdown that shuts the child down once this agent has been idle past the
+     * configured window, so an idle session stops paying for a process nothing
+     * is driving. Armed and cancelled by {@link setPhase}.
+     */
+    private readonly idleChild;
     constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig, spawn: KimiSpawnCapability, bin: string);
+    /** Shut the cached child down; the next step's {@link acpClient} spawns a fresh one. */
+    private closeChild;
     get status(): AgentStatus;
     /** Commit a phase and publish its externally visible status transition. */
     private setPhase;

package/lib/types/engine-kimi/loop.d.ts

@@ -32,6 +32,12 @@ export interface Config {
     env?: Record<string, string>;
     /** Kimi CLI executable; `'kimi'` resolves through PATH when not pinned to an absolute path. */
     bin?: string;
+    /**
+     * Idle window in milliseconds before a session's `kimi acp` child is shut
+     * down, spawned again by the next step. Omitted or non-positive keeps the
+     * child for the session's whole life.
+     */
+    childIdleMs?: number;
 }
 /** Schema of the Kimi loop plugin configuration. */
 export declare const Config: z<Config>;

package/lib/types/engine-kimi/types.d.ts

@@ -19,5 +19,12 @@ export interface ResolvedConfig {
     readonly env: Record<string, string>;
     /** Kimi CLI executable; `'kimi'` resolves through PATH when not pinned to an absolute path. */
     readonly bin: string;
+    /**
+     * How long an idle session keeps its `kimi acp` child, in milliseconds; zero
+     * or less keeps it for the session's whole life. See
+     * `driver-core/idle-child.ts` for why the child, and not the agent, is what
+     * gets released.
+     */
+    readonly childIdleMs: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/types/index.d.ts

@@ -15,16 +15,20 @@
  * Because the router owns the slot, the plugin keeps the base bundle's
  * `agent-loop` row disabled for as long as it is composed. That managed block
  * lives in the profile's `cordis.patch.yml` (see `patch-manager.ts`) and is the
- * plugin's only footprint in the harness's configuration; the block names no
- * engine, because the engine is a per-session decision.
+ * plugin's only footprint in the harness's configuration alongside the preset
+ * rows below; the block names no engine, because the engine is a per-session
+ * decision.
  *
- * The plugin authors one preset per hosted engine into the user preset root
- * (`$DSH_HOME/.agent-presets/loop-engine-<engine>`, see `preset.ts`), each a
- * copy of `standard` minus the dsh-native command and skill rows an external
- * engine replaces, and it serves every hosted engine's provider route label in
- * the llm registry (`provider-route.ts`): an engine logs its own label into
- * each session's request/header, and the web host refuses a turn whose session
- * selection names a provider no adapter serves. The preset is now only the
+ * The plugin authors one preset per hosted engine — each a copy of `standard`
+ * minus the dsh-native command and skill rows an external engine replaces — and
+ * it serves every hosted engine's provider route label in the llm registry
+ * (`provider-route.ts`): an engine logs its own label into each session's
+ * request/header, and the web host refuses a turn whose session selection names
+ * a provider no adapter serves. WHERE that copy lives depends on the harness
+ * generation — a directory under `$DSH_HOME/.agent-presets/loop-engine-<engine>`
+ * on the 0.1.5 line, a `@deepseek-ai/dsh-agent-preset` insert row in the profile
+ * patch on the 0.1.7 line, which stopped reading the directory (see
+ * `preset.ts`, {@link authorHostedPresets}). The preset is now only the
  * session's agent-plane composition (and the engine's own default for a session
  * with no record) — it is no longer the thing that decides a running session's
  * engine.
@@ -70,6 +74,14 @@ export interface Config extends ClaudeCodeConfig {
     piThinking?: string;
     /** Kimi CLI executable; `'kimi'` resolves through PATH when not pinned to an absolute path. */
     kimiBin?: string;
+    /**
+     * Idle window in milliseconds after which a hosted session's PERSISTENT child
+     * process (Kimi's `kimi acp`, Codex's app-server) is shut down and spawned
+     * again by the next step. Zero or omitted keeps the child for the session's
+     * whole life. Only these two engines hold a child between steps: the Pi and
+     * Claude Code drivers spawn per step, so the knob does not reach them.
+     */
+    childIdleMs?: number;
     /**
      * Default engine NEW sessions are created on. A live, profile-backed field:
      * the settings shell edits it and the running plugin reads it through this

package/lib/types/patch-manager.d.ts

@@ -69,6 +69,26 @@ export declare function hasManagedBlock(text: string): boolean;
  * engine this build does not recognize.
  */
 export declare function legacyBlockEngineOf(text: string): LoopEngineId | undefined;
+/** Normalize a file so a managed span sits on its own lines with a blank separator. */
+export declare function ensureTrailingNewline(text: string): string;
+/**
+ * The profile seed template (`cordis.patch.yml` on a fresh profile) is a lone
+ * root-level empty flow sequence `[]`. The plugin's managed block is itself a
+ * root-level block sequence of loader entries, so a block coexisting with a
+ * surviving `[]` is TWO root collections in one document — YAML the harness
+ * rejects with "end of the stream or a document separator is expected", and the
+ * web app then fails to boot. Remove a whole-line root `[]` placeholder so the
+ * managed block is the sole top-level collection. Anchored to column 0 so an
+ * indented `[]` that is a real value inside an entry's nested config is never
+ * touched.
+ *
+ * Shared with the preset-rows region (`./preset.ts`): both regions are
+ * root-level collections appended to the same file, so either one can be the
+ * first thing that meets a surviving seed.
+ * @param text - the patch-file text.
+ * @returns the text without a whole-line root `[]` placeholder.
+ */
+export declare function dropSeedPlaceholder(text: string): string;
 /**
  * Produce the next patch-file text carrying the managed block, preserving every
  * byte outside the managed span. Appends the span when absent and replaces it

package/lib/types/preset.d.ts

@@ -10,9 +10,29 @@
  * advisory prompt text an external engine never assembles, dsh `/compact`
  * cannot shrink a context the engine's child process holds, and dsh skills
  * would sit next to the engine's own catalog. Those rows live inside the
- * agent-preset composition, which a profile patch cannot reach, so the plugin
- * authors a stripped preset per engine into the user preset root
- * (`$DSH_HOME/.agent-presets/<id>`).
+ * agent-preset composition, which a profile patch cannot otherwise reach, so
+ * the plugin authors a stripped copy of that composition per engine.
+ *
+ * WHICH mechanism carries that copy is the running harness generation's
+ * business, and the two share everything but the carrier:
+ *
+ *  - the 0.1.5 line reads presets from a DIRECTORY per preset under the user
+ *    preset root (`$DSH_HOME/.agent-presets/<id>`), so there it is two files
+ *    per engine ({@link ensureEnginePresets});
+ *  - the 0.1.7 line replaced that with composed plugin rows: a preset is one
+ *    `@deepseek-ai/dsh-agent-preset` row whose `config.plugins` list IS the
+ *    composition, declared wherever a composition is declared. Nothing reads
+ *    `.agent-presets` any more, so there it is four `insert` rows in the
+ *    profile patch the plugin already manages
+ *    ({@link ensureEnginePresetRows}). The rows mirror the shipped shape
+ *    (`packages/bundle/web-app/presets/standard.patch.yml` in the harness),
+ *    with this plugin's own id, order, and stripped composition.
+ *
+ * Both mechanisms regenerate from the current `standard` composition on every
+ * boot: text on disk is never authoritative, so a harness upgrade that changes
+ * `standard` flows through. Neither re-parses YAML — the strip is a line
+ * transform that preserves everything it does not drop byte for byte, comments
+ * included, and the row form only re-indents that text.
  *
  * The preset id is ALSO the per-session engine selector: the harness resolves
  * one preset per session and hands its id to the agent factory at create time
@@ -21,12 +41,6 @@
  * makes "session A on Codex, session B on Kimi, concurrently" expressible in a
  * harness that admits exactly one AgentFactory.
  *
- * The presets are REGENERATED from the current `standard` composition on every
- * boot: text on disk is never authoritative, so a harness upgrade that changes
- * `standard` flows through. The file is plain YAML the loader already accepts —
- * the strip is a line transform that preserves everything it does not drop byte
- * for byte, comments included.
- *
  * @module dsh-loop-engine/preset
  */
 export { HOSTED_PRESET_PREFIX, SOURCE_PRESET_ID, engineOfPreset, enginePresetId, hostedEngineOf, sessionEngineOf, } from './agent-preset-ids.ts';
@@ -56,6 +70,47 @@ export declare const HOSTED_PRESET_IDS: readonly string[];
  *   its context and its own `/compact` (Claude, Kimi).
  */
 export declare const STRIPPED_ROWS: readonly ["skill-filesystem", "tool-skill", "tool-goal", "command-goal", "planning", "compaction"];
+/**
+ * Begin marker of the plugin-managed preset-rows region inside a profile patch
+ * file. The region is what registers the hosted engines' presets on the 0.1.7
+ * line, where a preset is a composed row rather than a directory.
+ *
+ * Deliberately NOT the managed block's marker: the two regions are located and
+ * rewritten independently, so editing one never rewrites the other's bytes.
+ */
+export declare const PRESET_ROWS_BEGIN = "# -- dsh-loop-engine presets --";
+/** End marker of the plugin-managed preset-rows region inside a profile patch file. */
+export declare const PRESET_ROWS_END = "# -- /dsh-loop-engine presets --";
+/**
+ * Roster order of every preset this plugin authors. The shipped presets occupy
+ * 1..4 (`standard` 1, `ptc` 2, `minimal` 3, `cordis` 4), and the roster sorts
+ * by order and then by id, so one constant past that range puts every managed
+ * preset after every shipped one — the deployment's own presets stay at the top
+ * of the picker and the engines' copies trail it, which is also where the
+ * order they are listed in (selection order) is readable.
+ */
+export declare const ENGINE_PRESET_ORDER = 100;
+/**
+ * The managed preset-rows region: one preset row per hosted engine, bracketed
+ * by the markers that make it locatable and rewritable.
+ * @param composition - the source `standard` composition.
+ * @returns the region's text, ending in a newline.
+ */
+export declare function renderPresetRows(composition: string): string;
+/**
+ * Produce the next patch-file text carrying the preset-rows region, preserving
+ * every byte outside that span — including the managed block, which is located
+ * by its own markers. Appends the region when absent and replaces it when
+ * present, so an unchanged composition leaves the text byte for byte identical.
+ *
+ * The region is a root-level collection like the managed block, so a leftover
+ * seed `[]` is dropped with it: two root collections in one document is YAML
+ * the harness rejects, and the profile would stop booting.
+ * @param text - current patch-file text.
+ * @param composition - the source `standard` composition.
+ * @returns the rewritten patch-file text.
+ */
+export declare function applyEnginePresetRows(text: string, composition: string): string;
 /**
  * Remove top-level entries by id from a preset composition, preserving every
  * other byte. Each entry owns the comment/blank run directly above its opener
@@ -87,4 +142,24 @@ export interface PresetCompositionSource {
  * @throws when the source preset cannot be read or the writes fail.
  */
 export declare function ensureEnginePresets(dshHome: string, source: PresetCompositionSource): Promise<boolean>;
+/**
+ * Regenerate every hosted engine's preset as an `insert` row in the profile
+ * patch the plugin already manages, from the roster's `standard` preset.
+ *
+ * This is the 0.1.7 mechanism: a preset there is a composed plugin row, and the
+ * user preset root is not read at all — so a preset written as a directory
+ * would simply never register, leaving the roster without the id every hosted
+ * session records. The rows go in the profile's own `cordis.patch.yml` because
+ * that is the one composition layer the plugin owns: it is already the file the
+ * managed block lives in, it is applied after the bundle's own preset rows, and
+ * a rewrite of it is what the harness's live patch reload picks up.
+ *
+ * Idempotent: an up-to-date region is left byte for byte alone, so a rewrite
+ * that changes nothing does not touch the file's stamp.
+ * @param patchPath - absolute path of the profile's patch file.
+ * @param source - the roster's composition reader.
+ * @returns whether the patch file was written.
+ * @throws when the source preset cannot be read or the write fails.
+ */
+export declare function ensureEnginePresetRows(patchPath: string, source: PresetCompositionSource): Promise<boolean>;
 //# sourceMappingURL=preset.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-loop-engine",
   "description": "Web-switchable agent loop engine selection for the DeepSeek Harness - out-of-tree plugin (Claude Code / Codex / Pi / Kimi Code drivers) maintained by @kuun993, zero main-repo changes",
-  "version": "0.1.7-rc3",
+  "version": "0.1.7-rc5",
   "publishConfig": {
     "access": "public"
   },