@deepseek-ai/dsh-terminal-bash 0.1.5-rc.2 → 0.1.6-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/terminal/terminal-bash/README.md
-README.md: 5dc66b97f550581df18efba55771d30057ab9aa0
-README.zh.md: 85a132ee1cc940fa90a53b91ea399ae48d3fdc2b
+README.md: 466a42f46844d16b85d8754df0bd910361e2e401
+README.zh.md: 7ca41883f6c807102c75b25e531187a7ab148cbf

package/README.md

@@ -44,7 +44,7 @@ Mount the terminal service, a subprocess provider, the sandbox and policy servic
 - name: '@deepseek-ai/dsh-tool-terminal'
 ```
 
-`danger-full-access` starts the shell directly. Confined modes require a same-world `ctx.sandbox` provider: without one, the spawn fails before the shell starts.
+`danger-full-access` starts the shell directly. Confined modes require a same-world `ctx.sandbox` provider: without one, the spawn fails before the shell starts. Confinement preparation receives the opening signal; cancellation prevents terminal allocation even if the provider returns later.
 
 ### Configuration
 
@@ -85,6 +85,8 @@ This section explains the design behind the backend and points at the code that
 
 One backend serves both dialects: bash and pwsh share the same session machinery — sanitizer, bounded buffers, readiness polling, cancellation, and teardown — and differ only in argv, environment, and prompt installation. Bash receives a private marker through `PS1` plus `PROMPT_COMMAND`. Pwsh writes a prompt function, pins UTF-8 console encoding, and publishes startup only after the backend reports `stdin_read`; echoed setup text cannot publish the shell. A zero-scrollback `@xterm/headless` instance consumes raw PTY data and returns terminal-protocol replies through the same handle, while the line sanitizer remains the only output projection.
 
+Scrollback and unread send output retain independently owned strings with incremental byte and newline counts, so sanitized slices cannot retain discarded control sequences. Appending and evicting text takes amortized time proportional to incoming text; reads assemble the retained chunks. Retention preserves code-point boundaries and counts the empty line after a trailing newline. The [retention decision](../../../.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.md) owns the complexity and measurement rationale.
+
 ### Source map
 
 | File | Role |

package/README.zh.md

@@ -1,5 +1,5 @@
 ---
-description: "持久终端会话的随附 shell 后端：在共享沙箱策略下启动交互式 bash 或 pwsh，带就绪检测与有界逐行输出。"
+description: "持久终端会话的随产品交付的 shell 后端：在共享沙箱策略下启动交互式 bash 或 pwsh，带就绪检测与有界逐行输出。"
 kind: "package-reference"
 ---
 
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 何时选择
 
-当工作需要状态持续存在的交互式 shell 或 REPL 时选择此后端：逐步调试 gdb、在 Python 或 Node REPL 中探索，或中断前台命令后回到 shell。对于应当一次调用即开始并结束的有界命令，请选择单次 bash 工具。bash 方言面向 POSIX；pwsh 方言面向 `dsh-pwsh-local` 能解析出 pwsh 可执行文件的 Windows 主机。
+当工作需要状态持续存在的交互式 shell 或 REPL 时选择此后端：在调试器中单步执行、在 Python 或 Node REPL 中探索，或中断前台命令后回到 shell。对于应当一次调用即开始并结束的有界命令，请选择单次 bash 工具。bash 方言面向 POSIX；pwsh 方言面向 `dsh-pwsh-local` 能解析出 pwsh 可执行文件的 Windows 主机。
 
 ### 组合方式
 
@@ -44,7 +44,7 @@ kind: "package-reference"
 - name: '@deepseek-ai/dsh-tool-terminal'
 ```
 
-`danger-full-access` 直接启动 shell。受限模式要求同一执行世界中存在 `ctx.sandbox` 提供方：缺少时，spawn 会在 shell 启动前失败。
+`danger-full-access` 直接启动 shell。受限模式要求同一执行世界中存在 `ctx.sandbox` 提供方：缺少时，spawn 会在 shell 启动前失败。限制准备过程接收打开操作的取消信号；即使提供方稍后返回，取消仍会阻止终端分配。
 
 ### 配置
 
