@namewta/speculo 1.0.12 → 1.0.13

package/template/workflows/ops/common/toolchains/volta-linux.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": 1,
+  "manager": "volta",
+  "volta_version": "2.0.2",
+  "node_version": "24.21.0",
+  "profile_edit": false,
+  "use_official_install_sh": false,
+  "volta_home_rel": "_host/toolchains/{account}/volta",
+  "archives": {
+    "linux-x64": {
+      "volta": {
+        "filename": "volta-2.0.2-linux.tar.gz",
+        "url": "https://github.com/volta-cli/volta/releases/download/v2.0.2/volta-2.0.2-linux.tar.gz",
+        "sha256": "6cec054c911fb925b629a09455775af6e95dc0f5694a4c28b63979ab9ef18037"
+      },
+      "node": {
+        "filename": "node-v24.21.0-linux-x64.tar.gz",
+        "url": "https://nodejs.org/dist/v24.21.0/node-v24.21.0-linux-x64.tar.gz",
+        "sha256": "6e1db87ef58b8819e5d5402eff1536491b18edd8eb7bee5ef7897876e88dc5ff"
+      }
+    },
+    "linux-arm64": {
+      "volta": {
+        "filename": "volta-2.0.2-linux-arm.tar.gz",
+        "url": "https://github.com/volta-cli/volta/releases/download/v2.0.2/volta-2.0.2-linux-arm.tar.gz",
+        "sha256": "1eb92f8b711753aa576352b2e580b2f3fdadeab8664929ca1da3d0de65448517"
+      },
+      "node": {
+        "filename": "node-v24.21.0-linux-arm64.tar.gz",
+        "url": "https://nodejs.org/dist/v24.21.0/node-v24.21.0-linux-arm64.tar.gz",
+        "sha256": "724282c3b43aec998aa9527380465b45d229e021b58035f5f4f63095eabfe5d5"
+      }
+    }
+  }
+}

package/template/workflows/ops/common/tools/bootstrap-volta.sh

