@namewta/speculo 1.0.19 → 1.0.21

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

@@ -1,7 +1,7 @@
 /** Strict host-key SSH and subprocess local transport. No passwords in argv. */
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, posix, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { canonical, digest, noSymlinks, OpsError, redact, UnknownResult } from "./core.mjs";
 import { fingerprint } from "./agent.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);
@@ -107,8 +107,8 @@ export function posixSend(endpoint, localFile, remotePath, { timeout = 180 } = {
     throw new OpsError("POSIX bootstrap is Linux-only; PowerShell targets still require an existing Node");
   }
   noSymlinks(localFile, { allowMissing: false });
-  if (typeof remotePath !== "string" || !isAbsolute(remotePath) || remotePath.split("/").includes("..") || /[\s\n\r]/.test(remotePath)) {
-    throw new OpsError("remote scp path must be absolute without spaces or ..");
+  if (typeof remotePath !== "string" || !posix.isAbsolute(remotePath) || remotePath.split("/").includes("..") || /[\s\\\0]/.test(remotePath)) {
+    throw new OpsError("remote scp path must be POSIX absolute without whitespace, backslashes, NUL or ..");
   }
   const argv = sshArgv(endpoint, { scp: true });
   argv.push("--", localFile, `${endpoint.username}@${endpoint.hostname}:${remotePath}`);
@@ -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/workflows/specdev/A-archive-and-consolidate/consolidation-interview.md

@@ -38,9 +38,9 @@
 change 内三份文档复用 grill 的既有格式，避免重复发明：
 
 - 设计日志：`<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`；
-- 领域上下文：`<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`；
-- 架构决策：`<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`；
-- 领域建模规则：`<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。
+- 领域上下文：`<Path>{roots.workflows}/specdev/common/rules/context-format.md</Path>`；
+- 架构决策：`<Path>{roots.workflows}/specdev/common/rules/adr-format.md</Path>`；
+- 领域建模规则：`<Path>{roots.workflows}/specdev/common/rules/domain-modeling.md</Path>`。
 
 同步顺序固定：先 LOG，再 CONTEXT，最后 ADR。CONTEXT 只描述当前真相，历史轨迹留在 LOG；未确认的解读不得写成已接受 ADR；与现有永久 ADR 冲突时建立 supersedes 链，不重写历史。高影响条目带来源标识（`USER-DECISION`、`CODE:`、`RESEARCH:`、`ADR-###`）。
 

package/template/workflows/specdev/C-code-review/C-code-review.md

@@ -23,7 +23,7 @@ C 是独立 review 入口，不实施修复。它拥有 `<Path>{roots.state}/spe
 
 ## 流程
 
-1. **解析固定点**：使用 `git rev-parse` 把固定点和 HEAD 固定为 SHA；PR 先通过 `<Path>{roots.skills}/github-npm-ops/SKILL.md</Path>` 的 `pr-read` 获得 base/head SHA，并确保对应对象可在本地解析。
+1. **解析固定点**：使用 `git rev-parse` 把固定点和 HEAD 固定为 SHA；PR 先通过 `<Path>{roots.workflows}/specdev/T-triage/remote-operations.md</Path>` 的 `pr-read` 获得 base/head SHA，并确保对应对象可在本地解析。
 2. **冻结输入**：记录 `git diff <fixed>...<head>` 和 `git log <fixed>..<head> --oneline`。引用无效或 diff 为空时失败，不创建报告。
 3. **发现来源**：调用 `<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`；规范来源缺失时经确认跳过规范轴，标准轴继续。
 4. **隔离审查**：仅按公共 Skill 的完整输入复用门接受既有结果；需要执行的轴在平台支持时并行 reviewer，否则用两个独立完整输入包顺序执行。两轴不得读取对方 finding。

package/template/workflows/specdev/D-diagnose-bugs/D-diagnose-bugs.md

@@ -69,3 +69,9 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
 ```
 
 根因确认后将本 Work 加入 `works_run` 并清空 `current_work`，返回 diagnosis 和下一 Work：局部修复进入 Tickets/I，公共行为或高风险进入 S/Tickets，缺 seam 进入 R，仍无根因则保持 blocked 或进入 W。
+
+## 脱敏与强制变异证据
+
+在日志、报告和重现材料中移除 token、Cookie、认证头、秘密配置、个人数据及机器绝对路径；保留项目相对定位和必要错误形态。原始敏感数据不进入长期工件。
+
+如果使用强制变异检验测试敏感性，先记录未变异文件的 hash/diff，实际修改目标后读取 git diff 与运行路径，证明变异已落到执行文件。只有测试因预期行为断言失败才算有效 red；编译错误、未选中测试、变异未落地均为无效证据。恢复原内容，复跑基线并核对 diff。D 输出诊断及修复不变量，正式修复仍交 I。

package/template/workflows/specdev/G-grill-with-docs/references/interview-procedure.md

@@ -40,9 +40,9 @@
 
 分别使用：
 
-- `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/adr-format.md</Path>`
 - `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`
-- `<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/context-format.md</Path>`
 - `<Path>{roots.workflows}/specdev/common/schemas/design-tree.schema.json</Path>`
 
 恢复时先读取四份工件，按 design tree 的节点状态恢复，避免重复询问已关闭问题。
@@ -90,7 +90,7 @@
 
 ### 5. 同步 change-local 领域模型
 
-加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。每轮先写 LOG，再把已确认且本 change 下游必须使用的项目规范术语同步到 change CONTEXT，最后把同时满足三个准入条件、已成为本 change 合同的架构决定写入 change ADR。
+加载 `<Path>{roots.workflows}/specdev/common/rules/domain-modeling.md</Path>`。每轮先写 LOG，再把已确认且本 change 下游必须使用的项目规范术语同步到 change CONTEXT，最后把同时满足三个准入条件、已成为本 change 合同的架构决定写入 change ADR。
 
 历史轨迹只留在 LOG；未确认选项不写成已接受 ADR；已有 change ADR 被替代时建立 supersedes 链。同步只更新本 change 工件，不创建、合并或改写永久 `context/`、`adr/`；它记录共识生长过程，不授权产品实现。
 
@@ -127,8 +127,8 @@ frontier 为空时，向用户确认设计树的每个分支均已走过且已
 
 - 质询协议：`<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`
 - 设计树模板：`<Path>{roots.workflows}/specdev/G-grill-with-docs/design-tree-template.json</Path>`
-- 领域建模：`<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`
-- ADR 格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`
-- CONTEXT 格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`
+- 领域建模：`<Path>{roots.workflows}/specdev/common/rules/domain-modeling.md</Path>`
+- ADR 格式：`<Path>{roots.workflows}/specdev/common/rules/adr-format.md</Path>`
+- CONTEXT 格式：`<Path>{roots.workflows}/specdev/common/rules/context-format.md</Path>`
 - LOG 格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`
 - Stakeholder 问卷：`<Path>{roots.workflows}/specdev/G-grill-with-docs/stakeholder-questionnaire.md</Path>`

package/template/workflows/specdev/I-implement/references/implementation-procedure.md

@@ -74,7 +74,7 @@ Ticket 模式下，Lead 根据 Ticket 独立性、路径冲突、上下文、风
 
 加载 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`，检查模块、接口、类型、不变量、顺序/错误/性能语义、接缝、适配器、依赖分类、测试观察点和既有公共合同。
 
-存在多个不改变上层契约的局部设计时，可运行 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。超出 Ticket 或改变产品/公共合同/数据/兼容/安全时，返回架构审查、Grill、Spec 或 Ticket owner。陌生外部依赖使用 research Skill。
+存在多个不改变上层契约的局部设计时，可运行 `<Path>{roots.workflows}/specdev/common/rules/design-it-twice.md</Path>`。超出 Ticket 或改变产品/公共合同/数据/兼容/安全时，返回架构审查、Grill、Spec 或 Ticket owner。陌生外部依赖使用 research Skill。
 
 **完成标准**：局部设计与上层契约一致，稳定接缝和依赖策略明确。
 

package/template/workflows/specdev/I-implement/tdd-rules.md

@@ -15,3 +15,7 @@
 - 一个循环只有一个 seam、一个测试和一个最小实现；
 - 测试没有通过删除、跳过、吞错或放宽断言制造绿色；
 - review 前没有以“顺手重构”扩大切片。
+
+## 强制变异验证
+
+使用强制变异时，先保存基线 hash/diff，修改后核对实际执行文件的 diff 与测试选择。只有预期行为断言 red 才有效；编译错误、错测或变异未落地均不计。恢复原内容、复跑基线并核对 diff，把全过程记入 Evidence。诊断协议见 <Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>。

package/template/workflows/specdev/I-init-setup/config-template.json

@@ -1,5 +1,5 @@
 {
-  "schema_version": 5,
+  "schema_version": 6,
   "interaction_language": "zh-CN",
   "artifact_language": "zh-CN",
   "git": {
@@ -23,5 +23,9 @@
     "require_evidence": true,
     "ui_design_default_candidates": 3,
     "ui_design_max_candidates": 4
+  },
+  "github": {
+    "include_external_prs": false,
+    "labels": {}
   }
 }

package/template/workflows/specdev/INDEX.md

@@ -3,8 +3,8 @@ id: specdev
 type: workflow
 workflow: specdev
 name: SpecDev Workflow
-description: 以本地工件为唯一开发权威，从来源冻结、诊断、设计、原型、规格、Ticket、编排和审查推进到证据驱动实现、远程 reconcile 或票级发布投影、记事项捕获与知识归档。
-keywords: [specdev, local-first, 规格驱动开发, decision-complete, prototype, code-review, TDD, 证据]
+description: 以本地工件为开发权威，覆盖来源分诊、诊断、设计、逻辑/UI 原型、规格、Ticket、编排、实现、审查、复盘、GitHub/PR/包发布交付与知识归档。
+keywords: [specdev, local-first, 规格驱动开发, decision-complete, prototype, code-review, TDD, retro, PR, release, 证据]
 ---
 
 # SpecDev Index

package/template/workflows/specdev/P-goal-plan/planning-modes.md

@@ -13,7 +13,7 @@
 - 等待真实上游产物的未来 Ticket 保持 `status: draft`、`ready: false`，在未决问题中记录缺口、生产者 Ticket、所需证据和 DoR 重审条件；不编造版本、路径或验证入口；
 - 每个验收合同被 Ticket 覆盖；
 - writable/shared path 有唯一 owner，Wave 候选无写冲突；
-- config schema v5，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；UI 设计候选范围读取 planning 配置；
+- config schema v6，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；UI 设计候选范围读取 planning 配置；
 - 父分支可定位，implementation commit 与本地 integration 的授权状态已记录；`plan` 可以列出待批准项并保持 `ready_for_execution: false`；
 - 待执行 Deep Ticket 的迁移、兼容、监控、恢复和不可逆批准点完整。
 - Ticket 与 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`、`<Path>{roots.state}/specdev/adr/</Path>`、`<Path>{roots.state}/specdev/context/</Path>` 和当前代码事实不存在未处理冲突；

package/template/workflows/specdev/P-prototype/P-prototype.md

@@ -2,12 +2,12 @@
 id: specdev/prototype
 type: workflow-entry
 workflow: specdev
-name: UI 设计原型
-description: 检测现有项目的 UI 事实，按产品任务推荐并逐步选择设计风格，生成持久化设计系统文档、多风格 HTML 对照和可运行 HTML/CSS/JS 原型。
+name: 逻辑与 UI 原型
+description: 按需验证离线逻辑模型，或检测现有项目的 UI 事实，按产品任务推荐并逐步选择设计风格，生成持久化设计系统文档、多风格 HTML 对照和可运行 HTML/CSS/JS 原型。
 keywords: [prototype, UI 原型, 风格检测, 设计系统, HTML, CSS, 交互, design tokens]
 ---
 
-# UI 设计原型
+# 逻辑与 UI 原型
 
 > 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
 
@@ -15,6 +15,10 @@ keywords: [prototype, UI 原型, 风格检测, 设计系统, HTML, CSS, 交互,
 
 激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前步骤定位输入和证据。
 
+## 分支选择
+
+逻辑/状态/规则验证读取 <Path>{roots.workflows}/specdev/P-prototype/logic-protocol.md</Path>，跳过下方 UI 专属步骤。UI 仍默认离线持久化，默认 3 个、最多 4 个方案。只有用户明确要求项目内预览时读取 <Path>{roots.workflows}/specdev/P-prototype/project-preview-protocol.md</Path>；其临时写集与清理由该分支管理，下方 UI 设计权威与离线交付保持。
+
 ## 输入与所有权
 
 - 必需输入：目标项目或新产品设想、核心用户任务，以及当前 SpecDev change。