@@ -83,7 +83,9 @@ shell 在整个生命周期内运行在有效的沙箱边界之下。当所有
 
 ### 设计理念
 
-一个后端服务两种方言：bash 与 pwsh 共享同一套会话机制——清理器、有界缓冲区、就绪轮询、取消与关闭——只在 argv、环境与提示符安装方式上不同。bash 通过 `PS1` 加 `PROMPT_COMMAND` 接收私有标记。pwsh 会写入提示符函数、钉住 UTF-8 控制台编码，并只在后端报告 `stdin_read` 后发布启动；回显的设置文本不能发布 shell。一个不保留 scrollback 的 `@xterm/headless` 实例会消费原始 PTY 数据，并通过同一句柄返回终端协议响应；逐行 sanitizer 仍是唯一输出投影。
+一个后端服务两种方言：bash 与 pwsh 共享同一套会话机制——清理器、有界缓冲区、就绪轮询、取消与关闭——只在 argv、环境与提示符安装方式上不同。bash 通过 `PS1` 加 `PROMPT_COMMAND` 接收私有标记。pwsh 会写入提示符函数、固定 UTF-8 控制台编码，并只在后端报告 `stdin_read` 后发布启动；回显的设置文本不能发布 shell。一个不保留 scrollback 的 `@xterm/headless` 实例会消费原始 PTY 数据，并通过同一句柄返回终端协议响应；逐行 sanitizer 仍是唯一输出投影。
+
+Scrollback 和尚未读取的发送输出保留独立拥有的字符串，并增量维护字节数与换行符数，因此清理后的切片不会保留已丢弃的控制序列。追加与淘汰文本的摊还耗时与输入文本量成正比；读取时才拼接保留的分片。保留策略维持码点边界，并将末尾换行符之后的空行计入行数。[保留策略决策](../../../.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.zh.md)记录复杂度与测量依据。
 
 ### 源码地图
 
@@ -96,7 +98,7 @@ shell 在整个生命周期内运行在有效的沙箱边界之下。当所有
 
 ### 就绪模型
 
-三个有界档位结算一次发送：来自子进程提供方的精确 stdin 等待证据（仅 Linux）、带精确可打印尾部的受控私有提示符标记，以及输出静默（`inferred_idle`）；绝对超时始终限制等待。pwsh 启动的完整设置循环共用一条 deadline，因此 `inferred_idle` 后续发送不会重新计时。提供方写入前收集的证据会在写入边界丢弃，早于写入的 stdin 等待不算写入后就绪，未知的前台状态绝不是精确空闲的正向信号。
+三个有界档位结算一次发送：来自子进程提供方的精确 stdin 等待证据（仅 Linux）、带精确可打印尾部的受控私有提示符标记，以及输出静默（`inferred_idle`）；绝对超时始终限制等待。pwsh 启动的完整设置循环共用同一个截止时间，因此 `inferred_idle` 后续发送不会重新计时。提供方写入前收集的证据会在写入边界丢弃，早于写入的 stdin 等待不算写入后就绪，未知的前台状态绝不是精确空闲的正向信号。
 
 ### 发送取消与关闭
 
@@ -115,7 +117,7 @@ shell 在整个生命周期内运行在有效的沙箱边界之下。当所有
 
 当包级约定不够用时阅读以下页面。它们从共享终端模型进入服务、工具与执行世界基底。
 
-- [终端子系统参考](../../../docs/subsystems/terminal.zh.md)——此后端实现的服务器约定与生成的 `ctx.terminals` 接口面。
+- [终端子系统参考](../../../docs/subsystems/terminal.zh.md)——此后端实现的服务约定与生成的 `ctx.terminals` 接口面。
 - [terminal 服务](../terminal/README.zh.md)——后端注册、所有者限制与清理语义。
 - [tool-terminal 工具](../tool-terminal/README.zh.md)——操作会话的面向模型工具。
 - [子进程 seam](../../../docs/subsystems/subprocess.zh.md)——负责 PTY 分配与进程树清理的终端原语。
