@namewta/speculo 1.0.19 → 1.0.21

package/template/workflows/ops/common/templates/HOST-README.md

@@ -2,7 +2,9 @@
 
 此文件是内容合同，不含真实密码；实际生成器依据成功回执填入真实值，不把占位符当交付。
 
-## host_id、实际身份、host_root、更新 UTC 时间
+## host_id、实际身份、登录账号、host_root、根确认回执、更新 UTC 时间
+
+区分已登记、目录存在、双边文档已验证、项目运行环境就绪。新根由用户指定或接受实际登录主目录下 ops；已有根标记既有登记，换账号不换根。
 
 ## 服务一览表
 

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

@@ -67,7 +67,7 @@ function setupFixture() {
     project_id: "app-a", display_name: "APP A", kind: "app", service_type: null,
     source: { type: "local", location: join(tmp, "source"), revision: "v1" },
   };
-  model.register(state, { hosts: [host], projects: [project] });
+  const legacy = model.load(state); legacy.hosts[host.host_id] = host; legacy.projects[project.project_id] = project; model.save(state, legacy); // pre-upgrade v3 fixture
   model.putCredential(state, { credential_id: "app-auth", version: 1, purpose: "Synthetic test only", values: { username: "app-user", password: PASSWORD } });
   const spec = (version = "v1", operation = "deploy", program = null) => {
     if (program == null) {
@@ -175,16 +175,13 @@ test("lock is not autobroken", () => {
   });
   rmSync(d, { recursive: true, force: true });
 });
