@namewta/speculo 1.0.17 → 1.0.19

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

@@ -0,0 +1,155 @@
+/** Allowlisted offline inventory. Never reads credentials, env, outboxes or raw task specifications. */
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+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 { latestCheck, readiness } from "./server_checks.mjs";
+
+const TEMPLATE = join(dirname(fileURLToPath(import.meta.url)), "../../templates/FLEET.html");
+const text = (v) => typeof v === "string" ? redact(v.replace(/[\u0000-\u001f\u007f]/g, " "), []).slice(0, 500) : "";
+const time = (v) => typeof v === "string" && Number.isFinite(Date.parse(v)) ? new Date(v).toISOString() : null;
+const sorted = (map) => Object.keys(map).sort().map((id) => map[id]);
+const knownStatus = new Set(["planned", "running", "configured", "docs_pending", "completed", "failed", "unknown", "retired", "blocked", "partial", "prepared", "authorized", "interrupted", "incomplete", "needs-inspection", "executing", "planned-not-authorized"]);
+const status = (v) => knownStatus.has(v) ? v : "unknown";
+const md = (v) => text(String(v ?? "—")).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("|", "&#124;").replaceAll("`", "&#96;").replaceAll("[", "&#91;").replaceAll("]", "&#93;");
+
+function taskSummaries(state) {
+  const root = join(state, "records", "tasks");
+  noSymlinks(root);
+  if (!existsSync(root)) return [];
+  const entries = readdirSync(root, { withFileTypes: true });
+  if (entries.length > 10000) throw new OpsError("task index exceeds 10000 entries");
+  return entries.sort((a, b) => a.name.localeCompare(b.name)).map((ent) => {
+    identifier(ent.name, "task_id");
+    if (!ent.isDirectory() || ent.isSymbolicLink()) throw new OpsError("invalid task index entry");
+    const folder = join(root, ent.name), summary = join(folder, "summary.json");
+    // Incomplete preparation stays visible without reading possibly secret-bearing task.json.
+    if (!existsSync(summary)) return { task_id: ent.name, scope: "unknown", server_ids: [], project_ids: [], status: "incomplete", updated_at: null, run_ids: [] };
+    const s = readBoundedJson(summary);
+    if (s.schema_version !== 1 || s.artifact !== "ops-task-summary" || s.task_id !== ent.name || !["server", "project"].includes(s.scope)) throw new OpsError("invalid task summary");
+    ids(s.server_ids, "server_ids"); ids(s.project_ids, "project_ids");
+    const result = ["result.json", "progress.json"].map((f) => join(folder, f)).find((p) => { noSymlinks(p); return existsSync(p); });
+    const r = result ? readBoundedJson(result) : null;
+    if (r && (r.artifact !== "ops-task-result" || r.task_id !== ent.name || !Array.isArray(r.steps))) throw new OpsError("invalid task result");
+    for (const f of ["started.json", "authorization.json", "task.json"]) noSymlinks(join(folder, f));
+    let st = r ? status(r.status) : existsSync(join(folder, "started.json")) ? "needs-inspection"
+      : existsSync(join(folder, "authorization.json")) ? "authorized" : existsSync(join(folder, "task.json")) ? "prepared" : "incomplete";
+    // A running record is not proof that a live process still owns the task.
+    if (st === "running") st = "needs-inspection";
+    const runIds = (r?.steps || []).map((step) => identifier(step.run_id, "run_id"));
+    return { task_id: s.task_id, scope: s.scope, server_ids: s.server_ids, project_ids: s.project_ids,
+      status: st, updated_at: time(r?.updated_at ?? s.created_at), run_ids: [...new Set(runIds)] };
+  });
+}
+
+export function projectFleet(registry, checks = {}, tasks = [], { at = new Date(), staleHours = 24 } = {}) {
+  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,
+    environment: text(d.environment), instance: text(d.instance), method: text(d.method), root: text(d.root),
+    status: status(d.status), desired_version: text(d.version), observed_version: d.observed_version == null ? null : text(d.observed_version),
+    updated_at: time(d.updated_at), run_id: d.run_id ? identifier(d.run_id, "run_id") : null,
+  }));
+  const byServer = new Map(), byProject = new Map();
+  for (const d of deployments) {
+    if (!byServer.has(d.server_id)) byServer.set(d.server_id, []);
+    if (!byProject.has(d.project_id)) byProject.set(d.project_id, []);
+    byServer.get(d.server_id).push(d); byProject.get(d.project_id).push(d);
+  }
+  const servers = sorted(registry.hosts).map((h) => {
+    const c = checks[h.host_id];
+    let checkStatus = "unknown";
+    if (c) {
+      try { if (targetDigest(h) === c.host_digest) checkStatus = readiness(c.checks, c.checked_at, { at, staleHours }); }
+      catch { /* A changed/missing pinned host key is not evidence of readiness. */ }
+    }
+    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),
+      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),
+      host_services: (h.host_services || []).map((s) => ({ service_id: identifier(s.id, "host service"), kind: text(s.kind), unit: text(s.unit), port: Number.isInteger(s.listen_port) ? s.listen_port : null })),
+    };
+  });
+  const projects = sorted(registry.projects).map((p) => {
+    const own = byProject.get(p.project_id) || [];
+    return { project_id: p.project_id, name: text(p.display_name ?? p.project_id), kind: text(p.kind), service_type: text(p.service_type),
+      server_ids: [...new Set(own.filter((d) => d.status !== "retired").map((d) => d.server_id))].sort(), deployment_ids: own.map((d) => d.deployment_id) };
+  });
+  const bindings = sorted(registry.bindings).map((b) => {
+    if (!registry.deployments[b.consumer_deployment_id] || (b.provider_deployment_id && !registry.deployments[b.provider_deployment_id])) throw new OpsError("orphan binding cannot be projected");
+    return { binding_id: b.binding_id, consumer_deployment_id: b.consumer_deployment_id,
+      provider_deployment_id: b.provider_deployment_id ?? null, mode: text(b.mode), status: text(b.status) };
+  });
+  const releases = sorted(registry.releases).map((r) => ({ run_id: identifier(r.run_id, "run_id"), worker: text(r.worker), status: status(r.status),
+    server_ids: ids(r.host_ids || [], "release hosts"), deployment_ids: ids(r.deployment_ids || [], "release deployments"), updated_at: time(r.updated_at) }));
+  return { schema_version: 1, artifact: "ops-fleet-view", generated_at: at.toISOString(), controller_id: registry.controller.controller_id,
+    source_revision: registry.revision, source_digest: digest(registry), stale_hours: staleHours,
+    notice: "ready 只表示指定 profile 的必需检查项通过；completed 是历史执行结果。未测、过期或身份变化不能视为生产验收通过。",
+    servers, projects, deployments, bindings, releases, tasks };
+}
+
+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(", ")])) +
+    `\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(", ")])) +
+    `\n## 原始 Run / Release 索引\n\n` + table(["Run", "Work", "记录状态", "服务器", "更新时间"], data.releases.map((r) => [r.run_id, r.worker, r.status, r.server_ids.join(", "), r.updated_at])) +
+    `\n原始不可覆盖证据仍位于 hosts/<host_id>/runs/<run_id>/ 或 releases/<run_id>/；通过 ops.mjs inspect-run 核对。此视图不移动、不替代执行回执，不导出 env、凭据账本或配置镜像。\n`;
+}
+
+export function renderHtml(data, template = readFileSync(TEMPLATE, "utf8")) {
+  template = template.replace(/\r\n?/g, "\n");
+  for (const marker of ["{{FLEET_DATA}}", "{{SCRIPT_CSP}}", "{{STYLE_CSP}}"]) if (template.split(marker).length !== 2) throw new OpsError(`HTML template must contain one ${marker}`);
+  const payload = JSON.stringify(data).replace(/[<>&\u2028\u2029]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+  let html = template.replace("{{FLEET_DATA}}", () => payload);
+  const scripts = [...html.matchAll(/<script(?:\s[^>]*)?>([\s\S]*?)<\/script>/g)].filter((m) => !m[0].startsWith('<script type="application/json"'));
+  const styles = [...html.matchAll(/<style>([\s\S]*?)<\/style>/g)];
+  if (scripts.length !== 1 || styles.length !== 1) throw new OpsError("offline template requires one audited inline script and style");
+  const csp = (s) => "sha256-" + createHash("sha256").update(s).digest("base64");
+  html = html.replace("{{SCRIPT_CSP}}", csp(scripts[0][1])).replace("{{STYLE_CSP}}", csp(styles[0][1]));
+  return html;
+}
+
+export function generateFleet(state, { at = new Date(), staleHours = 24 } = {}) {
+  statePath(state);
+  return withLock(join(state, "records", ".locks", "views"), { operation: "fleet" }, () => {
+    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 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);
+    const folder = join(state, "records", "views", viewId);
+    const files = { "inventory.json": JSON.stringify(data, null, 2) + "\n", "index.html": html, "FLEET.md": markdown };
+    const receipt = { schema_version: 1, artifact: "ops-fleet-receipt", view_id: viewId, source_digest: data.source_digest,
+      files: Object.fromEntries(Object.entries(files).map(([name, body]) => [name, digest(Buffer.from(body))])) };
+    noSymlinks(folder);
+    if (existsSync(folder)) {
+      const old = readBoundedJson(join(folder, "manifest.json"));
+      if (digest(old) !== digest(receipt)) throw new OpsError("existing view receipt differs; preserve evidence");
+    } else {
+      for (const [name, body] of Object.entries(files)) atomicWrite(join(folder, name), body, 0o600, { exclusive: true });
+      writeJson(join(folder, "manifest.json"), receipt, { exclusive: true });
+    }
+    for (const [name, expected] of Object.entries(receipt.files)) {
+      const path = join(folder, name); noSymlinks(path, { allowMissing: false });
+      if (digest(readFileSync(path)) !== expected) throw new OpsError("view readback mismatch; previous landing page preserved");
+    }
+    catalogUnlocked(state);
+    if (digest(readRegistry(state)) !== data.source_digest) throw new OpsError("catalog drift during rendering; previous landing page preserved");
+    const prefix = `records/views/${viewId}/`;
+    // Publish one landing page last; JSON + HTML always belong to the same immutable generation.
+    atomicWrite(join(state, "FLEET.md"), renderMarkdown(data, prefix + "index.html", prefix + "inventory.json"));
+    return { status: "generated", view_id: viewId, markdown: join(state, "FLEET.md"), html: join(folder, "index.html"),
+      json: join(folder, "inventory.json"), source_revision: data.source_revision, servers: data.servers.length, projects: data.projects.length,
+      note: "Local restricted snapshot only; no server connection, no live health claim, no credential export" };
+  });
+}

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