@@ -0,0 +1,210 @@
+#!/bin/sh
+# First-stage Linux SSH Node bootstrap. POSIX only; never runs install.sh or edits profiles.
+set -eu
+
+ACK='I-APPROVE-THIS-BOOTSTRAP'
+
+json_str() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
+}
+
+digest_file() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | cut -d' ' -f1
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$1" | cut -d' ' -f1
+  else
+    echo 'No SHA-256 implementation; bootstrap blocked' >&2
+    exit 2
+  fi
+}
+
+profile_digest() {
+  d=''
+  for f in "${HOME-}/.bashrc" "${HOME-}/.profile"; do
+    if [ -f "$f" ] && [ ! -L "$f" ]; then
+      d="${d}$(digest_file "$f")"
+    else
+      d="${d}absent"
+    fi
+  done
+  printf '%s' "$d"
+}
+
+normalize_arch() {
+  m=$(uname -m)
+  case "$m" in
+    x86_64) printf 'linux-x64' ;;
+    aarch64|arm64) printf 'linux-arm64' ;;
+    *) printf 'unsupported:%s' "$m" ;;
+  esac
+}
+
+tool_path() {
+  if command -v "$1" >/dev/null 2>&1; then command -v "$1"; else printf 'missing'; fi
+}
+
+abspath_cmd() {
+  p=$1
+  if [ "$p" = "missing" ] || [ -z "$p" ]; then
+    printf 'missing'
+    return
+  fi
+  if command -v readlink >/dev/null 2>&1; then
+    readlink -f "$p" 2>/dev/null || printf '%s' "$p"
+  else
+    printf '%s' "$p"
+  fi
+}
+
+emit_probe() {
+  specified=${1-}
+  arch=$(normalize_arch)
+  nodep=$(tool_path node)
+  voltap=$(tool_path volta)
+  usable=false
+  node_path=null
+  node_version=null
+  if [ -n "$specified" ]; then
+    if [ -x "$specified" ] && [ ! -L "$specified" -o -x "$specified" ]; then
+      usable=true
+      nodep=$specified
+    else
+      nodep=missing
+      usable=false
+    fi
+  elif [ "$nodep" != "missing" ] && [ -x "$nodep" ]; then
+    usable=true
+  fi
+  if [ "$usable" = true ]; then
+    nodep=$(abspath_cmd "$nodep")
+    node_path="\"$(json_str "$nodep")\""
+    ver=$("$nodep" --version 2>/dev/null || true)
+    if [ -n "$ver" ]; then node_version="\"$(json_str "$ver")\""; fi
+  else
+    nodep=missing
+  fi
+  profile_has=false
+  for f in "${HOME-}/.bashrc" "${HOME-}/.profile"; do
+    if [ -f "$f" ] && grep -q volta "$f" 2>/dev/null; then profile_has=true; fi
+  done
+  volta_out=$voltap
+  [ "$volta_out" = "missing" ] || volta_out=$(abspath_cmd "$volta_out")
+  printf '{"status":"probed","uname":"%s","arch":"%s","tools":{"node":"%s","volta":"%s","tar":"%s","sha256sum":"%s"},"node_path":%s,"node_version":%s,"node_usable":%s,"profile_has_volta":%s}\n' \
+    "$(json_str "$(uname -sm)")" "$(json_str "$arch")" \
+    "$(json_str "$nodep")" "$(json_str "$volta_out")" \
+    "$(json_str "$(tool_path tar)")" "$(json_str "$(tool_path sha256sum)")" \
+    "$node_path" "$node_version" "$usable" "$profile_has"
+}
+
+find_named() {
+  root=$1
+  name=$2
+  found=''
+  # Prefer a file literally named $name, skipping install.sh.
+  for cand in "$root/$name" "$root"/*/"$name"; do
+    if [ -f "$cand" ] && [ ! -L "$cand" ]; then
+      found=$cand
+      break
+    fi
+  done
+  printf '%s' "$found"
+}
+
+case "${1:---probe}" in
+  --probe)
+    emit_probe "${2-}"
+    ;;
+  --apply)
+    [ "$#" -eq 8 ] || { echo 'usage: bootstrap-volta.sh --apply VOLTA_TAR VOLTA_SHA NODE_TAR NODE_SHA VOLTA_HOME NODE_VERSION I-APPROVE-THIS-BOOTSTRAP' >&2; exit 2; }
+    volta_tar=$2
+    volta_sha=$3
+    node_tar=$4
+    node_sha=$5
+    volta_home=$6
+    node_version=$7
+    [ "$8" = "$ACK" ] || { echo 'explicit bootstrap acknowledgement required' >&2; exit 2; }
+    case "$node_version" in
+      ''|latest|Latest|LATEST|*latest*) echo 'refusing latest or empty node version' >&2; exit 2 ;;
+    esac
+    case "$volta_home" in
+      /*) ;;
+      *) echo 'VOLTA_HOME must be an absolute path' >&2; exit 2 ;;
+    esac
+    case "$volta_home" in
+      *..*|*[\ \	]*) echo 'VOLTA_HOME must not contain spaces or ..' >&2; exit 2 ;;
+    esac
+    for f in "$volta_tar" "$node_tar"; do
+      [ -f "$f" ] && [ ! -L "$f" ] || { echo "Installer must be a reviewed regular file: $f" >&2; exit 2; }
+    done
+    actual=$(digest_file "$volta_tar")
+    [ "$actual" = "$volta_sha" ] || { echo 'Volta installer changed after review' >&2; exit 2; }
+    actual=$(digest_file "$node_tar")
+    [ "$actual" = "$node_sha" ] || { echo 'Node installer changed after review' >&2; exit 2; }
+
+    image="$volta_home/tools/image/node/$node_version"
+    node_bin="$image/bin/node"
+    wrapper="$volta_home/bin/ops-node"
+    if [ -x "$node_bin" ] && [ -x "$wrapper" ]; then
+      ver=$("$wrapper" --version 2>/dev/null || true)
+      if [ "$ver" = "v$node_version" ]; then
+        printf '{"status":"installed","volta_home":"%s","connection_node":"%s","node_path":"%s","volta_bin":"%s","node_version":"%s","volta_version":"2.0.2","profile_unchanged":true,"idempotent":true}\n' \
+          "$(json_str "$volta_home")" "$(json_str "$wrapper")" "$(json_str "$node_bin")" "$(json_str "$volta_home/bin/volta")" "$(json_str "$node_version")"
+        exit 0
+      fi
+    fi
+
+    before=$(profile_digest)
+    mkdir -p "$volta_home/bin" "$image" "$volta_home/tmp"
+    stage=$(mktemp -d "$volta_home/tmp/extract.XXXXXX")
+    trap 'rm -rf "$stage"' EXIT
+
+    tar -xzf "$volta_tar" -C "$stage"
+    volta_src=$(find_named "$stage" volta)
+    [ -n "$volta_src" ] || { echo 'volta binary missing from archive; refusing to run install.sh' >&2; exit 2; }
+    cp "$volta_src" "$volta_home/bin/volta"
+    chmod 755 "$volta_home/bin/volta"
+    shim_src=$(find_named "$stage" volta-shim)
+    if [ -n "$shim_src" ]; then
+      cp "$shim_src" "$volta_home/bin/volta-shim"
+      chmod 755 "$volta_home/bin/volta-shim"
+    fi
+    mig_src=$(find_named "$stage" volta-migrate)
+    if [ -n "$mig_src" ]; then
+      cp "$mig_src" "$volta_home/bin/volta-migrate"
+      chmod 755 "$volta_home/bin/volta-migrate"
+    fi
+    # Never execute install.sh even if present.
+    if [ -f "$stage/install.sh" ] || [ -f "$stage"/*/install.sh ] 2>/dev/null; then
+      :
+    fi
+
+    tar -xzf "$node_tar" -C "$image" --strip-components=1
+    [ -x "$node_bin" ] || { echo 'Node binary missing after extract' >&2; exit 2; }
+    chmod 755 "$node_bin"
+
+    cat > "$wrapper" <<EOF
+#!/bin/sh
+export VOLTA_HOME=$(printf '%s' "$volta_home" | sed "s/'/'\\\\''/g; s/^/'/; s/\$/'/")
+export PATH="\$VOLTA_HOME/bin:\$PATH"
+exec $(printf '%s' "$node_bin" | sed "s/'/'\\\\''/g; s/^/'/; s/\$/'/") "\$@"
+EOF
+    chmod 755 "$wrapper"
+    cp "$wrapper" "$volta_home/bin/node"
+    chmod 755 "$volta_home/bin/node"
+
+    ver=$("$wrapper" --version 2>/dev/null || true)
+    [ "$ver" = "v$node_version" ] || { echo "ops-node version mismatch: got ${ver:-empty} want v$node_version" >&2; exit 2; }
+
+    after=$(profile_digest)
+    [ "$before" = "$after" ] || { echo 'bootstrap refused: shell profile changed' >&2; exit 2; }
+
+    volta_ver=$("$volta_home/bin/volta" --version 2>/dev/null || printf '2.0.2')
+    printf '{"status":"installed","volta_home":"%s","connection_node":"%s","node_path":"%s","volta_bin":"%s","node_version":"%s","volta_version":"%s","profile_unchanged":true}\n' \
+      "$(json_str "$volta_home")" "$(json_str "$wrapper")" "$(json_str "$node_bin")" "$(json_str "$volta_home/bin/volta")" "$(json_str "$node_version")" "$(json_str "$volta_ver")"
+    ;;
+  *)
+    echo 'usage: bootstrap-volta.sh --probe [NODE_PATH] | --apply VOLTA_TAR VOLTA_SHA NODE_TAR NODE_SHA VOLTA_HOME NODE_VERSION I-APPROVE-THIS-BOOTSTRAP' >&2
+    exit 2
+    ;;
+esac

