dsh-command-context-trim 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to this project are documented here. This project adheres to
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-16
+
+### Added
+
+- **Automatic trimming on the context wall.** A `prepend`ed `agent/request-error` listener reacts to
+  `CONTEXT_WINDOW_EXCEEDED`, frees space with no model call, and asks the loop to retry. Only when it cannot free
+  anything does the waterfall continue into DSH's own recovery (prune + summarize) — so a session that hits the wall
+  is repaired by *dropping* the oldest span first and only pays for summarization when dropping cannot help.
+  This is the unattended form of `/trim`; it is the same execution, invoked by the harness instead of a human.
+- Configuration `autoTrim` (default `true`) and `maxAutoTrimRetries` (default `1`, per overflow episode).
+- **The elided span is chosen by explicit preference tiers.** Elision always starts at the oldest balanced cut, and the
+  search is graded: (1) stay outside the retained tail and keep the final message, with the configured retention relaxed
+  step by step only if the fit otherwise fails; (2) reach into the retained tail, still keeping the final message;
+  (3) last resort — include the final message, typically the current step's assistant tool-call plus its tool result,
+  which can only be removed as a pair. `allowTailTrim: false` ends the list after tier 1. The plan and every rendered
+  result state when the last-resort tier was used.
+- **Planner anchor changed: the newest `user/message` is protected, the final node is not.** The previous rule
+  ("never elide the final surface node") deadlocked the most common overflow shape — one large assistant tool-call whose
+  tool result is the last node could not be removed as a pair, so only a handful of tokens were freeable while the
+  request stayed over the wall (observed live: "largest balanced span frees ~4 of the ~4631 tokens needed"). The newest
+  human instruction is now a **barrier** (never elided, never crossed) and everything after it stays eligible, tool
+  pairing still enforced on both cut edges.
+
+### Notes
+
+- **Scope: the context wall only.** The listener fires exclusively for `CONTEXT_WINDOW_EXCEEDED`. Ordinary
+  threshold compaction (`agent/pre-step` pressure), `/compact`, and the tool-result pruner are untouched — this is
+  asserted by a test that pins the registered listener set.
+- Why `prepend` is required: `agent/request-error` is a Cordis waterfall and compaction registers its summarization
+  recovery on the same event. Cordis stores listeners in registration order and `{ prepend: true }` unshifts, so this
+  listener runs first even when compaction is mounted later inside an agent-preset isolate realm (as it is in a web
+  profile). Returning `{ kind: 'retry' }` without calling `next()` vetoes summarization for that attempt.
+- The per-episode budget resets when a completed assistant message lands or the agent goes idle, mirroring
+  compaction's own overflow accounting.
+- Trade-off, stated plainly: an automatic trim **drops** the oldest span rather than summarizing it. That is the
+  point on a small local window — the summarizer must fit the region it is condensing and frequently cannot — but it
+  does mean the dropped text is replaced by a marker instead of a summary. `/compact` remains available, and the full
+  text stays in the durable session log.
+
+
 ## [0.1.1] - 2026-09-15
 
 ### Fixed
@@ -61,6 +101,7 @@ All notable changes to this project are documented here. This project adheres to
   content stays in the durable session log. v1 has no `/untrim`.
 - Requires a harness that exposes `ctx.commands`, `ctx.tokenMeter`, and `ctx.llm` (DeepSeek Harness 0.1.2-rc.1 or later).
 
-[Unreleased]: https://github.com/snailium/dsh-command-context-trim/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/snailium/dsh-command-context-trim/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/snailium/dsh-command-context-trim/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/snailium/dsh-command-context-trim/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/snailium/dsh-command-context-trim/releases/tag/v0.1.0

package/README.md

@@ -84,17 +84,66 @@ Design consequences:
   is idle, so it cannot interleave with a turn, `/compact`, or automatic compaction; it also refuses while an unmatched
   `compaction/start` is open.
 
+## Automatic trimming on the context wall
+
+`autoTrim` (default on) makes the same model-free reduction happen without anyone typing a command: a **prepended**
+`agent/request-error` listener reacts to `CONTEXT_WINDOW_EXCEEDED`, trims, and asks the loop to retry.
+
+```
+request fails (context wall)
+  ├─ prepended: context-trim   → trim a span, no model call → retry      ← wins when it can free space
+  └─ next(): compaction-basic  → prune tool results → summarize (LLM)    ← only when trimming cannot help
+```
+
+Why `prepend` is the whole trick: `agent/request-error` is a Cordis **waterfall**, and compaction registers its own
+summarization recovery on the same event. Cordis keeps listeners in registration order and `{ prepend: true }`
+unshifts to the front, so this plugin runs first even though compaction is mounted later — in a web profile it lives
+inside an agent-preset isolate realm, which no host-plane plugin can out-order by mount position. Returning
+`{ kind: 'retry' }` without calling `next()` vetoes summarization for that attempt.
+
+Scope, deliberately narrow:
+
+| Event | Behaviour |
+|---|---|
+| `CONTEXT_WINDOW_EXCEEDED` on `agent/request-error` | trim, then retry |
+| any other request failure | untouched (`next()`) |
+| ordinary threshold compaction (`agent/pre-step` pressure) | **never touched** |
+| `/compact`, the tool-result pruner | **never touched** |
+
+The per-episode retry budget (`maxAutoTrimRetries`, default 1) resets when a completed assistant message lands or the
+agent goes idle, mirroring compaction's own overflow accounting. Set `autoTrim: false` to keep trimming manual.
+
+Trade-off, stated plainly: an automatic trim **drops** the oldest span instead of summarizing it. On a small local
+window that is the point — the summarizer must fit the region it is condensing and frequently cannot — but the dropped
+text is replaced by a marker rather than a summary. `/compact` stays available, and the full text remains in the
+durable session log.
+
 ## What is protected
 
 | Protected | Why |
 |---|---|
 | Leading `protectHeadNodes` nodes (default 1) | The task statement — dropping it destroys the point of the conversation. |
 | Recent tail (`retainRatio` of the window, floor `minTailTokens`) | Recency is what a coding agent needs; retention is relaxed only when the fit is otherwise impossible, and the result says so. |
-| The final surface node | Never elided, even when trimming into the tail. |
+| The **newest** `user/message` | The live human instruction. It is never elided and no span may cross it, so an ongoing request cannot be dropped. Older user messages are ordinary nodes. |
+| The final surface message | **A preference, not a prohibition.** Kept whenever any older span can free enough; dropped only as a last resort, and typically only together with its tool call (they can only be removed as a pair). |
 
 Within those bounds the policy is **oldest-first, least-long-possible**: the elided span starts at the oldest balanced cut
 and grows only until it frees exactly enough tokens.
 
