@twinsearth/w2m-dsh-plugin 1.4.1 → 1.4.3

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "The w2m fleet plugins: one account, many machines, any of Windows, macOS or Linux.",
-    "version": "1.4.1"
+    "version": "1.4.3"
   },
   "plugins": [
     {
       "name": "w2m-fleet",
       "source": "./",
       "description": "Read fleet state and dispatch commands across the machines registered to one account. Read-only MCP surface: the five exposed tools cannot change anything.",
-      "version": "1.4.1",
+      "version": "1.4.3",
       "author": {
         "name": "TwinsEarth"
       },
@@ -26,5 +26,5 @@
       ]
     }
   ],
-  "version": "1.4.1"
+  "version": "1.4.3"
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "w2m-fleet",
   "description": "Drive the same project on online Windows, macOS and Linux machines from one account: read fleet state, dispatch commands and read results. The MCP surface is deliberately read-only.",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "author": {
     "name": "TwinsEarth"
   },

package/CHANGELOG.md

@@ -7,6 +7,61 @@
 
 All notable changes to this project are documented here.
 
+## [1.4.3] — 2026-10-22
+
+**微信编队桥接：回复可靠性修复（不回复/静默问题）。**
+
+- 每条消息独立 try/catch：任何处理异常不再让进程退出，改为回复
+  `处理失败（阶段，错误码）：原因 + /help 提示`（新增 `renderBridgeError`）。
+- 桥接启动调用 `ilink/bot/msg/notifystart`：修复"token 有效、进程在跑、但 iLink 不推送消息"的静默状态；
+  日志记录 `notifystart : ok`，失败也记录原因。
+- 非文本、空消息、未以 `/run` 开头、权限不足、派发失败/超时等路径均保证有回复与下一步提示。
+- 运行方式支持 launchd 常驻（KeepAlive 自动拉起；macOS plist 由运维部署，不进入安装包）。
+
+- **授权优先级修复**：exec-capability 只在任务未携带 grant 时兜底；grant 被拒（replay / 过期 / 机器不符）
+  原样上报，不再被能力分支覆盖成路径匹配错误，`GRANT_REPLAY` 语义恢复。
+
+真机验收（macmini）：`notifystart ok`、错误回复代码在位、launchd state=running、bridge 进程存活；
+证据 `docs/acceptance/1.4.3/BRIDGE-LIVE.json`。测试：chatops-ilink-fleet-bridge 36/36。
+
+## [1.4.2] — 2026-10-22
+
+**Node 代码执行权限成为 UI 可激活的子插件能力（命中真机验收）。**
+
+- 新增 `src/util/exec-capability.mjs`：机器本地能力状态（拒绝 / 临时 24h / 永久），fail-closed；临时档带绝对
+  `expires_at_ms`，过期即拒绝；唯一可放行的前缀固定为 `node -e`。
+- 新增 host 路由 `GET/POST /api/w2m/capability`（`src/plugin/exec-capability-route.mjs`），同源、在 host
+  认证栅栏内；浏览器不接触文件系统或设备 token。
+- client `lib/client.js` 在 `conversation.input.left` 新增第三个控制（order 42）：
+  `Node 执行：拒绝 | 临时 24 小时 | 永久`，带 RCE 风险提示与剩余时间。
+- agent 每个任务前读取能力文件；命中时结果信封 `authorization.provenance = "exec-capability"`，
+  warnings 记录 `EXEC_CAPABILITY`；pipeline 各 stage 同样覆盖。
+
+真机验收（TwinsEarth，插件 1.4.2-beta.1；先清空 `cordis.patch.yml` 的旧 allow-list 以隔离能力路径）：
+- 无能力、空 allow-list：`node --version` → `COMMAND_NOT_ALLOWED`
+- 能力=永久、空 allow-list：`node -e` → **ok**（`node -e` 是唯一被放行的前缀）
+- 能力=临时 5s 到期后：`node -e` → `COMMAND_NOT_ALLOWED`（fail-closed）
+- 证据：`docs/acceptance/1.4.2/CAPABILITY-LIVE.json`
+
+Verified: 单测/路由/客户端契约 43/43；候选 gate GREEN ×2；stable gate 见发布记录。
+
+## [1.4.2-beta.1] — 2026-10-22
+
+**Node 代码执行权限成为 UI 可激活的子插件能力。**
+
+- 新增 `src/util/exec-capability.mjs`：机器本地能力状态（拒绝 / 临时 24h / 永久），fail-closed，
+  临时档带绝对 `expires_at_ms`，过期即拒绝。
+- 新增 host 路由 `GET/POST /api/w2m/capability`（`src/plugin/exec-capability-route.mjs`），同源、在
+  host 认证栅栏内；浏览器不再接触文件系统或设备 token。
+- client `lib/client.js` 在 `conversation.input.left` 座位新增第三个控制（order 42）：
+  `Node 执行：拒绝 | 临时 24 小时 | 永久`，带 RCE 风险提示与剩余时间。
+- agent 每个任务前读取能力文件；命中时结果信封 `authorization.provenance = "exec-capability"`，
+  warnings 记录 `EXEC_CAPABILITY`；pipeline 各 stage 同样覆盖。
+- 文档 `docs/EXEC-CAPABILITY.md`；测试 `test/exec-capability.test.mjs`（7/7）、
+  client-bundle/loader-entry/exec-capability 合计 43/43。
+
+Verified: 单测与路由测试全绿；候选版本真机验收（UI 激活 → agent 下一任务可执行 node -e）。
+
 ## [1.4.1] — 2026-10-22
 
 **修复：授权模型在从未 bootstrap 的机器上不可用（真机发现）。**

package/codex/mcp-servers.toml

@@ -12,6 +12,6 @@
 
 [mcp_servers.w2m-fleet]
 command = "npx"
-args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.4.1", "w2m-mcp"]
+args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.4.3", "w2m-mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 60

package/docs/EXEC-CAPABILITY.md

@@ -0,0 +1,57 @@
+# Node 代码执行能力（子插件能力，DSH 界面激活）
+
+**状态：v1.4.2 实现。** 把"允许该机器执行任意 Node 代码"从一份静态 allow-list 变成了
+**插件界面里的一个显式开关**：客户在 DSH 的 composer 座位（目标机器旁）看到
+`Node 执行：拒绝 | 临时 24 小时 | 永久`，点选即生效，不需要手改配置文件。
+
+## 为什么需要它
+
+`node -e` 前缀等于放行任意 Node 代码，等效远程代码执行（RCE）。此前的做法是让用户手改
+`~/.w2m/machine.json` 的 `allowedCommands`：容易写成永久、没有到期、没有 UI 提示、没有审计措辞。
+把这一条能力单独做成"子插件能力"，其余 allow-list 语义不变，就能做到：
+
+- **默认拒绝**：文件缺失/损坏/过期都读作 `denied`，fail-closed；
+- **三档显式选择**：拒绝 / 临时 24h（可配置 TTL，上限 7 天）/ 永久；
+- **到期自失效**：临时档写入绝对 `expires_at_ms`，agent 每次任务前读取，过期即拒绝，不需要重启；
+- **可审计**：每次任务的结果信封记录 `authorization.provenance = "exec-capability"`，并在 warnings 里
+  写明 `EXEC_CAPABILITY: node code execution …`；台账里仍是 task id + argv + 机器。
+
+## 组成
+
+| 层 | 文件 | 作用 |
+|---|---|---|
+| util | `src/util/exec-capability.mjs` | 状态文件读写、过期判定、固定前缀 `node -e`、`describeExecCapability` |
+| host 路由 | `src/plugin/exec-capability-route.mjs` | `GET/POST /api/w2m/capability`，同源、在 host 认证栅栏内 |
+| agent | `src/agent/agent.mjs` | 每次任务前读文件；allow-list 拒绝后、grant 之前/之后按策略并集判定；stage 同样覆盖 |
+| client | `lib/client.js` | `conversation.input.left` 座位第三个控制（order 42），三档菜单 + 风险提示 |
+
+## 状态文件
+
+`~/.w2m/exec-capability.json`（每台机器本地，不通过 relay 同步）：
+
+```json
+{ "protocol": "w2m-exec-capability/v1", "state": "temporary",
+  "activated_at_ms": 1792650000000, "expires_at_ms": 1792736400000,
+  "actor": { "kind": "operator", "id": "plugin-ui", "at": "..." } }
+```
+
+## 生效顺序
+
+```
+允许执行 ⇔ allow-list 匹配
+          ∨ grant 授权（显式、单次、≤10 分钟、可撤销）
+          ∨ exec-capability 激活（本机 UI 开关；临时档未过期）
+```
+
+本机开关与 grant 是**并列的两种授权来源**：grant 适合"操作员对某一次跨机执行签字"，
+capability 适合"本机机主长期/为期一天地打开这个能力"。结果信封的 provenance 会区分二者。
+
+## 撤销
+
+界面切回"拒绝"即可；或删除 `~/.w2m/exec-capability.json`；或手改 `state: "denied"`。
+agent 下一个任务生效，不需要重启；插件自身回滚仍是"覆盖 `…w2m-dsh-plugin.pre-<ver>` 后重启 DSH"。
+
+## 测试
+
+`test/exec-capability.test.mjs`：默认拒绝、三态写入、24h 到期边界、非法输入、路由 GET/POST/405；
+`test/client-bundle.test.mjs`：第三个座位控制被注册、inject 面、样式与激活契约。

package/docs/acceptance/1.4.2/CAPABILITY-LIVE.json

@@ -0,0 +1,28 @@
+{
+  "version": "1.4.2-beta.1",
+  "case": "CAPABILITY-LIVE",
+  "kind": "positive",
+  "machines": [
+    "6c92b251-3728-48bc-82a9-56cc40df48f2"
+  ],
+  "executed_at": "2026-10-22T05:36:57.619Z",
+  "executor": "lead",
+  "requirement": "with an empty allow-list, node -e executes only while the UI-activated exec capability is effective; an expired temporary activation is refused",
+  "task_id": "01M5H1R5B8A0QAWNPDES19SZ1F",
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "plugin_version": "1.4.2-beta.1",
+      "allow_list_empty": true,
+      "plain_node_refused": true,
+      "capability_executed": true,
+      "expired_capability_refused": true
+    }
+  },
+  "tasks": {
+    "plain_refused": "01M5H1QPA9QD3SKK4KFB7V18WX",
+    "capability_allowed": "01M5H1R5B8A0QAWNPDES19SZ1F",
+    "expired_refused": "01M5H1S0BKNBVF9RMC8P1X0665"
+  },
+  "note": "candidate installed from the release tree through the relay blob channel; the stale allow-list in cordis.patch.yml was cleared so the capability alone authorized the execution; the capability file is what the DSH capability control writes"
+}

package/docs/acceptance/1.4.3/BRIDGE-LIVE.json

@@ -0,0 +1,22 @@
+{
+  "version": "1.4.3",
+  "case": "BRIDGE-LIVE",
+  "kind": "positive",
+  "machines": [
+    "71f0dd07-e957-4889-bf82-319a0d6b434a"
+  ],
+  "executed_at": "2026-10-22T07:08:13.838Z",
+  "executor": "lead",
+  "requirement": "the deployed WeChat bridge enables iLink message push (notifystart ok), answers failures through the renderBridgeError path, and runs under launchd KeepAlive",
+  "task_id": "01M5BRIDGEACCMVJ78GU0",
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "notifystart": true,
+      "error_reply_code": true,
+      "launchd_state": "state = running",
+      "bridge_processes": 3
+    }
+  },
+  "note": "hotfixed bridge files were verified live on macmini before packaging; the same files are what v1.4.3 ships"
+}

package/lib/client.js

