@namewta/speculo 1.0.12 → 1.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Workflow-packaged AI collaboration assets with state-safe refresh tooling.",
   "type": "module",
   "bin": {

package/template/workflows/ops/H-host-manage/H-host-manage.md

@@ -19,6 +19,9 @@ keywords: [ops, host-manage, 主机, 持久化, 审批]
 
 指定 local 或 SSH 的稳定 host_id；读取最近盘点与有限问题证据。初次 SSH 用用户已验证的 known_hosts，identity=discover 只允许只读探测；把返回身份明确登记后才允许计划和执行。
 
+Linux SSH 目标若没有 Node：必须先 `ops.mjs bootstrap-node`（控制端校验已审核 tar 的 SHA256，scp 到目标，远端 POSIX 展开固定 Volta/Node），禁止把 POSIX 盘点只写在对话里。引导成功后必须 `ops.mjs enroll`（或 `register` 再 `probe --host`），`hosts/{host_id}/inventory/snapshot-*.json` 与 `status.json.hosts` 是完成标准的一部分。引导是 ops.mjs 第一阶段通道，需要明文 ack 与 SHA256，不走 plan/approve；已有 Node 的目标不重复安装、不改 `.bashrc`/`.profile`。缺 Node 只能阻塞 apply，不能阻塞登记。本轮仅 Linux SSH；Windows/macOS 仍要求目标已有 Node。
+
+
 区分系统版本、用户默认、项目 pin、服务环境。environment-spec 支持明确版本的 uv、Volta、SDKMAN 管理配方；管理器缺失先用经过审核的安装器。保留旧默认与旧目录，不能为统一外观先删除旧环境。工作流不擅自改写用户 shell profile；激活新管理器入口是另一个明确的准备动作。
 
 Docker 缺失使用经审核且版本固定的 Linux Engine 安装配方，完成服务、Compose、data-root、账号权限验证之后才进入 D。既有 data-root 不匹配时单独备份、停机、迁移、验证，不把 /var/lib/docker 直接 mv 当作安装步骤。镜像源按可信清单、样本哈希和目标网络测试，切换配置仍需批准。

package/template/workflows/ops/INDEX.md

@@ -24,7 +24,7 @@ keywords: [ops, 主机, SSH, 部署, Docker, 持久化, 公共服务, 运维]
 ## Work 激活
 
 I-initialize：控制端初始化。
-H-host-manage：本地或远程主机的环境、诊断、清理和维护。
+H-host-manage：本地或远程主机的环境、诊断、清理和维护。Linux SSH 目标无 Node 时先走 USAGE 中的 `bootstrap-node` 再 `enroll`，盘点必须写入 `hosts/`。
 D-project-deploy：业务 APP 与公共服务部署、复用、更新、停止及显式迁移。
 
 三个入口都使用 plan → approve → apply → verify → dual-documents；不得自动激活额外旧 Work。

package/template/workflows/ops/README.md

@@ -89,7 +89,7 @@ init/register/credential-put 是用户显式请求的部署机本地记录操作
 
 ## 阅读与操作入口
 
-详细命令和可运行演练：`<Path>{roots.workflows}/ops/common/USAGE.md</Path>`。
+详细命令和可运行演练：`<Path>{roots.workflows}/ops/common/USAGE.md</Path>`。Linux SSH 缺 Node 的固定 Volta 引导见 USAGE §1。
 数据与账户：`<Path>{roots.workflows}/ops/common/rules/persistence-and-secrets.md</Path>`。
 共享服务：`<Path>{roots.workflows}/ops/common/rules/shared-services.md</Path>`。
 恢复：`<Path>{roots.workflows}/ops/common/rules/recovery.md</Path>`。

package/template/workflows/ops/common/CAPABILITIES.md

@@ -6,12 +6,12 @@
 |---|---|---|
 | 控制端 | Node 标准库 CLI（ops.mjs）；状态、锁、明文、计划、执行 | 无第三方 npm 包；控制端可本地执行完整闭环 |
 | Linux local | 原生 oneshot；systemd 配置/权限/健康门；Docker Engine Compose | 本轮隔离 local oneshot 演练；systemd/Docker 需要真实有权限主机验收 |
-| SSH | OpenSSH 密钥或 agent；固定 known_hosts；目标身份；可 sudo -n | 目标 Node；本轮没有远程主机/ssh 客户端实机验证；不实现交互式 SSH 密码登录 |
+| SSH | OpenSSH 密钥或 agent；固定 known_hosts；目标身份；可 sudo -n；Linux 目标无 Node 时可走固定 Volta 引导 | 目标无 Node 时 Linux SSH 可走固定 Volta/Node 引导（pin 见 common/toolchains/volta-linux.json）；Windows 仍要求已有 Node。本轮没有远程主机/ssh 客户端实机验证，由模拟 SSH/scp 覆盖；不实现交互式 SSH 密码登录 |
 | Windows 原生 | PowerShell 引导、路径/DACL、同账户登录态 Scheduled Task | 不是无人登录的 Windows Service；真正后台服务需专用 adapter；本轮非 Windows 实机 |
 | WSL | 单独登记为 Linux 执行目标 | 不把 Windows 主机路径/Docker Desktop VM 当作 WSL 根 |
 | macOS | 身份探测、POSIX 路径、oneshot | 无 launchd 适配；不是承诺全部平台常驻部署 |
 | Compose | JSON-as-YAML、显式 context/project、raw env_file、digest image、bind 与 VOLUME检查 | 要求 Compose >=2.30；strict Engine data-root；Docker Desktop 不自动迁移 |
-| uv/Volta/SDKMAN | 明确版本准备与原默认保留配方；命令/默认验证 | 管理器安装包必须可信固定；旧 profile 不自动改写；项目真实兼容性另验 |
+| uv/Volta/SDKMAN | 明确版本准备与原默认保留配方；命令/默认验证；Volta 本体 + 固定 Node 镜像可由 Linux SSH `bootstrap-node` 安装 | 管理器安装包必须可信固定；旧 profile 不自动改写；项目真实兼容性另验 |
 | 共享服务 | MySQL/Redis/MinIO 分配、existing 验证、owner/binding/依赖排序 | 无本轮数据库实机；未知产品须真实版本适配；没有万能数据库备份/恢复 |
 | 升级/回滚/迁移 | 新 spec、固定版本、显式主机操作、跨机排序、逐步回执 | 没有隐式停机零损失承诺；没有自动生成任意项目迁移脚本 |
 | 清理 | 只读诊断、cache/log 隔离、精确回执受控 purge | 不普遍删除 Windows/Linux 任意系统垃圾；不 drop_caches 或 prune volume |

package/template/workflows/ops/common/USAGE.md

@@ -10,9 +10,28 @@ node /path/to/ops/common/tools/ops.mjs --state /path/to/.speculo/ops init --cont
 node /path/to/ops/common/tools/ops.mjs probe --output /safe/path/local-inventory.json
 ```
 
-没有 Node 时运行 common/tools/bootstrap.sh probe 或 bootstrap.ps1 -Probe，只做检测。经过批准的本地安装器还需精确 SHA256 与确认字符串。完成后重新 init。
+没有 Node 时运行 common/tools/bootstrap.sh probe 或 bootstrap.ps1 -Probe，只做检测。经过批准的本地安装器还需精确 SHA256 与确认字符串。完成后重新 init。SSH 目标缺 Node 不要对本机 bootstrap.sh 假装能装远端，改走下面的 `bootstrap-node`。
+
+初次远端将 host.json 中 identity 写为 discover（仅 probe 支持），connection 包含 hostname、username、known_hosts，可选 port、identity_file、sudo、shell。known_hosts 必须已经通过可信方式核对，不能自动信任 ssh-keyscan 输出。目标还没有 Node 时不要填一个 PATH 上的 `node` 然后把盘点留在对话里：
+
+```sh
+node /path/to/ops/common/tools/ops.mjs bootstrap-node --connection-file /safe/path/host-discovery.json --probe
+# 若 tools.node=missing，准备已审核的 volta/node tar（SHA256 见 common/toolchains/volta-linux.json），再：
+node /path/to/ops/common/tools/ops.mjs --state /path/to/.speculo/ops bootstrap-node --apply \
+  --connection-file /safe/path/host-discovery.json --host-id node-a --account ops --host-root /srv/ops \
+  --volta-archive /safe/volta-2.0.2-linux.tar.gz --volta-sha256 PINNED \
+  --node-archive /safe/node-v24.21.0-linux-x64.tar.gz --node-sha256 PINNED \
+  --ack I-APPROVE-THIS-BOOTSTRAP
+```
+
+引导把 `VOLTA_HOME` 放在 `{host.root}/_host/toolchains/{account}/volta`，`connection.node` 指向其中的 `bin/ops-node`（导出 VOLTA_HOME 后 exec 真实 Node），不改 `.bashrc`/`.profile`，不跑官方 `install.sh`。已有 Node 则 `skipped-existing-node`，原默认不动。随后必须落盘：
+
+```sh
+node /path/to/ops/common/tools/ops.mjs --state /path/to/.speculo/ops enroll --file /safe/path/register.json
+```
+
+`enroll` 接受 `identity=discover` 与引导返回的绝对 `connection.node`，写入 `status.json` 与 `hosts/{host_id}/inventory/snapshot-*.json`。单独 `probe --connection-file` 仍只打印 JSON，下一步必须 enroll（或 register + `probe --host`）。
 
-初次远端将 host.json 中 identity 写为 discover（仅 probe 支持），connection 包含 hostname、username、known_hosts、node，可选 port、identity_file、sudo、shell。known_hosts 必须已经通过可信方式核对，不能自动信任 ssh-keyscan 输出。
 
 ```sh
 node /path/to/ops/common/tools/ops.mjs probe --connection-file /safe/path/host-discovery.json --output /safe/path/host-observed.json
@@ -63,7 +82,7 @@ node /path/to/ops/common/tools/ops.mjs --state /path/to/.speculo/ops environment
 node /path/to/ops/common/tools/ops.mjs --state /path/to/.speculo/ops mirror-probe --host node-a --file /safe/path/mirror-candidates.json --allow-network
 ```
 
-环境配方不抓 latest；管理器缺失先明确准备安装器。来源测速不修改配置，证书/哈希失败候选不使用，真实配置更换通过 H 的精确 write-file/write-control/命令计划。不能将 Python/npm/Docker/Maven 镜像混为一套规则。
+环境配方不抓 latest；管理器缺失先明确准备安装器。Linux SSH 上 Volta 本体与固定 Node 镜像用 `bootstrap-node`，不要指望 environment-spec 自己装 Volta。来源测速不修改配置，证书/哈希失败候选不使用，真实配置更换通过 H 的精确 write-file/write-control/命令计划。不能将 Python/npm/Docker/Maven 镜像混为一套规则。
 
 H.host_actions 支持 mkdir、write-file（host.root 内相对路径；不得写生成器负责的 README/DEPLOYMENTS/knowledge 账本）、write-control（精确系统控制文件：内置 docker daemon.json 与 ops-*.service，以及经理由/回滚/验证声明的 nginx、wireguard、非 ops- 前缀单元）、install-toolchain（明确写集/原默认/验证）、command（明确写集/验证）、defaults、quarantine、purge-quarantine。系统软件包安装使用明确批准的可信安装脚本，不自动猜当前发行版安装命令；Docker 示例见 service-profiles/docker-engine.md。主机级入口用 resource_updates.hosts[].host_services 与 spec.public_ingress 入账，不要为 Nginx/WireGuard 伪造 APP 部署。
 
@@ -105,7 +124,7 @@ node /path/to/ops/common/tools/ops.mjs --state /path/to/new-ops-state import-leg
 
 ```sh
 node /path/to/ops/common/tools/demo-local.mjs --output /absolute/empty/demo-root
-node --test /path/to/ops/common/tests/test_ops.mjs
+node --test /path/to/ops/common/tests/test_ops.mjs /path/to/ops/common/tests/test_ops_bootstrap.mjs
 node /path/to/ops/common/tools/validate-ops.mjs --self-check
 ```
 

package/template/workflows/ops/common/examples/register.example.json

@@ -12,7 +12,7 @@
         "username": "ops",
         "port": 22,
         "known_hosts": "/REPLACE/known_hosts",
-        "node": "node",
+        "node": "/srv/ops/_host/toolchains/ops/volta/bin/ops-node",
         "sudo": true
       }
     }

package/template/workflows/ops/common/tests/test_ops_bootstrap.mjs

@@ -0,0 +1,522 @@
+/** Node-less Linux SSH bootstrap/enroll contracts. SSH/scp are simulated; no public network. */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+import { createHash } from "node:crypto";
+import * as core from "../tools/opslib/core.mjs";
+import * as transport from "../tools/opslib/transport.mjs";
+import * as recipes from "../tools/opslib/host_recipes.mjs";
+import * as bootstrap from "../tools/opslib/bootstrap.mjs";
+import { initialize, main, cliHooks } from "../tools/opslib/cli.mjs";
+import * as agent from "../tools/opslib/agent.mjs";
+import * as model from "../tools/opslib/model.mjs";
+
+const toolsDir = join(dirname(fileURLToPath(import.meta.url)), "../tools");
+const scriptPath = join(toolsDir, "bootstrap-volta.sh");
+const ACK = "I-APPROVE-THIS-BOOTSTRAP";
+
+function sha256(p) {
+  return createHash("sha256").update(readFileSync(p)).digest("hex");
+}
+
+function splitRemote(cmd) {
+  return String(cmd).match(/(?:'[^']*'|\S)+/g).map((s) => (s.startsWith("'") ? s.slice(1, -1).replace(/'"'"'/g, "'") : s));
+}
+
+function makeArchives(dir, nodeVersion = "24.21.0") {
+  const voltaSrc = join(dir, "volta-src");
+  mkdirSync(voltaSrc, { recursive: true });
+  writeFileSync(join(voltaSrc, "volta"), "#!/bin/sh\necho 2.0.2\n", { mode: 0o755 });
+  writeFileSync(join(voltaSrc, "volta-shim"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+  writeFileSync(join(voltaSrc, "install.sh"), "#!/bin/sh\necho SHOULD-NOT-RUN >&2; echo PROFILE_EDIT >> \"$HOME/.bashrc\"; exit 1\n", { mode: 0o755 });
+  const voltaTar = join(dir, "volta-2.0.2-linux.tar.gz");
+  const t1 = spawnSync("tar", ["-czf", voltaTar, "-C", voltaSrc, "volta", "volta-shim", "install.sh"], { encoding: "utf8" });
+  assert.equal(t1.status, 0, t1.stderr);
+
+  const top = `node-v${nodeVersion}-linux-x64`;
+  const nodeRoot = join(dir, top);
+  mkdirSync(join(nodeRoot, "bin"), { recursive: true });
+  writeFileSync(join(nodeRoot, "bin", "node"), `#!/bin/sh
+if [ "$1" = "--version" ]; then echo v${nodeVersion}; exit 0; fi
+exec ${JSON.stringify(process.execPath)} "$@"
+`, { mode: 0o755 });
+  const nodeTar = join(dir, `${top}.tar.gz`);
+  const t2 = spawnSync("tar", ["-czf", nodeTar, "-C", dir, top], { encoding: "utf8" });
+  assert.equal(t2.status, 0, t2.stderr);
+  return { voltaTar, nodeTar, voltaSha: sha256(voltaTar), nodeSha: sha256(nodeTar), nodeVersion };
+}
+
+function pinFor(archives, arch = "linux-x64") {
+  const base = bootstrap.loadVoltaPin();
+  const slot = { ...base.archives[arch] };
+  slot.volta = { ...slot.volta, sha256: archives.voltaSha };
+  slot.node = { ...slot.node, sha256: archives.nodeSha };
+  return { ...base, archives: { ...base.archives, [arch]: slot } };
+}
+
+function mockTransport({ probeJson = null } = {}) {
+  const prev = transport.transportHooks.spawnSync;
+  const log = [];
+  transport.transportHooks.spawnSync = (cmd, args, kw) => {
+    log.push({ cmd, args: [...args], encoding: kw.encoding, inputIsBuffer: Buffer.isBuffer(kw.input) });
+    const last = args[args.length - 1];
+    if (cmd === "scp") {
+      const local = args[args.length - 2];
+      const spec = args[args.length - 1];
+      const remotePath = spec.slice(spec.indexOf(":") + 1);
+      mkdirSync(dirname(remotePath), { recursive: true });
+      copyFileSync(local, remotePath);
+      return { status: 0, stdout: Buffer.alloc(0), stderr: Buffer.alloc(0) };
+    }
+    if (cmd === "ssh") {
+      assert.ok(args.includes("BatchMode=yes"));
+      assert.ok(args.includes("StrictHostKeyChecking=yes"));
+      assert.ok(args.some((a) => String(a).startsWith("UserKnownHostsFile=")));
+      if (probeJson && String(last).includes("--probe")) {
+        return { status: 0, stdout: Buffer.from(JSON.stringify(probeJson) + "\n"), stderr: Buffer.alloc(0) };
+      }
+      if (String(last).includes("--input-type=module")) {
+        const parts = splitRemote(last);
+        return spawnSync(parts[0], parts.slice(1), {
+          input: kw.input, encoding: "buffer", timeout: kw.timeout, maxBuffer: kw.maxBuffer,
+        });
+      }
+      const parts = splitRemote(last);
+      return spawnSync(parts[0], parts.slice(1), {
+        input: kw.input, encoding: "buffer", timeout: kw.timeout, maxBuffer: kw.maxBuffer,
+        env: { ...process.env, HOME: kw.HOME || process.env.HOME },
+      });
+    }
+    return prev(cmd, args, kw);
+  };
+  return { log, restore() { transport.transportHooks.spawnSync = prev; } };
+}
+
+function captureMain(argv) {
+  const out = [];
+  const err = [];
+  const wo = process.stdout.write;
+  const we = process.stderr.write;
+  process.stdout.write = (c) => { out.push(String(c)); return true; };
+  process.stderr.write = (c) => { err.push(String(c)); return true; };
+  try {
+    const code = main(argv);
+    return { code, stdout: out.join(""), stderr: err.join("") };
+  } finally {
+    process.stdout.write = wo;
+    process.stderr.write = we;
+  }
+}
+
+function sshHost({ root, kh, node = "/usr/bin/node", identity = "discover" }) {
+  return {
+    host_id: "wsl-a",
+    display_name: "WSL fixture",
+    platform: "linux",
+    transport: "ssh",
+    root,
+    identity,
+    connection: {
+      hostname: "host.invalid",
+      username: "ops",
+      known_hosts: kh,
+      node,
+    },
+  };
+}
+
+function writeConn(dir, host) {
+  const p = join(dir, "conn.json");
+  writeFileSync(p, JSON.stringify(host, null, 2));
+  return p;
+}
+
+test("posix ssh uses the same host-key contract", () => {
+  const d = mkdtempSync(join(tmpdir(), "ops-posix-"));
+  const kh = join(d, "known_hosts");
+  writeFileSync(kh, "fixture pinned key\n");
+  const captured = {};
+  const prev = transport.transportHooks.spawnSync;
+  transport.transportHooks.spawnSync = (cmd, args, kw) => {
+    captured.argv = [cmd, ...args];
+    Object.assign(captured, kw);
+    return { status: 0, stdout: '{"status":"probed"}', stderr: "" };
+  };
+  try {
+    transport.posixCall({ hostname: "host.invalid", username: "ops", known_hosts: kh }, "#!/bin/sh\necho ok\n", { args: ["--probe"] });
+    assert.equal(captured.argv[0], "ssh");
+    assert.ok(captured.argv.includes("BatchMode=yes"));
+    assert.ok(captured.argv.includes("StrictHostKeyChecking=yes"));
+    assert.ok(captured.argv.includes("UserKnownHostsFile=" + kh));
+    assert.ok(captured.argv.includes("/bin/sh -s -- --probe") || captured.argv.at(-1).includes("/bin/sh"));
+    assert.ok(!String(captured.argv.at(-1)).includes("--input-type=module"));
+    assert.ok(Buffer.isBuffer(captured.input));
+  } finally { transport.transportHooks.spawnSync = prev; rmSync(d, { recursive: true, force: true }); }
+});
+
+test("scp uses the same host-key contract", () => {
+  const d = mkdtempSync(join(tmpdir(), "ops-scp-"));
+  const kh = join(d, "known_hosts");
+  writeFileSync(kh, "fixture pinned key\n");
+  const local = join(d, "a.tar.gz");
+  writeFileSync(local, "x");
+  const captured = {};
+  const prev = transport.transportHooks.spawnSync;
+  transport.transportHooks.spawnSync = (cmd, args, kw) => {
+    captured.argv = [cmd, ...args];
+    Object.assign(captured, kw);
+    return { status: 0, stdout: "", stderr: "" };
+  };
+  try {
+    transport.posixSend({ hostname: "host.invalid", username: "ops", known_hosts: kh }, local, "/srv/ops/_host/installers/a.tar.gz");
+    assert.equal(captured.argv[0], "scp");
+    assert.ok(captured.argv.includes("BatchMode=yes"));
+    assert.ok(captured.argv.includes("StrictHostKeyChecking=yes"));
+    assert.ok(captured.argv.includes("UserKnownHostsFile=" + kh));
+    assert.ok(captured.argv.includes("-P"));
+    assert.ok(!captured.argv.includes("-T"));
+  } finally { transport.transportHooks.spawnSync = prev; rmSync(d, { recursive: true, force: true }); }
+});
+
+test("bootstrap-volta apply installs wrapper and does not touch profile", () => {
+  const d = mkdtempSync(join(tmpdir(), "ops-vol-"));
+  const home = join(d, "home");
+  mkdirSync(home);
+  const bashrc = join(home, ".bashrc");
+  writeFileSync(bashrc, "keep-me\n");
+  const archives = makeArchives(d);
+  const voltaHome = join(d, "srv", "ops", "_host", "toolchains", "ops", "volta");
+  const p = spawnSync("/bin/sh", [scriptPath, "--apply", archives.voltaTar, archives.voltaSha, archives.nodeTar, archives.nodeSha, voltaHome, archives.nodeVersion, ACK], {
+    encoding: "utf8", env: { ...process.env, HOME: home },
+  });
+  try {
+    assert.equal(p.status, 0, p.stderr + p.stdout);
+    const result = JSON.parse(p.stdout.trim().split("\n").at(-1));
+    assert.equal(result.profile_unchanged, true);
+    assert.ok(result.connection_node.endsWith("/volta/bin/ops-node"));
+    assert.equal(readFileSync(bashrc, "utf8"), "keep-me\n");
+    const ver = spawnSync(result.connection_node, ["--version"], { encoding: "utf8", env: { ...process.env, HOME: home } });
+    assert.equal(ver.stdout.trim(), "v24.21.0");
+    assert.ok(!existsSync(join(voltaHome, "install.sh")) || readFileSync(join(home, ".bashrc"), "utf8") === "keep-me\n");
+  } finally { rmSync(d, { recursive: true, force: true }); }
+});
+
+test("bootstrap-volta apply without ack blocked", () => {
+  const d = mkdtempSync(join(tmpdir(), "ops-ack-"));
+  const archives = makeArchives(d);
+  const p = spawnSync("/bin/sh", [scriptPath, "--apply", archives.voltaTar, archives.voltaSha, archives.nodeTar, archives.nodeSha, join(d, "volta"), "24.21.0", "nope"], { encoding: "utf8" });
+  assert.notEqual(p.status, 0);
+  rmSync(d, { recursive: true, force: true });
+});
+
+test("bootstrap-volta sha mismatch blocked", () => {
+  const d = mkdtempSync(join(tmpdir(), "ops-sha-"));
+  const archives = makeArchives(d);
+  const p = spawnSync("/bin/sh", [scriptPath, "--apply", archives.voltaTar, "0".repeat(64), archives.nodeTar, archives.nodeSha, join(d, "volta"), "24.21.0", ACK], { encoding: "utf8" });
+  assert.notEqual(p.status, 0);
+  assert.ok(!existsSync(join(d, "volta", "bin", "ops-node")));
+  rmSync(d, { recursive: true, force: true });
+});
+
+function cliFixture() {
+  const tmp = mkdtempSync(join(tmpdir(), "ops-bootcli-"));
+  const state = join(tmp, "controller");
+  const target = join(tmp, "server");
+  mkdirSync(target, { recursive: true });
+  const kh = join(tmp, "known_hosts");
+  writeFileSync(kh, "fixture pinned key\n");
+  const prevProbe = cliHooks.probeLocal;
+  cliHooks.probeLocal = () => ({ identity: agent.fingerprint(), scope: "mock" });
+  initialize(state, "control-a");
+  cliHooks.probeLocal = prevProbe;
+  const archives = makeArchives(tmp);
+  const prevPin = bootstrap.bootstrapHooks.loadPin;
+  bootstrap.bootstrapHooks.loadPin = () => pinFor(archives);
+  return {
+    tmp, state, target, kh, archives,
+    cleanup() {
+      bootstrap.bootstrapHooks.loadPin = prevPin;
+      rmSync(tmp, { recursive: true, force: true });
+    },
+  };
+}
+
+const missingProbe = {
+  status: "probed", uname: "Linux x86_64", arch: "linux-x64",
+  tools: { node: "missing", volta: "missing", tar: "/bin/tar", sha256sum: "/usr/bin/sha256sum" },
+  node_path: null, node_version: null, node_usable: false, profile_has_volta: false,
+};
+
+test("discover probe without node returns node-missing", () => {
+  const fx = cliFixture();
+  const mock = mockTransport({ probeJson: missingProbe });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" });
+    const conn = writeConn(fx.tmp, host);
+    const r = captureMain(["probe", "--connection-file", conn]);
+    assert.equal(r.code, 2);
+    const payload = JSON.parse(r.stderr);
+    assert.equal(payload.status, "blocked");
+    assert.equal(payload.error, "node-missing");
+    assert.ok(String(payload.next).includes("bootstrap-node"));
+    assert.ok(!existsSync(join(fx.state, "hosts", "wsl-a")));
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
+test("bootstrap-node probe is read-only", () => {
+  const fx = cliFixture();
+  const mock = mockTransport({ probeJson: missingProbe });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" });
+    const conn = writeConn(fx.tmp, host);
+    const r = captureMain(["bootstrap-node", "--connection-file", conn, "--probe"]);
+    assert.equal(r.code, 0, r.stderr);
+    const payload = JSON.parse(r.stdout);
+    assert.equal(payload.status, "probed");
+    assert.equal(payload.posix.tools.node, "missing");
+    assert.ok(!mock.log.some((e) => e.cmd === "scp"));
+    assert.ok(!mock.log.some((e) => String(e.args.at(-1) || "").includes("--apply")));
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
+test("bootstrap-node apply without ack blocked", () => {
+  const fx = cliFixture();
+  const mock = mockTransport({ probeJson: missingProbe });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" });
+    const conn = writeConn(fx.tmp, host);
+    const r = captureMain([
+      "bootstrap-node", "--connection-file", conn, "--apply",
+      "--account", "ops", "--host-root", fx.target,
+      "--volta-archive", fx.archives.voltaTar, "--volta-sha256", fx.archives.voltaSha,
+      "--node-archive", fx.archives.nodeTar, "--node-sha256", fx.archives.nodeSha,
+    ]);
+    assert.equal(r.code, 2);
+    assert.ok(r.stderr.includes("I-APPROVE-THIS-BOOTSTRAP"));
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
+test("bootstrap-node sha mismatch blocked", () => {
+  const fx = cliFixture();
+  const mock = mockTransport({ probeJson: missingProbe });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" });
+    const conn = writeConn(fx.tmp, host);
+    const r = captureMain([
+      "bootstrap-node", "--connection-file", conn, "--apply",
+      "--account", "ops", "--host-root", fx.target, "--ack", ACK,
+      "--volta-archive", fx.archives.voltaTar, "--volta-sha256", "0".repeat(64),
+      "--node-archive", fx.archives.nodeTar, "--node-sha256", fx.archives.nodeSha,
+    ]);
+    assert.equal(r.code, 2);
+    assert.ok(!mock.log.some((e) => String(e.args.at(-1) || "").includes("--apply")));
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
+test("latest and curl-pipe names rejected", () => {
+  const fx = cliFixture();
+  const mock = mockTransport({ probeJson: missingProbe });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" });
+    const conn = writeConn(fx.tmp, host);
+    const r = captureMain([
+      "bootstrap-node", "--connection-file", conn, "--apply",
+      "--account", "ops", "--host-root", fx.target, "--ack", ACK,
+      "--node-version", "latest",
+      "--volta-archive", fx.archives.voltaTar, "--volta-sha256", fx.archives.voltaSha,
+      "--node-archive", fx.archives.nodeTar, "--node-sha256", fx.archives.nodeSha,
+    ]);
+    assert.equal(r.code, 2);
+    assert.match(r.stderr, /latest/i);
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
+test("bootstrap-node skips when node exists", () => {
+  const fx = cliFixture();
+  const mock = mockTransport({
+    probeJson: {
+      ...missingProbe,
+      tools: { ...missingProbe.tools, node: "/usr/bin/node" },
+      node_path: "/usr/bin/node",
+      node_usable: true,
+      node_version: "v22.22.3",
+    },
+  });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "/usr/bin/node" });
+    const conn = writeConn(fx.tmp, host);
+    const r = captureMain([
+      "bootstrap-node", "--connection-file", conn, "--apply",
+      "--account", "ops", "--host-root", fx.target, "--ack", ACK,
+      "--volta-archive", fx.archives.voltaTar, "--volta-sha256", fx.archives.voltaSha,
+      "--node-archive", fx.archives.nodeTar, "--node-sha256", fx.archives.nodeSha,
+    ]);
+    assert.equal(r.code, 0, r.stderr);
+    const payload = JSON.parse(r.stdout);
+    assert.equal(payload.status, "skipped-existing-node");
+    assert.ok(!mock.log.some((e) => e.cmd === "scp"));
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
+test("bootstrap-node apply then enroll writes inventory and status", () => {
+  const fx = cliFixture();
+  const home = join(fx.tmp, "home");
+  mkdirSync(home);
+  writeFileSync(join(home, ".bashrc"), "keep-me\n");
+  const prevHome = process.env.HOME;
+  process.env.HOME = home;
+  const mock = mockTransport({ probeJson: missingProbe });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" });
+    const conn = writeConn(fx.tmp, host);
+    const applied = captureMain([
+      "bootstrap-node", "--state", fx.state, "--host-id", "wsl-a",
+      "--connection-file", conn, "--apply",
+      "--account", "ops", "--host-root", fx.target, "--ack", ACK,
+      "--volta-archive", fx.archives.voltaTar, "--volta-sha256", fx.archives.voltaSha,
+      "--node-archive", fx.archives.nodeTar, "--node-sha256", fx.archives.nodeSha,
+    ]);
+    assert.equal(applied.code, 0, applied.stderr);
+    const boot = JSON.parse(applied.stdout);
+    assert.equal(boot.status, "installed");
+    assert.ok(boot.connection_node.endsWith("/ops-node"));
+    assert.equal(readFileSync(join(home, ".bashrc"), "utf8"), "keep-me\n");
+    assert.ok(existsSync(join(fx.state, "hosts", "wsl-a", "bootstrap")));
+    const statusBefore = model.load(fx.state);
+    assert.ok(!statusBefore.hosts["wsl-a"]);
+
+    host.connection.node = boot.connection_node;
+    host.identity = "discover";
+    const enrollFile = join(fx.tmp, "register.json");
+    writeFileSync(enrollFile, JSON.stringify({ hosts: [host], projects: [] }));
+    mock.restore();
+    const enrollMock = mockTransport({
+      probeJson: { ...missingProbe, tools: { ...missingProbe.tools, node: boot.connection_node }, node_path: boot.connection_node, node_usable: true },
+    });
+    try {
+      const enrolled = captureMain(["--state", fx.state, "enroll", "--file", enrollFile]);
+      assert.equal(enrolled.code, 0, enrolled.stderr + enrolled.stdout);
+      const result = JSON.parse(enrolled.stdout);
+      assert.equal(result.status, "enrolled");
+      assert.match(result.identity, /^[a-f0-9]{64}$/);
+      const snaps = readdirSync(join(fx.state, "hosts", "wsl-a", "inventory"));
+      assert.ok(snaps.some((n) => n.startsWith("snapshot-")));
+      const status = model.load(fx.state);
+      assert.ok(status.hosts["wsl-a"]);
+      assert.equal(status.hosts["wsl-a"].connection.node, boot.connection_node);
+    } finally { enrollMock.restore(); }
+  } finally {
+    process.env.HOME = prevHome;
+    mock.restore();
+    fx.cleanup();
+  }
+});
+
+test("enroll without node blocked", () => {
+  const fx = cliFixture();
+  const mock = mockTransport({ probeJson: missingProbe });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "/no/such/node" });
+    const enrollFile = join(fx.tmp, "register.json");
+    writeFileSync(enrollFile, JSON.stringify({ hosts: [host], projects: [] }));
+    const r = captureMain(["--state", fx.state, "enroll", "--file", enrollFile]);
+    assert.equal(r.code, 2);
+    const payload = JSON.parse(r.stderr);
+    assert.equal(payload.error, "node-missing");
+    const status = model.load(fx.state);
+    assert.deepEqual(Object.keys(status.hosts), []);
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
+test("probe --connection-file still does not imply register", () => {
+  const fx = cliFixture();
+  const mock = mockTransport({
+    probeJson: { ...missingProbe, tools: { ...missingProbe.tools, node: process.execPath }, node_path: process.execPath, node_usable: true },
+  });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: process.execPath, identity: "discover" });
+    const conn = writeConn(fx.tmp, host);
+    const r = captureMain(["probe", "--connection-file", conn]);
+    assert.equal(r.code, 0, r.stderr);
+    const payload = JSON.parse(r.stdout);
+    assert.ok(payload.next.includes("enroll"));
+    const status = model.load(fx.state);
+    assert.deepEqual(Object.keys(status.hosts), []);
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
+test("environmentSpec uses managed volta path", () => {
+  const tmp = mkdtempSync(join(tmpdir(), "ops-env-"));
+  const state = join(tmp, "controller");
+  const target = join(tmp, "server");
+  const prevProbe = cliHooks.probeLocal;
+  cliHooks.probeLocal = () => ({ identity: agent.fingerprint(), scope: "mock" });
+  initialize(state, "control-a");
+  cliHooks.probeLocal = prevProbe;
+  const host = {
+    host_id: "node-a", display_name: "Node A", platform: process.platform === "win32" ? "windows" : "linux",
+    transport: "local", root: target, identity: agent.fingerprint(), connection: {},
+  };
+  model.register(state, { hosts: [host], projects: [] });
+  const prev = recipes.hostRecipesHooks.call;
+  const voltaBin = core.targetJoin(host, "_host/toolchains/ops/volta/bin/volta");
+  recipes.hostRecipesHooks.call = (_h, req) => {
+    if (req.action === "snapshot") return { paths: { [req.paths[0]]: { kind: "file" } } };
+    return {
+      identity: host.identity,
+      tools: {
+        node: { status: "observed", version: "v24.21.0", path: process.execPath },
+        volta: { status: "missing", path: null },
+      },
+      defaults: { VOLTA_HOME: core.targetJoin(host, "_host/toolchains/ops/volta") },
+    };
+  };
+  try {
+    const spec = recipes.environmentSpec(state, "node-a", { account: "ops", node_version: "24.21.0" });
+    const install = spec.host_actions.find((a) => a.kind === "install-toolchain");
+    assert.equal(install.argv[0], voltaBin);
+  } finally {
+    recipes.hostRecipesHooks.call = prev;
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("environmentSpec still throws when volta truly absent", () => {
+  const tmp = mkdtempSync(join(tmpdir(), "ops-envmiss-"));
+  const state = join(tmp, "controller");
+  const target = join(tmp, "server");
+  const prevProbe = cliHooks.probeLocal;
+  cliHooks.probeLocal = () => ({ identity: agent.fingerprint(), scope: "mock" });
+  initialize(state, "control-a");
+  cliHooks.probeLocal = prevProbe;
+  const host = {
+    host_id: "node-a", display_name: "Node A", platform: process.platform === "win32" ? "windows" : "linux",
+    transport: "local", root: target, identity: agent.fingerprint(), connection: {},
+  };
+  model.register(state, { hosts: [host], projects: [] });
+  const prev = recipes.hostRecipesHooks.call;
+  recipes.hostRecipesHooks.call = (_h, req) => {
+    if (req.action === "snapshot") return { paths: { [req.paths[0]]: { kind: "absent" } } };
+    return {
+      identity: host.identity,
+      tools: {
+        node: { status: "observed", version: "v24.21.0", path: process.execPath },
+        volta: { status: "missing", path: null },
+      },
+      defaults: {},
+    };
+  };
+  try {
+    assert.throws(
+      () => recipes.environmentSpec(state, "node-a", { account: "ops", node_version: "24.21.0" }),
+      /bootstrap-node/,
+    );
+  } finally {
+    recipes.hostRecipesHooks.call = prev;
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});