Managed bootstrap protocol：OpenShell 沙箱的可信身份绑定重启事务

导读

本文围绕 NemoClaw 仓库 managed-bootstrap/README.md 所定义的managed bootstrap protocol（受管引导协议）展开：它是一条与运行时驱动无关（driver-neutral）的"持有-替换-提交/回滚"事务协议，用于 OpenShell Docker 驱动下 OpenClaw、Hermes、LangChain Deep Agents Code 等受管镜像（managed image）的初始上线（onboarding）与受管重建交接（rebuild handoff）。读完本文你将掌握：随机 bootstrap identity 如何把镜像清单摘要、启动画像指纹、supervisor 参数与运行时收据绑定成不可抵赖的证据链；Docker 适配器如何在不触碰运行中原始负载的前提下完成两阶段 cutover；以及 schema 1/2 旧日志的保守排水（legacy journal drain）规则。

一、协议定位：什么场景走 managed bootstrap，什么场景不走

从 README 引言 可以看到，这套协议不是所有沙箱创建路径的默认动作，而是一个明确圈定的边界：

• 启用路径：使用随仓库发布的 OpenClaw、Hermes、LangChain Deep Agents Code 三个受管镜像，走 OpenShell Docker-driver 的普通上线流程，或者进行受管重建交接（managed rebuild handoff）；
• 不启用路径：可移植（portable）上线、没有受管镜像契约（managed-image contract）的 agent、以及显式--from自定义 Dockerfile 的工作负载，全部保留原有的工作负载路径；
• 明确不支持：生产 provider 注册表中没有 Podman，其引导面（bootstrap surface）处于不支持状态。

这一边界的代码落实在 index.ts 与 runtime-provider/contract.ts 的注册关系上：README 的 "Architectural disposition" 一节明确写出——runtime-provider bundle 是唯一的引导注册边界，生产 Docker bundle 在其中注册 create 路由、替换构造、native 到兼容层的回退证据以及延迟提交/回滚，而中央上线流程只消费这一 provider-neutral 表面，不做 Docker/Podman 分支选择。

二、核心事务模型：一条随机身份绑定整个生命周期

协议把一个随机生成的 bootstrap identity 同时绑定到五类对象（见 README 事务模型）：

1. 期望的受管镜像 manifest digest 与启动画像指纹（startup-profile fingerprint）；
2. Ready 沙箱与不可变运行时收据（immutable runtime receipts）；
3. 捕获的 supervisorargv；
4. 替换运行时、spec 哈希、镜像自有完成收据；
5. 任一阶段失败时的身份绑定回滚收据。

在代码中，identity 是 32 字节随机数的小写十六进制（adapter.ts），由createManagedBootstrapIdentity()生成并经过严格正则校验；环境变量NEMOCLAW_MANAGED_BOOTSTRAP_IDENTITY是其传递载体。ManagedBootstrapExpectedPlan（adapter.ts）正是把 schema 版本、沙箱名、driver id、镜像身份、画像指纹、agent 身份（uid/gid/workdir）、受管状态根、预期 supervisor argv 与元数据打包成一份"计划指纹"（plan fingerprint）的证据结构。

两阶段协调器：先准备、后激活

协调器刻意只暴露两个阶段（README）：

• Preparation（准备）：可以创建并检查一个已停止的替换运行时，但绝不能改动 Ready 状态下正在持有的工作负载；
• Activation（激活）：必须先通过注入的持久化存储（durable store）记录一份完整的、带指纹的 authority 收据，之后 provider 才被允许静默（quiesce）或替换原运行时。

关键的不变量是：provider 的结果只有在被复制进"深度冻结"的协调器 authority 之后才生效。回滚终结收据必须证明"精确恢复了捕获的快照"或"精确确认了工作负载不存在"；提交收据则只证明提交结果，不报告回滚状态，且允许heldWorkloadRemoved为 false——因为 provider 自有清理尚未完成（README）。

createHeldWorkload 的清理边界

一个未完成的createHeldWorkload调用只有在它的launch回调返回了经过校验的 Ready 收据（其中已物化沙箱身份）之后才具备可清理资格（README）：

• 若在拿到收据之前 throw 或提前 return，不允许按计划中的沙箱名触发清理；
• 收据通过校验后，清理请求及其结果都绑定到沙箱 ID（而不是名字）。

