@deepseek-ai/dsh-api-terminal-controller 0.1.6-alpha.1 → 0.1.7-alpha.1

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/api/terminal-controller/README.md
-README.md: 7bcd04ad2848b4f263aaff21d0bee5aea2333343
-README.zh.md: 3db761f32c0e7c99fa622dd7adb62f3ac301b766
+README.md: dd93237a94f0cc9bdbd6e6d51f9a2762898399a7
+README.zh.md: b3bda5f4040ab6f9bb9cd74a8fd32f48dbdb1362

package/README.md

@@ -25,9 +25,9 @@ Open the execution environment's default shell in a Session workspace from the W
 <a id="use-this-package"></a>
 ## Use this package
 
-The Web bundle mounts this package with the subprocess provider, sandbox policy and Typert Gateway. `remote.terminal` exposes `environment`, `shells`, `list`, `create`, `follow`, `write`, `resize`, `rename` and `close`; each operation is scoped by Session identity. Listing reads retained Host terminals directly, so viewing an offline Session neither activates an Agent nor produces a recovery error.
+The Web bundle mounts this package with the subprocess provider, sandbox policy and Typert Gateway. Sandbox policy supplies only the fallback working directory for Sessions without a cwd. `remote.terminal` exposes `environment`, `shells`, `list`, `create`, `retain`, `follow`, `write`, `resize`, `rename` and `close`; each operation is scoped by Session identity. Listing reads retained Host terminals directly, so viewing an offline Session neither activates an Agent nor produces a recovery error.
 
-Shell discovery lists the execution environment's declared default shell first. Only when the provider omits that default does resolution use `/bin/sh` on POSIX or `cmd.exe` on Windows. An optional `shell` profile overrides that choice with executable `path`, display `name` and `args` (default `[]`). The selector also probes `shellCandidates` through the execution provider and omits only confirmed lookup misses. Creation accepts a discovered `shellPath` and verifies it again; resolution or transport failure is reported without launching a different shell. Environment lookup returns the working directory and limits without resolving a shell, so an unavailable default does not prevent reattaching to an existing process. Automatic POSIX profiles start interactively, and PowerShell uses `-NoLogo`, so completion and startup configuration remain shell-owned. The Session workspace supplies the initial directory; its sandbox policy also applies to the terminal.
+Shell discovery lists the execution environment's declared default shell first. Only when the provider omits that default does resolution use `/bin/sh` on POSIX or `cmd.exe` on Windows. An optional `shell` profile overrides that choice with executable `path`, display `name` and `args` (default `[]`). The selector also probes `shellCandidates` through the execution provider and omits only confirmed lookup misses. Creation accepts a discovered `shellPath` and verifies it again; resolution or transport failure is reported without launching a different shell. Environment lookup returns the working directory and limits without resolving a shell, so an unavailable default does not prevent reattaching to an existing process. Automatic POSIX profiles start interactively, and PowerShell uses `-NoLogo`, so completion and startup configuration remain shell-owned. The Session workspace supplies the initial directory. User terminals run with the execution environment’s system-user permissions, independently of the Agent’s sandbox mode and approval policy. Operating-system and container restrictions still apply; DSH does not elevate the user. The subprocess provider retains its credential-environment scrubbing.
 
 | Configuration | Default | Meaning |
 |---|---|---|
@@ -39,6 +39,11 @@ Shell discovery lists the execution environment's declared default shell first.
 | `maxBufferedBytes` | `2097152` | Output queued for one follower |
 | `maxInputBytes` | `65536` | Maximum input request bytes |
 | `disposeGraceMs` | `1000` | Provider termination grace in milliseconds |
+| `unattendedTimeoutMs` | `7200000` | Continuous confirmed idle time without window holds before cleanup; `0` disables automatic reclamation |
+| `activityPollIntervalMs` | `30000` | Interval between unattended activity observations |
+| `cleanupRetryMs` | `60000` | Delay before retrying failed cleanup |
+
+An open tab in any connected window retains its terminal, including hidden tabs and inactive Sessions. After the last hold disappears, only positively confirmed idle time counts toward reclamation. Running, stopped, input-waiting and background work remains protected; unknown activity clears the idle deadline. Completion starts a fresh full grace period. The Host uses a monotonic clock, rechecks current ownership and activity before cleanup, and resets evidence after an observation gap exceeding twice the polling interval. The timing fields use milliseconds and safe integers; polling and retry intervals must be positive.
 
 <a id="understand-the-implementation"></a>
 ## Understand the implementation
@@ -48,13 +53,15 @@ Shell discovery lists the execution environment's declared default shell first.
 
 The Host uses `ctx.subprocess.spawnTerminal` with `TERM=xterm-256color`; it never launches a desktop terminal application. Streaming UTF-8 decoding preserves split characters and leading BOMs, and replaces incomplete trailing bytes at EOF. Unary control uses the Gateway, and `follow` uses its multiplexed Remote stream transport. Headless xterm and its serializer produce each opening screen after all preceding output writes, then monotone output sequences identify subsequent frames. Slow followers fail explicitly; a new attachment restores the current screen.
 