package/template/workflows/ops/common/tools/bootstrap.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # First-stage controller/target bootstrap: POSIX shell only, no Python prerequisite.
+# Remote Linux SSH hosts that lack Node must use ops.mjs bootstrap-node, not this local script.
 set -eu
 case "${1:---probe}" in
   --probe)

package/template/workflows/ops/common/tools/opslib/bootstrap.mjs

@@ -0,0 +1,221 @@
+/** Node-less Linux SSH bootstrap: pinned Volta/Node via POSIX + scp, then enroll. */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, basename, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { digest, exact, identifier, newId, noSymlinks, NodeMissing, now, OpsError, privateDir, rootPath, targetJoin, writeJson } from "./core.mjs";
+import { register, validateHost } from "./model.mjs";
+import { call, posixCall, posixSend, validateSshEndpoint } from "./transport.mjs";
+
+const ACK = "I-APPROVE-THIS-BOOTSTRAP";
+const TOOLS = join(dirname(fileURLToPath(import.meta.url)), "..");
+const SCRIPT = readFileSync(join(TOOLS, "bootstrap-volta.sh"), "utf8");
+const PIN_PATH = join(TOOLS, "..", "toolchains", "volta-linux.json");
+
+export function loadVoltaPin() {
+  const pin = JSON.parse(readFileSync(PIN_PATH, "utf8"));
+  if (pin.schema_version !== 1 || pin.manager !== "volta") throw new OpsError("invalid volta-linux pin metadata");
+  return pin;
+}
+
+export const bootstrapHooks = { loadPin: loadVoltaPin };
+
+function rejectUnpinned(label, value) {
+  const s = String(value ?? "");
+  if (!s || /latest/i.test(s)) throw new OpsError(`${label} must be a concrete pinned name, not latest`);
+  return s;
+}
+
+function safeFilename(name) {
+  rejectUnpinned("installer filename", name);
+  if (!/^[A-Za-z0-9._+-]+$/.test(name)) throw new OpsError("unsafe installer filename: " + name);
+  return name;
+}
+
+function sha256File(path) {
+  noSymlinks(path, { allowMissing: false });
+  return digest(readFileSync(path));
+}
+
+function parseJsonLine(stdout, label) {
+  const lines = String(stdout || "").trim().split(/\r?\n/).filter(Boolean);
+  const last = lines.at(-1);
+  try { return JSON.parse(last); }
+  catch { throw new OpsError(`${label} returned invalid JSON`); }
+}
+
+export function posixProbe(endpoint, nodePath) {
+  const args = ["--probe"];
+  if (nodePath) args.push(String(nodePath));
+  const r = posixCall(endpoint, SCRIPT, { args });
+  return parseJsonLine(r.stdout, "posix probe");
+}
+
+function linuxHost(root) {
+  return { platform: "linux", root: rootPath(root, "linux") };
+}
+
+function installerDir(hostRoot) {
+  return targetJoin(linuxHost(hostRoot), "_host/installers");
+}
+
+function managedVoltaHome(hostRoot, account) {
+  return targetJoin(linuxHost(hostRoot), "_host/toolchains/" + account + "/volta");
+}
+
+function downloadHttps(url, dest) {
+  let u;
+  try { u = new URL(url); } catch { throw new OpsError("pin URL is invalid"); }
+  if (u.protocol !== "https:" || u.username || u.password) throw new OpsError("pin URL must be credential-free https");
+  privateDir(dirname(dest));
+  const curl = spawnSync("curl", ["-fsSL", "--max-time", "120", "-o", dest, url], { encoding: "utf8" });
+  if (curl.status === 0 && existsSync(dest)) return dest;
+  const wget = spawnSync("wget", ["-q", "-O", dest, url], { encoding: "utf8" });
+  if (wget.status === 0 && existsSync(dest)) return dest;
+  throw new OpsError("controller download failed; pass reviewed local archives instead of --allow-network");
+}
+
+function resolveArchive({ archive, sha256, pinEntry, allowNetwork, cacheDir, label }) {
+  const expected = pinEntry.sha256;
+  if (sha256 && sha256 !== expected) throw new OpsError(`${label} sha256 does not match the reviewed pin`);
+  let file = archive;
+  if (!file) {
+    if (!allowNetwork) throw new OpsError(`${label} archive is required unless --allow-network fetches the pinned URL`);
+    file = join(cacheDir, safeFilename(pinEntry.filename));
+    downloadHttps(pinEntry.url, file);
+  }
+  noSymlinks(file, { allowMissing: false });
+  if (safeFilename(basename(file)) && /latest/i.test(basename(file))) throw new OpsError(`${label} archive name must not contain latest`);
+  const actual = sha256File(file);
+  if (actual !== expected) throw new OpsError(`${label} installer changed after review`);
+  return { file, sha256: expected, filename: safeFilename(pinEntry.filename) };
+}
+
+export function bootstrapNode(args) {
+  const apply = Boolean(args.apply);
+  if (apply && args.probe) throw new OpsError("bootstrap-node --probe and --apply are mutually exclusive");
+  if (!args.connection_file) throw new OpsError("--connection-file is required");
+  const host = JSON.parse(readFileSync(args.connection_file, "utf8"));
+  const endpoint = host.connection || host;
+  validateSshEndpoint(endpoint);
+  if ((endpoint.shell ?? "posix") === "powershell") {
+    throw new OpsError("POSIX bootstrap is Linux-only; PowerShell targets still require an existing Node");
+  }
+  const pin = bootstrapHooks.loadPin();
+  const posix = posixProbe(endpoint, endpoint.node);
+  if (String(posix.arch || "").startsWith("unsupported")) throw new OpsError("unsupported target architecture: " + posix.arch);
+  const arch = posix.arch;
+  const pinArch = pin.archives[arch];
+  if (!pinArch) throw new OpsError("no pinned Volta/Node archives for " + arch);
+
+  if (!apply) {
+    return { status: "probed", posix, pin: { volta_version: pin.volta_version, node_version: pin.node_version, arch } };
+  }
+
+  if (posix.node_usable && posix.tools?.node && posix.tools.node !== "missing") {
+    return {
+      status: "skipped-existing-node",
+      connection_node: posix.node_path || posix.tools.node,
+      posix,
+      note: "existing Node left untouched; register it as connection.node",
+    };
+  }
+
+  if (args.ack !== ACK) throw new OpsError("explicit acknowledgement I-APPROVE-THIS-BOOTSTRAP is required");
+  if (!args.account) throw new OpsError("--account is required");
+  if (!args.host_root) throw new OpsError("--host-root is required");
+  identifier(args.account, "toolchain account");
+  const hostRoot = rootPath(args.host_root, "linux");
+  const nodeVersion = rejectUnpinned("node version", args.node_version || pin.node_version);
+  if (nodeVersion !== pin.node_version) throw new OpsError("node version must match the reviewed pin " + pin.node_version);
+
+  const cacheDir = args.state ? join(args.state, "private", "installers") : join(hostRoot, "_host", "installers-cache");
+  const volta = resolveArchive({
+    archive: args.volta_archive, sha256: args.volta_sha256, pinEntry: pinArch.volta,
+    allowNetwork: Boolean(args.allow_network), cacheDir, label: "Volta",
+  });
+  const node = resolveArchive({
+    archive: args.node_archive, sha256: args.node_sha256, pinEntry: pinArch.node,
+    allowNetwork: Boolean(args.allow_network), cacheDir, label: "Node",
+  });
+
+  const installers = installerDir(hostRoot);
+  const voltaHome = managedVoltaHome(hostRoot, args.account);
+  posixCall(endpoint, "#!/bin/sh\nset -eu\nmkdir -p -- \"$1\" \"$2\"\n", { args: [installers, voltaHome] });
+  const remoteVolta = join(installers, volta.filename);
+  const remoteNode = join(installers, node.filename);
+  posixSend(endpoint, volta.file, remoteVolta);
+  posixSend(endpoint, node.file, remoteNode);
+  const applied = posixCall(endpoint, SCRIPT, {
+    args: ["--apply", remoteVolta, volta.sha256, remoteNode, node.sha256, voltaHome, nodeVersion, ACK],
+    timeout: 600,
+  });
+  const result = parseJsonLine(applied.stdout, "posix apply");
+  result.status = result.status || "installed";
+  result.posix_probe = posix;
+  result.arch = arch;
+
+  if (args.state && args.host_id) {
+    identifier(args.host_id);
+    const receipt = join(args.state, "hosts", args.host_id, "bootstrap", newId("receipt") + ".json");
+    writeJson(receipt, { ...result, host_id: args.host_id, at: now() });
+    result.receipt = receipt;
+  }
+  return result;
+}
+
+export function enroll(state, request) {
+  exact(request, new Set(["hosts", "projects"]), new Set(), "enroll");
+  const hosts = request.hosts ?? [];
+  if (!hosts.length) throw new OpsError("enroll requires hosts");
+  const enrolled = [];
+  for (const raw of hosts) {
+    const host = { ...raw, connection: { ...(raw.connection || {}) } };
+    if (host.transport !== "ssh") throw new OpsError("enroll currently supports ssh hosts; local hosts use register");
+    validateSshEndpoint(host.connection);
+    if ((host.connection.shell ?? "posix") === "powershell") {
+      throw new OpsError("POSIX bootstrap/enroll is Linux-only");
+    }
+    if (!host.connection.node) throw new NodeMissing({ tools: { node: "missing" }, node_usable: false });
+    const posix = posixProbe(host.connection, host.connection.node);
+    if (posix.tools?.node === "missing" || posix.node_usable === false) throw new NodeMissing(posix);
+    const discovery = host.identity === "discover" || host.identity == null;
+    if (discovery) host.identity = "0".repeat(64);
+    if (!isAbsolute(host.connection.node)) {
+      throw new OpsError("connection.node must be the absolute path returned by bootstrap-node");
+    }
+    validateHost(host);
+    const observed = call(host, { action: "probe", ...(discovery ? { identity: null } : {}) }, { timeout: 180 });
+    host.identity = observed.identity;
+    validateHost(host);
+    register(state, { hosts: [host], projects: request.projects });
+    const inventory = call(host, { action: "probe" }, { timeout: 180 });
+    const snap = join(state, "hosts", host.host_id, "inventory", newId("snapshot") + ".json");
+    writeJson(snap, inventory);
+    enrolled.push({
+      host_id: host.host_id,
+      identity: host.identity,
+      connection_node: host.connection.node,
+      inventory,
+      snapshot: snap,
+    });
+  }
+  return {
+    status: "enrolled",
+    hosts: enrolled,
+    host_id: enrolled[0].host_id,
+    identity: enrolled[0].identity,
+    inventory: enrolled[0].inventory,
+    connection_node: enrolled[0].connection_node,
+  };
+}
+
+export function discoverOrMissing(host) {
+  if (host.transport !== "ssh") return null;
+  validateSshEndpoint(host.connection);
+  const posix = posixProbe(host.connection, host.connection?.node);
+  const missing = posix.tools?.node === "missing" || posix.node_usable === false;
+  if (missing) throw new NodeMissing(posix);
+  if (!host.connection.node && posix.node_path) host.connection.node = posix.node_path;
+  return posix;
+}