对应实现见 prepareManagedBootstrapSequence()：launchCalls计数与isDeepStrictEqual对比确保 provider 只能执行一次且参数完全一致的 launch，normalizeCreateReceipt与normalizeIncompleteCreateCleanupReceipt保证清理严格锚定在物化的沙箱身份上。

三、镜像自有的原生边界：freestanding C 入口点

scripts/managed-bootstrap-entrypoint.c定义了镜像自有的原生边界（README）。OpenClaw、Hermes、LangChain Deep Agents Code 三个镜像定义会把它编译成freestanding Linux amd64/arm64 产物，安装为/usr/local/bin/nemoclaw-managed-bootstrap，其硬性约束是：不能有动态 ELF 解释器、动态段、未定义符号或 C 库启动代码，入口点直接使用 Linux 系统调用。

源码印证：文件头部有#error "Managed bootstrap entrypoint requires a freestanding Linux build."的编译期守卫，并分别在 amd64（syscall指令）与 arm64（svc 0指令）分支用内联汇编实现raw_syscall1/3/5，以nemoclaw_bootstrap_start作为入口标签——没有任何 libc 依赖。

其运行流程是：

1. 把受边界约束的 supervisor 环境拷贝进一个密封的内存文件（sealed in-memory file），把该传输通道保留为文件描述符 9；
2. 以绝对路径调用 Bash，且不带任何启动文件、使用固定的引导环境；
3. 环境值绝不进入 bootstrap argv。

非可执行的 managed-bootstrap-trampoline.sh 因此无法在请求校验之前把 root 动态加载器或 Bash 解释器暴露给环境进程控制。

随后（README）：

• 校验固定且 root 拥有的请求及其身份绑定，验证匹配的完成（completion），为每个应用与校验辅助进程关闭密封传输；
• 通过绝对路径env、仅携带固定 resume 标记与密封描述符，重新进入静态边界；
• 原生 resume 模式校验密封与声明的边界、按字节精确重建环境、把传输标记为 close-on-exec，并且只在最终 supervisor 的execve上应用捕获的环境——从而保留环境顺序、重复赋值、进程控制值与精确的 supervisor 参数边界。

引导的 apply/verify 运行在各自独立的env -i之下，固定环境为：HOME=/root、LANG=C.UTF-8、LC_ALL=C.UTF-8、PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin、NEMOCLAW_MANAGED_IMAGE_CAPABILITY_UNION=1。运行时 provider 负责在激活前把完整的替换进程规格（含 supervisor 环境）绑定到不可变的 prepared authority；原生边界不引入任何 driver 特有的环境策略。

四、Docker 适配层：单调 cutover 日志与受控破坏性切换

Docker 专用层定义了三个构件（README）：私有单调 cutover 日志（monotonic cutover journal）、规范 launch-spec 归一化器、可注入的 provider create 生命周期。生产 Docker runtime bundle 只对受管镜像上线与受管重建交接注册这些表面；可移植上线、非受管 agent、显式自定义 Dockerfile 不会选中它。共享的终结表面则为既有 Docker 兼容路径与启动重建路径扩展回滚所有权。

日志本身是 schema 3 的持久化记录（docker-journal.ts），阶段机是单调的：

staged → cutover → rollback-authorized | bootstrap-complete → openshell-handoff-complete → shared-state-committed （另有 owner-cleanup-required）

记录携带 providerId、agent、沙箱身份、plan/profile 指纹、镜像引用、原始与替换的 runtime ID 与名字（originalName / replacementStagingName / backupName 三个名字）、两个 spec 哈希、回滚目标等字段；日志目录模式 0700、文件模式 0600，单条日志上限 32 KiB，并保留rollback-authorized、shared-state-committed两个决策阶段供恢复仲裁。

Docker 适配器的执行序列

README（L80-L94）给出了完整的时序：

1. 在原始运行时仍运行时，以身份派生出的 staging 名字创建并校验一个已停止的替换运行时；
2. 暂存 0400 权限的 envelope，返回清理权——不静默、不重命名、不改动原始运行时；
3. 协调器把完整 prepared authority 持久化记录之后，激活才把两个完整 runtime ID、三个名字、两个 launch-spec 哈希、镜像身份、画像指纹与沙箱 ID 全部写入日志，然后才进入破坏性 cutover；
4. 后 cutover 回滚先发布rollback-authorized再删除替换；前 cutover 的 staged 清理只删除已准备的替换，不经过该日志迁移；
5. 两个停止的运行时交换名字，provider 按完整 runtime ID 启动精确的替换，OpenShell 在提交前把 supervisor 发布为 Ready；
6. 适配器记录openshell-handoff-complete，然后共享状态才能提交；
7. 替换在终结期间持续运行；提交发布shared-state-committed后才删除备份，并证明同一个替换 supervisor 仍然在线。