+Elision always starts at the **oldest** balanced cut, and the search is graded so that the cheapest loss is tried first:
+
+1. a span that stays **outside the retained tail** and keeps the **final message** (the configured retention, relaxed step
+   by step only if the fit otherwise fails);
+2. a span that may reach **into the retained tail**, still keeping the final message;
+3. **last resort** — a span that includes the final message, typically the current step's assistant tool-call plus its tool
+   result, which can only be removed as a pair.
+
+Protecting the final message outright deadlocks the most common overflow shape: one large assistant tool-call whose tool
+result is the last node cannot be removed as a pair, which left a handful of freeable tokens while the request stayed over
+the wall (observed live: "largest balanced span frees ~4 of the ~4631 tokens needed"). The newest user message is the real
+anchor and stays a hard barrier in every tier. With `allowTailTrim: false` the search ends after tier 1, so the retained
+tail is a hard boundary and the final message is never dropped.
+
 ## Compatibility
 
 | Harness | State |
@@ -126,8 +175,10 @@ Override on the `context-trim` row of a profile patch (the bundle's own `cordis.
 | `retainRatio` / `retainTokens` | `0.16` / — | Recent tail kept verbatim (mutually exclusive forms) |
 | `minTailTokens` | `2048` | Absolute floor for that tail |
 | `protectHeadNodes` | `1` | Leading nodes that are never trimmed |
-| `allowTailTrim` | `true` | Let the elided span reach into the retained tail when necessary |
+| `allowTailTrim` | `true` | Enable tiers 2–3 (reach into the retained tail; as a last resort include the final message). `false` ends the search after tier 1, making the retained tail a hard boundary |
 | `markerSlackTokens` | `64` | Slack added to the priced marker so the post-trim request stays under budget |
+| `autoTrim` | `true` | Trim automatically on `CONTEXT_WINDOW_EXCEEDED`; never fires on ordinary compaction |
+| `maxAutoTrimRetries` | `1` | Automatic trims allowed per overflow episode before compaction takes over |
 
 ## Limits
 
@@ -143,6 +194,23 @@ Override on the `context-trim` row of a profile patch (the bundle's own `cordis.
 
 ## Development
 
+### End-to-end overflow check (no model needed)
+
+`scripts/mock-overflow-server.mjs` is a stateful OpenAI-compatible endpoint that enforces a **real** limit lower than the
+`contextWindow` the harness is told, and answers the first `TOOL_STEPS` requests with a tool call so one turn keeps
+looping and grows past the real limit — the context wall, without a model switch:
+
+```bash
+node scripts/mock-overflow-server.mjs &            # PORT=4185 TOKEN_LIMIT=12000 TOOL_STEPS=4
+# point an ISOLATED profile at it (provider with contextWindow 20000, baseURL .../v1), then:
+DSH_HOME=$(mktemp -d) dsh --profile headless "..."   # see the isolated-home procedure in dsh-plugin-packaging
+```
+
+A passing run leaves this in the session log: `assistant/attempt` (the wall), then exactly one `compaction/prune` + one
+`user/message` replacement, then a **succeeding** retry — and **zero** `compaction/start`, proving the request was
+repaired by trimming and that summarisation never ran.
+
+
 ```bash
 npm install            # the harness contracts this plugin builds on, pinned as devDependencies
 npm test               # node --test
@@ -159,13 +227,14 @@ releases go out through `.github/workflows/publish.yml`, which is manual-only (`
 
 | Check | State |
 |---|---|
-| `npm test` (34 tests: planner, args, surface apply + log replay, plugin handler) | ✅ passing |
+| `npm test` (51 tests: planner, args, surface apply + log replay, plugin handler, automatic overflow path) | ✅ passing |
 | Isolated `DSH_HOME` install (`dsh plugin add file:…`) reconciling dependency **and** bundle layer | ✅ verified |
 | Composed profile tree contains the `context-trim` insert row (`dsh --dump-config`) | ✅ verified |
 | Profile boot with the plugin mounted (no load error) | ✅ reaches the credential check cleanly |
-| Same suite against the pinned **published** harness packages (`npm ci`) | ✅ 34 passing |
+| Same suite against the pinned **published** harness packages (`npm ci`) | ✅ 51 passing |
 | Integration against the **real** `ctx.tokenMeter`: measured drop equals the claimed shadow price, and a fresh meter replaying the trimmed log reaches the identical total | ✅ 4 tests |
-| Same suite on harness 0.1.5-rc.2 (renamed marker + surface system prompt) | ✅ 40 passing |
+| Real-`cordis` proof that a `prepend`ed waterfall listener runs first and vetoes the chain (the mechanism the automatic path depends on) | ✅ 3 tests |
+| Same suite on harness 0.1.5-rc.2 (renamed marker + surface system prompt) | ✅ 51 passing |
 | CI workflow (Node 22 / 24) | ✅ green |
 | npm release via GitHub Actions | ✅ 0.1.0 published with provenance (`+ dsh-command-context-trim@0.1.0`) |
 | Isolated profile install **from the npm registry** (dependency + bundle layer + composed insert row) | ✅ 0.1.0 |

package/README.zh.md

@@ -53,9 +53,38 @@ dsh plugin --profile web add file:/path/to/dsh-command-context-trim   # 从源
 - **与其它机制互斥**：命令在 `agent.runMaintenance()` 内执行（非 idle 直接失败），不会与回合、`/compact`、自动压缩交错；
   存在未闭合的 `compaction/start` 时也会拒绝执行。
 
+## 撞墙自动 trim
+
+`autoTrim`（默认开）让同一套"无模型调用"的裁剪在无人值守时发生：用 **`prepend`** 注册的 `agent/request-error`
+监听器在 `CONTEXT_WINDOW_EXCEEDED` 时裁剪并请求重试。
+
+```
+请求撞墙
+  ├─ prepend: context-trim   → 裁剪一段，零模型调用 → retry       ← 能腾出空间时由它解决
+  └─ next(): compaction-basic → 先 prune 工具结果再摘要（LLM）     ← 只在 trim 无能为力时
+```
+
+为什么 `prepend` 是关键：`agent/request-error` 是 Cordis 的 **waterfall**，compaction 也在同一事件上注册了自己的
+摘要恢复；Cordis 按注册顺序存放监听器，`{ prepend: true }` 会 `unshift` 到最前，所以即使 compaction 是稍后在
+agent-preset 的 isolate realm 里挂载的（web profile 里就是这样），本插件依然先执行。不调用 `next()` 即否决该次
+摘要。
+
+**范围刻意收窄**：只有 `CONTEXT_WINDOW_EXCEEDED` 才触发；其它请求错误、普通阈值 compaction（`agent/pre-step` 压力路径）、
+`/compact`、工具结果 pruner **一律不碰**（有测试锁定注册的监听器集合）。
+
+每轮溢出 epis 的额度由 `maxAutoTrimRetries`（默认 1）限制，收到完成的 assistant 消息或 agent 空闲即重置。
+代价如实说：自动 trim 是**丢弃**最旧一段而不是摘要它——在小窗口下这正是要点，但被丢的内容只会变成一条占位标记。
+`/compact` 仍在，原文也仍在会话日志里。
+
 ## 保护集与选段策略
 
-保护：开头 `protectHeadNodes`（默认 1，即任务声明）、末尾最近 `retainRatio` 窗口（下限 `minTailTokens`）、以及最后一条消息永不裁剪。
+保护与**优先级**（永远从最旧处开始裁，按"损失最小"逐档尝试）：
+
+1. 留在保留尾部之外，且**保留最后一条**（先按配置的保留量；实在放不下才逐级放宽保留量）；
+2. 可以进入保留尾部，但仍**保留最后一条**；
+3. **最后一档**才允许把最后一条纳入——通常就是当前这步的 assistant tool-call 与它的 tool-result（两者只能成对移除）。
+
+另外：开头 `protectHeadNodes`（默认 1，即任务声明）与**最新的那条 `user/message`（你当前的指令）是硬屏障**——永不裁剪、也不被跨越。把最后一条按位置硬保护会卡死最常见的溢出形态（实测探针：`largest balanced span frees ~4 of the ~4631 tokens needed`）。`allowTailTrim: false` 时搜索在第 1 档后结束：保留尾部成为硬边界，最后一条永不丢弃。
 在保护集之间采用**最旧优先、够用即止**：从最旧的平衡切点开始，只增长到刚好释放够 token。
 
 ## 兼容性
@@ -99,7 +128,7 @@ npm run link:harness   # 也可改为从本地 dsh 安装的依赖闭包解析 @
 已验证：34 个测试全部通过（选段算法、参数解析、真实 Session 上的 surface 改写与日志重放、插件命令注册与端到端裁剪，以及用**真实 `ctx.tokenMeter`** 验证「实测降幅 == 声明的 shadow price」和「新进程重放裁剪后日志得到完全一致的总量」）；
 隔离 `DSH_HOME` 安装后 dependency 与 bundle 层均正确 reconcile；`dsh --dump-config` 中出现 `context-trim` 行；profile 启动无加载错误。
 CI 在 Node 22/24 上跑同一套测试；发布通过 `.github/workflows/publish.yml`（手动 `workflow_dispatch`）。
-npm 0.1.1 已发布（带 provenance），并已在隔离 profile 里从 registry 安装验证；尚未执行：Web GUI 里的真实小窗口端到端验证（mock provider 与隔离实例已就绪）。
+npm 0.2.0（新增撞墙自动 trim），并已在隔离 profile 里从 registry 安装验证；尚未执行：Web GUI 里的真实小窗口端到端验证（mock provider 与隔离实例已就绪）。
 
 ## License
 

package/cordis.patch.yml

@@ -27,3 +27,9 @@
         # Slack added to the priced replacement marker, so the post-trim request
         # stays under budget even though the marker text carries real numbers.
         markerSlackTokens: 64
+        # Trim automatically when a request hits the model's context wall
+        # (CONTEXT_WINDOW_EXCEEDED) instead of going straight to compaction.
+        # Ordinary threshold compaction is never touched.
+        autoTrim: true
+        # Automatic trims allowed per overflow episode before compaction takes over.
+        maxAutoTrimRetries: 1

package/lib/auto-trim.js

@@ -0,0 +1,87 @@
+/**
+ * Automatic trimming when a request hits the model's context wall.
+ *
+ * This is the unattended neighbour of `/trim`: a **prepended**
+ * `agent/request-error` listener reacts to `CONTEXT_WINDOW_EXCEEDED`, frees space
+ * with no model call, and asks the loop to retry. Only when it cannot help does
+ * the waterfall continue into DSH's own recovery — which prunes oversized tool
+ * results and then *summarizes*. That ordering is the whole point: dropping the
+ * oldest span is cheap and works when every request is failing, whereas the
+ * summarizer must itself fit the window while holding the region it is condensing,
+ * so on a small local window it frequently fails for the same reason the original
+ * request did.
+ *
+ * Why `prepend` matters: `agent/request-error` is a Cordis **waterfall**, and
+ * `@deepseek-ai/dsh-compaction-basic` registers its summarization recovery on the
+ * same event. Listeners are stored in registration order and `{ prepend: true }`
+ * unshifts to the front, so this listener runs first regardless of which bundle
+ * mounted compaction (in a web profile compaction lives inside an agent-preset
+ * isolate realm, mounted later than any host-plane plugin). Returning
+ * `{ kind: 'retry' }` without calling `next()` vetoes the rest of the chain for
+ * that attempt; calling `next()` hands the problem to compaction.
+ *
+ * @module dsh-command-context-trim/auto-trim
+ */
+import { CONTEXT_WINDOW_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm';
+import { logLine, describeError } from './render.js';
+import { executeTrim } from './trim-session.js';
+
+/**
+ * Register automatic context-overflow trimming.
+ * @param ctx - plugin context (token meter, LLM service, events, logger).
+ * @param config - resolved configuration.
+ * @returns nothing; listeners are owned by the plugin's fiber and disposed with it.
+ */
+export function registerAutoTrim(ctx, config) {
+	if (config.autoTrim !== true) return;
+	/** agent -> automatic trims already spent in the current overflow episode. */
+	const spent = new WeakMap();
+	/** session -> agent, so a successful assistant message can reset the budget. */
+	const actors = new WeakMap();
+	ctx.on(
+		'agent/request-error',
+		async ({ agent, failure, signal }, next) => {
+			if (failure?.code !== CONTEXT_WINDOW_EXCEEDED_CODE || signal.aborted) return next();
+			const used = spent.get(agent) ?? 0;
+			if (used >= config.maxAutoTrimRetries) {
+				log(ctx, 'info', `context-overflow auto-trim: retry budget spent (${used}); leaving recovery to compaction`);
+				return next();
+			}
+			const generation = agent.session.surface.replaceGeneration;
+			let outcome;
+			try {
+				outcome = await executeTrim(ctx, config, { agent, signal, routedOnly: true });
+			} catch (error) {
+				log(ctx, 'warn', `context-overflow auto-trim failed (${describeError(error)}); leaving recovery to compaction`);
+				return next();
+			}
+			if (signal.aborted) return next();
+			if (agent.session.surface.replaceGeneration <= generation) {
+				log(ctx, 'info', `context-overflow auto-trim: nothing safely trimmable; leaving recovery to compaction`);
+				return next();
+			}
+			spent.set(agent, used + 1);
+			actors.set(agent.session, agent);
+			log(ctx, 'info', `context-overflow auto-trim: ${logLine(outcome.plan, outcome.after, outcome.label)}`);
+			return { kind: 'retry' };
+		},
+		{ prepend: true }
+	);
+	// Mirror compaction-basic's accounting: one overflow episode's budget resets
+	// once the conversation advances or the agent goes idle.
+	ctx.on('agent/status', ({ agent, status }) => {
+		if (status === 'idle') spent.delete(agent);
+	});
+	ctx.on('session/event', (session, event) => {
+		if (event.type !== 'assistant/message') return;
+		const agent = actors.get(session);
+		if (agent !== undefined) spent.delete(agent);
+	});
+}
+
+/** Log through the context logger when it is available. */
+function log(ctx, level, message) {
+	const logger = ctx.logger;
+	if (logger?.[level] === undefined) return;
+	logger[level](`context-trim: ${message}`);
+}

package/lib/config.js

@@ -15,7 +15,9 @@ export const DEFAULTS = Object.freeze({
 	minTailTokens: 2048,
 	protectHeadNodes: 1,
 	allowTailTrim: true,
-	markerSlackTokens: 64
+	markerSlackTokens: 64,
+	autoTrim: true,
+	maxAutoTrimRetries: 1
 });
 
 /** Every key this plugin accepts. */
@@ -27,7 +29,9 @@ const CONFIG_KEYS = new Set([
 	'minTailTokens',
 	'protectHeadNodes',
 	'allowTailTrim',
-	'markerSlackTokens'
+	'markerSlackTokens',
+	'autoTrim',
+	'maxAutoTrimRetries'
 ]);
 
 /**
@@ -48,11 +52,15 @@ export function resolveConfig(config = {}) {
 	const protectHeadNodes = config.protectHeadNodes ?? DEFAULTS.protectHeadNodes;
 	const allowTailTrim = config.allowTailTrim ?? DEFAULTS.allowTailTrim;
 	const markerSlackTokens = config.markerSlackTokens ?? DEFAULTS.markerSlackTokens;
+	const autoTrim = config.autoTrim ?? DEFAULTS.autoTrim;
+	const maxAutoTrimRetries = config.maxAutoTrimRetries ?? DEFAULTS.maxAutoTrimRetries;
 	assertRatio('targetRatio', targetRatio);
 	assertNonNegativeInteger('reserveOutputTokens', reserveOutputTokens);
 	assertNonNegativeInteger('minTailTokens', minTailTokens);
 	assertNonNegativeInteger('protectHeadNodes', protectHeadNodes);
 	assertNonNegativeInteger('markerSlackTokens', markerSlackTokens);
+	assertNonNegativeInteger('maxAutoTrimRetries', maxAutoTrimRetries);
+	if (typeof autoTrim !== 'boolean') throw new Error('ContextTrimConfig: autoTrim must be a boolean');
 	if (typeof allowTailTrim !== 'boolean') throw new Error('ContextTrimConfig: allowTailTrim must be a boolean');
 	const retention = resolveRetention(config);
 	if (retention.retainRatio !== undefined && retention.retainRatio >= targetRatio) {
@@ -65,7 +73,9 @@ export function resolveConfig(config = {}) {
 		minTailTokens,
 		protectHeadNodes,
 		allowTailTrim,
-		markerSlackTokens
+		markerSlackTokens,
+		autoTrim,
+		maxAutoTrimRetries
 	});
 }
 

package/lib/index.js

@@ -13,16 +13,19 @@
  * synchronous appends, zero LLM calls, so it works precisely when every request
  * is failing.
  *
+ * The same execution also runs **automatically** on the context wall: a
+ * prepended `agent/request-error` listener trims on `CONTEXT_WINDOW_EXCEEDED` and
+ * retries, and only hands the problem to compaction (prune + summarize) when it
+ * cannot free anything — see `./auto-trim.js`.
+ *
  * @module dsh-command-context-trim
  */
-import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction';
 import z from '@deepseek-ai/schemastery';
 import { parseTrimArguments, USAGE } from './args.js';
-import { applyTrim, createMarkerMessage, provisionalMarker } from './apply.js';
-import { budgetFor, resolveConfig, retentionFor } from './config.js';
-import { planTrim } from './plan.js';
-import { resolveTarget, targetHeader } from './target.js';
-import { replaceKeys } from './session-compat.js';
+import { registerAutoTrim } from './auto-trim.js';
+import { resolveConfig } from './config.js';
+import { describeError } from './render.js';
+import { executeTrim } from './trim-session.js';
 
 /** Cordis plugin name. */
 export const name = 'context-trim';
@@ -30,7 +33,7 @@ export const name = 'context-trim';
 /** Services required before the command can be registered. */
 export const inject = ['commands', 'tokenMeter', 'llm'];
 
-/** Loader-facing configuration shape; ranges are enforced by {@link resolveConfig}. */
+/** Loader-facing configuration shape; ranges are enforced by `resolveConfig`. */
 export const Config = z.object({
 	targetRatio: z.number(),
 	reserveOutputTokens: z.number(),
@@ -39,11 +42,14 @@ export const Config = z.object({
 	minTailTokens: z.number(),
 	protectHeadNodes: z.number(),
 	allowTailTrim: z.boolean(),
-	markerSlackTokens: z.number()
+	markerSlackTokens: z.number(),
+	autoTrim: z.boolean(),
+	maxAutoTrimRetries: z.number()
 });
 
 /**
- * Register `/trim` for every composed human-command adapter.
+ * Register `/trim` for every composed human-command adapter, and the automatic
+ * context-overflow handler for every agent.
  * @param ctx - context carrying the command registry, token meter, and LLM service.
  * @param config - untrusted plugin configuration.
  */
@@ -70,6 +76,7 @@ export function apply(ctx, config) {
 			handler
 		});
 	}, 'context-trim lifecycle');
+	registerAutoTrim(ctx, resolved);
 }
 
 /**
@@ -84,7 +91,17 @@ async function execute(ctx, config, invocation) {
 	if (parsed.error !== undefined) return { kind: 'error', text: `${parsed.error}\n${USAGE}` };
 	let running;
 	try {
-		running = invocation.agent.runMaintenance((agentSignal) => trimOnce(ctx, config, invocation, parsed, agentSignal));
+		running = invocation.agent.runMaintenance(async (agentSignal) => {
+			const signal = AbortSignal.any([invocation.signal, agentSignal]);
+			const { result } = await executeTrim(ctx, config, {
+				agent: invocation.agent,
+				signal,
+				requestedRoute: parsed.route,
+				explicitBudget: parsed.budget,
+				check: parsed.check
+			});
+			return result;
+		});
 	} catch (error) {
 		return { kind: 'error', text: `Trim needs an idle agent: ${describeError(error)}` };
 	}
@@ -95,147 +112,3 @@ async function execute(ctx, config, invocation) {
 		return { kind: 'error', text: `Trim failed: ${describeError(error)}` };
 	}
 }
-
-/**
- * Plan and apply one trim; the whole session-visible mutation happens here.
- * @param ctx - plugin context.
- * @param config - resolved configuration.
- * @param invocation - command invocation (agent, signal).
- * @param parsed - parsed command arguments.
- * @param agentSignal - cancellation owned by the maintenance reservation.
- * @returns a command result.
- */
-async function trimOnce(ctx, config, invocation, parsed, agentSignal) {
-	const signal = AbortSignal.any([invocation.signal, agentSignal]);
-	signal.throwIfAborted();
-	const session = invocation.agent.session;
-	assertNoOpenCompaction(session);
-	const target = parsed.budget === undefined ? await resolveTarget(ctx, invocation.agent, parsed.route, signal) : undefined;
-	const budget = parsed.budget ?? budgetFor(target.contextWindow, config);
-	const label = target === undefined ? `an explicit ${budget}-token budget` : `${target.label} (window ${target.contextWindow})`;
-	const header = target === undefined ? undefined : targetHeader(session, target);
-	const measurement = ctx.tokenMeter.measure(session, header);
-	const nodes = measurement.nodes.map((node) => ({
-		seq: node.seq,
-		heuristicTokens: node.heuristicTokens,
-		// Harness 0.1.5+ carries the system prompt as surface node 0. It is never
-		// elidable, and no elided span may cross it: dropping it would strip the
-		// model's instructions, and letting it consume head protection would expose
-		// the user's original request instead.
-		...(session.eventAt(node.seq)?.type === 'system/message' ? { barrier: true } : {})
-	}));
-	if (nodes.length === 0) {
-		return { kind: 'success', text: `Nothing to trim: ${session.id} has no model-visible messages yet.` };
-	}
-	// The retained tail scales with the capacity being fitted: the target window
-	// when one is known, otherwise the explicit budget itself.
-	const retainTokens = retentionFor(target?.contextWindow ?? budget, config);
-	const envelopeTokens = Math.max(0, measurement.totalTokens - measurement.surfaceTokens);
-	const planFor = (markerTokens) =>
-		planTrim({
-			nodes,
-			envelopeTokens,
-			budget,
-			markerCost: markerTokens + config.markerSlackTokens,
-			retainTokens,
-			minTailTokens: config.minTailTokens,
-			protectHeadNodes: config.protectHeadNodes,
-			allowTailTrim: config.allowTailTrim,
-			isBalancedBefore: (seq) => toolPairingBalancedBefore(session, seq),
-			isBalancedAfter: (seq) => toolPairingBalancedAfter(session, seq)
-		});
-	let markerTokens = ctx.tokenMeter.estimateMessage(provisionalMarker());
-	let plan = planFor(markerTokens);
-	if (plan.kind !== 'span') return describeNonSpan(plan, label);
-	let marker = createMarkerMessage(plan, target?.label ?? `budget ${budget}`, budget);
-	const finalMarkerTokens = ctx.tokenMeter.estimateMessage(marker);
-	if (finalMarkerTokens > markerTokens) {
-		// The marker now carries real numbers; re-plan once so its own price is exact.
-		plan = planFor(finalMarkerTokens);
-		if (plan.kind !== 'span') return describeNonSpan(plan, label);
-		marker = createMarkerMessage(plan, target?.label ?? `budget ${budget}`, budget);
-		markerTokens = finalMarkerTokens;
-	}
-	if (parsed.check) return { kind: 'success', text: preview(plan, label, markerTokens) };
-	const replacement = applyTrim(session, plan, marker, replaceKeys());
-	const after = ctx.tokenMeter.measure(session, header);
-	return { kind: 'success', text: report(plan, after, label, markerTokens), sourceEventSeq: replacement.seq };
-}
-
-/** Refuse to rewrite a surface while a compaction bracket is open. */
-function assertNoOpenCompaction(session) {
-	for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
-		const event = session.eventAt(seq);
-		if (event === undefined) continue;
-		if (event.type === 'compaction/end') return;
-		// A seed boundary proves any earlier unmatched start belongs to a previous lifecycle.
-		if (event.type === 'session/end-seed') return;
-		if (event.type === 'compaction/start') {
-			throw new Error('a compaction is already in progress in this session; wait for it to finish, then retry');
-		}
-	}
-}
-
-/** Render every non-span outcome as a final command result. */
-function describeNonSpan(plan, label) {
-	switch (plan.kind) {
-		case 'fits':
-			return {
-				kind: 'success',
-				text: `Already within budget: ~${plan.totalTokens} / ${plan.budget} tokens for ${label}. Nothing to trim.`
-			};
-		case 'envelope':
-			return {
-				kind: 'error',
-				text: [
-					`Fixed request overhead alone (~${plan.envelopeTokens} tokens of tool schemas and other non-surface request data) exceeds the ${plan.budget}-token budget for ${label}.`,
-					'Trimming conversation history cannot help: raise the backend context size (the model\'s contextWindow in settings.yaml, or the server\'s context flag) or reduce mounted tools and skills, then retry.'
-				].join('\n')
-			};
-		case 'no-span':
-			return {
-				kind: 'error',
-				text: `Nothing safely trimmable for ${label}: ${plan.reason}, or no tool-pairing balanced cut exists.`
-			};
-		case 'insufficient':
-			return {
-				kind: 'error',
-				text: [
-					`Cannot free enough for ${label}: the largest balanced span frees ~${plan.maxFreeable} of the ~${plan.need} tokens needed.`,
-					`Protected content: task statement ~${plan.protectedHeadTokens} tokens, recent tail ~${plan.protectedTailTokens} tokens (retain target ~${plan.retainTokens})${plan.hasBarrier ? ', plus the system prompt, which is never trimmed' : ''}.`,
-					'Try /compact (it summarizes instead of dropping), a larger window, or /trim with an explicit budget after another reduction.'
-				].join('\n')
-			};
-		default:
-			return { kind: 'error', text: `Trim could not plan a reduction (${String(plan.kind)}).` };
-	}
-}
-
-/** Render a dry run. */
-function preview(plan, label, markerTokens) {
-	return [
-		`Would trim ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}, ~${plan.shadowedTokens} tokens → ${markerTokens}-token marker) for ${label}.`,
-		`Request size: ~${plan.totalTokens} → ~${plan.projectedTotal} tokens (target ${plan.budget}). Nothing was changed.`
-	].join('\n');
-}
-
-/** Render a committed trim against the re-measured request. */
-function report(plan, after, label, markerTokens) {
-	const lines = [
-		`Trimmed ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}, ~${plan.shadowedTokens} tokens → ${markerTokens}-token marker) for ${label}.`,
-		`Request size: ~${plan.totalTokens} → ~${after.totalTokens} tokens (target ${plan.budget}).`
-	];
-	if (plan.relaxedRetention) {
-		lines.push(`Retention relaxed to ~${plan.retainTokens} tokens to reach the budget.`);
-	}
-	return lines.join('\n');
-}
-
-/** Render a thrown value without trusting its string coercion. */
-function describeError(error) {
-	try {
-		return error instanceof Error ? error.message : String(error);
-	} catch {
-		return '<unrenderable thrown value>';
-	}
-}