package/template/workflows/ops/common/tools/opslib/cli.mjs

@@ -3,7 +3,7 @@ import { existsSync, readdirSync, readFileSync, statSync, lstatSync, unlinkSync,
 import { dirname, isAbsolute, join, relative as pathRelative, resolve, sep } from "node:path";
 import { hostname } from "node:os";
 import {
-  atomicWrite, digest, emptyStatus, identifier, newId, now, noSymlinks, OpsError,
+  atomicWrite, digest, emptyStatus, identifier, newId, now, noSymlinks, OpsError, NodeMissing,
   privateDir, readJson, VERSION, withLock, writeJson,
 } from "./core.mjs";
 import { load, ledgerLoad, putCredential, register, save, validate, validateHost, validateStatus } from "./model.mjs";
@@ -13,6 +13,7 @@ import { approval, apply, verifyJournal, requestBase } from "./execution.mjs";
 import { STANDARD } from "./docs.mjs";
 import { environmentSpec } from "./host_recipes.mjs";
 import { fetchSource } from "./sources.mjs";
+import { bootstrapNode, enroll, discoverOrMissing } from "./bootstrap.mjs";
 
 export const cliHooks = { probeLocal: transportProbeLocal };
 export function probeLocal() { return cliHooks.probeLocal(); }
@@ -218,6 +219,15 @@ function parseArgs(argv) {
   else if (command === "status") { /* none */ }
   else if (command === "recover-controller-lock") grab("--ack");
   else if (command === "import-legacy") { grab("--source"); grab("--controller-id"); }
+  else if (command === "bootstrap-node") {
+    grab("--connection-file"); grab("--host-id"); grab("--account"); grab("--host-root");
+    grab("--volta-archive"); grab("--volta-sha256"); grab("--node-archive"); grab("--node-sha256");
+    grab("--node-version"); grab("--ack");
+    out.probe = flag("--probe");
+    out.apply = flag("--apply");
+    out.allow_network = flag("--allow-network");
+  }
+  else if (command === "enroll") grab("--file");
   else throw new Error("unknown command: " + command);
   if (argv.length) throw new Error("unrecognized arguments: " + argv.join(" "));
   return out;
@@ -234,7 +244,7 @@ export function main(argv = process.argv.slice(2)) {
     process.stdout.write(VERSION + "\n");
     return 0;
   }
-  if (!args.state && !["analyze", "probe", "validate"].includes(args.command)) {
+  if (!args.state && !["analyze", "probe", "validate", "bootstrap-node"].includes(args.command)) {
     process.stderr.write("--state is required; it is never guessed from cwd\n");
     return 2;
   }
@@ -254,10 +264,14 @@ export function main(argv = process.argv.slice(2)) {
       } else if (args.connection_file) {
         const h = readJson(args.connection_file);
         const discovery = h.identity === "discover";
+        if (h.transport === "ssh") discoverOrMissing(h);
         if (discovery) h.identity = "0".repeat(64);
         validateHost(h);
         result = call(h, { action: "probe", ...(discovery ? { identity: null } : {}) }, { timeout: 180 });
-        if (discovery) result.registration_note = "Read-only discovery over your pinned known_hosts. Review identity and store it explicitly; discover is never valid for register/apply.";
+        if (discovery) {
+          result.next = "ops.mjs --state STATE enroll --file register.json";
+          result.registration_note = "Read-only discovery over your pinned known_hosts. Next must persist via enroll (or register + probe --host); discover is never valid for register/apply.";
+        }
       } else result = probeLocal();
       if (args.output) writeJson(resolve(args.output), result);
     } else if (cmd === "register") result = register(state, readJson(args.file));
@@ -302,10 +316,18 @@ export function main(argv = process.argv.slice(2)) {
       };
     } else if (cmd === "recover-controller-lock") result = breakControllerLock(state, args.ack);
     else if (cmd === "import-legacy") result = importLegacy(state, resolve(args.source), args.controller_id);
+    else if (cmd === "bootstrap-node") result = bootstrapNode({ ...args, state });
+    else if (cmd === "enroll") result = enroll(state, readJson(args.file));
     process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-    return ["failed", "partial", "unknown", "docs_pending"].includes(result.status) ? 2 : 0;
+    return ["failed", "partial", "unknown", "docs_pending", "blocked"].includes(result.status) ? 2 : 0;
   } catch (e) {
-    process.stderr.write(JSON.stringify({ status: "blocked", error: e.message || String(e) }) + "\n");
+    const payload = { status: "blocked", error: e.message || String(e) };
+    if (e instanceof NodeMissing) {
+      payload.error = "node-missing";
+      payload.next = e.next;
+      payload.posix = e.posix;
+    }
+    process.stderr.write(JSON.stringify(payload) + "\n");
     return 2;
   }
 }