终结收据的幂等与持久语义

提交或回滚在异步终结开始前同步认领（claimed）；对已认领结果的重复调用共享同一个 pending 结果，即使第一次终结的确认丢失，相反结果依然非法（README）。其私有状态根保留按版本化、按身份寻址的事务记录（provider 与沙箱身份、plan/profile 指纹、原始与替换 ID、回滚目标、阶段）。提交与清理收据是持久终端记录，因此适配器重建不依赖进程本地事务集或 tombstone 映射。

回滚保留owner-cleanup-required阶段：镜像自有共享状态已恢复、替换已不存在之后，若DockerManagedStartupSharedStateRestoreError报告恢复失败，回滚只能在移除替换后保留同一阶段。两条路径都会把原始运行时恢复到规范名并保持停止，日志保持无终端收据。沙箱服务仍负责destroy，provider 必须证明运行时不存在；未知的运行时在场是"可重试的持久清理失败"，绝不是缺席的证据（README）。

五、镜像自有共享状态事务与遗留日志排水

共享状态事务的身份绑定模型

镜像自有的共享状态事务沿用同一身份绑定模型（README）：提交会原子地把 pending manifest 与备份移入持久收据命名空间，压缩成提交收据，并在重启后拒绝回滚；provider 只有在证明外部回滚备份已消失后才能回收该收据，从而解除下一次引导。解析器只对 schema-v1 且写入于bootstrapIdentity字段引入之前的 manifest 接受遗留 null-identity 路径；额外字段、缺失历史字段、把遗留状态当作身份绑定 authority 呈现，一律拒绝。

回滚前 Docker 适配器会停止替换运行时，通过受保护 host 路径把其可写层提交收据拷入 daemon 卷验证——不可变 helper 无法通过--volumes-from拿到该收据，因为该选项暴露的是卷而非替换的可写层。

Schema 1/2 日志的保守排水

schema 1 与 schema 2 日志体先于持久 agent 身份存在，不能靠猜测可变沙箱名、镜像仓库或后续命令选中的 agent 来升级（README）。恢复时会保留规范记录与任何决策 sidecar，报告 bootstrap/provider/sandbox/原始运行时/替换运行时身份，且只对该沙箱名设 fence；对另一个沙箱的 create 在告警后可继续。

遇到这类记录时的标准处置流程：

1. 停止该命名沙箱的上线，保存完整诊断，备份规范状态根下managed-bootstrap/<bootstrap-identity>.json与相邻决策 sidecar，不编辑任一记录；
2. 通过 owning provider 检查报告出的完整 runtime ID——沙箱名与容器名只作诊断文本，绝不按名字删除、重命名或收养运行时，也绝不把当前调用的 agent 身份复制进旧记录；
3. 只要任一运行时在场或无法证明缺席，就保留日志，用那些不可变 ID 恢复 provider 自有事务；遗留 cutover 决策可能比日志体阶段更新，日志体本身绝不授权提交或回滚；
4. 两个运行时都证明缺席时仍保留日志与镜像自有共享状态证据，把缺席证明记录在案，等待身份校验的退役路径（identity-checked retirement path）落地后再处理。

六、恢复语义与协调器 authority 边界

恢复路径的要点（README）：

• 直接身份查找重建一条已知事务记录；受管 create-lifecycle 启动则用未完成记录枚举，让选中的 provider 在新沙箱 create 开始前调和每条身份寻址记录；
• Docker provider 单调恢复持久阶段：staged 工作回滚而不进入 cutover；cutover 工作跟随已被证明的镜像自有提交前进或持久授权回滚；bootstrap-complete 工作校验持久沙箱 ID，仅当其阶段可重连时才等待；
• 由于 OpenShell 的公开 start 操作是按名字索引的，恢复对已停止沙箱失败关闭（fail closed），直到经独立验证的操作员 start 使其可重连；绝不会启动可变沙箱名；
• 恢复持久化身份绑定终结收据后才移除活动日志，跨再次中断幂等；先枚举持久身份再加载每条记录，使一条不可读事务不会隐藏其他结果；
• provider 返回有界的{ receipts, failures }证据，协调器校验、复制、冻结并排序两个数组，不按 provider 阶段或失败码路由；
• 对请求沙箱名的失败、或无法证明沙箱身份的失败会阻塞 create；对另一沙箱的失败只告警并保留，不阻塞请求的 create；
• 代码读取可变 OpenShell 名字仅为检测所有权复用，不安全的仅名字删除返回类型化保留错误；Docker 变更使用先前已记日志的完整容器 ID（其身份不可重绑），静默后重新 inspect 同一 ID。

