DSH plugin 怎么接终端子系统：持久终端 ID、后端约定、有界读取与 owner 快照

DSH plugin 的终端子系统是「一层服务 + 多种可替换 PTY 后端」：服务铸造 id、管授权与清理，后端只负责把某种类型跑起来。 两条规则最容易踩：授权比较的是确切拥有者 Agent，不是名称也不是猜到的 id；一次发送返回不等于 shell 退出——waitReason 可能只是静默或超时，顶层状态要看 sessionStatus。再加上「同一会话同时只允许一个活动发送」，就构成了这套接口的全部硬约束。

DSH plugin 的终端服务：id 由服务铸造，授权看确切 owner

一句话结论：id 与授权都在服务侧，名称只是展示；owner 不对，操作直接拒绝。

1. id 来源：TerminalSessionId 由服务铸造，调用方不自行生成。
2. 名称定位：可选名称是拥有者本地的显示元数据，不参与授权。
3. 授权对象：比较的是拥有该会话的确切 Agent。
4. 活动窗口：hasOwnerActivity(owner) 在 spawn 到 close 全程为真，没有发布空窗。
5. 可见性：list(owner) 只返回该 owner 可见的快照，按发布顺序排列。

DSH plugin 的后端约定：spawn 只发布成功的会话

一句话结论：初始化成功才发布；清理失败用专门错误保留，不顶替取消原因。

1. 类型稳定：TerminalBackend.type 是稳定类型名，由 TerminalSpawnRequest.type 选择。
2. spawn 语义：返回未发布的会话，或在清理部分资源后拒绝。
3. 清理失败：以 TerminalBackendCleanupError 拒绝启动，调用方的取消原因仍然保留。
4. 后端职责：拥有终端状态，并负责让已捕获的资源完全停稳。
5. 服务职责：发布后负责 id 授权与清理；close(reason) 幂等，重复调用共享同一次拆除。
6. 初始输出：motd 是 terminal_open 返回的有界初始输出，别把它当成完整 scrollback。

DSH plugin 的发送与等待：waitReason 与 sessionStatus 是两件事

一句话结论：发送返回只解释「为什么还给你」，会话状态单独说「shell 还在不在」。

1. 正交关系：一次发送可能因静默或超时返回，而顶层 shell 仍然存活。
2. session_exit 的范围：表示该 shell 退出，不是任意前台子进程退出。
3. 会话状态：{ kind: 'running' } 或 { kind: 'exited', exitCode, signal }。
4. 发送结果：viewport 是敲定时剩余的界面上有界增量，truncated 说明输出是否被丢弃。
5. 取消：cancel() 请求 SIGINT，操作敲定后返回 false。
6. 信号：signal(owner, id, allowedSignal) 只投向已校验的前台进程组。

DSH plugin 的有界读取与输出游标：前台与后台分开

一句话结论：前台拿最终结果，后台拿「读后即推进」的游标；scrollback 另走有界分页。

1. 活动发送唯一：每个会话同时只允许一个活动发送。
2. 后台任务形态：操作向通用后台任务提供读取后即推进的输出游标，适合长跑进程。
3. 前台形态：done 敲定后给 viewport、waitReason、sessionStatus 与 truncated。
4. scrollback 分页：read(owner, id, { offset, count }) 从保留输出里取有界一页，与发送游标互不影响。
5. 上限意识：两处都是有界返回，不要假设能一次拿全量输出。
6. 验证：长跑命令用后台游标读增量，再单独翻 scrollback 对比，确认没有重复消费。

DSH plugin 的归属、重载与持久性：PTY 字节不出进程

一句话结论：清理挂在 owner 作用域上，后端与工具插件重载时会话仍存活；原始字节不落日志。

1. 清理归属：服务把等待完成的清理附加到确切拥有者作用域，其它 owner 的操作被拒。
2. 重载存活：后端或工具插件重载期间，已发布会话保持存活。
3. 进程内边界：PTY 状态与原始字节局限在进程内，不随日志持久化。
4. 只持久有界内容：模型输入与有界返回输出走现有 tool/call、tool/result 与任务结果路径，不重复记录 PTY 会话事件。
5. 关闭要等停稳：kill 只有在后端清理完成并静默后才移除会话；重复调用返回 false。
6. 诊断：close(reason) 的 reason 会进清理诊断，写清触发来源便于事后追。

DSH plugin 排查注意事项

一句话结论：终端问题先分「授权被拒」「发送被占」「等待误判」「输出被截断」四类。

1. 操作被拒 → 检查是否用了确切的 owner Agent，名称与 id 猜测都不行。
2. 第二个发送卡住 → 同一会话只允许一个活动发送，先等 done 或 cancel。
3. 以为进程退出了 → 看 waitReason 与 sessionStatus，别只看发送返回。
4. 输出不全 → truncated 为真或读取有界，改用 scrollback 分页。
5. 重载后会话丢了 → 检查是否在后端清理阶段被关闭，正常情况下会话应存活。
6. 修复状态如实：本文的 id 与授权规则、后端约定、等待原因与持久性边界均取自官方「持久 PTY 会话」页面；接口签名以该页 Cordis API 与你所用版本为准。

来源：持久 PTY 会话、terminal 源码、子进程。