cofluxd 1.1.1 → 2.0.1

package/README.md

@@ -9,6 +9,36 @@ Operate local and remote terminals from one account. This package provides two d
 
 Desktop, CLI, and runtime releases share the same version. The macOS desktop app includes its own native `coflux` binary and does not require this npm package or Node.js.
 
+## Codex skill discovery in Coflux terminals
+
+Interactive `codex`, `codex resume`, and `codex fork` invocations use a private
+Codex app-server. The native CLI registers the invocation's immutable Coflux skill
+directory through `skills/extraRoots/set` before connecting the TUI over a private
+Unix socket. Coflux appears in `/skills` and the `$` skill selector, and Codex loads
+the skill body on demand. The session hook continues to supply current terminal
+and workspace coordinates.
+
+No skill is installed in the user's skill directories and no plugin or marketplace
+registration is written to their configuration. The extra root belongs only to
+this app-server process; concurrent invocations keep their own skill versions.
+The launcher monitors the terminal UI, and a lifetime-pipe watchdog cleans up the
+backend and socket when the launcher exits, including when the terminal is killed.
+
+This requires a Codex version supporting `--remote unix://PATH` and
+`skills/extraRoots/set` (verified with Codex CLI 0.154.0). If startup or skill
+discovery fails, the launcher reports the error instead of claiming integration
+is ready. `COFLUX_AGENT_INTEGRATION=off codex` bypasses managed integration.
+Profile-selected invocations (`--profile` / `-p`) retain the native runtime and
+print an explanatory notice: Codex app-server cannot load profiles, and using the
+remote TUI would lose profile fields such as `developer_instructions`. Explicit
+`--remote` endpoints, administrative commands, and noninteractive commands
+such as `codex exec` retain the existing launch path; they do not receive this
+process-local skill registration. Existing hook injection remains unchanged.
+
+For remote resume/fork, `--yolo`, `--sandbox`, `--ask-for-approval`, and permission
+config overrides are applied to the private backend; Codex rejects these options
+on the remote TUI itself. New sessions retain the native TUI permission flags.
+
 ## Install
 
 Requires Node.js 20 or later.
@@ -34,14 +64,20 @@ coflux terminal read <terminal-id> --remote
 Account commands return JSON. Inside a Coflux terminal, local commands automatically use the current workspace:
 
 ```sh
-coflux terminal new --title 'Tests' --cmd 'pnpm test'
+coflux terminal new --title 'Tests' --cmd 'pnpm test'   # a persistent shell; the command is typed in once its prompt is ready
+coflux terminal wait <terminal-id>                      # blocks until that command finishes and prints its exit code
+coflux terminal run <terminal-id> --cmd 'pnpm lint'     # type another command into the same shell
+coflux terminal read <terminal-id>                      # the tail of the terminal's scrollback
 coflux terminal list
-coflux terminal read <terminal-id>
-coflux terminal wait <terminal-id>
+coflux terminal close <terminal-id>
 coflux progress 'Reviewing the changes.'
 coflux notify 'Ready for your review.'
 ```
 
+Every terminal is the workspace's default login shell on a real tty, alive until `exit` or `close`; `--cmd` and `run` only type a command in after the shell has signalled that its prompt is ready, and `wait` reports that command's exit code while the terminal stays open.
+
+`coflux notify` sends a persistent notification to your account inbox from the owning terminal. It needs a server connection and reports success only after the server saves it. Desktop shows an in-app hint in the foreground and additionally requests a system notification in the background. Reading a notification clears its unread state, while history survives hooks, terminal exit, and source deletion.
+
 The CLI bundled with the desktop app can reuse the app's login through a local channel. Independently installed CLIs can sign in themselves. See `coflux --help`, `cofluxd --help`, and the [agent skill](skills/coflux/SKILL.md).
 
 ## Upgrades and terminal lifetime

package/account-client.mjs

@@ -29,6 +29,11 @@ function broker(home, body, timeout) {
     socket.on("end", () => { try { resolve(unwrap(JSON.parse(text))); } catch (error) { reject(error); } });
   });
 }