@@ -76,6 +76,8 @@ window.__ModuleLoader__.load({
     // the route is mounted inside the host's authentication fence, so the page's own cookie is the
     // credential and there is no descriptor to keep in sync.
     const ROUTE = '/api/w2m/target';
+    // v1.4.2: the UI-activated Node-code-execution switch (host: src/plugin/exec-capability-route.mjs).
+    const CAPABILITY_ROUTE = '/api/w2m/capability';
 
     /**
      * The locale namespace and its two dictionaries.
@@ -103,6 +105,15 @@ window.__ModuleLoader__.load({
         unreachable: '无法连接插件',
         routeMissing: '这个 Harness 没有提供插件目标路由',
         fleetUnreadable: '机器列表读取失败',
+        capLabel: 'Node 执行：{state}',
+        capDenied: '拒绝',
+        capTemporary: '临时 24 小时',
+        capPermanent: '永久',
+        capWarning: '开启后该机器可执行任意 Node 代码（等效远程代码执行）',
+        capMenuLabel: 'Node 代码执行能力',
+        capRemaining: '剩余 {hours} 小时',
+        capRouteMissing: '这个 Harness 没有提供能力路由',
+        capRefused: '能力切换被拒绝：{error}',
       },
       en: {
         all: 'All machines',
@@ -118,6 +129,15 @@ window.__ModuleLoader__.load({
         unreachable: 'the plugin could not be reached',
         routeMissing: 'this host does not serve the W2M target route',
         fleetUnreadable: 'the fleet could not be read',
+        capLabel: 'Node exec: {state}',
+        capDenied: 'denied',
+        capTemporary: 'temporary 24 h',
+        capPermanent: 'permanent',
+        capWarning: 'once on, this machine runs arbitrary Node code (equivalent to remote code execution)',
+        capMenuLabel: 'Node code execution capability',
+        capRemaining: '{hours} h left',
+        capRouteMissing: 'this host does not serve the capability route',
+        capRefused: 'the capability switch was refused: {error}',
       },
     };
 
@@ -230,6 +250,23 @@ window.__ModuleLoader__.load({
       },
     });
 
+    /** One JSON call to the capability route: refusals are values, exactly like the target route. */
+    async function callCapability(options) {
+      let response;
+      try {
+        response = await fetch(options.url, options.init);
+      } catch (error) {
+        return { ok: false, error: 'the plugin could not be reached: ' + (error instanceof Error ? error.message : String(error)) };
+      }
+      if (response.status === 404) return { ok: false, status: 404, routeMissing: true, error: 'capability route missing' };
+      let body = null;
+      try { body = await response.json(); } catch { return { ok: false, error: 'the capability route answered HTTP ' + response.status } }
+      if (response.ok !== true) return { ok: false, status: response.status, error: typeof body?.error === 'string' ? body.error : 'HTTP ' + response.status };
+      return { ok: true, capacity: body?.capability ?? null };
+    }
+    const readCapability = (signal) => callCapability({ url: CAPABILITY_ROUTE, init: { method: 'GET', credentials: 'same-origin', headers: { accept: 'application/json' }, signal } });
+    const writeCapability = (state, ttlMs) => callCapability({ url: CAPABILITY_ROUTE, init: { method: 'POST', credentials: 'same-origin', headers: { 'content-type': 'application/json', accept: 'application/json' }, body: JSON.stringify(ttlMs === undefined ? { state } : { state, ttl_ms: ttlMs }) } });
+
     const labelOf = (state, t) => state?.selected?.machine_id != null
       ? (state.selected.name ?? state.selected.machine_id)
       : t('all');
@@ -283,6 +320,18 @@ window.__ModuleLoader__.load({
       '.w2mTarget_name{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
       '.w2mTarget_detail{margin-left:auto;flex:none;color:var(--dsw-alias-label-tertiary);font-size:11px;font-weight:400}',
       '.w2mTarget_option:disabled .w2mTarget_detail{color:var(--dsw-alias-label-caption)}',
+      '.w2mCap{position:relative;display:inline-flex;align-items:center}',
+      '.w2mCap_trigger{display:inline-flex;align-items:center;gap:4px;height:28px;padding:0 8px;border:none;border-radius:var(--dsw-radius-sm);background:transparent;color:var(--dsw-alias-label-secondary);font-size:13px;font-weight:500;line-height:20px;cursor:pointer;outline:none}',
+      '.w2mCap_trigger:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover)}',
+      '.w2mCap_trigger:disabled{color:var(--dsw-alias-label-dimmed);cursor:default}',
+      '.w2mCap_trigger[data-on="true"]{color:var(--dsw-alias-state-warn-primary)}',
+      '.w2mCap_dot{flex:none;width:8px;height:8px;border-radius:999px;background:var(--dsw-alias-state-idle-primary);box-shadow:inset 0 0 0 1px var(--dsw-alias-border-l2)}',
+      '.w2mCap_dot[data-on="true"]{background:var(--dsw-alias-state-warn-primary)}',
+      '.w2mCap_menu{position:fixed;z-index:60;box-sizing:border-box;width:280px;padding:4px;border-radius:var(--dsw-radius-lg);border:.5px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-1);box-shadow:var(--dsw-elevation-soft);font-size:13px;line-height:20px;color:var(--dsw-alias-label-primary)}',
+      '.w2mCap_option{display:block;width:100%;box-sizing:border-box;padding:6px 8px;border:none;border-radius:var(--dsw-radius-sm);background:transparent;color:inherit;font:inherit;text-align:left;cursor:pointer}',
+      '.w2mCap_option:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover)}',
+      '.w2mCap_option[data-active="true"]{color:var(--dsw-alias-state-business-primary)}',
+      '.w2mCap_note{padding:6px 8px;color:var(--dsw-alias-label-tertiary);font-weight:400}',
       '.w2mChat{position:relative;display:inline-flex;align-items:center}',
       '.w2mChat_trigger{display:inline-flex;align-items:center;gap:4px;height:28px;padding:0 8px;border:none;border-radius:var(--dsw-radius-sm);background:transparent;color:var(--dsw-alias-label-secondary);font-size:13px;font-weight:500;line-height:20px;cursor:pointer;outline:none}',
       '.w2mChat_trigger:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover)}',
@@ -833,6 +882,114 @@ window.__ModuleLoader__.load({
           : null);
     }
 
+
+    /**
+     * v1.4.2: the Node-code-execution capability switch.
+     *
+     * Three explicit decisions, no fourth: deny, temporary (24 h, expiring), permanent. The host owns the file
+     * and the agent reads it before every task, so a choice here takes effect on the next dispatch; the control
+     * never claims the choice succeeded until the host's own answer says so.
+     */
+    function ExecCapability({ t }) {
+      const [open, setOpen] = React.useState(false);
+      const [capability, setCapability] = React.useState(null);
+      const [error, setError] = React.useState(null);
+      const [busy, setBusy] = React.useState(false);
+      const anchorRef = React.useRef(null);
+      const menuRef = React.useRef(null);
+      const [placement, setPlacement] = React.useState(null);
+
+      React.useEffect(() => {
+        const controller = new AbortController();
+        readCapability(controller.signal).then((result) => {
+          if (controller.signal.aborted) return;
+          if (result.ok) { setCapability(result.capacity); setError(null); }
+          else setError(result.routeMissing ? t('capRouteMissing') : result.error);
+        });
+        return () => controller.abort();
+      }, []);
+
+      React.useEffect(() => {
+        if (!open) return undefined;
+        const reposition = () => {
+          const anchor = anchorRef.current;
+          if (anchor === null) return;
+          const rect = anchor.getBoundingClientRect();
+          const width = Math.min(280, Math.max(240, Math.round(rect.width) + 120));
+          const left = Math.max(8, Math.min(rect.left, window.innerWidth - width - 8));
+          const top = Math.max(8, rect.top - 220);
+          setPlacement({ left, width, top });
+        };
+        const onKeyDown = (event) => { if (event.key === 'Escape') { setOpen(false); anchorRef.current?.focus?.(); } };
+        const onPointerDown = (event) => {
+          if (anchorRef.current?.contains(event.target) === true) return;
+          if (menuRef.current?.contains(event.target) === true) return;
+          setOpen(false);
+        };
+        reposition();
+        document.addEventListener('keydown', onKeyDown, true);
+        document.addEventListener('pointerdown', onPointerDown, true);
+        return () => {
+          document.removeEventListener('keydown', onKeyDown, true);
+          document.removeEventListener('pointerdown', onPointerDown, true);
+        };
+      }, [open]);
+
+      const active = capability?.effective === true;
+      const stateName = active ? (capability.state === 'temporary' ? t('capTemporary') : t('capPermanent')) : t('capDenied');
+      const hours = capability?.remaining_ms === null || capability?.remaining_ms === undefined
+        ? null
+        : Math.max(0, Math.round(capability.remaining_ms / 3_600_000));
+      const title = capability === null
+        ? t('capMenuLabel')
+        : active ? t('capWarning') : t('capDenied');
+
+      const choose = (state, ttlMs) => {
+        setBusy(true);
+        writeCapability(state, ttlMs).then((result) => {
+          setBusy(false);
+          if (result.ok) { setCapability(result.capacity); setError(null); setOpen(false); return; }
+          setError(result.routeMissing ? t('capRouteMissing') : result.error);
+        });
+      };
+
+      const menu = open && placement !== null
+        ? h('div', {
+            className: 'w2mCap_menu',
+            role: 'menu',
+            'aria-label': t('capMenuLabel'),
+            ref: menuRef,
+            style: { left: placement.left + 'px', top: placement.top + 'px', width: placement.width + 'px' },
+          }, [
+            h('div', { key: 'warn', className: 'w2mCap_note', role: 'note' }, t('capWarning')),
+            h('button', { key: 'deny', type: 'button', className: 'w2mCap_option', 'data-active': active ? 'false' : 'true', onClick: () => choose('denied') }, t('capDenied')),
+            h('button', { key: 'temp', type: 'button', className: 'w2mCap_option', 'data-active': capability?.state === 'temporary' ? 'true' : 'false', onClick: () => choose('temporary', 24 * 60 * 60 * 1000) }, t('capTemporary')),
+            h('button', { key: 'perm', type: 'button', className: 'w2mCap_option', 'data-active': capability?.state === 'permanent' ? 'true' : 'false', onClick: () => choose('permanent') }, t('capPermanent')),
+            error === null ? null : h('div', { key: 'err', className: 'w2mCap_note', role: 'status' }, error),
+          ])
+        : null;
+
+      return h(React.Fragment, null, [
+        h('button', {
+          key: 'trigger',
+          type: 'button',
+          ref: anchorRef,
+          className: 'w2mCap_trigger',
+          'data-on': active ? 'true' : 'false',
+          'aria-label': t('capMenuLabel'),
+          'aria-haspopup': 'menu',
+          'aria-expanded': open,
+          'aria-busy': busy,
+          title,
+          onClick: () => setOpen((wasOpen) => !wasOpen),
+        }, [
+          h('span', { key: 'dot', className: 'w2mCap_dot', 'data-on': active ? 'true' : 'false', 'aria-hidden': 'true' }),
+          h('span', { key: 'label' }, t('capLabel', { state: stateName }) + (hours === null ? '' : ' · ' + t('capRemaining', { hours }))),
+        ]),
+        menu,
+      ]);
+    }
+
     /**
      * Client plugin body: install the stylesheet, register the dictionaries, take the seat.
      *
@@ -909,7 +1066,20 @@ window.__ModuleLoader__.load({
           sessionId,
           t,
         }),
-      }, TargetSelect));
+      }, TargetSelect));        // v1.4.2: the Node-code-execution switch, one seat to the right of the chat panel.
+        try {
+          slots.inject('conversation.input.left', () => slots.register({
+            name: 'conversation.input.left',
+            id: 'w2m-capability',
+            order: 42,
+            label: 'node code execution',
+            inject: () => ({ t }),
+          }, ExecCapability));
+        } catch (error) {
+          console.error('@twinsearth/w2m-dsh-plugin: the capability switch was not mounted; the rest of the page is unaffected', error);
+        }
+
+
 
       // The fleet-chat panel: the same session-scoped seat, one slot after the target control.
       // Wrapped in its own try/catch on purpose — the target control is the primary half of this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "type": "module",
   "exports": {
@@ -64,7 +64,7 @@
     "pack": "node scripts/pack.mjs",
     "reachability": "node scripts/reachability-check.mjs",
     "reachability:classify": "node scripts/reachability-classify.mjs",
-    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/blake2s.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/fleet-merge.test.mjs test/fleet-memory-e2e.test.mjs test/fleet-concurrency.test.mjs test/fleet-merge-race.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/portable-plugins.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs test/admission.test.mjs test/admission-routes.test.mjs test/join-degradation.test.mjs test/account-identity.test.mjs test/join-challenge.test.mjs test/exec-env-injection.test.mjs test/account-join.test.mjs test/fleet-messages.test.mjs test/message-shards.test.mjs test/fleet-messages-http.test.mjs test/message-notify.test.mjs test/update-channels.test.mjs test/update-prerelease.test.mjs test/session-watch.test.mjs test/session-readonly.test.mjs test/session-sync.test.mjs test/fleet-chat-identity.test.mjs test/identity-reader.test.mjs test/intents.test.mjs test/dataflow.test.mjs test/council-fleet.test.mjs test/fleet-memory.test.mjs test/memory-view.test.mjs test/schema-spec.test.mjs test/fleet-weight-parity.test.mjs test/task-deps.test.mjs test/dataflow-wiring.test.mjs test/task-graph.test.mjs test/ask-store.test.mjs test/turn.test.mjs test/fleet-members.test.mjs test/redact.test.mjs test/policy-matrix.test.mjs test/envelope-signature.test.mjs test/chat-crypto.test.mjs test/reduce-suggestion.test.mjs test/merge-hint.test.mjs test/fleet-chat-route.test.mjs test/maintenance.test.mjs test/maintenance-ferry.test.mjs test/grant.test.mjs test/grant-gate.test.mjs test/worktree.test.mjs test/patch-artifact.test.mjs test/merge-queue.test.mjs test/m3-workflow.test.mjs test/project-room.test.mjs test/project-attribution.test.mjs test/project-locks.test.mjs test/project-reviews.test.mjs test/project-notifications.test.mjs test/blob-sessions.test.mjs test/outbox.test.mjs test/reliability-metrics.test.mjs test/evidence.test.mjs test/grant-issue.test.mjs test/project-refs.test.mjs",
+    "test": "node --test --test-force-exit test/relay.test.mjs test/broadcast.test.mjs test/blake2s.test.mjs test/agent.test.mjs test/plan-sec-cmd.test.mjs test/authority.test.mjs test/blocks.test.mjs test/approval-index.test.mjs test/fleet-sync.test.mjs test/fleet-merge.test.mjs test/fleet-memory-e2e.test.mjs test/fleet-concurrency.test.mjs test/fleet-merge-race.test.mjs test/health.test.mjs test/storage.test.mjs test/exit-channel.test.mjs test/council.test.mjs test/council-session.test.mjs test/log-bounds.test.mjs test/test-report.test.mjs test/fleet-scale.test.mjs test/fleet-state.test.mjs test/crypto-blake2s.test.mjs test/installed-version.test.mjs test/permission.test.mjs test/machine-test-packet.test.mjs test/field-authority.test.mjs test/approval-gate.test.mjs test/authority-choice.test.mjs test/reachability-check.test.mjs test/reachability-classify.test.mjs test/accepted-orphans.test.mjs test/acceptance-doc.test.mjs test/layer-model.test.mjs test/cwd-containment.test.mjs test/cwd-outside-project.test.mjs test/memory.test.mjs test/tools.test.mjs  test/claims.test.mjs test/fleet-target.test.mjs test/client-bundle.test.mjs test/schedule.test.mjs test/auto-update.test.mjs test/update-source.test.mjs test/update-install.test.mjs test/update-wiring.test.mjs test/signing.test.mjs test/stress.test.mjs test/shared-config.test.mjs test/metrics.test.mjs test/metrics-route.test.mjs test/tool-cards.test.mjs test/p2p-stun.test.mjs test/p2p-transport.test.mjs test/p2p-signaling.test.mjs test/p2p-node.test.mjs test/p2p-transport-fields.test.mjs test/p2p-plugin.test.mjs test/p2p-crypto.test.mjs test/stun-server.test.mjs test/loader-entry.test.mjs test/mdns-wire.test.mjs test/mdns-discover.test.mjs test/chatops-approval.test.mjs test/chatops-policy.test.mjs test/chatops-file-safety.test.mjs test/chatops-outbound-queue.test.mjs test/chatops-commands.test.mjs test/chatops-bridge.test.mjs test/chatops-config-route.test.mjs test/chatops-apply.test.mjs test/chatops-ilink-contract.test.mjs test/chatops-fleet.test.mjs test/chatops-account.test.mjs test/chatops-auth.test.mjs test/chatops-fleet-scope.test.mjs test/chatops-handoff.test.mjs test/chatops-fleet-wiring.test.mjs test/chatops-fleet-live.test.mjs test/chatops-takeover.test.mjs test/chatops-device-signing.test.mjs test/chatops-relay-verify.test.mjs test/chatops-durability.test.mjs test/chatops-run-command.test.mjs test/secrets-guard.test.mjs test/chatops-ilink-fleet-bridge.test.mjs test/agent-plugins.test.mjs test/memory-layer.test.mjs test/mcp-server.test.mjs test/portable-plugins.test.mjs test/mcp-http.test.mjs test/mcp-http-live.test.mjs test/vision.test.mjs test/ilink-shape.test.mjs test/chatops-fleet-join.test.mjs test/admission.test.mjs test/admission-routes.test.mjs test/join-degradation.test.mjs test/account-identity.test.mjs test/join-challenge.test.mjs test/exec-env-injection.test.mjs test/account-join.test.mjs test/fleet-messages.test.mjs test/message-shards.test.mjs test/fleet-messages-http.test.mjs test/message-notify.test.mjs test/update-channels.test.mjs test/update-prerelease.test.mjs test/session-watch.test.mjs test/session-readonly.test.mjs test/session-sync.test.mjs test/fleet-chat-identity.test.mjs test/identity-reader.test.mjs test/intents.test.mjs test/dataflow.test.mjs test/council-fleet.test.mjs test/fleet-memory.test.mjs test/memory-view.test.mjs test/schema-spec.test.mjs test/fleet-weight-parity.test.mjs test/task-deps.test.mjs test/dataflow-wiring.test.mjs test/task-graph.test.mjs test/ask-store.test.mjs test/turn.test.mjs test/fleet-members.test.mjs test/redact.test.mjs test/policy-matrix.test.mjs test/envelope-signature.test.mjs test/chat-crypto.test.mjs test/reduce-suggestion.test.mjs test/merge-hint.test.mjs test/fleet-chat-route.test.mjs test/maintenance.test.mjs test/maintenance-ferry.test.mjs test/grant.test.mjs test/grant-gate.test.mjs test/worktree.test.mjs test/patch-artifact.test.mjs test/merge-queue.test.mjs test/m3-workflow.test.mjs test/project-room.test.mjs test/project-attribution.test.mjs test/project-locks.test.mjs test/project-reviews.test.mjs test/project-notifications.test.mjs test/blob-sessions.test.mjs test/outbox.test.mjs test/reliability-metrics.test.mjs test/evidence.test.mjs test/grant-issue.test.mjs test/project-refs.test.mjs test/exec-capability.test.mjs",
     "test:acceptance-doc": "node --test --test-force-exit test/acceptance-doc.test.mjs",
     "test:account-identity": "node --test --test-force-exit test/account-identity.test.mjs",
     "test:account-join": "node --test --test-force-exit test/account-join.test.mjs",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 12 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "license": "MIT",
   "keywords": [

package/src/agent/agent.mjs

@@ -55,6 +55,13 @@ import {
 import { createSpool } from './spool.mjs';
 import { MEMORY_FILE, appendMemory, memoryRecord } from './memory.mjs';
 import { matchAllowedCommand, parseAllowedCommands } from './allowed-commands.mjs';
+import {
+  EXEC_CAPABILITY_PREFIXES,
+  EXEC_CAPABILITY_WARNING,
+  defaultExecCapabilityFile,
+  effectiveExecCapabilityPrefixes,
+  readExecCapability,
+} from '../util/exec-capability.mjs';
 import { CRYPTO_REASON, DEVICE_KEY_FILE, DeviceKey, PeerKeyStore, deriveSigningKey } from './crypto.mjs';
 import { DEFAULT_P2P_MODE, P2P_DEFAULTS, P2PNode, normalizeP2PMode, normalizeP2PPort } from './p2p-node.mjs';
 import { punchSession, reverseDialSession } from './p2p.mjs';
@@ -1022,6 +1029,9 @@ export function createAgent(options) {
   // `string | string[][]` form is accepted, and a bare string list such as
   // `['node --test']` cannot reach `.map((prefix) => prefix.join(' '))`.
   const allowedCommands = parseAllowedCommands(options.allowedCommands ?? []);
+  // v1.4.2: the UI-activated Node-code-execution capability. Read before every task, so turning the switch in the
+  // plugin UI takes effect on the next task without restarting the agent; an expired temporary activation denies.
+  const execCapabilityFile = options.execCapabilityFile ?? defaultExecCapabilityFile();
 
   if (!rabbitUrl) throw new TypeError('createAgent: rabbitUrl is required');
   if (!project) throw new TypeError('createAgent: project is required');
@@ -2977,7 +2987,11 @@ export function createAgent(options) {
        */
       let allowed = matchAllowedCommand(commandArgv, allowedCommands);
       let grantAuthorized = false;
+      let capabilityAuthorized = false;
+      let grantAttempted = false;
+      const capabilityStatus = readExecCapability(execCapabilityFile);
       if (allowed.allowed !== true && offer && typeof offer.grant === 'object' && offer.grant !== null) {
+        grantAttempted = true;
         const gatePaths = maintenancePaths();
         const gate = await authorizeWithGrant({
           offer,
@@ -2988,10 +3002,19 @@ export function createAgent(options) {
         if (gate.ok === true) { allowed = { allowed: true, ok: true, grant_id: gate.grantId }; grantAuthorized = true; }
         else allowed = { ok: false, reason_code: gate.code ?? 'GRANT_REJECTED', detail: gate.message };
       }
+      // A capability is a machine-local standing authorization, so it may rescue an allow-list miss -- but never an
+      // explicit grant refusal (replay, expiry, wrong machine). Masking GRANT_REPLAY with a capability would execute a
+      // token the operator already spent, and the envelope would report a reason that names neither decision.
+      if (allowed.allowed !== true && grantAttempted !== true && capabilityStatus.effective === true) {
+        allowed = matchAllowedCommand(commandArgv, effectiveExecCapabilityPrefixes(execCapabilityFile));
+        if (allowed.allowed === true) { capabilityAuthorized = true; warnings.push('EXEC_CAPABILITY: ' + EXEC_CAPABILITY_WARNING); }
+      }
       // One decision, two audiences: the gate decides whether to run, and the envelope records which decision it was.
       const authorization = grantAuthorized
         ? { provenance: 'grant', capability_id: allowed.grant_id ?? null, grant_id: allowed.grant_id ?? null }
-        : { provenance: 'allow-list' };
+        : capabilityAuthorized
+          ? { provenance: 'exec-capability', capability_id: 'node-code-exec', grant_id: null }
+          : { provenance: 'allow-list' };
       if (!allowed.allowed) {
         log('warn', `refused ${offer.task_id}: ${allowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED}`, { argv: commandArgv });
         await finish({
@@ -3182,7 +3205,12 @@ export function createAgent(options) {
 
       for (const stage of plannedStages) {
         // v1.3.10-beta.6: a grant that authorised step 5 covers the whole task, but only for the argv it signed.
-      const stageAllowed = grantAuthorized ? { allowed: true, ok: true } : matchAllowedCommand(stage.command_argv, allowedCommands);
+      const stageAllowList = matchAllowedCommand(stage.command_argv, allowedCommands);
+      const stageAllowed = grantAuthorized
+        ? { allowed: true, ok: true }
+        : stageAllowList.allowed === true
+          ? { allowed: true, ok: true }
+          : capabilityAuthorized ? matchAllowedCommand(stage.command_argv, EXEC_CAPABILITY_PREFIXES) : stageAllowList;
         if (stageAllowed.allowed) continue;
         const code = stageAllowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED;
         if (workspaceState !== null) { try { await removeWorktree({ repoDir: project, worktreeDir: workspaceState.worktreeDir }); } catch { /* best effort */ } }

package/src/chatops/ilink-fleet-bridge.mjs

@@ -372,6 +372,25 @@ export function renderTaskOutcome({ taskId, body }) {
   return `${renderVerdict({ taskId, verdict, machines: rows }).text}`;
 }
 
+/**
+ * Render a per-message handling failure as something the operator can act on.
+ *
+ * The rule this exists for: **every message gets an answer, including the ones that broke something.**
+ * Before this, an exception anywhere in the per-message path escaped the loop, killed the process, and the
+ * chat window went silent with no indication why. A failure is now a reply with the phase, a stable code and
+ * the next step, and the loop continues.
+ *
+ * @param {unknown} error
+ * @param {string} [phase] where it failed: message | parse | reply | dispatch
+ * @returns {string}
+ */
+export function renderBridgeError(error, phase = 'message') {
+  const code = error?.code ?? error?.name ?? 'ERR_UNKNOWN';
+  const message = error?.message ?? String(error ?? '未知错误');
+  return `处理失败（${phase}，${code}）：${String(message).slice(0, 300)}\n`
+    + '可以发送 /help 查看用法，或稍后重试这条指令。';
+}
+
 /** Render a dispatch that never became a task. */
 export function renderFailure(error) {
   return renderDispatchFailure({

package/src/plugin/exec-capability-route.mjs

@@ -0,0 +1,75 @@
+/**
+ * `/api/w2m/capability` — the host half of the UI-activated Node-code-execution switch.
+ *
+ * The composer's capability control (lib/client.js) reads and writes this same-origin route; the route owns
+ * the machine-local file (`~/.w2m/exec-capability.json`) so the browser never touches the filesystem and the
+ * device token never enters the page. The agent reads the same file before every task, which is what makes an
+ * activation effective without restarting the agent.
+ *
+ * Wire:
+ *   GET  /api/w2m/capability            -> { ok, capability: describeExecCapability(...) }
+ *   POST /api/w2m/capability            { state: 'denied'|'temporary'|'permanent', ttl_ms? }
+ *                                       -> { ok, capability }
+ *
+ * The states are the three choices an operator gets: refuse, temporary (24 h default) or permanent. There is no
+ * fourth, and the prefix it can add is fixed in the util module (`node -e`).
+ */
+import {
+  EXEC_CAPABILITY_ROUTE_PATH,
+  describeExecCapability,
+  writeExecCapability,
+} from '../util/exec-capability.mjs';
+
+const NO_STORE = { 'cache-control': 'no-store' };
+
+/**
+ * Mount the route on the host's Connection fetch registry.
+ *
+ * @param {object} ctx Cordis context
+ * @param {{capabilityFile: () => string}} deps
+ * @returns {{mounted: boolean, reason: string|null}}
+ */
+export function registerExecCapabilityRoutes(ctx, deps) {
+  const status = { mounted: false, reason: 'the host has no Connection service' };
+  if (typeof ctx?.inject !== 'function') return status;
+  ctx.inject(['connection'], (webCtx) => {
+    const registry = webCtx?.connection?.fetch;
+    if (registry === undefined || typeof registry.register !== 'function') {
+      status.reason = 'the connection service carries no fetch registry';
+      return;
+    }
+    registry.register({
+      path: EXEC_CAPABILITY_ROUTE_PATH,
+      methods: ['GET', 'POST'],
+      requestBody: 'buffered',
+      fetch: async (request) => {
+        if (request.method !== 'GET' && request.method !== 'POST') {
+          return Response.json({ ok: false, error: request.method + ' is not a method this route answers', reason_code: 'METHOD_NOT_ALLOWED' }, { status: 405, headers: NO_STORE });
+        }
+        const file = deps.capabilityFile();
+        if (request.method === 'GET') {
+          return Response.json({ ok: true, capability: describeExecCapability(file) }, { headers: NO_STORE });
+        }
+        let body = null;
+        try {
+          body = await request.json();
+        } catch { /* a malformed body is refused below */ }
+        if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+          return Response.json({ ok: false, error: 'a JSON body with a state is required', reason_code: 'CAPABILITY_BODY_INVALID' }, { status: 400, headers: NO_STORE });
+        }
+        const written = writeExecCapability(file, {
+          state: body.state,
+          ttl_ms: body.ttl_ms,
+          actor: { kind: 'operator', id: 'plugin-ui', at: new Date().toISOString() },
+        });
+        if (written.ok !== true) {
+          return Response.json({ ok: false, error: written.detail, reason_code: written.code }, { status: 400, headers: NO_STORE });
+        }
+        return Response.json({ ok: true, capability: describeExecCapability(file) }, { headers: NO_STORE });
+      },
+    });
+    status.mounted = true;
+    status.reason = null;
+  });
+  return status;
+}

package/src/plugin/tools.mjs

@@ -184,6 +184,8 @@ import {
 // v1.1.17 chat: the host route behind the composer's fleet-chat panel. The relay side and the
 // `w2m_chat` tool shipped first; this is the browser-facing half that was still missing.
 import { registerChatRoutes } from './fleet-chat-route.mjs';
+import { registerExecCapabilityRoutes } from './exec-capability-route.mjs';
+import { defaultExecCapabilityFile } from '../util/exec-capability.mjs';
 import { createFleetCouncil, fleetCouncilThread } from './council-fleet.mjs';
 import { renderMemoryView } from './memory-view.mjs';
 import { renderMergeHint } from './merge-hint.mjs';
@@ -274,7 +276,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '1.4.1';
+const PLUGIN_VERSION = '1.4.3';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -3482,6 +3484,16 @@ export async function apply(ctx, config = {}) {
   // The composer's fleet-chat panel: `GET/POST /api/w2m/chat`, proxied to the relay's device-gated
   // `/v1/fleet/messages`. Optional like the target routes — a host without Connection keeps every
   // tool and the panel is simply not mounted.
+  // v1.4.2: the UI-activated Node-code-execution capability (`GET/POST /api/w2m/capability`). The composer
+  // control reads and writes it, the agent reads the same file before every task, so an activation takes effect
+  // on the next task without a restart. Optional like the other browser routes.
+  const capabilityRoutes = registerExecCapabilityRoutes(ctx, {
+    capabilityFile: () => defaultExecCapabilityFile(),
+  });
+  if (capabilityRoutes.mounted !== true) {
+    ctx.logger?.warn?.('w2m: the execution-capability control is inactive — ' + capabilityRoutes.reason);
+  }
+
   const chatRoutes = registerChatRoutes(ctx, {
     cfg: () => cfg,
     request,

package/src/util/exec-capability.mjs

@@ -0,0 +1,138 @@
+/**
+ * Node-code-execution capability: the machine-local switch behind the plugin UI.
+ *
+ * The allow-list is a standing decision made by the machine owner in a config file. This module is the
+ * *UI-activated* form of the same decision, scoped to one dangerous ability -- running arbitrary Node code
+ * (`node -e`) -- with an explicit state: denied, temporary (24 h by default) or permanent. The DSH plugin
+ * client renders the switch; the host route writes this file; the agent reads it before every task and
+ * treats an active capability exactly like an additional allow-list prefix.
+ *
+ * Fail-closed rules:
+ *   * a missing, unreadable or malformed file means `denied` (the standing default), never "on";
+ *   * `temporary` whose `expires_at_ms` has passed reads as `denied` and says `expired`, so an expiry
+ *     cannot be mistaken for a configuration error;
+ *   * the only prefix a capability can ever add is `node -e` -- a fixed constant, not caller input.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const EXEC_CAPABILITY_PROTOCOL = 'w2m-exec-capability/v1';
+export const EXEC_CAPABILITY_ROUTE_PATH = '/api/w2m/capability';
+/** The one ability the switch can turn on. Fixed here, never supplied by a request. */
+export const EXEC_CAPABILITY_PREFIXES = Object.freeze([Object.freeze(['node', '-e'])]);
+export const EXEC_CAPABILITY_STATES = Object.freeze(['denied', 'temporary', 'permanent']);
+export const DEFAULT_TEMPORARY_TTL_MS = 24 * 60 * 60 * 1000;
+export const MAX_TEMPORARY_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const EXEC_CAPABILITY_WARNING = 'node code execution: allows any Node code on this machine (RCE)';
+
+export function defaultExecCapabilityFile(home = homedir()) {
+  return join(home, '.w2m', 'exec-capability.json');
+}
+
+/** Normalise one state string; anything unknown is `null` (a caller error, not a default). */
+export function normalizeExecCapabilityState(value) {
+  return typeof value === 'string' && EXEC_CAPABILITY_STATES.includes(value) ? value : null;
+}
+
+/**
+ * Read the capability state. Never throws: a broken file is `denied` with reason `unreadable`/`invalid`.
+ *
+ * @param {string} file
+ * @param {number} [nowMs]
+ * @returns {{state: string, effective: boolean, expires_at_ms: number|null, activated_at_ms: number|null, actor: object|null, reason: string|null}}
+ */
+export function readExecCapability(file, nowMs = Date.now()) {
+  const denied = (reason) => ({ state: 'denied', effective: false, expires_at_ms: null, activated_at_ms: null, actor: null, reason });
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch (error) {
+    return denied(error?.code === 'ENOENT' ? 'absent' : 'unreadable');
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return denied('invalid');
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return denied('invalid');
+  const state = normalizeExecCapabilityState(raw.state);
+  if (state === null) return denied('invalid');
+  if (state === 'denied') return denied(null);
+  const expiresAt = Number.isFinite(raw.expires_at_ms) ? raw.expires_at_ms : null;
+  const activatedAt = Number.isFinite(raw.activated_at_ms) ? raw.activated_at_ms : null;
+  if (state === 'temporary') {
+    if (expiresAt === null) return denied('invalid');
+    if (expiresAt <= nowMs) return { state: 'denied', effective: false, expires_at_ms: expiresAt, activated_at_ms: activatedAt, actor: null, reason: 'expired' };
+  }
+  if (state === 'permanent' && expiresAt !== null) return denied('invalid');
+  return {
+    state,
+    effective: true,
+    expires_at_ms: state === 'temporary' ? expiresAt : null,
+    activated_at_ms: activatedAt,
+    actor: typeof raw.actor === 'object' && raw.actor !== null ? { ...raw.actor } : null,
+    reason: null,
+  };
+}
+
+/** The prefixes an active capability adds, or an empty array when it is denied/expired. */
+export function effectiveExecCapabilityPrefixes(file, nowMs = Date.now()) {
+  return readExecCapability(file, nowMs).effective === true ? EXEC_CAPABILITY_PREFIXES.map((prefix) => [...prefix]) : [];
+}
+
+/**
+ * Write one capability decision. `temporary` requires a TTL and records an absolute expiry.
+ *
+ * @returns {{ok: boolean, code?: string, detail?: string, capability?: object}}
+ */
+export function writeExecCapability(file, input, nowMs = Date.now()) {
+  const state = normalizeExecCapabilityState(input?.state);
+  if (state === null) return { ok: false, code: 'CAPABILITY_STATE_INVALID', detail: 'state must be denied, temporary or permanent' };
+  if (state === 'denied') {
+    try {
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, JSON.stringify({ protocol: EXEC_CAPABILITY_PROTOCOL, state: 'denied', activated_at_ms: nowMs, actor: input.actor ?? null }, null, 2) + '\n');
+    } catch (error) {
+      return { ok: false, code: 'CAPABILITY_WRITE_FAILED', detail: error?.message ?? String(error) };
+    }
+    return { ok: true, capability: readExecCapability(file, nowMs) };
+  }
+  let ttlMs = input?.ttl_ms;
+  if (state === 'temporary') {
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) ttlMs = DEFAULT_TEMPORARY_TTL_MS;
+    if (ttlMs > MAX_TEMPORARY_TTL_MS) return { ok: false, code: 'CAPABILITY_TTL_TOO_LONG', detail: 'temporary activation is limited to ' + MAX_TEMPORARY_TTL_MS + ' ms' };
+    ttlMs = Math.floor(ttlMs);
+  }
+  const record = {
+    protocol: EXEC_CAPABILITY_PROTOCOL,
+    state,
+    activated_at_ms: nowMs,
+    expires_at_ms: state === 'temporary' ? nowMs + ttlMs : null,
+    actor: typeof input?.actor === 'object' && input.actor !== null ? { ...input.actor } : null,
+  };
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(record, null, 2) + '\n');
+  } catch (error) {
+    return { ok: false, code: 'CAPABILITY_WRITE_FAILED', detail: error?.message ?? String(error) };
+  }
+  return { ok: true, capability: readExecCapability(file, nowMs) };
+}
+
+/** The JSON the UI renders: state, effective, remaining time and the one prefix it would allow. */
+export function describeExecCapability(file, nowMs = Date.now()) {
+  const capability = readExecCapability(file, nowMs);
+  return {
+    protocol: EXEC_CAPABILITY_PROTOCOL,
+    state: capability.state,
+    effective: capability.effective,
+    reason: capability.reason,
+    activated_at_ms: capability.activated_at_ms,
+    expires_at_ms: capability.expires_at_ms,
+    remaining_ms: capability.state === 'temporary' && capability.expires_at_ms !== null ? Math.max(0, capability.expires_at_ms - nowMs) : null,
+    allows: capability.effective === true ? EXEC_CAPABILITY_PREFIXES.map((prefix) => prefix.join(' ')) : [],
+    warning: EXEC_CAPABILITY_WARNING,
+  };
+}