-The latest attachment owns input and resize. Detachment releases input control without killing the process. Explicit close awaits process cleanup and final output; cleanup failure retains the resource for retry. The Session remembers closed identities and rejects their delayed or repeated creation, including creation already in progress when close arrives. A new terminal uses a new identity. Pending allocations remain owned even if cancellation and cleanup both fail. Session owner disposal and controller disposal also terminate owned processes. An open or pending terminal prevents changing that Session's sandbox mode. Input or resize refused after control transfer or process exit leaves the output attachment intact and disables input; rejected input is not replayed.
+The latest attachment owns input and resize. Detachment releases input control without killing the process. Explicit close awaits process cleanup and final output; cleanup failure retains the resource for retry. The Session remembers closed identities and rejects their delayed or repeated creation, including creation already in progress when close arrives. A new terminal uses a new identity. Pending allocations remain owned even if cancellation and cleanup both fail. Session owner disposal and controller disposal also terminate owned processes. Changing the Session’s sandbox mode leaves user terminals running with the same permissions. Input or resize refused after control transfer or process exit leaves the output attachment intact and disables input; rejected input is not replayed.
+
+The Client saves each Session/content-to-terminal association before allocation under its own `dsh.terminal.binding.v1.*` localStorage key. The content identity is globally unique; layout-local tab ids only identify live view occurrences. Independent record writes and deletes preserve other windows' bindings. Restored views reuse that identity; the sidebar terminal provider restores its views before querying unrepresented Host terminals. A new view may create a process, while a recovered view reports a missing target without creating a replacement. Explicit close removes the association after saving its cleanup request. The Host supplies current process metadata and screen contents; neither is saved in the browser. The Client model acknowledges screen writes after the browser emulator processes them, serializes input and ignores stale attachment responses. Client-owned errors carry locale keys. Plugin disposal awaits active and previously detached output streams without closing Host processes.
 
-Client views keep the association between sidebar tabs and terminal identities in memory. Recovery queries the Host for retained terminals; a new view may create a process, while a recovered view reports a missing target without creating a replacement. The Client model acknowledges screen writes after the browser emulator processes them, serializes input and ignores stale attachment responses. Client-owned errors carry locale keys. Plugin disposal awaits active and previously detached output streams without closing Host processes.
+The separate `retain(sessionId, id, signal)` Remote stream acknowledges a window hold without Agent activation, screen output, input transfer or process creation. The terminal provider supplies the sidebar's complete open-tab inventory, and the Client intersects it with its own saved identities. Duplicate occurrences share one hold per window; stale associations alone retain nothing. Restored output attachments wait for an acknowledged current hold. Transport cancellation releases exactly that physical generation; plugin disposal joins all hold streams. Failed cleanup retains ownership and retries without reopening admission or restarting the idle grace.
 
 New views start automatically, using an explicit guide selection or the remembered available shell. The last selected shell path is stored under `dsh.terminal.shell` in origin-scoped localStorage. Default launches verify the saved path through Host discovery and fall back to the current default when it is absent. The guide records a selection before opening its tab; each new tab retains its own chosen path and allocation identity. Storage failures do not prevent startup. Restoring existing terminals neither reads this preference nor discovers shells.
 
-Closing saves an unfinished cleanup request before releasing the tab, then awaits Host cleanup in the background. A failure exposes a retry notification. Each request has its own terminal-ID localStorage key and is removed after successful cleanup or a definitive `session/not-found` response; startup retries saved requests. Transport failures retain the request. This stores cleanup intent, not sidebar layout, open-tab mappings, selected tabs or process PIDs. If browser storage is unavailable, cleanup remains usable in memory but cannot be recovered after reload.
+Closing saves an unfinished cleanup request before releasing the tab, then awaits Host cleanup in the background. A failure exposes a retry notification. Each request has its own terminal-ID localStorage key and is removed after successful cleanup or a definitive `session/not-found` response; startup retries saved requests. Transport failures retain the request. Cleanup requests persist independently of tab associations and sidebar layout. If browser storage is unavailable, cleanup remains usable in memory but cannot be recovered after reload.
 
 </details>
 
@@ -63,6 +70,7 @@ Closing saves an unfinished cleanup request before releasing the tab, then await
 
 - [Subprocess](../../subprocess/subprocess/README.md)
 - [Right Sidebar](../../client/ui-sidebar-right/README.md)
+- [User-terminal permissions](../../../.agents/notes/implemented/architecture/2026-09-16-user-terminal-permissions.md)
 - [Web terminal decision](../../../.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.md)
 
 <a id="model-experience"></a>
