better-dsh 0.3.0 → 0.3.1

package/docs/specs/remote-tool-enhancement/spec.md

@@ -0,0 +1,203 @@
+# Remote 工具 enhancement — 交付、生命周期与传输规格
+
+- 日期：2026-10-10（Asia/Hong_Kong）
+- 状态：2026-10-10 user 已审阅并明确授权执行；Task0–7 已独立审阅通过；Task8 完整双包消费者验收进行中，L 实装暴露的 worker/SSH cleanup 缺陷已进入修复验证。用户亲验与发布尚未放行。
+- 输入：[2026-10-09 方向稿](../../10_plans/2026-10-09-remote-tool-optimization-directions.md)及 2026-10-10 会话裁决。
+- 执行计划：[2026-10-10-remote-tool-enhancement.md](../../superpowers/plans/2026-10-10-remote-tool-enhancement.md)。本规格优先于方向稿的冲突条款。
+
+## 1. 目标与本轮范围
+
+为 Agent 提供省步骤、减少转义和连接错误的 remote 便利层。一个 `remote` 工具覆盖 SSH、Docker、Incus、BYO-PTY，以及 Super 在场时的 Hub machine。Super 和 Better 分别可独立交付，不因另一包关闭或卸载丢失自身代码。
+
+本轮实现 P0/P1：
+
+1. Better 单一源码、Super 构建副本；两条插件行默认开启，Agent 实例级一次注册竞争。
+2. 可选 Hub 接入、动态 machine 清单；无远端机器时 Hub 清单为空，不执行本机。
+3. oneshot `script` 文件载体与 Hub oneshot stdin parity。
+4. 取消 Hub 模型工具缺省/显式本机执行入口，保留执行服务端与本地文件端点。
+5. BYO-SSH 注册、复用及连接参数；BYO-PTY 保持既有语义。
+6. oneshot 后台作业复用 DSH 原生 jobs 的 identity、pull-delta、完成通知及取消。
+7. `copy` 跨受支持端点的二进制传输、校验与暂存清理。
+8. `rsync` 仅 SSH；两个远端经发起机的 SSH 隧道中继，身份不下放。
+9. 真实双包交付和模型 Surface 验收。
+
+后续范围，不在本轮实现：P2 PTY 已完成命令的 backlog/offset 续读；P3 运行中 probe。取消：3.5M 提醒、一次性 `ssh://` target、`cmd[]` fan-out、push stdout、非 SSH/混合 transport rsync、BYO-WebSocket/Docker/Incus、命令黑名单、额外文件管理工具、inline cmd 扩容。
+
+## 2. 包归属与交付
+
+- 唯一可编辑源码：`better-dsh/src/remote/`。
+- Super 构建时从该源码生成独立 remote 交付闭包，导出 `super-dsh/remote`。不复制 Better 整包、客户端、REPL、文档或其他工具；不建立 Super→Better 的 npm dependency/optional/peer 边。
+- 生成目录及 provenance manifest 不手改；构建必须检查源码哈希与输出闭包，防止旧副本或跨包裸 import。
+- Better 行保留 `id: dashr-remote`、`name: better-dsh/remote`；Super 新行 `id: superd-remote`、`name: super-dsh/remote`。两个 YAML id 不相同，两行默认开，模型工具名相同：`remote`。
+- 不在 Super YAML 中禁用 Better remote，不写安装时脚本化的 profile enable/disable；已存在的用户开关选择保留。
+- Super 的 companion 原生安装流程不改变；remote 是“Super 不携带 Better 文件”契约的窄范围自有源码复用例外，而不是恢复整包捆绑。
+- 宿主模块继续 optional peer、真实类型和单实例契约；私有 schema 真实构建输入在生成闭包内解决，消费者不解析 Better 的 `#schemastery`。
+- 根、Better、Super 同步版本；实现轮经 `npm run version:release -- <同步字母版本>` 和双 tarball 通道，不发布 registry。
+
+## 3. Agent 实例级注册
+
+### 3.1 上游事实
+
+当前上游 `tools.register()` 同步插入 scoped registry，同 scope 同名立即抛错，不是先收集后统一去重。`agent/created` 是 setup 完成后、首轮工作放行前的 serial lifecycle 事件。preset revision/generation 被多个 Agent 复用，不能假设每个 session 重跑 preset 插件。
+
+证据位置：
+
+- `upstream/deepseek-harness/packages/core/tools/src/index.ts:1063`。
+- `upstream/deepseek-harness/packages/core/scope/src/store.ts:43`。
+- `upstream/deepseek-harness/packages/core/agent/src/runtime-types.ts:250`。
+- `upstream/deepseek-harness/packages/preset/agent-preset-registry/src/index.ts:104`。
+- `upstream/deepseek-harness/packages/api/session-controller/src/agent.ts:185`。
+
+### 3.2 行为
+
+- host 插件行只安装生命周期监听器，不在全局工具作用域注册 `remote`。
+- 每次 `agent/created`，两份行各自在该 Agent 的真实 scope 尝试注册工具。先成功者供该 Agent 使用，后者只跳过该实例。
+- 不自行判断 new/cold resume，不存 session 启动类型、不记录“已退出/待命”状态；官方创建事件本身给出尝试时机。必要改动仅为把现有 host 全局注册移到此事件的 scoped 注册，并局部处理同名冲突。
+- 不保证 Super 优先，不按 UI/YAML 展示顺序推断赢家。两份相同源码均可接入 Hub，赢家不影响能力集合。
+- 只处理实际的 `remote` 重名冲突，其他 schema、生命周期、服务异常继续抛出；不吞掉所有错误。
+- 重名跳过不写 `disabled`，不让 host 行变成失败状态，也不使 Agent 创建失败。
+- 注册、driver、PTY、BYO-SSH label 及 jobs 同时归该 Agent scope 和来源插件行所有：任一 owner 退出都撤注册并清理资源；不能仅依附 Agent 而留下已卸载包的执行闭包。
+- 不轮询、不设接管队列、不在空位出现时重试。已存活 Agent 中途卸载赢家，当前实例不自动补位。
+- new session 和 cold resume 创建新 Agent 时重新尝试；hot continuation、重开页面、给存活会话发消息不重试。
+- 首轮插件热安装不追溯给既有 Agent 补注册，Surface 提示新建会话或 cold resume；普通 disable→enable 若该插件本身支持恢复，须记录实际窗口，不承诺热接管。
+- foreign runtime 的既有 Hub 注入面与 native `remote` 不混淆：本轮不宣称所有 foreign agent 直接拥有 DSH scoped remote 工具。
+
+## 4. 可选 Hub 能力
+
+Better 不 import Super 包。共享 remote 定义 owned structural contract；Super 在官方 Cordis scope 提供 `superdRemoteTransport`，remote 用 `ctx.get()` 在能力消费时可选取得。absence 不形成硬 inject 等待，不修改宿主。
+
+- provider 在场 → 工具描述与 roster 说明 `hub:<machineId>`；机器目录可为空。机器变化只改变 roster，不增删 target 字段。
+- provider 不在场 → SSH/Docker/Incus/BYO 继续可用，Hub target 返回有恢复提示的 unavailable 错误，不静默改走 SSH。
+- provider 的出现/消失通过官方服务通知更新模型 Surface；不检查 npm 包目录，不轮询各机器可达性。
+- roster 来自 pairing 表中的远端 m4，排除 self；执行时检查 unknown machine、`execEnabled` 与连接错误，保留原始原因。
+- 远端执行服务端和文件 transport 随 Hub 本体提供，不依附模型侧 remote 行。关闭某台机器的工具行不应拆掉别人访问它的服务端。
+- PTY 沿用现有 pairing cookie、auth/Host/Origin fence 与 WS executor。oneshot 沿用既有 authenticated RPC，不声称现有 HTTP exec 已改为 WS。
+- 文件独立使用 binary WS lane；文本 PTY 不作为二进制文件通道。
+- 对端旧版本无文件 lane 时明确 unsupported；不以 base64 手搓冒充新增能力。
+
+## 5. 执行入口
+
+### 5.1 script 与 stdin
+
+`{ target, script: "/abs/local/script.sh", mode: "oneshot" }`：从工具所在运行时读文件，原文作为 `bash -s` 的 stdin。文件不要求能在目标机直接访问，不把源码拼入 argv。
+
+- `script`、`cmd`、`stdin` 的选择：script 与 cmd 互斥，script 与 stdin 互斥；stdin+cmd 沿用现有模式。
+- script 首轮仅 oneshot，BYO-PTY 或 mode pty 请求在读文件/拨号前拒绝。
+- 本地路径必须绝对、无 NUL；文件读取失败在连接/执行前报告。
+- 不做 script 自带业务 stdin 的第二通道；需要数据时用文件/参数，或用 cmd+stdin。
+- 保留 Hub inline cmd 4096 字符上限；script 固定命令短于上限，正文走 stdin。
+- Hub API、wire sender、legacy Hub tool exec Surface 同步支持 string stdin；PTY 不把 legacy stdin 支持悄悄扩成 script 模式。
+
+### 5.2 local
+
+- Hub 模型工具 exec 不再缺省本机；未传 machine 返回“请选择远端”提示，显式 self 默认也拒绝。
+- `localExec` 配置默认 false，可作为显式兼容入口，但不替正常消费者加入测试专用业务守卫。
+- 接收对端请求的本地 oneshot/PTY executor 保留；copy 的本地文件端点及读取 script 保留。
+
+### 5.3 输出
+
+- native/PTy 现有 4,000,000 UTF-16 code units 与 Hub oneshot 4MiB byte ring 是不同单位，回执必须真实说明；本轮不配置化，不凭文案把两者说成同一精确 4MB。
+- 保留约 30k 返回尾窗；统计总输出、保留量、已丢头部，超限明确标注。修复 native oneshot 现有收头却被上层当作尾窗的偏差。
+- 单次 dispatch 重新计数；达到上限不要求重启 PTY，重启不能找回已丢数据。
+- 不新增 3.5M 预警、输出预测或 push 监控。
+
+## 6. BYO-SSH
+
+调用形态：`{target:"byossh:label", ssh:{host,user?,port?,key?,proxyJump?}, cmd}`；首次注册连接，随后只用 target 复用。使用 `ssh` 字段而非复用现有 string `spawn`，避免破坏 BYO-PTY schema。
+
+- label 归 Agent 实例；不改 `~/.ssh/config`，不持久化凭据，不接受 inline 私钥内容；key 是发起机已有文件路径。
+- 首次可登记后执行或仅登记；复用相同参数幂等，不同参数给出冲突与换 label 提示。
+- host、user、port、key、proxyJump 通过参数数组、受控 config 文件或官方 SSH options 编排，不能拼出第二层任意 shell。
+- 所有执行、copy、rsync 和中继复用同一已解析 SSH connection spec，不能 rsync 又退回只读系统 alias。
+- roster 区分 SSH config 与 byossh labels，不导出密钥、cookie 或完整凭据。
+
+## 7. oneshot jobs
+
+`{target, cmd|script, run_in_background:true}` → 原生 jobId；读取/取消使用 DSH `job_output` / `job_kill`，完成由宿主通知。PTY mode 明确拒绝此选项。
+
+- 使用官方 `ctx.jobs.start`、owner、JobHooks、output source/pump；不自建第二份 job registry、poller 或通知渠道。
+- 子进程/远端任务在 job admission 后启动；启动被拒不能留下已经运行的进程。
+- job 输出必须运行中真实增量可读，不能等 command 完成后才一次 append 全量。
+- done 等到进程、远端任务及资源释放后结算；cancel 终止真实本地组/远端 job，不只把本地 Promise 标为取消。
+- provider 需要对 Hub oneshot 提供 job-owned start/read/cancel/done 协议；仅 abort HTTP fetch 不视为远端取消。
+- jobs service 不在场时同步 exec 仍可用，background 请求 fail-loud 并说明缺失的官方能力。
+- 前台 timeout 保持现有上限；background 无前台等待截止但受 owner cancellation 和 job kill 管理。
+
+## 8. 文件操作
+
+### 8.1 寻址及能力边界
+
+`{action:"copy", src, dst, verify:true, mkdir:true}` 与 `{action:"rsync", src, dst, delete:false, excludes:[], dryRun:true, preserve:true}`。
+
+端点使用 `[target:]绝对路径`；例如 `/tmp/a`、`ssh:dev3:/data/a`、`byossh:review:/data/a`、`docker:build:/data/a`、`hub:skc8:/data/a`。按最后一个 `:/` 边界解析 target/path，避免把 transport 前缀冒充 host。裸 label 的兼容解析复用 remote roster 规则，不另建命名系统。
+
+- copy 首轮支持文件与目录的 local、SSH/byossh、Docker、Incus、Hub 端点；每条腿使用实际 binary stream，保持精确路径与明确的内容/目录语义。
+- byop 是任意交互 shell，不保证 binary I/O 或 filesystem；copy/rsync 不承诺可用，拒绝并建议用显式 transport target。
+- rm/mv/mkdir/chmod/stat 不增加 action；mkdir 仅 copy 的建父目录选项。
+- 校验使用 SHA-256；目录使用排序、长度编码的相对路径/条目类型/内容 manifest，明确 symlink 不跟随，避免文件名含空白/换行破坏回执。
+- 覆盖默认允许普通文件，目录合并无删除；不得悄悄把 copy 变为 rsync delete。路径/type 不兼容返回错误。
+
+### 8.2 copy 中转
+
+任意两远端通过工具所在发起机中转，各腿使用其已有 target 通道，不向其中一端复制另一端连接身份。中转采用任务级 `.scratch` 暂存，先收完整载体，再向目标发送；不宣称提供源到目标流式复制、delta 或断点恢复。
+
+- 二进制 lane 需要 backpressure、传输错误/关闭、显式完成帧、有限 metadata/frame buffer 和 cancellation。
+- tar/archive 或等价 carrier 在解包前验证成员路径，不接受绝对成员、`..` 出界或借 symlink 写出目标目录。
+- `verify:true` 返回独立源/目标 hash 或 manifest digest、条目/字节统计、校验结果；数据端失败不能给成功回执。
+- 中转任务成功后清理 owned 暂存；失败保留可诊断载体，回执给出位置和原因。保留不意味着自动重试。
+- 远端临时进程、监听/临时接收文件必须取消/结束清理，不能因为“失败保留诊断”而留后台服务。
+- `verify:false` 不显示已校验；successful transfer 也清理中转载体，不无限堆垃圾。
+
+### 8.3 SSH-only rsync
+
+- 支持 local↔SSH，以及 SSH↔SSH；目标连接来自系统 SSH config 或 byossh 注册。
+- 两个 remote 参数不能直接传给普通 rsync；工具负责变成原生 rsync 可接受的一端本地视角。
+- remote↔remote 通过发起机建 SSH 隧道中继；一种实现为目标端短命 loopback rsync daemon + 发起机 local forward + 源端 reverse forward。rsync delta 算法仍为原生实现。
+- 两端 identity 仅由发起机 SSH 进程使用；禁止复制 private key、导出登录凭据、ssh-agent forwarding 或修改远端 SSH config。
+- daemon 仅绑定 loopback、模块限定目标目录，以当前登录用户启动；不安装永久 daemon，不公开监听。SSH 禁止 forwarding 时返回原始拒绝。
+- `dryRun` 默认 true、`delete` 默认 false；`excludes`、preserve、trailing slash 内容语义通过参数表达。真正传输显式 dryRun false。
+- 预检两端 rsync 和所需 SSH forwarding；缺失不静默 fallback copy，更不能对 delete/excludes 回报假成功。
+- 捕获 rsync 原始退出码与 itemized changes，保持 stderr；非零不标成成功。
+- 无论成功、失败、cancel 都清理 tunnel、短命 daemon 与本任务临时 config；复用 transport 不等于关掉用户既有 SSH 会话。
+
+## 9. 验收和完成定义
+
+代码、传统测试、打包成功只说明阶段进度，不等于产品验收。
+
+1. scoped 真实 Cordis/Agent fixture：双包仅一个 remote；Agent 创建不失败；非重名异常不被吞；不同 Agent 互不争抢；赢家卸载当前实例不补位；new/cold resume 可恢复；hot continuation 不假装恢复；退出清理。
+2. 单包 Better tarball：无 Super import/安装，SSH/Docker/Incus/BYO 按已有能力工作；jobs 缺失错误真实。
+3. Super tarball：禁用/卸载 Better 后 remote 仍可用；两包启用顺序相反都可用；Hub 存在但 machine 清单空的 Surface 正确；关闭模型工具行不拆 Hub executor。
+4. 4999 完整 launcher：安装双 tarball、真实模型 roster/script/stdin/PTY/后台任务/job_output/job_kill/copy/rsync 与错误恢复；工具 catalog 和 REPL 路由属于验收。
+5. dev3 同版本实际安装：配对但无 SSH 的 Hub PTY 与 binary copy；dev3↔另一 SSH 目标经发起机中继，远端无对方 key/config；第二次改少量内容证明真实 rsync delta；cancel/异常证明无残留。
+6. 记录上游实际 checkout、目标宿主版本、同步版本、tarball SHA-256、安装步骤、模型可见 Surface 和失败证据至 `docs/test-reports/`。
+7. Web 测试线保持运行，报告真实访问 URL，供 user 亲验。
+8. 不触碰生产 home/3080/3081/Caddy，不修改上游，不 npm publish、不 commit/tag/push 定版。发布需要本次单独放行。
+
+## 10. 书面确认边界
+
+本稿实现上述会话裁决，没有把 P2/P3、非 SSH rsync 或热接管重新塞入首轮。字段 `ssh`、端点解析、copy 的 BYO-PTY 不支持回执是保持已有接口并使交付可实现的具体化；user 可在书面规格审阅时修订。收到书面审阅后，按执行计划进入实现，不再为已批准的 routine 实现步骤重复请求授权。
+
+
+### 2026-10-10 consumer worker delivery correction
+
+The generated Super `remote/` contains exactly `plugin.js`, `plugin.d.ts`, private `file-worker.js`, and `provenance.json`. The worker leaf is built solely from canonical `better-dsh/src/remote/file-worker.ts`, has Node-builtins-only imports, and is hashed/checked with the closure. It has no public package export, host peer imports, duplicated host modules, source loader or Better dependency. The public plugin contract remains unchanged. The existing owned child-process/group cleanup remains the receiver boundary; no worker-thread lifecycle replacement. This narrow extra generated leaf fixes actual installed receiver resolution, not a general guarantee that host plugins import outside their host resolver.
+
+### Task8 delivery correction: owned SSH oneshots (Ruling22)
+
+Real consumer job-kill exposed local-only SSH termination. Foreground/background/script/stdin SSH oneshots therefore reuse the portable receiving sideband owner, preserving native literal stdio and connection normalization. Remote Bash4.1+, Python3.7+ (macOS3.10+), shared non-adjustable cross-process monotonic clock, Unix fcntl.flock and mktemp/mv/rm/sleep are required. Ordinary commands never require rsync; origin needs no Python, and this path needs no Linux/pidfd. Three SSH startups (clock, control, work), with authenticated same-identity cleanup reconnect after ambiguous startup; existing lease/bounds remain. Receiver helper/group cleanup precedes settlement, followed by up to2500ms work-stream drain; unavailable drain explicitly marks incomplete received output without fabricated counters. PTY/BYOPTY and rsync-specific restrictions remain unchanged. No second jobs registry or availability polling.
+
+
+### Task8 container oneshot ownership correction (Rulings23–24)
+
+Actual installed Docker/Incus native job cancellation reported killed while receiving children remained live. Canonical oneshot foreground/background/script/stdin therefore share the SSH portable receiving gate/control/work barrier through native container exec argv, not local CLI termination. Each command requires three native exec startups (clock, owner, literal-stdio work), remote Bash4.1+, Python3.7+, Unix fcntl.flock/shared non-adjustable cross-process monotonic clock, mktemp/mv/rm/sleep. Linux containers additionally require stdlib ctypes and permitted unprivileged PR_SET_CHILD_SUBREAPER before business admission; the work helper reaps only its own/adopted children and stays alive until its work group is absent. This supports ordinary non-reaping PID1 containers without forcing --init, privilege/capability, image/config mutation, rsync, pidfd or origin Python. PTY/BYOPTY stay unchanged; SSH portable prerequisites are not broadened. The same eight-second counted lease, gate recovery, actual cleanup barrier and 2500ms honest final-output drain apply, with no enlarged grace, second job registry or availability polling. Consumer iteration N must prove real native killed status together with owned process/group/helper/state absence; M failures remain historical evidence.
+
+Ruling25 supersedes the original two-remote source -R/private-master/sshd-FD/pidfd design after actual default dev3 source failed its permission requirement. A task-owned portable Python loopback proxy, inside the existing receiving helper/group/lease, carries bounded binary frames over authenticated SSH work stdio to an origin TCP bridge into the destination -L tunnel. A real full-route @RSYNCD greeting precedes business admission. No source Linux /proc, pidfd, privileged sshd access or source forwarding permission is required; native find, native rsync and the existing portable Bash/Python/fcntl/shared-monotonic prerequisites remain. No origin Python, credentials on peers, copy fallback, lease increase or second registry. Five-byte type/length frames cap data at64KiB and Python queues at256KiB; one active connection, real backpressure and half-close, prior reader/socket close before next OPEN. Ordinary two-remote transfer measures12 SSH startups: source preflight+inspection clock/work3, relay source/destination preflight2, destination clock/daemon+tunnel2, source proxy clock/owner/work3, native source rsync clock/work2. Fault recovery adds only task-owned authenticated cleanup reconnects, never transfer retries. Same real helper/listener/group/metadata/tunnel/socket cleanup barrier; receiving progress remains an explicit assumption. Historical M permission failure remains in the acceptance report; current default-dev3-source source test passes, installed next-artifact proof is separate.
+
+
+### CLI binary receiving ownership (consumer correction, Ruling26)
+
+Actual N native SSH copy cancellation settled while the remote import process and its unnamed staging file remained live under a finite work-channel EOF hold. CLI export/import/digest now reuse the canonical portable receiving owner, with raw binary work streams and the same counted lease, admission gate and authenticated recovery. Cancellation/failure waits for receiving helper/group/temp cleanup before local transport teardown/settlement. Normal success must completely drain the binary stream; the oneshot text lane's 2500ms incomplete-output rule does not apply. Archive validation, selected manifest digests, merge/no-delete behavior and canonical SSH identity/ProxyJump are unchanged. Local and Hub file lanes are unchanged.
+
+This intentionally replaces the former Python-only minimum for CLI peers: Bash4.1+, Python3.7+ (macOS3.10+), Unix fcntl.flock/shared non-adjustable cross-process monotonic clock, mktemp/mv/rm/sleep; Linux containers also need stdlib ctypes and permitted unprivileged PR_SET_CHILD_SUBREAPER. No rsync or origin Python requirement, auto-install, second registry, fallback, peer polling or increased lease. Minimal Python-only peers no longer support this CLI lane; use a supported peer or authenticated Hub.
+
+Each remote export/import/digest costs three native transport starts: clock, independent owner/control, literal binary work. Thus verified local→CLI or CLI→local costs six; CLI→CLI twelve. verify:false skips digest operations, reducing counts to three/three/six. Local/Hub operations do not contribute CLI starts. Fault recovery may add same-identity authenticated cleanup starts and may remain pending until genuine cleanup observation is possible. Artifact O must re-prove installed cancellation and complete binary integrity; N failures remain historical evidence.