@@ -0,0 +1,149 @@
+/** Bounded, read-only SSH/public-key and runtime checks; never installs or changes sshd. */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, posix } from "node:path";
+import { digest, identifier, newId, now, noSymlinks, OpsError, withLock, writeJson } from "./core.mjs";
+import { readBoundedJson, readRegistry, statePath, targetDigest } from "./workspace.mjs";
+
+export const CHECK_IDS = Object.freeze([
+  "registration", "ssh-publickey", "machine-identity", "linux", "node-runtime",
+  "deployment-root", "disk-space", "memory", "docker-daemon", "compose-version", "docker-data-root",
+  "least-privilege", "time-sync", "firewall", "egress", "backup-restore",
+]);
+const profiles = new Set(["base", "compose", "native"]);
+const statuses = new Set(["pass", "fail", "warn", "unknown", "not-applicable"]);
+
+function version(v) {
+  const m = typeof v === "string" && /(?:^|\s)v?(\d+)\.(\d+)\.(\d+)(?:\s|$|[-+])/.exec(v);
+  return m ? m.slice(1).map(Number) : null;
+}
+function atLeast(v, min) {
+  const found = version(v);
+  if (!found) return null;
+  for (let i = 0; i < 3; i++) if (found[i] !== min[i]) return found[i] > min[i];
+  return true;
+}
+function nodeSupported(v) {
+  const parsed = version(v);
+  return parsed ? atLeast(v, [22, 22, 3]) && parsed[0] < 25 : null;
+}
+function result(id, value, required, detail) {
+  return { id, status: value == null ? "unknown" : value ? "pass" : "fail", required, detail };
+}
+
+export function assessServer(host, { profile = "base", inventory = null, keyLogin = null,
+  minFreeMiB = 1024, minMemoryMiB = 256 } = {}) {
+  if (!profiles.has(profile)) throw new OpsError("profile must be base, compose or native");
+  for (const n of [minFreeMiB, minMemoryMiB]) if (!Number.isSafeInteger(n) || n < 1) throw new OpsError("resource thresholds must be positive integer MiB");
+  const inv = inventory;
+  const dc = inv?.docker_control;
+  const requiredRuntime = profile !== "base";
+  const disk = inv?.diagnostics?.disks?.[host.root]?.free;
+  const memory = inv?.diagnostics?.memory?.MemAvailable;
+  const checks = [
+    result("registration", true, true, "Registered resource; not proof of connectivity"),
+    host.transport === "ssh" ? result("ssh-publickey", keyLogin, true, "Strict pinned host key; publickey only; no password fallback")
+      : { id: "ssh-publickey", status: "not-applicable", required: false, detail: "Explicit local target; not the controller by inference" },
+    result("machine-identity", inv ? inv.identity === host.identity : null, true, "Observed machine identity must equal registered identity"),
+    result("linux", inv ? inv.platform === "linux" : null, requiredRuntime, "This readiness profile covers Linux; other platforms retain legacy support"),
+    result("node-runtime", nodeSupported(inv?.tools?.node?.version), requiredRuntime, "Node >=22.22.3 <25; missing Node does not prevent initial registration"),
+    result("deployment-root", inv?.snapshots?.[host.root] ? inv.snapshots[host.root].kind === "directory" : null, requiredRuntime, "Dedicated root exists without symlink traversal; does not prove write permission"),
+    result("disk-space", Number.isFinite(disk) ? disk >= minFreeMiB * 1024 * 1024 : null, requiredRuntime, `At least ${minFreeMiB} MiB free on root filesystem; project capacity still requires sizing`),
+    result("memory", Number.isFinite(memory) ? memory >= minMemoryMiB * 1024 * 1024 : null, requiredRuntime, `At least ${minMemoryMiB} MiB available; not a workload capacity guarantee`),
+    result("docker-daemon", dc ? dc.status === "observed" && typeof dc.endpoint === "string" && dc.endpoint.startsWith("unix://") : null, profile === "compose", "Reachable local Linux Docker daemon; remote Docker contexts are not this server"),
+    result("compose-version", atLeast(dc?.compose_version, [2, 30, 0]), profile === "compose", "Compose >=2.30 for raw env_file; container health remains a deployment check"),
+    result("docker-data-root", dc?.status === "observed" ? dc.data_root === posix.join(host.root, "_runtime/docker") : null, profile === "compose", "Existing Docker data must never be silently moved"),
+    ...["least-privilege", "time-sync", "firewall", "egress", "backup-restore"].map((id) => ({
+      id, status: "unknown", required: false, detail: "Requires requirement-specific evidence; no automatic mutation or blanket hardening",
+    })),
+  ];
+  return checks;
+}
+
+export function readiness(checks, checkedAt, { at = new Date(), staleHours = 24 } = {}) {
+  if (!Number.isFinite(staleHours) || staleHours <= 0) throw new OpsError("staleHours must be positive");
+  const timestamp = Date.parse(checkedAt);
+  if (!Number.isFinite(timestamp) || !Number.isFinite(at.getTime())) return "unknown";
+  if (timestamp > at.getTime() + 60000) return "unknown";
+  if (at.getTime() - timestamp > staleHours * 3600000) return "stale";
+  if (!Array.isArray(checks) || !checks.length) return "unknown";
+  const required = checks.filter((c) => c.required);
+  if (!required.length) return "unknown";
+  if (required.some((c) => c.status === "fail")) return "blocked";
+  if (required.some((c) => c.status !== "pass")) return "unknown";
+  return "ready";
+}
+
+export function validateCheck(report, host) {
+  if (report?.schema_version !== 1 || report.artifact !== "ops-server-check" || report.host_id !== host.host_id
+    || !profiles.has(report.profile) || !Number.isFinite(Date.parse(report.checked_at)) || !Array.isArray(report.checks)) {
+    throw new OpsError("invalid server check report");
+  }
+  const found = new Set();
+  for (const c of report.checks) {
+    if (!CHECK_IDS.includes(c.id) || found.has(c.id) || !statuses.has(c.status) || typeof c.required !== "boolean") throw new OpsError("invalid or duplicate check item");
+    found.add(c.id);
+  }
+  if (found.size !== CHECK_IDS.length) throw new OpsError("incomplete server checklist");
+  if (!/^[a-f0-9]{64}$/.test(report.host_digest || "")) throw new OpsError("missing check host digest");
+  return report;
+}
+
+export function latestCheck(state, host) {
+  identifier(host.host_id);
+  const folder = join(state, "records", "servers", host.host_id, "checks");
+  const pointer = join(folder, "latest.json");
+  noSymlinks(pointer);
+  if (!existsSync(pointer)) return null;
+  const p = readBoundedJson(pointer);
+  identifier(p.check_id, "check_id");
+  const value = readBoundedJson(join(folder, p.check_id + ".json"));
+  if (digest(value) !== p.digest) throw new OpsError("server check receipt digest mismatch");
+  validateCheck(value, host);
+  return value;
+}
+
+export async function checkServer(state, serverId, options = {}, adapter = null) {
+  statePath(state);
+  identifier(serverId, "server");
+  const registry = readRegistry(state);
+  const host = registry.hosts[serverId];
+  if (!host) throw new OpsError("unknown server; enroll through S first");
+  if (host.platform !== "linux") throw new OpsError("server-check currently covers Linux only; use the existing platform-specific probe for other servers");
+  // Reject malformed options before performing any network reads.
+  assessServer(host, options);
+  const pinnedTarget = targetDigest(host);
+  if (!adapter) {
+    const transport = await import("./transport.mjs");
+    adapter = { call: transport.call, sshArgv: transport.sshArgv, spawn: spawnSync };
+  }
+  let keyLogin = null, inventory = null;
+  if (host.transport === "ssh") {
+    const argv = adapter.sshArgv(host.connection);
+    argv.push("-o", "PreferredAuthentications=publickey", "-o", "PasswordAuthentication=no",
+      "-o", "KbdInteractiveAuthentication=no", "--", host.connection.username + "@" + host.connection.hostname, "true");
+    const p = adapter.spawn(argv[0], argv.slice(1), { encoding: "utf8", timeout: 30000, maxBuffer: 1024 * 1024, windowsHide: true });
+    keyLogin = !p.error && p.status === 0;
+  }
+  if (host.transport === "local" || keyLogin) {
+    try { inventory = adapter.call(host, { action: "probe", include_docker: true, disk_roots: [host.root], paths: [host.root] }, { timeout: 180 }); }
+    catch { /* A failed read is not evidence of health; keep inventory-dependent checks unknown. */ }
+  }
+  const report = {
+    schema_version: 1, artifact: "ops-server-check", host_id: serverId,
+    profile: options.profile ?? "base", checked_at: now(), host_digest: pinnedTarget,
+    checks: assessServer(host, { ...options, keyLogin, inventory }),
+  };
+  validateCheck(report, host);
+  // Refuse to attribute observations to a changed endpoint or identity.
+  if (targetDigest(readRegistry(state).hosts[serverId]) !== report.host_digest) throw new OpsError("server changed while checking; do not publish misattributed evidence");
+  const checkId = newId("check");
+  const folder = join(state, "records", "servers", serverId, "checks");
+  withLock(join(state, "records", ".locks", "check-" + serverId), { operation: "server-check" }, () => {
+    writeJson(join(folder, checkId + ".json"), report, { exclusive: true });
+    writeJson(join(folder, "latest.json"), { check_id: checkId, digest: digest(report) });
+  });
+  const status = readiness(report.checks, report.checked_at);
+  return { status, server_id: serverId, profile: report.profile, report: join(folder, checkId + ".json"), checks: report.checks,
+    note: "Read-only baseline, not application readiness, live monitoring or production acceptance" };
+}

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

