@namewta/speculo 1.0.16 → 1.0.18

package/template/workflows/ops/common/schemas/task-request.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:task-request:v1",
+  "type": "object",
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "task_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "title": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 200
+    },
+    "plan": {
+      "type": "string",
+      "minLength": 40,
+      "maxLength": 32000
+    },
+    "valid_for_hours": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 24
+    },
+    "scope": {
+      "type": "object",
+      "properties": {
+        "scope": {
+          "enum": [
+            "server",
+            "project"
+          ]
+        },
+        "server_ids": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "uniqueItems": true,
+          "minItems": 1
+        },
+        "project_ids": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "uniqueItems": true,
+          "maxItems": 1
+        },
+        "related_project_ids": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "uniqueItems": true
+        },
+        "allow_policy_changes": {
+          "type": "boolean"
+        },
+        "allow_public_ingress": {
+          "type": "boolean"
+        },
+        "allow_destructive": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "scope",
+        "server_ids",
+        "project_ids",
+        "related_project_ids",
+        "allow_policy_changes",
+        "allow_public_ingress",
+        "allow_destructive"
+      ],
+      "additionalProperties": false
+    },
+    "input_paths": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 20,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "spec": {
+            "$ref": "urn:speculo:ops:spec:v1"
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "spec"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "schema_version",
+    "task_id",
+    "title",
+    "plan",
+    "valid_for_hours",
+    "scope",
+    "input_paths",
+    "steps"
+  ],
+  "additionalProperties": false,
+  "$comment": "Register the existing spec.schema.json $id with a standards-compliant validator. Runtime validates each frozen spec through the original spec gateway."
+}

package/template/workflows/ops/common/templates/FLEET.html