package/dsh-docs/baseline.md

@@ -0,0 +1,13 @@
+# DSH runtime compatibility
+
+Better Dash and Super Dash use the same DSH host APIs. The verified upstream source baseline for this alignment is `dsh-v0.2.1-alpha.1` (`5badb15009ae1756c3afe0ae0cef1faafc290ccc`). The pages in this directory include older official reference snapshots; check this baseline before using an API described by a snapshot.
+
+On `0.2.1-alpha.1`:
+
+- The runtime `dsh-invariants` plugin, `ctx.invariants`, and companion `./invariant` exports are removed. The archived invariant reference does not define an available extension API.
+- Plugin subpaths provide display text through `<specifier>/locale/en.json` and localized sibling exports, and icons through `<specifier>/icon`. Subpaths do not read a separate `package.json`.
+- Composer statistics use separate `activity` and `usage` entries.
+- The native Plugin Manager refreshes profile package resolution when bundles are installed, enabled, disabled or removed. Replacing installed package code still requires a restart.
+- Automation is part of the Web composition. Reminder tools depend on agent mode; they are absent in Minimal mode and subagents.
+
+See the [official release notes](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.1-alpha.1) and the actual host package exports for the complete interface contract.

package/dsh-docs/subsystems/invariants.md

@@ -1,5 +1,8 @@
 # Runtime Invariants
 