@@ -164,7 +166,7 @@ shell 在整个生命周期内运行在有效的沙箱边界之下。当所有
 
 - **仅逐行输出**——headless xterm 只为终端协议响应维护控制序列状态。返回输出仍按行规范化；不支持全屏备用缓冲区交互。
 - **没有精确档时，就绪是启发式的**——精确 stdin 等待检测取决于已挂载的子进程提供方；无法证明该状态的提供方（macOS、Windows）按提示符标记与静默／超时就绪结算。
-- **受限沙箱中的 pwsh 引导**——提示符函数与 UTF-8 钉通过 `[Console]::` 写入，Windows ACL 沙箱的只读模式可能拒绝。若因此无法获得 marker 就绪，启动会在 `timeoutMs` 到期时拒绝，而不会发布不完整的 shell。
+- **受限沙箱中的 pwsh 引导**——提示符函数与 UTF-8 编码固定操作通过 `[Console]::` 写入，Windows ACL 沙箱的只读模式可能拒绝。若因此无法获得标记就绪状态，启动会在 `timeoutMs` 到期时拒绝，而不会发布不完整的 shell。
 - **清理保证属于提供方**——进程树清理是 `SubprocessTerminalHandle` 的约定，而不是此后端的。
 - **会话不随进程退出存活**——harness 重启会销毁所有会话。
 
@@ -178,4 +180,4 @@ shell 在整个生命周期内运行在有效的沙箱边界之下。当所有
 
 </details>
 
-**运行时不变式：** 不发布伴生入口。readiness、terminal buffer 与 process-tree state 都是按 Session 的私有实现状态，backend 不发布独立 lifecycle stream 或 snapshot。
+**运行时不变式：** 不发布伴生入口。就绪状态、终端缓冲区与进程树状态都是各会话私有的实现状态，后端不发布独立的生命周期流或快照。

package/lib/index.js

@@ -1,8 +1,8 @@
-import { createRequire } from "node:module";
 import { TerminalBackendCleanupError, TerminalError } from "@deepseek-ai/dsh-terminal";
 import { ENCODING_PREAMBLE, resolvePwshPath } from "@deepseek-ai/dsh-pwsh-local";
 import z from "@deepseek-ai/schemastery";
 import { Buffer } from "node:buffer";
+import { createLazyRequire } from "@deepseek-ai/dsh-lazy-require";
 //#region lib/types/config.js
 /** Validated configuration for the local PTY backend. */
 /** Bash dialect default executable. */
