billion-context-dsh 0.2.25 → 0.2.26

package/README.en.md

@@ -3,7 +3,7 @@
 [English](./README.en.md) | [中文](./README.md)
 
 > **⚠️ Beta notice — not for production use**
-> This project (**v0.2.25**) is a work-in-progress beta. The [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) itself is also in **public beta**. **Do not use either in engineering / production environments** — expect breaking changes and rough edges.
+> This project (**v0.2.26**) is a work-in-progress beta. The [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) itself is also in **public beta**. **Do not use either in engineering / production environments** — expect breaking changes and rough edges.
 
 <p align="center">
 <strong>Built with gratitude on top of these projects</strong> — please give them a ⭐:
@@ -42,7 +42,7 @@ When conversations get long, the model runs out of context. Most tools hard-trun
 Unlike DSH's built-in auto-compaction (which replaces a range with an automatically generated summary), billion-context-dsh:
 
 - **Model-driven** — the model writes the summary itself; there is no second LLM summarization call
-- **Advisory, never imperative** — automatic policy only *nudges*; the model decides whether and when to compress
+- **Advisory, never imperative** — automatic policy only *nudges*; the model decides whether and when to compress (one exception: a provider-confirmed context overflow lets the engine recover once by itself — see `maxOverflowRetries` in the configuration table)
 - **Durable & recoverable** — a compressed range becomes a checkpoint node, the originals stay in the append-only session log; `decompress` restores them, `search_context` finds information inside blocks
 - **Long tasks hold steady** — every step builds on the results before it; key conclusions stay usable and compound, so very long tasks actually finish
 - **Context stays lean** — every request rides on a small, distilled slice of context with only the key information; no bulk compression of large ranges, so details don't decay with it — and tokens stay low