+> DSH `0.2.1-alpha.1` removes this plugin and all companion `./invariant` exports. This page is an older reference snapshot; use the [runtime compatibility baseline](../baseline.md) for the current host contract.
+
+
 English | [中文](invariants.zh.md)
 
 [dsh-invariants](../../packages/runtime-diagnostics/invariants) is the configurable registry service (`ctx.invariants`) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a `./invariant` companion plugin that registers checks under its exact npm package name. What a check may assert — authoritative event streams or mutable data, never service or method presence — is the runtime-invariants convention in [AGENTS.md](../../AGENTS.md#conventions); the registry design is owned by the [invariant-service Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md).

package/dsh-docs/subsystems/invariants.zh.md

@@ -1,5 +1,8 @@
 # 运行时不变式
 
+> DSH `0.2.1-alpha.1` 已移除此插件及所有配套 `./invariant` 导出。本页保留旧版参考快照；当前宿主契约见[运行时兼容基线](../baseline.md)。
+
+
 [English](invariants.md) | 中文
 
 [dsh-invariants](../../packages/runtime-diagnostics/invariants) 是面向包自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 配套插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；注册表设计由[不变式服务 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md)规定。

package/eval-description.md

@@ -1,13 +1,17 @@
 Run one Python cell on a session-persistent scripting pad. One `eval` call = one cell; the pad's state persists across calls and turns — variables, imports, and definitions from earlier cells stay alive.
 
-Work incrementally: imports → define → test → use, each its own cell. Re-run setup only after `reset` or a crash.
+Work incrementally: imports → define → test → use, each its own cell. The pad uses an OMP-backed Python interpreter; Python must be available on the host. Better supplies its runner and checkpoint serializer without installing Jupyter or Python packages.
+
+After a restart, read the recovery notice before relying on earlier variables. Checkpoints restore Python scratchpad values on a best-effort basis; notices identify the last saved cell and any omitted values. Open files, sockets, subprocesses, locks and other live resources must be recreated. A checkpoint does not restore files, undo tool calls or recover the entire Python process.
+
+An interrupted or dying cell may already have changed variables, files or external systems. It is never automatically retried. Inspect the reported checkpoint and actual external state before deciding what to run again. A failed checkpoint leaves the previous valid checkpoint available; a failed restore starts with empty state and reports the reason.
 
 ## Arguments
 
 - `cell` (required): one Python program body. Top-level `await` works; top-level `return` is a SyntaxError — the cell runs in module scope (REPL semantics, not a function body).
 - `description` (required): a short summary of what the cell does — shown as the call's title in the UI.
 - `timeout` (optional): wall-clock budget in seconds; the cell is interrupted (then force-stopped) when exceeded. Omit for the runtime default.
-- `reset` (optional): restart the pad EMPTY first — earlier state is discarded.
+- `reset` (optional): restart the pad EMPTY first and delete its checkpoints — earlier state is discarded.
 
 ## Direct calls vs cells
 
@@ -20,7 +24,7 @@ Delegation: `agent` is the unified agent-spawn entry; `subagent` is its native a
 Every session tool is callable from a cell as `await tool.<name>(args)` with ONE positional argument: `args` is the tool's parameter object written as a Python dict literal, same field names (`true`/`false`/`null` become `True`/`False`/`None`). A failed call raises `ToolCallError` with `.toolName` naming the tool. Tool names that are not plain identifiers (e.g. contain hyphens) have no `tool.<name>` member — call those as direct tool calls.
 
 ```python
-print(await tool.read({"path": "docs/README.md", "limit": 5}))
+print(await tool.read({"file_path": "docs/README.md", "limit": 5}))
 
 r = await tool.bash({"command": "ls -la src/", "description": "List source directory"})
 print(r["stdout"]["text"])

package/lib/{LaunchOptions-kGXcZOe0.js → LaunchOptions-5eg7E0ye.js}

@@ -1,4 +1,4 @@
-import { b as ChromeReleaseChannel } from "./main-CupOhMp5.js";
+import { b as ChromeReleaseChannel } from "./main-BeCgUd20.js";
 
 //#region node_modules/puppeteer-core/lib/puppeteer/node/LaunchOptions.js
 /**

package/lib/LaunchOptions-DxQQ0s-A.js

@@ -0,0 +1,4 @@
+import "./main-BeCgUd20.js";
+import { t as convertPuppeteerChannelToBrowsersChannel } from "./LaunchOptions-5eg7E0ye.js";
+
+export { convertPuppeteerChannelToBrowsersChannel };

package/lib/{bidi-BalpKaJc.js → bidi-CwabFH07.js}

@@ -1,6 +1,6 @@
 import { n as __require } from "./chunk-DQxbwPpZ.js";
 import { A as stringToTypedArray, G as first, H as delayWhen, K as firstValueFrom, L as combineLatest, M as assert, Q as map, S as timeout, St as debug, Tt as environment, V as defer, W as filter, at as race, b as isString, bt as TouchError, c as evaluationString, d as fromEmitterEvent, g as isDate, gt as ProtocolError, h as getSourceUrlComment, ht as ConnectionClosedError, i as SOURCE_URL_REGEX, k as stringToBase64, lt as switchMap, m as getSourcePuppeteerURLIfAvailable, o as debugCatchError, ot as raceWith, q as from, r as PuppeteerURL, rt as of, s as debugError, u as fromAbortSignal, v as isPlainObject, vt as TargetCloseError, x as parsePDFOptions, xt as UnsupportedOperation, y as isRegExp, yt as TimeoutError } from "./util-BHL_dfV_.js";
-import { $n as Deferred, $t as scriptInjector, Bt as throwIfDetached, Ct as WebWorkerEvent, Dn as DeviceRequestPrompt, Dt as normalizeHeaderValue, Fn as Browser, Hn as DisposableStack, Ht as bindIsolatedHandle, In as WEB_PERMISSION_TO_PROTOCOL_PERMISSION, It as Dialog, Jn as CallbackRegistry, Kn as disposeSymbol, Ln as CDPSession, Lt as Accessibility, Mn as invokeAtMostOnceForArguments, Mt as InterceptResolutionAction, Nn as throwIfDisposed, Nt as STATUS_TEXTS, On as BrowserContext, Ot as SecurityDetails, Pt as handleError, Rt as Frame, St as WebWorker, Ut as JSHandle, Vt as ElementHandle, Zn as isErrorLike, _t as Mouse, an as stringifyFunction, cn as Tracing, dt as ConsoleMessage, en as ARIAQueryHandler, fn as Coverage, gt as Keyboard, ht as TargetType, in as interpolateFunction, jn as inertIfDisposed, jt as HTTPRequest, kn as bubble, kt as HTTPResponse, mn as Page, mt as Target, nn as LazyArg, on as AsyncIterableUtil, sn as FileChooser, un as EmulationManager, vt as MouseButton, wt as Realm, yt as Touchscreen, zn as EventEmitter } from "./index-browser-CysrjMyM.js";
+import { $n as Deferred, $t as scriptInjector, Bt as throwIfDetached, Ct as WebWorkerEvent, Dn as DeviceRequestPrompt, Dt as normalizeHeaderValue, Fn as Browser, Hn as DisposableStack, Ht as bindIsolatedHandle, In as WEB_PERMISSION_TO_PROTOCOL_PERMISSION, It as Dialog, Jn as CallbackRegistry, Kn as disposeSymbol, Ln as CDPSession, Lt as Accessibility, Mn as invokeAtMostOnceForArguments, Mt as InterceptResolutionAction, Nn as throwIfDisposed, Nt as STATUS_TEXTS, On as BrowserContext, Ot as SecurityDetails, Pt as handleError, Rt as Frame, St as WebWorker, Ut as JSHandle, Vt as ElementHandle, Zn as isErrorLike, _t as Mouse, an as stringifyFunction, cn as Tracing, dt as ConsoleMessage, en as ARIAQueryHandler, fn as Coverage, gt as Keyboard, ht as TargetType, in as interpolateFunction, jn as inertIfDisposed, jt as HTTPRequest, kn as bubble, kt as HTTPResponse, mn as Page, mt as Target, nn as LazyArg, on as AsyncIterableUtil, sn as FileChooser, un as EmulationManager, vt as MouseButton, wt as Realm, yt as Touchscreen, zn as EventEmitter } from "./index-browser-B-9jm12n.js";
 import "./BrowserWebSocketTransport-wm99h94r.js";
 
 //#region node_modules/mitt/dist/mitt.mjs

package/lib/client/index.js

@@ -613,7 +613,7 @@ function CompactionRow({ t, loadConfig, save }) {
 * Register the dictionaries and the General settings row.
 *
 * Called from the plugin's client entry, which already injects `locale`,
-* `slots` and `remote.settings`.
+* `slots`, `remote.settings` and `configForms`.
 *
 * @param ctx - client root context.
 */
@@ -622,7 +622,7 @@ function setupCompactionRow(ctx) {
 		zh: zh$1,
 		en: en$1
 	}), "compaction-tuning: dictionaries");
-	ctx.slots.inject("settings.general.item", function* () {
+	ctx.effect(() => ctx.configForms.whileServed([COMPACTION_SETTINGS_ENTRY], () => ctx.slots.inject("settings.general.item", function* () {
 		yield ctx.slots.register({
 			name: "settings.general.item",
 			id: COMPACTION_SETTINGS_NS,
@@ -647,7 +647,29 @@ function setupCompactionRow(ctx) {
 				}
 			})
 		}, CompactionRow);
-	});
+	})), "compaction-tuning: served settings row");
+}
+
+//#endregion
+//#region src/welcome-notice/client/index.ts
+/** Complete each newly selected notice without persisting native acknowledgement state. */
+function SkipWelcomeNotice({ complete }) {
+	const completed = (0, react.useRef)(false);
+	(0, react.useEffect)(() => {
+		if (completed.current) return;
+		completed.current = true;
+		complete();
+	}, [complete]);
+	return null;
+}
+/** A package client can outlive this independently toggleable Host component. */
+function setupWelcomeNotice(ctx) {
+	ctx.effect(() => ctx.configForms.whileServed(["dashr-welcome-notice"], () => ctx.slots.inject("settings.onboarding", () => ctx.slots.register({
+		name: "settings.onboarding",
+		id: "welcome-notice",
+		priority: -1,
+		order: -100
+	}, SkipWelcomeNotice))), "welcome notice: served skip policy");
 }
 
 //#endregion
@@ -658,7 +680,8 @@ const inject = [
 	"locale",
 	"remote",
 	"remote.settings",
-	"remote.session"
+	"remote.session",
+	"configForms"
 ];
 /**
 * Register the `failover` dictionaries and the General settings row.
@@ -671,7 +694,8 @@ function apply(ctx) {
 	}), "llm-failover: dictionaries");
 	setupMobileLayout(ctx);
 	setupCompactionRow(ctx);
-	ctx.slots.inject("settings.general.item", function* () {
+	setupWelcomeNotice(ctx);
+	ctx.effect(() => ctx.configForms.whileServed([FAILOVER_SETTINGS_ENTRY], () => ctx.slots.inject("settings.general.item", function* () {
 		yield ctx.slots.register({
 			name: "settings.general.item",
 			id: "failover",
@@ -702,7 +726,7 @@ function apply(ctx) {
 				}
 			})
 		}, FailoverRow);
-	});
+	})), "llm-failover: served settings row");
 }
 
 //#endregion

package/lib/failover/index.js

@@ -1,6 +1,6 @@
 import { t as Schema } from "../lib-C8_jXvwA.js";
-import { randomUUID } from "node:crypto";
 import { Context } from "@deepseek-ai/cordis";
+import { randomUUID } from "node:crypto";
 import { RetryId } from "@deepseek-ai/dsh-llm-retry";
 
 //#region src/failover/config.ts

package/lib/fs-aware/sandbox-plugin.js

@@ -1,7 +1,7 @@
-import { f as UrlSchemesError, t as buildFsLayerResolver } from "../wrap-T4I0nfPM.js";
-import { stat } from "node:fs/promises";
-import { dirname, sep } from "node:path";
+import { f as UrlSchemesError, t as buildFsLayerResolver } from "../wrap-0VA0uFx8.js";
 import { Context } from "@deepseek-ai/cordis";
+import { dirname, sep } from "node:path";
+import { stat } from "node:fs/promises";
 import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
 import { FsError } from "@deepseek-ai/dsh-fs";
 import { writableRoots } from "@deepseek-ai/dsh-sandbox";

package/lib/{index-browser-CysrjMyM.js → index-browser-B-9jm12n.js}

@@ -20792,7 +20792,7 @@ async function _connectToBiDiBrowser(connectionTransport, url, options) {
 	const { bidiConnection, cdpConnection, closeCallback } = await getBiDiConnection(connectionTransport, url, options);
 	return await (await import(
 		/* webpackIgnore: true */
-		"./bidi-BalpKaJc.js"
+		"./bidi-CwabFH07.js"
 )).BidiBrowser.create({
 		connection: bidiConnection,
 		cdpConnection,
@@ -20815,7 +20815,7 @@ async function _connectToBiDiBrowser(connectionTransport, url, options) {
 async function getBiDiConnection(connectionTransport, url, options) {
 	const BiDi = await import(
 		/* webpackIgnore: true */
-		"./bidi-BalpKaJc.js"
+		"./bidi-CwabFH07.js"
 );
 	const { slowMo = 0, protocolTimeout, idGenerator = createIncrementalIdGenerator() } = options;
 	const pureBidiConnection = new BiDi.BidiConnection(url, connectionTransport, idGenerator, slowMo, protocolTimeout);
@@ -20887,10 +20887,10 @@ async function getConnectionTransport(options) {
 			endpointUrl: connectionURL
 		};
 	} else if (options.channel && isNode) {
-		const { detectBrowserPlatform, resolveDefaultUserDataDir, Browser: Browser$1 } = await import("./main-BQeFrBM1.js");
+		const { detectBrowserPlatform, resolveDefaultUserDataDir, Browser: Browser$1 } = await import("./main-Dv_UQqG2.js");
 		const platform = detectBrowserPlatform();
 		if (!platform) throw new Error("Could not detect required browser platform");
-		const { convertPuppeteerChannelToBrowsersChannel } = await import("./LaunchOptions-B874eBu2.js");
+		const { convertPuppeteerChannelToBrowsersChannel } = await import("./LaunchOptions-DxQQ0s-A.js");
 		const { join } = await import("node:path");
 		const portPath = join(resolveDefaultUserDataDir(Browser$1.CHROME, platform, convertPuppeteerChannelToBrowsersChannel(options.channel)), "DevToolsActivePort");
 		try {

package/lib/index.d.ts

@@ -379,7 +379,7 @@ interface ReplRuntimeSurface {
 //#region src/runtime.d.ts
 /** Plugin config: every tunable, changeable from `cordis.yml` (no hardcoded tunables). */
 interface Config$1 {
-  /** Python interpreter with `ipykernel` installed. The bare sentinel `python3` (or absent) selects a managed venv under {@link Config.kernelEnvDir}. */
+  /** Python >=3.9 interpreter. The bare sentinel `python3` (or absent) selects a managed venv under {@link Config.kernelEnvDir}. */
   python?: string;
   /** Budget for kernel spawn → ready, in milliseconds. */
   startupTimeoutMs?: number;
@@ -388,8 +388,7 @@ interface Config$1 {
   /** Grace between a timeout/abort interrupt and the force-settle, in milliseconds. */
   interruptGraceMs?: number;
   /**
-   * Confirm window between the control-channel interrupt and the SIGALRM
-   * escalation, in milliseconds; must stay below {@link Config.interruptGraceMs}.
+   * Confirm window before repeating SIGINT, in milliseconds; must stay below {@link Config.interruptGraceMs}.
    * See the bridge's two-phase interrupt for why the escalation is deferred.
    */
   interruptConfirmMs?: number;
@@ -399,15 +398,15 @@ interface Config$1 {
   snapshotTimeoutMs?: number;
   /** Hard cap for serialized log-array, completion-value, and failure-message payloads. */
   maxOutputBytes?: number;
-  /** Directory for per-session namespace snapshots (`state.dill` + `manifest.json`); none when absent. */
+  /** Per-session immutable checkpoints. Defaults to the official profile home; empty string disables, standalone callers opt in. */
   snapshotDir?: string;
-  /** Serialized-size cap for a turn-end snapshot, in bytes; over-cap snapshots are skipped with a one-time model warning. */
+  /** Serialized graph cap in bytes; each over-cap attempt reports the last successful checkpoint. */
   snapshotSizeCapBytes?: number;
   /** Managed venv directory (used when `python` is absent/`python3`); defaults to `<package>/.venv-kernel`. */
   kernelEnvDir?: string;
   /** Preferred CPython version for a managed venv. */
   kernelPythonVersion?: string;
-  /** Provision the managed venv (ipykernel + dill) on first use; default true. */
+  /** Provision a stdlib-only managed venv on first use; default true. */
   kernelAutoInstall?: boolean;
   username?: string;
 }
@@ -428,6 +427,7 @@ declare class DashrRuntime extends ReplRuntime {
   /** One entry per session principal that has run code (lazy — never pre-seeded). */
   private readonly kernels;
   private disposed;
+  private readonly transactions;
   /** Lazily-resolved (and, when managed, provisioned) kernel interpreter. */
   private kernelEnvPromise;
   constructor(ctx: Context, config: Config$1);
@@ -446,7 +446,9 @@ declare class DashrRuntime extends ReplRuntime {
    * @param request - the program, its bindings, and the abort signal.
    * @returns the run's outcome per the seam contract.
    */
+  private transaction;
   run(request: CodeRunRequest): Promise<CodeRunResult>;
+  private runTransaction;
   /**
    * Read one user-namespace variable by name on the session's kernel. A
    * bare/empty name lists the namespace's user-variable names; a
@@ -459,6 +461,7 @@ declare class DashrRuntime extends ReplRuntime {
    * @param principal - the session key (absent → the shared default).
    */
   queryVar(name: string, principal?: string): Promise<ReplVarQuery>;
+  private queryTransaction;
   /**
    * Assign one lossless-JSON value into the user namespace under `name` on
    * the session's kernel. `name` must be a usable identifier (and not a
@@ -470,6 +473,7 @@ declare class DashrRuntime extends ReplRuntime {
    * @param principal - the session key (absent → the shared default).
    */
   setVar(name: string, value: unknown, principal?: string): Promise<void>;
+  private setTransaction;
   /** Map one cell outcome onto the seam's result shape under the output ledger. */
   private assembleResult;
   /** Reject malformed binding globals or typed-error declarations as contract misuse. */
@@ -486,40 +490,14 @@ declare class DashrRuntime extends ReplRuntime {
    * @param key - the run principal (or the agentless default).
    */
   private ensureKernel;
-  /**
-   * Restore a key's on-disk snapshot into a freshly booted kernel, when one
-   * exists and its manifest is plausible. Called once per entry boot. The
-   * kernel-side restore cell performs the authoritative environment checks
-   * (python version, interpreter identity, skills); this method only gates on
-   * the manifest the host can read cheaply, then records the turn so the
-   * first-run notice and the revive chain can name it.
-   */
+  /** Restore once before user admission; any degraded load retires that child. */
   private restoreEntry;
-  /** Read the per-key manifest's host-relevant fields; absent when unreadable/missing. */
-  private readSnapshotManifest;
-  /**
-   * Revive one session's kernel after death: respawn a fresh kernel, restore
-   * the nearest replayable snapshot onto it (the normal restore path), and
-   * return the death-observing run's explicit error naming the turn. When no
-   * replayable snapshot exists the message falls back to M3-A's fresh-empty
-   * contract. The run itself does NOT execute — an error that lies about a
-   * NameError costs the model more than one dropped cell (blueprint §8.3).
-   * @param key - the run principal.
-   * @param dead - the entry that died (its `turn` is the last completed turn).
-   */
+  private omissionNotice;
+  /** Restore a fresh child and report whether the observing call had started. */
   private reviveAfterDeath;
-  /**
-   * Write one key's turn-end snapshot, when a snapshot directory is
-   * configured. A size-cap skip is reported (so the run can warn the model
-   * once); other failures log without disturbing the run.
-   */
+  /** Save completed mutations and expose partial/failed coverage within output limits. */
   private snapshotTurnEnd;
-  /**
-   * Dispose to quiescence: snapshot every live key's namespace when a
-   * snapshot directory is configured (each under its own per-key
-   * subdirectory), then shut the subprocesses down. Registered as the
-   * plugin's `ctx.effect` disposer.
-   */
+  /** Cancel active work, drain admitted transactions, and reap every owned child. */
   private teardown;
   /**
    * Tear one session's kernel down (session end via the `agent/disposed`
@@ -530,11 +508,9 @@ declare class DashrRuntime extends ReplRuntime {
   /**
    * Reset one session's kernel to a fresh, empty namespace: dispose the live
    * subprocess WITHOUT a turn-end snapshot and clear its on-disk snapshot, so
-   * the next ensureKernel spawns empty (restore finds nothing to replay).
+   * the next ensureKernel spawns empty (restore finds no checkpoint).
    */
   private resetKey;
-  /** Snapshot (when configured) then dispose one key's kernel; failures log, never throw into a listener. */
-  private teardownKernel;
 }
 //#endregion
 //#region src/tool-call-id.d.ts
@@ -619,7 +595,7 @@ declare function resolveMaxParallelSubCalls(value: number | undefined): number;
  * `dashr/repl-dispatch-log` waterfall — dashr's OWN dispatch-log event,
  * self-registered via the cordis Events merge below. Decoupled from
  * upstream's `tools/ptc-dispatch-log` (PTC `run_code` sub-dispatches): `eval`
- * is a broader session-persistent REPL (IPython kernel) than upstream's
+ * is a broader session-persistent REPL (OMP Python child) than upstream's
  * `run_code` TS-worker tool, so its durable-log reshape extension point is
  * dashr-owned and version-independent — no coupling to upstream's
  * `CodeDispatchLog`/`PtcDispatchLog` rename or the PTC tool's event name.