package/template/workflows/ops/common/tools/opslib/core.mjs

@@ -19,6 +19,16 @@ export class OpsError extends Error {
   }
 }
 
+export class NodeMissing extends OpsError {
+  constructor(posix, next = "ops.mjs bootstrap-node --apply") {
+    super("node-missing");
+    this.name = "NodeMissing";
+    this.code = "node-missing";
+    this.next = next;
+    this.posix = posix;
+  }
+}
+
 export class UnknownResult extends OpsError {
   constructor(message) {
     super(message);
@@ -26,6 +36,8 @@ export class UnknownResult extends OpsError {
   }
 }
 
+
+
 export function now() {
   return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }

package/template/workflows/ops/common/tools/opslib/host_recipes.mjs

@@ -1,7 +1,9 @@
 /** Pinned environment-management recipes. No latest-version guessing or implicit profile edits. */
 import { identifier, exact, newId, now, OpsError, targetJoin, within } from "./core.mjs";
 import { load } from "./model.mjs";
-import { call } from "./transport.mjs";
+import { call as transportCall } from "./transport.mjs";
+
+export const hostRecipesHooks = { call: transportCall };
 
 function shlexQuote(s) {
   if (s === "") return "''";
@@ -13,12 +15,18 @@ function reEscape(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+function managedVoltaBin(host, account, inventory) {
+  const home = (inventory.defaults?.VOLTA_HOME || "").trim()
+    || targetJoin(host, "_host/toolchains/" + account + "/volta");
+  return host.platform === "windows" ? home + "\\bin\\volta" : home.replace(/\/+$/, "") + "/bin/volta";
+}
+
 export function environmentSpec(state, hid, request) {
   exact(request, new Set(["account", "python_versions", "uv_path", "node_version", "npm_version", "volta_path", "java_version", "original_java_candidate", "sdkman_init"]), new Set(["account"]), "environment request");
   identifier(request.account, "toolchain account");
   const status = load(state);
   const host = status.hosts[hid];
-  const inventory = call(host, { action: "probe", disk_roots: [host.root] }, { timeout: 180 });
+  const inventory = hostRecipesHooks.call(host, { action: "probe", disk_roots: [host.root] }, { timeout: 180 });
   const base = targetJoin(host, "_host/toolchains/" + request.account);
   const defaults = Object.fromEntries(Object.entries(inventory.tools).filter(([k, v]) => ["java", "python", "python3", "node", "npm"].includes(k) && v.status === "observed"));
   const actions = [];
@@ -55,8 +63,16 @@ export function environmentSpec(state, hid, request) {
   }
   if (request.node_version) {
     const v = pinned(request.node_version, "Node");
-    const volta = request.volta_path || inventory.tools.volta?.path;
-    if (!volta) throw new OpsError("Volta missing: install a reviewed pinned release before the managed environment recipe");
+    let volta = request.volta_path || inventory.tools.volta?.path;
+    if (!volta) {
+      const candidate = managedVoltaBin(host, request.account, inventory);
+      const snap = hostRecipesHooks.call(host, { action: "snapshot", paths: [candidate] }, { timeout: 60 });
+      const st = snap.paths?.[candidate];
+      if (!st || st.kind === "absent") {
+        throw new OpsError("Volta missing: install a reviewed pinned release before the managed environment recipe; for a Node-less Linux SSH target run ops.mjs bootstrap-node first");
+      }
+      volta = candidate;
+    }
     const home = base + (host.platform === "windows" ? "\\volta" : "/volta");
     mkdir("_host/toolchains/" + request.account + "/volta");
     let old = (inventory.tools.node?.version ?? "").trim();