cofluxd 0.11.0 → 0.13.0

package/README.md

@@ -22,6 +22,11 @@ cofluxd down            # 停止
 cofluxd uninstall [--purge]   # 卸载（--purge 连二进制/配置/凭证一并删）
 ```
 
+从 `cofluxd@0.12.0` 起，远端安装/更新会用 npm 包内置的 ed25519 公钥同时验证
+supervisor 与 worker 的 version/target/size/sha256/release statement；两个文件全部通过后才替换。
+CLI 还会取自身与 worker 的持久 release floor 较大值拒绝远端降级。`--bin-dir` 仍是本机管理员
+显式信任本地产物的开发/救援入口。
+
 默认连公共服务 `wss://api.coflux.dev/daemon`（自托管用 `--server` 改；已保存的地址继续生效，非默认时会有醒目提示）。
 
 ## 给 agent 用的命令
@@ -38,6 +43,8 @@ cofluxd ports                                             # 端口 + 可直接
 
 不需要任何凭证：daemon 用调用方 pid 反查进程树确认它属于哪个会话，**coflux 会话之外的进程一律拒绝**，权限也天然限定在该会话所属的工作区内。
 
+每个 coflux 开出来的 PTY 会话里还注入了一组 `COFLUX_*` 环境变量（由 supervisor 组装，中心只下发 id）：`COFLUX_DEVICE_ID` / `COFLUX_PROJECT_ID`（目录工作区为空串）/ `COFLUX_WORKSPACE_ID` / `COFLUX_TASK_ID` / `COFLUX_SESSION_ID` / `COFLUX_MCP_URL`。agent 读它们就知道自己在哪台设备、哪个项目/工作区/终端，值与中心 MCP `list_*` 返回的 id 完全一致，可直接传给 MCP tools。本地命令与 MCP 的分工：本工作区内的开终端/读/等/输入/播报/叫人/端口用上面的零凭证命令；开子工作区、跨工作区/跨设备读写、或从 coflux 之外接入，用中心的 `coflux` MCP（`claude mcp add --transport http coflux "$COFLUX_MCP_URL"`，一次 OAuth 授权）。supervisor 不走热升级，旧机器要 `cofluxd update && cofluxd restart` 之后会话里才有这些变量；skill 里写了变量为空时的降级分支。
+
 配套的 skill 在 `skills/coflux/SKILL.md`（随包分发），装给 Claude Code：
 
 ```sh

package/cofluxd.mjs

@@ -12,11 +12,25 @@ import dns from "node:dns/promises";
 import net from "node:net";
 import tls from "node:tls";
 import crypto from "node:crypto";
+import {
+  MAX_RELEASE_ARTIFACT_BYTES,
+  assertReleaseVersion,
+  compareReleaseVersions,
+  createReleasePublicKey,
+  installStagedPair,
+  parseReleaseManifestEntry,
+  verifyReleaseArtifact,
+} from "./release-trust.mjs";
 
 // 默认中心服务（公共 SaaS）；自托管用 --server 覆盖。
 const DEFAULT_SERVER = "wss://api.coflux.dev/daemon";
 
 const REPO = "myWsq/coflux";
+const RELEASE_API_BASE = (process.env.COFLUX_RELEASE_API_BASE || "https://api.github.com").replace(/\/+$/, "");
+const RELEASE_DOWNLOAD_BASE = (
+  process.env.COFLUX_RELEASE_DOWNLOAD_BASE || `https://github.com/${REPO}/releases/download`
+).replace(/\/+$/, "");
+const MAX_RELEASE_METADATA_BYTES = 1024 * 1024;
 const HOME = process.env.COFLUX_HOME || join(homedir(), ".coflux");
 const BIN_DIR = join(HOME, "bin");
 const SETTINGS = join(HOME, "settings.json"); // 用户配置（serverUrl/deviceName/shell）→ daemon 直接读；600 权限防同机其他用户窥探
@@ -28,6 +42,8 @@ const LOCAL_GATEWAY_STORE = join(HOME, "local-gateway.json"); // gateway key/ori
 const FDA_STATUS = join(HOME, "fda-status"); // supervisor 启动时探测落盘（仅 macOS，见 crates/supervisor/src/fda.rs）
 const SUP_BIN = join(BIN_DIR, "coflux-supervisor");
 const WRK_BIN = join(BIN_DIR, "coflux-worker");
+const CLI_RELEASE_FLOOR = join(HOME, "cofluxd.release-floor");
+const WORKER_RELEASE_FLOOR = join(HOME, "worker.release-floor");
 const IS_MAC = platform() === "darwin";
 const IS_LINUX = platform() === "linux";
 const PLIST = join(homedir(), "Library", "LaunchAgents", "com.coflux.daemon.plist");
@@ -121,30 +137,113 @@ function fileSha256(path) {
 
 // macOS：新落盘的二进制带 com.apple.provenance，launchd 顶层 spawn 会被 AMFI 以
 // OS_REASON_CODESIGNING 静默杀死——即使产物是 Developer ID 签名 + 已公证（2026-07-25
-// v0.13.0 实测仍被连杀）。本地 ad-hoc 重签使其成为"本机产物"绕开该检查；签名威胁模型
-// 不受影响（防的是中心被攻破推恶意产物，靠下载后的 sha256+ed25519 验签，与此无关）。
+// v0.13.0 实测仍被连杀）。本地 ad-hoc 重签使其成为"本机产物"绕开该检查。
+// 远端产物必须先完成 release statement 验签，再允许走到这里；绝不能替任意下载内容重签。
 function resignMacBinaries(paths) {
   if (!IS_MAC) return;
   for (const p of paths) {
     const r = run("codesign", ["--force", "-s", "-", p]);
-    if (r.status !== 0) console.warn(`⚠ 本地重签失败: ${p}（daemon 若被系统杀，手动 codesign --force -s - 该文件后 cofluxd restart）`);
+    if (r.status !== 0) {
+      throw new Error(`macOS 本地重签失败: ${p}；保留当前 daemon 二进制`);
+    }
+  }
+}
+
+async function fetchBounded(url, maxBytes, label) {
+  const res = await fetch(url, {
+    redirect: "follow",
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!res.ok) throw new Error(`${label} 下载失败（HTTP ${res.status}）`);
+  const declaredLength = Number(res.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    throw new Error(`${label} 超过大小上限`);
+  }
+  if (!res.body) throw new Error(`${label} 响应没有 body`);
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of res.body) {
+    const bytes = Buffer.from(chunk);
+    total += bytes.byteLength;
+    if (total > maxBytes) {
+      await res.body.cancel().catch(() => {});
+      throw new Error(`${label} 超过大小上限`);
+    }
+    chunks.push(bytes);
+  }
+  return Buffer.concat(chunks, total);
+}
+
+function loadReleasePublicKey() {
+  const publicKeyHex = process.env.COFLUX_WORKER_PUBKEY ||
+    fs.readFileSync(new URL("./release-pubkey.hex", import.meta.url), "utf8");
+  return createReleasePublicKey(publicKeyHex);
+}
+
+function readReleaseFloor(path, label) {
+  let metadata;
+  try { metadata = fs.lstatSync(path); }
+  catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw new Error(`${label} 元数据无法读取，拒绝远端升级`);
+  }
+  if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size <= 0 || metadata.size > 128) {
+    throw new Error(`${label} 不是安全且有界的普通文件，拒绝远端升级`);
   }
+  let value;
+  try { value = fs.readFileSync(path, "utf8").trim(); }
+  catch { throw new Error(`${label} 无法读取，拒绝远端升级`); }
+  try { assertReleaseVersion(value); }
+  catch { throw new Error(`${label} 已损坏，拒绝远端升级`); }
+  return value;
 }
 
-async function download(url, dest) {
-  const res = await fetch(url, { redirect: "follow" });
-  if (!res.ok) die(`下载失败 HTTP ${res.status}: ${url}\n（该版本/平台的 release 资产是否已发布？）`);
-  fs.writeFileSync(dest, Buffer.from(await res.arrayBuffer()), { mode: 0o755 });
+function currentReleaseFloor() {
+  const floors = [
+    readReleaseFloor(CLI_RELEASE_FLOOR, "cofluxd.release-floor"),
+    readReleaseFloor(WORKER_RELEASE_FLOOR, "worker.release-floor"),
+  ].filter(Boolean);
+  return floors.reduce((highest, candidate) => {
+    if (!highest) return candidate;
+    const order = compareReleaseVersions(candidate, highest);
+    if (order === 0 && candidate !== highest) {
+      throw new Error(`本机 release floor precedence 相同但身份冲突：${highest} / ${candidate}`);
+    }
+    return order > 0 ? candidate : highest;
+  }, undefined);
 }
+
+function persistCliReleaseFloor(version) {
+  const temp = join(HOME, `.cofluxd.release-floor.${process.pid}.${crypto.randomBytes(8).toString("hex")}`);
+  let file;
+  try {
+    file = fs.openSync(temp, "wx", 0o600);
+    fs.writeFileSync(file, `${version}\n`);
+    fs.fsyncSync(file);
+    fs.closeSync(file);
+    file = undefined;
+    fs.renameSync(temp, CLI_RELEASE_FLOOR);
+    const homeDir = fs.openSync(HOME, "r");
+    try { fs.fsyncSync(homeDir); }
+    finally { fs.closeSync(homeDir); }
+  } finally {
+    if (file !== undefined) {
+      try { fs.closeSync(file); } catch {}
+    }
+    try { fs.rmSync(temp, { force: true }); } catch {}
+  }
+}
+
 // 取最新 release tag（含 prerelease；GitHub 的 /releases/latest 跳转不含 prerelease，故走 API）。
 async function resolveLatestTag() {
   try {
-    const r = await fetch(`https://api.github.com/repos/${REPO}/releases?per_page=1`, {
-      headers: { "user-agent": "cofluxd", accept: "application/vnd.github+json" },
-    });
-    if (!r.ok) return null;
-    const arr = await r.json();
-    return Array.isArray(arr) && arr[0]?.tag_name ? arr[0].tag_name : null;
+    const body = await fetchBounded(
+      `${RELEASE_API_BASE}/repos/${REPO}/releases?per_page=1`,
+      MAX_RELEASE_METADATA_BYTES,
+      "GitHub release 元数据",
+    );
+    const arr = JSON.parse(body.toString("utf8"));
+    return Array.isArray(arr) && typeof arr[0]?.tag_name === "string" ? arr[0].tag_name : null;
   } catch {
     return null;
   }
@@ -155,13 +254,36 @@ async function resolveLatestTag() {
 async function ensureBinaries({ version, binDir, skipIfPresent }) {
   fs.mkdirSync(BIN_DIR, { recursive: true });
   if (binDir) {
-    for (const b of ["coflux-supervisor", "coflux-worker"]) {
-      const src = join(binDir, b);
-      if (!fs.existsSync(src)) die(`本地产物缺失: ${src}（先 cargo build --release？）`);
-      fs.copyFileSync(src, join(BIN_DIR, b));
-      fs.chmodSync(join(BIN_DIR, b), 0o755);
+    const localArtifacts = ["coflux-supervisor", "coflux-worker"].map((name) => ({
+      name,
+      path: join(binDir, name),
+    }));
+    for (const artifact of localArtifacts) {
+      if (!fs.existsSync(artifact.path)) {
+        die(`本地产物缺失: ${artifact.path}（先 cargo build --release？）`);
+      }
+    }
+    const stageDir = fs.mkdtempSync(join(BIN_DIR, ".coflux-local-install-"));
+    let localFailure;
+    try {
+      const staged = [];
+      for (const artifact of localArtifacts) {
+        const destination = join(BIN_DIR, artifact.name);
+        const source = join(stageDir, artifact.name);
+        fs.copyFileSync(artifact.path, source);
+        fs.chmodSync(source, 0o755);
+        staged.push({ source, destination });
+      }
+      resignMacBinaries(staged.map(({ source }) => source));
+      installStagedPair(staged);
+    } catch (error) {
+      localFailure = error;
+    } finally {
+      fs.rmSync(stageDir, { recursive: true, force: true });
+    }
+    if (localFailure) {
+      die(`本地 daemon 安装失败：${localFailure instanceof Error ? localFailure.message : String(localFailure)}`);
     }
-    resignMacBinaries([SUP_BIN, WRK_BIN]);
     console.log(`✓ 用本地二进制（${binDir}）`);
     return;
   }
@@ -169,21 +291,86 @@ async function ensureBinaries({ version, binDir, skipIfPresent }) {
     console.log(`✓ 二进制已存在（${BIN_DIR}），跳过下载（用 cofluxd update 升级）`);
     return;
   }
-  const t = rustTarget();
-  let base;
+  const target = rustTarget();
+  let releaseVersion;
   if (!version || version === "latest") {
     const tag = await resolveLatestTag();
-    if (tag) console.log(`最新版本: ${tag}`);
-    base = tag ? `https://github.com/${REPO}/releases/download/${tag}` : `https://github.com/${REPO}/releases/latest/download`;
+    if (!tag) die("无法取得最新 release 的精确版本，拒绝无版本身份的下载");
+    releaseVersion = tag;
+    console.log(`最新版本: ${releaseVersion}`);
   } else {
-    base = `https://github.com/${REPO}/releases/download/${version}`;
+    releaseVersion = version;
+  }
+  try {
+    assertReleaseVersion(releaseVersion);
+  } catch (error) {
+    die(error instanceof Error ? error.message : String(error));
+  }
+  let releaseFloor;
+  try {
+    releaseFloor = currentReleaseFloor();
+    const floorOrder = releaseFloor
+      ? compareReleaseVersions(releaseVersion, releaseFloor)
+      : 1;
+    if (floorOrder < 0 || (floorOrder === 0 && releaseVersion !== releaseFloor)) {
+      throw new Error(`远端 release ${releaseVersion} 不高于本机可信身份 ${releaseFloor}，拒绝降级/重放`);
+    }
+  } catch (error) {
+    die(error instanceof Error ? error.message : String(error));
+  }
+
+  const base = `${RELEASE_DOWNLOAD_BASE}/${releaseVersion}`;
+  const stageDir = fs.mkdtempSync(join(BIN_DIR, ".coflux-release-install-"));
+  let failure;
+  try {
+    const manifestBytes = await fetchBounded(
+      `${base}/manifest.json`,
+      MAX_RELEASE_METADATA_BYTES,
+      "release manifest",
+    );
+    let manifest;
+    try {
+      manifest = JSON.parse(manifestBytes.toString("utf8"));
+    } catch {
+      throw new Error("release manifest 不是有效 JSON");
+    }
+    const publicKey = loadReleasePublicKey();
+    const staged = [];
+    for (const component of ["supervisor", "worker"]) {
+      const entry = parseReleaseManifestEntry(manifest, component, releaseVersion, target);
+      const artifactName = `coflux-${component}-${target}`;
+      process.stdout.write(`下载并验签 ${artifactName} … `);
+      const data = await fetchBounded(
+        `${base}/${artifactName}`,
+        Math.min(entry.size, MAX_RELEASE_ARTIFACT_BYTES),
+        artifactName,
+      );
+      verifyReleaseArtifact({ component, version: releaseVersion, entry, data, publicKey });
+      const source = join(stageDir, `coflux-${component}`);
+      fs.writeFileSync(source, data, { mode: 0o755 });
+      fs.chmodSync(source, 0o755);
+      staged.push({
+        source,
+        destination: component === "supervisor" ? SUP_BIN : WRK_BIN,
+      });
+      console.log("✓");
+    }
+    // 两个远端产物均通过同一发布根的验签后，才允许做本地平台变换与替换。
+    resignMacBinaries(staged.map(({ source }) => source));
+    // floor 先于 pair 提交：若其后进程崩溃，最多是旧二进制配更高 floor；重跑同版仍允许，
+    // 但任何旧的合法 release 都不能趁窗口降级。
+    if (!releaseFloor || compareReleaseVersions(releaseVersion, releaseFloor) > 0) {
+      persistCliReleaseFloor(releaseVersion);
+    }
+    installStagedPair(staged);
+  } catch (error) {
+    failure = error;
+  } finally {
+    fs.rmSync(stageDir, { recursive: true, force: true });
   }
-  for (const b of ["coflux-supervisor", "coflux-worker"]) {
-    process.stdout.write(`下载 ${b}-${t} … `);
-    await download(`${base}/${b}-${t}`, join(BIN_DIR, b));
-    console.log("✓");
+  if (failure) {
+    die(`release 安装失败：${failure instanceof Error ? failure.message : String(failure)}`);
   }
-  resignMacBinaries([SUP_BIN, WRK_BIN]);
 }
 
 // 写 settings.json（daemon 直接读）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cofluxd",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "coflux daemon 管理 CLI：装/起/停/升级 Rust daemon（supervisor + worker）",
   "type": "module",
   "bin": {
@@ -8,6 +8,8 @@
   },
   "files": [
     "cofluxd.mjs",
+    "release-pubkey.hex",
+    "release-trust.mjs",
     "README.md",
     "skills"
   ],

package/release-pubkey.hex

@@ -0,0 +1 @@
+d5605555e704b65933a82f57cb648ac96884c237353b0e47f5445f09e745d7a1

package/release-trust.mjs

@@ -0,0 +1,240 @@
+import crypto from "node:crypto";
+import { Buffer } from "node:buffer";
+import fs from "node:fs";
+
+export const WORKER_RELEASE_STATEMENT_DOMAIN = Buffer.from(
+  "coflux-worker-release-v1\0",
+  "utf8",
+);
+export const SUPERVISOR_RELEASE_STATEMENT_DOMAIN = Buffer.from(
+  "coflux-supervisor-release-v1\0",
+  "utf8",
+);
+
+const STRICT_RELEASE_VERSION = /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+const ED25519_SIGNATURE_HEX = /^[0-9a-f]{128}$/i;
+const ED25519_PUBLIC_KEY_HEX = /^[0-9a-f]{64}$/i;
+export const MAX_RELEASE_ARTIFACT_BYTES = 128 * 1024 * 1024;
+
+function parseReleaseVersion(version) {
+  const match = typeof version === "string" ? STRICT_RELEASE_VERSION.exec(version) : null;
+  if (!match) throw new Error(`release version 不是带 v 前缀的严格 SemVer: ${JSON.stringify(version)}`);
+  const prerelease = match[4]
+    ? match[4].split(".").map((identifier) => {
+      if (/^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith("0")) {
+        throw new Error(`release version 的数字 prerelease 标识符含前导 0: ${JSON.stringify(version)}`);
+      }
+      return /^\d+$/.test(identifier)
+        ? { numeric: true, value: BigInt(identifier) }
+        : { numeric: false, value: identifier };
+    })
+    : [];
+  return {
+    raw: version,
+    core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])],
+    prerelease,
+  };
+}
+
+/** 与 Rust semver crate 一致的 release tag 子集：必须带 v，数字标识符禁止前导 0。 */
+export function assertReleaseVersion(version) {
+  parseReleaseVersion(version);
+  return version;
+}
+
+/** SemVer precedence；build metadata 不参与比较。 */
+export function compareReleaseVersions(leftVersion, rightVersion) {
+  const left = parseReleaseVersion(leftVersion);
+  const right = parseReleaseVersion(rightVersion);
+  for (let index = 0; index < 3; index += 1) {
+    if (left.core[index] < right.core[index]) return -1;
+    if (left.core[index] > right.core[index]) return 1;
+  }
+  if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+    if (left.prerelease.length === right.prerelease.length) return 0;
+    return left.prerelease.length === 0 ? 1 : -1;
+  }
+  const common = Math.min(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < common; index += 1) {
+    const a = left.prerelease[index];
+    const b = right.prerelease[index];
+    if (a.numeric && b.numeric) {
+      if (a.value < b.value) return -1;
+      if (a.value > b.value) return 1;
+    } else if (a.numeric !== b.numeric) {
+      return a.numeric ? -1 : 1;
+    } else {
+      if (a.value < b.value) return -1;
+      if (a.value > b.value) return 1;
+    }
+  }
+  return Math.sign(left.prerelease.length - right.prerelease.length);
+}
+
+function lenPrefixed(value) {
+  const bytes = Buffer.from(value, "utf8");
+  const length = Buffer.allocUnsafe(4);
+  length.writeUInt32BE(bytes.length);
+  return [length, bytes];
+}
+
+function artifactReleaseStatement(domain, { version, target, sha256, size }) {
+  assertReleaseVersion(version);
+  if (typeof target !== "string" || !target || Buffer.byteLength(target) > 128) {
+    throw new Error("release target 非法");
+  }
+  if (typeof sha256 !== "string" || !SHA256_HEX.test(sha256)) {
+    throw new Error("release sha256 必须是 32 字节 hex");
+  }
+  if (!Number.isSafeInteger(size) || size <= 0 || size > MAX_RELEASE_ARTIFACT_BYTES) {
+    throw new Error("release size 必须是有效且有界的正整数");
+  }
+  const sizeBytes = Buffer.allocUnsafe(8);
+  sizeBytes.writeBigUInt64BE(BigInt(size));
+  return Buffer.concat([
+    domain,
+    ...lenPrefixed(version),
+    ...lenPrefixed(target),
+    Buffer.from(sha256, "hex"),
+    sizeBytes,
+  ]);
+}
+
+/** worker 热升级沿用的 v1 transcript；不得改变 domain 或字段顺序。 */
+export function workerReleaseStatement(metadata) {
+  return artifactReleaseStatement(WORKER_RELEASE_STATEMENT_DOMAIN, metadata);
+}
+
+/** supervisor 安装专用 transcript；独立 domain 防止合法 worker 签名被横向移植。 */
+export function supervisorReleaseStatement(metadata) {
+  return artifactReleaseStatement(SUPERVISOR_RELEASE_STATEMENT_DOMAIN, metadata);
+}
+
+export function createReleasePublicKey(publicKeyHex) {
+  const normalized = typeof publicKeyHex === "string" ? publicKeyHex.trim() : "";
+  if (!ED25519_PUBLIC_KEY_HEX.test(normalized)) {
+    throw new Error("发布公钥必须是 32 字节 hex");
+  }
+  return crypto.createPublicKey({
+    format: "jwk",
+    key: {
+      kty: "OKP",
+      crv: "Ed25519",
+      x: Buffer.from(normalized, "hex").toString("base64url"),
+    },
+  });
+}
+
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * 从 schema 2 manifest 取指定 component/target。额外顶层字段允许滚动扩展；
+ * 但参与信任裁决的 version/target/size/hash/signature 全部严格校验。
+ */
+export function parseReleaseManifestEntry(manifest, component, version, target) {
+  assertReleaseVersion(version);
+  if (component !== "worker" && component !== "supervisor") {
+    throw new Error(`未知 release component: ${JSON.stringify(component)}`);
+  }
+  if (!isRecord(manifest) || manifest.schemaVersion !== 2 || manifest.version !== version) {
+    throw new Error("release manifest schema/version 与请求不一致");
+  }
+  const entries = manifest[component];
+  const entry = isRecord(entries) ? entries[target] : undefined;
+  if (!isRecord(entry) || entry.target !== target) {
+    throw new Error(`release manifest 缺少匹配的 ${component}/${target}`);
+  }
+  if (
+    typeof entry.sha256 !== "string" ||
+    !SHA256_HEX.test(entry.sha256) ||
+    !Number.isSafeInteger(entry.size) ||
+    entry.size <= 0 ||
+    entry.size > MAX_RELEASE_ARTIFACT_BYTES ||
+    typeof entry.releaseSignature !== "string" ||
+    !ED25519_SIGNATURE_HEX.test(entry.releaseSignature)
+  ) {
+    throw new Error(`release manifest 的 ${component}/${target} 元数据非法`);
+  }
+  if (
+    component === "worker" &&
+    (typeof entry.signature !== "string" || !ED25519_SIGNATURE_HEX.test(entry.signature))
+  ) {
+    throw new Error(`release manifest 的 worker/${target} 缺少 legacy 签名`);
+  }
+  return {
+    target,
+    sha256: entry.sha256.toLowerCase(),
+    size: entry.size,
+    signature: component === "worker" ? entry.signature.toLowerCase() : undefined,
+    releaseSignature: entry.releaseSignature.toLowerCase(),
+  };
+}
+
+/** 校验实际 bytes 与 manifest 元数据、raw worker 签名及 component-separated release 签名。 */
+export function verifyReleaseArtifact({ component, version, entry, data, publicKey }) {
+  if (!Buffer.isBuffer(data)) throw new Error("release 产物必须是 Buffer");
+  if (data.byteLength !== entry.size) {
+    throw new Error(`${component} 产物大小不匹配：期望 ${entry.size}，实际 ${data.byteLength}`);
+  }
+  const sha256 = crypto.createHash("sha256").update(data).digest("hex");
+  if (sha256 !== entry.sha256) {
+    throw new Error(`${component} 产物 sha256 不匹配`);
+  }
+  if (
+    component === "worker" &&
+    !crypto.verify(null, data, publicKey, Buffer.from(entry.signature, "hex"))
+  ) {
+    throw new Error("worker 产物 legacy Ed25519 签名无效");
+  }
+  const metadata = { version, target: entry.target, sha256, size: data.byteLength };
+  const statement = component === "worker"
+    ? workerReleaseStatement(metadata)
+    : supervisorReleaseStatement(metadata);
+  if (!crypto.verify(null, statement, publicKey, Buffer.from(entry.releaseSignature, "hex"))) {
+    throw new Error(`${component} 产物 release Ed25519 签名无效`);
+  }
+}
+
+/**
+ * 两个已验证/本地显式信任的暂存文件一起进入替换阶段；任一 rename 失败都会恢复旧 pair。
+ * 单文件 rename 是原子的，pair 级失败用同文件系统内备份回滚，绝不把“只更新一半”当成功。
+ */
+export function installStagedPair(staged) {
+  if (
+    !Array.isArray(staged) ||
+    staged.length !== 2 ||
+    staged.some(({ source, destination }) =>
+      typeof source !== "string" || !source || typeof destination !== "string" || !destination)
+  ) {
+    throw new Error("daemon 安装必须提供两个合法的暂存文件");
+  }
+  const installed = [];
+  const backups = [];
+  try {
+    for (const { source, destination } of staged) {
+      const backup = `${source}.previous`;
+      if (fs.existsSync(destination)) {
+        fs.renameSync(destination, backup);
+        backups.push({ backup, destination });
+      }
+      fs.renameSync(source, destination);
+      installed.push(destination);
+    }
+  } catch (error) {
+    for (const destination of installed.reverse()) {
+      try { fs.rmSync(destination, { force: true }); } catch {}
+    }
+    const restoreFailures = [];
+    for (const { backup, destination } of backups.reverse()) {
+      try { fs.renameSync(backup, destination); }
+      catch (restoreError) { restoreFailures.push(restoreError); }
+    }
+    if (restoreFailures.length > 0) {
+      throw new AggregateError([error, ...restoreFailures], "daemon 二进制替换失败且旧版本恢复不完整");
+    }
+    throw error;
+  }
+}

package/skills/coflux/SKILL.md

@@ -1,17 +1,49 @@
 ---
 name: coflux
-description: 当你运行在 coflux 终端里时，把长任务、并行工作和求助外化成用户在 coflux web/手机上看得见、能随时接管的真实终端。适用于跑测试/构建/dev server 等耗时命令、需要用户接管或决策、想给用户一个可点开的预览 URL 的场景。
+description: 当你运行在 coflux 终端里时，把长任务、并行工作和求助外化成用户在 coflux web/手机上看得见、能随时接管的真实终端；读 COFLUX_* 环境变量知道自己在哪台设备/项目/工作区/终端，本工作区内用本地 cofluxd 命令，开子工作区或跨工作区/跨设备操作用中心的 coflux MCP。适用于跑测试/构建/dev server 等耗时命令、需要用户接管或决策、想给用户一个可点开的预览 URL、要在隔离的子工作区并行干活的场景。
 ---
 
 # 在 coflux 里工作
 
 你可能正跑在 coflux 的一个终端里。coflux 让用户在浏览器和手机上盯着各台机器上的
-agent 干活，随时接管。这套命令让你把自己的工作**变成用户看得见的东西**。
+agent 干活，随时接管。这个 skill 让你把自己的工作**变成用户看得见的东西**，并在需要时
+操作账号下的其它工作区和设备。
 
-先判断自己在不在 coflux 里：任意一条命令返回「不在 coflux 终端里」就说明不在，
-这时忘掉这个 skill，照常用你自己的工具。
+有两条轨道，分工固定：
 
-## 什么时候用
+| 轨道 | 凭证 | 能触达的范围 | 用在 |
+|---|---|---|---|
+| 本地命令 `cofluxd terminal/progress/notify/ports` | 零凭证（daemon 按你的进程树认身份） | 只有**你所在的工作区** | 本工作区内开终端、读、等、输入、播报、叫人、拿预览 URL——最省事的路径 |
+| 中心 MCP `coflux`（14 个 tools） | 用户在宿主里做一次 OAuth 授权 | **整个账号**：所有设备、项目、工作区、终端 | 开子工作区（git worktree）、跨工作区/跨设备读写、从 coflux 之外接入 |
+
+## 先判断自己在哪
+
+先看环境变量：
+
+```sh
+env | grep '^COFLUX_'
+```
+
+- **`COFLUX_WORKSPACE_ID` 非空** → 你在 coflux 终端里，且 daemon 已是新版。下面的变量就是
+  你的坐标，MCP tools 要的 id 直接从这里拿，不用去 `list_*` 里猜：
+
+  | 变量 | 含义 |
+  |---|---|
+  | `COFLUX_DEVICE_ID` | 你所在机器的设备 id（`list_devices` 的 id） |
+  | `COFLUX_PROJECT_ID` | 所属项目 id；无仓库的目录工作区为空串 |
+  | `COFLUX_WORKSPACE_ID` | 所属工作区 id（`list_workspaces` 的 id） |
+  | `COFLUX_TASK_ID` | 你这个终端的 id（`list_terminals` / `read_terminal` 用的 terminalId） |
+  | `COFLUX_SESSION_ID` | 你这个 PTY 会话 id |
+  | `COFLUX_MCP_URL` | 中心 MCP 地址，用户配 MCP 时就用它 |
+
+- **变量为空或不存在** → 跑一条 `cofluxd terminal list`：
+  - 返回「不在 coflux 终端里」→ 你不在 coflux 里，忘掉这个 skill，照常用你自己的工具
+    （除非用户已经在宿主里配了 coflux MCP，那时 MCP tools 照用，只是没有「我在哪」的坐标）。
+  - 能列出终端 → 你在 coflux 里，但 daemon 还没升级到注入环境变量的版本：本地命令全部可用，
+    只是你不知道自己的 id；要用 MCP 就先 `list_devices` / `list_workspaces` 按路径对一下
+    `pwd`，并顺手告诉用户 `cofluxd update && cofluxd restart` 之后就有环境变量了。
+
+## 什么时候用本地命令
 
 **用 `cofluxd terminal new` 而不是自己后台起进程**——只要这条命令满足任一条：
 
@@ -26,7 +58,7 @@ agent 干活，随时接管。这套命令让你把自己的工作**变成用户
 **不要用**在一次性的快命令上（`ls`、`grep`、`git status`、读文件）——你自己的工具更快，
 给用户开一堆一秒就结束的终端只是噪音。
 
-## 命令
+## 本地命令
 
 ### 开终端跑命令
 
@@ -44,6 +76,8 @@ cofluxd terminal new --title "跑单测" --cmd "pnpm -C tests test"
 关掉颜色和进度条。极少数程序在非 tty 下行为不同（比如不输出进度、切成 CI 模式），如果你
 依赖那种行为，自己在 Bash 里跑。
 
+新开的终端里同样有 `COFLUX_*` 变量（指向它自己的 task/session id，工作区与你相同）。
+
 ### 看跑到哪了
 
 ```sh
@@ -117,12 +151,72 @@ cofluxd ports
 列出本工作区所有监听端口和对应的公网预览 URL。起了 dev server 之后用它拿 URL 直接
 告诉用户，他点开就能看，不用自己去翻。
 
+## 中心 MCP：跨出本工作区
+
+本地命令只看得见你所在的工作区。要做下面这些事，用宿主里名为 `coflux` 的 MCP server：
+
+- **开一个隔离的子工作区并行干活**：`create_workspace`（项目 id 用 `$COFLUX_PROJECT_ID`）
+  在设备上真的 `git worktree add`，然后 `create_terminal` 在那里跑命令。
+- **看/操作别的工作区、别的设备上的终端**：`list_*` → `read_terminal` / `send_terminal_input`。
+- **不在 coflux 终端里**（比如用户在自己电脑上开的 Claude Code）时接入账号下的一切。
+
+### 没配 MCP 时
+
+先 `claude mcp list`（Codex：`codex mcp list`）看有没有 `coflux`。没有就告诉用户一行接入，
+地址用 `$COFLUX_MCP_URL`（它就是中心公网地址 + `/mcp`）：
+
+```sh
+claude mcp add --transport http coflux "$COFLUX_MCP_URL"     # Claude Code
+codex mcp add coflux --url "$COFLUX_MCP_URL"                 # Codex
+```
+
+之后宿主会引导用户在浏览器完成一次 OAuth 授权（Claude Code 里是 `/mcp`）。授权是用户的事，
+你只需要把地址和命令给他；没配好之前本工作区内的活照样用本地命令干。
+
+### 14 个 tools
+
+id 优先从 `COFLUX_*` 环境变量拿；跨出本工作区的 id 用 `list_*` 查。
+
+| tool | 用途 |
+|---|---|
+| `list_devices` | 账号下的设备（跑着 daemon 的机器）：id、名称、在线、版本 |
+| `list_projects` | 导入的项目（git 仓库）：id、所在设备、仓库路径、默认分支 |
+| `list_workspaces` | 工作区（主工作区 = 仓库本身，其余是 worktree；目录工作区 projectId 为 null），可按 projectId 筛 |
+| `list_terminals` | 终端：id、工作区、标题、状态 idle/running/exited、退出码，可按 workspaceId 筛 |
+| `read_terminal` | 读终端纯文本（去 ANSI，默认尾 200 行）：source=log 是命令终端的完整日志（退出后仍可读），snapshot 是当前画面，checkpoint 是设备离线时中心的最近快照 |
+| `list_ports` | 终端里检测到的监听端口 + 可直接打开的预览 URL |
+| `create_workspace` | 在项目下新建 git worktree 工作区（可新建分支），设备真在磁盘上建目录 |
+| `rename_workspace` | 改工作区名（纯展示） |
+| `remove_workspace` | 删 worktree 工作区：先关其下所有终端再 `git worktree remove --force`（未提交改动会丢）；主工作区不可删 |
+| `create_terminal` | 在某工作区开真实终端跑一条命令（用户可接管、侧栏可见），跑完带退出码；输出落日志供 `read_terminal` |
+| `send_terminal_input` | 往运行中的终端写文本（默认追加回车） |
+| `wait_terminal` | 有界等待终端退出并拿退出码（默认 30 秒、上限 50 秒） |
+| `stop_terminal` | 结束终端会话（等价 web 上的停止） |
+| `remove_terminal` | 删终端记录；运行中的必须先 `stop_terminal` |
+
+### 用 MCP 的三条纪律
+
+1. **人类优先**：`send_terminal_input` 在用户正在接管那个终端时会被拒，错误里写明
+   「用户正在接管」——把交互留给用户，不要重试；要沟通用本工作区的 `cofluxd notify`。
+   `send` 之前先 `read_terminal` 看清它在等什么；回执超时先 `read` 再决定要不要重发。
+2. **有界等待**：`wait_terminal` 最多等 50 秒，到期返回 `timedOut=true` 不是错误——需要更久
+   就再调一次，**别自己写轮询循环去 `read_terminal`**。`create_workspace` / `create_terminal`
+   最多等 30 秒启动回执，到期返回「已提交」并附 id，稍后用 `list_*` 查。
+3. **「需要升级」就停**：写 tools 在目标设备的 daemon 太旧时立即返回「该设备的 daemon 需要
+   升级」——这是能力门禁，不是暂时故障。转告用户在那台机器上 `cofluxd update && cofluxd restart`，
+   别重试也别换 tool 绕。
+
+本地命令的纪律（先 read 再 send、被拒即停、`progress` 与 `notify` 分界、用 `wait` 别轮询）
+在 MCP 里同样成立。
+
 ## 边界
 
 - 你能开、读、等、输入，但**输入是人类优先的受限写权**：用户正在接管的终端你写不进去
   （会被明确拒绝），用户随时接管也会把你顶掉。别和人抢终端。
-- 能看到的只有**你自己所在的工作区**，别的工作区和别的机器都看不见也碰不到。
+- 本地命令只看得见**你自己所在的工作区**；别的工作区和别的机器要经 MCP，且限于同一账号。
 - 一个工作区同时活着的终端有上限（默认 8，含用户自己开的）。撞上限先 `list` 看看，
   多半是有跑完没收的；真是用户占满了，就 `notify` 告诉他，别硬试。
-- 这些命令都要 daemon 连着中心才能用——毕竟「让用户看见」就是它们的全部意义。
+- 这些命令与 tools 都要 daemon 连着中心才能用——毕竟「让用户看见」就是它们的全部意义。
   连不上时会明确报错，不会默默降级。
+- `COFLUX_*` 变量只在 coflux 开出来的 PTY 里有；你自己 `export` 或改它们没有任何效果，
+  中心只认它自己下发的 id。