@namewta/speculo 1.0.20 → 1.0.22

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

@@ -0,0 +1,215 @@
+/** S-owned account discovery and explicit root confirmation. No target writes. */
+import { readFileSync } from "node:fs";
+import { dirname, join, posix, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { digest, identifier, newId, now, noSymlinks, OpsError, rootPath, withLock, writeJson } from "./core.mjs";
+import { load, validate } from "./model.mjs";
+import { call, posixCall, validateSshEndpoint } from "./transport.mjs";
+import { readBoundedJson, statePath } from "./workspace.mjs";
+
+const SCRIPT = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../server-discover.sh"), "utf8").replace(/\r\n?/g, "\n");
+export const onboardingHooks = { observe: observeServer };
+const pathApi = (platform) => platform === "windows" ? win32 : posix;
+const clean = (s) => typeof s === "string" && s.trim().length > 0 && s.length <= 4096 && !/[\x00-\x1f\x7f]/.test(s);
+
+export function endpointDigest(host) {
+  const c = { ...(host.connection || {}) };
+  // Runtime selection may change after a pinned Node bootstrap, not SSH identity/trust.
+  delete c.node;
+  if (host.transport === "ssh") {
+    validateSshEndpoint(c);
+    noSymlinks(c.known_hosts, { allowMissing: false });
+  }
+  return digest({ platform: host.platform, transport: host.transport, connection: c,
+    known_hosts_digest: host.transport === "ssh" ? digest(readFileSync(c.known_hosts)) : null });
+}
+
+export function parseLinuxDiscovery(stdout, withRoot = false) {
+  const values = {};
+  const keys = ["machine", "system", "username", "uid", "home", "node", "node_version",
+    ...(withRoot ? ["root_exists", "root_writable", "root_nonempty", "root_owner"] : [])];
+  for (const line of String(stdout).trimEnd().split(/\r?\n/)) {
+    const match = /^([a-z_]+)=((?:[a-f0-9]{2})*)$/.exec(line);
+    if (!match || !keys.includes(match[1]) || Object.hasOwn(values, match[1])) throw new OpsError("invalid Linux discovery response");
+    values[match[1]] = Buffer.from(match[2], "hex").toString("utf8");
+  }
+  if (Object.keys(values).length !== keys.length || values.system !== "Linux" || !clean(values.machine)) throw new OpsError("incomplete Linux identity discovery");
+  const facts = { identity: digest({ machine: values.machine.trim(), platform: "Linux" }), platform: "linux",
+    username: values.username, uid: values.uid, home: values.home, node: values.node || null, node_version: values.node_version || null };
+  if (withRoot) {
+    for (const key of ["root_exists", "root_writable", "root_nonempty"]) if (!["true", "false"].includes(values[key])) throw new OpsError("invalid root observation");
+    let owner = null;
+    if (values.root_owner) { try { owner = JSON.parse(values.root_owner); } catch { throw new OpsError("invalid root owner marker"); } }
+    facts.root_check = { exists: values.root_exists === "true", writable: values.root_writable === "true", nonempty: values.root_nonempty === "true", owner };
+  }
+  return facts;
+}
+
+export function observeServer(host, root = null) {
+  if (host.transport === "ssh" && host.platform === "linux") {
+    const result = posixCall(host.connection, SCRIPT, { sudo: false, args: root ? [root] : [], timeout: 30 });
+    return parseLinuxDiscovery(result.stdout, Boolean(root));
+  }
+  if (host.transport === "ssh" && !host.connection?.node) throw new OpsError("non-Linux SSH discovery requires an existing Node executable");
+  return call({ ...host, connection: host.transport === "ssh" ? { ...host.connection, sudo: false } : {} },
+    { action: "onboarding", identity: null, root }, { timeout: 30 });
+}
+
+function validateFacts(host, facts) {
+  if (!facts || facts.platform !== host.platform || !/^[a-f0-9]{64}$/.test(facts.identity || "")
+    || !clean(facts.username) || !clean(facts.home) || !pathApi(host.platform).isAbsolute(facts.home)) throw new OpsError("reliable login account/home/identity unavailable");
+  if (host.platform !== "windows" && !/^\d+$/.test(facts.uid)) throw new OpsError("reliable login uid unavailable");
+  if (host.transport === "ssh") {
+    const accountMatches = host.platform === "windows" ? facts.username.toLowerCase() === host.connection.username.toLowerCase() : facts.username === host.connection.username;
+    if (!accountMatches) throw new OpsError("observed login account differs from SSH username");
+  }
+  return facts;
+}
+
+export function assertUniqueMachine(registry, host) {
+  const peers = Object.values(registry.hosts).filter((h) => h.identity === host.identity);
+  if (peers.length > 1) throw new OpsError("ambiguous legacy machine roots; preserve evidence and resolve the affected Host explicitly");
+  if (peers.length && peers[0].host_id !== host.host_id) throw new OpsError("machine already registered; reuse Host " + peers[0].host_id + " and its root " + peers[0].root);
+  return peers[0] || null;
+}
+
+function folder(state, id) { identifier(id, "server"); return join(state, "records", "servers", id, "onboarding"); }
+function artifactPath(state, id, rid) { identifier(rid, "receipt"); return join(folder(state, id), rid + ".json"); }
+function persist(state, id, rid, value, schema) {
+  validate(value, schema);
+  const path = artifactPath(state, id, rid);
+  writeJson(path, value, { exclusive: true });
+  if (digest(readBoundedJson(path)) !== digest(value)) throw new OpsError("onboarding receipt readback mismatch");
+  return { receipt_id: rid, digest: digest(value) };
+}
+
+function assertSelectedPath(host, facts, root) {
+  const normalized = rootPath(root, host.platform);
+  if (!clean(root) || normalized !== root || (host.platform !== "windows" && root.includes("\\"))) throw new OpsError("selected root must be a normalized absolute path without control characters");
+  const p = pathApi(host.platform);
+  const home = p.normalize(facts.home);
+  if (host.platform === "windows" ? home.toLowerCase() === root.toLowerCase() : home === root) throw new OpsError("select a dedicated child, not the login home itself");
+  const system = host.platform === "windows" ? ["C:\\Windows", "C:\\Program Files", "C:\\Program Files (x86)"] : ["/etc", "/usr", "/bin", "/sbin", "/dev", "/proc", "/sys", "/boot"];
+  for (const base of system) {
+    const rel = p.relative(base, root);
+    if (rel === "" || (!rel.startsWith("..") && !p.isAbsolute(rel))) throw new OpsError("system directory cannot contain a managed root");
+  }
+}
+
+function assertRootObservation(host, facts, { legacy = false } = {}) {
+  const c = facts.root_check;
+  if (!c || typeof c.exists !== "boolean" || typeof c.nonempty !== "boolean" || c.writable !== true) throw new OpsError("selected root or nearest parent is not writable/searchable by the login account; provision permissions explicitly");
+  if (c.owner && (c.owner.host_id !== host.host_id || c.owner.identity !== facts.identity)) throw new OpsError("root ownership conflict");
+  if (!legacy && c.nonempty && !c.owner) throw new OpsError("nonempty unowned root; choose a dedicated empty directory or use a reviewed adoption plan");
+}
+
+export function discoverServer(state, serverId, endpoint) {
+  statePath(state); identifier(serverId);
+  const host = { host_id: serverId, platform: endpoint.platform, transport: endpoint.transport, connection: endpoint.connection || {} };
+  validate({ platform: host.platform, transport: host.transport, connection: host.connection }, "server-connection");
+  const registry = load(state);
+  if (!registry.controller) throw new OpsError("initialize the controller before connecting a Host");
+  if (!["linux", "windows", "darwin"].includes(host.platform) || !["local", "ssh"].includes(host.transport)) throw new OpsError("explicit platform and transport required");
+  if (host.transport === "local" && Object.keys(host.connection).length) throw new OpsError("local connection must be empty");
+  const before = endpointDigest(host);
+  const facts = validateFacts(host, onboardingHooks.observe(host));
+  const previous = assertUniqueMachine(registry, { ...host, identity: facts.identity });
+  if (registry.hosts[serverId] && !previous) throw new OpsError("registered machine identity drift");
+  if (before !== endpointDigest(host)) throw new OpsError("SSH trust changed during discovery");
+  const id = newId("discovery");
+  const record = { schema_version: 1, artifact: "ops-server-discovery", discovery_id: id, host_id: serverId,
+    discovered_at: now(), endpoint: host, endpoint_digest: before, facts,
+    suggested_root: previous?.root ?? pathApi(host.platform).join(facts.home, "ops"), registered: Boolean(previous) };
+  const ref = persist(state, serverId, id, record, "server-discovery");
+  return { status: previous ? "discovered-existing-host" : "discovered-not-confirmed", discovery: ref, ...record,
+    next: previous ? "Reuse the registered root; connection changes require S verification and an exact approved plan." : "Ask the user to specify or accept the suggested root, then server-root-confirm." };
+}
+
+export function confirmServerRoot(state, serverId, discoveryId, root, by, statement) {
+  statePath(state);
+  if (!clean(by) || !clean(statement)) throw new OpsError("actual user confirmation by/statement required");
+  const discovery = readBoundedJson(artifactPath(state, serverId, discoveryId));
+  validate(discovery, "server-discovery");
+  if (discovery.host_id !== serverId || discovery.discovery_id !== discoveryId) throw new OpsError("discovery identity mismatch");
+  const host = discovery.endpoint;
+  assertSelectedPath(host, discovery.facts, root);
+  if (endpointDigest(host) !== discovery.endpoint_digest) throw new OpsError("SSH endpoint/trust changed; rediscover");
+  const facts = validateFacts(host, onboardingHooks.observe(host, root));
+  for (const k of ["identity", "username", "uid", "home"]) if (facts[k] !== discovery.facts[k]) throw new OpsError("login account/home/identity drift; rediscover");
+  return withLock(join(state, ".locks", "catalog"), { operation: "server-root-confirm" }, () => {
+    const registry = load(state);
+    const previous = assertUniqueMachine(registry, { ...host, identity: facts.identity });
+    if (registry.hosts[serverId] && !previous) throw new OpsError("registered machine identity drift");
+    if (previous && previous.root !== root) throw new OpsError("registered root is immutable; explicit migration required");
+    assertRootObservation(host, facts, { legacy: Boolean(previous && !previous.root_confirmation) });
+    if (endpointDigest(host) !== discovery.endpoint_digest) throw new OpsError("SSH trust changed during root confirmation");
+    const id = newId("root");
+    const record = { schema_version: 1, artifact: "ops-root-confirmation", receipt_id: id, host_id: serverId,
+      platform: host.platform, transport: host.transport, identity: facts.identity, root,
+      account: { username: facts.username, uid: facts.uid, home: facts.home }, endpoint_digest: discovery.endpoint_digest,
+      discovery: { receipt_id: discoveryId, digest: digest(discovery) }, confirmed_at: now(), by, statement };
+    const ref = persist(state, serverId, id, record, "root-confirmation");
+    return { status: "root-confirmed", host_id: serverId, root, identity: facts.identity, root_confirmation: ref,
+      note: "Local confirmation evidence only; no directory created or software installed." };
+  });
+}
+
+export function validateRootConfirmation(state, host, { fresh = false, freshLegacy = false, require = false, checkEndpoint = false } = {}) {
+  const registry = load(state);
+  const previous = registry.hosts[host.host_id];
+  const ref = host.root_confirmation;
+  if (!ref) {
+    if (require || !previous || previous.identity !== host.identity || previous.root !== host.root || previous.root_confirmation) throw new OpsError("new Host requires server-root-confirm evidence before registration or target writes");
+    if (freshLegacy) {
+      const facts = validateFacts(host, onboardingHooks.observe(host, host.root));
+      if (facts.identity !== host.identity) throw new OpsError("legacy target machine identity drift");
+      assertRootObservation(host, facts, { legacy: true });
+    }
+    return null; // Existing v3 root remains authoritative; never fabricate retrospective consent.
+  }
+  assertUniqueMachine(registry, host);
+  const record = readBoundedJson(artifactPath(state, host.host_id, ref.receipt_id));
+  validate(record, "root-confirmation");
+  if (digest(record) !== ref.digest || record.receipt_id !== ref.receipt_id
+    || ["host_id", "identity", "platform", "transport", "root"].some((k) => host[k] !== record[k])) throw new OpsError("root confirmation digest/target mismatch");
+  const discovery = readBoundedJson(artifactPath(state, host.host_id, record.discovery.receipt_id));
+  validate(discovery, "server-discovery");
+  if (digest(discovery) !== record.discovery.digest) throw new OpsError("discovery evidence digest mismatch");
+  if (checkEndpoint && record.endpoint_digest !== endpointDigest(host)) throw new OpsError("confirmed SSH endpoint/trust drift; rediscover");
+  if (fresh) {
+    const facts = validateFacts(host, onboardingHooks.observe(host, host.root));
+    if (facts.identity !== host.identity) throw new OpsError("target machine identity drift");
+    // A reviewed connection-account update keeps the original root and confirmation.
+    if (endpointDigest(host) === record.endpoint_digest && ["username", "uid", "home"].some((k) => facts[k] !== record.account[k])) throw new OpsError("login account/home drift; rediscover and review the connection");
+    assertSelectedPath(host, facts, host.root);
+    assertRootObservation(host, facts);
+  }
+  return record;
+}
+
+export function confirmedBootstrapHost(state, raw, serverId, root) {
+  if (!state || !serverId) throw new OpsError("bootstrap apply requires --state and --host-id with root confirmation evidence");
+  statePath(state);
+  const previous = load(state).hosts[serverId];
+  const ref = raw.root_confirmation ?? previous?.root_confirmation;
+  if (!ref) {
+    if (!previous || previous.root !== root || previous.platform !== "linux" || previous.transport !== "ssh") throw new OpsError("bootstrap requires server-root-confirm evidence");
+    const host = { ...previous, connection: raw.connection || raw };
+    if (endpointDigest(previous) !== endpointDigest(host)) throw new OpsError("legacy bootstrap connection changes require S verification first");
+    assertUniqueMachine(load(state), host);
+    validateRootConfirmation(state, host, { freshLegacy: true });
+    return host;
+  }
+  const receipt = readBoundedJson(artifactPath(state, serverId, ref.receipt_id));
+  const host = { host_id: serverId, platform: "linux", transport: "ssh", root,
+    identity: receipt.identity, connection: raw.connection || raw, root_confirmation: ref };
+  if (raw.identity && raw.identity !== "discover" && raw.identity !== receipt.identity) throw new OpsError("bootstrap machine identity mismatch");
+  validateRootConfirmation(state, host, { require: true, fresh: true, checkEndpoint: true });
+  return host;
+}
+
+export function rootSummary(state, host) {
+  if (!host.root_confirmation) return { status: "legacy-registered", login_home: null, confirmed_at: null };
+  const r = validateRootConfirmation(state, host);
+  return { status: "confirmed", login_home: r.account.home, confirmed_at: r.confirmed_at };
+}

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

@@ -12,6 +12,7 @@ import { allocationOperation } from "./services.mjs";
 import { credentialRefs, planReport, remotePaths } from "./docs.mjs";
 import { taskFiles } from "./native_windows.mjs";
 import { engineDigest } from "./execution.mjs";
+import { validateRootConfirmation } from "./onboarding.mjs";
 import { assertSafeControlPath, defaultFileMode, reservedHostDocumentPaths } from "./control_files.mjs";
 
 export const plannerHooks = { call: transportCall };
@@ -246,6 +247,7 @@ export function compilePlan(state, specPath) {
         if (previous == null || fixed.some((k) => previous[k] !== item[k])) {
           throw new OpsError("resource update cannot change identity/root/kind; create explicit migration resources");
         }
+        if (group === "hosts" && digest(previous.root_confirmation ?? null) !== digest(item.root_confirmation ?? null)) throw new OpsError("root confirmation cannot be removed or replaced through resource updates");
         after[group][item[idkey]] = structuredClone(item);
       }
     }