@@ -100,7 +100,7 @@ This only installs the package into your project/global store; it does **not** t
 **Install from the git source (`github:` spec — the form the plugin store shows).** The prebuilt `dist/` artifacts are committed to this repository, so a git-source install also works out of the box — **no build step needed**, and pnpm 11's default build-script blocking (`allowBuilds`) never applies to this package:
 
 ```bash
-dsh plugin --profile web add github:Tyan66666/billion-context-dsh#v0.2.25
+dsh plugin --profile web add github:Tyan66666/billion-context-dsh#v0.2.26
 ```
 
 Prefer a `#<tag>` ref to get artifacts identical to that npm release; without a ref you get the latest default-branch build. Only building the repo yourself (`npm run build`) requires approving build scripts. Background and trade-offs: [docs/git-source-install-design.md](docs/git-source-install-design.md) (issue #92).
@@ -167,7 +167,7 @@ compaction-acp:
 /acp-prune config reset all
 ```
 
-Changing a window key (`modelContextLimit` / `autoModelContextLimit`) clears the window-probe cache — the next pre-step re-probes under the new values (probe failures are cached too, so this is also how a fixed gateway gets re-probed). In provider-less plain-npm compositions `/acp-prune config` degrades to advice text; `settingsEnabled: false` disables the integration entirely (composition-row-only — the switch is deliberately NOT part of the settings layer: it cannot turn itself off). Design details: [docs/settings-integration-design.md](docs/settings-integration-design.md).
+Changing a window key (`modelContextLimit` / `autoModelContextLimit`) clears the window-probe cache — the next pre-step re-probes under the new values (probe failures are cached too, so this is also how a fixed gateway gets re-probed). In provider-less plain-npm compositions `/acp-prune config` degrades to advice text; on DSH lines ≥0.1.7, where the host settings service no longer provides `installSection` (outside this plugin's declared peer range), the engine degrades cleanly too — one startup warning, the six keys stay adjustable through the composition-row `config:`, engine and tools unaffected (issue #173); `settingsEnabled: false` disables the integration entirely (composition-row-only — the switch is deliberately NOT part of the settings layer: it cannot turn itself off). Design details: [docs/settings-integration-design.md](docs/settings-integration-design.md).
 
 **Per-mode — an agent preset's `compaction` realm.** First *disable (or delete) the realm's existing `dsh-compaction-basic` row*, then mount this engine — two backends cannot coexist in the same realm:
 
@@ -251,6 +251,7 @@ This project reuses `acp-kernel`'s compression core and `billion-context-pi`'s d
 | `autoTools` | `true` | Register the four model tools on `ctx.tools` |
 | `autoCommand` | `true` | Register the `/acp-prune` command on `ctx.commands` |
 | `autoNudge` | `true` | Inject the nudge into `agent/pre-step` (runtime-adjustable: `/acp-prune config`) |
+| `maxOverflowRetries` | `1` | Budget for automatic recovery from a provider-confirmed context overflow (`CONTEXT_WINDOW_EXCEEDED`): the engine hides the largest eligible range with a marker summary it writes itself (no model call — the request was just rejected, so there is no model turn to write one; every original stays in the session log and `search_context`/`decompress` find it again), then answers the host's `agent/request-error` so the request is retried. The budget counts per request and resets once the model makes progress (an assistant message lands) or the agent goes idle; `0` disables the automatic action (the error surfaces unchanged). This is ACP's ONLY automatic compaction action — the pressure side stays nudge-only, the model decides (composition-only, not in the settings layer; rationale and trade-offs in [docs/overflow-recovery-design.md](docs/overflow-recovery-design.md)) |
 | `settingsEnabled` | `true` (enabled when unset) | (optional) Disable the runtime-settings integration entirely (composition-row-only, deliberately NOT in the settings layer — the switch cannot turn itself off; with it off the composition-row `config:` stays the only effective channel) |
 | `prompts` | — | (optional) Custom prompt copy: per-slot overrides for nudge / range table / system prompt / tool descriptions (template + named placeholders, validated at construction; see “Custom prompt copy” above and [docs/configurable-prompts-design.md](docs/configurable-prompts-design.md)) |
 
@@ -267,6 +268,7 @@ If you do not want to tune three percentages by hand, pick the nudge aggressiven
 | `aggressive` | 0.30 | 0.50 | 0.70 | Lean context — compresses early and frequently |
 
 - **Fills only what you left unset**: `preset` fills ONLY the `nudge*ContextLimitPct` values you did not set explicitly; if you set both a `preset` and one of those thresholds, your explicit value wins (precedence: explicit > preset > default).
+- **Presets reach the runtime settings layer too**: the threshold values a composed preset fills are registered as the settings layer's `base` — `/acp-prune config list` attributes them to `source: base`, and `/acp-prune config reset <key>` returns them to the **preset value**, not the engine default (a runtime reset restores what the composition chose). Without a preset, nothing changes.
 - **No other knob is touched**: `modelContextLimit`, `autoNudge`, `prompts`, and `coreOverrides` are unaffected; `coreOverrides.nudge` still lands last and its same-name keys outrank everything.
 - **See the active tier**: `/acp-prune status` prints the effective `preset` and the three thresholds **actually in force** — the line mirrors `kernelConfigFor`'s merge order, so any explicit override you made on top of the preset AND any same-name key in `coreOverrides.nudge` are shown as they really apply.
 - **A typo fails loudly**: an unknown name throws at engine construction and lists the valid tiers (the same fail-fast contract as custom prompt templates) — it never silently falls back to the defaults. The bundle row itself carries no `config`, so a `preset` can only come from your own same-id `compaction-acp` row; if that row fails to construct, the profile stays down until you fix it (intended fail-fast, not a defect).

package/README.md

@@ -3,7 +3,7 @@
 [中文](./README.md) | [English](./README.en.md)
 
 > **⚠️ 测试版声明——请勿用于生产环境**
-> 本项目（**v0.2.25**）仍处于开发中的测试版。[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 本身也处于**公开测试版**阶段。**请勿将两者用于工程化 / 生产环境**——预期会有破坏性变更与粗糙之处。
+> 本项目（**v0.2.26**）仍处于开发中的测试版。[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 本身也处于**公开测试版**阶段。**请勿将两者用于工程化 / 生产环境**——预期会有破坏性变更与粗糙之处。
 
 <p align="center">
 <strong>衷心感谢以下项目——请给它们一个 ⭐：</strong>
@@ -42,7 +42,7 @@
 与 DSH 内置的自动压缩（用自动生成的摘要替换一段范围）不同，billion-context-dsh：
 
 - **模型驱动** —— 摘要由模型自己书写，没有第二次 LLM 摘要调用
-- **只建议、不强令** —— 自动策略只 *nudge*（提醒），是否压缩、何时压缩由模型决定
+- **只建议、不强令** —— 自动策略只 *nudge*（提醒），是否压缩、何时压缩由模型决定（唯一的例外：provider 确认的上下文超窗会让引擎自己抢救一次——见配置表的 `maxOverflowRetries`）
 - **持久且可恢复** —— 压缩范围成为 checkpoint 节点，原文保留在 append-only 会话日志中；`decompress` 可恢复，`search_context` 可在块内查找
 - **长任务稳得住** —— 每一步都接着前面的成果走，关键结论持续可用、不断叠加，超长任务更容易跑完
 - **上下文始终精简** —— 每次请求都只用少量、精炼的上下文，只保留关键信息；不做大段统一压缩，细节不随之衰失，token 消耗自然更低
@@ -99,7 +99,7 @@ npm install billion-context-dsh
 **git 源安装（`github:` 规格，插件商店展示的形态）。** 预构建产物 `dist/` 已提交到仓库，从 git 源安装同样开箱即用——**无需任何构建步骤**，pnpm 11 默认拦截构建脚本（`allowBuilds`）的机制对这个包不构成障碍：
 
 ```bash
-dsh plugin --profile web add github:Tyan66666/billion-context-dsh#v0.2.25
+dsh plugin --profile web add github:Tyan66666/billion-context-dsh#v0.2.26
 ```
 
 建议带 `#<tag>` 安装，拿到与对应 npm 版本完全一致的产物；不带 ref 则装默认分支的最新构建。只有 clone 仓库自行从源码构建（`npm run build`）才需要放行构建。背景与方案取舍见 [docs/git-source-install-design.md](docs/git-source-install-design.md)（issue #92）。
@@ -164,7 +164,7 @@ compaction-acp:
 /acp-prune config reset all
 ```
 
-窗口相关键（`modelContextLimit` / `autoModelContextLimit`）改动会清空窗口探测缓存——下一次 pre-step 按新值重新探测（探测失败也会被缓存，正是靠这个机制在修复网关后重新探测）。无 settings provider 的纯 npm 安装组合下 `/acp-prune config` 降级为指引文案；`settingsEnabled: false` 可整体关闭该集成（组合行专用，不进 settings 层——开关不能关掉自己）。设计细节见 [docs/settings-integration-design.md](docs/settings-integration-design.md)。
+窗口相关键（`modelContextLimit` / `autoModelContextLimit`）改动会清空窗口探测缓存——下一次 pre-step 按新值重新探测（探测失败也会被缓存，正是靠这个机制在修复网关后重新探测）。无 settings provider 的纯 npm 安装组合下 `/acp-prune config` 降级为指引文案；DSH 0.1.7+ 宿主线（settings 服务已移除 `installSection`，在本插件声明的 peer 区间之外）同样干净降级：启动时记一条 warn，六个键改由组合行 `config:` 调整，引擎与工具不受影响（issue #173）；`settingsEnabled: false` 可整体关闭该集成（组合行专用，不进 settings 层——开关不能关掉自己）。设计细节见 [docs/settings-integration-design.md](docs/settings-integration-design.md)。
 
 **单模式生效（agent preset 的 `compaction` realm）**。先在该 realm 内*禁用（或删除）原有的 `dsh-compaction-basic` 行*，再插入本引擎——同一 realm 内两个后端不能并存：
 
@@ -248,6 +248,7 @@ DSH 的每个模型请求都派生自其 append-only 会话日志（*surface*）
 | `autoTools` | `true` | 在 `ctx.tools` 注册四个模型工具 |
 | `autoCommand` | `true` | 在 `ctx.commands` 注册 `/acp-prune` 命令 |
 | `autoNudge` | `true` | 当内核建议时向 `agent/pre-step` 注入 nudge（运行时热调：`/acp-prune config`） |
+| `maxOverflowRetries` | `1` | 宿主确认的上下文超窗（`CONTEXT_WINDOW_EXCEEDED`）自动抢救预算：超窗时引擎挑一段**最大且合规**的范围做一次紧急压缩（摘要是引擎自己写的标记，不调模型——请求刚被拒，本就没有模型回合可写摘要；原文都留在日志里，`search_context`/`decompress` 找得回来），然后应答宿主的 `agent/request-error` 让该请求重试。预算按请求计数，模型有进展（落一条 assistant 消息）或 agent 回到 idle 即重置；`0` 关闭这个自动动作（错误原样抛给用户）。这是 ACP 唯一的自动压缩动作——压力侧始终只 nudge、由模型决定（组合行专用，不进 settings 层；原理与取舍见 [docs/overflow-recovery-design.md](docs/overflow-recovery-design.md)） |
 | `settingsEnabled` | `true`（未配置即启用） | （可选）整体关闭运行时设置集成（组合行专用，不进 settings 层——开关不能关掉自己；关闭后组合行 `config:` 仍是唯一生效通道） |
 | `prompts` | — | （可选）自定义提示词文案：nudge / 范围表 / system prompt / 工具描述按槽位覆盖（模板 + 命名占位符，构造期校验；见上文「自定义提示词文案」与 [docs/configurable-prompts-design.md](docs/configurable-prompts-design.md)） |
 
@@ -264,6 +265,7 @@ DSH 的每个模型请求都派生自其 append-only 会话日志（*surface*）
 | `aggressive` | 0.30 | 0.50 | 0.70 | 精简上下文，更早更频繁地压缩 |
 
 - **只填未设的阈值**：`preset` 仅填充你没有显式设置的 `nudge*ContextLimitPct`；同时写了 `preset` 和某个阈值时，该阈值以你的显式值为准（优先级 显式 > preset > 默认）。
+- **preset 同样落到运行时设置层**：组合 preset 填出的三个阈值注册为 settings 层的 `base` 层——`/acp-prune config list` 把它们归因为 `source: base`，`/acp-prune config reset <key>` 退回的是 **preset 值**而非引擎默认（运行时 reset 恢复的是组合的选择）；未配 preset 时行为完全不变。
 - **不碰其他旋钮**：`modelContextLimit`、`autoNudge`、`prompts`、`coreOverrides` 完全不受影响；`coreOverrides.nudge` 仍最后落地、同名键最高优先。
 - **查看当前档位**：`/acp-prune status` 会打印生效的 `preset` 及其**真实生效的**三个阈值——这一行镜像 `kernelConfigFor` 的合并顺序，所以你在其上做的显式覆盖、以及 `coreOverrides.nudge` 里的同名键都会如实显示。
 - **拼错即报错**：未知名称在引擎构造期直接抛错并列出合法值（与自定义提示词模板同一约定），不会静默回退默认。注意 bundle 行本身不带 `config`，`preset` 只能由你自己的同 id `compaction-acp` 行提供；该行构造失败即挂载失败，profile 会在你修好配置前一直起不来（fail-fast 的既定行为）。

package/dist/index.d.ts

@@ -115,6 +115,15 @@ export interface AcpConfig {
     readonly autoCommand: boolean;
     /** Inject the nudge into `agent/pre-step` when the kernel recommends it. Default true. */
     readonly autoNudge: boolean;
+    /**
+     * How many consecutive provider-confirmed context-overflow failures one
+     * agent may answer with an emergency compaction + retry before the original
+     * error is preserved (mirrors compaction-basic's `maxOverflowRetries`;
+     * default 1, the host's own default). The budget resets when the agent
+     * makes progress (an assistant message lands) or returns to idle, so a
+     * request that cannot be repaired cannot retry forever.
+     */
+    readonly maxOverflowRetries?: number;
     /**
      * Escape hatch: disable the runtime-settings integration entirely
      * (composition-layer ONLY — deliberately not exposed through the settings
@@ -163,6 +172,10 @@ export declare class AcpCompactionEngine extends CompactionEngine {
     readonly settingsCommand: SettingsCommandSurface;
     /** Per route the adapter's per-request output cap (the output reservation); null = undisclosed. */
     private readonly outputReservationCache;
+    /** Per-agent context-overflow recovery budget (mirrors the host's `overflowRetries`). */
+    private readonly overflowRetries;
+    /** Per-session overflow agents, so session progress can reset the recovery budget. */
+    private readonly overflowSessions;
     constructor(ctx: Context, config?: Partial<AcpConfig>);
     /**
      * Resolve the effective context window for an agent. An explicitly
@@ -208,6 +221,18 @@ export declare class AcpCompactionEngine extends CompactionEngine {
      * (degenerate config) — the raw-window behavior is preserved.
      */
     private applyReservation;
+    /**
+     * Best-effort emergency compaction for one provider-confirmed context
+     * overflow: pick the largest eligible (guarded, tool-pairing-balanced)
+     * surface range and land the normal durable transaction with a fixed
+     * engine-written marker summary. No LLM call — the provider just rejected
+     * the request for being too large, so there is no model turn available to
+     * write a summary; the originals stay in the append-only log, so
+     * search_context still indexes them, decompress restores them, and the
+     * model can re-run the compress tool over the marker later to write a real
+     * summary. Returns null when nothing eligible exists (nothing to reclaim).
+     */
+    private compactForOverflow;
     /** ACP is model-driven: automatic pressure policy never summarizes by itself. */
     compactIfNeeded(_agent: CompactionAgentContext, _trigger: CompactionTrigger, signal: AbortSignal): Promise<CompactionResult | null>;
     /** Explicit idle-session compaction: ACP leaves the decision to the model. */

package/dist/index.js

@@ -3363,6 +3363,9 @@ function makePreview(text, query, len) {
   return prefix + text.slice(start, end).trim() + suffix;
 }
 
+// src/index.ts
+import { CONTEXT_WINDOW_EXCEEDED_CODE } from "@deepseek-ai/dsh-llm";
+
 // src/lru.ts
 var DEFAULT_SESSION_CACHE_LIMIT = 512;
 var LruMap = class extends Map {
@@ -3478,9 +3481,18 @@ function buildToolCallIndex(events) {
 }
 var SUMMARY_FRAME_PREFIX = "[Model-written summary \u2014 not user words; re-verify any obligations before relying on them]";
 function withSummaryFramePrefix(text) {
-  return text.startsWith(SUMMARY_FRAME_PREFIX) ? text : `${SUMMARY_FRAME_PREFIX}
+  if (text.startsWith(SUMMARY_FRAME_PREFIX)) return text;
+  if (isEngineWrittenSummary(text)) return text;
+  return `${SUMMARY_FRAME_PREFIX}
 ${text}`;
 }