@@ -80,6 +88,7 @@ None; terminal output travels only between the browser and Host.
 
 - Processes and screens survive browser reloads, but not Host or Session owner disposal. There is no durable terminal restoration or automatic shell respawn. Exited terminals count toward `maxTerminals`; close unused tabs to release their screens and quota.
 - The subprocess provider determines native PTY availability and process-tree cleanup guarantees. Finding an executable does not prove PTY allocation will succeed.
+- Automatic reclamation depends on the provider's [supported shell activity observation](../../subprocess/subprocess-local/README.md#running-terminal-sessions). Unsupported shells, custom launch arguments and uncertain process observations may retain resources until explicit close or owner disposal. No maximum runtime kills busy commands.
 - Screen recovery retains bounded history, not a complete transcript. Only one attachment at a time can write or resize.
 
 <a id="dev-note"></a>

package/README.zh.md

@@ -25,9 +25,9 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用此包
 
-Web bundle 将此包与 subprocess provider、sandbox policy 和 Typert Gateway 一起挂载。`remote.terminal` 提供 `environment`、`shells`、`list`、`create`、`follow`、`write`、`resize`、`rename` 和 `close`；每个操作均按 Session 标识限定范围。列表直接读取 Host 保留的终端，因此查看离线 Session 不会激活 Agent，也不会产生恢复错误。
+Web bundle 将此包与 subprocess provider、sandbox policy 和 Typert Gateway 一起挂载。Sandbox policy 仅为没有 cwd 的 Session 提供默认工作目录。`remote.terminal` 提供 `environment`、`shells`、`list`、`create`、`retain`、`follow`、`write`、`resize`、`rename` 和 `close`；每个操作均按 Session 标识限定范围。列表直接读取 Host 保留的终端，因此查看离线 Session 不会激活 Agent，也不会产生恢复错误。
 
-Shell 探测结果首先列出执行环境声明的默认 shell。仅当 provider 未声明默认值时，才在 POSIX 使用 `/bin/sh`，在 Windows 使用 `cmd.exe`。可选的 `shell` profile 通过可执行路径 `path`、显示名称 `name` 和参数 `args`（默认 `[]`）覆盖这一选择。选择器还会通过执行 provider 探测 `shellCandidates`，仅省略确定未找到的候选。创建请求接受探测返回的 `shellPath` 并再次验证；解析或传输失败会直接报告，不启动其他 shell。环境查询只返回工作目录和限制，不解析 shell，因此默认 shell 不可用时仍可重新连接已有进程。POSIX 自动 profile 以交互模式启动，PowerShell 使用 `-NoLogo`，补全和启动配置仍由 shell 提供。初始目录来自 Session 工作区，终端遵循同一 sandbox policy。
+Shell 探测结果首先列出执行环境声明的默认 shell。仅当 provider 未声明默认值时，才在 POSIX 使用 `/bin/sh`，在 Windows 使用 `cmd.exe`。可选的 `shell` profile 通过可执行路径 `path`、显示名称 `name` 和参数 `args`（默认 `[]`）覆盖这一选择。选择器还会通过执行 provider 探测 `shellCandidates`，仅省略确定未找到的候选。创建请求接受探测返回的 `shellPath` 并再次验证；解析或传输失败会直接报告，不启动其他 shell。环境查询只返回工作目录和限制，不解析 shell，因此默认 shell 不可用时仍可重新连接已有进程。POSIX 自动 profile 以交互模式启动，PowerShell 使用 `-NoLogo`，补全和启动配置仍由 shell 提供。初始目录来自 Session 工作区。用户终端使用执行环境中系统用户的权限，独立于 Agent 的沙箱模式和审批策略。操作系统和容器的限制仍然生效；DSH 不提升用户权限。Subprocess provider 继续清除环境中的凭据变量。
 
 | 配置 | 默认值 | 含义 |
 |---|---|---|
@@ -39,6 +39,11 @@ Shell 探测结果首先列出执行环境声明的默认 shell。仅当 provide
 | `maxBufferedBytes` | `2097152` | 单个订阅者的输出排队上限 |
 | `maxInputBytes` | `65536` | 单次输入请求的字节上限 |
 | `disposeGraceMs` | `1000` | provider 终止宽限期，单位毫秒 |
+| `unattendedTimeoutMs` | `7200000` | 无窗口持有且持续确认空闲后开始清理的时长；`0` 禁用自动回收 |
+| `activityPollIntervalMs` | `30000` | 无窗口持有时的活动观察间隔 |
+| `cleanupRetryMs` | `60000` | 清理失败后的重试间隔 |
+
+任何已连接窗口中的打开标签页都会持有其终端，包括隐藏标签和非当前 Session。最后一个持有关系消失后，只有明确确认空闲的时间才计入回收期限。运行中、停止、等待输入和后台执行的任务都会受到保护；活动状态未知时清除空闲截止时间。任务完成后重新给予完整宽限期。Host 使用单调时钟，在清理前重新检查持有关系和当前活动；观察间隔超过轮询周期的两倍时丢弃旧证据。时间字段使用毫秒和安全整数，轮询及重试间隔必须为正数。
 
 <a id="understand-the-implementation"></a>
 ## 了解实现