-test("symlink rejected", () => {
+test("symlink rejected", (t) => {
   const d = mkdtempSync(join(tmpdir(), "ops-link-"));
+  t.after(() => rmSync(d, { recursive: true, force: true }));
   mkdirSync(join(d, "real"));
-  try { symlinkSync(join(d, "real"), join(d, "link"), "dir"); }
-  catch (e) {
-    if (process.platform === "win32") { rmSync(d, { recursive: true, force: true }); return; }
-    throw e;
-  }
+  symlinkSync(join(d, "real"), join(d, "link"), process.platform === "win32" ? "junction" : "dir");
   assert.throws(() => atomicWrite(join(d, "link", "a.txt"), "x"), OpsError);
-  rmSync(d, { recursive: true, force: true });
+  assert.equal(existsSync(join(d, "real", "a.txt")), false);
 });
 test("file permissions", () => {
   const d = mkdtempSync(join(tmpdir(), "ops-perm-"));
@@ -443,7 +440,7 @@ test("planner contracts", async (t) => {
   });
   await each("unrelated host registration does not block approval", (fx) => {
     const [info] = fx.plan();
-    model.register(fx.state, { hosts: [{ ...fx.host, host_id: "node-b", display_name: "Node B", root: join(fx.tmp, "server-b") }] });
+    const legacy = model.load(fx.state); legacy.hosts["node-b"] = { ...fx.host, host_id: "node-b", display_name: "Node B", root: join(fx.tmp, "server-b") }; model.save(fx.state, legacy); // preserve legacy multi-root executor coverage
     fx.approve(info);
   });
   await each("touched host catalog drift blocks approval", (fx) => {
@@ -891,7 +888,7 @@ test("control file helpers", () => {
 });
 
 test("disjoint host plans apply sequentially", () => runFx((fx) => {
-  model.register(fx.state, { hosts: [{ ...fx.host, host_id: "node-b", display_name: "Node B", root: join(fx.tmp, "server-b") }] });
+  const legacy = model.load(fx.state); legacy.hosts["node-b"] = { ...fx.host, host_id: "node-b", display_name: "Node B", root: join(fx.tmp, "server-b") }; model.save(fx.state, legacy); // preserve legacy multi-root executor coverage
   const specA = {
     schema_version: 1, worker: "H", operation: "maintain", hosts: ["node-a"], reason: "Host A cache fixture",
     rollback_note: "Keep isolated cache until a separate purge is approved.",
@@ -994,7 +991,7 @@ test("new controllers keep secrets out of default documentation", () => runFx((f
   }
   assert.match(readFileSync(join(local,"OPERATIONS.md"),"utf8"), /secret_ref:.*app-auth@1/);
   assert.ok(readFileSync(join(remote,"env","app.env"),"utf8").includes(PASSWORD));
-  assert.equal(plan.operations.find((o) => o.path?.endsWith("env/app.env")).mode, 0o600);
+  assert.equal(plan.operations.find((o) => o.path === join(remote, "env", "app.env")).mode, 0o600);
   if (process.platform !== "win32") assert.equal(statSync(join(remote,"env","app.env")).mode & 0o777, 0o600);
   assert.equal(readJson(join(local,"docs-receipt.json")).status, "both-sides-verified");
 }));

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

@@ -3,7 +3,7 @@ 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 { dirname, join, posix } from "node:path";
 import { fileURLToPath } from "node:url";
 import test from "node:test";
 import { createHash } from "node:crypto";
@@ -14,10 +14,12 @@ 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";
+import { onboardingHooks, discoverServer, confirmServerRoot } from "../tools/opslib/onboarding.mjs";
 
 const toolsDir = join(dirname(fileURLToPath(import.meta.url)), "../tools");
 const scriptPath = join(toolsDir, "bootstrap-volta.sh");
 const ACK = "I-APPROVE-THIS-BOOTSTRAP";
+const linuxExecution = { skip: process.platform !== "linux" && "Requires Linux /bin/sh and a Linux Node executable; SSH protocol contracts run on every platform" };
 
 function sha256(p) {
   return createHash("sha256").update(readFileSync(p)).digest("hex");
@@ -58,13 +60,14 @@ function pinFor(archives, arch = "linux-x64") {
   return { ...base, archives: { ...base.archives, [arch]: slot } };
 }
 
-function mockTransport({ probeJson = null } = {}) {
+function mockTransport({ probeJson = null, agentJson = null, applyJson = 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") {
+      if (applyJson) return { status: 0, stdout: Buffer.alloc(0), stderr: Buffer.alloc(0) };
       const local = args[args.length - 2];
       const spec = args[args.length - 1];
       const remotePath = spec.slice(spec.indexOf(":") + 1);
@@ -80,11 +83,13 @@ function mockTransport({ probeJson = null } = {}) {
         return { status: 0, stdout: Buffer.from(JSON.stringify(probeJson) + "\n"), stderr: Buffer.alloc(0) };
       }
       if (String(last).includes("--input-type=module")) {
+        if (agentJson) return { status: 0, stdout: Buffer.from(JSON.stringify({ ok: true, result: agentJson }) + "\n"), stderr: Buffer.alloc(0) };
         const parts = splitRemote(last);
         return spawnSync(parts[0], parts.slice(1), {
           input: kw.input, encoding: "buffer", timeout: kw.timeout, maxBuffer: kw.maxBuffer,
         });
       }
+      if (applyJson) return { status: 0, stdout: Buffer.from(String(last).includes("--apply") ? JSON.stringify(applyJson) + "\n" : ""), stderr: Buffer.alloc(0) };
       const parts = splitRemote(last);
       return spawnSync(parts[0], parts.slice(1), {
         input: kw.input, encoding: "buffer", timeout: kw.timeout, maxBuffer: kw.maxBuffer,
@@ -182,7 +187,20 @@ test("scp uses the same host-key contract", () => {
   } finally { transport.transportHooks.spawnSync = prev; rmSync(d, { recursive: true, force: true }); }
 });
 
-test("bootstrap-volta apply installs wrapper and does not touch profile", () => {
+test("scp rejects controller paths and unsafe Linux paths before spawning", (t) => {
+  const d = mkdtempSync(join(tmpdir(), "ops-scp-path-"));
+  t.after(() => rmSync(d, { recursive: true, force: true }));
+  const kh = join(d, "known_hosts"), local = join(d, "archive.tar.gz");
+  writeFileSync(kh, "fixture pinned key\n"); writeFileSync(local, "reviewed archive");
+  const prev = transport.transportHooks.spawnSync;
+  t.after(() => { transport.transportHooks.spawnSync = prev; });
+  transport.transportHooks.spawnSync = () => { assert.fail("invalid paths must not reach scp"); };
+  for (const path of ["C:\\server\\archive.tar.gz", "C:/server/archive.tar.gz", "\\\\server\\share\\archive.tar.gz", "/srv/ops\\archive.tar.gz", "relative.tar.gz", "/srv/../archive.tar.gz", "/srv/space name.tar.gz", "/srv/nul\0.tar.gz"]) {
+    assert.throws(() => transport.posixSend({ hostname: "host.invalid", username: "ops", known_hosts: kh }, local, path), /remote scp path/);
+  }
+});
+
+test("bootstrap-volta apply installs wrapper and does not touch profile", linuxExecution, () => {
   const d = mkdtempSync(join(tmpdir(), "ops-vol-"));
   const home = join(d, "home");
   mkdirSync(home);
@@ -205,28 +223,33 @@ test("bootstrap-volta apply installs wrapper and does not touch profile", () =>
   } finally { rmSync(d, { recursive: true, force: true }); }
 });
 
-test("bootstrap-volta apply without ack blocked", () => {
+test("bootstrap-volta apply without ack blocked", linuxExecution, () => {
   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);
+  assert.equal(p.error, undefined);
+  assert.equal(p.status, 2);
+  assert.match(p.stderr, /acknowledgement/);
   rmSync(d, { recursive: true, force: true });
 });
 
-test("bootstrap-volta sha mismatch blocked", () => {
+test("bootstrap-volta sha mismatch blocked", linuxExecution, () => {
   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.equal(p.error, undefined);
+  assert.equal(p.status, 2);
+  assert.match(p.stderr, /installer changed after review/);
   assert.ok(!existsSync(join(d, "volta", "bin", "ops-node")));
   rmSync(d, { recursive: true, force: true });
 });
 
-function cliFixture() {
+function cliFixture({ executeLinux = false } = {}) {
   const tmp = mkdtempSync(join(tmpdir(), "ops-bootcli-"));
   const state = join(tmp, "controller");
-  const target = join(tmp, "server");
-  mkdirSync(target, { recursive: true });
+  // A simulated Linux SSH target is not a path on the controller filesystem.
+  const target = executeLinux ? join(tmp, "server") : "/srv/speculo-bootstrap-test";
+  if (executeLinux) mkdirSync(target, { recursive: true });
   const kh = join(tmp, "known_hosts");
   writeFileSync(kh, "fixture pinned key\n");
   const prevProbe = cliHooks.probeLocal;
@@ -236,9 +259,13 @@ function cliFixture() {
   const archives = makeArchives(tmp);
   const prevPin = bootstrap.bootstrapHooks.loadPin;
   bootstrap.bootstrapHooks.loadPin = () => pinFor(archives);
+  const previousObserve = onboardingHooks.observe;
+  onboardingHooks.observe = (h, root) => ({ identity: executeLinux ? agent.fingerprint() : "a".repeat(64), platform: "linux", username: h.connection.username, uid: "1000", home: "/home/ops", node: null, node_version: null, ...(root ? {root_check: {exists: false, writable: true, nonempty: false, owner: null}} : {}) });
   return {
     tmp, state, target, kh, archives,
+    confirm(host) { const d = discoverServer(state, host.host_id, host); const r = confirmServerRoot(state, host.host_id, d.discovery.receipt_id, host.root, "fixture-user", "Confirm only this isolated simulated target root"); host.root_confirmation = r.root_confirmation; },
     cleanup() {
+      onboardingHooks.observe = previousObserve;
       bootstrap.bootstrapHooks.loadPin = prevPin;
       rmSync(tmp, { recursive: true, force: true });
     },
@@ -251,6 +278,49 @@ const missingProbe = {
   node_path: null, node_version: null, node_usable: false, profile_has_volta: false,
 };
 
+test("Linux SSH bootstrap and enrollment preserve remote paths on every controller platform", () => {
+  const fx = cliFixture();
+  const connectionNode = posix.join(fx.target, "_host/toolchains/ops/volta/bin/ops-node");
+  const mock = mockTransport({ probeJson: missingProbe, applyJson: { status: "installed", connection_node: connectionNode, profile_unchanged: true } });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" });
+    fx.confirm(host);
+    const conn = writeConn(fx.tmp, host);
+    const r = captureMain(["bootstrap-node", "--state", fx.state, "--host-id", host.host_id, "--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 boot = JSON.parse(r.stdout), pins = pinFor(fx.archives).archives["linux-x64"];
+    const paths = [pins.volta.filename, pins.node.filename].map(name => posix.join(fx.target, "_host/installers", name));
+    assert.deepEqual(mock.log.filter(e => e.cmd === "scp").map(e => e.args.at(-1)), paths.map(p => "ops@host.invalid:" + p));
+    const applyArgs = splitRemote(mock.log.find(e => e.cmd === "ssh" && e.args.at(-1).includes("--apply")).args.at(-1));
+    assert.deepEqual(applyArgs.slice(applyArgs.indexOf("--apply") + 1), [paths[0], fx.archives.voltaSha, paths[1], fx.archives.nodeSha, posix.dirname(posix.dirname(connectionNode)), fx.archives.nodeVersion, ACK]);
+    assert.equal(JSON.parse(readFileSync(boot.receipt, "utf8")).connection_node, connectionNode);
+    assert.deepEqual(Object.keys(model.load(fx.state).hosts), []);
+    // A new confirmation cannot reset an interrupted bootstrap's machine/root guard.
+    fx.confirm(host); writeConn(fx.tmp, host);
+    const retryArgs = ["bootstrap-node", "--state", fx.state, "--host-id", host.host_id, "--connection-file", conn, "--apply", "--account", "ops", "--host-root", fx.target, "--ack", ACK,
+      "--volta-archive", fx.archives.voltaTar, "--node-archive", fx.archives.nodeTar];
+    const blockedRetry = captureMain(retryArgs); assert.equal(blockedRetry.code, 2); assert.match(blockedRetry.stderr, /already started/);
+    assert.equal(mock.log.filter(e => e.cmd === "scp").length, 2);
+    const recovered = captureMain([...retryArgs, "--recover-ack", "I-VERIFIED-BOOTSTRAP-IS-STOPPED", "--recovery-statement", "Fixture only: the simulated old process is stopped; retry exactly the same pinned inputs"]);
+    assert.equal(recovered.code, 0, recovered.stderr);
+    assert.ok(readdirSync(join(fx.state, "hosts", host.host_id, "bootstrap")).some(n => n.startsWith("recovery-")));
+    mock.restore();
+    host.connection.node = connectionNode;
+    const enrollFile = join(fx.tmp, "register.json"); writeFileSync(enrollFile, JSON.stringify({ hosts: [host], projects: [] }));
+    const inventory = { identity: "a".repeat(64), platform: "linux", tools: { node: { path: connectionNode, version: "v24.21.0" } } };
+    const enrolledMock = mockTransport({ probeJson: { ...missingProbe, tools: { ...missingProbe.tools, node: connectionNode }, node_path: connectionNode, node_usable: true }, agentJson: inventory });
+    try {
+      const enrolled = captureMain(["--state", fx.state, "enroll", "--file", enrollFile]);
+      assert.equal(enrolled.code, 0, enrolled.stderr);
+      assert.equal(model.load(fx.state).hosts[host.host_id].connection.node, connectionNode);
+      const snapshot = JSON.parse(enrolled.stdout).hosts[0].snapshot;
+      assert.deepEqual(JSON.parse(readFileSync(snapshot, "utf8")), inventory);
+      assert.equal(enrolledMock.log.filter(e => e.args.at(-1).includes("--input-type=module")).length, 2);
+    } finally { enrolledMock.restore(); }
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
 test("discover probe without node returns node-missing", () => {
   const fx = cliFixture();
   const mock = mockTransport({ probeJson: missingProbe });
@@ -300,6 +370,18 @@ test("bootstrap-node apply without ack blocked", () => {
   } finally { mock.restore(); fx.cleanup(); }
 });
 
+test("bootstrap with valid archives but no root confirmation cannot write or upload", () => {
+  const fx = cliFixture(), mock = mockTransport({ probeJson: missingProbe });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" }), conn = writeConn(fx.tmp, host);
+    const r = captureMain(["bootstrap-node", "--state", fx.state, "--host-id", host.host_id, "--connection-file", conn, "--apply", "--account", "ops", "--host-root", fx.target, "--ack", ACK,
+      "--volta-archive", fx.archives.voltaTar, "--node-archive", fx.archives.nodeTar]);
+    assert.equal(r.code, 2); assert.match(r.stderr, /root-confirm/);
+    assert.equal(mock.log.filter(e => e.cmd === "scp").length, 0);
+    assert.ok(mock.log.every(e => e.args.at(-1).includes("--probe")));
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
 test("bootstrap-node sha mismatch blocked", () => {
   const fx = cliFixture();
   const mock = mockTransport({ probeJson: missingProbe });
@@ -313,6 +395,7 @@ test("bootstrap-node sha mismatch blocked", () => {
       "--node-archive", fx.archives.nodeTar, "--node-sha256", fx.archives.nodeSha,
     ]);
     assert.equal(r.code, 2);
+    assert.match(r.stderr, /sha256 does not match the reviewed pin/i);
     assert.ok(!mock.log.some((e) => String(e.args.at(-1) || "").includes("--apply")));
   } finally { mock.restore(); fx.cleanup(); }
 });
@@ -362,8 +445,8 @@ test("bootstrap-node skips when node exists", () => {
   } finally { mock.restore(); fx.cleanup(); }
 });
 
-test("bootstrap-node apply then enroll writes inventory and status", () => {
-  const fx = cliFixture();
+test("bootstrap-node apply then enroll writes inventory and status", linuxExecution, () => {
+  const fx = cliFixture({ executeLinux: true });
   const home = join(fx.tmp, "home");
   mkdirSync(home);
   writeFileSync(join(home, ".bashrc"), "keep-me\n");
@@ -372,6 +455,7 @@ test("bootstrap-node apply then enroll writes inventory and status", () => {
   const mock = mockTransport({ probeJson: missingProbe });
   try {
     const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" });
+    fx.confirm(host);
     const conn = writeConn(fx.tmp, host);
     const applied = captureMain([
       "bootstrap-node", "--state", fx.state, "--host-id", "wsl-a",
@@ -435,10 +519,11 @@ test("enroll without node blocked", () => {
 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 },
+    probeJson: { ...missingProbe, tools: { ...missingProbe.tools, node: "/usr/bin/node" }, node_path: "/usr/bin/node", node_usable: true },
+    agentJson: { identity: "a".repeat(64), platform: "linux" },
   });
   try {
-    const host = sshHost({ root: fx.target, kh: fx.kh, node: process.execPath, identity: "discover" });
+    const host = sshHost({ root: fx.target, kh: fx.kh, identity: "discover" });
     const conn = writeConn(fx.tmp, host);
     const r = captureMain(["probe", "--connection-file", conn]);
     assert.equal(r.code, 0, r.stderr);
@@ -461,7 +546,7 @@ test("environmentSpec uses managed volta path", () => {
     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 legacy = model.load(state); legacy.hosts[host.host_id] = host; model.save(state, legacy); // existing runtime, no fabricated confirmation
   const prev = recipes.hostRecipesHooks.call;
   const voltaBin = core.targetJoin(host, "_host/toolchains/ops/volta/bin/volta");
   recipes.hostRecipesHooks.call = (_h, req) => {
@@ -497,7 +582,7 @@ test("environmentSpec still throws when volta truly absent", () => {
     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 legacy = model.load(state); legacy.hosts[host.host_id] = host; model.save(state, legacy); // existing runtime, no fabricated confirmation
   const prev = recipes.hostRecipesHooks.call;
   recipes.hostRecipesHooks.call = (_h, req) => {
     if (req.action === "snapshot") return { paths: { [req.paths[0]]: { kind: "absent" } } };

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

@@ -0,0 +1,225 @@
+/** Root-consent contracts, simulated SSH and real disposable local initialization. */
+import assert from "node:assert/strict";
+import test from "node:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { emptyStatus, digest, writeJson } from "../tools/opslib/core.mjs";
+import { load, register, save, validate } from "../tools/opslib/model.mjs";
+import { discoverServer, confirmServerRoot, validateRootConfirmation, onboardingHooks, observeServer, parseLinuxDiscovery } from "../tools/opslib/onboarding.mjs";
+import { call, transportHooks } from "../tools/opslib/transport.mjs";
+import { initializeHostSpec, connectionSpec, hostRecipesHooks } from "../tools/opslib/host_recipes.mjs";
+import { compilePlan, plannerHooks } from "../tools/opslib/planner.mjs";
+import { approval, apply } from "../tools/opslib/execution.mjs";
+import { fileState } from "../tools/opslib/agent.mjs";
+import { generateFleet } from "../tools/opslib/fleet.mjs";
+
+function fixture(t, local = false) {
+  const dir = mkdtempSync(join(tmpdir(), "ops-onboard-")), state = join(dir, "state");
+  mkdirSync(state); mkdirSync(join(state, "private"));
+  const registry = emptyStatus();
+  registry.controller = { controller_id: "fixture", state_root: state, created_at: "2026-01-01T00:00:00Z" };
+  writeFileSync(join(state, "status.json"), JSON.stringify(registry));
+  writeFileSync(join(state, "private/credentials.json"), '{"schema_version":1,"entries":{}}', { mode: 0o600 });
+  const knownHosts = join(dir, "known_hosts"); writeFileSync(knownHosts, "synthetic pinned key\n");
+  const host = { host_id: "node-a", display_name: "Node A", platform: local ? process.platform === "win32" ? "windows" : process.platform : "linux",
+    transport: local ? "local" : "ssh", root: local ? join(dir, "target") : "/home/wta/ops", identity: "a".repeat(64),
+    connection: local ? {} : { hostname: "server.invalid", username: "wta", known_hosts: knownHosts, node: "/usr/bin/node", sudo: true } };
+  const prev = onboardingHooks.observe;
+  let facts = { identity: host.identity, platform: "linux", username: "wta", uid: "1000", home: "/home/wta", node: null, node_version: null };
+  let check = { exists: false, writable: true, nonempty: false, owner: null };
+  if (!local) onboardingHooks.observe = (_h, root) => ({ ...facts, ...(root ? { root_check: { ...check } } : {}) });
+  t.after(() => { onboardingHooks.observe = prev; rmSync(dir, { recursive: true, force: true }); });
+  return { dir, state, host, knownHosts, facts: (v) => { facts = { ...facts, ...v }; }, check: (v) => { check = { ...check, ...v }; },
+    discover: () => discoverServer(state, host.host_id, host),
+    confirm(root = host.root) {
+      const d = discoverServer(state, host.host_id, host);
+      const r = confirmServerRoot(state, host.host_id, d.discovery.receipt_id, root, "fixture-user", "Use this exact isolated root for this fixture");
+      Object.assign(host, { root: r.root, identity: r.identity, root_confirmation: r.root_confirmation });
+      return r;
+    } };
+}
+
+function wire(values) { return Object.entries(values).map(([k, v]) => k + "=" + Buffer.from(v).toString("hex")).join("\n") + "\n"; }
+const accountWire = { machine: "fixture-machine", system: "Linux", username: "wta", uid: "1000", home: "/accounts/wta", node: "", node_version: "" };
+
+test("Linux wire discovery reads account database home, rejects malformed/noisy responses", () => {
+  const r = parseLinuxDiscovery(wire(accountWire));
+  assert.equal(r.home, "/accounts/wta"); assert.equal(r.node, null);
+  assert.equal(r.identity, digest({ machine: "fixture-machine", platform: "Linux" }));
+  for (const input of ["banner\n" + wire(accountWire), wire(accountWire) + "home=00\n", "home=xyz\n"]) assert.throws(() => parseLinuxDiscovery(input));
+});
+
+test("sudo-enabled Linux SSH discovery is unprivileged and does not need Node", (t) => {
+  const f = fixture(t), prev = transportHooks.spawnSync;
+  t.after(() => { transportHooks.spawnSync = prev; });
+  let called = false;
+  transportHooks.spawnSync = (cmd, args, options) => {
+    called = true; assert.equal(cmd, "ssh"); assert.ok(args.includes("StrictHostKeyChecking=yes"));
+    assert.ok(!args.at(-1).includes("sudo")); assert.ok(!args.at(-1).includes("node"));
+    assert.ok(options.input.toString().includes('getent passwd "$uid"'));
+    return { status: 0, stdout: wire(accountWire), stderr: "" };
+  };
+  assert.equal(observeServer(f.host).username, "wta"); assert.ok(called);
+});
+
+test("root, ordinary and custom account homes generate suggestions, never confirmation", (t) => {
+  const f = fixture(t);
+  for (const [username, uid, home] of [["root", "0", "/root"], ["wta", "1000", "/home/wta"], ["service_user", "1001", "/accounts/service user"]]) {
+    f.host.connection.username = username; f.facts({ username, uid, home });
+    const d = f.discover(); assert.equal(d.suggested_root, home + "/ops");
+    assert.deepEqual(load(f.state).hosts, {});
+    assert.throws(() => register(f.state, { hosts: [f.host] }), /requires server-root-confirm/);
+  }
+  assert.equal(existsSync(join(f.dir, "target")), false);
+});
+
+test("confirmed root locks retain login ownership while approved steps can use sudo", (t) => {
+  const f = fixture(t), prev = transportHooks.spawnSync;
+  t.after(() => { transportHooks.spawnSync = prev; });
+  const commands = [];
+  transportHooks.spawnSync = (_cmd, args) => {
+    commands.push(args.at(-1));
+    return { status: 0, stdout: JSON.stringify({ ok: true, result: {} }), stderr: "" };
+  };
+  f.host.root_confirmation = { receipt_id: "root-test", digest: "b".repeat(64) };
+  for (const action of ["lock", "step", "unlock"]) call(f.host, { action });
+  assert.equal(commands[0].startsWith("sudo "), false);
+  assert.equal(commands[1].startsWith("sudo -n -- "), true);
+  assert.equal(commands[2].startsWith("sudo "), false);
+  delete f.host.root_confirmation;
+  call(f.host, { action: "lock" });
+  assert.equal(commands[3].startsWith("sudo -n -- "), true, "legacy privilege behavior is unchanged");
+});
+
+test("invalid endpoint and missing controller initialization fail before probing", (t) => {
+  const f = fixture(t); onboardingHooks.observe = () => assert.fail("invalid inputs must not reach a target");
+  assert.throws(() => discoverServer(f.state, "node-a", { ...f.host, connection: { ...f.host.connection, password: "synthetic-only" } }), /unknown/);
+  const s = load(f.state); s.controller = null; save(f.state, s);
+  assert.throws(() => f.discover(), /initialize the controller/);
+});
+
+test("Windows account discovery accepts SSH account casing and uses its actual home", (t) => {
+  const f = fixture(t);
+  f.host.platform = "windows"; f.host.connection.username = "WTA"; f.host.connection.shell = "powershell";
+  f.facts({ platform: "windows", username: "wta", uid: "-1", home: "D:\\Profiles\\wta" });
+  assert.equal(f.discover().suggested_root, "D:\\Profiles\\wta\\ops");
+  f.facts({ username: "different-user" }); assert.throws(() => f.discover(), /login account differs/);
+});
+
+test("explicit default/custom roots register with immutable evidence and repeat without new consent", (t) => {
+  const f = fixture(t); f.confirm("/data/ops");
+  const ref = structuredClone(f.host.root_confirmation);
+  register(f.state, { hosts: [f.host] }); register(f.state, { hosts: [f.host] });
+  assert.equal(load(f.state).hosts["node-a"].root, "/data/ops");
+  assert.deepEqual(load(f.state).hosts["node-a"].root_confirmation, ref);
+  assert.equal(f.discover().suggested_root, "/data/ops");
+  assert.throws(() => f.confirm("/new-root"), /immutable/);
+  const other = { ...f.host, host_id: "node-b", root: "/other/ops" };
+  assert.throws(() => register(f.state, { hosts: [other] }), /reuse Host/);
+  assert.throws(() => discoverServer(f.state, "node-b", other), /reuse Host/);
+});
+
+test("missing user statement, unsafe paths, nonempty roots, permissions and ownership block confirmation", (t) => {
+  const f = fixture(t), d = f.discover();
+  const confirm = (root = f.host.root, statement = "Use this isolated root") => confirmServerRoot(f.state, "node-a", d.discovery.receipt_id, root, "user", statement);
+  for (const statement of ["", "   "]) assert.throws(() => confirm(f.host.root, statement), /confirmation/);
+  for (const root of ["relative", "/", "/root", "/home/wta", "/etc/nested", "/data/../root", "/data/ops\n", "/data\\ops"]) assert.throws(() => confirm(root));
+  f.check({ writable: false }); assert.throws(() => confirm(), /writable/);
+  f.check({ writable: true, exists: true, nonempty: true }); assert.throws(() => confirm(), /unowned/);
+  f.check({ owner: { host_id: "other", identity: f.host.identity } }); assert.throws(() => confirm(), /ownership/);
+  assert.deepEqual(load(f.state).hosts, {});
+});
+
+test("identity, home, trust and receipt drift never authorize the changed target", (t) => {
+  const f = fixture(t), d = f.discover();
+  const confirm = () => confirmServerRoot(f.state, "node-a", d.discovery.receipt_id, f.host.root, "user", "Use this exact root");
+  f.facts({ home: "/changed/home" }); assert.throws(confirm, /drift/);
+  f.facts({ home: "/home/wta", identity: "b".repeat(64) }); assert.throws(confirm, /drift/);
+  f.facts({ identity: "a".repeat(64) });
+  writeFileSync(f.knownHosts, "changed host key"); assert.throws(confirm, /trust changed/);
+  f.confirm();
+  assert.throws(() => register(f.state, { hosts: [{ ...f.host, root: "/elsewhere/ops" }] }), /mismatch/);
+  const receipt = join(f.state, "records/servers/node-a/onboarding", f.host.root_confirmation.receipt_id + ".json");
+  const data = JSON.parse(readFileSync(receipt)); data.statement = "tampered"; writeFileSync(receipt, JSON.stringify(data));
+  assert.throws(() => register(f.state, { hosts: [f.host] }), /mismatch/);
+});
+
+test("same-machine connection update preserves the selected root and verifies new account access", (t) => {
+  const f = fixture(t); f.confirm(); register(f.state, { hosts: [f.host] });
+  f.facts({ username: "root", uid: "0", home: "/root" });
+  const endpoint = { ...f.host, connection: { ...f.host.connection, username: "root" } };
+  const spec = connectionSpec(f.state, "node-a", endpoint);
+  assert.equal(spec.resource_updates.hosts[0].root, "/home/wta/ops");
+  assert.deepEqual(spec.resource_updates.hosts[0].root_confirmation, f.host.root_confirmation);
+  assert.equal(load(f.state).hosts["node-a"].connection.username, "wta");
+  f.check({ writable: false }); assert.throws(() => connectionSpec(f.state, "node-a", endpoint), /writable/);
+});
+
+test("legacy v3 roots and evidence stay unchanged; ambiguous reconnection is blocked", (t) => {
+  const f = fixture(t), s = load(f.state); s.hosts["node-a"] = { ...f.host, root: "/srv/ops" }; save(f.state, s);
+  const before = readFileSync(join(f.state, "status.json"));
+  assert.equal(f.discover().suggested_root, "/srv/ops");
+  assert.equal(validateRootConfirmation(f.state, s.hosts["node-a"]), null);
+  assert.deepEqual(readFileSync(join(f.state, "status.json")), before);
+  s.hosts["old-second"] = { ...s.hosts["node-a"], host_id: "old-second", root: "/srv/second" }; save(f.state, s);
+  assert.throws(() => f.discover(), /ambiguous legacy/);
+});
+
+test("real local root rejects symlink ancestors and existing unrelated files", (t) => {
+  const f = fixture(t, true), real = join(f.dir, "real"), link = join(f.dir, "link"); mkdirSync(real);
+  symlinkSync(real, link, process.platform === "win32" ? "junction" : "dir");
+  assert.throws(() => f.confirm(join(link, "ops")), /symlink|reparse/i);
+  mkdirSync(f.host.root); writeFileSync(join(f.host.root, "README.md"), "User file, preserve");
+  assert.throws(() => f.confirm(), /unowned/);
+  assert.equal(readFileSync(join(f.host.root, "README.md"), "utf8"), "User file, preserve");
+});
+
+test("real local onboarding and approved minimal initialization deliver both sides, then reuse directories", (t) => {
+  const f = fixture(t, true); f.confirm(); register(f.state, { hosts: [f.host] });
+  assert.equal(existsSync(f.host.root), false, "registration must not create target directories");
+  const pp = plannerHooks.call, hp = hostRecipesHooks.call;
+  const inventory = (h, req) => ({ identity: h.identity, platform: h.platform, tools: {}, defaults: {}, diagnostics: {},
+    snapshots: Object.fromEntries((req.paths || []).map(p => [p, fileState(p)])) });
+  plannerHooks.call = inventory; hostRecipesHooks.call = inventory;
+  t.after(() => { plannerHooks.call = pp; hostRecipesHooks.call = hp; });
+  const spec = initializeHostSpec(f.state, "node-a");
+  assert.ok(spec.host_actions.length > 0); assert.ok(spec.host_actions.every(a => a.kind === "mkdir"));
+  const specPath = join(f.dir, "init.json"); writeJson(specPath, spec);
+  const plan = compilePlan(f.state, specPath);
+  assert.equal(existsSync(f.host.root), false, "planning must not prepare the target");
+  approval(f.state, plan.run_id, plan.plan_digest, "fixture-user", "Initialize only this disposable local Host");
+  const redirected = join(f.dir, "redirected"); mkdirSync(redirected);
+  symlinkSync(redirected, f.host.root, process.platform === "win32" ? "junction" : "dir");
+  assert.throws(() => apply(f.state, plan.run_id), /symlink|reparse/i);
+  assert.equal(existsSync(join(redirected, ".ops-host.json")), false);
+  unlinkSync(f.host.root);
+  const result = apply(f.state, plan.run_id); assert.equal(result.status, "completed", JSON.stringify(result));
+  for (const p of ["README.md", "DEPLOYMENTS.md", "docs/standards/DEPLOYMENT-STANDARD.md", ".ops-host.json"]) assert.ok(existsSync(join(f.host.root, p)), p);
+  assert.equal(initializeHostSpec(f.state, "node-a").host_actions.length, 0);
+  assert.equal(existsSync(join(f.host.root, "_runtime/docker")), false, "minimal initialization never installs Docker");
+  const previous = onboardingHooks.observe; onboardingHooks.observe = () => assert.fail("V must not connect to targets");
+  try {
+    const view = generateFleet(f.state); const data = JSON.parse(readFileSync(view.json)); validate(data, "fleet-view");
+    assert.equal(data.servers[0].root_confirmation.status, "confirmed");
+    assert.equal(data.servers[0].initialization.documents, "both-sides-verified");
+    assert.equal(data.servers[0].initialization.runtime, "unverified");
+    assert.ok(!readFileSync(view.html, "utf8").includes("Use this exact isolated root"));
+    const s = load(f.state), last = s.releases[plan.run_id];
+    s.releases["pending-fixture"] = { ...last, run_id: "pending-fixture", status: "docs_pending", updated_at: new Date(Date.now() + 2000).toISOString() };
+    save(f.state, s);
+    const pending = JSON.parse(readFileSync(generateFleet(f.state).json));
+    assert.equal(pending.servers[0].initialization.documents, "unknown", "an older receipt cannot conceal a newer pending delivery");
+  } finally { onboardingHooks.observe = previous; }
+});
+
+test("Linux shell adapter matches real account identity without creating the selected root", { skip: process.platform !== "linux" && "Linux shell execution requires a Linux runner" }, (t) => {
+  const f = fixture(t, true), script = fileURLToPath(new URL("../tools/server-discover.sh", import.meta.url));
+  const run = spawnSync("/bin/sh", [script, f.host.root], { encoding: "utf8", timeout: 30000 });
+  assert.equal(run.status, 0, run.stderr);
+  const shell = parseLinuxDiscovery(run.stdout, true), native = observeServer(f.host, f.host.root);
+  for (const key of ["identity", "username", "uid", "home"]) assert.equal(shell[key], native[key]);
+  assert.equal(existsSync(f.host.root), false);
+});