多进程租约/仲裁（multi-process lease/arbitration）仍是显式的生产激活门槛，激活还必须注入所选 gateway 的规范状态根。

七、Docker 与休眠 Podman 候选的边界划分

休眠 Podman 候选（README）保持同一 provider-neutral 协调器边界，但引擎特有权在内部：绑定一个 operation-scoped 的 Podman 命令适配器到 rootless 端点，两次捕获一个 held OpenShell 工作负载，并在任何 cutover 前持久租用 watcher owner。准备阶段创建并证明一个已停止、带 final 标签的替换及私有受管状态卷，同时保留原始运行时；日志在下一个外部效果之前记录每个变更边界，并保留足够不可变身份以在不按名字删除的情况下回滚。镜像引导只接受该 prepared authority：暂存一个受保护的 root-apply envelope，启动替换，并为 OpenClaw/Hermes/LangChain Deep Agents Code 认证镜像自有完成。

这些模块刻意不进入生产 provider 注册表，无法被 stock Docker 受管镜像路径选中；单元测试隔离地演练休眠 Podman 引导组件。README 同时给出后续切片清单：持久化引擎恢复、GPU 与本地推理、安装器覆盖、受保护 E2E 资质验证、以及被接受的产品激活。

八、测试与证据：可执行的、有界的地基

README 的 "Architectural disposition"（L212-L232）强调这是"可执行的、有界的地基，而非未经测试的占位实现"：

• adapter.test.ts 通过一个 MXC 命名的 fake driver，为 OpenClaw、Hermes、LangChain Deep Agents Code 驱动 prepare、持久记录、激活、终结与失败回滚；
• runtime-provider-contract.test.ts 通过同一 provider bundle 契约验证生产 Docker 注册与 MXC 风格引导面；
• 同一目录下还有针对日志（docker-journal.test.ts）、恢复（docker-recovery.test.ts）、共享状态（docker-shared-state.test.ts）、envelope（envelope.test.ts）、authority store、handoff identity、spec 归一化以及各 Podman 组件的独立测试。

依赖方向是单向的：managed-bootstrap 组合导入 managed-startup，而 managed-startup不导入 managed-bootstrap（README）。镜像运行时组合受管启动 API 与消费受保护引导 envelope 的模式、把共享状态 authority 绑定到尝试、发布身份绑定完成并连同普通启动交接一起认证；envelope 在应用与完成发布期间被保留，使同一尝试可在中断后重试，应用前原子地把已认证 inode 移入 root 私有、同文件系统的认领路径。

九、镜像内协议假设与失败关闭语义

协议明确声明其假设（README）：OCI 可写层支持同设备原子 rename 与硬链接；生产者只写规范请求路径；同一时刻只有一个引导消费者拥有该路径；容器 uid 0 可信。不支持的跨设备 rename 或硬链接会在应用前失败关闭并保留请求数据；协议不声称能抵御可篡改私有 mode-0700 命名空间的主机 root 进程。请求数据从不进入 bootstrap argv 或引导 helper 环境，只在长生命周期 supervisor 处恢复——这是整个原生边界最核心的安全不变量。

十、快速对照：核心文件索引

结语

managed bootstrap protocol 本质上是把"替换运行中的沙箱运行时"这一高风险操作，改造成一条身份绑定、阶段单调、收据可持久证明的事务：准备阶段不动原始负载，激活阶段先落盘 authority 再进入破坏性 cutover，终结收据与恢复路径全部以不可变 runtime ID 与 bootstrap identity 为锚，彻底规避了按名字猜测、按名字收养、按名字删除带来的歧义。对希望为 OpenShell 沙箱上线与重建交接引入更强安全边界的开发者而言，本目录的 README、协调器与 Docker 适配器实现，加上三 agent 的 MXC 契约测试，是一份可以直接研读和借鉴的可执行参考。