package/lib/plan.js

@@ -17,7 +17,11 @@
  *   original request instead. Barriers are therefore untouchable and split the
  *   elidable space into regions, and `protectHeadNodes` counts only non-barrier
  *   nodes so it keeps protecting the task statement.
- * - **The final node**, and the retained tail.
+ * - **The newest `user/message`** — the live human instruction — plus the
+ *   retained tail. An earlier rule protected the final surface node outright,
+ *   which deadlocked exactly the common overflow shape: a large assistant
+ *   tool-call whose tool result is the last node could not be removed as a pair,
+ *   leaving only a few tokens freeable while the request stayed over the wall.
  *
  * Nothing here touches a session: the planner receives measured node prices and
  * two balance predicates, so every branch is directly testable.
@@ -31,6 +35,8 @@
  * @property {number} heuristicTokens - the token meter's heuristic price for it.
  * @property {boolean} [barrier] - true for a node that may never be elided and
  *   that no elided span may cross (the system prompt).
+ * @property {boolean} [userMessage] - true for human prompts; the newest one is
+ *   treated as a barrier so an ongoing instruction is never elided.
  */
 
 /**
@@ -69,20 +75,21 @@ export function planTrim(input) {
 	const need = common.totalTokens - input.budget;
 	const configuredRetention = input.retainTokens;
 	let weakest = null;
-	for (const retainTokens of retentionLadder(configuredRetention, input.minTailTokens)) {
-		const attempt = attemptSpan({ ...input, retainTokens, need });
+	for (const configuration of attemptConfigurations(input, configuredRetention)) {
+		const attempt = attemptSpan({ ...input, ...configuration, need });
 		if (attempt.kind === 'span') {
 			return {
 				kind: 'span',
 				...common,
 				...attempt,
 				need,
-				retainTokens,
-				relaxedRetention: retainTokens < configuredRetention,
+				retainTokens: configuration.retainTokens,
+				relaxedRetention: configuration.retainTokens < configuredRetention,
+				reachedFinalNode: configuration.allowFinalNode === true,
 				projectedTotal: common.totalTokens - attempt.freedTokens
 			};
 		}
-		if (weakest === null || attempt.maxFreeable > weakest.maxFreeable) weakest = { ...attempt, retainTokens };
+		if (weakest === null || attempt.maxFreeable > weakest.maxFreeable) weakest = { ...attempt, retainTokens: configuration.retainTokens };
 	}
 	return {
 		kind: 'insufficient',
@@ -91,10 +98,44 @@ export function planTrim(input) {
 		maxFreeable: weakest?.maxFreeable ?? 0,
 		protectedHeadTokens: protectedHeadTokens(input.nodes, input.protectHeadNodes),
 		protectedTailTokens: weakest?.protectedTailTokens ?? 0,
+		protectedUserTokens: weakest?.protectedUserTokens ?? 0,
 		retainTokens: configuredRetention
 	};
 }
 
+/**
+ * The search order, most conservative first. The final surface node is a
+ * *preference*, not a law: keeping it is always tried before dropping it, and
+ * dropping it happens only when no other span can free enough.
+ *
+ * 1. stay outside the retained tail and keep the final node (the configured
+ *    retention, relaxed step by step only if the fit otherwise fails);
+ * 2. may reach into the retained tail, still keeping the final node;
+ * 3. last resort: a span that includes the final node (typically the current
+ *    step's assistant tool-call plus its tool result, which can only be removed
+ *    as a pair).
+ *
+ * Elision always starts at the oldest balanced cut, so within every tier the
+ * oldest content goes first. A strict `allowTailTrim: false` ends the list after
+ * tier 1: the retained tail then is a hard boundary.
+ * @param input - planning input.
+ * @param configuredRetention - the preferred verbatim recent-tail budget.
+ * @returns ordered attempt configurations.
+ */
+function attemptConfigurations(input, configuredRetention) {
+	const insideTail = retentionLadder(configuredRetention, input.minTailTokens).map((retainTokens) => ({
+		retainTokens,
+		tailHard: true,
+		allowFinalNode: false
+	}));
+	if (input.allowTailTrim !== true) return insideTail;
+	return [
+		...insideTail,
+		{ retainTokens: configuredRetention, tailHard: false, allowFinalNode: false },
+		{ retainTokens: configuredRetention, tailHard: false, allowFinalNode: true }
+	];
+}
+
 /**
  * Try one retention budget, returning the smallest oldest-anchored balanced span
  * that frees at least `need` tokens.
@@ -104,17 +145,25 @@ export function planTrim(input) {
 function attemptSpan(input) {
 	const nodes = input.nodes;
 	const tailStart = tailStartIndex(nodes, input.retainTokens);
-	const lastElidable = input.allowTailTrim ? nodes.length - 2 : Math.min(nodes.length - 2, tailStart - 1);
+	// The newest human instruction is the anchor: it must never be elided, and no
+	// span may cross it.
+	const newestUserIndex = newestUserMessageIndex(nodes);
+	// How far right a span may reach: a hard tail boundary when this attempt keeps
+	// the retained tail, otherwise the end of the surface.
+	const tailFloor = input.tailHard === true ? Math.min(nodes.length - 1, tailStart - 1) : nodes.length - 1;
+	// The final node is kept unless this attempt is the last-resort tier.
+	const lastElidable = input.allowFinalNode === true ? tailFloor : Math.min(tailFloor, nodes.length - 2);
 	const shortfall = (maxFreeable) => ({
 		kind: 'shortfall',
 		maxFreeable,
 		protectedTailTokens: tailTokens(nodes, tailStart),
-		protectedHeadTokens: protectedHeadTokens(nodes, input.protectHeadNodes)
+		protectedHeadTokens: protectedHeadTokens(nodes, input.protectHeadNodes),
+		protectedUserTokens: newestUserIndex === -1 ? 0 : nodes[newestUserIndex].heuristicTokens
 	});
 	const headEnd = protectedHeadEnd(nodes, input.protectHeadNodes);
 	if (lastElidable < headEnd) return shortfall(0);
 	let weakest = null;
-	for (const region of elidableRegions(nodes, headEnd, lastElidable)) {
+	for (const region of elidableRegions(nodes, headEnd, lastElidable, newestUserIndex)) {
 		const attempt = attemptRegion(nodes, region, input);
 		if (attempt === null) continue;
 		if (attempt.kind === 'span') return attempt;
@@ -172,12 +221,26 @@ function protectedHeadEnd(nodes, protectHeadNodes) {
 	return nodes.length;
 }
 
-/** Maximal runs of elidable indices inside `[from, to]`. */
-function elidableRegions(nodes, from, to) {
+/** Index of the newest human prompt on the surface, or -1 when there is none. */
+function newestUserMessageIndex(nodes) {
+	let found = -1;
+	for (let index = 0; index < nodes.length; index += 1) if (nodes[index].userMessage === true) found = index;
+	return found;
+}
+
+/**
+ * Maximal runs of elidable indices inside `[from, to]`.
+ * @param nodes - full priced surface.
+ * @param from - inclusive first index to consider.
+ * @param to - inclusive last index to consider.
+ * @param extraBarrier - one additional index treated as a barrier (the newest user message).
+ * @returns contiguous index runs a span may occupy.
+ */
+function elidableRegions(nodes, from, to, extraBarrier) {
 	const regions = [];
 	let start = null;
 	for (let index = from; index <= to; index += 1) {
-		if (nodes[index].barrier === true) {
+		if (nodes[index].barrier === true || index === extraBarrier) {
 			if (start !== null) regions.push({ start, end: index - 1 });
 			start = null;
 			continue;

package/lib/render.js

@@ -0,0 +1,115 @@
+/**
+ * Command-result and log rendering, shared by the `/trim` command and the
+ * automatic context-overflow path.
+ *
+ * @module dsh-command-context-trim/render
+ */
+
+/**
+ * Render every non-span planning outcome as a final command result.
+ * @param plan - the plan returned by `planTrim`.
+ * @param label - human label of the target route.
+ * @returns a command result.
+ */
+export function describeNonSpan(plan, label) {
+	switch (plan.kind) {
+		case 'fits':
+			return {
+				kind: 'success',
+				text: `Already within budget: ~${plan.totalTokens} / ${plan.budget} tokens for ${label}. Nothing to trim.`
+			};
+		case 'envelope':
+			return {
+				kind: 'error',
+				text: [
+					`Fixed request overhead alone (~${plan.envelopeTokens} tokens of tool schemas and other non-surface request data) exceeds the ${plan.budget}-token budget for ${label}.`,
+					'Trimming conversation history cannot help: raise the backend context size (the model\'s contextWindow in settings.yaml, or the server\'s context flag) or reduce mounted tools and skills, then retry.'
+				].join('\n')
+			};
+		case 'no-span':
+			return {
+				kind: 'error',
+				text: `Nothing safely trimmable for ${label}: ${plan.reason}, or no tool-pairing balanced cut exists.`
+			};
+		case 'insufficient':
+			return {
+				kind: 'error',
+				text: [
+					`Cannot free enough for ${label}: the largest balanced span frees ~${plan.maxFreeable} of the ~${plan.need} tokens needed.`,
+					`Protected content: task statement ~${plan.protectedHeadTokens} tokens, recent tail ~${plan.protectedTailTokens} tokens (retain target ~${plan.retainTokens})` +
+						`${plan.protectedUserTokens > 0 ? `, newest instruction ~${plan.protectedUserTokens} tokens (never elided)` : ''}` +
+						`${plan.hasBarrier ? ', plus the system prompt, which is never trimmed' : ''}.`,
+					'Try /compact (it summarizes instead of dropping), a larger window, or /trim with an explicit budget after another reduction.'
+				].join('\n')
+			};
+		default:
+			return { kind: 'error', text: `Trim could not plan a reduction (${String(plan.kind)}).` };
+	}
+}
+
+/**
+ * Render a dry run.
+ * @param plan - a committed span plan.
+ * @param label - human label of the target route.
+ * @param markerTokens - measured price of the replacement marker.
+ * @returns the dry-run text.
+ */
+export function preview(plan, label, markerTokens) {
+	return [
+		`Would trim ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}, ~${plan.shadowedTokens} tokens → ${markerTokens}-token marker) for ${label}.`,
+		`Request size: ~${plan.totalTokens} → ~${plan.projectedTotal} tokens (target ${plan.budget}). Nothing was changed.`,
+		...(plan.reachedFinalNode === true
+			? ['Note: nothing else can free enough — this plan has to remove the final surface message as a tool-call/result pair.']
+			: [])
+	].join('\n');
+}
+
+/**
+ * Render a committed trim against the re-measured request.
+ * @param plan - the committed span plan.
+ * @param after - post-trim measurement.
+ * @param label - human label of the target route.
+ * @param markerTokens - measured price of the replacement marker.
+ * @returns the report text.
+ */
+export function report(plan, after, label, markerTokens) {
+	const lines = [
+		`Trimmed ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}, ~${plan.shadowedTokens} tokens → ${markerTokens}-token marker) for ${label}.`,
+		`Request size: ~${plan.totalTokens} → ~${after.totalTokens} tokens (target ${plan.budget}).`
+	];
+	if (plan.relaxedRetention) {
+		lines.push(`Retention relaxed to ~${plan.retainTokens} tokens to reach the budget.`);
+	}
+	if (plan.reachedFinalNode === true) {
+		lines.push('Nothing else could free enough: the final surface message was removed as part of a tool-call/result pair.');
+	}
+	return lines.join('\n');
+}
+
+/**
+ * Render a committed trim as one log line, for the automatic path.
+ * @param plan - the committed span plan.
+ * @param after - post-trim measurement.
+ * @param label - human label of the target route.
+ * @returns a single-line account.
+ */
+export function logLine(plan, after, label) {
+	return (
+		`freed ~${plan.freedTokens} tokens over ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}) for ${label}; ` +
+		`request ~${plan.totalTokens} → ~${after.totalTokens} tokens (budget ${plan.budget})` +
+		`${plan.reachedFinalNode === true ? ' (last resort: the final message went as a tool-call/result pair)' : ''}`
+	);
+}
+
+/**
+ * Render a thrown value without trusting its string coercion.
+ * @param error - the caught value (`unknown` in catch clauses).
+ * @returns a printable message.
+ */
+export function describeError(error) {
+	try {
+		return error instanceof Error ? error.message : String(error);
+	} catch {
+		return '<unrenderable thrown value>';
+	}
+}

package/lib/target.js

@@ -40,8 +40,10 @@ export function latestRoute(session) {
  * @returns `{ provider, model, contextWindow, label }`.
  * @throws when no route can be determined, the route is unknown, or its adapter declares no window.
  */
-export async function resolveTarget(ctx, agent, requested, signal) {
-	const route = requested ?? latestRoute(agent.session) ?? agentRoute(agent);
+export async function resolveTarget(ctx, agent, requested, signal, options = {}) {
+	const primary =
+		options.routedOnly === true ? routedTarget(agent.session) ?? latestRoute(agent.session) : latestRoute(agent.session);
+	const route = requested ?? primary ?? agentRoute(agent);
 	if (route === undefined) {
 		throw new Error('cannot determine the target model: select a model in this session first, or pass an explicit budget (e.g. /trim 32k)');
 	}
@@ -82,6 +84,20 @@ export function targetHeader(session, target) {
 	});
 }
 
+/**
+ * The route the last durable request was actually built for: the one that just
+ * overflowed during automatic recovery.
+ * @param session - session whose log is read.
+ * @returns `{ provider, model, source }`, or undefined when nothing was routed yet.
+ */
+export function routedTarget(session) {
+	const config = session.requestHeader()?.config;
+	if (config === undefined) return undefined;
+	if (typeof config.provider !== 'string' || config.provider.length === 0) return undefined;
+	if (typeof config.model !== 'string' || config.model.length === 0) return undefined;
+	return { provider: config.provider, model: config.model, source: 'request' };
+}
+
 /** Per-agent configured route, used only before any request was routed. */
 function agentRoute(agent) {
 	const provider = agent.options?.provider;

package/lib/trim-session.js

@@ -0,0 +1,129 @@
+/**
+ * One trim execution, shared by the `/trim` command and the automatic
+ * context-overflow path.
+ *
+ * Everything session-visible happens here: measure the current request under the
+ * target route, plan the oldest balanced span, and apply it as two synchronous
+ * appends. The caller owns only *when* to invoke it (`/trim` inside an idle-agent
+ * reservation, the automatic path inside a failing step) and how to render the
+ * outcome.
+ *
+ * @module dsh-command-context-trim/trim-session
+ */
+import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction';
+import { applyTrim, createMarkerMessage, provisionalMarker } from './apply.js';
+import { budgetFor, retentionFor } from './config.js';
+import { planTrim } from './plan.js';
+import { describeNonSpan, preview, report } from './render.js';
+import { replaceKeys } from './session-compat.js';
+import { resolveTarget, targetHeader } from './target.js';
+
+/**
+ * @typedef {object} TrimRequest
+ * @property {object} agent - agent owning the session to trim.
+ * @property {AbortSignal} [signal] - cancellation for the whole execution.
+ * @property {{ provider: string, model: string }} [requestedRoute] - explicit target route.
+ * @property {number} [explicitBudget] - explicit token budget instead of a resolved window.
+ * @property {boolean} [check] - plan only, mutate nothing.
+ * @property {boolean} [routedOnly] - target the route the last durable request used.
+ */
+
+/**
+ * Execute one trim.
+ * @param ctx - plugin context (token meter, LLM service).
+ * @param config - resolved configuration.
+ * @param request - what to trim and how far.
+ * @returns `{ result, plan?, label?, before?, after?, replacement?, markerTokens? }`;
+ *   `result` is a command result, and `replacement` is present only when the
+ *   surface was actually rewritten.
+ */
+export async function executeTrim(ctx, config, request) {
+	const { agent, signal, requestedRoute, explicitBudget, check = false, routedOnly = false } = request;
+	signal?.throwIfAborted?.();
+	const session = agent.session;
+	assertNoOpenCompaction(session);
+	const target =
+		explicitBudget === undefined ? await resolveTarget(ctx, agent, requestedRoute, signal, { routedOnly }) : undefined;
+	const budget = explicitBudget ?? budgetFor(target.contextWindow, config);
+	const label = target === undefined ? `an explicit ${budget}-token budget` : `${target.label} (window ${target.contextWindow})`;
+	const header = target === undefined ? undefined : targetHeader(session, target);
+	const measurement = ctx.tokenMeter.measure(session, header);
+	const nodes = measurement.nodes.map((node) => {
+		const type = session.eventAt(node.seq)?.type;
+		return {
+			seq: node.seq,
+			heuristicTokens: node.heuristicTokens,
+			// Harness 0.1.5+ carries the system prompt as surface node 0. It is never
+			// elidable, and no elided span may cross it: dropping it would strip the
+			// model's instructions, and letting it consume head protection would expose
+			// the user's original request instead.
+			...(type === 'system/message' ? { barrier: true } : {}),
+			// The newest human prompt is the anchor the planner must never elide.
+			...(type === 'user/message' ? { userMessage: true } : {})
+		};
+	});
+	if (nodes.length === 0) {
+		return { result: { kind: 'success', text: `Nothing to trim: ${session.id} has no model-visible messages yet.` } };
+	}
+	// The retained tail scales with the capacity being fitted: the target window
+	// when one is known, otherwise the explicit budget itself.
+	const retainTokens = retentionFor(target?.contextWindow ?? budget, config);
+	const envelopeTokens = Math.max(0, measurement.totalTokens - measurement.surfaceTokens);
+	const planFor = (markerTokens) =>
+		planTrim({
+			nodes,
+			envelopeTokens,
+			budget,
+			markerCost: markerTokens + config.markerSlackTokens,
+			retainTokens,
+			minTailTokens: config.minTailTokens,
+			protectHeadNodes: config.protectHeadNodes,
+			allowTailTrim: config.allowTailTrim,
+			isBalancedBefore: (seq) => toolPairingBalancedBefore(session, seq),
+			isBalancedAfter: (seq) => toolPairingBalancedAfter(session, seq)
+		});
+	let markerTokens = ctx.tokenMeter.estimateMessage(provisionalMarker());
+	let plan = planFor(markerTokens);
+	if (plan.kind !== 'span') return { result: describeNonSpan(plan, label), plan, label, before: measurement };
+	let marker = createMarkerMessage(plan, target?.label ?? `budget ${budget}`, budget);
+	const finalMarkerTokens = ctx.tokenMeter.estimateMessage(marker);
+	if (finalMarkerTokens > markerTokens) {
+		// The marker now carries real numbers; re-plan once so its own price is exact.
+		plan = planFor(finalMarkerTokens);
+		if (plan.kind !== 'span') return { result: describeNonSpan(plan, label), plan, label, before: measurement };
+		marker = createMarkerMessage(plan, target?.label ?? `budget ${budget}`, budget);
+		markerTokens = finalMarkerTokens;
+	}
+	if (check) {
+		return { result: { kind: 'success', text: preview(plan, label, markerTokens) }, plan, label, before: measurement };
+	}
+	const replacement = applyTrim(session, plan, marker, replaceKeys());
+	const after = ctx.tokenMeter.measure(session, header);
+	return {
+		result: { kind: 'success', text: report(plan, after, label, markerTokens), sourceEventSeq: replacement.seq },
+		plan,
+		label,
+		before: measurement,
+		after,
+		markerTokens,
+		replacement
+	};
+}
+
+/**
+ * Refuse to rewrite a surface while a compaction bracket is open.
+ * @param session - session whose log is inspected.
+ * @throws when an unmatched `compaction/start` is open in the current lifecycle.
+ */
+export function assertNoOpenCompaction(session) {
+	for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+		const event = session.eventAt(seq);
+		if (event === undefined) continue;
+		if (event.type === 'compaction/end') return;
+		// A seed boundary proves any earlier unmatched start belongs to a previous lifecycle.
+		if (event.type === 'session/end-seed') return;
+		if (event.type === 'compaction/start') {
+			throw new Error('a compaction is already in progress in this session; wait for it to finish, then retry');
+		}
+	}
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-command-context-trim",
-  "version": "0.1.1",
-  "description": "Model-free /trim command for DeepSeek Harness — drop the oldest, least valuable span of conversation context so a session can continue on a smaller-window model, without any model call.",
+  "version": "0.2.0",
+  "description": "Model-free /trim for DeepSeek Harness — drop the oldest, least valuable span of context on demand (the `/trim` command) or automatically when a request hits the model's context wall, without any model call.",
   "license": "MIT",
   "author": "snailium",
   "type": "module",
@@ -27,7 +27,8 @@
   "scripts": {
     "test": "node --test",
     "link:harness": "bash scripts/dev-link-harness.sh",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "e2e:mock": "node scripts/mock-overflow-server.mjs"
   },
   "dsh": {
     "bundle": {