@@ -232,7 +232,7 @@ function normalizeTerminalText(text) {
 //#endregion
 //#region lib/types/session.js
 /** Persistent PTY session with bounded output, readiness, and terminal-protocol replies. */
-const { Terminal: HeadlessTerminal } = createRequire(import.meta.url)("@xterm/headless");
+const requireHeadless = createLazyRequire("@xterm/headless", import.meta.url);
 function utf8Tail(text, maxBytes) {
 	if (Buffer.byteLength(text) <= maxBytes) return {
 		text,
@@ -252,33 +252,83 @@ function utf8Tail(text, maxBytes) {
 		truncated: true
 	};
 }
+const COALESCED_CHUNK_UNITS = 4096;
+/** Retention work is amortized over appended text; reads assemble the retained chunks. */
 var BoundedTextBuffer = class {
 	maxBytes;
 	maxLines;
-	value = "";
+	head;
+	tail;
+	bytes = 0;
+	newlines = 0;
+	lastCodeUnit = 0;
 	dropped = false;
 	constructor(maxBytes, maxLines) {
 		this.maxBytes = maxBytes;
 		this.maxLines = maxLines;
 	}
+	get truncated() {
+		return this.dropped;
+	}
+	get isEmpty() {
+		return this.head === void 0;
+	}
 	append(text) {
 		if (text.length === 0) return;
-		this.value += text;
-		if (this.maxLines !== void 0) {
-			const lines = this.value.split("\n");
-			if (lines.length > this.maxLines) {
-				this.value = lines.slice(lines.length - this.maxLines).join("\n");
-				this.dropped = true;
-			}
+		text = Buffer.from(text, "utf16le").toString("utf16le");
+		this.bytes += Buffer.byteLength(text);
+		const tail = this.tail;
+		if (tail !== void 0) {
+			const last = this.lastCodeUnit;
+			const first = text.charCodeAt(0);
+			if (last >= 55296 && last <= 56319 && first >= 56320 && first <= 57343) this.bytes -= 2;
+		}
+		for (let index = text.indexOf("\n"); index !== -1; index = text.indexOf("\n", index + 1)) this.newlines += 1;
+		this.lastCodeUnit = text.charCodeAt(text.length - 1);
+		if (tail !== void 0 && tail !== this.head && tail.text.length + text.length <= COALESCED_CHUNK_UNITS) tail.text += text;
+		else {
+			if (tail !== void 0 && tail.text.length <= COALESCED_CHUNK_UNITS) tail.text = Buffer.from(tail.text, "utf16le").toString("utf16le");
+			const chunk = {
+				text,
+				start: 0,
+				next: void 0
+			};
+			if (tail === void 0) this.head = chunk;
+			else tail.next = chunk;
+			this.tail = chunk;
+		}
+		while (this.head !== void 0 && (this.bytes > this.maxBytes || this.maxLines !== void 0 && this.newlines >= this.maxLines)) {
+			const head = this.head;
+			const first = head.text.charCodeAt(head.start);
+			const second = head.start + 1 < head.text.length ? head.text.charCodeAt(head.start + 1) : head.next?.text.charCodeAt(0);
+			const paired = first >= 55296 && first <= 56319 && second !== void 0 && second >= 56320 && second <= 57343;
+			this.bytes -= paired ? 4 : first < 128 ? 1 : first < 2048 ? 2 : 3;
+			if (first === 10) this.newlines -= 1;
+			this.advance(paired ? 2 : 1);
+			this.dropped = true;
+		}
+		const head = this.head;
+		if (head !== void 0 && head.start >= head.text.length / 2) {
+			head.text = Buffer.from(head.text.slice(head.start), "utf16le").toString("utf16le");
+			head.start = 0;
+		}
+	}
+	advance(units) {
+		while (units > 0 && this.head !== void 0) {
+			const head = this.head;
+			const count = Math.min(units, head.text.length - head.start);
+			head.start += count;
+			units -= count;
+			if (head.start === head.text.length) this.head = head.next;
 		}
-		const tail = utf8Tail(this.value, this.maxBytes);
-		this.value = tail.text;
-		this.dropped ||= tail.truncated;
+		if (this.head === void 0) this.tail = void 0;
 	}
 	consume() {
-		const delta = this.value;
-		const truncated = this.dropped;
-		this.value = "";
+		const { text: delta, truncated } = this.snapshot();
+		this.head = void 0;
+		this.tail = void 0;
+		this.bytes = 0;
+		this.newlines = 0;
 		this.dropped = false;
 		return {
 			delta,
@@ -286,8 +336,10 @@ var BoundedTextBuffer = class {
 		};
 	}
 	snapshot() {
+		const chunks = [];
+		for (let chunk = this.head; chunk !== void 0; chunk = chunk.next) chunks.push(chunk.text.slice(chunk.start));
 		return {
-			text: this.value,
+			text: chunks.join(""),
 			truncated: this.dropped
 		};
 	}
@@ -398,6 +450,7 @@ var LocalPtySession = class {
 		this.terminal = terminal;
 		this.config = config;
 		this.pid = terminal.pid;
+		const { Terminal: HeadlessTerminal } = requireHeadless();
 		this.emulator = new HeadlessTerminal({
 			cols: config.cols,
 			rows: config.rows,
@@ -654,7 +707,7 @@ var LocalPtySession = class {
 				return;
 			}
 			const elapsed = Date.now() - operation.startedAt;
-			const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0;
+			const startupHasOutput = !this.initializing || !this.scrollback.isEmpty;
 			const acceptsStdinWait = startupHasOutput && foreground !== void 0 && operation.acceptsStdinWait(foreground.processGroupId, foreground.inputWaiting);
 			if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
 				this.settleActive("stdin_read");
@@ -759,7 +812,7 @@ var LocalPtySession = class {
 	settleActive(waitReason, retainOwnership = false) {
 		const operation = this.active;
 		if (operation === void 0) return;
-		const scrollbackTruncated = this.scrollback.snapshot().truncated;
+		const scrollbackTruncated = this.scrollback.truncated;
 		if (retainOwnership) {
 			this.stopPolling();
 			this.activeAbort?.();
@@ -898,15 +951,15 @@ function childEnvironment(spec, dialect) {
 * input are unreliable under PSReadLine.
 */
 const PWSH_PROMPT_SETUP = "function prompt { [Console]::Write([char]27 + ']133;D;' + [int]$LASTEXITCODE + [char]7); 'dsh> ' }";
-function spawnArgv(ctx, config, policy) {
+async function spawnArgv(ctx, config, policy, signal) {
 	const argv = [config.shellPath, ...config.shellArgs];
 	if (policy.mode === "danger-full-access") return argv;
 	const sandbox = ctx.get("sandbox");
 	if (sandbox === void 0) throw new Error(`terminal-bash: sandbox mode "${policy.mode}" requires a ctx.sandbox provider in the execution world`);
-	return sandbox.confine(argv, {
+	return (await sandbox.confine(argv, {
 		...policy,
 		mode: policy.mode
-	}).argv;
+	}, signal)).argv;
 }
 async function startupSession(session, dialect, timeoutMs, signal) {
 	let startupOperation;
@@ -958,6 +1011,15 @@ async function startupSession(session, dialect, timeoutMs, signal) {
 		if (signal !== void 0 && onAbort !== void 0) signal.removeEventListener("abort", onAbort);
 	}
 }
+/** Reject a failed startup only after its unpublished resources reach quiescence. */
+async function rejectAfterStartupCleanup(error, cleanup) {
+	try {
+		await cleanup();
+	} catch (cleanupError) {
+		throw new TerminalBackendCleanupError(error, cleanupError);
+	}
+	throw error;
+}
 /** Local shell backend registered under the configured type. */
 var BashTerminalBackend = class {
 	ctx;
@@ -976,7 +1038,8 @@ var BashTerminalBackend = class {
 		spec.signal?.throwIfAborted();
 		ensureSandboxModeFence(this.ctx, spec.owner);
 		const policy = this.ctx.sandboxPolicy.resolve({ session: spec.owner.session });
-		const argv = spawnArgv(this.ctx, this.config, policy);
+		const argv = await spawnArgv(this.ctx, this.config, policy, spec.signal);
+		spec.signal?.throwIfAborted();
 		if (argv[0] === void 0) throw new Error("terminal-bash: sandbox returned empty argv");
 		const terminal = await this.spawnTerminal({
 			argv,
@@ -984,20 +1047,21 @@ var BashTerminalBackend = class {
 			env: childEnvironment(spec, this.config.shellDialect),
 			rows: this.config.rows,
 			cols: this.config.cols,
+			terminalType: "dumb",
 			graceMs: this.config.disposeGraceMs,
 			signal: spec.signal
 		});
-		const session = this.createSession(terminal, this.config);
+		let session;
+		try {
+			session = this.createSession(terminal, this.config);
+		} catch (error) {
+			return rejectAfterStartupCleanup(error, () => terminal.terminate());
+		}
 		try {
 			await startupSession(session, this.config.shellDialect, this.config.timeoutMs, spec.signal);
 			return session;
 		} catch (error) {
-			try {
-				await session.close("PTY startup failed");
-			} catch (closeError) {
-				throw new TerminalBackendCleanupError(error, closeError);
-			}
-			throw error;
+			return rejectAfterStartupCleanup(error, () => session.close("PTY startup failed"));
 		}
 	}
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-terminal-bash",
   "description": "Persistent shell PTY backend over the DeepSeek Harness subprocess terminal primitive",
-  "version": "0.1.5-rc.2",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,29 +27,30 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-terminal": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-terminal": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.6-alpha.2"
   },
   "dependencies": {
     "@xterm/headless": "^6.0.0",
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-pwsh-local": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-lazy-require": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-pwsh-local": "^0.1.6-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-terminal": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.5-rc.2",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-terminal": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }