cofluxd 2.9.0 → 2.11.0

package/coflux.mjs

@@ -11,8 +11,10 @@ import { join } from "node:path";
 const HOME = process.env.COFLUX_HOME || join(homedir(), ".coflux");
 // Native integration owns explicit workspace selection and conversation state. `secret` is native
 // only too: it speaks the worker's kernel-attested socket and masks child output, and one
-// implementation of that is enough (plan 20260926-agent-secret-input).
-if (process.argv[2] === "agent" || process.argv[2] === "secret" || (process.argv[2] === "workspace" && process.argv[3] === "enter")) {
+// implementation of that is enough (plan 20260926-agent-secret-input). `annotations` is native only
+// as well: the worker keeps browser annotations and the Rust CLI renders them (plan
+// 20260929-browser-annotations).
+if (process.argv[2] === "agent" || process.argv[2] === "secret" || process.argv[2] === "annotations" || (process.argv[2] === "workspace" && process.argv[3] === "enter")) {
   const native = process.env.COFLUX_AGENT_BUNDLE
     ? join(process.env.COFLUX_AGENT_BUNDLE, "coflux")
     : join(HOME, "bin", "coflux");

package/cofluxd.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // cofluxd —— coflux daemon 管理 CLI。
-// daemon 是两个 Rust 二进制（supervisor 持 PTY + worker 频繁热升级，零 node 运行时）；
-// 本 CLI 只负责装/起/停/升级（用一下，不常驻）。systemd(Linux user) / launchd(macOS LaunchAgent)。
+// daemon 是三个 Rust 进程（ptyd 持 PTY、长生；supervisor 可随时替换；worker 频繁热升级，零 node 运行时）；
+// 本 CLI 只负责装/起/停/升级（用一下，不常驻）。systemd(Linux user) / launchd(macOS LaunchAgent)，
+// ptyd 与 supervisor 各自一份服务文件：重启 supervisor 不带走 ptyd，终端留在里面。
 import { parseArgs } from "node:util";
 import { homedir, hostname, platform, arch } from "node:os";
 import { join, dirname } from "node:path";
@@ -21,7 +22,7 @@ import {
   parseReleaseManifestEntry,
   verifyReleaseArtifact,
 } from "./release-trust.mjs";
-import { executorRuntime, plistXml, systemdUnit } from "./service-unit.mjs";
+import { executorRuntime, plistXml, ptydPlistXml, ptydSystemdUnit, systemdUnit } from "./service-unit.mjs";
 
 // 默认中心服务（公共 SaaS）；自托管用 --server 覆盖。
 const DEFAULT_SERVER = "wss://api.coflux.dev/daemon";
@@ -47,12 +48,19 @@ 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");
+// PTY 托管进程（plan 20260918-ptyd-terminal-custody）：与 supervisor 平级的独立服务，supervisor 找不到它就拒绝启动。
+const PTYD_BIN = join(BIN_DIR, "coflux-ptyd");
 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");
 const UNIT = join(homedir(), ".config", "systemd", "user", "coflux-daemon.service");
+// ptyd 是独立的服务（plan 20260918-ptyd-terminal-custody）：launchd 一个 plist 只能跑一个程序，systemd 默认
+// KillMode=control-group 会在 `systemctl restart` 时把整个 cgroup 一起杀——ptyd 必须在 supervisor 的进程组 /
+// cgroup 之外，重启 supervisor 才不会带走它。停止 daemon（down / uninstall）仍然一并停 ptyd。
+const PTYD_PLIST = join(homedir(), "Library", "LaunchAgents", "com.coflux.ptyd.plist");
+const PTYD_UNIT = join(homedir(), ".config", "systemd", "user", "coflux-ptyd.service");
 const DEFAULT_LOCAL_GATEWAY_PORT = 8788; // 与 packages/crates protocol 的 LOCAL_GATEWAY_PORT 保持一致
 
 const die = (m) => { console.error("✗ " + m); process.exit(1); };
@@ -270,7 +278,7 @@ async function resolveLatestTag() {
 async function ensureBinaries({ version, binDir, skipIfPresent }) {
   fs.mkdirSync(BIN_DIR, { recursive: true });
   if (binDir) {
-    const localArtifacts = ["coflux-supervisor", "coflux-worker", ...(fs.existsSync(join(binDir, "coflux")) ? ["coflux"] : []), ...(fs.existsSync(join(binDir, "coflux-transport")) ? ["coflux-transport"] : [])].map((name) => ({
+    const localArtifacts = ["coflux-supervisor", "coflux-worker", "coflux-ptyd", ...(fs.existsSync(join(binDir, "coflux")) ? ["coflux"] : []), ...(fs.existsSync(join(binDir, "coflux-transport")) ? ["coflux-transport"] : [])].map((name) => ({
       name,
       path: join(binDir, name),
     }));
@@ -308,7 +316,7 @@ async function ensureBinaries({ version, binDir, skipIfPresent }) {
     console.log(`✓ 用本地二进制（${binDir}）`);
     return;
   }
-  if (skipIfPresent && !version && fs.existsSync(SUP_BIN) && fs.existsSync(WRK_BIN)) {
+  if (skipIfPresent && !version && fs.existsSync(SUP_BIN) && fs.existsSync(WRK_BIN) && fs.existsSync(PTYD_BIN)) {
     console.log(`✓ 二进制已存在（${BIN_DIR}），跳过下载（用 cofluxd update 升级）`);
     return;
   }
@@ -357,7 +365,7 @@ async function ensureBinaries({ version, binDir, skipIfPresent }) {
     }
     const publicKey = loadReleasePublicKey();
     const staged = [];
-    for (const component of ["supervisor", "worker", ...(manifest.cli ? ["cli"] : []), ...(manifest.transport ? ["transport"] : [])]) {
+    for (const component of ["supervisor", "worker", ...(manifest.cli ? ["cli"] : []), ...(manifest.transport ? ["transport"] : []), ...(manifest.ptyd ? ["ptyd"] : [])]) {
       const entry = parseReleaseManifestEntry(manifest, component, releaseVersion, target);
       const artifactName = `coflux-${component}-${target}`;
       process.stdout.write(`下载并验签 ${artifactName} … `);
@@ -372,7 +380,7 @@ async function ensureBinaries({ version, binDir, skipIfPresent }) {
       fs.chmodSync(source, 0o755);
       staged.push({
         source,
-        destination: component === "cli" ? join(BIN_DIR, "coflux") : component === "supervisor" ? SUP_BIN : component === "transport" ? join(BIN_DIR, "coflux-transport") : WRK_BIN,
+        destination: component === "cli" ? join(BIN_DIR, "coflux") : component === "supervisor" ? SUP_BIN : component === "transport" ? join(BIN_DIR, "coflux-transport") : component === "ptyd" ? PTYD_BIN : WRK_BIN,
       });
       console.log("✓");
     }
@@ -421,26 +429,67 @@ function executorUnitRuntime() {
   return runtime;
 }
 
+/** 四份服务文件的路径与文本（`cofluxd service-files` 原样打印，黑盒据此断言 ptyd 独立受管）。 */
+function serviceFiles(executor = executorRuntime()) {
+  return {
+    launchd: {
+      supervisor: { path: PLIST, text: plistXml({ supervisorBin: SUP_BIN, home: HOME, logFile: LOG_FILE, executor }) },
+      ptyd: { path: PTYD_PLIST, text: ptydPlistXml({ ptydBin: PTYD_BIN, home: HOME, logFile: LOG_FILE }) },
+    },
+    systemd: {
+      supervisor: { path: UNIT, text: systemdUnit({ supervisorBin: SUP_BIN, home: HOME, executor }) },
+      ptyd: { path: PTYD_UNIT, text: ptydSystemdUnit({ ptydBin: PTYD_BIN, home: HOME }) },
+    },
+  };
+}
 function installService(start) {
+  const files = serviceFiles(executorUnitRuntime());
   if (IS_MAC) {
     fs.mkdirSync(dirname(PLIST), { recursive: true });
-    fs.writeFileSync(PLIST, plistXml({ supervisorBin: SUP_BIN, home: HOME, logFile: LOG_FILE, executor: executorUnitRuntime() }));
-    if (start) { run("launchctl", ["unload", PLIST]); run("launchctl", ["load", PLIST]); }
-    console.log(`✓ launchd: ${PLIST}`);
+    fs.writeFileSync(PTYD_PLIST, files.launchd.ptyd.text);
+    fs.writeFileSync(PLIST, files.launchd.supervisor.text);
+    if (start) {
+      // ptyd 先起：supervisor 连不上它会退出，KeepAlive 再拉一次也只是浪费。
+      run("launchctl", ["unload", PLIST]);
+      run("launchctl", ["unload", PTYD_PLIST]);
+      run("launchctl", ["load", PTYD_PLIST]);
+      run("launchctl", ["load", PLIST]);
+    }
+    console.log(`✓ launchd: ${PTYD_PLIST}\n✓ launchd: ${PLIST}`);
   } else if (IS_LINUX) {
     fs.mkdirSync(dirname(UNIT), { recursive: true });
-    fs.writeFileSync(UNIT, systemdUnit({ supervisorBin: SUP_BIN, home: HOME, executor: executorUnitRuntime() }));
-    if (start) { run("systemctl", ["--user", "daemon-reload"]); run("systemctl", ["--user", "enable", "--now", "coflux-daemon.service"]); }
-    console.log(`✓ systemd: ${UNIT}`);
+    fs.writeFileSync(PTYD_UNIT, files.systemd.ptyd.text);
+    fs.writeFileSync(UNIT, files.systemd.supervisor.text);
+    if (start) {
+      run("systemctl", ["--user", "daemon-reload"]);
+      run("systemctl", ["--user", "enable", "--now", "coflux-ptyd.service"]);
+      run("systemctl", ["--user", "enable", "--now", "coflux-daemon.service"]);
+    }
+    console.log(`✓ systemd: ${PTYD_UNIT}\n✓ systemd: ${UNIT}`);
   } else die("仅支持 macOS / Linux");
 }
+/** 只重启 supervisor：终端留在 ptyd 里。ptyd 若还没起（首次升到带 ptyd 的版本）先把它拉起来，已在跑则无事。 */
 function restartService() {
-  if (IS_MAC) { run("launchctl", ["unload", PLIST]); run("launchctl", ["load", PLIST]); }
-  else if (IS_LINUX) run("systemctl", ["--user", "restart", "coflux-daemon.service"]);
+  if (IS_MAC) {
+    run("launchctl", ["load", PTYD_PLIST]);
+    run("launchctl", ["unload", PLIST]);
+    run("launchctl", ["load", PLIST]);
+  } else if (IS_LINUX) {
+    run("systemctl", ["--user", "daemon-reload"]);
+    run("systemctl", ["--user", "enable", "--now", "coflux-ptyd.service"]);
+    run("systemctl", ["--user", "restart", "coflux-daemon.service"]);
+  }
+}
+/** 重启两者（ptyd 自身更新）：会结束本机全部终端。 */
+function restartAllServices() {
+  stopService();
+  if (IS_MAC) { run("launchctl", ["load", PTYD_PLIST]); run("launchctl", ["load", PLIST]); }
+  else if (IS_LINUX) { run("systemctl", ["--user", "start", "coflux-ptyd.service"]); run("systemctl", ["--user", "start", "coflux-daemon.service"]); }
 }
+/** 停止本机 daemon = supervisor + ptyd 一起停（终端结束）。 */
 function stopService() {
-  if (IS_MAC) run("launchctl", ["unload", PLIST]);
-  else if (IS_LINUX) run("systemctl", ["--user", "stop", "coflux-daemon.service"]);
+  if (IS_MAC) { run("launchctl", ["unload", PLIST]); run("launchctl", ["unload", PTYD_PLIST]); }
+  else if (IS_LINUX) { run("systemctl", ["--user", "stop", "coflux-daemon.service"]); run("systemctl", ["--user", "stop", "coflux-ptyd.service"]); }
 }
 
 async function applyAndStart({ serverUrl, deviceName, shell, version, binDir, noStart }) {
@@ -582,24 +631,46 @@ async function cmdUpdate(v) {
   if (!fs.existsSync(SETTINGS)) die("尚未安装，先 cofluxd up");
   const version = v.version || "latest";
   const before = fileSha256(SUP_BIN);
+  const ptydBefore = fileSha256(PTYD_BIN);
   await ensureBinaries({ version, binDir: v["bin-dir"] });
-  if (before === fileSha256(SUP_BIN)) {
-    console.log("✓ 已更新：supervisor 无变化——不需要重启，活会话不受影响");
+  const supervisorChanged = before !== fileSha256(SUP_BIN);
+  const ptydChanged = ptydBefore !== fileSha256(PTYD_BIN);
+  if (!supervisorChanged && !ptydChanged) {
+    console.log("✓ 已更新：supervisor / ptyd 无变化——不需要重启，活会话不受影响");
     console.log("  worker 由 server 自动热升级；本次刷新的只是兜底 worker 二进制。");
-  } else {
+    return;
+  }
+  if (supervisorChanged) {
     console.log(`✓ 新 supervisor 已就位（${v["bin-dir"] ? "本地产物" : version}），但尚未生效`);
-    console.log("  ⚠ 运行 `cofluxd restart` 应用——会重启 daemon 并结束本机所有活会话（PTY 随 supervisor 退出）。");
+    console.log("  运行 `cofluxd restart` 应用——终端留在 ptyd 里，屏幕与回滚原样保留，只有几秒停顿。");
+  }
+  if (ptydChanged) {
+    console.log(`✓ 新 ptyd（终端托管进程）已就位${ptydBefore ? "" : "（首次安装）"}，但尚未生效`);
+    console.log("  ⚠ 运行 `cofluxd restart --ptyd` 应用——ptyd 自身更新无法保留终端，会结束本机所有活会话。");
   }
 }
 
-// 唯一会主动中断会话的命令：应用已就位的新 supervisor（或单纯重启 daemon）。
-function cmdRestart() {
+// 应用已就位的新 supervisor（或单纯重启 supervisor）：终端留在 ptyd 里不动。
+// `--ptyd`：连 ptyd 一起重启（ptyd 自身更新时才需要）——这才是会结束本机会话的那条命令。
+function cmdRestart(v) {
   if (!fs.existsSync(SETTINGS)) die("尚未安装，先 cofluxd up");
-  console.log("⚠ 正在重启 daemon：本机所有活会话将结束（PTY 随 supervisor 退出）…");
-  restartService();
+  // 服务文件与模板同步（首次升到带 ptyd 的版本时 ptyd 的 plist / unit 还不存在）；只写文件，不在这里启动。
+  installService(false);
+  if (v.ptyd) {
+    console.log("⚠ 正在重启 ptyd 与 supervisor：本机所有活会话将结束…");
+    restartAllServices();
+  } else {
+    console.log("正在重启 supervisor：本机终端留在 ptyd 里，屏幕与回滚原样保留…");
+    restartService();
+  }
   console.log("✓ 已重启（cofluxd status 查看状态）");
 }
 
+/** 隐藏命令：把四份服务文件（launchd × 2、systemd × 2）以 JSON 打到 stdout，供黑盒断言与运维核对。 */
+function cmdServiceFiles() {
+  console.log(JSON.stringify(serviceFiles(), null, 2));
+}
+
 // launchd(macOS) / systemd --user(Linux) 服务活跃态查询，status 与 doctor 共用。
 // macOS 必须以 launchctl list 输出里的 PID 为准：label 登记 ≠ 进程存活（supervisor 被
 // OS_REASON_CODESIGNING 杀掉时 label 仍在，旧实现会报假"运行中"，2026-07-25 实测踩过）。
@@ -916,7 +987,9 @@ async function cmdFda() {
 
 function cmdUninstall(v) {
   stopService();
-  try { fs.rmSync(IS_MAC ? PLIST : UNIT); } catch { /* */ }
+  for (const file of IS_MAC ? [PLIST, PTYD_PLIST] : [UNIT, PTYD_UNIT]) {
+    try { fs.rmSync(file); } catch { /* */ }
+  }
   if (IS_LINUX) run("systemctl", ["--user", "daemon-reload"]);
   if (v.purge) { try { fs.rmSync(HOME, { recursive: true, force: true }); } catch { /* */ } console.log("✓ 已卸载并清除 " + HOME); }
   else console.log(`✓ 已卸载服务（保留二进制/配置/凭证于 ${HOME}；--purge 可全清）`);
@@ -929,8 +1002,9 @@ const HELP = `cofluxd —— coflux daemon 管理
   cofluxd up --key <密钥>  用 Coflux 添加设备里生成的一次性密钥直接接入账号（不打印授权链接；已接入则不做改动）
   cofluxd status          服务器/登记（含"等待授权"）/服务/连接状态
   cofluxd doctor          中心网络 + gateway bind/grant/loopback + daemon 状态分层自检
-  cofluxd update          下载新二进制（不重启；supervisor 有变化时提示用 restart 应用）
-  cofluxd restart         重启 daemon 应用新 supervisor（⚠ 结束本机所有活会话）
+  cofluxd update          下载新二进制（不重启；supervisor / ptyd 有变化时提示用 restart 应用）
+  cofluxd restart         重启 supervisor 应用新版本（终端留在 ptyd 里，不结束会话）
+  cofluxd restart --ptyd  连 ptyd 一起重启（⚠ 结束本机所有活会话；仅 ptyd 自身更新时需要）
   cofluxd fda             [仅 macOS] 引导授予完全磁盘访问权限（避免 PTY 因 TCC 弹窗卡住）
   cofluxd logs [-f]       看 daemon 日志
   cofluxd down            停止
@@ -946,12 +1020,13 @@ const { values, positionals } = parseArgs({
     server: { type: "string" }, name: { type: "string" }, shell: { type: "string" }, key: { type: "string" },
     version: { type: "string" }, "bin-dir": { type: "string" },
     "no-start": { type: "boolean", default: false }, purge: { type: "boolean", default: false },
+    ptyd: { type: "boolean", default: false },
     follow: { type: "boolean", short: "f", default: false }, help: { type: "boolean", short: "h", default: false },
   },
 });
 const cmd = positionals[0] || (fs.existsSync(SETTINGS) ? "status" : "up");
 if (values.help || cmd === "help") { console.log(HELP); process.exit(0); }
-const handlers = { up: cmdUp, update: cmdUpdate, restart: cmdRestart, down: cmdDown, status: cmdStatus, doctor: cmdDoctor, fda: cmdFda, logs: cmdLogs, uninstall: cmdUninstall };
+const handlers = { up: cmdUp, update: cmdUpdate, restart: cmdRestart, down: cmdDown, status: cmdStatus, doctor: cmdDoctor, fda: cmdFda, logs: cmdLogs, uninstall: cmdUninstall, "service-files": cmdServiceFiles };
 const handler = handlers[cmd];
 if (!handler) die(`未知命令: ${cmd}\n登录与终端操作请使用 coflux。\n\n${HELP}`);
 await handler(values);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cofluxd",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "Coflux 无界面宿主（cofluxd）与统一操作工具（coflux）",
   "type": "module",
   "bin": {

package/release-trust.mjs

@@ -17,6 +17,22 @@ export const CLI_RELEASE_STATEMENT_DOMAIN = Buffer.from("coflux-cli-release-v1\0
 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); }
 
+/** PTY 托管进程（plan 20260918-ptyd-terminal-custody）：独立 domain，合法的其它组件签名不能移植过来。 */
+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"];
+
+function releaseStatementFor(component, metadata) {
+  switch (component) {
+    case "worker": return workerReleaseStatement(metadata);
+    case "cli": return cliReleaseStatement(metadata);
+    case "transport": return transportReleaseStatement(metadata);
+    case "ptyd": return ptydReleaseStatement(metadata);
+    default: return supervisorReleaseStatement(metadata);
+  }
+}
+
 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;
@@ -146,7 +162,7 @@ function isRecord(value) {
  */
 export function parseReleaseManifestEntry(manifest, component, version, target) {
   assertReleaseVersion(version);
-  if (!["worker", "supervisor", "cli", "transport"].includes(component)) {
+  if (!RELEASE_COMPONENTS.includes(component)) {
     throw new Error(`未知 release component: ${JSON.stringify(component)}`);
   }
   if (!isRecord(manifest) || manifest.schemaVersion !== 2 || manifest.version !== version) {
@@ -200,9 +216,7 @@ export function verifyReleaseArtifact({ component, version, entry, data, publicK
     throw new Error("worker 产物 legacy Ed25519 签名无效");
   }
   const metadata = { version, target: entry.target, sha256, size: data.byteLength };
-  const statement = component === "worker"
-    ? workerReleaseStatement(metadata)
-    : component === "cli" ? cliReleaseStatement(metadata) : component === "transport" ? transportReleaseStatement(metadata) : supervisorReleaseStatement(metadata);
+  const statement = releaseStatementFor(component, metadata);
   if (!crypto.verify(null, statement, publicKey, Buffer.from(entry.releaseSignature, "hex"))) {
     throw new Error(`${component} 产物 release Ed25519 签名无效`);
   }
@@ -215,11 +229,11 @@ export function verifyReleaseArtifact({ component, version, entry, data, publicK
 export function installStagedPair(staged) {
   if (
     !Array.isArray(staged) ||
-    ![2, 3, 4, 5].includes(staged.length) ||
+    staged.length < 2 || staged.length > 6 ||
     staged.some(({ source, destination }) =>
       typeof source !== "string" || !source || typeof destination !== "string" || !destination)
   ) {
-    throw new Error("daemon installation requires two to five valid staged artifacts");
+    throw new Error("daemon installation requires two to six valid staged artifacts");
   }
   const installed = [];
   const backups = [];

package/service-unit.mjs

@@ -80,6 +80,53 @@ ${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.
+ */
+export function ptydPlistXml({ ptydBin, home, logFile }) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>com.coflux.ptyd</string>
+  <key>ProgramArguments</key>
+  <array><string>${xml(ptydBin)}</string></array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>COFLUX_HOME</key><string>${xml(home)}</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${xml(logFile)}</string>
+  <key>StandardErrorPath</key><string>${xml(logFile)}</string>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * 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).
+ */
+export function ptydSystemdUnit({ ptydBin, home }) {
+  const environment = oneLine(home) ? `Environment=COFLUX_HOME=${home}\n` : "";
+  return `[Unit]
+Description=coflux ptyd (terminal custody)
+
+[Service]
+${environment}ExecStart=${ptydBin}
+Restart=always
+RestartSec=2
+KillMode=process
+
+[Install]
+WantedBy=default.target
+`;
+}
+
 export function systemdUnit({ supervisorBin, home, executor }) {
   const variables = [["COFLUX_HOME", home]];
   if (executor) {
@@ -91,8 +138,9 @@ export function systemdUnit({ supervisorBin, home, executor }) {
     .join("\n");
   return `[Unit]
 Description=coflux daemon (supervisor)
-After=network-online.target
+After=network-online.target coflux-ptyd.service
 Wants=network-online.target
+Requires=coflux-ptyd.service
 
 [Service]
 ${environment}

package/skills/coflux/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coflux
-description: Use coflux to enter workspaces, open terminals the user can see and take over, run commands in them, wait for those commands, read their scrollback, type into them, run one-shot commands on another device in the account and get their output, report progress, notify the user, obtain preview URLs, get a secret (API key, password) from the user without the value entering your context, and hand a bounded mechanical sub-task to the built-in executor instead of spending your own context on it. Prefer zero-credential local commands in the current workspace; use the account CLI across workspaces and devices. Coordinates arrive through coflux-session or COFLUX_* variables.
+description: Use coflux to enter workspaces, open terminals the user can see and take over, run commands in them, wait for those commands, read their scrollback, type into them, run one-shot commands on another device in the account and get their output, report progress, notify the user, obtain preview URLs, get a secret (API key, password) from the user without the value entering your context, pick up the elements the user annotated in Coflux's built-in browser and mark them done, and hand a bounded mechanical sub-task to the built-in executor instead of spending your own context on it. Prefer zero-credential local commands in the current workspace; use the account CLI across workspaces and devices. Coordinates arrive through coflux-session or COFLUX_* variables.
 ---
 
 # Working inside coflux
@@ -14,10 +14,10 @@ and a way to operate the other workspaces and devices under the account when you
 
 | Track | Credentials | Reach | Use for |
 |---|---|---|---|
-| Local commands `coflux terminal/progress/notify/ports/executor/secret` | none (the daemon identifies you by process tree) | **the workspace your cwd is in** | open, run, wait, read, send, close, report progress, call the user, preview URLs, get a secret from the user, hand a bounded sub-task to the built-in executor: the default; some actions require a server connection |
+| Local commands `coflux terminal/progress/notify/ports/executor/secret/annotations` | none (the daemon identifies you by process tree) | **the workspace your cwd is in** | open, run, wait, read, send, close, report progress, call the user, preview URLs, get a secret from the user, implement the user's browser annotations, hand a bounded sub-task to the built-in executor: the default; some actions require a server connection |
 | Account CLI | app login or `coflux login` | all devices and workspaces in the account | child workspaces and remote terminals; JSON output |
 
-Of the local commands, `run`/`wait`/`read`/`send`/`close`/`progress`/`executor` complete
+Of the local commands, `run`/`wait`/`read`/`send`/`close`/`progress`/`executor`/`annotations` complete
 entirely inside the local daemon and never touch the center; `new`/`list`/`ports`/`notify` are relayed to the
 center by the daemon on your behalf (terminals and notification history are persisted centrally; preview URLs are
 minted by the center). You only ever talk to the local daemon.
@@ -510,6 +510,39 @@ executor cannot use `coflux secret` (it is not a terminal process). And it preve
 a determined agent: once a value is in an environment variable or a file you can read, printing it
 on purpose would leak it — never do that.
 
+### Implement the user's browser annotations
+
+```sh
+coflux annotations list
+coflux annotations resolve 3 --note "Primary button now uses the brand token; spacing from the 8px scale"
+coflux annotations watch
+```
+
+The user can point at elements of a page in Coflux's built-in browser tab ("this element — change it
+like so") and hand them to you; the desktop then types an instruction into your terminal, or they
+simply ask you to handle the annotations. They belong to the workspace your cwd is in and live on
+this machine, so they are there whether or not a desktop is open.
+
+- `list` prints the pending ones as markdown: the user's comment (and, for a reopened one, your
+  earlier note and what the user answered), the page, the component chain and source location when
+  the page exposed them, the element's selector, DOM path and key computed styles, and the paths of
+  its images. It always names the workspace it resolved: an empty list in the wrong workspace means
+  you moved (`coflux workspace`). Add `--json` for structured output.
+- Find the code from the most specific lead: a source location first, then the component names,
+  then text and selectors (`rg` for them). Treat the computed styles as the current state, not as
+  the target: map colors, sizes and spacing onto the project's design system (its tokens, theme and
+  components) instead of hard-coding raw values.
+- The images are local files: read them. A *screenshot of the current state* shows the element as
+  the user saw it; a *reference image* is what the user wants or pointed at.
+- After implementing each annotation, run `resolve <id or number> --note "<what you changed>"`.
+  The note is what the user reads to review the change; the pin on their page turns into a check.
+  They confirm it (it disappears) or reopen it with a comment, and it comes back in `list`. Resolve
+  only what you actually changed; if you cannot or should not do one, resolve it with a note that
+  says why rather than leaving it pending silently.
+- `watch` blocks until the workspace has pending annotations and then prints them like `list`
+  (default budget 30 minutes, `--timeout <seconds>`). Use it only when the user asked you to keep
+  handling annotations hands-free: loop list → implement → resolve → `watch`.
+
 ### Errors from local commands
 
 Errors are one readable sentence; do what they say: "not inside a coflux terminal" = you are not