cofluxd 2.14.0 → 2.16.0

package/output.mjs

@@ -0,0 +1,93 @@
+// The one place cofluxd and coflux decide how a message looks: symbols, colour, the error shape.
+//
+// - `✓` success and plain lines go to stdout; `!` warnings and `✗ Error:` go to stderr.
+// - Every error is one line saying what happened plus one indented line saying what to do next.
+// - Colour only when the stream is a TTY and NO_COLOR is unset (https://no-color.org) and TERM is
+//   not "dumb". Agents call coflux without a TTY and always get plain text.
+//
+// Hand-rolled SGR on purpose: `util.styleText` does not exist before Node 20.12 and colours
+// unconditionally before 22.13, and package.json promises Node 20.
+import process from "node:process";
+
+const SGR = { green: [32, 39], yellow: [33, 39], red: [31, 39], bold: [1, 22], dim: [2, 22] };
+
+/** Whether `stream` may carry colour. */
+export function colorEnabled(stream) {
+  if (!stream?.isTTY) return false;
+  const noColor = process.env.NO_COLOR;
+  if (noColor !== undefined && noColor !== "") return false;
+  return process.env.TERM !== "dumb";
+}
+
+function paint(stream, style, text) {
+  if (!colorEnabled(stream)) return text;
+  const [open, close] = SGR[style];
+  return `\u001b[${open}m${text}\u001b[${close}m`;
+}
+
+/** Bold for emphasis on stdout (a URL, a command to run). */
+export const bold = (text, stream = process.stdout) => paint(stream, "bold", text);
+export const dim = (text, stream = process.stdout) => paint(stream, "dim", text);
+
+/** A plain line on stdout. */
+export function info(message = "") {
+  process.stdout.write(`${message}\n`);
+}
+
+/** `✓ message` on stdout. */
+export function success(message) {
+  process.stdout.write(`${paint(process.stdout, "green", "✓")} ${message}\n`);
+}
+
+/** `! message` on stderr, with an optional indented next step. */
+export function warn(message, next) {
+  let text = `${paint(process.stderr, "yellow", "!")} ${message}\n`;
+  if (next) text += next.split("\n").map((line) => `  ${line}\n`).join("");
+  process.stderr.write(text);
+}
+
+/** `✗ Error: what` plus an indented next step, on stderr. */
+export function error(what, next) {
+  let text = `${paint(process.stderr, "red", "✗ Error:")} ${what}\n`;
+  if (next) text += next.split("\n").map((line) => `  ${line}\n`).join("");
+  process.stderr.write(text);
+}
+
+/** Print an error and exit. The write completes before the exit, even into a pipe. */
+export function fail(what, next, code = 1) {
+  error(what, next);
+  // A message this short is written in full before process.exit: libuv tries the write
+  // synchronously first and only queues what the pipe cannot take at once.
+  process.exit(code);
+}
+
+/** `Doing X... ` now, then `done` (or a failure word) when the step ends. */
+export function step(label) {
+  process.stdout.write(`${label}... `);
+  return {
+    done(word = "done") { process.stdout.write(`${word}\n`); },
+    failed(word = "failed") { process.stdout.write(`${word}\n`); },
+  };
+}
+
+/** Aligned key/value rows on stdout; rows whose value is undefined or null are skipped. */
+export function table(rows) {
+  const shown = rows.filter(([, value]) => value !== undefined && value !== null);
+  const width = Math.max(0, ...shown.map(([key]) => key.length));
+  for (const [key, value] of shown) {
+    const lines = String(value).split("\n");
+    process.stdout.write(`${key.padEnd(width)}  ${lines[0]}\n`);
+    for (const line of lines.slice(1)) process.stdout.write(`${" ".repeat(width)}  ${line}\n`);
+  }
+}
+
+/** A short human duration: `45s`, `12m`, `3h 12m`, `2d 4h`. */
+export function duration(ms) {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ${minutes % 60}m`;
+  return `${Math.floor(hours / 24)}d ${hours % 24}h`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cofluxd",
-  "version": "2.14.0",
-  "description": "Coflux 无界面宿主（cofluxd）与统一操作工具（coflux）",
+  "version": "2.16.0",
+  "description": "Run a headless Coflux device (cofluxd) and work with Coflux terminals, workspaces and your account (coflux)",
   "type": "module",
   "bin": {
     "cofluxd": "cofluxd.mjs",
@@ -11,6 +11,7 @@
     "cofluxd.mjs",
     "coflux.mjs",
     "account-client.mjs",
+    "output.mjs",
     "release-pubkey.hex",
     "release-trust.mjs",
     "service-unit.mjs",

package/release-trust.mjs

@@ -14,6 +14,18 @@ export const SUPERVISOR_RELEASE_STATEMENT_DOMAIN = Buffer.from(
 
 export const CLI_RELEASE_STATEMENT_DOMAIN = Buffer.from("coflux-cli-release-v1\0", "utf8");
 
+/**
+ * The runtime and the launcher (plan 20261002-runtime-launcher-merge) each have their own domain,
+ * distinct from `coflux-worker-release-v1` / `coflux-supervisor-release-v1`: a runtime statement
+ * never verifies against the worker transcript built from identical metadata, so no pre-plan
+ * supervisor can accept a runtime artifact as a worker. Runtime artifacts carry no legacy raw
+ * signature at all.
+ */
+export const RUNTIME_RELEASE_STATEMENT_DOMAIN = Buffer.from("coflux-runtime-release-v1\0", "utf8");
+export const LAUNCHER_RELEASE_STATEMENT_DOMAIN = Buffer.from("coflux-launcher-release-v1\0", "utf8");
+export function runtimeReleaseStatement(metadata) { return artifactReleaseStatement(RUNTIME_RELEASE_STATEMENT_DOMAIN, metadata); }
+export function launcherReleaseStatement(metadata) { return artifactReleaseStatement(LAUNCHER_RELEASE_STATEMENT_DOMAIN, metadata); }
+
 export const TRANSPORT_RELEASE_STATEMENT_DOMAIN = Buffer.from("coflux-transport-release-v1\0", "utf8");
 export function transportReleaseStatement(metadata) { return artifactReleaseStatement(TRANSPORT_RELEASE_STATEMENT_DOMAIN, metadata); }
 
@@ -21,15 +33,20 @@ export function transportReleaseStatement(metadata) { return artifactReleaseStat
 export const PTYD_RELEASE_STATEMENT_DOMAIN = Buffer.from("coflux-ptyd-release-v1\0", "utf8");
 export function ptydReleaseStatement(metadata) { return artifactReleaseStatement(PTYD_RELEASE_STATEMENT_DOMAIN, metadata); }
 
-const RELEASE_COMPONENTS = ["worker", "supervisor", "cli", "transport", "ptyd"];
+/** Components of a schema 3 manifest. `worker` / `supervisor` are schema 2 only. */
+export const RELEASE_COMPONENTS = ["runtime", "launcher", "cli", "transport", "ptyd"];
+export const RELEASE_MANIFEST_SCHEMA_VERSION = 3;
 
 function releaseStatementFor(component, metadata) {
   switch (component) {
+    case "runtime": return runtimeReleaseStatement(metadata);
+    case "launcher": return launcherReleaseStatement(metadata);
     case "worker": return workerReleaseStatement(metadata);
+    case "supervisor": return supervisorReleaseStatement(metadata);
     case "cli": return cliReleaseStatement(metadata);
     case "transport": return transportReleaseStatement(metadata);
     case "ptyd": return ptydReleaseStatement(metadata);
-    default: return supervisorReleaseStatement(metadata);
+    default: throw new Error(`Unknown release component: ${JSON.stringify(component)}`);
   }
 }
 
@@ -41,11 +58,11 @@ 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)}`);
+  if (!match) throw new Error(`Release version must be strict SemVer with a v prefix: ${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)}`);
+        throw new Error(`Release version has a numeric prerelease identifier with a leading zero: ${JSON.stringify(version)}`);
       }
       return /^\d+$/.test(identifier)
         ? { numeric: true, value: BigInt(identifier) }