@@ -48,13 +53,15 @@ Shell 探测结果首先列出执行环境声明的默认 shell。仅当 provide
 
 Host 通过 `ctx.subprocess.spawnTerminal` 创建 `TERM=xterm-256color` 的终端，不启动桌面终端应用。流式 UTF-8 解码保留跨块字符和开头的 BOM，并在 EOF 将不完整的尾部字节替换为替代字符。控制请求走 Gateway，`follow` 使用其复用的 Remote stream。Headless xterm 和序列化 addon 在此前输出写入后生成初始屏幕，后续增量携带单调序号。过慢的订阅者明确失败；重新连接恢复当前屏幕。
 
-最新连接持有输入和尺寸控制权。断开连接只释放输入权，不结束进程。显式关闭等待进程清理和最后输出；清理失败时保留资源以便重试。Session 记住已关闭的标识并拒绝迟到或重复的创建请求，包括关闭到达时仍在进行的创建。新终端使用新标识。取消创建且清理失败时，已分配的进程仍有所有者。Session owner 和 controller 卸载也会终止所拥有的进程。存在终端或创建请求时不能改变该 Session 的 sandbox mode。 控制权转移或进程退出后被拒绝的输入和尺寸请求保留输出连接并禁用输入，不重发被拒绝的输入。
+最新连接持有输入和尺寸控制权。断开连接只释放输入权，不结束进程。显式关闭等待进程清理和最后输出；清理失败时保留资源以便重试。Session 记住已关闭的标识并拒绝迟到或重复的创建请求，包括关闭到达时仍在进行的创建。新终端使用新标识。取消创建且清理失败时，已分配的进程仍有所有者。Session owner 和 controller 卸载也会终止所拥有的进程。改变 Session 的沙箱模式时，用户终端继续以原有权限运行。控制权转移或进程退出后被拒绝的输入和尺寸请求保留输出连接并禁用输入，不重发被拒绝的输入。
+
+Client 在分配前将每条 Session/内容与终端身份的关联保存到独立的 localStorage key `dsh.terminal.binding.v1.*`。内容身份全局唯一；布局内的 tab id 只标识活动视图 occurrence。逐条记录的写入和删除会保留其他窗口的关联。恢复视图复用该身份；侧栏 terminal provider 先恢复自己的视图，再查询尚无视图的 Host 终端。新视图可以创建进程，恢复视图在目标缺失时显示错误，不创建替代进程。显式关闭先保存清理请求，再删除关联。当前进程元数据和屏幕内容由 Host 提供，不保存在浏览器中。Client 模型在浏览器完成屏幕解析后确认帧，按序发送输入，并忽略旧连接迟到的响应。Client 自产错误携带本地化键。插件卸载等待活跃及先前断开的输出流结束，不关闭 Host 进程。
 
-Client 视图只在内存中关联侧栏标签页与终端标识。恢复操作查询 Host 保留的终端；新视图可以创建进程，恢复视图在目标缺失时显示错误，不创建替代进程。Client 模型在浏览器完成屏幕解析后确认帧，按序发送输入，并忽略旧连接迟到的响应。 Client 自产错误携带本地化键。插件卸载等待活跃及先前断开的输出流结束，不关闭 Host 进程。
+独立的 `retain(sessionId, id, signal)` Remote 流确认窗口持有关系，不激活 Agent、发送屏幕输出、转移输入权或创建进程。终端 provider 提供侧栏的完整打开标签清单，Client 将其与自己保存的身份取交集。同一窗口中的重复 occurrence 共用一个持有流；孤立的旧关联不会保活任何终端。恢复输出连接前必须等待当前持有关系确认。传输取消只释放对应的物理流代次；插件卸载等待全部持有流结束。清理失败时保留所有权并重试，不重新接受连接，也不重新计算空闲宽限期。
 
 新视图自动启动，使用开始页明确选中的 shell，或上次选择且仍可用的 shell。上次选择的路径保存在当前站点 localStorage 的 `dsh.terminal.shell` 中。默认启动通过 Host 探测验证保存的路径，不可用时回到当前默认项。开始页在打开标签页前记录选择，每个新标签页保留自己的 shell 路径和分配身份。存储失败不影响启动。恢复已有终端既不读取这一偏好，也不探测 shell。
 
-关闭时先保存未完成的清理请求并释放标签页，再在后台等待 Host 清理。失败时提供重试通知。每个请求使用独立的终端 ID localStorage key，清理成功或收到明确的 `session/not-found` 响应后删除；启动时重试已保存的请求。传输失败时保留请求。保存的是清理意图，不是侧栏布局、打开标签页映射、选中标签页或进程 PID。浏览器存储不可用时，内存中的清理仍可工作，但刷新后无法恢复该请求。
+关闭时先保存未完成的清理请求并释放标签页，再在后台等待 Host 清理。失败时提供重试通知。每个请求使用独立的终端 ID localStorage key，清理成功或收到明确的 `session/not-found` 响应后删除；启动时重试已保存的请求。传输失败时保留请求。清理请求独立于标签关联和侧栏布局持久化。浏览器存储不可用时，内存中的清理仍可工作，但刷新后无法恢复该请求。
 
 </details>
 
