cofluxd 0.13.0 → 0.15.0

package/README.md

@@ -34,16 +34,22 @@ CLI 还会取自身与 worker 的持久 release floor 较大值拒绝远端降
 跑在 coflux 终端里的 claude/codex 可以用下面几条，把工作外化成用户在 web/手机上**看得见、能接管**的东西——而不是在自己的 Bash 里后台起一个谁也看不见的进程：
 
 ```sh
-cofluxd terminal new --title "跑单测" --cmd "pnpm test"   # 开真实终端，用户可接管
+cofluxd terminal new --title "跑单测" --cmd "pnpm test"   # 作业终端：跑完即退，带退出码
+cofluxd terminal new --title "调试 shell"                 # 会话终端：不带命令 = 常驻登录 shell
 cofluxd terminal list                                     # 本工作区的终端 + 状态/退出码
 cofluxd terminal read <taskId> [--lines N]                # 读终端内容（纯文本，已退出也能读）
+cofluxd terminal wait <taskId> [--timeout <秒>]           # 阻塞到退出，打印退出码
+cofluxd terminal send <taskId> --text "y" --enter         # 往终端输入；用户正在接管时被拒
+cofluxd progress "复现了，正在定位"                        # 播报进度：显示在工作区卡片上
 cofluxd notify "需要你定一下用哪个方案"                    # 叫人：侧栏转「等待交互」
 cofluxd ports                                             # 端口 + 可直接打开的预览 URL
 ```
 
-不需要任何凭证：daemon 用调用方 pid 反查进程树确认它属于哪个会话，**coflux 会话之外的进程一律拒绝**，权限也天然限定在该会话所属的工作区内。
+`terminal new` 带不带 `--cmd` 是两种终端：带命令是**作业终端**，命令包成脚本交登录 shell 跑，跑完终端退出并带退出码，输出另落一份日志供 `read` 回读（代价是命令的 stdout 是管道而非 tty，颜色/进度条/全屏程序都没有）；不带命令是**会话终端**，等价于用户在侧栏点「新建终端」——工作区目录下的默认登录 shell，stdin/stdout 都是真 tty，不会自己退出，直到 agent 或用户输入 `exit`。会话终端没有命令日志，`read` 读的是当前画面（一屏），首次 `send` 前要先 `read` 等提示符。
 
-每个 coflux 开出来的 PTY 会话里还注入了一组 `COFLUX_*` 环境变量（由 supervisor 组装，中心只下发 id）：`COFLUX_DEVICE_ID` / `COFLUX_PROJECT_ID`（目录工作区为空串）/ `COFLUX_WORKSPACE_ID` / `COFLUX_TASK_ID` / `COFLUX_SESSION_ID` / `COFLUX_MCP_URL`。agent 读它们就知道自己在哪台设备、哪个项目/工作区/终端，值与中心 MCP `list_*` 返回的 id 完全一致，可直接传给 MCP tools。本地命令与 MCP 的分工：本工作区内的开终端/读/等/输入/播报/叫人/端口用上面的零凭证命令；开子工作区、跨工作区/跨设备读写、或从 coflux 之外接入，用中心的 `coflux` MCP（`claude mcp add --transport http coflux "$COFLUX_MCP_URL"`，一次 OAuth 授权）。supervisor 不走热升级，旧机器要 `cofluxd update && cofluxd restart` 之后会话里才有这些变量；skill 里写了变量为空时的降级分支。
+不需要任何凭证：daemon 用调用方 pid 反查进程树确认它属于哪个会话，**coflux 会话之外的进程一律拒绝**，权限也天然限定在该会话所属的工作区内。**local-first**：send/read/wait/notify/progress 在 daemon 本地闭环、不经中心（归属与退出码来自 daemon 自己的会话账本，内容来自本地命令日志或 sessiond 快照）；只有 new/list/ports 由 daemon 代问中心——Task 要落库广播、预览 URL 由中心生成。早于 daemon 升级开出来的终端缺归属信息，本地命令会明确拒绝，重开即可。
+
+每个 coflux 开出来的 PTY 会话里还注入了一组 `COFLUX_*` 环境变量（由 supervisor 组装，中心只下发 id）：`COFLUX_DEVICE_ID` / `COFLUX_PROJECT_ID`（目录工作区为空串）/ `COFLUX_WORKSPACE_ID` / `COFLUX_TASK_ID` / `COFLUX_SESSION_ID` / `COFLUX_MCP_URL`。agent 读它们就知道自己在哪台设备、哪个项目/工作区/终端，值与中心 MCP `list_*` 返回的 id 完全一致，可直接传给 MCP tools。本地命令与 MCP 的分工只有一条规则：**本地能闭环的一律本地命令**（本工作区内的开终端/读/等/输入/播报/叫人/端口）；只有跨出本工作区——开子工作区、跨工作区/跨设备读写、或从 coflux 之外接入——才用中心的 `coflux` MCP（`claude mcp add --transport http coflux "$COFLUX_MCP_URL"`，一次 OAuth 授权）。supervisor 不走热升级，旧机器要 `cofluxd update && cofluxd restart` 之后会话里才有这些变量；skill 里写了变量为空时的降级分支。
 
 配套的 skill 在 `skills/coflux/SKILL.md`（随包分发），装给 Claude Code：
 

package/cofluxd.mjs

@@ -943,17 +943,41 @@ 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 除外，它们挂在本会话上，与工作区无关）。
 // 与 `hook` 子命令的约定**相反**：这些命令必须写 stdout——输出就是给 agent 读的返回值。
 // 也刻意不做自动重试：terminal new 有副作用，重试会开出两个终端，失败就把错误交给 agent。
 
 const AGENT_TIMEOUT_MS = 30_000;
+/** 调用方能收窄单次 `/agent` 等待的下限；再低就只够覆盖 node 自己的启动，等于必然超时。 */
+const MIN_AGENT_TIMEOUT_MS = 200;
 const DEFAULT_READ_LINES = 200;
-// wait 的循环必须在 CLI 侧：单次 agentPost 撑不起长等待（daemon 控制 WS 有自己的往返超时）。
-// 默认 30 分钟——编码任务常跑很久；轮询走 terminal.list（status 来自 sessionExit 事件链，
-// 不受快照 ~2s 延迟影响），3 秒一次对本机 loopback 是零负担。
+// wait 的循环必须在 CLI 侧：单次 agentPost 有 25 秒的 loopback 应答上限。默认 30 分钟——编码任务
+// 常跑很久；轮询走 terminal.status（daemon 本地账本直接答，不经中心），3 秒一次对本机 loopback
+// 是零负担。
 const DEFAULT_WAIT_TIMEOUT_S = 1800;
 const WAIT_POLL_MS = 3000;
 
+// 每条请求都带调用方 cwd（plan 102）：agent 可以经 `/cd` 或 EnterWorktree 把活着的会话挪进同
+// 设备的另一个 coflux 工作区，daemon 据此把本次请求的**目标**解析到 cwd 所在的工作区（会话的
+// 归属工作区不变）。目录被删掉时 process.cwd() 会抛，按"报不出来"处理，daemon 退回归属工作区。
+function callerCwd() {
+  try { return process.cwd(); } catch { return ""; }
+}
+
+// 调用方可以用 COFLUX_AGENT_TIMEOUT_MS 收窄单次请求的等待上限（plan 104）。默认 30 秒是为
+// agent 定的——它等得起；hook 脚本等不起：宿主按秒杀 hook（SessionStart 只给几秒），而经中心的
+// 动作最坏要等 daemon 的 20 秒中心超时。被宿主杀在半路比拿不到答案坏得多（连坐标块都印不出来），
+// 所以这类调用方自报一个更小的预算，到点干净失败、让脚本走回退。
+// 只允许收窄不允许放宽：上限仍是 AGENT_TIMEOUT_MS，畸形值一律按默认处理。
+function agentTimeoutMs() {
+  const raw = Number(process.env.COFLUX_AGENT_TIMEOUT_MS);
+  if (!Number.isFinite(raw) || raw <= 0) return AGENT_TIMEOUT_MS;
+  return Math.min(Math.max(Math.floor(raw), MIN_AGENT_TIMEOUT_MS), AGENT_TIMEOUT_MS);
+}
+
 async function agentPost(body) {
   const portResult = localGatewayPort();
   if (!portResult.ok) die(portResult.error);
@@ -962,8 +986,8 @@ async function agentPost(body) {
     res = await fetch(`http://127.0.0.1:${portResult.port}/agent`, {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ ...body, pid: process.pid, ppid: process.ppid }),
-      signal: AbortSignal.timeout(AGENT_TIMEOUT_MS),
+      body: JSON.stringify({ ...body, pid: process.pid, ppid: process.ppid, cwd: callerCwd() }),
+      signal: AbortSignal.timeout(agentTimeoutMs()),
     });
   } catch (error) {
     die(`连不上本机 daemon：${error?.message || error}（daemon 没在跑？先看 cofluxd status）`);
@@ -994,11 +1018,20 @@ function tailLines(text, n) {
 async function cmdTerminal(values) {
   const sub = positionals[1];
   if (sub === "new") {
-    const command = values.cmd;
-    if (!command) die(`terminal new 需要 --cmd "<命令>"`);
+    // 两种终端只看「命令是否为空」（plan 101）：--cmd 缺省与 --cmd= 空白等价，都开会话终端
+    // ——工作区目录下的默认登录 shell，stdin/stdout 都是真 tty，不自动退出。带命令的仍是作业
+    // 终端：命令跑完终端退出并带退出码，语义一字不变。空白在这里统一收敛成空串，好让中心的
+    // 「默认标题取命令首行」落到它自己的兜底。
+    const command = (values.cmd ?? "").trim() ? values.cmd : "";
     const result = await agentPost({ action: "terminal.new", title: values.title || "", command });
     console.log(`已开终端 ${result.taskId}（用户可在 coflux 侧栏看到并随时接管）`);
-    console.log(`看输出：cofluxd terminal read ${result.taskId}`);
+    if (command) {
+      console.log(`看输出：cofluxd terminal read ${result.taskId}`);
+    } else {
+      console.log(`会话终端：常驻的登录 shell（全 tty），不会自己退出`);
+      console.log(`先等提示符：cofluxd terminal read ${result.taskId}`);
+      console.log(`再输命令：cofluxd terminal send ${result.taskId} --text "<命令>" --enter（送 exit 才结束）`);
+    }
   } else if (sub === "list") {
     const { terminals } = await agentPost({ action: "terminal.list" });
     if (!terminals.length) return void console.log("本工作区暂无终端");
@@ -1030,9 +1063,8 @@ async function cmdTerminal(values) {
     const timeoutSec = Number.isFinite(requested) && requested > 0 ? requested : DEFAULT_WAIT_TIMEOUT_S;
     const deadline = Date.now() + timeoutSec * 1000;
     for (;;) {
-      const { terminals } = await agentPost({ action: "terminal.list" });
-      const t = terminals.find((x) => x.taskId === taskId);
-      if (!t) die(`本工作区没有终端 ${taskId}（用 cofluxd terminal list 查）`);
+      // 按 taskId 直接问本地账本；目标不存在/不在本工作区时 daemon 回可读错误，agentPost 直接 die。
+      const t = await agentPost({ action: "terminal.status", taskId });
       if (t.status === "exited") {
         const exit = t.exitCode === undefined || t.exitCode === null ? "" : ` exit=${t.exitCode}`;
         return void console.log(`# exited${exit}`);
@@ -1061,6 +1093,55 @@ async function cmdProgress() {
   console.log("已更新进度（显示在工作区卡片上，被下一条覆盖）");
 }
 
+// 「我在哪」与「跟着我搬」（plan 102 / 103）。三条都打一行 JSON，字段稳定——插件脚本按它比对，
+// agent 也直接读。
+//
+//   cofluxd workspace                 只读：cwd 所在的有效工作区 + 本终端的归属工作区
+//   cofluxd workspace locate [path]   把本终端的**归属**搬到 path 所属的工作区（未登记先登记）
+//   cofluxd workspace forget <path>   该 worktree 已被删掉：其下终端搬回主工作区、记录消失
+//
+// locate/forget 是插件在 SessionStart / PostToolUse(EnterWorktree|ExitWorktree) / WorktreeRemove
+// 上调的，同样零凭证（daemon 按进程树认身份）。daemon 旧到不认识这两个动作时它会回
+// 「未知 action …」，agentPost 原样报错并非零退出——脚本据此静默放弃，不干扰会话。
+async function cmdWorkspace() {
+  const sub = positionals[1];
+  if (!sub) {
+    const result = await agentPost({ action: "workspace.current" });
+    return void console.log(JSON.stringify({
+      workspaceId: result.workspaceId,
+      path: result.path,
+      owningWorkspaceId: result.owningWorkspaceId,
+      moved: Boolean(result.moved),
+    }));
+  }
+  if (sub === "locate") {
+    // 路径缺省取调用方 cwd；插件脚本一律显式传 hook 载荷里的 cwd（hook 在会话当前目录执行，
+    // 与载荷里的 cwd 未必相同）。
+    const path = positionals[2] || callerCwd();
+    if (!path) die("workspace locate 需要 <path>（取不到当前目录）");
+    const result = await agentPost({ action: "workspace.locate", path });
+    return void console.log(JSON.stringify({
+      workspaceId: result.workspaceId,
+      path: result.path,
+      branch: result.branch,
+      created: Boolean(result.created),
+      moved: Boolean(result.moved),
+    }));
+  }
+  if (sub === "forget") {
+    const path = positionals[2];
+    if (!path) die("workspace forget 需要 <path>（被删掉的 worktree 目录）");
+    const result = await agentPost({ action: "workspace.forget", path });
+    return void console.log(JSON.stringify({
+      workspaceId: result.workspaceId,
+      fallbackWorkspaceId: result.fallbackWorkspaceId,
+      movedTerminals: result.movedTerminals ?? 0,
+      removed: Boolean(result.removed),
+    }));
+  }
+  die(`workspace 的子命令只有 locate | forget（不带子命令 = 报出我在哪）`);
+}
+
 async function cmdPorts() {
   const { ports } = await agentPost({ action: "ports" });
   if (!ports.length) return void console.log("本工作区暂无监听端口");
@@ -1084,8 +1165,12 @@ const HELP = `cofluxd —— coflux daemon 管理
 
   以下几条供**跑在 coflux 终端里的 agent** 调用，把工作变成用户看得见、能接管的东西：
 
-  cofluxd terminal new --cmd "<命令>" [--title "<标题>"]
-                          开一个真实终端跑命令，用户在 coflux 侧栏能看到并随时接管
+  cofluxd terminal new [--cmd "<命令>"] [--title "<标题>"]
+                          开一个真实终端，用户在 coflux 侧栏能看到并随时接管
+                          带 --cmd = 作业终端：命令在登录 shell 里跑完即退出并带退出码，输出另
+                          落一份日志供 read 回读（代价：stdout 是管道，不是 tty）
+                          不带 --cmd = 会话终端：工作区目录下的常驻登录 shell，stdin/stdout 都是
+                          真 tty（能跑 vim/htop、有颜色），先 read 等提示符再 send，送 exit 才结束
   cofluxd terminal list   列出本工作区的终端（含 status / 退出码）
   cofluxd terminal read <taskId> [--lines N]
                           读某个终端的内容（纯文本，默认最后 200 行；终端已退出也能读）
@@ -1096,6 +1181,20 @@ const HELP = `cofluxd —— coflux daemon 管理
   cofluxd notify "<一句话>"  叫人：工作区在侧栏转为「等待交互」并显示这句话
   cofluxd progress "<一句话>"  播报进度：显示在工作区卡片上，被下一条覆盖（不打扰用户）
   cofluxd ports           列出本工作区的监听端口及可直接打开的预览 URL
+  cofluxd workspace       一行 JSON 报出「我在哪」：workspaceId（cwd 所在的有效工作区，本地命令
+                          都落在它上面）、path、owningWorkspaceId（本终端此刻归属哪个工作区）、
+                          moved。用 /cd 挪进另一个 coflux 工作区后用它确认目标，调 MCP 时也传这个
+                          workspaceId
+  cofluxd workspace locate [path]
+                          把本终端的**归属**搬到 path（缺省=当前目录）所属的工作区：进入/离开
+                          worktree 后 coflux 跟着走，未登记的同仓库 worktree 先登记出一个子工作区。
+                          插件自动调，一般不用手敲
+  cofluxd workspace forget <path>
+                          该 worktree 已被删掉：其下所有终端搬回项目主工作区、工作区记录消失
+                          （不执行 git worktree remove）
+
+agent 命令的环境变量：COFLUX_AGENT_TIMEOUT_MS 收窄单次请求的等待上限（默认 30000，只能调小），
+供有硬超时的 hook 脚本用——到点干净失败，好过被宿主杀在半路。
 
 up flags: --server <ws://.../daemon>  --name <名>  --shell <路径>
 通用: --version <vX|latest>(不传时 up 沿用已有二进制，update 默认 latest)  --bin-dir <dir>(用本地 cargo 产物)  --no-start
@@ -1133,7 +1232,7 @@ let cmd = positionals[0];
 if (values.help || cmd === "help") { console.log(HELP); process.exit(0); }
 if (!cmd) cmd = fs.existsSync(SETTINGS) ? "status" : "up"; // 首次裸跑 → 引导
 
-const handlers = { up: cmdUp, update: cmdUpdate, restart: cmdRestart, down: cmdDown, status: cmdStatus, doctor: cmdDoctor, fda: cmdFda, logs: cmdLogs, uninstall: cmdUninstall, hook: cmdHook, terminal: cmdTerminal, notify: cmdNotify, progress: cmdProgress, ports: cmdPorts };
+const handlers = { up: cmdUp, update: cmdUpdate, restart: cmdRestart, down: cmdDown, status: cmdStatus, doctor: cmdDoctor, fda: cmdFda, logs: cmdLogs, uninstall: cmdUninstall, hook: cmdHook, terminal: cmdTerminal, notify: cmdNotify, progress: cmdProgress, ports: cmdPorts, workspace: cmdWorkspace };
 const h = handlers[cmd];
 if (!h) die(`未知命令: ${cmd}${MIGRATED[cmd] ? `\n${MIGRATED[cmd]}` : ""}\n\n${HELP}`);
 await h(values);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cofluxd",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "coflux daemon 管理 CLI：装/起/停/升级 Rust daemon（supervisor + worker）",
   "type": "module",
   "bin": {

package/skills/coflux/SKILL.md

@@ -1,222 +1,370 @@
 ---
 name: coflux
-description: 当你运行在 coflux 终端里时，把长任务、并行工作和求助外化成用户在 coflux web/手机上看得见、能随时接管的真实终端；读 COFLUX_* 环境变量知道自己在哪台设备/项目/工作区/终端，本工作区内用本地 cofluxd 命令，开子工作区或跨工作区/跨设备操作用中心的 coflux MCP。适用于跑测试/构建/dev server 等耗时命令、需要用户接管或决策、想给用户一个可点开的预览 URL、要在隔离的子工作区并行干活的场景。
+description: When you run inside a coflux terminal, this skill documents the local cofluxd commands that open terminals the user can watch and take over from the coflux web/mobile app, report progress, call the user and hand out preview URLs, plus the center MCP for reaching other workspaces and devices. Your coordinates (device / project / workspace / terminal) arrive in a <coflux-session> block at session start, or via the COFLUX_* environment variables. For the workspace your cwd is in always use the zero-credential local cofluxd commands (open, read, wait, send, report progress, call the user, get preview URLs); use the center's coflux MCP only to reach beyond it (child workspaces, other workspaces or devices). Use when the user should be able to watch, step into or stop a command (interactive steps, dev servers, a job they are waiting on), when the user has to decide something, when you want to hand the user a clickable preview URL, or when you need an isolated child workspace for parallel work.
 ---
 
-# 在 coflux 里工作
+# Working inside coflux
 
-你可能正跑在 coflux 的一个终端里。coflux 让用户在浏览器和手机上盯着各台机器上的
-agent 干活，随时接管。这个 skill 让你把自己的工作**变成用户看得见的东西**，并在需要时
-操作账号下的其它工作区和设备。
+You may be running inside a coflux terminal. coflux lets the user watch agents working on many
+machines from a browser or a phone and take over at any time. This skill gives you terminals the
+user can see and take over, a progress line and a call button on the workspace card, preview URLs,
+and a way to operate the other workspaces and devices under the account when you need to.
 
-有两条轨道，分工固定：
+Two tracks, one rule: **whatever closes locally uses local commands; only reaching beyond the
+workspace you are in goes through MCP.**
 
-| 轨道 | 凭证 | 能触达的范围 | 用在 |
+| Track | Credentials | Reach | Use for |
 |---|---|---|---|
-| 本地命令 `cofluxd terminal/progress/notify/ports` | 零凭证（daemon 按你的进程树认身份） | 只有**你所在的工作区** | 本工作区内开终端、读、等、输入、播报、叫人、拿预览 URL——最省事的路径 |
-| 中心 MCP `coflux`（14 个 tools） | 用户在宿主里做一次 OAuth 授权 | **整个账号**：所有设备、项目、工作区、终端 | 开子工作区（git worktree）、跨工作区/跨设备读写、从 coflux 之外接入 |
+| Local commands `cofluxd 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 |
+| Center MCP `coflux` | one OAuth authorization by the user in the host | **the whole account**: every device, project, workspace and terminal | child workspaces (git worktrees), cross-workspace / cross-device access, joining from outside coflux |
 
-## 先判断自己在哪
+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.
 
-先看环境变量：
+## Figure out where you are first
+
+With the coflux plugin installed, Claude Code and Codex receive a `<coflux-session>` block at
+session start (and again after context compaction). Your coordinates are in it; use them
+directly. Without that block (no plugin, hand-wired hooks, hook not trusted yet), read the
+environment:
 
 ```sh
 env | grep '^COFLUX_'
 ```
 
-- **`COFLUX_WORKSPACE_ID` 非空** → 你在 coflux 终端里，且 daemon 已是新版。下面的变量就是
-  你的坐标，MCP tools 要的 id 直接从这里拿，不用去 `list_*` 里猜：
+- **`COFLUX_WORKSPACE_ID` is non-empty** (or the `<coflux-session>` block is present) → you are in
+  a coflux terminal with an up-to-date daemon. The variables below are your coordinates; pass
+  these ids to MCP tools directly instead of guessing from `list_*`:
 
-  | 变量 | 含义 |
+  | Variable | Meaning |
   |---|---|
-  | `COFLUX_DEVICE_ID` | 你所在机器的设备 id（`list_devices` 的 id） |
-  | `COFLUX_PROJECT_ID` | 所属项目 id；无仓库的目录工作区为空串 |
-  | `COFLUX_WORKSPACE_ID` | 所属工作区 id（`list_workspaces` 的 id） |
-  | `COFLUX_TASK_ID` | 你这个终端的 id（`list_terminals` / `read_terminal` 用的 terminalId） |
-  | `COFLUX_SESSION_ID` | 你这个 PTY 会话 id |
-  | `COFLUX_MCP_URL` | 中心 MCP 地址，用户配 MCP 时就用它 |
+  | `COFLUX_DEVICE_ID` | id of the device you run on (the id in `list_devices`) |
+  | `COFLUX_PROJECT_ID` | owning project id; empty string for a directory workspace without a repository |
+  | `COFLUX_WORKSPACE_ID` | the workspace this terminal was **opened** in (the id in `list_workspaces`). The variable is frozen when the terminal starts; the workspace the terminal *belongs to* can still change — see below. `cofluxd workspace` is the authority |
+  | `COFLUX_TASK_ID` | id of this terminal (the taskId / terminalId used by local commands and `read_terminal`) |
+  | `COFLUX_SESSION_ID` | id of this PTY session |
+  | `COFLUX_MCP_URL` | the center's MCP URL; the user configures MCP with it |
+
+- **Variables empty or absent** → treat yourself as outside coflux: forget this skill and use your
+  own tools as usual (if the user configured the coflux MCP in the host, the MCP tools still work;
+  you just have no "where am I" coordinates). If the user insists you are inside a coflux terminal,
+  this machine's daemon has not been upgraded: tell the user to run `cofluxd update && cofluxd restart`;
+  after reopening the terminal the variables and the local commands are there.
+
+### Two workspaces to keep apart: owning and effective
+
+- **Owning workspace** = the workspace this terminal **belongs to**: what the user's sidebar shows it
+  under, what its turn state, branch and diff stats are attributed to. It starts out as
+  `COFLUX_WORKSPACE_ID` and moves with you when you enter or leave a git worktree (below).
+- **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:
+
+- `cofluxd 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;
+- `cofluxd terminal list` lists B's terminals, and A's terminals answer `read` / `wait` / `send`
+  with "not in this workspace or does not exist" (`cd` back to A to reach them again);
+- MCP calls need **B's** id as `workspaceId`;
+- the terminal itself stays under A, and `progress`, `notify` and `ports` still belong to it,
+  whatever your cwd is; `COFLUX_TASK_ID` and `COFLUX_SESSION_ID` never change.
+
+If your cwd is outside every coflux workspace (say `/tmp`), local commands fall back to the owning
+workspace.
+
+A terminal opened before the daemon was upgraded is the one case with no owning workspace at all:
+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
+
+`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
+back in it. **coflux comes along**: the terminal's *owning* workspace moves to the workspace that
+worktree is, and if coflux has never seen that worktree it registers it as a child workspace of this
+project first — a new card appears in the user's sidebar, with its branch and diff stats. Nothing is
+interrupted: same terminal, same PTY, same conversation, and the user keeps watching it where it now
+lives. When Claude Code cleans up its own worktree on exit, that workspace's terminals move back to
+the project's main workspace and the record disappears by itself.
+
+So, after entering or leaving a worktree, owning **and** effective are both the new workspace: pass
+its id to MCP tools and everything local already acts on it. The plugin drops the new id next to the
+tool result, and `cofluxd workspace` always tells you. Two things stay behind on purpose:
+
+- `COFLUX_WORKSPACE_ID` (and the id in the `<coflux-session>` block from earlier in this session)
+  still names where the terminal was *opened*; it is frozen when the PTY starts and cannot be
+  rewritten. Never reuse it after a move.
+- The shell inside this terminal keeps its own directory. That is only about the shell; it does not
+  affect where your work is attributed.
+
+Nothing happens when coflux cannot follow, and nothing is blocked either: another repository, a
+directory that is not a git repository, a terminal opened in a directory workspace (no project), or
+a daemon that is down or too old — the session just carries on with the ownership it had.
+
+### Ask where you are
 
-- **变量为空或不存在** → 跑一条 `cofluxd terminal list`：
-  - 返回「不在 coflux 终端里」→ 你不在 coflux 里，忘掉这个 skill，照常用你自己的工具
-    （除非用户已经在宿主里配了 coflux MCP，那时 MCP tools 照用，只是没有「我在哪」的坐标）。
-  - 能列出终端 → 你在 coflux 里，但 daemon 还没升级到注入环境变量的版本：本地命令全部可用，
-    只是你不知道自己的 id；要用 MCP 就先 `list_devices` / `list_workspaces` 按路径对一下
-    `pwd`，并顺手告诉用户 `cofluxd update && cofluxd restart` 之后就有环境变量了。
+```sh
+cofluxd workspace
+{"workspaceId":"ws-b","path":"/Users/me/.coflux/worktrees/ws-b","owningWorkspaceId":"ws-a","moved":true}
+```
 
-## 什么时候用本地命令
+One line of JSON: `workspaceId` (+ `path`) is the **effective** workspace, `owningWorkspaceId` is the
+workspace this terminal belongs to right now, and `moved` says whether they differ. With the plugin
+installed you also get a `<coflux-session-moved>` block at the start of every prompt while the two
+differ — but that block only arrives with the **next** user prompt. **About to call an MCP tool right
+after a `cd`? Run `cofluxd workspace` first** and use the `workspaceId` it prints; do not reuse
+`COFLUX_WORKSPACE_ID`.
 
-**用 `cofluxd terminal new` 而不是自己后台起进程**——只要这条命令满足任一条：
+## When to open a terminal
 
-- 要跑超过十几秒（测试、构建、安装依赖、迁移）
-- 会一直跑下去（dev server、watch、日志跟随）
-- 用户可能想接管（需要交互、可能要中途叫停、失败了要人去调）
+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.
+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:
 
-这类工作在你自己的 Bash 里后台跑，用户**什么也看不见**：看不到它在跑、接管不了、
-出问题只能等你转述。开成 coflux 终端，它就是侧栏里一个有标题的条目，用户能点进去、
-能接管、能自己敲命令。
+- the user may want to step in: interactive steps, confirmations, something they may need to stop
+  midway or rescue when it fails
+- 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)
 
-**不要用**在一次性的快命令上（`ls`、`grep`、`git status`、读文件）——你自己的工具更快，
-给用户开一堆一秒就结束的终端只是噪音。
+**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.
 
-## 本地命令
+## Local commands
 
-### 开终端跑命令
+### Open a terminal
+
+There are two kinds, told apart by one single thing: **whether you pass a command**.
 
 ```sh
-cofluxd terminal new --title "跑单测" --cmd "pnpm -C tests test"
+cofluxd terminal new --title="Run unit tests" --cmd="pnpm -C tests test"   # job terminal
+cofluxd terminal new --title="Debug shell"                                 # session terminal
 ```
 
-`--title` 是用户在侧栏看到的名字，**认真起**：写「跑单测」「起 dev server」，
-别写「terminal 1」。命令在当前工作区目录下、用登录 shell 执行。
-
-命令跑完终端就退出，任务转 `exited` 并带上退出码——这是你判断成没成的依据。
-所以别指望在同一个终端里接着跑第二条命令，要么写成 `a && b`，要么再开一个。
+`--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. `cofluxd terminal new --title="Debug shell"` → prints a taskId.
+2. `cofluxd 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. `cofluxd 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. `cofluxd terminal send <taskId> --text="exit" --enter` when you are done; the terminal then
+   becomes `exited` with the shell's exit code.
+
+The new terminal has the same `COFLUX_*` variables (pointing at its own task/session ids, same
+workspace as you).
+
+### See how far it got
 
-命令的输出会同时落一份日志供你回读，代价是它的 stdout 是管道而不是 tty——多数程序会因此
-关掉颜色和进度条。极少数程序在非 tty 下行为不同（比如不输出进度、切成 CI 模式），如果你
-依赖那种行为，自己在 Bash 里跑。
+```sh
+cofluxd terminal list                      # every terminal in the workspace your cwd is in: id, state, exit code, title
+cofluxd terminal read <taskId>             # a terminal's content (plain text, last 200 lines by default)
+cofluxd terminal read <taskId> --lines 50
+```
 
-新开的终端里同样有 `COFLUX_*` 变量（指向它自己的 task/session id，工作区与你相同）。
+`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.
 
-### 看跑到哪了
+### Wait for a command to finish
 
 ```sh
-cofluxd terminal list                      # 本工作区所有终端：id、状态、退出码、标题
-cofluxd terminal read <taskId>             # 某个终端的内容（纯文本，默认最后 200 行）
-cofluxd terminal read <taskId> --lines 50
+cofluxd terminal wait <taskId>               # block until that terminal exits and print the exit code (default cap 30 minutes)
+cofluxd terminal wait <taskId> --timeout 300 # custom timeout in seconds; a timeout fails loudly with a non-zero exit
 ```
 
-`list` 的状态是 `running` / `exited` / `idle`；`exited` 会带 `exit=<码>`。
-**终端已经退出也能 read**——「命令跑完了看输出」正是最常用的场景。
+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.
 
-内容有最多约 2 秒的延迟（来自中心的定期快照），所以刚 `new` 完立刻 `read` 可能是空的。
+`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.
 
-### 等命令跑完
+**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.
 
-```sh
-cofluxd terminal wait <taskId>               # 阻塞到该终端退出，打印退出码（默认最长等 30 分钟）
-cofluxd terminal wait <taskId> --timeout 300 # 自定超时（秒）；超时会明确报错并非零退出
-```
+**Keep working, and be woken up when it finishes.** `wait` blocks, so run it as a backgrounded Bash
+call of your own:
 
-要等一条命令跑完就用 `wait`，**别自己写轮询循环**——它一条命令阻塞到位，退出码直接给你。
-超时不代表命令失败，只是还没跑完：`read` 看看现场再决定继续等还是处理。
+1. `cofluxd terminal new --title="Run the test suite" --cmd="pnpm -C tests test"` → prints a taskId.
+2. Run `cofluxd 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
+   `cofluxd terminal read <taskId>` to see what actually happened.
 
-### 往终端里输入
+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.
+
+### Type into a terminal
 
 ```sh
-cofluxd terminal send <taskId> --text "y" --enter    # 输入一行并回车
-cofluxd terminal send <taskId> --enter               # 只按一个回车
+cofluxd terminal send <taskId> --text "y" --enter    # type a line and press Enter
+cofluxd terminal send <taskId> --enter               # just press Enter
 ```
 
-用在命令要交互确认（y/N、选项）、或想在跑完的同一 shell 里补一条命令的时候。纪律：
+For interactive confirmations (y/N, menus), or to add a command in the same shell after the
+previous one finished. Discipline:
 
-- **先 `read` 再 `send`**：看清终端现在在等什么再输入，别盲打。
-- **用户正在接管时会被拒**——这不是错误，是设计：人永远优先。被拒就停手，
-  要沟通用 `notify`，别重试。
-- send 超时后**不要直接重发**：先 `read` 确认刚才那次到底进没进去，重复输入比丢输入更糟。
+- **`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.
+- **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.
 
-### 播报进度
+### Report progress
 
 ```sh
-cofluxd progress "复现了，正在定位 relay 重连的时序"
+cofluxd progress "Reproduced; narrowing down the relay reconnect timing"
 ```
 
-一句话告诉用户你干到哪了，显示在工作区卡片上，被下一条覆盖。在关键节点更新：复现了、
-定位到了、修完在验、卡在哪。它**不打扰用户**，和 `notify` 是两条信道：
+One sentence telling the user how far you are, shown on the workspace card and replaced by the
+next one. Update it at milestones: reproduced, located, fixed and verifying, stuck on X. It
+**does not interrupt the user**; it is a different channel from `notify`:
 
-- `progress` = 播报（用户扫一眼就知道进展，不需要回应）
-- `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)
 
-拿不准用哪个：不需要用户做任何事就用 `progress`。
+If unsure: when the user does not have to do anything, use `progress`.
 
-### 叫人
+### Call the user
 
 ```sh
-cofluxd notify "两个方案都能走通，需要你定一下用哪个"
+cofluxd 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.
 
-（你正常的提问和权限请求已经会自动反映到侧栏状态上，不需要额外 notify。
-这条是给「你要说的事，用户光看状态图标猜不出来」准备的。）
+(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".)
 
-### 给用户可点开的预览
+### Hand the user a clickable preview
 
 ```sh
 cofluxd ports
 ```
 
-列出本工作区所有监听端口和对应的公网预览 URL。起了 dev server 之后用它拿 URL 直接
-告诉用户，他点开就能看，不用自己去翻。
-
-## 中心 MCP：跨出本工作区
-
-本地命令只看得见你所在的工作区。要做下面这些事，用宿主里名为 `coflux` 的 MCP server：
-
-- **开一个隔离的子工作区并行干活**：`create_workspace`（项目 id 用 `$COFLUX_PROJECT_ID`）
-  在设备上真的 `git worktree add`，然后 `create_terminal` 在那里跑命令。
-- **看/操作别的工作区、别的设备上的终端**：`list_*` → `read_terminal` / `send_terminal_input`。
-- **不在 coflux 终端里**（比如用户在自己电脑上开的 Claude Code）时接入账号下的一切。
-
-### 没配 MCP 时
-
-先 `claude mcp list`（Codex：`codex mcp list`）看有没有 `coflux`。没有就告诉用户一行接入，
-地址用 `$COFLUX_MCP_URL`（它就是中心公网地址 + `/mcp`）：
+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.
+
+### 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 (`cofluxd 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.
+
+## Center MCP: leaving this workspace
+
+Local commands only see the workspace your cwd is in. Use the MCP server named `coflux` in the
+host **only** for these:
+
+- **Open an isolated child workspace to work in parallel**: `create_workspace` (project id from
+  `$COFLUX_PROJECT_ID`) really runs `git worktree add` on the device; then `create_terminal` runs
+  commands there. The same two kinds apply: `create_terminal` with a `command` opens a
+  job terminal, without one it opens a session terminal.
+- **Look at or operate terminals in other workspaces or on other devices**: `list_*` →
+  `read_terminal` / `send_terminal_input`.
+- **Join everything under the account when you are not inside a coflux terminal** (for example
+  Claude Code the user started on their own machine).
+- **Deleting a workspace**: `remove_workspace` (it closes that workspace's terminals first, then
+  removes the worktree and the record). Inside a coflux project the plugin blocks
+  `git worktree remove|move` run by hand, because that leaves an orphan workspace record in the user's
+  sidebar. Creating a worktree is *not* blocked — coflux follows you into it (see above) — and Claude
+  Code's own worktrees need no cleanup from you at all.
+
+Do not detour through MCP for work inside the workspace you are in — including one you moved into
+with `cd` or EnterWorktree, where the local commands follow you: that is an extra round trip to the
+center, while a local command does it in one step.
+
+### When MCP is not configured
+
+Run `claude mcp list` (Codex: `codex mcp list`) to see whether `coflux` is there. If not, give
+the user the one-line setup, with the URL from `$COFLUX_MCP_URL` (it is the center's public URL
++ `/mcp`):
 
 ```sh
 claude mcp add --transport http coflux "$COFLUX_MCP_URL"     # Claude Code
 codex mcp add coflux --url "$COFLUX_MCP_URL"                 # Codex
 ```
 
-之后宿主会引导用户在浏览器完成一次 OAuth 授权（Claude Code 里是 `/mcp`）。授权是用户的事，
-你只需要把地址和命令给他；没配好之前本工作区内的活照样用本地命令干。
-
-### 14 个 tools
-
-id 优先从 `COFLUX_*` 环境变量拿；跨出本工作区的 id 用 `list_*` 查。
-
-| tool | 用途 |
-|---|---|
-| `list_devices` | 账号下的设备（跑着 daemon 的机器）：id、名称、在线、版本 |
-| `list_projects` | 导入的项目（git 仓库）：id、所在设备、仓库路径、默认分支 |
-| `list_workspaces` | 工作区（主工作区 = 仓库本身，其余是 worktree；目录工作区 projectId 为 null），可按 projectId 筛 |
-| `list_terminals` | 终端：id、工作区、标题、状态 idle/running/exited、退出码，可按 workspaceId 筛 |
-| `read_terminal` | 读终端纯文本（去 ANSI，默认尾 200 行）：source=log 是命令终端的完整日志（退出后仍可读），snapshot 是当前画面，checkpoint 是设备离线时中心的最近快照 |
-| `list_ports` | 终端里检测到的监听端口 + 可直接打开的预览 URL |
-| `create_workspace` | 在项目下新建 git worktree 工作区（可新建分支），设备真在磁盘上建目录 |
-| `rename_workspace` | 改工作区名（纯展示） |
-| `remove_workspace` | 删 worktree 工作区：先关其下所有终端再 `git worktree remove --force`（未提交改动会丢）；主工作区不可删 |
-| `create_terminal` | 在某工作区开真实终端跑一条命令（用户可接管、侧栏可见），跑完带退出码；输出落日志供 `read_terminal` |
-| `send_terminal_input` | 往运行中的终端写文本（默认追加回车） |
-| `wait_terminal` | 有界等待终端退出并拿退出码（默认 30 秒、上限 50 秒） |
-| `stop_terminal` | 结束终端会话（等价 web 上的停止） |
-| `remove_terminal` | 删终端记录；运行中的必须先 `stop_terminal` |
-
-### 用 MCP 的三条纪律
-
-1. **人类优先**：`send_terminal_input` 在用户正在接管那个终端时会被拒，错误里写明
-   「用户正在接管」——把交互留给用户，不要重试；要沟通用本工作区的 `cofluxd notify`。
-   `send` 之前先 `read_terminal` 看清它在等什么；回执超时先 `read` 再决定要不要重发。
-2. **有界等待**：`wait_terminal` 最多等 50 秒，到期返回 `timedOut=true` 不是错误——需要更久
-   就再调一次，**别自己写轮询循环去 `read_terminal`**。`create_workspace` / `create_terminal`
-   最多等 30 秒启动回执，到期返回「已提交」并附 id，稍后用 `list_*` 查。
-3. **「需要升级」就停**：写 tools 在目标设备的 daemon 太旧时立即返回「该设备的 daemon 需要
-   升级」——这是能力门禁，不是暂时故障。转告用户在那台机器上 `cofluxd update && cofluxd restart`，
-   别重试也别换 tool 绕。
-
-本地命令的纪律（先 read 再 send、被拒即停、`progress` 与 `notify` 分界、用 `wait` 别轮询）
-在 MCP 里同样成立。
-
-## 边界
-
-- 你能开、读、等、输入，但**输入是人类优先的受限写权**：用户正在接管的终端你写不进去
-  （会被明确拒绝），用户随时接管也会把你顶掉。别和人抢终端。
-- 本地命令只看得见**你自己所在的工作区**；别的工作区和别的机器要经 MCP，且限于同一账号。
-- 一个工作区同时活着的终端有上限（默认 8，含用户自己开的）。撞上限先 `list` 看看，
-  多半是有跑完没收的；真是用户占满了，就 `notify` 告诉他，别硬试。
-- 这些命令与 tools 都要 daemon 连着中心才能用——毕竟「让用户看见」就是它们的全部意义。
-  连不上时会明确报错，不会默默降级。
-- `COFLUX_*` 变量只在 coflux 开出来的 PTY 里有；你自己 `export` 或改它们没有任何效果，
-  中心只认它自己下发的 id。
+The host then guides the user through a one-time OAuth authorization in the browser (`/mcp` in
+Claude Code). Authorization is the user's job; you only hand over the URL and the command. Until
+it is set up, keep doing the work inside this workspace with local commands.
+
+### Using the tools
+
+The tool list and each tool's contract (parameters, limits, what an error means) come from the
+MCP server itself: read the tool descriptions in the host, they are the source of truth and this
+file does not repeat them. Take ids from the `COFLUX_*` variables first — except the workspace id
+after you moved, which comes from `cofluxd workspace` (or the `<coflux-session-moved>` block); for
+anything outside the workspace you are in, find ids with the `list_*` tools.
+
+The local-command disciplines apply to MCP just the same: `read_terminal` before
+`send_terminal_input`, stop when refused because the user is taking over (communicate with
+`cofluxd notify` instead of retrying), `wait_terminal` instead of a polling loop around
+`read_terminal`, and stop on "needs upgrade" (tell the user to run
+`cofluxd update && cofluxd restart` on that device; do not retry or work around 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.
+- Local commands only see **the workspace your cwd is in** (`cofluxd workspace` says which one);
+  other workspaces and other machines go through MCP and are limited to 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 every MCP tool 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.
+- `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
+  worktree; both "where does this terminal belong now" and "where am I acting" come from
+  `cofluxd workspace`.