@@ -104,13 +121,13 @@ function lenPrefixed(value) {
 function artifactReleaseStatement(domain, { version, target, sha256, size }) {
   assertReleaseVersion(version);
   if (typeof target !== "string" || !target || Buffer.byteLength(target) > 128) {
-    throw new Error("release target 非法");
+    throw new Error("Release target is invalid");
   }
   if (typeof sha256 !== "string" || !SHA256_HEX.test(sha256)) {
-    throw new Error("release sha256 必须是 32 字节 hex");
+    throw new Error("Release sha256 must be 32 bytes of hex");
   }
   if (!Number.isSafeInteger(size) || size <= 0 || size > MAX_RELEASE_ARTIFACT_BYTES) {
-    throw new Error("release size 必须是有效且有界的正整数");
+    throw new Error("Release size must be a positive integer within bounds");
   }
   const sizeBytes = Buffer.allocUnsafe(8);
   sizeBytes.writeBigUInt64BE(BigInt(size));
@@ -140,7 +157,7 @@ export function cliReleaseStatement(metadata) {
 export function createReleasePublicKey(publicKeyHex) {
   const normalized = typeof publicKeyHex === "string" ? publicKeyHex.trim() : "";
   if (!ED25519_PUBLIC_KEY_HEX.test(normalized)) {
-    throw new Error("发布公钥必须是 32 字节 hex");
+    throw new Error("The release public key must be 32 bytes of hex");
   }
   return crypto.createPublicKey({
     format: "jwk",
@@ -157,21 +174,23 @@ function isRecord(value) {
 }
 
 /**
- * 从 schema 2 manifest 取指定 component/target。额外顶层字段允许滚动扩展；
+ * 从 schema 3 manifest 取指定 component/target。额外顶层字段允许滚动扩展；
  * 但参与信任裁决的 version/target/size/hash/signature 全部严格校验。
+ * A schema 2 manifest (worker/supervisor) is refused outright: this cofluxd installs a launcher
+ * and a runtime, and a `worker` lookup in a schema 3 manifest throws.
  */
 export function parseReleaseManifestEntry(manifest, component, version, target) {
   assertReleaseVersion(version);
   if (!RELEASE_COMPONENTS.includes(component)) {
-    throw new Error(`未知 release component: ${JSON.stringify(component)}`);
+    throw new Error(`Unknown release component: ${JSON.stringify(component)}`);
   }
-  if (!isRecord(manifest) || manifest.schemaVersion !== 2 || manifest.version !== version) {
-    throw new Error("release manifest schema/version 与请求不一致");
+  if (!isRecord(manifest) || manifest.schemaVersion !== RELEASE_MANIFEST_SCHEMA_VERSION || manifest.version !== version) {
+    throw new Error("Release manifest schema/version does not match the request");
   }
   const entries = manifest[component];
   const entry = isRecord(entries) ? entries[target] : undefined;
   if (!isRecord(entry) || entry.target !== target) {
-    throw new Error(`release manifest 缺少匹配的 ${component}/${target}`);
+    throw new Error(`Release manifest has no matching ${component}/${target}`);
   }
   if (
     typeof entry.sha256 !== "string" ||
@@ -182,43 +201,32 @@ export function parseReleaseManifestEntry(manifest, component, version, target)
     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 签名`);
+    throw new Error(`Release manifest metadata is invalid for ${component}/${target}`);
   }
+  // No component of schema 3 carries a legacy raw-binary signature (the worker's was the back
+  // door old supervisors still check); a stray `signature` field is ignored, never trusted.
   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 签名。 */
+/** 校验实际 bytes 与 manifest 元数据及 component-separated release 签名。 */
 export function verifyReleaseArtifact({ component, version, entry, data, publicKey }) {
-  if (!Buffer.isBuffer(data)) throw new Error("release 产物必须是 Buffer");
+  if (!Buffer.isBuffer(data)) throw new Error("Release artifact must be a Buffer");
   if (data.byteLength !== entry.size) {
-    throw new Error(`${component} 产物大小不匹配：期望 ${entry.size}，实际 ${data.byteLength}`);
+    throw new Error(`${component} artifact size does not match: expected ${entry.size}, got ${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 签名无效");
+    throw new Error(`${component} artifact sha256 does not match`);
   }
   const metadata = { version, target: entry.target, sha256, size: data.byteLength };
   const statement = releaseStatementFor(component, metadata);
   if (!crypto.verify(null, statement, publicKey, Buffer.from(entry.releaseSignature, "hex"))) {
-    throw new Error(`${component} 产物 release Ed25519 签名无效`);
+    throw new Error(`${component} artifact release Ed25519 signature is invalid`);
   }
 }
 
@@ -257,16 +265,16 @@ export function installStagedPair(staged) {
       catch (restoreError) { restoreFailures.push(restoreError); }
     }
     if (restoreFailures.length > 0) {
-      throw new AggregateError([error, ...restoreFailures], "daemon 二进制替换失败且旧版本恢复不完整");
+      throw new AggregateError([error, ...restoreFailures], "Replacing the binaries failed and the previous version could not be fully restored");
     }
     throw error;
   }
 }
 
-/** Publish a complete native runtime before changing any executable entry point.
- * A worker reached through a bin symlink resolves current_exe into its immutable
+/** Publish a complete native release before changing any executable entry point.
+ * A runtime reached through a bin symlink resolves current_exe into its immutable
  * release directory, so interruption between entry-point updates cannot pair
- * that worker with a helper from another release. */
+ * that runtime with a helper from another release. */
 export function installNativeRelease(staged) {
   if (!staged.some(({ destination }) => path.basename(destination) === "coflux-transport")) return installStagedPair(staged);
   const binDir = path.dirname(staged[0].destination);

package/service-unit.mjs

@@ -7,8 +7,8 @@
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
-/** The two variables the worker reads; kept identical to `packages/executor/src/env.ts` and
- * `crates/worker/src/executor_host.rs`. */
+/** The two variables the runtime reads; kept identical to `packages/executor/src/env.ts` and
+ * `crates/runtime/src/executor_host.rs`. */
 export const EXECUTOR_NODE_ENV = "COFLUX_EXECUTOR_NODE";
 export const EXECUTOR_ENTRY_ENV = "COFLUX_EXECUTOR_ENTRY";
 
@@ -52,7 +52,7 @@ function oneLine(value) {
   return !/[\n\r]/.test(String(value));
 }
 
-export function plistXml({ supervisorBin, home, logFile, executor }) {
+export function plistXml({ launcherBin, home, logFile, executor }) {
   const variables = [["COFLUX_HOME", home]];
   if (executor) {
     variables.push([EXECUTOR_NODE_ENV, executor.node], [EXECUTOR_ENTRY_ENV, executor.entry]);
@@ -66,7 +66,7 @@ export function plistXml({ supervisorBin, home, logFile, executor }) {
 <dict>
   <key>Label</key><string>com.coflux.daemon</string>
   <key>ProgramArguments</key>
-  <array><string>${xml(supervisorBin)}</string></array>
+  <array><string>${xml(launcherBin)}</string></array>
   <key>EnvironmentVariables</key>
   <dict>
 ${entries}
@@ -81,9 +81,9 @@ ${entries}
 }
 
 /**
- * ptyd (plan 20260918-ptyd-terminal-custody) runs under its own label: the supervisor's SIGTERM
- * leaves sessions in ptyd, so `launchctl unload/load com.coflux.daemon` touches only the supervisor,
- * and KeepAlive brings ptyd back on its own if it crashes.
+ * ptyd (plan 20260918-ptyd-terminal-custody) runs under its own label: the launcher's SIGTERM
+ * leaves sessions in ptyd, so `launchctl unload/load com.coflux.daemon` touches only the launcher
+ * and its runtime, and KeepAlive brings ptyd back on its own if it crashes.
  */
 export function ptydPlistXml({ ptydBin, home, logFile }) {
   return `<?xml version="1.0" encoding="UTF-8"?>
@@ -107,9 +107,9 @@ export function ptydPlistXml({ ptydBin, home, logFile }) {
 }
 
 /**
- * systemd: ptyd has its own unit and the supervisor's unit Requires/After it. `systemctl restart
- * coflux-daemon` restarts only the supervisor's cgroup; ptyd's is not part of it, so terminals are
- * untouched. Stopping ptyd (down) also stops the supervisor (Requires).
+ * systemd: ptyd has its own unit and the launcher's unit Requires/After it. `systemctl restart
+ * coflux-daemon` restarts only the launcher's cgroup (runtime included); ptyd's is not part of it,
+ * so terminals are untouched. Stopping ptyd (down) also stops the launcher (Requires).
  */
 export function ptydSystemdUnit({ ptydBin, home }) {
   const environment = oneLine(home) ? `Environment=COFLUX_HOME=${home}\n` : "";
@@ -127,7 +127,7 @@ WantedBy=default.target
 `;
 }
 
-export function systemdUnit({ supervisorBin, home, executor }) {
+export function systemdUnit({ launcherBin, home, executor }) {
   const variables = [["COFLUX_HOME", home]];
   if (executor) {
     variables.push([EXECUTOR_NODE_ENV, executor.node], [EXECUTOR_ENTRY_ENV, executor.entry]);
@@ -137,14 +137,14 @@ export function systemdUnit({ supervisorBin, home, executor }) {
     .map(([key, value]) => `Environment=${key}=${value}`)
     .join("\n");
   return `[Unit]
-Description=coflux daemon (supervisor)
+Description=coflux daemon (launcher + runtime)
 After=network-online.target coflux-ptyd.service
 Wants=network-online.target
 Requires=coflux-ptyd.service
 
 [Service]
 ${environment}
-ExecStart=${supervisorBin}
+ExecStart=${launcherBin}
 Restart=always
 RestartSec=2
 
@@ -152,3 +152,42 @@ RestartSec=2
 WantedBy=default.target
 `;
 }
+
+/**
+ * Operator and test overrides the self-managed service keeps from the environment of
+ * `cofluxd up` / `cofluxd run`: the release public key (tests and self-keyed releases), the
+ * runtime's probation window, and its connection timing knobs. Nothing a Coflux terminal sets.
+ */
+export const WATCHER_ENV_ALLOWLIST = [
+  "COFLUX_WORKER_PUBKEY",
+  "COFLUX_RUNTIME_PROBATION_MS",
+  "COFLUX_CONNECT_TIMEOUT_MS",
+  "COFLUX_IDLE_PING_MS",
+  "COFLUX_IDLE_GRACE_MS",
+];
+
+/**
+ * The environment of the self-managed service (`coflux-launcher watch`): the same `COFLUX_*`
+ * variables the launchd / systemd units carry, and only those.
+ *
+ * Not `{ ...process.env, COFLUX_HOME }`: `cofluxd up` is often run from inside a Coflux terminal,
+ * whose environment is a copy of the running service's own — `COFLUX_LAUNCHER_SOCK`,
+ * `COFLUX_LAUNCHER_NONCE`, `COFLUX_TRANSPORT_*`, `COFLUX_LOCAL_GATEWAY_PORT`, `COFLUX_SESSION_ID` and,
+ * under the desktop app, `COFLUX_RUNTIME_CMD`. The launcher and runtime read those and would bind
+ * to another service's sockets. Every other `COFLUX_*` variable is dropped except the allowlist;
+ * everything else (PATH, HOME, locale) passes through.
+ */
+export function watcherEnv(base, { home, executor }) {
+  const env = {};
+  for (const [key, value] of Object.entries(base)) {
+    if (value === undefined) continue;
+    if (key.startsWith("COFLUX_") && !WATCHER_ENV_ALLOWLIST.includes(key)) continue;
+    env[key] = value;
+  }
+  env.COFLUX_HOME = home;
+  if (executor) {
+    env[EXECUTOR_NODE_ENV] = executor.node;
+    env[EXECUTOR_ENTRY_ENV] = executor.entry;
+  }
+  return env;
+}

package/skills/coflux/SKILL.md

@@ -276,7 +276,7 @@ command line is capped at 64 KB. Always write `--cmd=<value>` and `--title=<valu
 never separated by a space: a value that starts with `-` is otherwise taken for another option.
 
 `new` prints the terminal id on its first line whatever happens next; when the command could not
-be typed it says so on the following line (see "Errors").
+be typed it says so in an error on stderr (see "Errors").
 
 The new terminal has the same `COFLUX_*` variables (pointing at its own task/session ids, same
 workspace as you).
@@ -537,7 +537,9 @@ this machine, so they are there whether or not a desktop is open.
 
 ### Errors from local commands
 
-Errors are one readable sentence; do what they say: "not inside a coflux terminal" = you are not
+Errors go to stderr as `✗ Error: <what happened>` followed by an indented line saying what to do
+next; the sentences below come from the daemon and appear after `Error:`. Do what they say: "not
+inside a coflux terminal" = you are not
 in a coflux session; "terminal is not in this workspace or does not exist" = check the id with
 `list`, and if you moved into another workspace that is exactly what a terminal of the other one
 looks like (`coflux workspace` to confirm, `cd` back to reach it); "predates the daemon upgrade" =
@@ -635,8 +637,8 @@ CLI's exit code is the remote command's**, so an ordinary shell test around it w
 failures — device offline (it exists and is not connected), no device of this account with that id
 (`设备 <id> 不存在或不属于当前账号`: a mistyped or bare-prefix id, **not** an outage to investigate),
 that device's daemon too old (`cofluxd update && cofluxd restart` there), `--cwd` missing or not a
-directory, the timeout elapsing — are one readable sentence and exit **255**, so a remote exit 1 is
-never confused with "it never ran".
+directory, the timeout elapsing — are reported as `✗ Error:` with a next step and exit **255**, so a
+remote exit 1 is never confused with "it never ran".
 
 `--cwd` is the only addressing: an absolute path or a `~` prefix, defaulting to the daemon user's
 HOME. To run inside a workspace, pass the `path` from `coflux workspace list --device <deviceId>`.