@namewta/speculo 1.0.19 → 1.0.21

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

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
 import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, existsSync, statSync, symlinkSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, posix } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { digest, emptyStatus, now, writeJson } from "../tools/opslib/core.mjs";
@@ -18,7 +18,7 @@ function fixture(t) {
   t.after(() => rmSync(root, { recursive: true, force: true }));
   const state = join(root, "state"); mkdirSync(state);
   const s = emptyStatus(); s.controller = { controller_id: "controller-a", state_root: state, created_at: now() };
-  for (const id of ["node-a", "node-b"]) s.hosts[id] = { host_id: id, display_name: id, platform: "linux", transport: "local", root: join(root, id), identity: "a".repeat(64), connection: {} };
+  for (const id of ["node-a", "node-b"]) s.hosts[id] = { host_id: id, display_name: id, platform: process.platform === "win32" ? "windows" : "linux", transport: "local", root: join(root, id), identity: "a".repeat(64), connection: {} };
   for (const id of ["app-a", "app-b"]) s.projects[id] = { project_id: id, display_name: id, kind: "app", service_type: null, source: { type: "local", location: join(root, "source"), revision: "v1" } };
   writeJson(join(state, "status.json"), s);
   const save = () => writeJson(join(state, "status.json"), s);
@@ -32,7 +32,13 @@ function request(id = "task-one") {
 function inventory(h) {
   return { identity: h.identity, platform: "linux", tools: { node: { version: "v22.22.3" } },
     snapshots: { [h.root]: { kind: "directory" } }, diagnostics: { disks: { [h.root]: { free: 4 * 1024 ** 3 } }, memory: { MemAvailable: 1024 ** 3 } },
-    docker_control: { status: "observed", endpoint: "unix:///var/run/docker.sock", data_root: join(h.root, "_runtime/docker"), compose_version: "2.30.0" } };
+    docker_control: { status: "observed", endpoint: "unix:///var/run/docker.sock", data_root: posix.join(h.root, "_runtime/docker"), compose_version: "2.30.0" } };
+}
+function linuxServer(f) {
+  return Object.assign(f.s.hosts["node-a"], { platform: "linux", root: "/srv/speculo-test/node-a" });
+}
+function directoryLink(target, path) {
+  symlinkSync(target, path, process.platform === "win32" ? "junction" : "dir");
 }
 function adapterFor(f, options = {}) {
   const calls = { compile: 0, approve: 0, apply: 0 };
@@ -76,7 +82,7 @@ test("explicit layer routing distinguishes controller, access, server, project a
 test("workspace rejects guessed roots, traversal, symlinks, duplicate JSON keys and orphan deployments", (t) => {
   const f = fixture(t);
   for (const path of [".", "/", f.state + "/../state"]) assert.throws(() => statePath(path));
-  const link = join(f.root, "linked"); symlinkSync(f.state, link, "dir"); assert.throws(() => statePath(link), /symlink/);
+  const link = join(f.root, "linked"); directoryLink(f.state, link); assert.throws(() => statePath(link), /symlink/);
   writeFileSync(join(f.state, "status.json"), '{"schema_version":3,"schema_version":3}'); assert.throws(() => readRegistry(f.state), /duplicate JSON/);
   f.s.deployments.dangling = { deployment_id: "dangling", host_id: "missing", project_id: "app-a" }; f.save(); assert.throws(() => readRegistry(f.state), /orphan/);
 });
@@ -90,7 +96,7 @@ test("CLI help works without network, server dependencies or state", () => {
   const r = spawnSync(process.execPath, [path, "workspace-help"], { encoding: "utf8" }); assert.equal(r.status, 0, r.stderr); assert.match(r.stdout, /server-check/);
 });
 test("Linux checklist distinguishes missing, failed, profile-ready and stale evidence", (t) => {
-  const f = fixture(t), h = f.s.hosts["node-a"], inv = inventory(h), at = new Date("2026-01-01T00:00:00Z");
+  const f = fixture(t), h = linuxServer(f), inv = inventory(h), at = new Date("2026-01-01T00:00:00Z");
   assert.equal(readiness(assessServer(h), at.toISOString(), { at }), "unknown");
   assert.equal(readiness(assessServer(h, { profile: "compose", inventory: inv }), at.toISOString(), { at }), "ready");
   assert.equal(readiness(assessServer(h, { profile: "compose", inventory: inv }), at.toISOString(), { at: new Date("2026-01-03T00:00:00Z") }), "stale");
@@ -100,7 +106,7 @@ test("Linux checklist distinguishes missing, failed, profile-ready and stale evi
   }
 });
 test("server check uses pinned public-key-only SSH and records restricted evidence", async (t) => {
-  const f = fixture(t), h = f.s.hosts["node-a"], kh = join(f.root, "known_hosts"); writeFileSync(kh, "fixture verified key");
+  const f = fixture(t), h = linuxServer(f), kh = join(f.root, "known_hosts"); writeFileSync(kh, "fixture verified key");
   Object.assign(h, { transport: "ssh", connection: { hostname: "example.invalid", username: "deploy", known_hosts: kh } }); f.save();
   let spawned = 0, called = 0;
   const a = { sshArgv: () => ["ssh", "-o", "StrictHostKeyChecking=yes"], spawn: (_cmd, args) => { spawned++; assert.ok(args.includes("PasswordAuthentication=no")); assert.ok(args.includes("KbdInteractiveAuthentication=no")); return { status: 0 }; }, call: () => { called++; return inventory(h); } };
@@ -111,7 +117,7 @@ test("server check uses pinned public-key-only SSH and records restricted eviden
   writeFileSync(kh, "different key"); assert.notEqual(check.host_digest, targetDigest(h));
 });
 test("failed SSH login never triggers Node probe and is not reported ready", async (t) => {
-  const f = fixture(t), h = f.s.hosts["node-a"], kh = join(f.root, "known_hosts"); writeFileSync(kh, "fixture"); Object.assign(h, { transport: "ssh", connection: { hostname: "invalid", username: "deploy", known_hosts: kh } }); f.save();
+  const f = fixture(t), h = linuxServer(f), kh = join(f.root, "known_hosts"); writeFileSync(kh, "fixture"); Object.assign(h, { transport: "ssh", connection: { hostname: "invalid", username: "deploy", known_hosts: kh } }); f.save();
   const r = await checkServer(f.state, "node-a", {}, { sshArgv: () => ["ssh"], spawn: () => ({ status: 255 }), call: () => { throw new Error("must not probe"); } });
   assert.equal(r.status, "blocked"); assert.equal(r.checks.find(c => c.id === "machine-identity").status, "unknown");
 });
@@ -210,7 +216,10 @@ test("fleet writes immutable generations, verifies readback and retains one cons
   const before = readFileSync(first.markdown, "utf8"); writeFileSync(first.html, "tampered"); assert.throws(() => generateFleet(f.state, { at }), /readback mismatch/); assert.equal(readFileSync(first.markdown, "utf8"), before);
 });
 test("fleet refuses symlink outputs and catalog locks without overwriting old entry", (t) => {
-  const f = fixture(t), outside = join(f.root, "outside.txt"); writeFileSync(outside, "untouched"); symlinkSync(outside, join(f.state, "FLEET.md"));
+  const f = fixture(t), outsideDir = join(f.root, "outside"), outside = join(outsideDir, "sentinel.txt");
+  mkdirSync(outsideDir); writeFileSync(outside, "untouched");
+  if (process.platform === "win32") directoryLink(outsideDir, join(f.state, "FLEET.md"));
+  else symlinkSync(outside, join(f.state, "FLEET.md"));
   assert.throws(() => generateFleet(f.state), /symlink/); assert.equal(readFileSync(outside, "utf8"), "untouched");
   rmSync(join(f.state, "FLEET.md")); mkdirSync(join(f.state, ".locks/catalog"), { recursive: true }); assert.throws(() => generateFleet(f.state), /catalog lock/);
 });

package/template/workflows/ops/common/tools/demo-local.mjs

@@ -9,6 +9,7 @@ import { register, putCredential } from "./opslib/model.mjs";
 import { probeLocal } from "./opslib/transport.mjs";
 import { compilePlan } from "./opslib/planner.mjs";
 import { approval, apply } from "./opslib/execution.mjs";
+import { discoverServer, confirmServerRoot } from "./opslib/onboarding.mjs";
 
 export function run(output) {
   output = resolve(output);
@@ -22,10 +23,13 @@ export function run(output) {
   const inventory = probeLocal();
   const platform = inventory.platform;
   if (!["linux", "darwin", "windows"].includes(platform)) throw new OpsError("unsupported platform");
+  const discovered = discoverServer(state, "demo-local", { platform, transport: "local", connection: {} });
+  const confirmed = confirmServerRoot(state, "demo-local", discovered.discovery.receipt_id, target, "demo-user", "Run this explicitly requested disposable demo only inside its new output/server directory.");
   register(state, {
     hosts: [{
       host_id: "demo-local", display_name: "Disposable local demo", platform, transport: "local",
       connection: {}, root: target, identity: inventory.identity,
+      root_confirmation: confirmed.root_confirmation,
     }],
     projects: [{
       project_id: "app-a", display_name: "Demo APP A", kind: "app", service_type: null,

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

@@ -775,10 +775,36 @@ export function benchmarkMirrors(req) {
   };
 }
 
+export function onboardingObservation(root = null) {
+  const account = userInfo();
+  const result = { identity: fingerprint(), platform: process.platform === "win32" ? "windows" : process.platform,
+    username: account.username, uid: String(account.uid), home: account.homedir, node: process.execPath, node_version: process.version };
+  if (root) {
+    if (!isAbsolute(root) || root.split(/[\\/]/).includes("..")) throw new Failure("unsafe discovery root");
+    noLinks(root);
+    let parent = root;
+    while (!existsSync(parent)) parent = dirname(parent);
+    if (!statSync(parent).isDirectory()) throw new Failure("root ancestor is not a directory");
+    let writable = true;
+    try { accessSync(parent, fsConstants.W_OK | fsConstants.X_OK); } catch { writable = false; }
+    const present = existsSync(root);
+    for (const rel of [".ops-host.json", "_host", "_runtime", "docs", "knowledge", "README.md", "DEPLOYMENTS.md"]) noLinks(join(root, rel));
+    const marker = join(root, ".ops-host.json");
+    let owner = null;
+    if (existsSync(marker)) {
+      if (!statSync(marker).isFile() || statSync(marker).size > 16384) throw new Failure("invalid root owner marker");
+      owner = rj(marker);
+    }
+    result.root_check = { exists: present, writable, nonempty: present && readdirSync(root).length > 0, owner };
+  }
+  return result;
+}
+
 export function main(req) {
   const identity = fingerprint();
   if (req.identity && identity !== req.identity) throw new Failure("target identity drift");
   const action = req.action;
+  if (action === "onboarding") return onboardingObservation(req.root);
   if (action === "probe") return inventory(req);
   if (action === "mirror-probe") return benchmarkMirrors(req);
   if (action === "snapshot") return { identity, paths: Object.fromEntries((req.paths || []).map((p) => [p, fileState(p)])), at: stamp() };

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

@@ -1,15 +1,16 @@
 /** 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 { dirname, basename, join, posix as posixPath } 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 { digest, exact, identifier, newId, noSymlinks, NodeMissing, now, OpsError, privateDir, readJson, rootPath, targetJoin, withLock, writeJson } from "./core.mjs";
 import { register, validateHost } from "./model.mjs";
 import { call, posixCall, posixSend, validateSshEndpoint } from "./transport.mjs";
+import { confirmedBootstrapHost, validateRootConfirmation } from "./onboarding.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 SCRIPT = readFileSync(join(TOOLS, "bootstrap-volta.sh"), "utf8").replace(/\r\n?/g, "\n");
 const PIN_PATH = join(TOOLS, "..", "toolchains", "volta-linux.json");
 
 export function loadVoltaPin() {
@@ -47,7 +48,7 @@ function parseJsonLine(stdout, label) {
 export function posixProbe(endpoint, nodePath) {
   const args = ["--probe"];
   if (nodePath) args.push(String(nodePath));
-  const r = posixCall(endpoint, SCRIPT, { args });
+  const r = posixCall(endpoint, SCRIPT, { args, sudo: false });
   return parseJsonLine(r.stdout, "posix probe");
 }
 
@@ -124,7 +125,7 @@ export function bootstrapNode(args) {
   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");
+  if (!/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,79}$/.test(args.account)) throw new OpsError("unsafe 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);
@@ -139,29 +140,53 @@ export function bootstrapNode(args) {
     allowNetwork: Boolean(args.allow_network), cacheDir, label: "Node",
   });
 
+  // Only read operations precede confirmation. The remote write gate is shared with H/D.
+  const confirmed = confirmedBootstrapHost(args.state, host, args.host_id, hostRoot);
+  if (args.account !== endpoint.username) throw new OpsError("bootstrap account must be the observed SSH login account");
+  if (/[\s\\\0]/.test(hostRoot)) throw new OpsError("Node bootstrap scp requires a root without whitespace or backslashes; use an existing Node or a supported dedicated path");
+
   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,
+  return withLock(join(args.state, ".locks", "catalog"), { operation: "bootstrap-node", host_id: args.host_id }, () => {
+    validateRootConfirmation(args.state, confirmed, { fresh: true, freshLegacy: true, checkEndpoint: true });
+    const rootConfirmation = confirmed.root_confirmation ?? null;
+    const attempt = join(args.state, "hosts", args.host_id, "bootstrap", "attempt-" + digest({ identity: confirmed.identity, root: hostRoot }).slice(0, 24) + ".json");
+    const inputDigest = digest({ identity: confirmed.identity, root: hostRoot, account: args.account, node_version: nodeVersion, volta_sha256: volta.sha256, node_sha256: node.sha256 });
+    noSymlinks(attempt);
+    if (existsSync(attempt)) {
+      const previous = readJson(attempt);
+      if (args.recover_ack !== "I-VERIFIED-BOOTSTRAP-IS-STOPPED" || !args.recovery_statement?.trim()) throw new OpsError("bootstrap already started; inspect " + attempt + " and remote state, then explicitly supply --recover-ack I-VERIFIED-BOOTSTRAP-IS-STOPPED --recovery-statement with the actual recovery authorization; never replay blindly");
+      if (previous.input_digest !== inputDigest) throw new OpsError("bootstrap recovery inputs differ from the original attempt; preserve evidence and prepare a separate repair plan");
+      writeJson(join(dirname(attempt), newId("recovery") + ".json"), { previous_attempt: previous, ack: args.recover_ack, statement: args.recovery_statement, at: now() }, { exclusive: true });
+    }
+    writeJson(attempt, { status: "started", host_id: args.host_id, root: hostRoot, root_confirmation: rootConfirmation, input_digest: inputDigest, at: now() });
+    const owner = JSON.stringify({ host_id: args.host_id, identity: confirmed.identity });
+    // Match the existing agent-owned marker. Run as the login account so scp can write.
+    // Recheck links immediately before mkdir; never chown/chmod an existing parent.
+    posixCall(endpoint, "#!/bin/sh\nset -eu\numask 077\n[ ! -e \"$3/_host/execution.lock\" ] && [ ! -L \"$3/_host/execution.lock\" ] || { echo 'target execution lock exists; inspect before bootstrap' >&2; exit 2; }\nfor dest in \"$1\" \"$2\"; do p=$dest; while [ \"$p\" != / ]; do [ ! -L \"$p\" ] || exit 2; p=$(dirname -- \"$p\"); done; done\nmkdir -p -- \"$1\" \"$2\"\nif [ ! -e \"$3/.ops-host.json\" ]; then (set -C; printf '%s\\n' \"$4\" > \"$3/.ops-host.json\"); fi\n", { sudo: false, args: [installers, voltaHome, hostRoot, owner] });
+    const remoteVolta = posixPath.join(installers, volta.filename);
+    const remoteNode = posixPath.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,
+      sudo: false,
+    });
+    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() });
+      writeJson(attempt, { status: "installed", host_id: args.host_id, root: hostRoot, root_confirmation: rootConfirmation, input_digest: inputDigest, receipt, at: now() });
+      result.receipt = receipt;
+    }
+    return result;
   });
-  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) {
@@ -181,13 +206,14 @@ export function enroll(state, request) {
     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)) {
+    if (!posixPath.isAbsolute(host.connection.node) || host.connection.node.includes("\\")) {
       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);
+    validateRootConfirmation(state, host, { checkEndpoint: true });
     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");

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

@@ -223,6 +223,7 @@ function parseArgs(argv) {
     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");
+    grab("--recover-ack"); grab("--recovery-statement");
     out.probe = flag("--probe");
     out.apply = flag("--apply");
     out.allow_network = flag("--allow-network");

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

@@ -8,7 +8,7 @@ import { hostname } from "node:os";
 import { dirname, join, posix, win32 } from "node:path";
 import { spawnSync } from "node:child_process";
 
-export const VERSION = "2.2.0";
+export const VERSION = "2.3.0";
 const ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 export const SECRET_RE = /\{\{credential:([a-z0-9-]+)@([1-9][0-9]*):([A-Za-z_][A-Za-z0-9_]*)\}\}/g;
 

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

@@ -285,6 +285,7 @@ export function hostReadme(status, hid, runId, at, { ledger = null, full = false
   const out = [
     `# 主机 ${host.display_name} / ${hid}\n`,
     `主机持久化根：${code(host.root)}；更新：${at}；运行：${runId}。\n`,
+    `连接账号：${code(host.connection.username ?? "显式本机账号")}；根目录确认：${host.root_confirmation ? code(host.root_confirmation.receipt_id) : "既有登记（保留原根，不补造历史确认）"}。更换连接账号不改变该根。\n`,
     "APP 与公共服务同级。主机级入口（WireGuard/Nginx/探测）登记为 host_services，不是假的 APP 目录。通用规范见 docs/standards/DEPLOYMENT-STANDARD.md。\n",
     "## 服务一览\n",
     renderOverviewTable(rows, { includeCredentials }),

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

@@ -11,6 +11,7 @@ import { load, save, ledgerLoad, validate, validateStatus } from "./model.mjs";
 import { locatePlan, envFile, sliceDigest } from "./planner.mjs";
 import { call as transportCall, hostTransportDigest } from "./transport.mjs";
 import { deliveryBundle } from "./docs.mjs";
+import { validateRootConfirmation } from "./onboarding.mjs";
 
 const COMMON = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
@@ -18,6 +19,7 @@ export function defaultEngineDigest() {
   const opslib = join(COMMON, "tools", "opslib");
   const schemas = join(COMMON, "schemas");
   const files = [
+    join(COMMON, "tools", "server-discover.sh"),
     ...readdirSync(opslib).filter((n) => n.endsWith(".mjs")).map((n) => join(opslib, n)),
     ...readdirSync(schemas).filter((n) => n.endsWith(".json")).map((n) => join(schemas, n)),
   ].sort();
@@ -245,6 +247,7 @@ function deliver(state, folder, plan, status, execution, ledger) {
   }
   const receipt = { schema_version: 1, run_id: plan.run_id, plan_digest: digest(plan), completed_at: now(), documents: bundle.acks, status: "both-sides-verified" };
   writeJson(join(folder, "docs-receipt.json"), receipt);
+  for (const hid of Object.keys(plan.hosts)) writeJson(join(state, "hosts", hid, "docs-receipt.json"), receipt);
   for (const did of eligible) {
     const dep = status.deployments[did];
     writeJson(join(state, "hosts", dep.host_id, "deployments", did, "docs-receipt.json"), receipt);
@@ -279,6 +282,7 @@ export function apply(state, run, { resume = false, docsOnly = false } = {}) {
     verifyJournal(join(folder, "journal.jsonl"));
     for (const [hid, h] of Object.entries(plan.hosts)) {
       if (hostTransportDigest(h) !== plan.transport_digests[hid]) throw new OpsError("SSH connection/known_hosts changed since approval");
+      validateRootConfirmation(state, h, { fresh: true });
     }
     for (const [ref, wanted] of Object.entries(plan.credential_versions)) {
       const [cid, v] = ref.split("@");

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

@@ -5,6 +5,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { atomicWrite, digest, identifier, noSymlinks, OpsError, redact, withLock, writeJson } from "./core.mjs";
 import { catalogUnlocked, ids, readBoundedJson, readRegistry, statePath, targetDigest } from "./workspace.mjs";
+import { rootSummary } from "./onboarding.mjs";
 import { latestCheck, readiness } from "./server_checks.mjs";
 
 const TEMPLATE = join(dirname(fileURLToPath(import.meta.url)), "../../templates/FLEET.html");
@@ -44,7 +45,7 @@ function taskSummaries(state) {
   });
 }
 
-export function projectFleet(registry, checks = {}, tasks = [], { at = new Date(), staleHours = 24 } = {}) {
+export function projectFleet(registry, checks = {}, tasks = [], { at = new Date(), staleHours = 24, onboarding = {} } = {}) {
   if (!Number.isFinite(at.getTime()) || !Number.isFinite(staleHours) || staleHours <= 0 || staleHours > 8760) throw new OpsError("invalid inventory time/staleness policy");
   const deployments = sorted(registry.deployments).map((d) => ({
     deployment_id: d.deployment_id, project_id: d.project_id, server_id: d.host_id,
@@ -68,7 +69,11 @@ export function projectFleet(registry, checks = {}, tasks = [], { at = new Date(
     const own = byServer.get(h.host_id) || [];
     return { server_id: h.host_id, name: text(h.display_name), platform: text(h.platform), transport: h.transport,
       address: h.transport === "ssh" ? text(h.connection.hostname) : "local (explicit)", port: h.transport === "ssh" ? h.connection.port ?? 22 : null,
-      root: text(h.root), readiness: checkStatus, profile: c?.profile ?? null, checked_at: time(c?.checked_at),
+      root: text(h.root), login_account: text(h.connection.username ?? "local"),
+      root_confirmation: onboarding[h.host_id]?.root ?? { status: h.root_confirmation ? "unverified" : "legacy-registered", login_home: null, confirmed_at: null },
+      initialization: { registered: true, directory: checkStatus !== "stale" && checkStatus !== "unknown" ? c?.checks?.find(v => v.id === "deployment-root")?.status ?? "unknown" : "unknown",
+        documents: onboarding[h.host_id]?.documents ?? "unknown", runtime: checkStatus === "ready" && c?.profile !== "base" ? c.profile : "unverified" },
+      readiness: checkStatus, profile: c?.profile ?? null, checked_at: time(c?.checked_at),
       checks: (c?.checks || []).map((v) => ({ id: v.id, status: v.status, required: v.required })),
       project_ids: [...new Set(own.filter((d) => d.status !== "retired").map((d) => d.project_id))].sort(),
       deployment_ids: own.map((d) => d.deployment_id),
@@ -96,7 +101,7 @@ export function projectFleet(registry, checks = {}, tasks = [], { at = new Date(
 export function renderMarkdown(data, html = "index.html", json = "inventory.json") {
   const table = (headers, rows) => `| ${headers.join(" | ")} |\n| ${headers.map(() => "---").join(" | ")} |\n` + (rows.length ? rows.map((r) => `| ${r.map(md).join(" | ")} |`).join("\n") : `| ${headers.map((_, i) => i ? "—" : "暂无记录").join(" | ")} |`) + "\n";
   return `# OPS 服务器与部署清单\n\n[打开离线看板](${html}) · [结构化快照](${json})\n\n生成：${data.generated_at}；资源修订：${data.source_revision}；控制端：${data.controller_id}。\n\n这是离线记录，不是实时监控。ready 仅代表指定检查 profile 的必需项通过；completed 是历史执行结果。未测、过期、身份变化不视为正常。\n\n## 服务器 → 项目\n\n` +
-    table(["服务器", "名称 / 地址", "系统", "检查 / profile", "检查时间", "项目", "主机级服务"], data.servers.map((s) => [s.server_id, `${s.name} / ${s.address}`, s.platform, `${s.readiness} / ${s.profile ?? "未检查"}`, s.checked_at, s.project_ids.join(", "), s.host_services.map((v) => v.service_id).join(", ")])) +
+    table(["服务器", "名称 / 地址", "账号 / 持久化根", "根确认 / 文档", "系统", "检查 / profile", "检查时间", "项目", "主机级服务"], data.servers.map((s) => [s.server_id, `${s.name} / ${s.address}`, `${s.login_account} / ${s.root}`, `${s.root_confirmation.status} / ${s.initialization.documents}`, s.platform, `${s.readiness} / ${s.profile ?? "未检查"}`, s.checked_at, s.project_ids.join(", "), s.host_services.map((v) => v.service_id).join(", ")])) +
     `\n## 项目 → 服务器\n\n` + table(["项目", "名称", "类别", "服务器", "部署实例"], data.projects.map((p) => [p.project_id, p.name, p.kind, p.server_ids.join(", "), p.deployment_ids.join(", ")])) +
     `\n## 部署实例\n\n` + table(["部署", "项目", "服务器", "环境", "记录状态", "计划版本", "验证版本", "根目录"], data.deployments.map((d) => [d.deployment_id, d.project_id, d.server_id, d.environment, d.status, d.desired_version, d.observed_version, d.root])) +
     `\n## 任务记录\n\n` + table(["任务", "范围", "状态", "服务器", "Run"], data.tasks.map((t) => [t.task_id, t.scope, t.status, t.server_ids.join(", "), t.run_ids.join(", ")])) +
@@ -123,7 +128,24 @@ export function generateFleet(state, { at = new Date(), staleHours = 24 } = {})
     catalogUnlocked(state);
     const registry = readRegistry(state);
     const checks = Object.fromEntries(sorted(registry.hosts).map((h) => [h.host_id, latestCheck(state, h)]));
-    const data = projectFleet(registry, checks, taskSummaries(state), { at, staleHours });
+    const rootEvidence = Object.fromEntries(sorted(registry.hosts).map(h => {
+      const root = rootSummary(state, h);
+      const receiptPath = join(state, "hosts", h.host_id, "docs-receipt.json");
+      noSymlinks(receiptPath);
+      let documents = "unknown";
+      if (existsSync(receiptPath)) {
+        const receipt = readBoundedJson(receiptPath), release = registry.releases[receipt.run_id];
+        const localKey = "hosts/" + h.host_id + "/README.md";
+        const local = join(state, localKey); noSymlinks(local);
+        const remoteKey = "remote:" + h.host_id + ":" + (h.platform === "windows" ? h.root + "\\README.md" : h.root + "/README.md");
+        const unresolved = Object.values(registry.releases).some(r => r.host_ids.includes(h.host_id) && r.status !== "completed" && Date.parse(r.updated_at) >= Date.parse(release?.updated_at));
+        if (!unresolved && receipt.status === "both-sides-verified" && release?.status === "completed" && release.host_ids.includes(h.host_id)
+          && receipt.documents?.[remoteKey] && existsSync(local)
+          && receipt.documents?.["local:" + localKey]?.sha256 === digest(readFileSync(local))) documents = "both-sides-verified";
+      }
+      return [h.host_id, { root, documents }];
+    }));
+    const data = projectFleet(registry, checks, taskSummaries(state), { at, staleHours, onboarding: rootEvidence });
     const html = renderHtml(data), markdown = renderMarkdown(data);
     // Snapshot identity includes renderer bytes, so a template update cannot collide with an older view.
     const viewId = "view-" + digest({ data, html, markdown }).slice(0, 32);

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

@@ -2,9 +2,43 @@
 import { identifier, exact, newId, now, OpsError, targetJoin, within } from "./core.mjs";
 import { load } from "./model.mjs";
 import { call as transportCall } from "./transport.mjs";
+import { validateRootConfirmation, discoverServer } from "./onboarding.mjs";
 
 export const hostRecipesHooks = { call: transportCall };
 
+export function initializeHostSpec(state, hid) {
+  const status = load(state), host = status.hosts[hid];
+  if (!host) throw new OpsError("unknown server; complete S first");
+  validateRootConfirmation(state, host, { fresh: true });
+  const dirs = ["_host/cache", "_host/installers", "_host/toolchains", "_runtime", "docs/standards", "knowledge"];
+  const paths = dirs.map((p) => targetJoin(host, p));
+  const inventory = hostRecipesHooks.call(host, { action: "probe", paths, disk_roots: [host.root] }, { timeout: 180 });
+  if (inventory.identity !== host.identity) throw new OpsError("host initialization identity drift");
+  const actions = dirs.flatMap((path, i) => {
+    const observed = inventory.snapshots?.[paths[i]];
+    if (observed?.kind === "directory") return [];
+    if (observed?.kind !== "absent") throw new OpsError("initialization path conflict: " + paths[i]);
+    return [{ host_id: hid, kind: "mkdir", path, mode: 0o750, reason: "Prepare only the selected Host root; keep all existing data and account permissions" }];
+  });
+  return { schema_version: 1, worker: "H", operation: "prepare", hosts: [hid], host_actions: actions,
+    acknowledged_consumers: Object.values(status.deployments).filter((d) => d.host_id === hid && d.status !== "retired").map((d) => d.deployment_id).sort(),
+    reason: "Minimal Host initialization: managed directories and verified bilateral host documents; project runtimes are prepared only when needed",
+    rollback_note: "Preserve all existing directories and data. Inspect unknown runs; docs-sync repairs documents without reinstalling anything.", risk: "external-mutation" };
+}
+
+export function connectionSpec(state, hid, endpoint) {
+  const status = load(state), host = status.hosts[hid];
+  if (!host) throw new OpsError("unknown server; complete S first");
+  if (endpoint.platform !== host.platform || endpoint.transport !== host.transport) throw new OpsError("connection update cannot change platform or transport");
+  const discovery = discoverServer(state, hid, endpoint);
+  if (discovery.facts.identity !== host.identity) throw new OpsError("new connection is a different machine");
+  const updated = { ...host, connection: endpoint.connection };
+  validateRootConfirmation(state, updated, { fresh: true, freshLegacy: true });
+  return { schema_version: 1, worker: "H", operation: "maintain", hosts: [hid], resource_updates: { hosts: [updated] },
+    reason: "S verified connection update for the same machine; preserve Host identity, root and original root confirmation",
+    rollback_note: "Keep the old login channel available; use a new exact approved plan to restore it if needed. Never move the root to the new account home.", risk: "external-mutation" };
+}
+
 function shlexQuote(s) {
   if (s === "") return "''";
   if (/[^\w@%+=:,./-]/.test(s)) return "'" + s.replaceAll("'", "'\"'\"'") + "'";

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

@@ -2,6 +2,7 @@
 import { existsSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { validateRootConfirmation, assertUniqueMachine } from "./onboarding.mjs";
 import { readFileSync } from "node:fs";
 import {
   OpsError, canonical, digest, emptyStatus, exact, identifier, now, readJson, relative,
@@ -261,6 +262,11 @@ export function register(state, request) {
         if (key in s[group] && digest(s[group][key]) !== digest(item)) {
           throw new OpsError(`registered identity is immutable through register: ${group}/${key}; use a reviewed migration`);
         }
+        if (group === "hosts" && !(key in s.hosts)) {
+          validateHost(item);
+          assertUniqueMachine(s, item);
+          validateRootConfirmation(state, item, { require: true, checkEndpoint: true });
+        }
         s[group][key] = item;
       }
     }