@@ -0,0 +1,61 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src '{{SCRIPT_CSP}}'; style-src '{{STYLE_CSP}}'; base-uri 'none'; form-action 'none'; connect-src 'none'; img-src 'none'">
+<meta name="referrer" content="no-referrer">
+<title>Speculo · OPS 资产清单</title>
+<style>
+:root{color-scheme:light;--ink:#182633;--muted:#596b78;--line:#d7e0e5;--paper:#f3f6f8;--accent:#126c62;--card:#fff}*{box-sizing:border-box}body{margin:0;background:var(--paper);color:var(--ink);font:15px/1.65 system-ui,-apple-system,"Segoe UI",sans-serif}header{background:#142d36;color:white;padding:34px max(24px,calc((100vw - 1360px)/2));border-bottom:5px solid #45b9a6}.eyebrow{letter-spacing:.15em;font-size:12px;text-transform:uppercase;color:#a2d8d0}h1{font-size:32px;line-height:1.25;margin:10px 0}h2{font-size:21px;margin:0 0 14px}p{margin:8px 0}header p{color:#cbdde3;max-width:1000px}main{max-width:1408px;margin:auto;padding:24px}.stats{display:grid;grid-template-columns:repeat(4,1fr);gap:14px;margin:0 0 22px}.stat,section,.notice,.filters{background:var(--card);border:1px solid var(--line);border-radius:10px}.stat{padding:16px 20px}.stat strong{display:block;font-size:30px;line-height:1.25}.stat span{color:var(--muted);font-size:13px}.notice{padding:14px 18px;margin-bottom:20px;border-left:4px solid #c38835}.filters{padding:16px;display:flex;flex-wrap:wrap;gap:12px;align-items:end;position:sticky;top:0;z-index:1;box-shadow:0 4px 15px #142d3610}label{display:flex;flex-direction:column;font-size:12px;color:var(--muted);gap:4px}label.search{flex:1;min-width:220px}input,select,button{font:inherit;border:1px solid #b9cbd1;border-radius:6px;padding:9px 12px;background:#fff;color:var(--ink)}input:focus,select:focus,button:focus{outline:3px solid #79c8bb;outline-offset:2px}button{cursor:pointer}button.link{border:0;padding:0;color:var(--accent);background:transparent;text-align:left;text-decoration:underline;text-underline-offset:3px}section{padding:22px;margin:20px 0}.scroll{overflow:auto}table{width:100%;border-collapse:collapse;font-size:13px}th{text-align:left;background:#eef4f5;font-weight:650;color:#3e5764}td,th{padding:11px 12px;border-bottom:1px solid var(--line);vertical-align:top;overflow-wrap:anywhere}tr:last-child td{border-bottom:0}td{max-width:380px;min-width:80px}.muted{color:var(--muted);font-size:12px}.badge{display:inline-block;padding:2px 9px;border-radius:20px;background:#e8eef2;font-size:12px;white-space:nowrap}.pass,.ready,.completed{background:#e0f2e8;color:#216844}.fail,.failed,.blocked{background:#fbe6e5;color:#993b37}.unknown,.stale,.docs_pending,.interrupted,.needs-inspection,.incomplete{background:#fff0d6;color:#865719}.details{font-size:12px}summary{cursor:pointer;color:var(--accent)}.detail-list{padding:6px 0}.check{display:flex;justify-content:space-between;gap:16px;margin:4px 0}.empty{padding:20px;color:var(--muted)}footer{overflow-wrap:anywhere;color:var(--muted);font-size:12px;padding:10px 0 30px}code{font-size:12px}noscript{display:block;padding:24px}@media(max-width:760px){.stats{grid-template-columns:repeat(2,1fr)}main{padding:14px}section{padding:16px}.filters{position:static}header{padding:25px 20px}h1{font-size:25px}td,th{padding:9px}}@media print{.filters{display:none}header{background:white;color:var(--ink);padding:10px}header p{color:var(--muted)}section,.stat{break-inside:avoid}main{padding:0}}
+</style>
+</head>
+<body>
+<header><div class="eyebrow">Speculo / Operations workspace</div><h1>服务器与项目，一处查看</h1><p id="meta"></p><p>服务器 → 项目 · 项目 → 服务器 · 系统服务与业务部署分别记录</p></header>
+<main>
+<div class="stats" id="stats"></div>
+<div class="notice"><strong>这是离线快照，不是实时监控。</strong> <span id="notice-text">“ready”仅说明指定 profile 的必需检查项通过；“completed”是记录中的执行结果。未测、过期、身份变化及未完成文档均不能视为生产验收通过。</span></div>
+<div class="filters"><label class="search">搜索服务器、项目、部署、版本或路径<input id="search" type="search" placeholder="输入关键词" autocomplete="off"></label><label>服务器<select id="server"><option value="">全部服务器</option></select></label><label>项目<select id="project"><option value="">全部项目</option></select></label><label>部署记录状态<select id="status"><option value="">全部状态</option></select></label><button id="reset" type="button">重置筛选</button></div>
+<section><h2>01 / 服务器清单</h2><p class="muted">点击项目名称反向查询部署位置。展开检查项可查看尚未验证的基础环境。</p><div class="scroll" id="servers"></div></section>
+<section><h2>02 / 项目清单</h2><p class="muted">项目是逻辑资源；同一项目可以部署在多台服务器。退役实例保留历史记录。</p><div class="scroll" id="projects"></div></section>
+<section><h2>03 / 部署实例</h2><div class="scroll" id="deployments"></div></section>
+<section><h2>04 / 系统服务与依赖</h2><p class="muted">Nginx、WireGuard 等主机级服务不伪装成业务项目；共享依赖通过部署关系显示。</p><div class="scroll" id="services"></div><div class="scroll" id="bindings"></div></section>
+<section><h2>05 / 任务与执行记录</h2><p class="muted">缺少已验证终态的任务需核对原始回执；看板不证明进程仍在运行，也不触发重试、回滚或部署。</p><div class="scroll" id="tasks"></div><details><summary>查看原始 Run / Release 索引</summary><div class="scroll" id="releases"></div></details></section>
+<footer id="footer"></footer>
+</main>
+<noscript>此看板需要本地 JavaScript 才能筛选；同目录 FLEET.md 提供无需脚本的清单。</noscript>
+<script type="application/json" id="fleet-data">{{FLEET_DATA}}</script>
+<script>
+"use strict";
+const data=JSON.parse(document.getElementById("fleet-data").textContent);
+const $=(id)=>document.getElementById(id);
+const byDeployment=new Map(data.deployments.map(d=>[d.deployment_id,d]));
+const labels={registration:"资源登记","ssh-publickey":"SSH 公钥认证","machine-identity":"服务器身份",linux:"Linux 系统","node-runtime":"Node 运行环境","deployment-root":"部署根存在","disk-space":"磁盘空间",memory:"可用内存","docker-daemon":"本机 Docker","compose-version":"Compose 版本","docker-data-root":"Docker 数据目录","least-privilege":"最小权限","time-sync":"时间同步",firewall:"防火墙",egress:"外部依赖连通性","backup-restore":"备份恢复"};
+const node=(tag,value,cls)=>{const n=document.createElement(tag);if(value!=null)n.textContent=String(value);if(cls)n.className=cls;return n;};
+const badge=(value)=>node("span",value||"unknown","badge "+String(value||"unknown").replace(/[^a-z_-]/g,""));
+function choose(kind,id){$(kind).value=id;$(kind==="server"?"project":"server").value="";$("search").value="";$("status").value="";render();}
+const link=(kind,id)=>{const n=node("button",id,"link");n.type="button";n.addEventListener("click",()=>choose(kind,id));return n;};
+function links(kind,ids){const n=node("div");if(!ids.length)n.textContent="—";ids.forEach((id,i)=>{if(i)n.append(document.createTextNode(", "));n.append(link(kind,id));});return n;}
+function table(target,headers,rows){const root=$(target);root.replaceChildren();if(!rows.length){root.append(node("p","没有匹配记录。","empty"));return;}const t=node("table"),head=node("thead"),hr=node("tr"),body=node("tbody");for(const h of headers)hr.append(node("th",h));head.append(hr);for(const row of rows){const tr=node("tr");for(const value of row){const td=node("td");if(value instanceof Node)td.append(value);else td.textContent=value==null||value===""?"—":String(value);tr.append(td);}body.append(tr);}t.append(head,body);root.append(t);}
+function checks(s){const d=node("details",null,"details");d.append(node("summary",`${s.profile||"未检查"} · ${s.checked_at||"无时间记录"}`));const wrap=node("div",null,"detail-list");if(!s.checks.length)wrap.textContent="未检查：不能据此推断服务器可用。";for(const c of s.checks){const row=node("div",null,"check");row.append(node("span",(labels[c.id]||c.id)+(c.required?" *":"")),badge(c.status));wrap.append(row);}d.append(wrap);return d;}
+for(const [id,values] of [["server",data.servers.map(s=>s.server_id)],["project",data.projects.map(p=>p.project_id)],["status",[...new Set(data.deployments.map(d=>d.status))].sort()]])for(const value of values){const o=node("option",value);o.value=value;$(id).append(o);}
+$("meta").textContent=`控制端 ${data.controller_id}  /  资源修订 ${data.source_revision}  /  生成于 ${data.generated_at}`;
+$("notice-text").textContent=data.notice;
+for(const [label,value] of [["已登记服务器",data.servers.length],["项目",data.projects.length],["部署实例（含历史）",data.deployments.length],["需关注的服务器",data.servers.filter(s=>s.readiness!=="ready").length]]){const box=node("div",null,"stat");box.append(node("strong",value),node("span",label));$("stats").append(box);}
+$("footer").textContent=`数据格式 v${data.schema_version} · 检查过期阈值 ${data.stale_hours} 小时 · 资源摘要 ${data.source_digest}。此文件可能包含内部拓扑，请勿直接公开发布。`;
+function render(){const server=$("server").value,project=$("project").value,st=$("status").value,q=$("search").value.toLocaleLowerCase();const match=(v)=>!q||JSON.stringify(v).toLocaleLowerCase().includes(q);
+const ds=data.deployments.filter(d=>(!server||d.server_id===server)&&(!project||d.project_id===project)&&(!st||d.status===st)&&match(d));
+const ss=data.servers.filter(s=>(!server||s.server_id===server)&&(!project||s.deployment_ids.some(id=>byDeployment.get(id)?.project_id===project))&&(!st||ds.some(d=>d.server_id===s.server_id))&&(match(s)||ds.some(d=>d.server_id===s.server_id)));
+const ps=data.projects.filter(p=>(!project||p.project_id===project)&&(!server||p.deployment_ids.some(id=>byDeployment.get(id)?.server_id===server))&&(!st||ds.some(d=>d.project_id===p.project_id))&&(match(p)||ds.some(d=>d.project_id===p.project_id)));
+table("servers",["服务器 / 名称","地址 / 系统","检查结果","检查详情（* 必需项）","项目","部署根"],ss.map(s=>[links("server",[s.server_id]),`${s.name} · ${s.address}${s.port?":"+s.port:""} / ${s.platform}`,badge(s.readiness),checks(s),links("project",s.project_ids),s.root]));
+table("projects",["项目","名称","类别 / 服务类型","所在服务器","部署数量"],ps.map(p=>[link("project",p.project_id),p.name,`${p.kind} / ${p.service_type||"—"}`,links("server",p.server_ids),p.deployment_ids.length]));
+table("deployments",["部署实例","项目 / 服务器","环境 / 方法","记录状态","计划版本","验证版本","根目录 / 更新时间"],ds.map(d=>{const where=node("div");where.append(link("project",d.project_id),node("div"),link("server",d.server_id));return[d.deployment_id,where,`${d.environment} / ${d.instance} / ${d.method}`,badge(d.status),d.desired_version,d.observed_version,`${d.root} / ${d.updated_at||"未验证"}`];}));
+table("services",["服务器","主机级服务","类型","systemd 单元","监听端口"],ss.flatMap(s=>s.host_services.map(v=>[link("server",s.server_id),v.service_id,v.kind,v.unit,v.port])));
+const depIds=new Set(ds.map(d=>d.deployment_id));table("bindings",["依赖关系","消费者部署","提供者部署","模式 / 状态"],data.bindings.filter(b=>depIds.has(b.consumer_deployment_id)||depIds.has(b.provider_deployment_id)).map(b=>[b.binding_id,b.consumer_deployment_id,b.provider_deployment_id||"external（不推断服务器）",`${b.mode} / ${b.status}`]));
+table("tasks",["任务","范围","服务器","项目","记录状态","Run"],data.tasks.filter(t=>(!server||t.server_ids.includes(server))&&(!project||t.project_ids.includes(project))&&match(t)).map(t=>[t.task_id,t.scope,links("server",t.server_ids),links("project",t.project_ids),badge(t.status),t.run_ids.join(", ")]));
+table("releases",["Run","Work","服务器","部署实例","记录状态","更新时间"],data.releases.filter(r=>(!server||r.server_ids.includes(server))&&(!project||r.deployment_ids.some(id=>byDeployment.get(id)?.project_id===project))&&match(r)).map(r=>[r.run_id,r.worker,links("server",r.server_ids),r.deployment_ids.join(", "),badge(r.status),r.updated_at]));}
+for(const id of ["search","server","project","status"])$(id).addEventListener("input",render);
+$("reset").addEventListener("click",()=>{for(const id of ["search","server","project","status"])$(id).value="";render();});render();
+</script>
+</body>
+</html>

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

@@ -580,8 +580,9 @@ test("planner contracts", async (t) => {
   });
 });
 