+var ENGINE_SUMMARY_LEAD = "[engine-written summary \u2014 context-overflow emergency compaction";
+function isEngineWrittenSummary(text) {
+  return text.startsWith(ENGINE_SUMMARY_LEAD);
+}
+function overflowMarkerSummary(hiddenCount) {
+  return `${ENGINE_SUMMARY_LEAD}: ${hiddenCount} surface message(s) hidden because the provider rejected the request as exceeding the context window. The originals are intact in the session log \u2014 use search_context or decompress (see acp_status) to read them, or re-run the compress tool over this range to write a proper summary.]`;
+}
 function projectEvent(event, toolNames) {
   switch (event.type) {
     case "user/message": {
@@ -3606,7 +3618,12 @@ function contentBlocksOfEvent(event) {
 function isCheckpointNode(event) {
   if (event.type !== "user/message") return false;
   const source = event.data.source;
-  return source?.plugin === "compact";
+  return source?.plugin === "compact" || source?.kind === "compact-checkpoint";
+}
+function checkpointCompactionIdOf(event) {
+  if (!isCheckpointNode(event)) return null;
+  const source = event.data.source;
+  return typeof source?.compactionId === "string" ? source.compactionId : null;
 }
 var METADATA_PLUGINS = /* @__PURE__ */ new Set([
   "acp-nudge",
@@ -3619,17 +3636,44 @@ var REAL_CONTENT_PLUGINS = /* @__PURE__ */ new Set([
   "user-approval",
   "tools-ptc"
 ]);
+var REAL_CONTENT_KINDS = /* @__PURE__ */ new Set([
+  "runtime-context",
+  // dynamic-context snapshot (was '@deepseek-ai/dsh-system-prompt')
+  "ptc-mode"
+  // deferred tool context (was 'tools-ptc' / 'tools-code-mode')
+]);
+var AUDITED_RELAY_KINDS = /* @__PURE__ */ new Set([
+  "subagent-report",
+  "subagent-settled"
+]);
 var HOST_INSTRUCTION_KINDS = /* @__PURE__ */ new Set([
   "agent-instructions",
   // AGENTS.md injection (hook shape: {kind:'agent-instructions', form:'instructions'})
-  "skill-catalog"
+  "skill-catalog",
   // skill catalog (form:'catalog')
+  // Host compaction summary row (DSH >= 0.1.7; was plugin 'dsh-compaction-basic').
+  // That legacy name was never whitelisted, so its rows were barriers already —
+  // the renamed spelling keeps exactly that treatment instead of silently
+  // becoming foldable content (issue #169).
+  "compact-basic"
 ]);
+function sourcePluginOf(source) {
+  if (source === void 0 || typeof source !== "object") return void 0;
+  const kind = source.kind;
+  if (kind === "plugin") {
+    return typeof source.plugin === "string" && source.plugin.length > 0 ? source.plugin : void 0;
+  }
+  if (typeof kind === "string" && kind.startsWith("plugin:")) {
+    const name = kind.slice("plugin:".length);
+    return name.length > 0 ? name : void 0;
+  }
+  return void 0;
+}
 function isAgentInstructionsRow(event) {
   if (event.type !== "user/message") return false;
   const source = event.data.source;
   if (!source) return false;
-  return source.kind === "agent-instructions" || source.kind === "plugin" && source.plugin === "agent-instructions";
+  return source.kind === "agent-instructions" || sourcePluginOf(source) === "agent-instructions";
 }
 function classifySurfaceEvent(event) {
   if (isCheckpointNode(event)) return "checkpoint";
@@ -3638,20 +3682,26 @@ function classifySurfaceEvent(event) {
   if (!source) return "real";
   const kind = source.kind;
   if (kind === "user") return "real";
-  if (kind === "plugin") {
-    if (source.plugin !== void 0 && METADATA_PLUGINS.has(source.plugin)) return "metadata";
-    if (source.plugin !== void 0 && REAL_CONTENT_PLUGINS.has(source.plugin)) return "real";
+  const plugin = sourcePluginOf(source);
+  if (kind === "plugin" || plugin !== void 0) {
+    if (plugin !== void 0 && METADATA_PLUGINS.has(plugin)) return "metadata";
+    if (plugin !== void 0 && REAL_CONTENT_PLUGINS.has(plugin)) return "real";
     return "instruction";
   }
-  if (kind !== void 0 && HOST_INSTRUCTION_KINDS.has(kind)) return "instruction";
-  return "real";
+  if (typeof kind !== "string") return "real";
+  if (HOST_INSTRUCTION_KINDS.has(kind)) return "instruction";
+  if (REAL_CONTENT_KINDS.has(kind) || AUDITED_RELAY_KINDS.has(kind)) return "real";
+  return "instruction";
 }
 function isRealUserTurn(event) {
   if (event.type !== "user/message") return false;
   if (classifySurfaceEvent(event) !== "real") return false;
   const source = event.data.source;
-  if (source?.plugin !== void 0 && REAL_CONTENT_PLUGINS.has(source.plugin)) return false;
-  return source?.kind !== "subagent-report" && source?.kind !== "subagent-settled";
+  const plugin = sourcePluginOf(source);
+  if (plugin !== void 0 && REAL_CONTENT_PLUGINS.has(plugin)) return false;
+  const kind = source?.kind;
+  if (typeof kind === "string" && REAL_CONTENT_KINDS.has(kind)) return false;
+  return kind !== "subagent-report" && kind !== "subagent-settled";
 }
 
 // src/host-tokens.ts
@@ -4036,9 +4086,8 @@ function summarySeqIndex(events) {
   const index = /* @__PURE__ */ new Map();
   for (const event of events) {
     if (event.type !== "user/message") continue;
-    const source = event.data.source;
-    const compactionId = source?.plugin === "compact" ? source.compactionId : void 0;
-    if (compactionId !== void 0 && !index.has(compactionId)) index.set(compactionId, event.seq);
+    const compactionId = checkpointCompactionIdOf(event);
+    if (compactionId !== null && !index.has(compactionId)) index.set(compactionId, event.seq);
   }
   return index;
 }
@@ -4128,7 +4177,10 @@ function hideSurfaceSeqs(session, seqs, text, priceEvent = hostPriceEvent) {
   const body = text !== void 0 && text.trim().length > 0 ? text : PRUNE_NOTE;
   session.append("user/message", createUserMessage({
     content: [{ type: "text", text: body }],
-    source: { kind: "plugin", plugin: "billion-context-dsh" }
+    // V4 producer kind (issue #163): DSH ≥0.1.7's V4 admission rejects the
+    // legacy wrapper `{ kind: 'plugin', plugin: … }`; `plugin:<name>` is what
+    // the host's own V3→V4 migration emits and is accepted by 0.1.5 too.
+    source: { kind: "plugin:billion-context-dsh" }
   }), {
     surfaceOp: { op: "replace", startSeq: start, endSeq: end },
     sourceEventSeqs: [...seqs]
@@ -4436,10 +4488,10 @@ function blockRegistry(session) {
 }
 function blockRefForSummarySeq(session, seq) {
   const event = eventAtOf(session, seq);
-  if (event?.type !== "user/message") return null;
-  const source = event.data.source;
-  if (source?.plugin !== "compact" || source.compactionId === void 0) return null;
-  const entry = blockRegistry(session).find((r) => r.blockId === source.compactionId);
+  if (event === void 0) return null;
+  const compactionId = checkpointCompactionIdOf(event);
+  if (compactionId === null) return null;
+  const entry = blockRegistry(session).find((r) => r.blockId === compactionId);
   if (entry === void 0) return null;
   return entry.kernelBlockId;
 }
@@ -4459,10 +4511,8 @@ function summarySeqOfKernelBlock(session, kernelBlockId) {
 }
 function checkpointBlockIdOf(events, seq) {
   const event = events[seq];
-  if (event?.type !== "user/message") return null;
-  const source = event.data.source;
-  if (source?.plugin !== "compact" || source.compactionId === void 0) return null;
-  return source.compactionId;
+  if (event === void 0) return null;
+  return checkpointCompactionIdOf(event);
 }
 function expandShadowedSeqs(session, blockId) {
   const ledger = rebuildBlockLedger(sessionEventsOf(session));
@@ -4902,7 +4952,13 @@ function buildNudge(agent, env, lastNudgeTurn, emergencyNudges, onEmergencyCapHi
   );
   const message = createUserMessage2({
     content: [{ type: "text", text }],
-    source: { kind: "plugin", plugin: "acp-nudge" }
+    // V4 producer kind (issue #163): DSH ≥0.1.7's V4 admission rejects the
+    // legacy wrapper shape `{ kind: 'plugin', plugin: … }` outright (a wedged
+    // batch fails the NEXT turn with "format v4 message requires a
+    // producer-owned source kind"). `plugin:<name>` is exactly what the host's
+    // own V3→V4 migration emits for unregistered plugins, and DSH 0.1.5
+    // sessions accept it too (probe-verified), so no version gate is needed.
+    source: { kind: "plugin:acp-nudge" }
   });
   return { message, emergency };
 }
@@ -6107,6 +6163,9 @@ var DEFAULT_CONFIG = {
   autoTools: true,
   autoCommand: true,
   autoNudge: true,
+  // Same default as the host's compaction-basic policy: one owned retry per
+  // unrelieved overflow, then the original error is preserved.
+  maxOverflowRetries: 1,
   // Nudge thresholds: engine defaults 0.70/0.85 — deliberately below the
   // kernel/billion-context-pi 0.75/0.95. 0.95 leaves no room to act before
   // the API rejects, and the host's compaction-basic line (thresholdRatio
@@ -6120,7 +6179,11 @@ var DEFAULT_CONFIG = {
 function resolveAcpConfig(config = {}) {
   const resolved = resolvePresetThresholds({ ...DEFAULT_CONFIG, ...config }, config);
   assertNudgeThresholdOrder(resolved);
-  return resolved;
+  const maxOverflowRetries = resolved.maxOverflowRetries ?? 1;
+  if (!Number.isInteger(maxOverflowRetries) || maxOverflowRetries < 0) {
+    throw new Error(`maxOverflowRetries must be a non-negative integer (got ${maxOverflowRetries})`);
+  }
+  return { ...resolved, maxOverflowRetries };
 }
 function resolvePresetThresholds(base, config) {
   if (base.preset === void 0) return base;
@@ -6132,6 +6195,17 @@ function resolvePresetThresholds(base, config) {
     nudgeEmergencyThresholdPct: config.nudgeEmergencyThresholdPct ?? preset.nudgeEmergencyThresholdPct
   };
 }
+function presetFilledSettingsEntry(config) {
+  const entry = filterSettingsEntry(config);
+  if (config.preset === void 0) return entry;
+  const preset = resolvePreset(config.preset);
+  return {
+    ...entry,
+    nudgeMinContextLimitPct: config.nudgeMinContextLimitPct ?? preset.nudgeMinContextLimitPct,
+    nudgeMaxContextLimitPct: config.nudgeMaxContextLimitPct ?? preset.nudgeMaxContextLimitPct,
+    nudgeEmergencyThresholdPct: config.nudgeEmergencyThresholdPct ?? preset.nudgeEmergencyThresholdPct
+  };
+}
 function assertNudgeThresholdOrder(config) {
   const { nudgeMinContextLimitPct: min, nudgeMaxContextLimitPct: max, nudgeEmergencyThresholdPct: emergency } = config;
   const describe = `min ${min ?? "kernel default"} / max ${max ?? "kernel default"} / emergency ${emergency ?? "kernel default"}`;
@@ -6177,6 +6251,10 @@ var AcpCompactionEngine = class extends CompactionEngine {
   settingsCommand;
   /** Per route the adapter's per-request output cap (the output reservation); null = undisclosed. */
   outputReservationCache = /* @__PURE__ */ new Map();
+  /** Per-agent context-overflow recovery budget (mirrors the host's `overflowRetries`). */
+  overflowRetries = /* @__PURE__ */ new Map();
+  /** Per-session overflow agents, so session progress can reset the recovery budget. */
+  overflowSessions = /* @__PURE__ */ new Map();
   constructor(ctx, config = {}) {
     super(ctx);
     this.config = resolveAcpConfig(config);
@@ -6185,7 +6263,7 @@ var AcpCompactionEngine = class extends CompactionEngine {
     this.kernel = createCore(ports);
     setDocCacheCap(128 * 1024 * 1024);
     this.store = new AcpStateStore();
-    const compositionEntry = filterSettingsEntry(config);
+    const compositionEntry = presetFilledSettingsEntry(config);
     let current = resolveAcpSettings(compositionEntry);
     this.readSettingsSource = () => current;
     const engine = this;
@@ -6202,6 +6280,12 @@ var AcpCompactionEngine = class extends CompactionEngine {
     this.settingsCommand = makeSettingsCommandSurface(() => this.settingsService, () => current);
     if (this.config.settingsEnabled !== false) {
       ctx.inject(["settings"], (settingsCtx) => {
+        if (typeof settingsCtx.settings?.installSection !== "function") {
+          this.ctx.logger.warn(
+            "billion-context-dsh: host settings service has no installSection (removed in dsh-settings >= 0.1.7) \u2014 the compaction-acp settings section is not registered; the six knobs keep their composition values and /acp-prune config reports the section unavailable"
+          );
+          return void 0;
+        }
         settingsCtx.settings.installSection(ctx, ACP_SETTINGS_NAMESPACE, AcpSettingsSchema, compositionEntry, {
           // The seam's source type follows the entry it registered, so `source`
           // is a partial view of the settings; re-resolve it into a
@@ -6282,6 +6366,13 @@ var AcpCompactionEngine = class extends CompactionEngine {
       });
     }
     ctx.on("session/event", (session, event) => {
+      if (event.type === "assistant/message") {
+        const overflowAgent = this.overflowSessions.get(session);
+        if (overflowAgent !== void 0) {
+          this.overflowRetries.delete(overflowAgent);
+          this.overflowSessions.delete(session);
+        }
+      }
       if (event.type !== "tool/result") return;
       const message = event.data.message;
       const block = message.content[0];
@@ -6312,6 +6403,49 @@ var AcpCompactionEngine = class extends CompactionEngine {
       if (outcome === null) return decision;
       return { kind: "enter", messages: [...decision.messages, outcome.message] };
     });
+    ctx.on("agent/status", ({ agent, status }) => {
+      if (status !== "idle") return;
+      this.overflowRetries.delete(agent);
+      this.overflowSessions.delete(agent.session);
+    });
+    ctx.on("agent/request-error", async ({ agent, failure, signal }, next) => {
+      if (failure.code !== CONTEXT_WINDOW_EXCEEDED_CODE || signal.aborted) return next();
+      this.overflowSessions.set(agent.session, agent);
+      const retries = this.overflowRetries.get(agent) ?? 0;
+      const max = this.config.maxOverflowRetries ?? 1;
+      if (retries >= max) {
+        this.ctx.logger.warn(
+          `billion-context-dsh: context-overflow recovery budget spent (${max} retries) for session ${agent.session.id}; preserving the original request error`
+        );
+        return next();
+      }
+      const generation = agent.session.surface.replaceGeneration;
+      let result;
+      try {
+        result = await this.compactForOverflow(agent, signal);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!signal.aborted && agent.session.surface.replaceGeneration > generation) {
+          this.ctx.logger.warn(
+            `billion-context-dsh: context-overflow compaction failed after durable surface progress: ${message}; retrying from the replacement surface`
+          );
+          this.overflowRetries.set(agent, retries + 1);
+          return { kind: "retry" };
+        }
+        this.ctx.logger.warn(
+          `billion-context-dsh: context-overflow compaction failed: ${message}; ${signal.aborted ? "cancellation prevents retry" : "preserving the original request error"}`
+        );
+        return next();
+      }
+      if (signal.aborted || agent.session.surface.replaceGeneration <= generation) return next();
+      if (result !== null) {
+        this.ctx.logger.info(
+          `compaction (context overflow recovery): shadowed ${result.shadowedSeqs.length} surface nodes (seqs ${result.start}-${result.end}, ~${result.shadowedTokenCount} tokens)`
+        );
+      }
+      this.overflowRetries.set(agent, retries + 1);
+      return { kind: "retry" };
+    });
     const systemPrompt = ctx.get("systemPrompt");
     if (systemPrompt !== void 0) {
       systemPrompt.section({
@@ -6435,6 +6569,81 @@ var AcpCompactionEngine = class extends CompactionEngine {
     if (cap === null || cap >= window.limit) return window;
     return { ...window, rawLimit: window.limit, outputReserved: cap, limit: window.limit - cap };
   }
+  /**
+   * Best-effort emergency compaction for one provider-confirmed context
+   * overflow: pick the largest eligible (guarded, tool-pairing-balanced)
+   * surface range and land the normal durable transaction with a fixed
+   * engine-written marker summary. No LLM call — the provider just rejected
+   * the request for being too large, so there is no model turn available to
+   * write a summary; the originals stay in the append-only log, so
+   * search_context still indexes them, decompress restores them, and the
+   * model can re-run the compress tool over the marker later to write a real
+   * summary. Returns null when nothing eligible exists (nothing to reclaim).
+   */
+  async compactForOverflow(agent, signal) {
+    signal.throwIfAborted();
+    const session = agent.session;
+    const state = this.store.stateFor(session);
+    const coreMessages = allLogMessages(session);
+    const surfaceMessages = eventsToCoreMessages(surfaceEventsOf(session));
+    const tokenCount = resolveTokenCount(agent, surfaceMessages);
+    const window = await this.windowFor(agent);
+    const config = kernelConfigFor({ ...this.env, modelContextLimit: window.limit });
+    const turn = this.kernel.processTurn({ messages: coreMessages, state, config, tokenCount, renderTags: "none" });
+    this.store.set(session, turn.state);
+    const byRaw = turn.state.messageRefs.byRaw;
+    let firstSeq;
+    let lastSeq;
+    for (const seq of session.surface.nodes) {
+      if (byRaw[String(seq)] === void 0) continue;
+      firstSeq ??= seq;
+      lastSeq = seq;
+    }
+    if (firstSeq === void 0 || lastSeq === void 0) return null;
+    const view = {
+      ranges: [{ startRef: byRaw[String(firstSeq)], endRef: byRaw[String(lastSeq)] }],
+      refs: { byRef: turn.state.messageRefs.byRef }
+    };
+    const ranges = buildCompressibleSeqRanges(session, view, {
+      preserveRecent: 5,
+      mediaPriceOf: meterMediaPriceResolver(agent, session)
+    });
+    if (ranges.length === 0) return null;
+    const best = ranges.reduce((largest, range) => range.tokens > largest.tokens ? range : largest);
+    const startRef = byRaw[String(best.start)];
+    const endRef = byRaw[String(best.end)];
+    if (startRef === void 0 || endRef === void 0) return null;
+    const summary = overflowMarkerSummary(best.count);
+    const applied = this.kernel.applyCompression({
+      ranges: [{ startRef, endRef, summary, topic: "context-overflow recovery" }],
+      messages: coreMessages,
+      state: turn.state,
+      config
+    });
+    if (applied.result.blocksCreated === 0) return null;
+    this.store.set(session, applied.state);
+    const previousIds = new Set(turn.state.blocks.map((block) => block.blockId));
+    const created = applied.state.blocks.find((block) => !previousIds.has(block.blockId));
+    if (created === void 0) return null;
+    const shadowed = shadowedSeqsOf(session, best.start, best.end);
+    if (shadowed.length === 0) return null;
+    const shadowedTokenCount = shadowedTokensViaMeter(session, shadowed, agent.ctx);
+    const { provider, model } = routeFor(agent);
+    runCompactionTransaction(session, {
+      start: best.start,
+      end: best.end,
+      shadowedSeqs: shadowed,
+      summary: [{ type: "text", text: summary }],
+      shadowedTokenCount,
+      provider,
+      model,
+      topic: "context-overflow recovery",
+      kernelBlockId: created.blockId,
+      directMessageIds: created.directMessageIds,
+      effectiveMessageIds: created.effectiveMessageIds
+    });
+    return { start: best.start, end: best.end, shadowedSeqs: shadowed, shadowedTokenCount };
+  }
   /** ACP is model-driven: automatic pressure policy never summarizes by itself. */
   async compactIfNeeded(_agent, _trigger, signal) {
     signal.throwIfAborted();