@@ -63,6 +70,7 @@ Client 视图只在内存中关联侧栏标签页与终端标识。恢复操作
 
 - [Subprocess](../../subprocess/subprocess/README.zh.md)
 - [Right Sidebar](../../client/ui-sidebar-right/README.zh.md)
+- [用户终端权限](../../../.agents/notes/implemented/architecture/2026-09-16-user-terminal-permissions.zh.md)
 - [Web terminal decision](../../../.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.zh.md)
 
 <a id="model-experience"></a>
@@ -80,6 +88,7 @@ Client 视图只在内存中关联侧栏标签页与终端标识。恢复操作
 
 - 浏览器刷新保留进程和屏幕；Host 或 Session owner 卸载不保留。不提供持久终端恢复或自动重启 shell。 已退出的终端仍计入 `maxTerminals`；关闭不用的标签页可释放其屏幕和名额。
 - 原生 PTY 可用性和进程树清理保证由 subprocess provider 决定。找到可执行文件并不保证 PTY 分配成功。
+- 自动回收依赖 provider [支持的 shell 活动观察](../../subprocess/subprocess-local/README.zh.md#running-terminal-sessions)。不支持的 shell、自定义启动参数和不确定的进程观察可能让资源一直保留到明确关闭或 owner 卸载。运行中的命令没有强制最长执行时间。
 - 屏幕恢复只保留有界历史，不保留完整记录。同一时刻只有一个连接可输入或调整尺寸。
 
 <a id="dev-note"></a>

package/lib/client.js

@@ -97,6 +97,7 @@ window.__ModuleLoader__.load({
 			id;
 			createWhenMissing;
 			shellPath;
+			retain;
 			/** Observable controls, process metadata and the next screen update awaiting acknowledgement. */
 			state = (0, _deepseek_ai_dsh_client_store.createSnapshotStore)({
 				phase: "idle",
@@ -121,14 +122,16 @@ window.__ModuleLoader__.load({
 			* @param id - Host terminal identity, reused when recovering an item from its Session list.
 			* @param createWhenMissing - allow allocation only for a new tab, never a listed terminal.
 			* @param shellPath - explicit shell chosen at the guide; omission uses the remembered available shell.
+			* @param retain - window hold acknowledgement required before output attachment.
 			*/
-			constructor(sessionId, remote, gateway, id, createWhenMissing = true, shellPath) {
+			constructor(sessionId, remote, gateway, id, createWhenMissing = true, shellPath, retain) {
 				this.sessionId = sessionId;
 				this.remote = remote;
 				this.gateway = gateway;
 				this.id = id;
 				this.createWhenMissing = createWhenMissing;
 				this.shellPath = shellPath;
+				this.retain = retain;
 			}
 			/**
 			* Attach the DOM lifetime, starting the chosen shell or reconnecting the saved process.
@@ -210,7 +213,15 @@ window.__ModuleLoader__.load({
 					info,
 					title: info.title
 				});
-				if (this.mounted && this.closing === void 0) this.connect();
+				if (this.retain === void 0) {
+					if (this.mounted && this.closing === void 0) this.connect();
+					return;
+				}
+				this.retain(this.lifetime.signal).then(() => {
+					if (this.mounted && this.closing === void 0) this.connect();
+				}).catch((error) => {
+					if (!this.stopped()) this.fail(error);
+				});
 			}
 			/** Reattach with a fresh screen and regain input control. */
 			connect() {
@@ -219,11 +230,13 @@ window.__ModuleLoader__.load({
 				this.detach();
 				const stream = this.gateway.$stream({
 					name: "Browser terminal output",
-					open: (signal) => {
+					open: async function* (signal) {
+						await this.retain?.(signal);
+						signal.throwIfAborted();
 						const attachmentId = randomUUID();
 						this.attachmentId = attachmentId;
-						return this.remote.follow(this.sessionId, info.id, attachmentId, signal);
-					},
+						yield* this.remote.follow(this.sessionId, info.id, attachmentId, signal);
+					}.bind(this),
 					ended: () => new TerminalViewError("attachmentEnded"),
 					carrierFailed: () => {
 						if (this.stream === stream) this.patch({
@@ -437,7 +450,7 @@ window.__ModuleLoader__.load({
 					});
 					return;
 				}
-				const issue = failure?.code === "terminal/view" ? failure.details.issue : failure?.code === "terminal/limit-reached" ? "terminalLimit" : void 0;
+				const issue = failure?.code === "terminal/view" ? failure.details.issue : failure?.code === "terminal/limit-reached" ? "terminalLimit" : failure?.code === "terminal/unavailable" ? "missingTerminal" : void 0;
 				this.patch({
 					phase: error instanceof _deepseek_ai_dsh_api_gateway_client.RemoteStreamCarrierError ? "disconnected" : "failed",
 					writable: false,
@@ -452,7 +465,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region lib/types/client/close-requests.js
-		const PREFIX = "dsh.terminal.close.v1.";
+		const PREFIX$1 = "dsh.terminal.close.v1.";
 		/** Each request has its own storage key, so other browser windows cannot overwrite its cleanup. */
 		var TerminalCloseRequests = class {
 			requests = /* @__PURE__ */ new Map();
@@ -461,7 +474,7 @@ window.__ModuleLoader__.load({
 					if (typeof localStorage === "undefined") return;
 					for (let index = 0; index < localStorage.length; index++) {
 						const key = localStorage.key(index);
-						if (key?.startsWith(PREFIX)) this.load(key);
+						if (key?.startsWith(PREFIX$1)) this.load(key);
 					}
 				} catch (error) {
 					console.error("Terminal cleanup recovery failed:", error);
@@ -481,7 +494,7 @@ window.__ModuleLoader__.load({
 			save(request) {
 				this.requests.set(request.id, request);
 				try {
-					if (typeof localStorage !== "undefined") localStorage.setItem(PREFIX + request.id, JSON.stringify(request));
+					if (typeof localStorage !== "undefined") localStorage.setItem(PREFIX$1 + request.id, JSON.stringify(request));
 				} catch (error) {
 					console.error("Terminal cleanup persistence failed:", error);
 				}
@@ -493,7 +506,7 @@ window.__ModuleLoader__.load({
 			remove(id) {
 				this.requests.delete(id);
 				try {
-					if (typeof localStorage !== "undefined") localStorage.removeItem(PREFIX + id);
+					if (typeof localStorage !== "undefined") localStorage.removeItem(PREFIX$1 + id);
 				} catch (error) {
 					console.error("Terminal cleanup persistence failed:", error);
 				}
@@ -503,7 +516,7 @@ window.__ModuleLoader__.load({
 					const raw = localStorage.getItem(key);
 					if (raw === null) return;
 					const parsed = JSON.parse(raw);
-					if (!isRequest(parsed) || key !== PREFIX + parsed.id) throw new Error("Invalid terminal cleanup request");
+					if (!isRequest(parsed) || key !== PREFIX$1 + parsed.id) throw new Error("Invalid terminal cleanup request");
 					this.requests.set(parsed.id, parsed);
 				} catch (error) {
 					console.error("Terminal cleanup recovery failed:", error);
@@ -516,6 +529,148 @@ window.__ModuleLoader__.load({
 			return typeof request.sessionId === "string" && request.sessionId.length > 0 && typeof request.id === "string" && /^[\w-]{1,128}$/u.test(request.id) && typeof request.title === "string";
 		}
 		//#endregion
+		//#region lib/types/client/retention.js
+		/** A stream acknowledgement gates output attachment for each physical connection. */
+		var TerminalWindowHold = class {
+			stream;
+			waiters = /* @__PURE__ */ new Set();
+			generation;
+			failure;
+			/**
+			* @param gateway - reconnecting stream owner.
+			* @param remote - typed terminal namespace.
+			* @param sessionId - saved layout's Session, without Agent activation.
+			* @param id - existing Host terminal.
+			*/
+			constructor(gateway, remote, sessionId, id) {
+				this.stream = gateway.$stream({
+					name: "Browser terminal window hold",
+					open: (signal) => remote.retain(sessionId, id, signal),
+					ended: () => new RemoteError("terminal/unavailable", "Terminal hold ended", {})
+				});
+				this.consume();
+			}
+			/** Whether a terminal-domain failure ended this hold, allowing an explicit retry. */
+			get failed() {
+				return this.failure !== void 0;
+			}
+			/**
+			* Wait for an acknowledged current physical hold before following its screen.
+			* @param signal - output request or view lifetime.
+			* @returns after acknowledgement, or rejects on cancellation/unavailability.
+			*/
+			async ready(signal) {
+				signal.throwIfAborted();
+				if (this.failure !== void 0) throw this.failure;
+				if (this.generation !== void 0 && !this.generation.aborted) return;
+				const waiting = Promise.withResolvers();
+				const abort = () => {
+					waiting.reject(signal.reason);
+				};
+				this.waiters.add(waiting);
+				signal.addEventListener("abort", abort, { once: true });
+				try {
+					await waiting.promise;
+				} finally {
+					this.waiters.delete(waiting);
+					signal.removeEventListener("abort", abort);
+				}
+			}
+			/**
+			* Release this window's stream and all acknowledgement waiters.
+			* @returns after the stream consumer closes.
+			*/
+			dispose() {
+				this.reject(/* @__PURE__ */ new Error("Terminal window hold released"));
+				return this.stream.dispose();
+			}
+			async consume() {
+				try {
+					for await (const item of this.stream) {
+						item.accept();
+						this.generation = item.signal;
+						for (const waiter of this.waiters) waiter.resolve();
+						this.waiters.clear();
+					}
+				} catch (error) {
+					this.reject(error);
+				}
+			}
+			reject(error) {
+				this.failure = error instanceof Error ? error : new Error("Terminal window hold failed", { cause: error });
+				this.generation = void 0;
+				for (const waiter of this.waiters) waiter.reject(error);
+				this.waiters.clear();
+			}
+		};
+		//#endregion
+		//#region lib/types/client/bindings.js
+		const PREFIX = "dsh.terminal.binding.v1.";
+		/** Saved recovery targets keyed by Session and globally unique terminal content identity. */
+		var TerminalBindings = class {
+			memory = /* @__PURE__ */ new Map();
+			/**
+			* Read a saved target, retaining this window's value when storage is unavailable.
+			* @param sessionId - owning Session.
+			* @param contentId - terminal content identity, shared only by deliberate copies.
+			* @returns the existing Host identity, if one has been saved.
+			*/
+			get(sessionId, contentId) {
+				const key = this.key(sessionId, contentId);
+				const known = this.memory.get(key);
+				if (known !== void 0) return known;
+				if (typeof localStorage === "undefined") return void 0;
+				try {
+					const raw = localStorage.getItem(key);
+					if (raw === null) return void 0;
+					const value = JSON.parse(raw);
+					if (typeof value !== "string" || !/^[\w-]{1,128}$/u.test(value)) return void 0;
+					this.memory.set(key, value);
+					return value;
+				} catch (_storageUnavailable) {
+					return;
+				}
+			}
+			/**
+			* Save an identity before its Host allocation begins.
+			* @param sessionId - owning Session.
+			* @param contentId - globally unique terminal content identity.
+			* @param id - existing or newly allocated Host identity.
+			*/
+			set(sessionId, contentId, id) {
+				const key = this.key(sessionId, contentId);
+				this.memory.set(key, id);
+				if (typeof localStorage === "undefined") return;
+				try {
+					localStorage.setItem(key, JSON.stringify(id));
+				} catch (error) {
+					console.error("Terminal binding persistence failed:", error);
+				}
+			}
+			/**
+			* Remove this content's target after its close intent has been saved.
+			* @param sessionId - owning Session.
+			* @param contentId - closing terminal content identity.
+			*/
+			delete(sessionId, contentId) {
+				const key = this.key(sessionId, contentId);
+				this.memory.delete(key);
+				if (typeof localStorage === "undefined") return;
+				try {
+					localStorage.removeItem(key);
+				} catch (error) {
+					console.error("Terminal binding cleanup failed:", error);
+				}
+			}
+			/** Release cached values when the Client service is disposed. */
+			clear() {
+				this.memory.clear();
+			}
+			key(sessionId, contentId) {
+				return PREFIX + JSON.stringify([sessionId, contentId]);
+			}
+		};
+		//#endregion
 		//#region lib/types/client/index.js
 		/** Client terminal model service; views are keyed independently from Host terminal identities. */
 		/** Session and occurrence lookup, independent tab and terminal identities and background cleanup. */
@@ -528,6 +683,10 @@ window.__ModuleLoader__.load({
 			closed = new Set(this.requests.pending().map((request) => request.id));
 			disposed = false;
 			views = /* @__PURE__ */ new Map();
+			bindings = new TerminalBindings();
+			holds = /* @__PURE__ */ new Map();
+			releasing = /* @__PURE__ */ new Set();
+			openTabs = [];
 			/**
 			* @param ctx - Client root Context with Gateway and terminal Remote namespace.
 			* @param remote - generated terminal namespace.
@@ -539,7 +698,15 @@ window.__ModuleLoader__.load({
 					this.disposed = true;
 					const detaching = [...this.views.values()].flatMap((views) => [...views.values()].map((view) => view.dispose()));
 					this.views.clear();
-					await Promise.all([...detaching, ...this.closing.values()]);
+					this.bindings.clear();
+					const holds = [...this.holds.values()].flatMap((holds) => [...holds.values()].map((hold) => hold.dispose()));
+					this.holds.clear();
+					await Promise.all([
+						...detaching,
+						...holds,
+						...this.releasing,
+						...this.closing.values()
+					]);
 				}, "terminal-controller.client.views");
 				for (const request of this.requests.pending()) this.cleanup(request);
 			}
@@ -547,11 +714,12 @@ window.__ModuleLoader__.load({
 			* Return the stable model for one sidebar occurrence.
 			* @param sessionId - owning Session.
 			* @param key - sidebar occurrence key.
-			* @param terminalId - existing Host identity when restoring a listed terminal.
+			* @param contentId - globally unique content identity; layout-local tab ids are not persistence keys.
+			* @param terminalId - existing Host identity when restoring a listed terminal; otherwise reuse the saved content identity.
 			* @param shellPath - explicit shell for a new terminal; restored terminals retain their own shell.
 			* @returns its observable state and terminal commands.
 			*/
-			view(sessionId, key, terminalId, shellPath) {
+			view(sessionId, key, contentId, terminalId, shellPath) {
 				let views = this.views.get(sessionId);
 				if (views === void 0) {
 					views = /* @__PURE__ */ new Map();
@@ -559,9 +727,12 @@ window.__ModuleLoader__.load({
 				}
 				let view = views.get(key);
 				if (view === void 0) {
-					const id = terminalId ?? randomUUID();
-					view = new TerminalView(sessionId, this.remote, this.ctx.remote, id, terminalId === void 0, shellPath);
+					const saved = terminalId ?? this.bindings.get(sessionId, contentId);
+					const id = saved ?? randomUUID();
+					this.bindings.set(sessionId, contentId, id);
+					view = new TerminalView(sessionId, this.remote, this.ctx.remote, id, saved === void 0, shellPath, (signal) => this.hold(sessionId, id).ready(signal));
 					views.set(key, view);
+					this.reconcileHolds();
 					view.refresh();
 				}
 				return view;
@@ -592,12 +763,13 @@ window.__ModuleLoader__.load({
 			* Save a close intent and release the tab immediately; cleanup outlives DOM unmount and reload.
 			* @param sessionId - owning Session.
 			* @param key - sidebar occurrence key, including an inactive restored tab.
+			* @param contentId - globally unique content identity whose binding is removed.
 			* @param terminalId - restored identity if the tab has no model yet.
 			*/
-			close(sessionId, key, terminalId) {
+			close(sessionId, key, contentId, terminalId) {
 				const views = this.views.get(sessionId);
 				const view = views?.get(key);
-				const id = view?.id ?? terminalId;
+				const id = view?.id ?? terminalId ?? this.bindings.get(sessionId, contentId);
 				if (id === void 0) return;
 				const request = {
 					sessionId,
@@ -606,12 +778,70 @@ window.__ModuleLoader__.load({
 				};
 				this.closed.add(id);
 				this.requests.save(request);
+				this.bindings.delete(sessionId, contentId);
 				views?.delete(key);
 				if (views?.size === 0) this.views.delete(sessionId);
 				this.cleanup(request, view);
+				this.reconcileHolds();
+			}
+			/**
+			* Reconcile this window's open terminal occurrences, including dormant saved Sessions.
+			* @param tabs - terminal-kind membership supplied by the sidebar layout owner.
+			*/
+			retainTabs(tabs) {
+				this.openTabs = tabs;
+				this.reconcileHolds();
+			}
+			hold(sessionId, id) {
+				let holds = this.holds.get(sessionId);
+				if (holds === void 0) {
+					holds = /* @__PURE__ */ new Map();
+					this.holds.set(sessionId, holds);
+				}
+				let hold = holds.get(id);
+				if (hold === void 0 || hold.failed) {
+					if (hold !== void 0) this.release(hold);
+					hold = new TerminalWindowHold(this.ctx.remote, this.remote, sessionId, id);
+					holds.set(id, hold);
+				}
+				return hold;
+			}
+			reconcileHolds() {
+				if (this.disposed) return;
+				const wanted = /* @__PURE__ */ new Map();
+				for (const tab of this.openTabs) {
+					const id = this.bindings.get(tab.sessionId, tab.contentId);
+					if (id === void 0 || this.closed.has(id)) continue;
+					let ids = wanted.get(tab.sessionId);
+					if (ids === void 0) {
+						ids = /* @__PURE__ */ new Set();
+						wanted.set(tab.sessionId, ids);
+					}
+					ids.add(id);
+					const view = this.views.get(tab.sessionId)?.get(tab.tabId);
+					if (view === void 0 || view.state.getSnapshot().info !== void 0) {
+						if (!this.holds.get(tab.sessionId)?.has(id)) this.hold(tab.sessionId, id);
+					}
+				}
+				for (const [sessionId, holds] of this.holds) {
+					for (const [id, hold] of holds) if (!wanted.get(sessionId)?.has(id)) {
+						holds.delete(id);
+						this.release(hold);
+					}
+					if (holds.size === 0) this.holds.delete(sessionId);
+				}
+			}
+			release(hold) {
+				const releasing = hold.dispose().finally(() => {
+					this.releasing.delete(releasing);
+				});
+				this.releasing.add(releasing);
+				releasing.catch((error) => {
+					this.ctx.logger.warn("Terminal hold release failed", error);
+				});
 			}
 			/**
-			* Query Host terminals that have neither a tab in this page nor an unfinished close.
+			* Query Host terminals without a live view or unfinished close.
 			* @param sessionId - Session being displayed.
 			* @returns terminals available for opening as recovered tabs.
 			*/