-test("real native and dual docs", () => runFx((fx) => {
-    const [info, , result] = fx.runSpec();
+test("real native and explicitly approved plaintext dual docs", () => runFx((fx) => {
+    const input = fx.spec(); input.plaintext_documentation = true;
+    const [info, , result] = fx.runSpec(input);
     assert.equal(result.status, "completed", JSON.stringify(result));
     const dep = model.load(fx.state).deployments["app-a-prod"];
     assert.equal(dep.observed_version, "v1");
@@ -980,3 +981,33 @@ test("host services and public ingress are delivered", () => runFx((fx) => {
   assert.ok(fleet.includes("公网访问内网"));
   assert.ok(!fleet.includes("<code>"));
 }));
+
+
+test("new controllers keep secrets out of default documentation", () => runFx((fx) => {
+  assert.equal(model.load(fx.state).policies.plaintext_documentation, false);
+  const [info, plan, result] = fx.runSpec();
+  assert.equal(result.status, "completed", JSON.stringify(result));
+  const remote = join(fx.target, "app-a");
+  const local = join(fx.state, "hosts", "node-a", "deployments", "app-a-prod");
+  for (const path of [join(remote,"README.md"), join(remote,"OPERATIONS.md"), join(local,"README.md"), join(local,"OPERATIONS.md"), join(fx.state,"FLEET-DEPLOYMENTS.md"), join(fx.target,"DEPLOYMENTS.md")]) {
+    assert.ok(!readFileSync(path,"utf8").includes(PASSWORD), path);
+  }
+  assert.match(readFileSync(join(local,"OPERATIONS.md"),"utf8"), /secret_ref:.*app-auth@1/);
+  assert.ok(readFileSync(join(remote,"env","app.env"),"utf8").includes(PASSWORD));
+  assert.equal(plan.operations.find((o) => o.path?.endsWith("env/app.env")).mode, 0o600);
+  if (process.platform !== "win32") assert.equal(statSync(join(remote,"env","app.env")).mode & 0o777, 0o600);
+  assert.equal(readJson(join(local,"docs-receipt.json")).status, "both-sides-verified");
+}));
+
+test("legacy absent policy retains previous explicit plaintext behavior without migration", () => {
+  const status = emptyStatus(); delete status.policies.plaintext_documentation;
+  assert.equal(docs.plaintextDocumentation(status), true);
+  status.policies.plaintext_documentation = false;
+  assert.equal(docs.plaintextDocumentation(status), false);
+});
+
+test("credential-bearing config rejects permissive explicit file modes", () => runFx((fx) => {
+  const spec = fx.spec();
+  spec.deployments[0].files.push({path:"config/auth.conf",content:"{{credential:app-auth@1:password}}",mode:0o644});
+  assert.throws(() => fx.plan(spec), /secret-bearing|private|0600|permission/i);
+}));

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

@@ -0,0 +1,246 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, existsSync, statSync, symlinkSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { digest, emptyStatus, now, writeJson } from "../tools/opslib/core.mjs";
+import { route, readRegistry, statePath, targetDigest } from "../tools/opslib/workspace.mjs";
+import { assessServer, readiness, checkServer, latestCheck } from "../tools/opslib/server_checks.mjs";
+import { assertSpecScope, prepareTask, authorizeTask, runTask } from "../tools/opslib/tasks.mjs";
+import { projectFleet, renderHtml, renderMarkdown, generateFleet } from "../tools/opslib/fleet.mjs";
+import { parseWorkspaceArgs, workspaceCommand } from "../tools/opslib/workspace_cli.mjs";
+
+function fixture(t) {
+  const root = mkdtempSync(join(tmpdir(), "speculo-workspace-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const state = join(root, "state"); mkdirSync(state);
+  const s = emptyStatus(); s.controller = { controller_id: "controller-a", state_root: state, created_at: now() };
+  for (const id of ["node-a", "node-b"]) s.hosts[id] = { host_id: id, display_name: id, platform: "linux", transport: "local", root: join(root, id), identity: "a".repeat(64), connection: {} };
+  for (const id of ["app-a", "app-b"]) s.projects[id] = { project_id: id, display_name: id, kind: "app", service_type: null, source: { type: "local", location: join(root, "source"), revision: "v1" } };
+  writeJson(join(state, "status.json"), s);
+  const save = () => writeJson(join(state, "status.json"), s);
+  return { root, state, s, save };
+}
+function request(id = "task-one") {
+  return { schema_version: 1, task_id: id, title: "Prepare one selected server", plan: "Inspect the explicitly selected server, prepare only its declared directory, verify the result, retain the original evidence, and never retry an unknown operation.", valid_for_hours: 2,
+    scope: { scope: "server", server_ids: ["node-a"], project_ids: [], related_project_ids: [], allow_policy_changes: false, allow_public_ingress: false, allow_destructive: false }, input_paths: [],
+    steps: [{ id: "prepare-root", title: "Prepare explicit directory", spec: { schema_version: 1, worker: "H", operation: "prepare", reason: "unit fixture", rollback_note: "retain", hosts: ["node-a"], host_actions: [{ host_id: "node-a", kind: "mkdir", path: "_host/cache", reason: "Create only the temporary fixture cache directory" }] } }] };
+}
+function inventory(h) {
+  return { identity: h.identity, platform: "linux", tools: { node: { version: "v22.22.3" } },
+    snapshots: { [h.root]: { kind: "directory" } }, diagnostics: { disks: { [h.root]: { free: 4 * 1024 ** 3 } }, memory: { MemAvailable: 1024 ** 3 } },
+    docker_control: { status: "observed", endpoint: "unix:///var/run/docker.sock", data_root: join(h.root, "_runtime/docker"), compose_version: "2.30.0" } };
+}
+function adapterFor(f, options = {}) {
+  const calls = { compile: 0, approve: 0, apply: 0 };
+  let engine = "e".repeat(64), ledger = { entries: {} };
+  const adapter = { load: readRegistry, validate: (s, kind) => { assert.equal(kind, "spec"); assert.equal(s.schema_version, 1); }, engineDigest: () => engine, ledgerLoad: () => ledger,
+    compilePlan: (state, path) => {
+      calls.compile++;
+      const spec = JSON.parse(readFileSync(path, "utf8")), current = readRegistry(state), id = `run-${calls.compile}`;
+      const plan = { run_id: id, worker: spec.worker, operation: spec.operation, controller_id: current.controller.controller_id, engine_digest: engine,
+        hosts: { "node-a": current.hosts["node-a"] }, registry_scope: { hosts: ["node-a"], projects: [], deployments: [], allocations: [], bindings: [], policies: false, public_ingress: false },
+        registry_after: structuredClone(current), operations: [{ host_id: "node-a", kind: "mkdir", deployment_id: null }], document_targets: [], affected_consumers: [], source_digests: {} };
+      options.plan?.(plan);
+      const planPath = join(state, "hosts/node-a/runs", id, "plan.json"); writeJson(planPath, plan);
+      return { run_id: id, plan_path: planPath, plan_digest: digest(plan) };
+    },
+    approval: (_state, _run, _digest, by, statement) => { calls.approve++; assert.match(by, /^task:/); assert.match(statement, /Delegated exact-spec/); },
+    apply: (state, _run) => { calls.apply++; options.beforeApply?.(); if (options.throwApply) throw new Error("transport disconnected");
+      const s = readRegistry(state); s.revision++; writeJson(join(state, "status.json"), s); return { status: options.result ?? "completed" }; },
+  };
+  return { adapter, calls, changeEngine: () => { engine = "f".repeat(64); }, changeLedger: () => { ledger = { entries: { changed: true } }; } };
+}
+async function authorized(f, req, adapter) {
+  const p = await prepareTask(f.state, req, adapter);
+  authorizeTask(f.state, req.task_id, p.task_digest, "test-user", "Execute this exact task without per-step reconfirmation", req.scope.allow_destructive ? "I-APPROVE-THIS-EXACT-DESTRUCTIVE-TASK" : null);
+  return p;
+}
+
+test("explicit layer routing distinguishes controller, access, server, project and inventory", (t) => {
+  const f = fixture(t);
+  assert.equal(route(f.s, { scope: "controller", server_ids: [], project_ids: [] }).work, "I-initialize");
+  assert.equal(route(f.s, { scope: "server", server_ids: ["node-a"], project_ids: [] }).work, "H-host-manage");
+  assert.equal(route(f.s, { scope: "project", server_ids: ["node-b"], project_ids: ["app-a"] }).work, "D-project-deploy");
+  assert.equal(route(f.s, { scope: "inventory", server_ids: [], project_ids: [] }).work, "V-inventory-view");
+  assert.deepEqual(route(f.s, { scope: "access", server_ids: ["new-node"], project_ids: [] }).registration_required, ["new-node"]);
+  for (const c of [
+    { scope: "controller", server_ids: ["node-a"], project_ids: [] }, { scope: "server", server_ids: ["node-a"], project_ids: ["app-a"] },
+    { scope: "project", server_ids: [], project_ids: ["app-a"] }, { scope: "server", server_ids: ["missing"], project_ids: [] },
+    { scope: "project", server_ids: ["node-a", "node-a"], project_ids: ["app-a"] },
+  ]) assert.throws(() => route(f.s, c));
+});
+test("workspace rejects guessed roots, traversal, symlinks, duplicate JSON keys and orphan deployments", (t) => {
+  const f = fixture(t);
+  for (const path of [".", "/", f.state + "/../state"]) assert.throws(() => statePath(path));
+  const link = join(f.root, "linked"); symlinkSync(f.state, link, "dir"); assert.throws(() => statePath(link), /symlink/);
+  writeFileSync(join(f.state, "status.json"), '{"schema_version":3,"schema_version":3}'); assert.throws(() => readRegistry(f.state), /duplicate JSON/);
+  f.s.deployments.dangling = { deployment_id: "dangling", host_id: "missing", project_id: "app-a" }; f.save(); assert.throws(() => readRegistry(f.state), /orphan/);
+});
+test("workspace argument parser rejects duplicates, unknown flags and missing values", () => {
+  assert.equal(workspaceCommand(["--state", "/x", "fleet"]), "fleet"); assert.equal(workspaceCommand(["--state", "/x", "apply", "--run", "abc"]), null);
+  assert.deepEqual(parseWorkspaceArgs(["fleet", "--state", "/x", "--stale-hours", "8"]), { command: "fleet", state: "/x", "stale-hours": "8" });
+  for (const a of [["fleet"], ["fleet", "--state", "/x", "--state", "/y"], ["fleet", "--state"], ["fleet", "--state", "/x", "--project", "app-a"]]) assert.throws(() => parseWorkspaceArgs(a));
+});
+test("CLI help works without network, server dependencies or state", () => {
+  const path = resolve(dirname(fileURLToPath(import.meta.url)), "../tools/ops.mjs");
+  const r = spawnSync(process.execPath, [path, "workspace-help"], { encoding: "utf8" }); assert.equal(r.status, 0, r.stderr); assert.match(r.stdout, /server-check/);
+});
+test("Linux checklist distinguishes missing, failed, profile-ready and stale evidence", (t) => {
+  const f = fixture(t), h = f.s.hosts["node-a"], inv = inventory(h), at = new Date("2026-01-01T00:00:00Z");
+  assert.equal(readiness(assessServer(h), at.toISOString(), { at }), "unknown");
+  assert.equal(readiness(assessServer(h, { profile: "compose", inventory: inv }), at.toISOString(), { at }), "ready");
+  assert.equal(readiness(assessServer(h, { profile: "compose", inventory: inv }), at.toISOString(), { at: new Date("2026-01-03T00:00:00Z") }), "stale");
+  assert.equal(readiness(assessServer(h, { inventory: inv }), "2027-01-01", { at }), "unknown");
+  for (const change of [i => { i.identity = "b".repeat(64); }, i => { i.tools.node.version = "v22.16.0"; }, i => { i.tools.node.version = "v25.0.0"; }, i => { i.docker_control.compose_version = "2.29.9"; }, i => { i.docker_control.endpoint = "tcp://other:2375"; }, i => { i.docker_control.data_root = "/var/lib/docker"; }, i => { i.diagnostics.memory.MemAvailable = 1; }]) {
+    const v = structuredClone(inv); change(v); assert.equal(readiness(assessServer(h, { profile: "compose", inventory: v }), at.toISOString(), { at }), "blocked");
+  }
+});
+test("server check uses pinned public-key-only SSH and records restricted evidence", async (t) => {
+  const f = fixture(t), h = f.s.hosts["node-a"], kh = join(f.root, "known_hosts"); writeFileSync(kh, "fixture verified key");
+  Object.assign(h, { transport: "ssh", connection: { hostname: "example.invalid", username: "deploy", known_hosts: kh } }); f.save();
+  let spawned = 0, called = 0;
+  const a = { sshArgv: () => ["ssh", "-o", "StrictHostKeyChecking=yes"], spawn: (_cmd, args) => { spawned++; assert.ok(args.includes("PasswordAuthentication=no")); assert.ok(args.includes("KbdInteractiveAuthentication=no")); return { status: 0 }; }, call: () => { called++; return inventory(h); } };
+  await assert.rejects(checkServer(f.state, "node-a", { profile: "bad" }, a)); assert.equal(spawned, 0);
+  const r = await checkServer(f.state, "node-a", { profile: "compose" }, a); assert.equal(r.status, "ready"); assert.equal(called, 1);
+  const check = latestCheck(f.state, h); assert.equal(check.host_digest, targetDigest(h)); assert.equal(check.checks.length, 16);
+  if (process.platform !== "win32") assert.equal(statSync(r.report).mode & 0o777, 0o600);
+  writeFileSync(kh, "different key"); assert.notEqual(check.host_digest, targetDigest(h));
+});
+test("failed SSH login never triggers Node probe and is not reported ready", async (t) => {
+  const f = fixture(t), h = f.s.hosts["node-a"], kh = join(f.root, "known_hosts"); writeFileSync(kh, "fixture"); Object.assign(h, { transport: "ssh", connection: { hostname: "invalid", username: "deploy", known_hosts: kh } }); f.save();
+  const r = await checkServer(f.state, "node-a", {}, { sshArgv: () => ["ssh"], spawn: () => ({ status: 255 }), call: () => { throw new Error("must not probe"); } });
+  assert.equal(r.status, "blocked"); assert.equal(r.checks.find(c => c.id === "machine-identity").status, "unknown");
+});
+test("task preparation does not execute; one authorization runs ordered steps without repeated confirmation", async (t) => {
+  const f = fixture(t), a = adapterFor(f), req = request(); req.steps.push({ ...structuredClone(req.steps[0]), id: "verify-root" });
+  const p = await prepareTask(f.state, req, a.adapter); assert.deepEqual(a.calls, { compile: 0, approve: 0, apply: 0 });
+  await assert.rejects(runTask(f.state, req.task_id, a.adapter), /missing path/);
+  assert.throws(() => authorizeTask(f.state, req.task_id, "0".repeat(64), "test-user", "explicit confirmation"), /digest mismatch/);
+  authorizeTask(f.state, req.task_id, p.task_digest, "test-user", "Execute the already confirmed exact task");
+  const r = await runTask(f.state, req.task_id, a.adapter); assert.equal(r.status, "completed"); assert.equal(r.steps.length, 2); assert.deepEqual(a.calls, { compile: 2, approve: 2, apply: 2 });
+  await assert.rejects(runTask(f.state, req.task_id, a.adapter), /already started/); assert.equal(a.calls.apply, 2);
+});
+test("task IDs, frozen specs and authorization are immutable", async (t) => {
+  const f = fixture(t), a = adapterFor(f), req = request(), p = await authorized(f, req, a.adapter);
+  await assert.rejects(prepareTask(f.state, req, a.adapter), /already exists/);
+  assert.throws(() => authorizeTask(f.state, req.task_id, p.task_digest, "test-user", "same explicit confirmation"), /immutable/);
+  writeJson(join(f.state, "records/tasks/task-one/specs/prepare-root.json"), { changed: true });
+  assert.equal((await runTask(f.state, req.task_id, a.adapter)).status, "blocked"); assert.equal(a.calls.compile, 0);
+});
+test("task rejects server/project confusion and indirect provider/consumer scope escalation before planning", (t) => {
+  const f = fixture(t), req = request();
+  assert.throws(() => assertSpecScope({ ...req.steps[0].spec, worker: "D", host_actions: [] }, req.scope, f.s), /cannot silently/);
+  assert.throws(() => assertSpecScope({ ...req.steps[0].spec, hosts: ["node-b"] }, req.scope, f.s), /outside task/);
+  f.s.deployments.provider = { deployment_id: "provider", host_id: "node-b", project_id: "app-b", status: "completed" };
+  f.s.allocations.db = { allocation_id: "db", provider_deployment_id: "provider", owner_project_id: "app-a", shared_owners: [] };
+  assert.throws(() => assertSpecScope({ schema_version: 1, worker: "D", operation: "deploy", provision: [{ allocation_id: "db" }] }, { ...req.scope, scope: "project", project_ids: ["app-a"], related_project_ids: ["app-b"] }, f.s), /outside task/);
+  f.s.deployments.consumer = { deployment_id: "consumer", host_id: "node-a", project_id: "app-a", status: "completed" };
+  f.s.bindings.link = { binding_id: "link", provider_deployment_id: "provider", consumer_deployment_id: "consumer", status: "active" };
+  assert.throws(() => assertSpecScope(req.steps[0].spec, { ...req.scope, related_project_ids: ["app-a", "app-b"] }, f.s), /outside task/);
+});
+test("task stops on expiry, executor, credential, input and catalog drift before any execution", async (t) => {
+  for (const kind of ["expiry", "engine", "ledger", "input", "catalog"]) {
+    await t.test(kind, async (sub) => {
+      const f = fixture(sub), a = adapterFor(f), req = request();
+      const input = join(f.root, "installer.bin"); writeFileSync(input, "reviewed"); req.input_paths = [input];
+      if (kind === "expiry") {
+        const p = await prepareTask(f.state, req, a.adapter); const path = join(f.state, "records/tasks/task-one/task.json"), task = JSON.parse(readFileSync(path, "utf8")); task.expires_at = "2020-01-01T00:00:00Z"; writeJson(path, task);
+        assert.throws(() => authorizeTask(f.state, req.task_id, digest(task), "test-user", "explicit confirmed task"), /expired/); assert.ok(p.task_digest); return;
+      }
+      await authorized(f, req, a.adapter);
+      if (kind === "engine") a.changeEngine(); if (kind === "ledger") a.changeLedger(); if (kind === "input") writeFileSync(input, "modified"); if (kind === "catalog") { f.s.revision++; f.save(); }
+      await assert.rejects(runTask(f.state, req.task_id, a.adapter), /drift|changed/); assert.equal(a.calls.apply, 0);
+    });
+  }
+});
+test("destructive and policy changes need explicitly bounded authorization", async (t) => {
+  const f = fixture(t), a = adapterFor(f), req = request(); req.steps[0].spec.operation = "migrate";
+  await assert.rejects(prepareTask(f.state, req, a.adapter), /destructive/);
+  assert.throws(() => assertSpecScope({ worker: "D", operation: "deploy", retire_deployments: ["app-a-prod"] }, { ...request().scope, scope: "project", project_ids: ["app-a"] }, f.s), /destructive/);
+  req.scope.allow_destructive = true; const p = await prepareTask(f.state, req, a.adapter);
+  assert.throws(() => authorizeTask(f.state, req.task_id, p.task_digest, "test-user", "explicit confirmed task"), /independently explicit/);
+  assert.throws(() => assertSpecScope({ ...request().steps[0].spec, plaintext_documentation: true }, request().scope, f.s), /policy change/);
+});
+test("compiled scope escalation and unpinned artifacts stop before approval and preserve plan references", async (t) => {
+  for (const kind of ["target", "source", "hidden-catalog"]) await t.test(kind, async sub => {
+    const f = fixture(sub), a = adapterFor(f, { plan: p => {
+      if (kind === "target") p.hosts["node-b"] = f.s.hosts["node-b"];
+      if (kind === "source") p.source_digests[join(f.root, "unreviewed")] = "a".repeat(64);
+      if (kind === "hidden-catalog") p.registry_after.projects["app-b"].service_type = "changed";
+    } }); await authorized(f, request(), a.adapter);
+    const r = await runTask(f.state, "task-one", a.adapter); assert.equal(r.status, "blocked"); assert.equal(a.calls.approve, 0); assert.equal(a.calls.apply, 0); assert.equal(r.steps[0].run_id, "run-1");
+  });
+});
+test("failed, unknown and docs_pending results stop later steps and cannot replay", async (t) => {
+  for (const outcome of ["failed", "unknown", "docs_pending", "throw"]) await t.test(outcome, async sub => {
+    const f = fixture(sub), a = adapterFor(f, { result: outcome, throwApply: outcome === "throw" }), req = request(); req.steps.push({ ...structuredClone(req.steps[0]), id: "next-step" });
+    await authorized(f, req, a.adapter); const r = await runTask(f.state, req.task_id, a.adapter);
+    assert.equal(r.status, outcome === "throw" ? "unknown" : outcome); assert.equal(a.calls.apply, 1); assert.equal(a.calls.compile, 1);
+    await assert.rejects(runTask(f.state, req.task_id, a.adapter), /already started/);
+  });
+});
+test("fleet projects both directions, host services and external providers without exporting secret fields", (t) => {
+  const f = fixture(t), sentinel = "NEVER-EXPORT-THIS-SECRET";
+  f.s.hosts["node-a"].connection.password = sentinel; f.s.hosts["node-a"].host_services = [{ id: "edge", kind: "nginx", notes: sentinel, public_url: `https://invalid/?token=${sentinel}` }];
+  f.s.projects["app-a"].source = { repository: `https://user:${sentinel}@invalid` };
+  f.s.deployments["app-prod"] = { deployment_id: "app-prod", host_id: "node-a", project_id: "app-a", status: "docs_pending", version: "v2", observed_version: "v1", root: "/srv/ops/app-a", env: { PASSWORD: sentinel }, notes: [sentinel], credential_refs: [sentinel] };
+  f.s.bindings.external = { binding_id: "external", consumer_deployment_id: "app-prod", provider_deployment_id: null, mode: "external", status: "active", credential_ref: sentinel };
+  const d = projectFleet(f.s); assert.deepEqual(d.servers[0].project_ids, ["app-a"]); assert.deepEqual(d.projects[0].server_ids, ["node-a"]); assert.equal(d.servers[0].host_services[0].service_id, "edge");
+  assert.equal(d.deployments[0].desired_version, "v2"); assert.equal(d.deployments[0].observed_version, "v1"); assert.equal(d.bindings[0].provider_deployment_id, null);
+  assert.ok(!JSON.stringify(d).includes(sentinel)); assert.ok(!renderHtml(d).includes(sentinel)); assert.ok(!renderMarkdown(d).includes(sentinel));
+});
+test("HTML rendering is deterministic, escaped, offline and CSP hashes match executable bytes", (t) => {
+  const f = fixture(t); f.s.hosts["node-a"].display_name = '</script><img src=x onerror="alert(1)">'; const d = projectFleet(f.s, {}, [], { at: new Date("2026-01-01") });
+  const html = renderHtml(d); assert.equal(html, renderHtml(d)); assert.ok(!html.includes(f.s.hosts["node-a"].display_name)); assert.ok(html.includes("\\u003c/script\\u003e")); assert.ok(!html.includes("innerHTML")); assert.ok(!html.includes("fetch("));
+  const script = [...html.matchAll(/<script(?:\s[^>]*)?>([\s\S]*?)<\/script>/g)].find(m => m[0].startsWith("<script>"))[1];
+  assert.ok(html.includes("sha256-" + createHash("sha256").update(script).digest("base64"))); assert.match(html, /connect-src 'none'/);
+  const md = renderMarkdown(d); assert.ok(!md.includes("<img"));
+});
+test("fleet writes immutable generations, verifies readback and retains one consistent landing page", async (t) => {
+  const f = fixture(t), at = new Date("2026-01-01T00:00:00Z");
+  // A secret ledger is deliberately unreadable JSON. View generation must not open it.
+  mkdirSync(join(f.state, "private")); writeFileSync(join(f.state, "private/credentials.json"), "NOT JSON, DO NOT READ");
+  const a = adapterFor(f); await authorized(f, request(), a.adapter);
+  const first = generateFleet(f.state, { at }), second = generateFleet(f.state, { at }); assert.equal(first.view_id, second.view_id);
+  assert.ok(readFileSync(first.markdown, "utf8").includes(first.view_id)); assert.ok(existsSync(first.html));
+  const before = readFileSync(first.markdown, "utf8"); writeFileSync(first.html, "tampered"); assert.throws(() => generateFleet(f.state, { at }), /readback mismatch/); assert.equal(readFileSync(first.markdown, "utf8"), before);
+});
+test("fleet refuses symlink outputs and catalog locks without overwriting old entry", (t) => {
+  const f = fixture(t), outside = join(f.root, "outside.txt"); writeFileSync(outside, "untouched"); symlinkSync(outside, join(f.state, "FLEET.md"));
+  assert.throws(() => generateFleet(f.state), /symlink/); assert.equal(readFileSync(outside, "utf8"), "untouched");
+  rmSync(join(f.state, "FLEET.md")); mkdirSync(join(f.state, ".locks/catalog"), { recursive: true }); assert.throws(() => generateFleet(f.state), /catalog lock/);
+});
+
+
+test("workspace task and fleet integrate with the real legacy planner/approval/apply gateway", async (t) => {
+  // A partial source overlay can run pure tests; installed-repository CI must exercise this branch.
+  const modelPath = resolve(dirname(fileURLToPath(import.meta.url)), "../tools/opslib/model.mjs");
+  if (!existsSync(modelPath)) { t.skip("legacy runtime absent in partial source overlay; full repository CI required"); return; }
+  const f = fixture(t);
+  const { fingerprint } = await import("../tools/opslib/agent.mjs");
+  const { validate } = await import("../tools/opslib/model.mjs");
+  const example = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), "../examples/task-host.example.json"), "utf8"));
+  validate(example.steps[0].spec, "spec");
+  f.s.hosts["node-a"].identity = fingerprint(); f.save();
+  writeJson(join(f.state, "private/credentials.json"), { schema_version: 1, entries: {} });
+  const p = await prepareTask(f.state, request());
+  authorizeTask(f.state, "task-one", p.task_digest, "local-test-user", "Execute only this temporary local test directory preparation");
+  const r = await runTask(f.state, "task-one");
+  assert.equal(r.status, "completed", JSON.stringify(r));
+  assert.ok(existsSync(join(f.s.hosts["node-a"].root, "_host/cache")));
+  const view = generateFleet(f.state); assert.equal(view.status, "generated");
+  const data = JSON.parse(readFileSync(view.json, "utf8")); assert.equal(data.tasks[0].status, "completed");
+  assert.ok(data.releases.some(v => v.run_id === r.steps[0].run_id));
+});
+
+test("H and D cannot be mislabeled to cross server/project boundaries", (t) => {
+  const f = fixture(t), s = request().scope;
+  const d = { deployment_id: "app-prod", host_id: "node-a", project_id: "app-a" };
+  assert.throws(() => assertSpecScope({ worker: "H", deployments: [d] }, { ...s, related_project_ids: ["app-a"] }, f.s), /H cannot/);
+  assert.throws(() => assertSpecScope({ worker: "D", host_actions: [{ host_id: "node-a", kind: "mkdir" }] }, { ...s, scope: "project", project_ids: ["app-a"] }, f.s), /D cannot/);
+  assert.doesNotThrow(() => assertSpecScope({ worker: "D", operation: "deploy", deployments: [{ ...d, compose: { services: { app: { environment: { project_id: "vendor-data-not-a-resource", host_id: "vendor-setting" } } } } }] }, { ...s, scope: "project", project_ids: ["app-a"] }, f.s));
+});

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

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
-/** OPS entry point: Node >=22, no third-party packages. */
-import { main } from "./opslib/cli.mjs";
-process.exit(main(process.argv.slice(2)));
+/** OPS entry point: Node >=22.22.3 <25, no third-party packages. */
+import { workspaceCommand } from "./opslib/workspace_cli.mjs";
+const argv = process.argv.slice(2);
+const { main } = await import(workspaceCommand(argv) ? "./opslib/workspace_cli.mjs" : "./opslib/cli.mjs");
+process.exitCode = await main(argv);

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

@@ -397,7 +397,7 @@ export function emptyStatus() {
     allocations: {},
     bindings: {},
     releases: {},
-    policies: { server_readme_credentials: false, server_operations: true, strict_docker_root: true },
+    policies: { server_readme_credentials: false, server_operations: true, strict_docker_root: true, plaintext_documentation: false },
     updated_at: null,
   };
 }

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

@@ -274,13 +274,13 @@ export function deploymentReadme(status, dep, runId, generatedAt, { ledger = nul
   out.push("## 同项目部署位置\n", replicas.sort((a, b) => a.deployment_id < b.deployment_id ? -1 : 1).map((d) => `- ${d.host_id} / ${d.deployment_id}：${code(d.root)}`).join("\n") + "\n");
   if (controller) out.push("\n本目录是部署机的配置、凭据、运行证据和远端文档记录；不声称自动复制了远端业务数据。数据备份需要独立的备份策略和回执。\n");
   if (includeCredentials) out.push(credentialsText(credentialRefs(status, dep), ledger));
-  else out.push("\n## 凭据记录\n\n本 README 默认不写密码。获授权管理员读取本项目 OPERATIONS.md（启用时）或部署机明文手册；密码未知时必须补齐，不能编造。\n");
+  else out.push("\n## 凭据记录\n\nsecret_ref: " + credentialRefs(status, dep).map(code).join(", ") + "\n\n本文件默认不写密码。凭据按 ID@版本定位受限 private/credentials.json；真实值仅在批准 plaintext_documentation 后导出。未知值不得编造。\n");
   return out.join("\n") + "\n";
 }
 
 export function hostReadme(status, hid, runId, at, { ledger = null, full = false, controller = false } = {}) {
   const host = status.hosts[hid];
-  const includeCredentials = Boolean(full && controller && ledger);
+  const includeCredentials = Boolean(full && controller && ledger && plaintextDocumentation(status));
   const rows = overviewRows(status, hid, { ledger, includeCredentials });
   const out = [
     `# 主机 ${host.display_name} / ${hid}\n`,
@@ -368,6 +368,11 @@ const KNOWLEDGE_INDEX = `# 共享知识索引
 只收录经用户确认、带来源和最后验证时间的知识，不存密码。
 `;
 
+// Legacy absent field retains existing deliberate behavior; init seeds false. Changing policy requires a new approved plan.
+export function plaintextDocumentation(status) {
+  return status.policies.plaintext_documentation ?? true;
+}
+
 export function deliveryBundle(state, plan, status, ledger, verifiedIds) {
   const at = now();
   const rid = plan.run_id;
@@ -381,9 +386,9 @@ export function deliveryBundle(state, plan, status, ledger, verifiedIds) {
   for (const did of [...new Set(verifiedIds)].sort()) {
     const d = status.deployments[did];
     const hid = d.host_id;
-    const readme = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: status.policies.server_readme_credentials });
+    const readme = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: Boolean(status.policies.server_readme_credentials && plaintextDocumentation(status)) });
     addRemote(hid, pathFor(status, d, "README.md"), readme);
-    const operations = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: true });
+    const operations = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: plaintextDocumentation(status) });
     if (status.policies.server_operations) addRemote(hid, pathFor(status, d, "OPERATIONS.md"), operations);
     addRemote(hid, pathFor(status, d, "project.yaml"), JSON.stringify(d, null, 2) + "\n");
     addRemote(hid, pathFor(status, d, "run/release-state.json"), JSON.stringify({
@@ -397,7 +402,7 @@ export function deliveryBundle(state, plan, status, ledger, verifiedIds) {
       addRemote(hid, targetJoin({ ...status.hosts[hid], root: projectroot }, "README.md"), text);
     }
     const prefix = `hosts/${hid}/deployments/${did}`;
-    local[prefix + "/README.md"] = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: true, controller: true });
+    local[prefix + "/README.md"] = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: plaintextDocumentation(status), controller: true });
     local[prefix + "/OPERATIONS.md"] = operations;
     local[prefix + "/deployment.json"] = JSON.stringify(d, null, 2) + "\n";
     local[prefix + "/server/README.md"] = readme;