@@ -0,0 +1,313 @@
+/** One user-authorized task, frozen specifications, legacy digest-bound plans, no automatic retry. */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, relative as pathRelative, resolve } from "node:path";
+import { atomicWrite, digest, exact, identifier, noSymlinks, now, OpsError, redact, withLock, writeJson } from "./core.mjs";
+import { fileDigest, ids, readBoundedJson, readRegistry, route, statePath, targetDigest, containedPath } from "./workspace.mjs";
+
+const DESTRUCTIVE_ACK = "I-APPROVE-THIS-EXACT-DESTRUCTIVE-TASK";
+const MAX_INPUT_BYTES = 256 * 1024 * 1024;
+const fields = new Set(["schema_version", "task_id", "title", "plan", "valid_for_hours", "scope", "input_paths", "steps"]);
+const scopeFields = new Set(["scope", "server_ids", "project_ids", "related_project_ids", "allow_policy_changes", "allow_public_ingress", "allow_destructive"]);
+
+async function runtime() {
+  const [model, planner, execution] = await Promise.all([import("./model.mjs"), import("./planner.mjs"), import("./execution.mjs")]);
+  return { ...model, compilePlan: planner.compilePlan, engineDigest: execution.engineDigest, approval: execution.approval, apply: execution.apply };
+}
+function taskFolder(state, taskId) { return join(statePath(state), "records", "tasks", identifier(taskId, "task_id")); }
+function active(task, at = Date.now()) {
+  if (!Number.isFinite(Date.parse(task.expires_at)) || at >= Date.parse(task.expires_at)) throw new OpsError("task authorization expired; form a new bounded task");
+}
+export { targetDigest } from "./workspace.mjs";
+function allowedProjects(scope) { return new Set([...scope.project_ids, ...scope.related_project_ids]); }
+
+export function validateRequest(request, registry) {
+  exact(request, fields, fields, "task request");
+  if (request.schema_version !== 1) throw new OpsError("task request schema_version must be 1");
+  identifier(request.task_id, "task_id");
+  if (typeof request.title !== "string" || request.title.trim().length < 3 || request.title.length > 200) throw new OpsError("task needs a meaningful title (3..200 characters)");
+  if (typeof request.plan !== "string" || request.plan.trim().length < 40 || request.plan.length > 32000) throw new OpsError("task needs a detailed, already-disclosed Plan Mode description (40..32000 characters)");
+  if (!Number.isInteger(request.valid_for_hours) || request.valid_for_hours < 1 || request.valid_for_hours > 24) throw new OpsError("valid_for_hours must be 1..24");
+  const s = request.scope;
+  exact(s, scopeFields, scopeFields, "task scope");
+  if (!["server", "project"].includes(s.scope)) throw new OpsError("task execution covers H/D only; controller initialization and SSH enrollment retain their own entry");
+  ids(s.server_ids, "server_ids");
+  // A task may sequence several H steps and include explicitly named impact hosts;
+  // the standalone H routing command still selects one primary server.
+  route(registry, { scope: s.scope, server_ids: s.scope === "server" ? s.server_ids.slice(0, 1) : s.server_ids, project_ids: s.project_ids });
+  for (const id of s.server_ids) if (!Object.hasOwn(registry.hosts, id)) throw new OpsError(`unknown task server: ${id}`);
+  ids(s.related_project_ids, "related_project_ids");
+  for (const id of s.related_project_ids) if (!Object.hasOwn(registry.projects, id) || s.project_ids.includes(id)) throw new OpsError("related projects must be distinct registered impact/dependency IDs");
+  for (const key of ["allow_policy_changes", "allow_public_ingress", "allow_destructive"]) if (typeof s[key] !== "boolean") throw new OpsError(`${key} must be explicit boolean`);
+  if (!Array.isArray(request.input_paths) || new Set(request.input_paths).size !== request.input_paths.length) throw new OpsError("input_paths must be distinct absolute files/directories");
+  if (!Array.isArray(request.steps) || request.steps.length < 1 || request.steps.length > 20) throw new OpsError("task must contain 1..20 ordered steps");
+  const seen = new Set();
+  for (const step of request.steps) {
+    exact(step, new Set(["id", "title", "spec"]), new Set(["id", "title", "spec"]), "task step");
+    identifier(step.id, "step.id");
+    if (seen.has(step.id)) throw new OpsError("duplicate task step ID");
+    seen.add(step.id);
+    if (typeof step.title !== "string" || !step.title.trim() || step.title.length > 200) throw new OpsError("step title must be 1..200 characters");
+    assertSpecScope(step.spec, s, registry);
+  }
+  return request;
+}
+
+function inScopeDeployment(dep, scope, label) {
+  if (!dep || !scope.server_ids.includes(dep.host_id) || !allowedProjects(scope).has(dep.project_id)) throw new OpsError(`deployment/consumer outside task scope: ${label}`);
+}
+export function assertSpecScope(spec, scope, registry) {
+  if (!spec || typeof spec !== "object" || !["H", "D"].includes(spec.worker)) throw new OpsError("task step must use the existing H or D spec contract");
+  if (spec.worker === "H" && (["deployments", "allocations", "bindings", "provision", "retire_deployments", "retire_bindings"].some((k) => (spec[k] || []).length) || (spec.resource_updates?.projects || []).length)) throw new OpsError("H cannot create or retire project resources; use a separate D step");
+  if (spec.worker === "D" && ((spec.host_actions || []).length || (spec.resource_updates?.hosts || []).length || spec.public_ingress !== undefined)) throw new OpsError("D cannot configure server-level resources; use a separate H prerequisite step");
+  if (scope.scope === "server" && spec.worker !== "H") throw new OpsError("server task cannot silently become project deployment; select D explicitly");
+  if ((["migrate", "uninstall"].includes(spec.operation) || (spec.retire_deployments || []).length || (spec.host_actions || []).some((a) => a.kind === "purge-quarantine")) && !scope.allow_destructive) {
+    throw new OpsError("destructive/migration scope not authorized");
+  }
+  if (spec.plaintext_documentation !== undefined && spec.plaintext_documentation !== registry.policies.plaintext_documentation && !scope.allow_policy_changes) throw new OpsError("policy change outside task scope");
+  if (spec.public_ingress !== undefined && digest(spec.public_ingress) !== digest(registry.public_ingress ?? null) && !scope.allow_public_ingress) throw new OpsError("public ingress change outside task scope");
+  const projects = allowedProjects(scope);
+  const deployments = { ...registry.deployments, ...Object.fromEntries((spec.deployments || []).map((d) => [d.deployment_id, d])) };
+  const checkHost = (id) => { if (!scope.server_ids.includes(id)) throw new OpsError(`server outside task scope: ${id}`); };
+  for (const id of spec.hosts || []) checkHost(id);
+  for (const h of spec.resource_updates?.hosts || []) {
+    checkHost(h.host_id);
+    if (targetDigest(h) !== targetDigest(registry.hosts[h.host_id])) throw new OpsError("connection/identity/root changes belong to a new S task, not delegated H/D approval");
+  }
+  for (const action of spec.host_actions || []) checkHost(action.host_id);
+  for (const d of spec.deployments || []) inScopeDeployment(d, scope, d.deployment_id);
+  for (const p of spec.resource_updates?.projects || []) if (!projects.has(p.project_id)) throw new OpsError(`project outside task scope: ${p.project_id}`);
+  for (const id of [...(spec.retire_deployments || []), ...(spec.acknowledged_consumers || [])]) inScopeDeployment(deployments[id], scope, id);
+  // Inspect resource references, not arbitrary project JSON/env keys named host_id.
+  const ingressHosts = (v) => {
+    if (Array.isArray(v)) for (const x of v) ingressHosts(x);
+    else if (v && typeof v === "object") for (const [key, x] of Object.entries(v)) {
+      if ((key === "host_id" || key.endsWith("_host_id")) && typeof x === "string") checkHost(x);
+      else ingressHosts(x);
+    }
+  };
+  ingressHosts(spec.public_ingress);
+  const allocations = { ...registry.allocations, ...Object.fromEntries((spec.allocations || []).map((a) => [a.allocation_id, a])) };
+  const bindings = { ...registry.bindings, ...Object.fromEntries((spec.bindings || []).map((b) => [b.binding_id, b])) };
+  const allocation = (id) => {
+    const a = allocations[id];
+    if (!a || !projects.has(a.owner_project_id) || (a.shared_owners || []).some((p) => !projects.has(p))) throw new OpsError(`allocation owner outside task scope: ${id}`);
+    inScopeDeployment(deployments[a.provider_deployment_id], scope, a.provider_deployment_id);
+  };
+  const binding = (id) => {
+    const b = bindings[id];
+    if (!b) throw new OpsError(`unknown binding: ${id}`);
+    inScopeDeployment(deployments[b.consumer_deployment_id], scope, b.consumer_deployment_id);
+    if (b.provider_deployment_id) inScopeDeployment(deployments[b.provider_deployment_id], scope, b.provider_deployment_id);
+    if (b.allocation_id) allocation(b.allocation_id);
+  };
+  for (const a of spec.allocations || []) allocation(a.allocation_id);
+  for (const p of spec.provision || []) allocation(p.allocation_id);
+  for (const b of spec.bindings || []) binding(b.binding_id);
+  for (const id of spec.retire_bindings || []) binding(id);
+  // Include known dependency/impact closure before the planner performs remote reads.
+  const touched = new Set([...(spec.deployments || []).map((d) => d.deployment_id), ...(spec.retire_deployments || [])]);
+  const hostActions = new Set((spec.host_actions || []).map((a) => a.host_id));
+  for (const d of Object.values(registry.deployments)) if (hostActions.has(d.host_id) && d.status !== "retired") touched.add(d.deployment_id);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const b of Object.values({ ...registry.bindings, ...Object.fromEntries((spec.bindings || []).map((b) => [b.binding_id, b])) })) {
+      if (b.status === "retired" || (!touched.has(b.consumer_deployment_id) && !touched.has(b.provider_deployment_id))) continue;
+      for (const id of [b.consumer_deployment_id, b.provider_deployment_id].filter(Boolean)) if (!touched.has(id)) { touched.add(id); changed = true; }
+    }
+  }
+  for (const id of touched) inScopeDeployment(deployments[id], scope, id);
+}
+
+export function pinInputs(paths) {
+  const files = {};
+  let bytes = 0;
+  const walk = (p) => {
+    noSymlinks(p, { allowMissing: false });
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      for (const name of readdirSync(p).sort()) walk(join(p, name));
+    } else if (st.isFile()) {
+      if (Object.hasOwn(files, p)) return;
+      bytes += st.size;
+      if (Object.keys(files).length >= 10000 || bytes > MAX_INPUT_BYTES) throw new OpsError("task inputs exceed 10000 files/256 MiB; use a reviewed bounded artifact tree");
+      files[p] = fileDigest(p);
+    } else throw new OpsError("task input must be a regular file or directory");
+  };
+  for (const p of paths) {
+    if (typeof p !== "string" || !isAbsolute(p) || p.split(/[\\/]/).includes("..")) throw new OpsError("task input paths must be absolute without traversal");
+    walk(resolve(p));
+  }
+  return files;
+}
+
+function markdown(task) {
+  return `# ${redact(task.request.title, [])}\n\n` +
+    `任务：\`${task.request.task_id}\`；控制端：\`${task.controller_id}\`；有效期：${task.expires_at}。\n\n` +
+    `范围：${task.request.scope.scope}；服务器：${task.request.scope.server_ids.join(", ")}；项目：${task.request.scope.project_ids.join(", ") || "无"}；影响/依赖项目：${task.request.scope.related_project_ids.join(", ") || "无"}。\n\n` +
+    `## Plan Mode\n\n${redact(task.request.plan, [])}\n\n` +
+    `## 固定顺序与精确规格\n\n` + task.request.steps.map((s, i) =>
+      `${i + 1}. ${redact(s.title, [])} — worker=${s.spec.worker}，operation=${s.spec.operation}，spec SHA256=${digest(s.spec)}；[受限规格](specs/${s.id}.json)。`
+    ).join("\n") + `\n\n## 授权边界\n\n此文件不是授权。明确实施请求且已展示上述计划后，入口可记录一次原始任务确认，不逐步骤再问。运行器只为这些冻结规格产生的范围内计划写入关联任务的机械批准；不声称用户逐一确认了未来的计划摘要。\n\n` +
+    `策略变更：${task.request.scope.allow_policy_changes}；公网映射：${task.request.scope.allow_public_ingress}；破坏性/迁移：${task.request.scope.allow_destructive}。\n\n` +
+    `输入文件：${Object.keys(task.input_digests).length}；执行器 SHA256：${task.engine_digest}。连接、凭据账本、输入文件、执行器漂移或过期即停止。\n\n` +
+    `失败/unknown/docs_pending 不自动重试、不自动迁移回滚。原 plan/approval/journal/双边回执仍是执行事实源。\n`;
+}
+
+export async function prepareTask(state, request, adapter = null) {
+  statePath(state);
+  adapter ??= await runtime();
+  const registry = adapter.load(state);
+  readRegistry(state);
+  validateRequest(request, registry);
+  for (const step of request.steps) adapter.validate(step.spec, "spec");
+  const task = {
+    schema_version: 1, artifact: "ops-task", controller_id: registry.controller.controller_id,
+    created_at: now(), expires_at: new Date(Date.now() + request.valid_for_hours * 3600000).toISOString(),
+    registry_revision: registry.revision, request: structuredClone(request),
+    engine_digest: adapter.engineDigest(), ledger_digest: digest(adapter.ledgerLoad(state)),
+    targets: Object.fromEntries(request.scope.server_ids.map((id) => [id, targetDigest(registry.hosts[id])])),
+    input_digests: pinInputs(request.input_paths),
+  };
+  const folder = taskFolder(state, request.task_id);
+  return withLock(join(state, "records", ".locks", "task-" + request.task_id), { operation: "task-plan" }, () => {
+    if (existsSync(folder)) throw new OpsError("task ID already exists; never overwrite task evidence");
+    for (const step of request.steps) writeJson(join(folder, "specs", step.id + ".json"), step.spec, { exclusive: true });
+    atomicWrite(join(folder, "PLAN.md"), markdown(task), 0o600, { exclusive: true });
+    writeJson(join(folder, "summary.json"), { schema_version: 1, artifact: "ops-task-summary", task_id: request.task_id,
+      scope: request.scope.scope, server_ids: request.scope.server_ids, project_ids: request.scope.project_ids,
+      related_project_ids: request.scope.related_project_ids, step_ids: request.steps.map((s) => s.id), created_at: task.created_at }, { exclusive: true });
+    // Commit marker written last. A crashed preparation is preserved, never auto-repaired.
+    writeJson(join(folder, "task.json"), task, { exclusive: true });
+    return { status: "prepared-not-authorized", task_id: request.task_id, task_digest: digest(task), plan: join(folder, "PLAN.md"), steps: request.steps.length };
+  });
+}
+
+export function authorizeTask(state, taskId, expected, by, statement, ackDestructive = null) {
+  const folder = taskFolder(state, taskId);
+  const task = readBoundedJson(join(folder, "task.json"));
+  if (digest(task) !== expected) throw new OpsError("task digest mismatch; reread the disclosed task plan");
+  active(task);
+  validateRequest(task.request, readRegistry(state));
+  if (typeof by !== "string" || !by.trim() || typeof statement !== "string" || statement.trim().length < 8) throw new OpsError("identified approver and explicit original task confirmation are required");
+  if (task.request.scope.allow_destructive && ackDestructive !== DESTRUCTIVE_ACK) throw new OpsError("destructive task requires an independently explicit exact-task acknowledgement");
+  const value = { schema_version: 1, artifact: "ops-task-authorization", task_id: taskId, task_digest: expected,
+    approved_by: by, statement, approved_at: now(), decision: "approved", destructive_ack: ackDestructive };
+  return withLock(join(state, "records", ".locks", "task-" + taskId), { operation: "task-authorize" }, () => {
+    writeJson(join(folder, "authorization.json"), value, { exclusive: true });
+    return { status: "authorized", task_id: taskId, task_digest: expected, note: "No per-step conversational re-confirmation inside this frozen task" };
+  });
+}
+
+export function assertPlanScope(plan, task, registry) {
+  const s = task.request.scope, projects = allowedProjects(s);
+  if (plan.controller_id !== task.controller_id || plan.engine_digest !== task.engine_digest) throw new OpsError("compiled plan controller/engine differs from authorized task");
+  for (const [id, h] of Object.entries(plan.hosts || {})) if (!s.server_ids.includes(id) || targetDigest(h) !== task.targets[id]) throw new OpsError(`compiled plan target outside authorization: ${id}`);
+  const scope = plan.registry_scope;
+  if (!scope) throw new OpsError("compiled plan has no registry scope");
+  for (const id of scope.hosts || []) if (!s.server_ids.includes(id)) throw new OpsError(`catalog server outside task: ${id}`);
+  for (const id of scope.projects || []) if (!projects.has(id)) throw new OpsError(`catalog project outside task: ${id}`);
+  for (const id of [...(scope.deployments || []), ...(plan.document_targets || []), ...(plan.affected_consumers || [])]) {
+    inScopeDeployment(plan.registry_after.deployments[id] || registry.deployments[id], s, id);
+  }
+  for (const id of scope.allocations || []) {
+    const a = plan.registry_after.allocations?.[id] || registry.allocations[id];
+    if (!a || !projects.has(a.owner_project_id) || (a.shared_owners || []).some((p) => !projects.has(p))) throw new OpsError("compiled allocation owner outside task");
+    inScopeDeployment(plan.registry_after.deployments[a.provider_deployment_id] || registry.deployments[a.provider_deployment_id], s, a.provider_deployment_id);
+  }
+  for (const id of scope.bindings || []) {
+    const b = plan.registry_after.bindings?.[id] || registry.bindings[id];
+    if (!b) throw new OpsError("compiled binding not found");
+    for (const did of [b.consumer_deployment_id, b.provider_deployment_id].filter(Boolean)) inScopeDeployment(plan.registry_after.deployments[did] || registry.deployments[did], s, did);
+  }
+  // A compiler omission must not hide an unrelated catalog mutation.
+  for (const group of ["hosts", "projects", "deployments", "allocations", "bindings"]) {
+    for (const id of new Set([...Object.keys(registry[group]), ...Object.keys(plan.registry_after[group] || {})])) {
+      if (digest(registry[group][id] ?? null) !== digest(plan.registry_after[group]?.[id] ?? null) && !(scope[group] || []).includes(id)) throw new OpsError(`unscoped compiled catalog change: ${group}/${id}`);
+    }
+  }
+  if ((scope.policies || digest(registry.policies) !== digest(plan.registry_after.policies)) && !s.allow_policy_changes) throw new OpsError("compiled plan changes unauthorized policies");
+  if ((scope.public_ingress || digest(registry.public_ingress ?? null) !== digest(plan.registry_after.public_ingress ?? null)) && !s.allow_public_ingress) throw new OpsError("compiled plan changes unauthorized public ingress");
+  for (const op of plan.operations || []) {
+    if (!s.server_ids.includes(op.host_id)) throw new OpsError("operation target outside task");
+    if (op.deployment_id) inScopeDeployment(plan.registry_after.deployments[op.deployment_id], s, op.deployment_id);
+    if (op.kind === "purge-quarantine" && !s.allow_destructive) throw new OpsError("unauthorized purge operation");
+  }
+  for (const [p, d] of Object.entries(plan.source_digests || {})) if (task.input_digests[resolve(p)] !== d) throw new OpsError(`unreviewed or changed local source input: ${p}; pin it in input_paths before authorization`);
+}
+
+function preflight(state, task, adapter, first = false) {
+  active(task);
+  const registry = adapter.load(state);
+  if (registry.controller.controller_id !== task.controller_id) throw new OpsError("task controller mismatch");
+  if (first && registry.revision !== task.registry_revision) throw new OpsError("catalog changed after task preparation; form a new disclosed task");
+  if (adapter.engineDigest() !== task.engine_digest) throw new OpsError("task executor drifted");
+  if (digest(adapter.ledgerLoad(state)) !== task.ledger_digest) throw new OpsError("credential ledger drifted after task authorization");
+  for (const [id, expected] of Object.entries(task.targets)) if (!registry.hosts[id] || targetDigest(registry.hosts[id]) !== expected) throw new OpsError(`task connection/identity drift: ${id}`);
+  if (digest(pinInputs(task.request.input_paths)) !== digest(task.input_digests)) throw new OpsError("task input files changed, disappeared or were added");
+  return registry;
+}
+
+export async function runTask(state, taskId, adapter = null) {
+  const folder = taskFolder(state, taskId);
+  adapter ??= await runtime();
+  const task = readBoundedJson(join(folder, "task.json"));
+  const auth = readBoundedJson(join(folder, "authorization.json"));
+  if (auth.artifact !== "ops-task-authorization" || auth.decision !== "approved" || auth.task_id !== taskId || auth.task_digest !== digest(task)) throw new OpsError("missing or mismatched task authorization");
+  if (task.request.task_id !== taskId) throw new OpsError("task path/identity mismatch");
+  return withLock(join(state, "records", ".locks", "task-" + taskId), { operation: "task-run", task_id: taskId }, () => {
+    if (existsSync(join(folder, "started.json"))) throw new OpsError("task already started; inspect its progress and original run receipts, never automatically replay it");
+    const initial = preflight(state, task, adapter, true);
+    validateRequest(task.request, initial);
+    writeJson(join(folder, "started.json"), { task_digest: digest(task), at: now() }, { exclusive: true });
+    const progress = { schema_version: 1, artifact: "ops-task-result", task_id: taskId, status: "running", steps: [], started_at: now(), updated_at: now() };
+    let phase = "planning";
+    try {
+      for (const step of task.request.steps) {
+        phase = "planning";
+        const registry = preflight(state, task, adapter);
+        assertSpecScope(step.spec, task.request.scope, registry);
+        const path = join(folder, "specs", step.id + ".json");
+        if (digest(readBoundedJson(path)) !== digest(step.spec)) throw new OpsError("frozen step specification drifted");
+        const compiled = adapter.compilePlan(state, path);
+        containedPath(state, compiled.plan_path);
+        const plan = readBoundedJson(compiled.plan_path);
+        identifier(compiled.run_id, "run_id");
+        if (compiled.run_id !== plan.run_id || plan.worker !== step.spec.worker || plan.operation !== step.spec.operation) throw new OpsError("compiled run identity/worker/operation mismatch");
+        if (digest(plan) !== compiled.plan_digest) throw new OpsError("compiled plan digest mismatch");
+        const row = { step_id: step.id, run_id: compiled.run_id, plan_digest: compiled.plan_digest,
+          plan_path: pathRelative(state, compiled.plan_path).replaceAll("\\", "/"), status: "planned-not-authorized" };
+        progress.steps.push(row);
+        progress.updated_at = now();
+        writeJson(join(folder, "progress.json"), progress);
+        assertPlanScope(plan, task, registry);
+        // Check inputs again after compilation and before delegating any approval.
+        preflight(state, task, adapter);
+        adapter.approval(state, compiled.run_id, compiled.plan_digest, "task:" + taskId,
+          `Delegated exact-spec authorization from task ${taskId}, digest ${auth.task_digest}; original approver ${auth.approved_by}.`);
+        row.status = "executing";
+        writeJson(join(folder, "progress.json"), progress);
+        preflight(state, task, adapter);
+        phase = "applying";
+        const result = adapter.apply(state, compiled.run_id);
+        row.status = result.status;
+        progress.updated_at = now();
+        writeJson(join(folder, "progress.json"), progress);
+        phase = "between-steps";
+        if (result.status !== "completed") {
+          progress.status = ["failed", "unknown", "docs_pending", "partial", "blocked"].includes(result.status) ? result.status : "blocked";
+          break;
+        }
+      }
+      if (progress.status === "running") progress.status = "completed";
+    } catch (error) {
+      progress.status = phase === "applying" ? "unknown" : "blocked";
+      progress.error = redact(error.message || String(error), []).slice(0, 2000);
+    }
+    progress.updated_at = now();
+    progress.recovery = progress.status === "completed" ? "none" : "Inspect progress and the original run with inspect-run; no automatic resume, docs-sync or migration retry. New actions need a new bounded task.";
+    writeJson(join(folder, "progress.json"), progress);
+    writeJson(join(folder, "result.json"), progress, { exclusive: true });
+    return { ...progress, record: folder };
+  });
+}