+/** 写到底再继续：`device exec` 之后要用远端退出码退出，而 process.exit 会截断写向管道的输出。 */
+function writeAll(stream, text) {
+  if (!text) return Promise.resolve();
+  return new Promise((resolve) => stream.write(text, resolve));
+}
 export function handlesAccountCommand(positionals, flags, home) {
   const [command, sub] = positionals;
   if (["login", "logout", "whoami", "device", "project"].includes(command)) return true;
@@ -59,7 +64,8 @@ export async function runAccountCommand(positionals, flags, home) {
   const session = fs.existsSync(sessionPath) ? JSON.parse(fs.readFileSync(sessionPath, "utf8")) : null;
   const call = (operation) => {
     const body = { protocolVersion: 1, command: operation };
-    const timeout = operation.op === "terminal.wait" ? 610000 : 40000;
+    // `terminal.wait` 与 `device.exec` 都可能在中心侧阻塞到 600 秒；其余账号操作 40 秒足够。
+    const timeout = operation.op === "terminal.wait" || operation.op === "device.exec" ? 610000 : 40000;
     if (!session) {
       if (flags.server) throw new Error("请先登录指定服务器");
       return broker(home, body, timeout);
@@ -76,6 +82,32 @@ export async function runAccountCommand(positionals, flags, home) {
     print({ loggedOut: true });
     return;
   }
+  // `device exec`: one-shot cross-device execution, ssh semantics — not a Terminal, so the output is
+  // not JSON either. stdout goes to stdout, stderr to stderr (always separate), the last line is
+  // `# exit=<code>`, and the process exit code is the **remote** one. This CLI's own failures
+  // (device offline, capability missing, bad cwd, timeout, bad arguments) all exit 255, so a caller's
+  // shell test can tell "the remote command returned 1" from "it never ran".
+  if (command === "device" && sub === "exec") {
+    const fail = async (message) => { await writeAll(process.stderr, `✗ ${message}\n`); process.exit(255); };
+    let value;
+    try {
+      if (!id) throw new Error("缺少设备 ID（coflux device list 可以看到）");
+      const cmd = required("cmd");
+      const timeout = Number(flags.timeout ?? 60);
+      // 上限在这里就说清楚，别让中心的入参校验回一句「请求失败」。
+      if (!Number.isInteger(timeout)) throw new Error("--timeout 必须是整数秒");
+      if (timeout < 1 || timeout > 600) throw new Error("--timeout 取 1-600 秒；更久、或需要用户看见的长任务请改用 coflux terminal new");
+      value = await call({ op: "device.exec", deviceId: id, command: cmd, cwd: flags.cwd ?? "", timeout });
+    } catch (error) {
+      await fail(error.message);
+    }
+    const exitCode = Number(value?.exitCode);
+    if (!Number.isInteger(exitCode)) await fail("设备回执缺少退出码（中心版本过旧？）");
+    await writeAll(process.stdout, String(value.stdout ?? ""));
+    await writeAll(process.stderr, String(value.stderr ?? ""));
+    await writeAll(process.stdout, `# exit=${exitCode}\n`);
+    process.exit(exitCode);
+  }
   let operation;
   if (command === "workspace") {
     if (sub === "new") operation = { op: "workspace.new", projectId: required("project"), branch: required("branch"), createNew: !flags["existing-branch"], ...(flags.name ? { name: flags.name } : {}) };
@@ -83,7 +115,9 @@ export async function runAccountCommand(positionals, flags, home) {
     if (sub === "remove") operation = { op: "workspace.remove", workspaceId: target() };
   }
   if (command === "terminal") {
+    // `--cmd` is "do script": typed into the new terminal once its shell is at the prompt; the terminal stays open.
     if (sub === "new") operation = { op: "terminal.new", workspaceId: required("workspace"), title: flags.title || "", command: flags.cmd || "" };
+    if (sub === "run") operation = { op: "terminal.run", terminalId: target(), command: required("cmd") };
     if (sub === "read") operation = { op: "terminal.read", terminalId: target(), lines: Number(flags.lines ?? 200) };
     if (sub === "send") operation = { op: "terminal.send", terminalId: target(), text: required("text"), enter: !!flags.enter };
     if (sub === "wait") operation = { op: "terminal.wait", terminalId: target(), timeout: Number(flags.timeout ?? 30) };

package/coflux.mjs

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
 // coflux：账号与本地、跨设备业务操作；不负责宿主生命周期。
 import { handlesAccountCommand, runAccountCommand } from "./account-client.mjs";
+import { randomUUID } from "node:crypto";
 import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const HOME = process.env.COFLUX_HOME || join(homedir(), ".coflux");
-// Delegate integration to the native CLI shipped with this device's runtime.
-if (process.argv[2] === "agent") {
-  const native = join(HOME, "bin", "coflux");
+// Native integration owns explicit workspace selection and conversation state.
+if (process.argv[2] === "agent" || (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");
   if (!existsSync(native)) {
     console.error("Coflux integration is unavailable. Update this device with cofluxd update.");
     process.exit(1);
@@ -122,10 +125,9 @@ async function cmdHook() {
 // **看得见、能接管**的 coflux 实体——而不是在自己的 Bash 里后台起一个谁也看不见的进程。
 //
 // 不需要任何凭证：daemon 用调用方 pid 反查进程树确认它属于哪个会话，树外一律拒。
-// local-first（plan 094）：send/read/wait/notify/progress 在 daemon 本地闭环，不经中心；只有
-// new/list/ports 由 daemon 代问中心（Task 要落库广播、预览 URL 由中心生成）。
-// 跟随 cwd（plan 102）：请求都带 process.cwd()，agent 挪进同设备另一个 coflux 工作区后，这些
-// 命令就对那个工作区办事（notify/progress/ports 除外，它们挂在本会话上，与工作区无关）。
+// Local read/send/run/wait/close/progress stay on the daemon. Notify, new/list/ports and ownership
+// changes require a server acknowledgement. Scope follows cwd except terminal-owned
+// notify/progress/ports, whose source remains the owning session.
 // 与 `hook` 子命令的约定**相反**：这些命令必须写 stdout——输出就是给 agent 读的返回值。
 // 也刻意不做自动重试：terminal new 有副作用，重试会开出两个终端，失败就把错误交给 agent。
 
@@ -133,11 +135,11 @@ const AGENT_TIMEOUT_MS = 30_000;
 /** 调用方能收窄单次 `/agent` 等待的下限；再低就只够覆盖 node 自己的启动，等于必然超时。 */
 const MIN_AGENT_TIMEOUT_MS = 200;
 const DEFAULT_READ_LINES = 200;
-// wait 的循环必须在 CLI 侧：单次 agentPost 有 25 秒的 loopback 应答上限。默认 30 分钟——编码任务
-// 常跑很久；轮询走 terminal.status（daemon 本地账本直接答，不经中心），3 秒一次对本机 loopback
-// 是零负担。
+// wait loops here because one agentPost round-trip is capped at 25 s on the loopback endpoint; each
+// round the daemon blocks up to WAIT_ROUND_MS on its command-state watch and answers the moment the
+// command finishes, so the loop never hammers it. Default 30 minutes overall.
 const DEFAULT_WAIT_TIMEOUT_S = 1800;
-const WAIT_POLL_MS = 3000;
+const WAIT_ROUND_MS = 20_000;
 
 // 每条请求都带调用方 cwd（plan 102）：agent 可以经 `/cd` 或 EnterWorktree 把活着的会话挪进同
 // 设备的另一个 coflux 工作区，daemon 据此把本次请求的**目标**解析到 cwd 所在的工作区（会话的
@@ -157,9 +159,12 @@ function agentTimeoutMs() {
   return Math.min(Math.max(Math.floor(raw), MIN_AGENT_TIMEOUT_MS), AGENT_TIMEOUT_MS);
 }
 
-async function agentPost(body) {
+// The two kinds of `/agent` failure, separated for the executor's submit path: only a "transport"
+// failure may be re-sent with the same submissionId (the daemon deduplicates on it); re-sending a
+// "refused" request accomplishes nothing. Mirrors `AgentError` in crates/cli/src/gateway.rs.
+async function agentPostResult(body) {
   const portResult = localGatewayPort();
-  if (!portResult.ok) die(portResult.error);
+  if (!portResult.ok) return { ok: false, kind: "refused", message: portResult.error };
   let res;
   try {
     res = await fetch(`http://127.0.0.1:${portResult.port}/agent`, {
@@ -169,12 +174,19 @@ async function agentPost(body) {
       signal: AbortSignal.timeout(agentTimeoutMs()),
     });
   } catch (error) {
-    die(`连不上本机 daemon：${error?.message || error}（daemon 没在跑？查看 Coflux.app 或 cofluxd status）`);
+    const detail = error?.message || error;
+    return { ok: false, kind: "transport", message: `连不上本机 daemon：${detail}（daemon 没在跑？查看 Coflux.app 或 cofluxd status）` };
   }
   let parsed = null;
   try { parsed = await res.json(); } catch { /* 非 JSON 响应按下面的兜底报错处理 */ }
-  if (!res.ok || !parsed?.ok) die(parsed?.error || `daemon 返回 ${res.status}`);
-  return parsed;
+  if (!res.ok || !parsed?.ok) return { ok: false, kind: "refused", message: parsed?.error || `daemon 返回 ${res.status}` };
+  return { ok: true, value: parsed };
+}
+
+async function agentPost(body) {
+  const result = await agentPostResult(body);
+  if (!result.ok) die(result.message);
+  return result.value;
 }
 
 // 剥掉 ANSI/OSC 转义与 C0 控制字符，保留 \t 与 \n——snapshot 是给终端渲染的字节流，
@@ -194,29 +206,57 @@ function tailLines(text, n) {
   return lines.slice(-n).join("\n");
 }
 
+/** ` busy` / ` idle` plus ` last=<code>` for a live, instrumented terminal; nothing otherwise. */
+function commandSuffix(t) {
+  if (!t.integrated) return "";
+  const last = t.lastCommandExitCode === undefined || t.lastCommandExitCode === null ? "" : ` last=${t.lastCommandExitCode}`;
+  return `${t.busy ? " busy" : " idle"}${last}`;
+}
+
+/** "do script": type a command into a terminal once its shell signalled prompt readiness. */
+async function runCommand(taskId, command) {
+  const result = await agentPost({ action: "terminal.run", taskId, command });
+  console.log(`已打入命令 #${result.commandSeq}（coflux terminal wait ${taskId} 等它结束，coflux terminal read ${taskId} 看输出）`);
+}
+
 async function cmdTerminal(values) {
   const sub = positionals[1];
   if (sub === "new") {
-    // 两种终端只看「命令是否为空」（plan 101）：--cmd 缺省与 --cmd= 空白等价，都开会话终端
-    // ——工作区目录下的默认登录 shell，stdin/stdout 都是真 tty，不自动退出。带命令的仍是作业
-    // 终端：命令跑完终端退出并带退出码，语义一字不变。空白在这里统一收敛成空串，好让中心的
-    // 「默认标题取命令首行」落到它自己的兜底。
+    // Open first, then "do script": the terminal exists (and is reported) even when the command
+    // cannot be typed — an old daemon refuses terminal.run as an unknown action and never runs
+    // the command any other way. --cmd missing and --cmd= blank are the same: nothing is typed.
     const command = (values.cmd ?? "").trim() ? values.cmd : "";
-    const result = await agentPost({ action: "terminal.new", title: values.title || "", command });
+    const result = await agentPost({ action: "terminal.new", title: values.title || "" });
     console.log(`已开终端 ${result.taskId}（用户可在 coflux 侧栏看到并随时接管）`);
     if (command) {
-      console.log(`看输出：coflux terminal read ${result.taskId}`);
+      await runCommand(result.taskId, command);
     } else {
-      console.log(`会话终端：常驻的登录 shell（全 tty），不会自己退出`);
-      console.log(`先等提示符：coflux terminal read ${result.taskId}`);
-      console.log(`再输命令：coflux terminal send ${result.taskId} --text "<命令>" --enter（送 exit 才结束）`);
+      console.log(`常驻的登录 shell（全 tty），不会自己退出`);
+      console.log(`跑命令：coflux terminal run ${result.taskId} --cmd="<命令>"（等提示符就绪后打入，wait 可等它结束）`);
+      console.log(`看输出：coflux terminal read ${result.taskId}；结束：coflux terminal close ${result.taskId}`);
+    }
+  } else if (sub === "run") {
+    const taskId = positionals[2];
+    if (!taskId) die("terminal run 需要 <taskId>（用 coflux terminal list 查）");
+    const command = (values.cmd ?? "").trim() ? values.cmd : "";
+    if (!command) die(`terminal run 需要 --cmd="<命令>"`);
+    await runCommand(taskId, command);
+  } else if (sub === "close") {
+    const taskId = positionals[2];
+    if (!taskId) die("terminal close 需要 <taskId>（用 coflux terminal list 查）");
+    const result = await agentPost({ action: "terminal.close", taskId });
+    if (result.exited) {
+      const exit = result.exitCode === undefined || result.exitCode === null ? "" : ` exit=${result.exitCode}`;
+      console.log(`已关闭终端 ${taskId}（exited${exit}）`);
+    } else {
+      console.log(`已请求关闭终端 ${taskId}，shell 仍在退出中（coflux terminal list 可查）`);
     }
   } else if (sub === "list") {
     const { terminals } = await agentPost({ action: "terminal.list" });
     if (!terminals.length) return void console.log("本工作区暂无终端");
     for (const t of terminals) {
       const exit = t.exitCode === undefined || t.exitCode === null ? "" : ` exit=${t.exitCode}`;
-      console.log(`${t.taskId}  ${t.status}${exit}  ${t.title}`);
+      console.log(`${t.taskId}  ${t.status}${exit}${commandSuffix(t)}  ${t.title}`);
     }
   } else if (sub === "read") {
     const taskId = positionals[2];
@@ -240,29 +280,33 @@ async function cmdTerminal(values) {
     if (!taskId) die("terminal wait 需要 <taskId>（用 coflux terminal list 查）");
     const requested = Number(values.timeout);
     const timeoutSec = Number.isFinite(requested) && requested > 0 ? requested : DEFAULT_WAIT_TIMEOUT_S;
+    const seq = Number(values.seq);
+    const commandSeq = Number.isInteger(seq) && seq > 0 ? seq : 0;
     const deadline = Date.now() + timeoutSec * 1000;
     for (;;) {
-      // 按 taskId 直接问本地账本；目标不存在/不在本工作区时 daemon 回可读错误，agentPost 直接 die。
-      const t = await agentPost({ action: "terminal.status", taskId });
-      if (t.status === "exited") {
+      // Each round blocks inside the daemon (its command-state watch wakes it the moment the
+      // command ends); a `running` answer only means the round elapsed.
+      const roundMs = Math.min(WAIT_ROUND_MS, Math.max(1, deadline - Date.now()));
+      const t = await agentPost({ action: "terminal.wait", taskId, commandSeq, timeoutMs: roundMs });
+      if (t.state !== "running") {
         const exit = t.exitCode === undefined || t.exitCode === null ? "" : ` exit=${t.exitCode}`;
-        return void console.log(`# exited${exit}`);
+        return void console.log(`# ${t.state === "exited" ? "exited" : "finished"}${exit}`);
       }
       if (Date.now() >= deadline) {
-        die(`等待超时（${timeoutSec}s）：终端 ${taskId} 仍是 ${t.status}。可加大 --timeout，或 coflux terminal read ${taskId} 看现场`);
+        die(`等待超时（${timeoutSec}s）：终端 ${taskId} 的命令 #${t.commandSeq} 仍在运行。可加大 --timeout，或 coflux terminal read ${taskId} 看现场`);
       }
-      await sleep(WAIT_POLL_MS);
     }
   } else {
-    die(`terminal 需要子命令：new | list | read | wait | send`);
+    die(`terminal 需要子命令：new | run | list | read | wait | send | close`);
   }
 }
 
 async function cmdNotify() {
   const message = positionals.slice(1).join(" ").trim();
   if (!message) die(`notify 需要一句话，例如：coflux notify "两个方案拿不准，需要你定"`);
-  await agentPost({ action: "notify", message });
-  console.log("已通知用户（工作区在侧栏转为「等待交互」）");
+  const result = await agentPost({ action: "notify", notificationId: randomUUID(), message });
+  if (!result.notificationId) die("daemon 不支持持久通知，请升级；未确认送达");
+  console.log("通知已发送（已保存到账号通知中心）");
 }
 
 async function cmdProgress() {
@@ -318,7 +362,7 @@ async function cmdWorkspace() {
       removed: Boolean(result.removed),
     }));
   }
-  die(`workspace 的子命令只有 locate | forget（不带子命令 = 报出我在哪）`);
+  die(`workspace 的子命令只有 enter | locate | forget（不带子命令 = 报出我在哪）`);
 }
 
 async function cmdPorts() {
@@ -327,32 +371,149 @@ async function cmdPorts() {
   for (const p of ports) console.log(`${p.port}  ${p.url}`);
 }
 
+/* -------------------------------- executor ------------------------------- */
+// `coflux executor run`: hand one well-bounded sub-task to the built-in executor. Request bodies,
+// stdout phrases and exit codes are aligned command-for-command with `run_executor` in
+// crates/cli/src/commands.rs.
+//
+// Three phases: **submit** returns a runId (answered immediately, deduplicated by `submissionId`)
+// -> the CLI **polls** status (a single `/agent` reply is capped at 25 seconds, so a long run can
+// never hang off one request) -> the terminal state is rendered. On wait timeout a cancel goes out
+// before the error: leaving an unwatched write job editing files is worse than the timeout itself.
+
+// Tighter than WAIT_POLL_MS: the executor's terminal state is a return value someone is blocked on.
+const EXECUTOR_POLL_MS = 2000;
+const DEFAULT_EXECUTOR_TIMEOUT_S = 1800;
+// How many times a submission may be re-sent after a *transport* failure. The retry reuses the same
+// submissionId and the daemon deduplicates on it — "never blindly resubmit" forbids a second id,
+// not a second attempt.
+const EXECUTOR_SUBMIT_RETRIES = 2;
+
+/** This process's stable submission id: pid plus the nanosecond it was minted. Generated once. */
+function submissionId() {
+  const nanos = BigInt(Date.now()) * 1000000n + (process.hrtime.bigint() % 1000000n);
+  return `sub-${process.pid}-${nanos}`;
+}
+
+function executorTimeoutSecs(raw) {
+  const requested = Number(raw);
+  return Number.isFinite(requested) && requested > 0 ? requested : DEFAULT_EXECUTOR_TIMEOUT_S;
+}
+
+function executorChangedFiles(status) {
+  return Array.isArray(status?.changedFiles) ? status.changedFiles.filter((f) => typeof f === "string") : [];
+}
+
+/** stdout for a success: a machine-readable status line, the final reply, then the changed files. */
+function renderExecutorSuccess(status) {
+  const out = ["# succeeded"];
+  const summary = String(status?.summary ?? "").trim();
+  out.push(summary || "（executor 没有留下最终回复）");
+  const files = executorChangedFiles(status);
+  if (!files.length) out.push("改动文件：无");
+  else { out.push(`改动文件（${files.length}）：`); out.push(...files); }
+  out.push("executor 不会 git commit：改动请自己 review 后提交。");
+  return out.join("\n");
+}
+
+/** One stderr sentence for a non-success terminal state: state, reason, and what already changed. */
+function renderExecutorFailure(status) {
+  const terminal = String(status?.terminal ?? "") || "unknown";
+  const reason = String(status?.error ?? "").trim() || String(status?.note ?? "").trim() || "executor 没有给出原因";
+  const files = executorChangedFiles(status);
+  const tail = files.length ? `；已改动 ${files.length} 个文件：${files.join(" ")}` : "";
+  return `executor 任务未成功（${terminal}）：${reason}${tail}`;
+}
+
+function renderExecutorTimeout(timeoutSec, runId, phase) {
+  return `等待超时（${timeoutSec}s）：executor 任务 ${runId} 仍是 ${phase}，已请求取消。可加大 --timeout 后重发`;
+}
+
+/** Submit. A transport failure retries with the same submissionId; a refusal is reported verbatim. */
+async function executorSubmit(prompt, write) {
+  const submission = submissionId();
+  for (let attempt = 0; ; attempt += 1) {
+    const result = await agentPostResult({ action: "executor.submit", submissionId: submission, prompt, write });
+    if (result.ok) {
+      const runId = String(result.value?.runId ?? "");
+      if (!runId) die("daemon 没有返回 runId（版本太旧？）");
+      return runId;
+    }
+    if (result.kind === "refused" || attempt >= EXECUTOR_SUBMIT_RETRIES) die(result.message);
+    await sleep(EXECUTOR_POLL_MS);
+  }
+}
+
+async function cmdExecutor(values) {
+  if (positionals[1] !== "run") die(`executor 的子命令只有 run：coflux executor run --prompt="<任务>" [--write]`);
+  const prompt = String(values.prompt ?? "").trim();
+  if (!prompt) {
+    die(`executor run 需要 --prompt="<任务>"（一句把边界说清的任务描述，例如 --prompt="把 crates/worker 的 clippy 警告清掉"）`);
+  }
+  const write = Boolean(values.write);
+  const timeoutSec = executorTimeoutSecs(values.timeout);
+  const deadline = Date.now() + timeoutSec * 1000;
+  const runId = await executorSubmit(prompt, write);
+  for (;;) {
+    // The first poll does not sleep: a rejection (write lock taken, model not configured) has to
+    // surface immediately instead of costing the caller a whole poll interval.
+    const status = await agentPost({ action: "executor.status", runId });
+    if (status.phase === "done") {
+      // `succeeded` is about the *task*; the envelope's top-level `ok` only says the request itself
+      // was accepted.
+      if (status.succeeded) return void console.log(renderExecutorSuccess(status));
+      die(renderExecutorFailure(status));
+    }
+    if (Date.now() >= deadline) {
+      // Cancel before reporting: an unwatched write job still editing files in the background is
+      // far worse than the timeout itself.
+      await agentPostResult({ action: "executor.cancel", runId });
+      die(renderExecutorTimeout(timeoutSec, runId, status.phase));
+    }
+    await sleep(EXECUTOR_POLL_MS);
+  }
+}
+
 const HELP = `coflux —— 账号与终端操作
   coflux hook <claude|codex>   [agent hook 信使] 读 stdin/argv 的事件 JSON，转发给本机 daemon
                           （在 claude/codex 的 hook 配置里指向本命令；失败静默，不干扰 agent）
 
   以下几条供**跑在 coflux 终端里的 agent** 调用，把工作变成用户看得见、能接管的东西：
 
-  coflux terminal new [--cmd "<命令>"] [--title "<标题>"]
-                          开一个真实终端，用户在 coflux 侧栏能看到并随时接管
-                          带 --cmd = 作业终端：命令在登录 shell 里跑完即退出并带退出码，输出另
-                          落一份日志供 read 回读（代价：stdout 是管道，不是 tty）
-                          不带 --cmd = 会话终端：工作区目录下的常驻登录 shell，stdin/stdout 都是
-                          真 tty（能跑 vim/htop、有颜色），先 read 等提示符再 send，送 exit 才结束
-  coflux terminal list   列出本工作区的终端（含 status / 退出码）
-  coflux terminal read <taskId> [--lines N]
-                          读某个终端的内容（纯文本，默认最后 200 行；终端已退出也能读）
-  coflux terminal wait <taskId> [--timeout <秒>]
-                          阻塞等到该终端退出，打印退出码（默认超时 30 分钟）
-  coflux terminal send <taskId> --text "<文本>" [--enter]
+  coflux terminal new [--title="<标题>"] [--cmd="<命令>"]
+                          开一个真实终端：工作区目录下的常驻登录 shell，stdin/stdout 都是真 tty，
+                          用户在 coflux 侧栏能看到并随时接管，直到输入 exit 或 close 才结束
+                          带 --cmd = 等 shell 提示符就绪后把命令打进去（终端继续活着），等于 new + run
+  coflux terminal run <taskId> --cmd="<命令>"
+                          往已开的终端里打一条命令（提示符就绪后才打入；上一条还在跑时拒绝）
+  coflux terminal wait <taskId> [--timeout=<秒>] [--seq=<N>]
+                          阻塞等到当前（或第 N 条）命令结束，打印它的退出码：# finished exit=<code>；
+                          shell 自己退出则打印 # exited exit=<code>（默认超时 30 分钟）
+  coflux terminal read <taskId> [--lines=N]
+                          读终端滚动缓冲的尾部（纯文本，默认最后 200 行，可远超一屏）
+  coflux terminal send <taskId> --text="<文本>" [--enter]
                           往终端里输入文本（--enter 追加回车）。用户正在接管时会被拒
-  coflux notify "<一句话>"  叫人：工作区在侧栏转为「等待交互」并显示这句话
+  coflux terminal list   列出本工作区的终端（含 status / 退出码，跑着的还带 busy|idle 与上一条命令的退出码）
+  coflux terminal close <taskId>
+                          结束该终端（等价账号 CLI 的 stop）
+  coflux notify "<一句话>"  发送站内通知；服务器保存后确认送达
   coflux progress "<一句话>"  播报进度：显示在工作区卡片上，被下一条覆盖（不打扰用户）
   coflux ports           列出本工作区的监听端口及可直接打开的预览 URL
+  coflux executor run --prompt="<任务>" [--write] [--timeout <秒>]
+                          把一个边界清楚的子任务甩给内置的轻量 executor（由本机 Coflux.app
+                          执行），阻塞到跑完并打印它的最终回复与改动文件。一次性：没有会话、
+                          不续聊，要改就再发一次。入参只有任务描述与读写模式——模型由用户在
+                          Coflux.app 里全局配一次。默认只读；--write 才允许改文件（同一工作区
+                          同时只允许一个写任务）。它被内核级沙箱锁在本工作区目录内，**不联网**
+                          （先把依赖装好再甩），也**不会 git commit**（改动由你自己 review 提交）
+                          只有装了 Coflux.app 的这台机器能用
   coflux workspace       一行 JSON 报出「我在哪」：workspaceId（cwd 所在的有效工作区，本地命令
                           都落在它上面）、path、owningWorkspaceId（本终端此刻归属哪个工作区）、
                           moved。用 /cd 挪进另一个 coflux 工作区后用它确认目标，跨工作区操作时也传这个
                           workspaceId
+  coflux workspace enter <path>
+                          进入同仓库工作区并迁移当前终端；受管 Codex 会话记住选择供恢复/压缩使用。
+                          后续工具必须显式使用返回路径；不会改变宿主默认 cwd 或沙箱权限
   coflux workspace locate [path]
                           把本终端的**归属**搬到 path（缺省=当前目录）所属的工作区：进入/离开
                           worktree 后 coflux 跟着走，未登记的同仓库 worktree 先登记出一个子工作区。
@@ -368,11 +529,19 @@ agent 命令的环境变量：COFLUX_AGENT_TIMEOUT_MS 收窄单次请求的等
   coflux login --username <账号> --password-stdin [--server https://…]
   coflux whoami | logout
   coflux device list | project list | workspace list
+  coflux device exec <deviceId> --cmd="<命令>" [--cwd=<目录>] [--timeout=<秒>]
+                          在另一台设备上跑一条命令并拿回结果，语义同 ssh host "cmd"：命令交给远端
+                          sh -c（管道、&&、重定向、通配、$VAR 都有效），stdout 与 stderr 分开回带，
+                          最后一行是 # exit=<code>，进程退出码透传远端（本命令自己失败时为 255）。
+                          **这不是终端**：没有 PTY、不进用户侧栏、不占工作区的终端并发额度、不需要
+                          任何工作区。--cwd 默认 daemon 用户的 HOME，只接受绝对路径或 ~ 开头的路径；
+                          --timeout 默认 60 秒、最长 600 秒；没有 stdin。要输密码、驱动 TUI，或想让
+                          用户看见过程并能接管的长任务，用 coflux terminal new，不要用它
   coflux workspace new --project <id> --branch <分支> [--existing-branch]
   coflux workspace rename <id> --name <名称> | workspace remove <id>
   coflux terminal new --workspace <id> [--cmd <命令>]
-  coflux terminal read|send|wait|stop|remove <id> --remote
-  coflux terminal list [--device <id>] [--workspace <id>]
+  coflux terminal run|read|send|wait|stop|remove <id> --remote
+  coflux terminal list [--device <id>] [--workspace <id>]（跑着的终端带 busy / lastCommandExitCode，经 checkpoint 滞后 ≤2 秒）
   coflux ports --remote
   已登录的 Coflux 应用可供 CLI 直接使用；独立 CLI 可自行登录。
 `;
@@ -394,7 +563,14 @@ const { values, positionals } = parseArgs({
     cmd: { type: "string" },
     lines: { type: "string" },
     timeout: { type: "string" },
+    seq: { type: "string" },
+    // `device exec`: the working directory on the remote device (absolute, or a `~` prefix).
+    cwd: { type: "string" },
     text: { type: "string" },
+    // executor: the only free-form input is the prompt; the model is configured once in Coflux.app.
+    prompt: { type: "string" },
+    // executor: read-only by default; --write is the only mode switch.
+    write: { type: "boolean", default: false },
     enter: { type: "boolean", default: false },
     help: { type: "boolean", short: "h", default: false },
   },
@@ -406,7 +582,7 @@ if (handlesAccountCommand(positionals, values, HOME)) {
   try { await runAccountCommand(positionals, values, HOME); } catch (error) { die(error.message); }
   process.exit(0);
 }
-const handlers = { hook: cmdHook, terminal: cmdTerminal, notify: cmdNotify, progress: cmdProgress, ports: cmdPorts, workspace: cmdWorkspace };
+const handlers = { hook: cmdHook, terminal: cmdTerminal, notify: cmdNotify, progress: cmdProgress, ports: cmdPorts, executor: cmdExecutor, workspace: cmdWorkspace };
 const handler = handlers[cmd];
 if (!handler) die(`未知命令: ${cmd}\n本机宿主请使用 Coflux.app 或 cofluxd。\n\n${HELP}`);
 await handler(values);

package/cofluxd.mjs

@@ -17,7 +17,7 @@ import {
   assertReleaseVersion,
   compareReleaseVersions,
   createReleasePublicKey,
-  installStagedPair,
+  installNativeRelease,
   parseReleaseManifestEntry,
   verifyReleaseArtifact,
 } from "./release-trust.mjs";
@@ -254,7 +254,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"] : [])].map((name) => ({
+    const localArtifacts = ["coflux-supervisor", "coflux-worker", ...(fs.existsSync(join(binDir, "coflux")) ? ["coflux"] : []), ...(fs.existsSync(join(binDir, "coflux-transport")) ? ["coflux-transport"] : [])].map((name) => ({
       name,
       path: join(binDir, name),
     }));
@@ -275,7 +275,12 @@ async function ensureBinaries({ version, binDir, skipIfPresent }) {
         staged.push({ source, destination });
       }
       resignMacBinaries(staged.map(({ source }) => source));
-      installStagedPair(staged);
+      if (localArtifacts.some(artifact => artifact.name === "coflux-transport")) {
+        const source = join(stageDir, "TRANSPORT-NOTICES.txt");
+        fs.copyFileSync(join(binDir, "TRANSPORT-NOTICES.txt"), source);
+        staged.push({ source, destination: join(BIN_DIR, "TRANSPORT-NOTICES.txt") });
+      }
+      installNativeRelease(staged);
     } catch (error) {
       localFailure = error;
     } finally {
@@ -336,7 +341,7 @@ async function ensureBinaries({ version, binDir, skipIfPresent }) {
     }
     const publicKey = loadReleasePublicKey();
     const staged = [];
-    for (const component of ["supervisor", "worker", ...(manifest.cli ? ["cli"] : [])]) {
+    for (const component of ["supervisor", "worker", ...(manifest.cli ? ["cli"] : []), ...(manifest.transport ? ["transport"] : [])]) {
       const entry = parseReleaseManifestEntry(manifest, component, releaseVersion, target);
       const artifactName = `coflux-${component}-${target}`;
       process.stdout.write(`下载并验签 ${artifactName} … `);
@@ -351,18 +356,25 @@ async function ensureBinaries({ version, binDir, skipIfPresent }) {
       fs.chmodSync(source, 0o755);
       staged.push({
         source,
-        destination: component === "cli" ? join(BIN_DIR, "coflux") : component === "supervisor" ? SUP_BIN : WRK_BIN,
+        destination: component === "cli" ? join(BIN_DIR, "coflux") : component === "supervisor" ? SUP_BIN : component === "transport" ? join(BIN_DIR, "coflux-transport") : WRK_BIN,
       });
       console.log("✓");
     }
     // 两个远端产物均通过同一发布根的验签后，才允许做本地平台变换与替换。
     resignMacBinaries(staged.map(({ source }) => source));
+    if (manifest.transport) {
+      const source = join(stageDir, "TRANSPORT-NOTICES.txt");
+      const notices = await fetchBounded(`${base}/coflux-transport-NOTICES-${target}.txt`, 2 * 1024 * 1024, "native transport notices");
+      if (notices.length === 0) throw new Error("Native transport notices are empty");
+      fs.writeFileSync(source, notices, { mode: 0o644 });
+      staged.push({ source, destination: join(BIN_DIR, "TRANSPORT-NOTICES.txt") });
+    }
     // floor 先于 pair 提交：若其后进程崩溃，最多是旧二进制配更高 floor；重跑同版仍允许，
     // 但任何旧的合法 release 都不能趁窗口降级。
     if (!releaseFloor || compareReleaseVersions(releaseVersion, releaseFloor) > 0) {
       persistCliReleaseFloor(releaseVersion);
     }
-    installStagedPair(staged);
+    installNativeRelease(staged);
   } catch (error) {
     failure = error;
   } finally {

package/package.json

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

package/release-trust.mjs

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import { Buffer } from "node:buffer";
 import fs from "node:fs";
+import path from "node:path";
 
 export const WORKER_RELEASE_STATEMENT_DOMAIN = Buffer.from(
   "coflux-worker-release-v1\0",
@@ -13,6 +14,9 @@ export const SUPERVISOR_RELEASE_STATEMENT_DOMAIN = Buffer.from(
 
 export const CLI_RELEASE_STATEMENT_DOMAIN = Buffer.from("coflux-cli-release-v1\0", "utf8");
 
+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); }
+
 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;
@@ -142,7 +146,7 @@ function isRecord(value) {
  */
 export function parseReleaseManifestEntry(manifest, component, version, target) {
   assertReleaseVersion(version);
-  if (!["worker", "supervisor", "cli"].includes(component)) {
+  if (!["worker", "supervisor", "cli", "transport"].includes(component)) {
     throw new Error(`未知 release component: ${JSON.stringify(component)}`);
   }
   if (!isRecord(manifest) || manifest.schemaVersion !== 2 || manifest.version !== version) {
@@ -198,7 +202,7 @@ export function verifyReleaseArtifact({ component, version, entry, data, publicK
   const metadata = { version, target: entry.target, sha256, size: data.byteLength };
   const statement = component === "worker"
     ? workerReleaseStatement(metadata)
-    : component === "cli" ? cliReleaseStatement(metadata) : supervisorReleaseStatement(metadata);
+    : component === "cli" ? cliReleaseStatement(metadata) : component === "transport" ? transportReleaseStatement(metadata) : supervisorReleaseStatement(metadata);
   if (!crypto.verify(null, statement, publicKey, Buffer.from(entry.releaseSignature, "hex"))) {
     throw new Error(`${component} 产物 release Ed25519 签名无效`);
   }
@@ -211,11 +215,11 @@ export function verifyReleaseArtifact({ component, version, entry, data, publicK
 export function installStagedPair(staged) {
   if (
     !Array.isArray(staged) ||
-    ![2, 3].includes(staged.length) ||
+    ![2, 3, 4, 5].includes(staged.length) ||
     staged.some(({ source, destination }) =>
       typeof source !== "string" || !source || typeof destination !== "string" || !destination)
   ) {
-    throw new Error("daemon installation requires two or three valid staged artifacts");
+    throw new Error("daemon installation requires two to five valid staged artifacts");
   }
   const installed = [];
   const backups = [];
@@ -244,3 +248,48 @@ export function installStagedPair(staged) {
     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
+ * release directory, so interruption between entry-point updates cannot pair
+ * that worker 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);
+  if (staged.some(({ destination }) => path.dirname(destination) !== binDir)) throw new Error("Native release destinations must share one binary directory");
+  const digest = crypto.createHash("sha256");
+  const entries = staged.map(({ source, destination }) => ({ source, destination, name: path.basename(destination) })).sort((a, b) => a.name.localeCompare(b.name));
+  if (new Set(entries.map(entry => entry.name)).size !== entries.length) throw new Error("Duplicate native release entry point");
+  for (const entry of entries) digest.update(entry.name).update("\0").update(fs.readFileSync(entry.source));
+  const id = digest.digest("hex"), releases = path.join(binDir, "releases"), directory = path.join(releases, id);
+  fs.mkdirSync(releases, { recursive: true, mode: 0o700 });
+  const sync = name => { const fd = fs.openSync(name, "r"); try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); } };
+  if (!fs.existsSync(directory)) {
+    const temporary = fs.mkdtempSync(path.join(releases, ".staging-"));
+    try {
+      for (const entry of entries) {
+        const output = path.join(temporary, entry.name);
+        fs.copyFileSync(entry.source, output);
+        fs.chmodSync(output, entry.name.endsWith(".txt") ? 0o644 : 0o755);
+        sync(output);
+      }
+      sync(temporary); fs.renameSync(temporary, directory); sync(releases);
+    } finally { fs.rmSync(temporary, { recursive: true, force: true }); }
+  }
+  const actual = crypto.createHash("sha256");
+  for (const entry of entries) {
+    const file = path.join(directory, entry.name), stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("Invalid immutable native release member");
+    actual.update(entry.name).update("\0").update(fs.readFileSync(file));
+  }
+  if (actual.digest("hex") !== id) throw new Error("Immutable native release digest mismatch");
+  const links = fs.mkdtempSync(path.join(binDir, ".native-links-"));
+  try {
+    const entryPoints = entries.map(entry => {
+      const source = path.join(links, entry.name);
+      fs.symlinkSync(path.join(directory, entry.name), source);
+      return { source, destination: entry.destination };
+    });
+    installStagedPair(entryPoints); sync(binDir);
+  } finally { fs.rmSync(links, { recursive: true, force: true }); }
+}

package/skills/coflux/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coflux
-description: Use coflux to open visible terminals, read, wait, type, report progress, notify the user and obtain preview URLs. 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, 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,13 +14,13 @@ 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` | none (the daemon identifies you by process tree) | **the workspace your cwd is in** | open, read, wait, send, report progress, call the user, preview URLs: the default, fastest, no network dependency |
+| Local commands `coflux terminal/progress/notify/ports/executor` | 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, 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, `send`/`read`/`wait`/`notify`/`progress` complete entirely inside the
-local daemon and never touch the center; `new`/`list`/`ports` are relayed to the center by the
-daemon on your behalf (terminals must appear in the user's sidebar, preview URLs are minted by
-the center). You only ever talk to the local daemon.
+Of the local commands, `run`/`wait`/`read`/`send`/`close`/`progress`/`executor` 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.
 
 ## Managed terminal integration
 
@@ -71,10 +71,9 @@ env | grep '^COFLUX_'
 - **Effective workspace** = the workspace **your current working directory is inside**. This is what
   every local command acts on.
 
-They are the same until your cwd wanders off. A plain `cd <path>` moves a *live* session — same
-conversation, no restart — and a coflux child workspace is a normal registered git worktree, so a
-session whose terminal belongs to workspace A can end up working inside workspace B. From that
-moment, in B:
+They are the same until your cwd wanders off. A coflux child workspace is a normal registered Git
+worktree. Running a command with cwd B (or `cd <path>` inside that command) changes that command's
+effective workspace, but does not move the terminal or change later tools' default cwd. In B:
 
 - `coflux terminal new` opens the terminal **in B**, under B in the user's sidebar, running in B's
   directory, counting against B's terminal cap;
@@ -91,7 +90,40 @@ A terminal opened before the daemon was upgraded is the one case with no owning
 its local commands are refused with "predates the daemon upgrade" whatever your cwd is, because the
 daemon never guesses ownership from a directory. Open a new terminal.
 
-### coflux follows you into a git worktree
+### Explicitly enter a workspace
+
+Use this workflow when the task should move into another worktree, particularly in Codex, which
+does not provide Claude's `EnterWorktree` tool:
+
+1. Select an existing worktree from `coflux workspace list --device <deviceId>`, or create one with
+   `coflux workspace new --project <projectId> --branch <branch>`. Use the returned workspace path.
+2. Run `coflux workspace enter <path>`. This uses the existing workspace-locate operation: the
+   daemon verifies the same Git repository, registers an unknown worktree, and moves the current
+   terminal's owning workspace. The terminal, PTY and conversation continue without restarting.
+3. Use the returned absolute `path` explicitly as `workdir`/`cwd` for subsequent task commands,
+   including local `coflux` commands. Use absolute file paths for tools with no working-directory
+   argument. Read the target directory's applicable `AGENTS.md` before editing. Run `coflux workspace`
+   **in that directory** and use its workspace ID for account operations.
+
+`hostCwdChanged: false` is intentional: neither this command nor a one-off shell `cd` can change
+Codex's default directory or sandbox permissions. A successful terminal move is not proof that
+later tools operate there. Keep the selected path in task context and verify it before editing.
+Use the same enter command with the original path to return; returning does not delete a worktree.
+Temporary reads, checks or commands elsewhere do not change the explicit selection.
+
+For a device-managed Codex session, `resumeSupported: true` means the selection is saved by native
+conversation ID. Hooks inject the selected path after the switch and restore it after compaction
+or resume, including resume in another Coflux terminal of the same project and device. A new
+conversation does not inherit the selection. If the saved path is missing or cannot be verified,
+the hook reports it; do not silently resume edits in the original directory. Select a valid
+workspace explicitly, or retry after connectivity returns. Plain terminals and Claude receive
+`resumeSupported: false`; Claude's native directory tools provide its session directory behavior.
+
+The enter command requires the current native CLI. The npm CLI delegates it to the pinned native
+integration, or the installed device CLI outside a managed agent. If unavailable, update the
+device; do not claim that a shell `cd` supplied the missing persistence behavior.
+
+### Claude: coflux follows you into a git worktree
 
 `EnterWorktree` switches this live session into a git worktree (its own, or an existing one you point
 it at), `ExitWorktree` switches back, and resuming a session that had entered one puts you straight
@@ -132,133 +164,144 @@ after a `cd`? Run `coflux workspace` first** and use the `workspaceId` it prints
 
 ## When to open a terminal
 
-A coflux terminal is a process the user can see: a titled entry in their sidebar that they can
-open, take over and type into, whose output you can read back at any time.
+A coflux terminal is a real, persistent shell the user can see: a titled entry in their sidebar
+that they can open, take over and type into, whose scrollback you can read back at any time. It is
+modelled on Terminal.app's scripting surface: you open a shell, you *do script* into it, you ask
+whether it is busy, you read its contents, you close it.
+
 Whether a command runs in your own Bash or in a coflux terminal is your call; a coflux terminal is
-worth it when the user's view of the process matters:
+worth it when the user's view of the process, or the user's hands, matter:
 
-- the user may want to step in: interactive steps, confirmations, something they may need to stop
-  midway or rescue when it fails
+- **a step only the human can do**: typing a password (`ssh -t user@host "su - root -c '...'"`,
+  `sudo`), confirming a prompt, driving a TUI, picking an option in an installer
 - it keeps running and the user will want to find it later (dev server, watch mode, log tailing)
 - you want to hand the user something to look at (a test run they asked to watch, a build they are
   waiting on)
 
 **Do not use it** for quick one-shot commands (`ls`, `grep`, `git status`, reading files): your
-own tools are faster, and a pile of one-second terminals is just noise to the user.
+own tools are faster, and a pile of throwaway terminals is just noise to the user.
 
 ## Local commands
 
 ### Open a terminal
 
-There are two kinds, told apart by one single thing: **whether you pass a command**.
-
 ```sh
-coflux terminal new --title="Run unit tests" --cmd="pnpm -C tests test"   # job terminal
-coflux terminal new --title="Debug shell"                                 # session terminal
+coflux terminal new --title="Root ssh" --cmd="ssh -t user@host"   # open a shell and type the command in
+coflux terminal new --title="Debug shell"                          # open a shell, type nothing yet
 ```
 
+Every terminal is the same thing: the workspace's default login shell on a real tty (stdin **and**
+stdout), started in the directory of the workspace your cwd is in (which is not always the one this
+terminal was opened in; see "owning and effective"), alive until `exit` is typed into it or you
+`close` it. It runs nothing by itself and never exits on its own.
+
 `--title` is the name the user sees in the sidebar; **name it properly**: "Run unit tests",
-"Start dev server", never "terminal 1". Either kind runs in the directory of the workspace your cwd
-is in (which is not always the one this terminal was opened in — see "owning and effective").
-
-Always write `--cmd=<value>` and `--title=<value>` with the `=`, never separated by a space: a
-value that starts with `-` is otherwise taken for another option and the call fails outright.
-
-**Job terminal — with `--cmd=...`.** It runs that one command under the login shell (command line
-capped at 16 KB). The terminal exits when the command finishes and the task becomes `exited` with
-the exit code: that is how you tell success from failure. So do not expect to run a second command
-in the same terminal: write `a && b`, or open another one. The output is also written to a local
-log for you to read back (roughly the last 1 MB is kept). The cost is that the command's stdout is
-a pipe rather than a tty: most programs turn off colors and progress bars, full-screen programs
-(vim, htop, less) do not work at all, and a few switch to a different "CI" behavior.
-
-**Session terminal — no `--cmd` at all.** You get exactly what the user gets by clicking "new
-terminal" in the sidebar: the default login shell in the workspace directory, with stdin **and**
-stdout on a real tty. It runs nothing by itself and **never exits on its own** — it lives until
-`exit` is typed into it (by you with `send`, or by the user), or the user stops it. Reach for it
-when you need several commands in the same shell, a TUI or a program whose colors and progress
-bars matter, or simply a terminal the user can step into and keep using. There is no command log
-for it: `read` returns the current screen (one screenful, no history), so you judge how it went
-from what is on screen, and `wait` is only meaningful after you have sent `exit`.
-
-Driving a session terminal:
-
-1. `coflux terminal new --title="Debug shell"` → prints a taskId.
-2. `coflux terminal read <taskId>` until you see the shell prompt. The shell needs a moment to
-   start and the first read can come back empty — **never `send` before you have seen a prompt**.
-3. `coflux terminal send <taskId> --text="pnpm build" --enter`, then `read` again to see what
-   happened. One send per command; nothing signals you when a command finished, so read until the
-   prompt is back. To make that unambiguous, end the command with a marker of your own
-   (`pnpm build; echo DONE-$?`) and read until the marker shows up.
-4. `coflux terminal send <taskId> --text="exit" --enter` when you are done; the terminal then
-   becomes `exited` with the shell's exit code.
+"Root ssh", never "terminal 1".
+
+`--cmd=...` is *do script*: the command is typed into the shell **after the shell has signalled that
+its prompt is ready**, then the shell keeps living. It is exactly `new` followed by `run`. The
+command line is capped at 64 KB. Always write `--cmd=<value>` and `--title=<value>` with the `=`,
+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").
 
 The new terminal has the same `COFLUX_*` variables (pointing at its own task/session ids, same
 workspace as you).
 
-### See how far it got
+### Run a command in it
 
 ```sh
-coflux terminal list                      # every terminal in the workspace your cwd is in: id, state, exit code, title
-coflux terminal read <taskId>             # a terminal's content (plain text, last 200 lines by default)
-coflux terminal read <taskId> --lines 50
+coflux terminal run <taskId> --cmd="pnpm build"
 ```
 
-`list` states are `running` / `exited` / `idle`; `exited` carries `exit=<code>`.
-**An exited terminal can still be read**: "the command finished, look at the output" is the most
-common case. `read` reads the local log of a job terminal; terminals that have no log (session
-terminals, and the ones the user opened) return the current screen instead — one screenful, no
-history, and empty for the first moments after opening. Both are immediate.
+Types the command (plus Enter) into the shell and prints the command's number, `#N`. It never types
+blind: the daemon waits for the shell's prompt-ready mark first (up to ten seconds), so you do not
+have to read the screen before running. It is refused readably while a previous command is still
+running ("busy": `wait` for it or `read` the screen first), while the user is taking the terminal
+over (humans first), and on a shell coflux cannot instrument (see "Errors"; `send` is the fallback).
+One `run` = one command line; chain with `a && b` when you need several.
 
-### Wait for a command to finish
+### Wait for the command to finish
 
 ```sh
-coflux terminal wait <taskId>               # block until that terminal exits and print the exit code (default cap 30 minutes)
-coflux terminal wait <taskId> --timeout 300 # custom timeout in seconds; a timeout fails loudly with a non-zero exit
+coflux terminal wait <taskId>               # block until the current command finishes; prints its exit code
+coflux terminal wait <taskId> --timeout=300 # custom timeout in seconds (default 30 minutes)
+coflux terminal wait <taskId> --seq=2       # wait for command #2 specifically
 ```
 
-To wait for a command use `wait`; **do not write your own polling loop**. One command blocks
-until done and hands you the exit code. A timeout does not mean the command failed, only that it
-is still running: `read` to see where it is, then decide whether to keep waiting or act.
+`wait` is command-scoped, like Terminal.app's `busy`. It targets the most recently started command
+(the one the last `run` printed) unless `--seq` names another, and it cannot lose a completion: a
+command that finished before you called `wait` answers immediately with its stored exit code. The
+answer is one line:
+
+- `# finished exit=<code>`: the command ended; the terminal is still open at its prompt.
+- `# exited exit=<code>`: the shell itself ended (someone typed `exit`, or `close`); the code is the
+  shell's.
 
-`wait` **always exits 0** once the terminal is done: it reports that the command finished, not
-whether it succeeded. Read the result off its output line `# exited exit=<code>` (`list` shows the
-same). A non-zero exit from `wait` itself means the wait timed out or the id was wrong.
+Completion comes from the shell's own integration marks, so it survives the user typing into the
+running command (a password into `ssh`, `y` into a prompt), and a nested shell, `ssh` session or
+TUI counts as one long command from the outside; marks from a remote host never end it early.
 
-**Do not `wait` on a session terminal** unless you have already sent it `exit`: it never finishes
-by itself, so the wait can only end in the 30-minute timeout — a timeout there means the shell is
-still sitting at its prompt, nothing more. Its exit code, when it finally exits, is the shell's and
-not any command's: check what a command did by reading the screen.
+A timeout is a non-zero exit with a readable message, not a failure of the command: `read` to see
+where it is, then decide. `wait` on a terminal that has not run any command yet returns readably
+instead of blocking. `wait`, `read`, `list` and `close` are never refused because the user has
+taken the terminal over.
 
-**Keep working, and be woken up when it finishes.** `wait` blocks, so run it as a backgrounded Bash
-call of your own:
+**The flow for a step only the human can do:**
 
-1. `coflux terminal new --title="Run the test suite" --cmd="pnpm -C tests test"` → prints a taskId.
-2. Run `coflux terminal wait <taskId>` as a backgrounded Bash call, then go do something else.
-3. The host wakes you when that call exits. Check its output for `# exited exit=<code>`, then
-   `coflux terminal read <taskId>` to see what actually happened.
+1. `coflux terminal new --title="Root ssh" --cmd="ssh -t user@host \"su - root -c '/opt/deploy.sh'\""`
+2. `coflux notify "Please type the root password in the Root ssh terminal"`
+3. Run `coflux terminal wait <taskId>` as a backgrounded Bash call and go do something else.
+4. The host wakes you when that call exits with `# finished exit=<code>`; `coflux terminal read
+   <taskId>` shows what the remote script printed, and the terminal is still there for the user.
 
-That gets you both halves at once: the user watches (and can take over) a real terminal, and you are
-still told the moment it is over, instead of blocking or polling for it.
+**Do not write your own polling loop**: `wait` blocks and wakes the moment the command ends.
+
+### See how far it got
+
+```sh
+coflux terminal list                      # every terminal in the workspace your cwd is in
+coflux terminal read <taskId>             # the last 200 lines of the scrollback, plain text
+coflux terminal read <taskId> --lines=50
+```
+
+`list` rows are `<taskId>  <state>[ exit=<code>][ busy|idle][ last=<code>]  <title>`: `running` /
+`exited` / `idle` is the terminal, `busy` or `idle` says whether a command is running in it right
+now, and `last=<code>` is the exit code of the last command that finished. `read` returns the tail
+of the terminal's **full scrollback** (well beyond one screen, up to the daemon's history limit),
+ANSI stripped, with a `# running` / `# exited exit=<code>` header. A freshly opened terminal can
+read back empty for a moment while the shell starts. Once the shell has exited only the last
+screen the center cached remains.
 
 ### Type into a terminal
 
 ```sh
-coflux terminal send <taskId> --text "y" --enter    # type a line and press Enter
+coflux terminal send <taskId> --text="y" --enter    # type a line and press Enter
 coflux terminal send <taskId> --enter               # just press Enter
 ```
 
-For interactive confirmations (y/N, menus), or to add a command in the same shell after the
-previous one finished. Discipline:
+For interactive answers (y/N, menus, a line a program is waiting for), and the fallback way to type a
+command when `run` cannot (see "Errors"). Discipline:
 
 - **`read` before `send`**: see what the terminal is waiting for before typing; never type blind.
-  On a freshly opened session terminal this also means waiting for the shell prompt to appear.
+  On a freshly opened terminal this means waiting for the shell prompt to appear.
 - **Refused while the user is taking over**: that is not an error, it is by design; humans always
   win. Stop when refused; use `notify` to communicate, do not retry.
 - **After a send timeout do not resend right away**: `read` first to check whether the input
   actually landed; duplicated input is worse than lost input.
 - A single text is capped at 64 KB; this is an interactive input channel, not a file transfer.
 
+### Close a terminal
+
+```sh
+coflux terminal close <taskId>
+```
+
+Ends the terminal (the shell and whatever runs in it) and reports `exited exit=<code>`; the same
+effect as the account CLI's `stop`. Close the terminals you opened for a one-off step once you have
+read what you needed; leave the ones the user is meant to keep (a dev server, a shell they are using).
+
 ### Report progress
 
 ```sh
@@ -270,7 +313,7 @@ next one. Update it at milestones: reproduced, located, fixed and verifying, stu
 **does not interrupt the user**; it is a different channel from `notify`:
 
 - `progress` = broadcast (the user glances and knows the state, no response needed)
-- `notify` = call the user (the workspace turns "waiting for interaction", the user should come and look)
+- `notify` = send a persistent account notification asking the user to look or respond
 
 If unsure: when the user does not have to do anything, use `progress`.
 
@@ -280,13 +323,19 @@ If unsure: when the user does not have to do anything, use `progress`.
 coflux notify "Both approaches work; I need you to pick one"
 ```
 
-The user's sidebar switches this workspace to "waiting for interaction" and shows this sentence;
-they see it on the phone too. Use it when you are **really stuck**: a decision is needed, a
-password or a permission, a problem only a human can judge. One sentence saying what you need;
-do not write a log.
+This creates an unread notification in the account inbox, with this terminal and its owning
+workspace as the source. It works from any owned Coflux shell, even without an agent process.
+The desktop shows an in-app hint while foregrounded, including when the source workspace is
+already selected; when backgrounded it also requests a system notification. Clicking opens the
+source terminal and marks the notification read. History remains after reading, hooks, agent
+exit, or source deletion. An application that is fully quit syncs history on next launch.
 
-(Your normal questions and permission prompts already show up in the sidebar state; they need no
-extra notify. This is for "what you have to say cannot be guessed from the status icon".)
+Success means the server has saved the notification. A disconnected daemon, unsupported server,
+or timeout reports failure rather than silently falling back to workspace state. A transport retry
+of the same request is deduplicated; a separate invocation is a new notification. Keep the message
+concise (at most 2000 characters). Use this for decisions, blocked work, or review requests; use
+`progress` for updates that need no response. Automatic approval/question indicators remain
+separate and do not create inbox entries.
 
 ### Hand the user a clickable preview
 
@@ -297,16 +346,61 @@ coflux ports
 Lists every listening port in this workspace with its public preview URL. After starting a dev
 server, use it to get the URL and tell the user directly; they click it and nobody has to dig.
 
+### Hand a bounded sub-task to the executor
+
+```sh
+coflux executor run --prompt="Fix every clippy warning in crates/worker" --write
+coflux executor run --prompt="Find why the relay reconnect test flakes and report back"
+```
+
+The executor is a small agent built into coflux. Give it one self-contained job and it works in
+**the workspace your cwd is in** while you keep your own context for the main thread. The command
+blocks until the job ends, then prints the executor's final report and the files it changed.
+
+Reach for it when a job is mechanical, bounded and verbose — chasing a failing test suite, a
+repetitive refactor across many files, a search that would cost you many tool calls. Keep the work
+yourself when it needs the conversation's context, the user's judgment, or decisions the prompt
+cannot carry.
+
+**One-shot: there is no session and no follow-up.** Each run starts clean and ends when it ends;
+to change something, send a new run with a new prompt. So **write the prompt as a brief, not a
+hint**: the executor gets that one string and nothing else — no conversation history, no way to ask
+you what you meant. Say what done looks like and how to check it.
+
+Its boundaries, enforced by a kernel sandbox — count on them, and tell it what it needs up front:
+
+- **Only the originating workspace is writable.** Writes anywhere outside it are refused by the
+  kernel. Reads are not restricted, so it can still see system files, toolchains and the rest of the
+  machine — the sandbox stops it from changing things, not from looking. Without `--write` even that
+  workspace is read-only, which is the right mode for investigations.
+- **Git metadata is read-only, so it never commits.** It leaves changes in the working tree;
+  reviewing and committing them is yours. `git status` and `git diff` work fine for it.
+- **Its tool processes have no network.** `npm install`, `cargo fetch` and friends fail. Install
+  what the job needs before handing it over.
+- **One writing executor per workspace at a time.** A second `--write` in the same workspace is
+  refused outright rather than queued; read-only runs may go in parallel up to a small cap.
+
+It runs inside the user's desktop app, so it only exists on the machine that app is on, and a run
+ends if the user quits the app, signs out, or stops the machine's terminals (you get a definite
+failure, never a hang). `--timeout <seconds>` caps how long you wait; the default is 30 minutes and
+a timeout cancels the run before failing. The model comes from the user's desktop settings; if they
+have not configured one, the command says so in one line — relay that to the user instead of
+retrying.
+
 ### Errors from local commands
 
 Errors are one readable sentence; 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" =
-that terminal was opened before the daemon upgrade, open a new one; a `new` without `--cmd` refused for a missing command = this machine's daemon is older
-than session terminals, tell the user to run `cofluxd update && cofluxd restart` (or pass a command
-and use a job terminal); "daemon is not connected to the center" only appears on
-`new`/`list`/`ports`, retry once it reconnects.
+that terminal was opened before the daemon upgrade, open a new one; "never signalled prompt
+readiness" = this terminal's shell is not zsh, bash or fish started through coflux's rc chain (or
+the integration was bypassed), so the command was **not** typed and `wait` cannot observe commands
+there: the terminal is open all the same, use `read` and `send` with it; "busy" = a command is
+still running in that terminal, `wait` for it or `read` first; "unknown action terminal.run" = this
+machine's daemon is older than the CLI, tell the user to run `cofluxd update && cofluxd restart`
+(the terminal was opened as a plain shell, nothing was run); "daemon is not connected to the
+center" only appears on `new`/`list`/`ports`/`notify`, retry once it reconnects.
 
 ## Account CLI: across workspaces and devices
 
@@ -316,10 +410,12 @@ never as a command argument. Account commands return JSON. A workspace ID identi
 
 ```sh
 coflux device list
+coflux device exec <deviceId> --cmd="<command>" [--cwd=<dir>] [--timeout=<seconds>]
 coflux project list --device <deviceId>
 coflux workspace list --device <deviceId>
 coflux workspace new --project <projectId> --branch <branch>
 coflux terminal new --workspace <workspaceId> --title <title> [--cmd <command>]
+coflux terminal run <terminalId> --remote --cmd <command>
 coflux terminal list --workspace <workspaceId>
 coflux terminal read <terminalId> --remote
 coflux terminal send <terminalId> --remote --text <text> [--enter]
@@ -331,24 +427,65 @@ coflux workspace remove <workspaceId>
 coflux ports --remote --device <deviceId>
 ```
 
-`--remote` selects account access, including other workspaces on this machine. Read before sending;
-stop immediately when the user takes over. If a write times out, inspect the result before retrying.
-Exiting the CLI does not stop its terminals. Delete workspaces through `coflux workspace remove`
-so the filesystem and workspace records stay consistent.
+`--remote` selects account access, including other workspaces on this machine. The semantics are the
+same as the local commands: `--cmd` and `run` type a command in after the prompt is ready, `wait`
+returns `finished` with the command's exit code (or `exited` with the shell's) and `timedOut` on the
+deadline, `list` shows `busy` and `lastCommandExitCode` for live terminals (fed by the device's
+checkpoints, so this view lags a couple of seconds behind reality; the local `coflux terminal list`
+is immediate), and `stop` is `close`.
+Read before sending; stop immediately when the user takes over. If a write times out, inspect the
+result before retrying. Exiting the CLI does not stop its terminals. Delete workspaces through
+`coflux workspace remove` so the filesystem and workspace records stay consistent.
+
+### Run one command on another machine
+
+```sh
+coflux device exec <deviceId> --cmd="cd /opt/app && git rev-parse HEAD"
+coflux device exec <deviceId> --cmd="systemctl is-active caddy" --cwd=/etc --timeout=10
+```
+
+This is `ssh host "cmd"` for the devices in this account, and it is **not a Terminal**: no PTY on
+the device, nothing in the user's sidebar, no draw on any workspace's terminal cap, and no workspace
+required — a device whose directories were never registered as coflux workspaces is still reachable.
+The command string is handed to the remote `sh -c`, so pipes, `&&`, redirection, globs and `$VAR` all
+work, and quoting is yours to get right.
+
+Its output is not JSON: stdout goes to stdout, stderr goes to stderr (always separate, and each one
+carries an explicit marker if it had to be truncated), and the last line is `# exit=<code>`. **The
+CLI's exit code is the remote command's**, so an ordinary shell test around it works. The CLI's own
+failures — device offline, 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".
+
+`--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>`.
+There is no `--workspace`, and there is **no stdin**.
+
+**`device exec` or a terminal?** A division of labour, not a limitation:
+
+- **`device exec`** when the command is short and what you want is its result: a version check, a
+  config grep, a service status, a one-line remote fix. `--timeout` defaults to 60 seconds and is
+  capped at 600; a timeout kills the remote process and is a definite failure, never a partial
+  answer. Output is buffered, so nothing appears until the command ends.
+- **`coflux terminal new --workspace <workspaceId>`** when the job is long, when the user should be
+  able to watch it and take it over, or when a human has to type something into it (a `sudo`
+  password, a confirmation, a TUI). That is what a Terminal is for, and exec deliberately cannot do
+  it.
 
 ## Boundaries
 
-- You can open, read, wait and type, but **typing is a restricted write with humans first**: you
-  cannot write into a terminal the user is taking over (you are refused explicitly), and the user
-  taking over at any time displaces you. Do not fight a human for a terminal.
+- You can open, run, wait, read, type and close, but **typing is a restricted write with humans
+  first**: neither `run` nor `send` can write into a terminal the user is taking over (you are
+  refused explicitly), and the user taking over at any time displaces you. Do not fight a human for
+  a terminal; `wait` and `read` keep working while they have it.
 - Local commands only see **the workspace your cwd is in** (`coflux workspace` says which one);
   use the account CLI for other workspaces and machines in the same account.
 - A workspace has a cap on concurrently live terminals (default 8, including the user's own).
   On hitting the cap, `list` first: usually some finished terminals were never collected. If the
   user really filled it up, `notify` them instead of forcing it.
-- `new`/`list`/`ports` and account commands need the daemon connected to the center; "letting the
-  user see" is their whole point. `send`/`read`/`wait`/`notify`/`progress` do not depend on the
-  center. When disconnected they fail loudly rather than degrade silently.
+- `new`/`list`/`ports`/`notify` and account commands need the daemon connected to the center; "letting the
+  user see" is their whole point. `run`/`wait`/`read`/`send`/`close`/`progress` do not
+  depend on the center. When disconnected they fail loudly rather than degrade silently.
 - `COFLUX_*` variables exist only in PTYs opened by coflux; exporting or changing them yourself
   has no effect, the center only trusts the ids it issued. `COFLUX_WORKSPACE_ID` always means the
   workspace this terminal was **opened** in and goes stale the moment coflux follows you into a