@@ -420,8 +425,8 @@ export function deliveryBundle(state, plan, status, ledger, verifiedIds) {
     local[`hosts/${hid}/knowledge/host-services.json`] = hostServicesDocument(h);
     if (ingressJson) local[`hosts/${hid}/knowledge/public-ingress.json`] = ingressJson;
   }
-  local["FLEET-DEPLOYMENTS.md"] = fleetDocument(status, Object.keys(status.hosts), rid, at, { ledger, includeCredentials: true });
-  local["README.md"] = "# OPS 控制端\n\n主机记录位于 hosts/<host_id>/；项目关联位于 status.json；项目部署记录位于 hosts/<host_id>/deployments/<deployment_id>/；完整明文总册位于 FLEET-DEPLOYMENTS.md；凭据账本位于 private/credentials.json；执行证据按 host runs / release 保存。主机级入口见 hosts/<id>/knowledge/host-services.json，跨主机公网入口见 knowledge/public-ingress.json。\n\n不得清理此运行态目录来替换静态 workflow。双边文档完成由每次运行 docs-receipt.json 证明。\n";
+  local["FLEET-DEPLOYMENTS.md"] = fleetDocument(status, Object.keys(status.hosts), rid, at, { ledger, includeCredentials: plaintextDocumentation(status) });
+  local["README.md"] = "# OPS 控制端\n\n主机记录位于 hosts/<host_id>/；项目关联位于 status.json；项目部署记录位于 hosts/<host_id>/deployments/<deployment_id>/；总册位于 FLEET-DEPLOYMENTS.md（新安装默认仅引用凭据版本）；凭据账本位于 private/credentials.json；执行证据按 host runs / release 保存。主机级入口见 hosts/<id>/knowledge/host-services.json，跨主机公网入口见 knowledge/public-ingress.json。\n\n不得清理此运行态目录来替换静态 workflow。双边文档完成由每次运行 docs-receipt.json 证明。\n";
   local["docs/standards/DEPLOYMENT-STANDARD.md"] = STANDARD;
   if (!existsSync(join(state, "knowledge", "INDEX.md"))) {
     local["knowledge/INDEX.md"] = "# 共享知识索引\n\n只收录经用户批准、带来源与最后验证日期的通用知识。运行时环境和密码不自动提升为共享知识。跨主机入口规范见各主机 knowledge/public-ingress.json。\n";