@@ -668,6 +670,7 @@ export function compilePlan(state, specPath) {
     const snapshots = {};
     const docPreconditions = {};
     for (const [hid, host] of Object.entries(selected)) {
+      validateRootConfirmation(state, host, { fresh: true });
       const paths = new Set(ops.filter((o) => o.host_id === hid && ["write", "quarantine", "purge-quarantine"].includes(o.kind)).map((o) => o.path));
       for (const did of uniqueDocs) {
         if (after.deployments[did].host_id === hid) for (const p of remotePaths(after, after.deployments[did])) paths.add(p);

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

@@ -75,12 +75,12 @@ function buffers(p) {
   return { stdout, stderr };
 }
 
-export function posixCall(endpoint, script, { timeout = 180, args = [], sudo = false } = {}) {
+export function posixCall(endpoint, script, { timeout = 180, args = [], sudo } = {}) {
   validateSshEndpoint(endpoint);
   if ((endpoint.shell ?? "posix") === "powershell") {
     throw new OpsError("POSIX bootstrap is Linux-only; PowerShell targets still require an existing Node");
   }
-  const useSudo = sudo || endpoint.sudo;
+  const useSudo = sudo ?? endpoint.sudo;
   let remote = ["/bin/sh", "-s", "--", ...args.map(String)];
   if (useSudo) remote = ["sudo", "-n", "--", ...remote];
   const argv = sshArgv(endpoint);
@@ -155,7 +155,11 @@ export function call(host, request, { timeout = 1800 } = {}) {
   const c = host.connection;
   const argv = sshArgv(c);
   let remote = [c.node, "--input-type=module"];
-  if (c.sudo) remote = ["sudo", "-n", "--", ...remote];
+  // New confirmed roots and their owner/lock files belong to the login account.
+  // Running first lock as root would make later unprivileged discovery unreadable.
+  // Legacy Hosts retain their existing privilege behavior.
+  const useSudo = c.sudo && !(host.root_confirmation && ["lock", "unlock"].includes(request.action));
+  if (useSudo) remote = ["sudo", "-n", "--", ...remote];
   let remoteCommand;
   if ((c.shell ?? "posix") === "powershell") {
     if (c.sudo) throw new OpsError("sudo not valid for PowerShell transport");

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

@@ -5,9 +5,16 @@ import { readBoundedJson, readRegistry, route, statePath } from "./workspace.mjs
 import { checkServer } from "./server_checks.mjs";
 import { generateFleet } from "./fleet.mjs";
 import { authorizeTask, prepareTask, runTask } from "./tasks.mjs";
+import { discoverServer, confirmServerRoot } from "./onboarding.mjs";
+import { initializeHostSpec, connectionSpec } from "./host_recipes.mjs";
+import { writeJson } from "./core.mjs";
 
-export const COMMANDS = Object.freeze(["workspace-help", "route", "server-check", "fleet", "task-plan", "task-authorize", "task-run"]);
+export const COMMANDS = Object.freeze(["workspace-help", "route", "server-discover", "server-root-confirm", "server-initialize-spec", "server-connection-spec", "server-check", "fleet", "task-plan", "task-authorize", "task-run"]);
 const options = {
+  "server-discover": ["server", "connection-file"],
+  "server-root-confirm": ["server", "discovery", "root", "by", "statement"],
+  "server-initialize-spec": ["server", "output"],
+  "server-connection-spec": ["server", "connection-file", "output"],
   route: ["scope", "server", "project"],
   "server-check": ["server", "profile", "min-free-mib", "min-memory-mib"],
   fleet: ["stale-hours"], "task-plan": ["file"],
@@ -59,6 +66,18 @@ export async function main(argv = process.argv.slice(2)) {
     load(state);
     let result;
     switch (args.command) {
+      case "server-discover": result = discoverServer(state, required(args, "server"), readBoundedJson(required(args, "connection-file"))); break;
+      case "server-root-confirm": result = confirmServerRoot(state, required(args, "server"), required(args, "discovery"), required(args, "root"), required(args, "by"), required(args, "statement")); break;
+      case "server-initialize-spec":
+      case "server-connection-spec": {
+        const output = required(args, "output");
+        if (!isAbsolute(output)) throw new OpsError("--output must be absolute");
+        const spec = args.command === "server-initialize-spec" ? initializeHostSpec(state, required(args, "server"))
+          : connectionSpec(state, required(args, "server"), readBoundedJson(required(args, "connection-file")));
+        writeJson(output, spec, { exclusive: true });
+        result = { status: "generated-not-executed", spec_path: output, next: "plan -> exact approve -> apply; root selection is not installation authorization" };
+        break;
+      }
       case "route": result = route(readRegistry(state), { scope: required(args, "scope"), server_ids: list(args.server), project_ids: list(args.project) }); break;
       case "server-check": result = await checkServer(state, required(args, "server"), { profile: args.profile ?? "base",
         minFreeMiB: integer(args["min-free-mib"], 1024), minMemoryMiB: integer(args["min-memory-mib"], 256) }); break;

package/template/workflows/ops/common/tools/server-discover.sh

@@ -0,0 +1,65 @@
+#!/bin/sh
+# Read-only Linux account and root inspection. Never sudo, mkdir or install here.
+set -eu
+[ "$(uname -s)" = Linux ] || { echo 'Linux discovery adapter required' >&2; exit 2; }
+emit() { printf '%s=' "$1"; printf '%s' "$2" | od -An -v -tx1 | tr -d ' \n'; printf '\n'; }
+account=$(id -un)
+uid=$(id -u)
+if command -v getent >/dev/null 2>&1; then
+  record=$(getent passwd "$uid")
+else
+  record=$(awk -F: -v uid="$uid" '$3 == uid { print }' /etc/passwd)
+fi
+[ "$(printf '%s\n' "$record" | wc -l | tr -d ' ')" = 1 ] || { echo 'Ambiguous account database entry' >&2; exit 2; }
+[ "$(printf '%s' "$record" | cut -d: -f1)" = "$account" ] || { echo 'Account database mismatch' >&2; exit 2; }
+home=$(printf '%s' "$record" | cut -d: -f6)
+case "$home" in /*) ;; *) echo 'Account home is not absolute' >&2; exit 2;; esac
+machine=''
+for p in /etc/machine-id /var/lib/dbus/machine-id; do
+  if [ -r "$p" ]; then machine=$(cat "$p"); [ -z "$machine" ] || break; fi
+done
+[ -n "$machine" ] || { echo 'Stable machine identity unavailable' >&2; exit 2; }
+node=$(command -v node 2>/dev/null || true)
+version=''
+if [ -n "$node" ]; then version=$("$node" --version 2>/dev/null || true); fi
+emit machine "$machine"
+emit system Linux
+emit username "$account"
+emit uid "$uid"
+emit home "$home"
+emit node "$node"
+emit node_version "$version"
+root=${1-}
+if [ -n "$root" ]; then
+  cursor=$root
+  while :; do
+    [ ! -L "$cursor" ] || { echo 'Symlink root traversal rejected' >&2; exit 2; }
+    if [ -e "$cursor" ] && [ ! -d "$cursor" ]; then echo 'Root ancestor is not a directory' >&2; exit 2; fi
+    [ "$cursor" != / ] || break
+    cursor=$(dirname -- "$cursor")
+  done
+  cursor=$root
+  while [ ! -e "$cursor" ]; do cursor=$(dirname -- "$cursor"); done
+  writable=false
+  if [ -w "$cursor" ] && [ -x "$cursor" ]; then writable=true; fi
+  present=false
+  nonempty=false
+  owner=''
+  if [ -d "$root" ]; then
+    present=true
+    [ -r "$root" ] || { echo 'Selected root cannot be inspected by the login account' >&2; exit 2; }
+    entries=$(find "$root" -mindepth 1 -maxdepth 1 -print -quit) || { echo 'Selected root inspection failed' >&2; exit 2; }
+    if [ -n "$entries" ]; then nonempty=true; fi
+    for rel in .ops-host.json _host _runtime docs knowledge README.md DEPLOYMENTS.md; do
+      [ ! -L "$root/$rel" ] || { echo 'Managed path is a symlink' >&2; exit 2; }
+    done
+    if [ -e "$root/.ops-host.json" ]; then
+      [ -f "$root/.ops-host.json" ] && [ "$(wc -c < "$root/.ops-host.json")" -le 16384 ] || { echo 'Invalid root owner marker' >&2; exit 2; }
+      owner=$(cat "$root/.ops-host.json")
+    fi
+  fi
+  emit root_exists "$present"
+  emit root_writable "$writable"
+  emit root_nonempty "$nonempty"
+  emit root_owner "$owner"
+fi

package/template/workflows/ops/common/tools/validate-ops.mjs

@@ -26,7 +26,7 @@ try {
       const text = readFileSync(join(root, id, id + ".md"), "utf8");
       if (!text.includes("type: workflow-entry") || !text.includes("读取范围") || !text.includes("id: ops/" + id.slice(2))) throw new Error("invalid work " + id);
     }
-    for (const file of ["INDEX.md", "README.md", "manifest.json", "runtime-contract.json", "common/USAGE.md", "common/WORKSPACE-USAGE.md", "common/CAPABILITIES.md", "common/templates/FLEET.html", "common/schemas/fleet-view.schema.json", "common/schemas/task-request.schema.json", "common/schemas/server-check.schema.json", "common/tools/opslib/execution.mjs", "common/tools/opslib/tasks.mjs", "common/tools/opslib/fleet.mjs"]) {
+    for (const file of ["INDEX.md", "README.md", "manifest.json", "runtime-contract.json", "common/USAGE.md", "common/WORKSPACE-USAGE.md", "common/CAPABILITIES.md", "common/templates/FLEET.html", "common/schemas/fleet-view.schema.json", "common/schemas/task-request.schema.json", "common/schemas/server-check.schema.json", "common/tools/opslib/execution.mjs", "common/tools/opslib/tasks.mjs", "common/tools/opslib/fleet.mjs", "common/tools/opslib/onboarding.mjs", "common/tools/server-discover.sh", "common/schemas/server-discovery.schema.json", "common/schemas/root-confirmation.schema.json", "common/rules/host-root-and-onboarding.md"]) {
       if (!existsSync(join(root, file))) throw new Error("missing " + file);
     }
     for (const name of readdirSync(join(root, "common/schemas")).filter((x) => x.endsWith(".json"))) {

package/template/workflows/ops/manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "id": "ops",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "persistent_knowledge": [
     "<Path>{roots.state}/ops/knowledge/</Path>",
     "<Path>{roots.state}/ops/hosts/{host_id}/knowledge/</Path>",
@@ -30,19 +30,24 @@
       "inputs": [
         "server",
         "verified-host-key",
-        "key-or-agent"
+        "key-or-agent",
+        "user-selected-persistence-root"
       ],
       "outputs": [
         "server-registration",
         "inventory",
-        "server-checks"
+        "server-checks",
+        "login-account-discovery",
+        "root-confirmation"
       ],
       "risk": "production-critical",
       "context_budget": 20000
     },
     {
       "id": "host-manage",
-      "after": [],
+      "after": [
+        "server-connect"
+      ],
       "inputs": [
         "server",
         "spec",
@@ -59,7 +64,9 @@
     },
     {
       "id": "project-deploy",
-      "after": [],
+      "after": [
+        "host-manage"
+      ],
       "inputs": [
         "project",
         "explicit-servers",

package/template/skills/optimize-codex-config/SKILL.md

@@ -1,81 +0,0 @@
----
-name: optimize-codex-config
-description: Audit config.toml/auth.json and diagnose Codex 413 or related failures; modify configuration only after explicit confirmation.
----
-
-# Optimize Codex Config
-
-以**体检**为主导词：先建立脱敏事实，再提出配置变更。默认只读；修改本机配置前必须向用户展示完整目标和脱敏 diff，并取得本次修改的明确确认。
-
-## 1. 锁定范围与权限
-
-1. 解析实际 `CODEX_HOME`；未显式设置时使用当前用户的 `~/.codex`。将它转成绝对路径并确认目标是目录且不是符号链接。
-2. 将请求归类为只读体检、故障诊断或配置修改。只读体检和诊断不取得写权限。
-3. 将本 skill 的写入边界限制为用户明确指定的本机 Codex 文件。CC Switch 数据库、远端 API、反向代理和 Nginx 只输出归因与交接建议。
-4. 在任何可能写入前记录 `config.toml` 的哈希、大小和修改时间，并检查目标文件是否存在已证明的可写句柄。普通 Codex CLI、ChatGPT/Codex 应用进程及其 helper 的存在不构成 writer 证据。
-
-**完成标准：** 实际 `CODEX_HOME`、任务类型、允许写入的文件和外部边界均已明确；符号链接、已证明的活跃 writer、不明确目标，或修改任务无法取得 writer 观测时已成为 blocker。只读任务可以把不可用探针记录为 unknown 后继续。
-
-## 2. 建立只读基线
-
-从本 `SKILL.md` 所在目录运行：
-
-```bash
-node scripts/audit-codex-config.mjs --codex-home <absolute-directory> --json
-```
-
-需要离线或可复现 fixture 时加入 `--no-command-probes`；需要缩小会话扫描范围时使用 `--since-days <N>`。先运行 `--help` 核对当前接口；CLI 不在导出的 `PATH` 中时，用 `command -v codex` 取得绝对路径并传给 `--codex-bin`。
-
-1. 保留审计脚本的结构化结果；不得把 `auth.json` 内容、提示词、工具输出、完整接口 URL 或 bearer token复制进报告。
-2. 直接查看配置时，先遮蔽 `experimental_bearer_token`、静态认证 header、环境变量值和 URL 主机。只检查 `auth.json` 的存在、文件类型、权限和 Codex 报告的认证模式，不读取或打印文件内容。
-3. 对配置、供应商、认证、权限、Agent、MCP、Hook 或历史设置提出判断前，读取 [configuration contract](references/configuration-contract.md)，并用已安装 CLI 与当前官方配置参考验证每个拟使用的键。
-4. 把用户提供的既有设置视为需要保留或评估的事实，不把个人模型、认证方式或权限策略提升为通用默认值。
-
-**完成标准：** 当前版本、配置指纹、认证存储模式、供应商契约、权限、Agent、MCP、Hook、会话故障和 writer 状态均有脱敏证据；无法取得的事实被标为 unknown。
-
-## 3. 归因故障
-
-当请求包含 HTTP 状态码、SSE、超时或 compaction 失败时，读取 [troubleshooting](references/troubleshooting.md)，按其中证据梯度完成归因。
-
-1. 关联错误发生前最近一次 `token_count`，但只保留 token 数和模型上下文窗口。
-2. 区分本机配置、认证、供应商 wire API、远端模型服务和前置代理。HTML 代理错误页属于代理证据，不归因给模型。
-3. 对外部问题给出可复现证据、影响、临时本机缓解和服务端交接项。本 skill 不探测或修改用户未授权的远端系统。
-
-**完成标准：** 每个错误只有一个主要归属域，证据与推断分开，所有本机缓解都标明质量、成本或频率代价。
-
-## 4. 设计目标状态
-
-只询问审计无法发现且会改变方案的偏好：模型与推理等级、认证存储、审批与沙箱、网络访问、Agent 并发、供应商认证方式、历史保留，以及 MCP/Hook 的保留意图。
-
-输出确认包：
-
-1. 当前状态和问题证据；
-2. 目标状态及每项理由；
-3. 逐文件脱敏 diff；
-4. 明确保留的未知项、MCP、Hook、profile 和兼容设置；
-5. 备份名、原子写入方法、验证命令和回滚条件；
-6. 不在本机范围内的外部 blocker。
-
-只采用当前官方参考与已安装 CLI 均能验证的键。项目级 `.codex/config.toml` 不承载 provider、auth 或其他被 Codex 忽略的机器级设置。
-
-**完成标准：** 用户无需猜测任何目标值；diff 不含 secret；未关联的现有设置不会被清理；外部问题不会伪装成本机可修复项。
-
-## 5. 确认后原子写入
-
-只有用户在看到确认包后明确同意本次变更，才执行以下动作：
-
-1. 重读指纹；若配置已变化、存在目标文件的可写句柄，或 writer 探针仍为 unknown，停止并重新体检。
-2. 为每个待改文件创建不覆盖的 `*.pre-optimize-<YYYYMMDD-HHMMSS>.bak`，并将包含凭据的文件权限设为 `0600`。
-3. 在同一目录写临时文件、解析或加载验证成功后 rename 到目标，保留与任务无关的表和注释。
-4. 仅在用户明确要求且已安装 Codex 能验证格式时处理 `auth.json`。文件存储是有效选择，不强制迁移钥匙串；不得自行发明认证 JSON schema。
-
-**完成标准：** 写入前后的指纹、备份和确认可对应；目标文件是原子替换结果；没有越出已确认文件集合。
-
-## 6. 验证与交付
-
-1. 运行 `codex doctor --json`，再核对 `codex features list` 和 `codex debug models --bundled` 中与目标相关的能力。
-2. 验证配置加载、认证模式、权限与沙箱、MCP、Hook、Agent 和旧会话恢复。只有用户授权可能计费的网络请求后，才执行最小第三方 API 请求。
-3. 任一必须验证项失败时恢复备份，重跑相同检查并报告原始失败与回滚结果。
-4. 报告已改变、已保留、已验证、未验证和外部 blocker；不回显任何 secret 或完整 URL。
-
-**完成标准：** 所有已确认变更通过本机验证，或已完整回滚；报告包含命令、退出码和关键脱敏证据。

package/template/skills/optimize-codex-config/references/configuration-contract.md

@@ -1,103 +0,0 @@
-# Codex Configuration Contract
-
-在设计或修改 `config.toml`、`auth.json`、模型供应商、权限、Agent、MCP、Hook 或历史配置时完整应用本契约。配置键会随 Codex 版本变化；以已安装 CLI 和当前 [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) 为最终事实源。
-
-## 1. 配置归属与事实优先级
-
-1. 用户级配置位于 `$CODEX_HOME/config.toml`；profile 文件位于同一目录并通过 `--profile` 选择。
-2. 受信任项目可以使用 `.codex/config.toml` 覆盖项目设置，但 provider、auth、host metadata、通知、profile 选择和 telemetry 等机器级键会被忽略，必须留在用户级配置。
-3. 先读取现有配置、`codex doctor --json`、`codex features list` 和 `codex debug models --bundled`，再核对当前官方参考。API 模型网页上的最大上下文不是本机 Codex 目录的替代品。
-4. 只更改与目标直接相关的键。MCP、Hook、profile、插件、历史兼容项和未知集成默认原样保留，直到有证据证明无效且用户确认删除。
-
-## 2. 模型与推理
-
-- 从已安装模型目录选择 model，并确认所选 reasoning effort 受支持。常规工作可以从 `medium` 或现有值开始；`high`、`xhigh` 和更高等级只在质量收益能够覆盖延迟与成本时采用。
-- `plan_mode_reasoning_effort` 独立于普通 `model_reasoning_effort`；未设置时使用 Codex 内置 Plan preset。
-- 仅在自定义模型目录确实需要时设置 `model_context_window`。不得为了绕过 compaction 或代理限制而夸大它。
-- `model_auto_compact_token_limit` 是触发阈值，不是服务端请求体限制。降低它会更早、更频繁地压缩，并可能改变成本和上下文质量。
-- `model_auto_compact_token_limit_scope` 默认是 `total`；只有理解 carried prefix 行为后才选择 `body_after_prefix`。
-
-## 3. 第三方 Responses 供应商
-
-Codex 当前自定义供应商只支持 `responses` wire API。供应商必须兼容 Codex 实际使用的 Responses 请求、SSE 输出、工具项和 compaction 路径；仅兼容 Chat Completions 不够。
-
-使用存储在 `auth.json` 的 OpenAI-style API key 时，可以采用：
-
-```toml
-model = "gpt-5.6-sol"
-model_provider = "third-party"
-model_reasoning_effort = "high"
-plan_mode_reasoning_effort = "xhigh"
-cli_auth_credentials_store = "file"
-
-[model_providers.third-party]
-name = "Third Party Responses"
-base_url = "https://relay.example/api-root"
-wire_api = "responses"
-requires_openai_auth = true
-```
-
-`base_url` 必须是供应商声明的 API root。先确认 Codex 最终请求路径，不能机械添加或删除 `/v1`。生产连接优先 HTTPS；HTTP 会在主机到中转之间明文传输凭据和内容。
-
-供应商使用独立环境变量时改用：
-
-```toml
-[model_providers.third-party]
-name = "Third Party Responses"
-base_url = "https://relay.example/api-root"
-wire_api = "responses"
-env_key = "THIRD_PARTY_API_KEY"
-```
-
-动态 token 可以使用 `[model_providers.<id>.auth]` 下的 command、args、cwd、timeout 和 refresh interval。`auth`、`env_key`、`experimental_bearer_token` 与 `requires_openai_auth` 是互斥认证路线；每个供应商只保留一条。
-
-仅在证据要求时调整 `request_max_retries`、`stream_max_retries` 或 `stream_idle_timeout_ms`。重试不能修复稳定的 401、403、404 或 413。
-
-## 4. 认证存储
-
-- `cli_auth_credentials_store = "file"` 正式选择 `$CODEX_HOME/auth.json`；`keyring` 选择系统钥匙串；`auto` 由 Codex 决定。三者是偏好，不是安全等级排序。
-- 文件模式下，验证 `auth.json` 是普通文件、权限为 `0600` 且 `codex doctor --json` 报告认证可用。不要读取、打印、diff 或记录其中的 key。
-- 保留已安装 Codex 创建并验证过的 JSON schema。需要重新登录时优先通过 stdin 使用 `codex login --with-api-key`；手工修改只有在当前 schema 已被可靠确认时进行。
-- 自定义 provider 的 command-backed token 和 `env_key` 不应同时把同一 secret 写入 `auth.json` 或 `config.toml`。
-
-## 5. 权限、沙箱与网络
-
-一个保守、可交互的本机基线是：
-
-```toml
-approval_policy = "on-request"
-approvals_reviewer = "auto_review"
-sandbox_mode = "workspace-write"
-
-[sandbox_workspace_write]
-network_access = false
-```
-
-这只是安全起点，不是固定默认。`approval_policy = "never"` 和 `sandbox_mode = "danger-full-access"` 适合用户明确接受风险的受控环境；不要通过 profile 名称暗示它们更安全。
-
-`default_permissions` 与 `sandbox_mode` / `[sandbox_workspace_write]` 是两套选择，不能混合。网络访问只按实际工具需求开放；第三方模型请求由 Codex host 发出，不等同于给沙箱内命令开放任意网络。
-
-## 6. Agent、MCP、Hook 与历史
-
-Agent 配置先确认当前 CLI 支持的键：
-
-```toml
-[agents]
-enabled = true
-max_concurrent_threads_per_session = 4
-default_subagent_model = "gpt-5.6-terra"
-default_subagent_reasoning_effort = "medium"
-```
-
-并发数由 CPU、内存、供应商速率限制和成本共同决定。不要假定四个线程适合所有机器或接口。
-
-- 对每个 MCP 逐项验证 command/path、启动、tool discovery 和审批策略；不因某个 MCP 失败而清理其他 MCP。
-- Hook 按事件和集成所有者保留。两个 Hook 调用不同集成时不是重复；只有调用链、输入和副作用等价时才合并。
-- `history.persistence` 和 `history.max_bytes` 由隐私、恢复需求和磁盘预算决定。修改前验证旧会话与数据库兼容。
-- 审计期间 `config.toml` 指纹变化或目标文件存在已证明的可写句柄时，先关闭写入来源并重新审计；进程名本身不是 writer 证据。修改任务无法取得精确 writer 观测时保持 blocked，且不得覆盖竞争写入。
-
-## 7. 确认包与写入契约
-
-确认包必须列出当前值、目标值、理由、脱敏 diff、保留项、备份路径、验证和回滚。对每个 secret 只写 `<redacted>` 或“存在/不存在”。
-
-确认后在目标目录创建权限正确的临时文件，完成 TOML/JSON 和 Codex 加载验证后原子 rename。写入前再次比较哈希、大小和 mtime；任一变化都使原确认失效。验证失败时恢复备份并重复验证，不留下部分应用状态。