@twinsearth/w2m-dsh-plugin 2.2.1 → 2.2.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": "2.2.1"
+    "version": "2.2.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": "2.2.1",
+      "version": "2.2.3",
       "author": {
         "name": "TwinsEarth"
       },
@@ -26,5 +26,5 @@
       ]
     }
   ],
-  "version": "2.2.1"
+  "version": "2.2.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": "2.2.1",
+  "version": "2.2.3",
   "author": {
     "name": "TwinsEarth"
   },

package/CHANGELOG.md

@@ -5,8 +5,33 @@ All notable changes to this project are documented here.
 ## [Unreleased]
 
 - `w2m_intent`: structured intents mapped onto allow-listed commands; unknown actions, parameters and types
-  are refused by name (the fleet does not invent commands).
-
+  are refused by name (the fleet does not invent commands).
+
+## [2.2.3] - 2026-11-05
+
+- Remote desktop (view-only) now reaches 1 frame per second in a fleet. A machine opts in by
+  enabling 远程桌面 in its own settings; the target agent reads that file before consuming a
+  request and before every frame, so enabling or disabling takes effect without an agent restart.
+- The target sends repeated frames instead of one: P2P renews the request from the viewer, and the
+  relay target runs a bounded encrypted-frame stream while the viewer renews its request. The viewer
+  fetches the next relay frame on every 1 Hz poll and re-derives the key when a renewed stream uses a
+  new target ephemeral key.
+- Windows capture uses a once-compiled .NET helper (with the PowerShell path as fallback) so a frame
+  costs hundreds of milliseconds rather than a PowerShell startup; the frame scheduler compensates
+  for capture time to keep the one-second cadence.
+- Tests: target consent (including the localside parent directory), relay streaming at the configured
+  interval, P2P frame streaming and stop, viewer relay frame refresh, and a 1 Hz viewer route probe.
+
+## [2.2.2] - 2026-11-05
+
+- DSH 0.2.2-rc.1 compatibility: composer popups (the dispatch-target menu and the Node-execution menu)
+  now render through a `react-dom` portal under `document.body`. The release candidate puts
+  `container-type: inline-size` on the composer row, which makes that row the containing block for
+  `position: fixed` descendants; the Node-execution menu was positioned relative to the row and its
+  options could not be selected. A portal keeps the viewport coordinates the menus compute.
+- Loader tests: the bundle-fetch helper sends a Fetch `Request` as 0.2.2-rc.1 requires, the real-page
+  probe seeds a Workspace, opens the Node-execution menu and selects temporary execution, and the
+  host route probe confirms `GET/POST /api/w2m/capability` is mounted.
 ## [2.2.1] - 2026-11-01
 
 - Fleet identity is now per-account **home**-first. Each machine records the fleet key it actually joined under `fleet-home.json` beside `device.json`; switching back to an account returns to that account’s previous fleet instead of deriving a new one. This is the “whoever leaves returns by themselves” rule: a first appearance of account B may join B’s account fleet, but an existing home for A is never rewritten by B, and no other machine is moved.

package/README.md

@@ -37,7 +37,8 @@ English | [中文说明](#中文说明)
 ### 功能 6 · 全局文件夹读写黑白名单：保护系统盘 & 个人/工作文件夹
 DSH 默认的权限模型是“限制 or 全开”，一旦放开就难以精细控制。本插件在官方沙箱之上追加全局文件夹读写黑白名单，为系统盘（`C:\Windows`、`Program Files`、`/etc`、`/usr` 等）和个人/工作文件夹建立明确的读/写边界，避免 AI 或跨机任务误触不该动的路径。这一设计来自实际重装系统后的教训：粗粒度的“全开”代价太高，黑白名单把“绝对不允许”与“经常要放行”的路径变成可配置的硬规则。v2.0.4 起提供两种策略：**小白模式（默认）**只保留黑名单强制拒绝（内置 Windows/Program Files 等默认保护文件夹，路径操作每 3 秒最多自动放行一次），其余全部放行；**高级模式**需手动切换，保留白名单预算、待审批队列与 10 秒无人应答自动放行。
 
-### 功能 7 ·远程桌面（开发中）
+### 功能 7 · 远程桌面（仅查看，1 帧/秒）
+在设置里打开「远程桌面」后，可在远程桌面页选择在线目标并连接。目标机也必须打开同一开关，表示同意被编队内其他机器查看；只传输画面，不发送鼠标/键盘输入。目标以 1 帧/秒采集并加密：优先 P2P 直连，P2P 不通时走 relay 的加密帧通道（relay 只看到密文，看不到 JPEG）。查看端每秒拉取最新一帧，因此最低可用帧率是 1 帧/秒；网络和采集耗时会决定实际帧率。目标关闭开关后，下一次采集立即停止。
 
 ## 安装
 
@@ -92,7 +93,7 @@ w2m-mcp --help
 # 复制进你自己的 codex/mcp-servers.toml
 [mcp_servers.w2m]
 command = "npx"
-args = ["-y", "@twinsearth/w2m-dsh-plugin@2.2.1", "w2m-mcp"]
+args = ["-y", "@twinsearth/w2m-dsh-plugin@2.2.3", "w2m-mcp"]
 ```
 
 ### 5. 验证过的 release tarball（离线）

package/codex/mcp-servers.toml

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

package/docs/acceptance/2.2.2/RELEASE-2220.json

@@ -0,0 +1,25 @@
+{
+  "version": "2.2.2",
+  "case": "RELEASE-2220",
+  "kind": "positive",
+  "machines": [
+    "b53a37f4-1464-4512-9259-33a7df091e3e"
+  ],
+  "executed_at": "2026-11-04T20:16:04.717Z",
+  "executor": "lead",
+  "task_id": "pre-release-2220-1793823364724",
+  "requirement": "v2.2.2: DSH 0.2.2-rc.1 users can open the Node-execution menu and select temporary execution from the composer",
+  "commands": [
+    ["node", "--test", "--test-force-exit", "test/client-bundle.test.mjs"],
+    ["node", "--test", "--test-force-exit", "test/loader-entry.test.mjs"]
+  ],
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "client": "test/client-bundle.test.mjs 36/36: popup menus portal to document.body when react-dom is available and fall back inline without it",
+      "loader": "test/loader-entry.test.mjs 10/10 against the packed 2.2.2 tarball in the real DSH 0.2.2-rc.1 Loader and its own Edge page; the route probe finds /api/w2m/capability and W2M_CAPABILITY_PROBE=1 opens the Node-execution menu and selects temporary execution",
+      "dsh": "the installed runtime is @deepseek-ai/dsh-desktop-runtime 0.2.2-rc.1 (resources/app.asar), not the 0.2.1-rc.5 profile pins",
+      "scope": "local code and packed artifact only; no installed profile was edited by the tests; the release is published separately"
+    }
+  }
+}

package/docs/acceptance/2.2.3/RELEASE-2230.json

@@ -0,0 +1,32 @@
+{
+  "version": "2.2.3",
+  "case": "RELEASE-2230",
+  "kind": "positive",
+  "machines": [
+    "b53a37f4-1464-4512-9259-33a7df091e3e"
+  ],
+  "executed_at": "2026-11-05T02:16:57.551Z",
+  "executor": "lead",
+  "task_id": "pre-release-2230-1793845017571",
+  "requirement": "v2.2.3: a fleet target that enables remote desktop serves repeated encrypted view frames to an online viewer at a one-second cadence, over P2P when available and the encrypted relay frame channel otherwise",
+  "commands": [
+    ["node", "--test", "--test-force-exit", "test/view-capture.test.mjs", "test/view-frame-channel.test.mjs", "test/view-consent.test.mjs"],
+    ["node", "--test", "--test-force-exit", "test/relay-target.test.mjs", "test/remote-view-route.test.mjs"],
+    ["node", "--test", "--test-force-exit", "test/client-bundle.test.mjs"],
+    ["node", "--test", "--test-force-exit", "test/loader-entry.test.mjs"]
+  ],
+  "result": {
+    "outcome": "ok",
+    "assertions": {
+      "capture": "test/view-capture.test.mjs 4/4: unsupported platform, macOS capture, spawnSync status, and the transport size refusal",
+      "p2p": "test/view-frame-channel.test.mjs 4/4: consent denial, handshake, repeated frames at the configured interval, and input-frame refusal",
+      "consent": "test/view-consent.test.mjs 4/4: default deny, local enable, localside/ parent fallback, and W2M_VIEW_ALLOW overrides",
+      "relay": "test/relay-target.test.mjs 3/3: first sealed frame, repeated frames at the interval, and no request consumption while consent is off",
+      "viewer": "test/remote-view-route.test.mjs 3/3: P2P session, P2P refusal, and a fresh relay frame on each 1 Hz poll",
+      "client": "test/client-bundle.test.mjs 36/36: the client bundle still loads with the remote-view settings and page copy",
+      "loader": "test/loader-entry.test.mjs 10/10 against the packed 2.2.3 tarball in the real DSH 0.2.2-rc.1 Loader and Edge page",
+      "capture_timing": "local Windows real-capture relay stream produced 3 frames at 1.067 s, 2.087 s and 3.123 s (1.02-1.06 s cadence); the fast helper itself measured 0.23-0.40 s after compilation",
+      "scope": "local code and tests only; no installed profile was edited by the tests; release is published separately"
+    }
+  }
+}

package/lib/client.js

@@ -66,6 +66,37 @@ window.__ModuleLoader__.load({
 
     const React = require('react');
 
+    /**
+     * Render a popup under `document.body`.
+     *
+     * DSH 0.2.2-rc.1 puts `container-type: inline-size` on the composer row. Layout containment makes
+     * that row the containing block for `position: fixed` descendants, so a menu rendered inside the
+     * composer slot is positioned relative to the row (and can be clipped) instead of the viewport.
+     * A portal keeps the viewport coordinates the menus already compute. `react-dom` is a platform
+     * seed in the Web shell; the lazy require keeps this bundle loadable where only React is present,
+     * and the inline fallback preserves the old behavior if the portal cannot be created.
+     *
+     * @param {object|null} node - menu element.
+     * @returns {object|null} portal element, or the original node.
+     */
+    let portalRuntime;
+    let portalUnavailable = false;
+    function portalNode(node) {
+      if (node === null || portalUnavailable) return node;
+      if (typeof document === 'undefined' || document.body === null || document.body === undefined) return node;
+      try {
+        if (portalRuntime === undefined) portalRuntime = require('react-dom');
+        if (typeof portalRuntime?.createPortal !== 'function') {
+          portalUnavailable = true;
+          return node;
+        }
+        return portalRuntime.createPortal(node, document.body);
+      } catch {
+        portalUnavailable = true;
+        return node;
+      }
+    }
+
     // -------------------------------------------------------------------------------------------
     // Wire
     // -------------------------------------------------------------------------------------------
@@ -2285,7 +2316,7 @@ function UpdateSettingsSection() {
       };
 
       const menu = open && placement !== null
-        ? h('div', {
+        ? portalNode(h('div', {
             className: cls('menu'),
             role: 'listbox',
             'aria-label': t('targetLabel', { name: label }),
@@ -2381,7 +2412,7 @@ function UpdateSettingsSection() {
                 ? h('div', { key: 'hint', className: cls('relayHint') }, t('relayFold', { count: relayFold.hidden_count }))
                 : null,
             ]),
-          ])
+          ]))
         : null;
 
       return h(React.Fragment, null, [
@@ -2595,8 +2626,8 @@ function UpdateSettingsSection() {
           h('span', { key: 'text' }, enabled ? '已开启' : '已关闭'),
         ]),
         h('div', { key: 'hint', style: { fontSize: '12px', opacity: 0.75, lineHeight: 1.5 } },
-          '仅查看，不发送鼠标/键盘输入。P1 目标为最高 1 帧/秒；实际帧率取决于目标机性能与网络。媒体优先 P2P，relay 只承载信令。'),
-        h('div', { key: 'status', style: { fontSize: '12px', opacity: 0.6 } }, 'P1 当前为本机回环查看；远端采集/P2P 在后续切片接入。'),
+          '开启后可查看其他机器；本机也会允许编队内其他机器查看，仅画面，不发送鼠标/键盘输入。目标帧率为 1 帧/秒；实际帧率取决于目标机性能与网络。媒体优先 P2P，P2P 不通时走加密 relay 帧通道。'),
+        h('div', { key: 'status', style: { fontSize: '12px', opacity: 0.6 } }, '要查看某台机器，那台机器也需要开启此开关。选择目标后点「连接」；远端画面每秒刷新一次。'),
       ]);
     }
 
@@ -2662,7 +2693,7 @@ function UpdateSettingsSection() {
       const ready = enabled && frame?.data_base64;
       return h('div', { style: { padding: '16px', display: 'grid', gap: '12px', maxWidth: '1100px' } }, [
         h('div', { key: 'title', style: { fontSize: '16px', fontWeight: 600 } }, '远程桌面 · 仅查看'),
-        h('div', { key: 'state', style: { fontSize: '13px', opacity: 0.8 } }, enabled ? (session ? ('P2P 会话：' + (session.machine_id ?? '') + (session.encrypted ? '（加密）' : '（未加密）')) : '未连接目标') : '插件设置中尚未开启远程桌面。'),
+        h('div', { key: 'state', style: { fontSize: '13px', opacity: 0.8 } }, enabled ? (session ? ('远程会话：' + (session.machine_id ?? '') + (session.encrypted ? '（加密）' : '（未加密）') + ' · ' + (session.channel === 'relay' ? '加密 relay' : 'P2P')) : '未连接目标') : '插件设置中尚未开启远程桌面。'),
         h('div', { key: 'controls', style: { display: 'flex', gap: '8px', alignItems: 'center', flexWrap: 'wrap' } }, [
           h('select', { key: 'target', value: target, disabled: !enabled, onChange: (event) => setTarget(event.target.value), style: { minWidth: '180px' } }, machines.length === 0 ? h('option', { value: '' }, '无在线机器') : machines.map((machine) => h('option', { key: machine.machine_id, value: machine.machine_id }, (machine.name ?? machine.machine_id)))),
           h('button', { key: 'connect', type: 'button', disabled: !enabled || target === '' || session !== null, onClick: connect }, '连接'),
@@ -2671,10 +2702,10 @@ function UpdateSettingsSection() {
         ]),
         h('div', { key: 'canvas', style: { minHeight: '320px', border: '1px solid var(--dsw-alias-border-l2)', borderRadius: 'var(--dsw-radius-sm)', overflow: 'hidden', display: 'flex', alignItems: 'center', justifyContent: 'center', background: 'var(--dsw-alias-bg-layer-1)' } }, ready
           ? h('img', { src: 'data:' + (frame.mime ?? 'image/jpeg') + ';base64,' + frame.data_base64, alt: '远程桌面画面', style: { maxWidth: '100%', maxHeight: '70vh', display: 'block' } })
-          : h('span', { style: { opacity: 0.6, fontSize: '13px' } }, !enabled ? '尚未开启' : (error ? ('查看失败：' + error) : (session ? '等待远端帧…' : '本机回环预览（选择目标后点连接）')))),
+          : h('span', { style: { opacity: 0.6, fontSize: '13px' } }, !enabled ? '尚未开启' : (error ? ('查看失败：' + error) : (session ? '等待远端帧…' : '选择在线目标后点「连接」')))),
         h('div', { key: 'statusline', style: { fontSize: '12px', opacity: 0.7, display: 'flex', gap: '14px', flexWrap: 'wrap' } }, [
           h('span', { key: 'fps' }, '1 fps 上限'),
-          h('span', { key: 'channel' }, '通道：' + (session ? (session.channel === 'relay' ? '加密中继' : 'P2P') : '本机回环')),
+          h('span', { key: 'channel' }, '通道：' + (session ? (session.channel === 'relay' ? '加密中继' : 'P2P') : '未连接')),
           h('span', { key: 'cap' }, '采集：' + (stats?.capture_ms ?? '—') + 'ms'),
           h('span', { key: 'bytes' }, '帧：' + (stats?.bytes ?? '—') + 'B'),
           h('span', { key: 'age' }, '最近帧：' + (stats?.at ?? '—')),
@@ -3106,7 +3137,7 @@ const CHAT_EMOJIS = CHAT_COMMANDS;
       };
 
       const menu = open && placement !== null
-        ? h('div', {
+        ? portalNode(h('div', {
             className: 'w2mCap_menu',
             role: 'menu',
             'aria-label': t('capMenuLabel'),
@@ -3118,7 +3149,7 @@ const CHAT_EMOJIS = CHAT_COMMANDS;
             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, [
@@ -3449,6 +3480,7 @@ const CHAT_EMOJIS = CHAT_COMMANDS;
       exports.FleetChat = FleetChat;
     exports.injectStyle = injectStyle;
     exports.makeTranslator = makeTranslator;
+    exports.portalNode = portalNode;
     return module.exports;
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/w2m-dsh-plugin",
-  "version": "2.2.1",
+  "version": "2.2.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": {
@@ -71,7 +71,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/exec-capability.test.mjs test/secondary-link.test.mjs test/bootstrap-cli.test.mjs test/bootstrap.test.mjs test/windows-hidden-task.test.mjs test/relay-failover.test.mjs test/npm-update.test.mjs test/agent-start-nonblocking.test.mjs test/fleet-chat-capture.test.mjs test/capture-route.test.mjs test/update-resolver.test.mjs test/agent-identity-safe.test.mjs test/re-pair-stale-token.test.mjs test/gpw-folder-policy.test.mjs test/gpw-activation.test.mjs test/gpw-hardening.test.mjs test/gpw-tamper-gate.test.mjs test/gpw-persistence.test.mjs test/gpw-colors.test.mjs test/gpw-recent-fold.test.mjs test/gpw-auto-approve.test.mjs test/joint-dev-dispatch.test.mjs test/joint-dev-loop.test.mjs test/joint-dev-audit.test.mjs test/joint-dev-redline.test.mjs test/relay-redline-guard.test.mjs test/relay-p0-projection.test.mjs test/guarded-dispatch.test.mjs test/p0-single-matcher.test.mjs test/path-policy.test.mjs test/path-policy-fs.test.mjs test/gpw-inheritance-table.test.mjs test/gpw-policy-adapter.test.mjs test/target-policy.test.mjs test/relay-redline-audit.test.mjs test/relay-repair-ledger.test.mjs test/relay-purge-blobs.test.mjs test/relay-scrub.test.mjs test/joint-dev-plan-store.test.mjs test/relay-basepath-blobs.test.mjs test/operator-token.test.mjs test/relay-health-capabilities.test.mjs test/joint-relay-dispatch.test.mjs test/operator-token-route.test.mjs test/relay-scrub-task-projection.test.mjs test/operator-key-approval.test.mjs test/relay-offer-journal.test.mjs test/joint-r5-wiring.test.mjs test/p1-hardening.test.mjs test/joint-merge-engine.test.mjs test/artifact-ref-dir-sink.test.mjs test/chat-sticker-guard.test.mjs test/relay-task-progress.test.mjs test/gpw-modes.test.mjs test/joint-cli.test.mjs test/joint-command-hash.test.mjs test/joint-dispatch-audit.test.mjs test/tools-cancel-auth.test.mjs test/fleet-mirror.test.mjs test/sink-git-ssh.test.mjs test/agent-sse-watchdog.test.mjs test/version-gate.test.mjs test/joint-merge-cli.test.mjs test/joint-progress.test.mjs test/project-room-truncation.test.mjs test/chat-crypto-aad.test.mjs test/agent-artifact-delivery.test.mjs test/dataplane-sink-route.test.mjs test/artifact-sink-e2e.test.mjs test/project-room-persistence.test.mjs test/project-room-disk-persistence.test.mjs test/project-stream-route.test.mjs test/chat-v2-gate.test.mjs test/xiangqi.test.mjs test/xfer-foundation.test.mjs test/xfer-ferry.test.mjs test/xfer-publish.test.mjs test/xfer-want-block.test.mjs test/p2p-cipher-diag.test.mjs test/chacha-fallback.test.mjs test/fleet-binding.test.mjs test/fleet-home.test.mjs test/fleet-config.test.mjs test/fleet-config-route.test.mjs test/xfer-channel.test.mjs test/p2p-race.test.mjs test/path-scheduler.test.mjs test/transport.test.mjs test/iroh-sidecar.test.mjs test/discovery.test.mjs test/p2p-rtt.test.mjs test/artifact-ref-v3.test.mjs test/xfer-recovery.test.mjs test/xfer-router.test.mjs test/remote-s2-capture.test.mjs test/view-capture.test.mjs test/view-frame-channel.test.mjs test/remote-view-route.test.mjs test/remote-media.test.mjs test/view-session-key.test.mjs test/remote-requests.test.mjs test/relay-target.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/secondary-link.test.mjs test/bootstrap-cli.test.mjs test/bootstrap.test.mjs test/windows-hidden-task.test.mjs test/relay-failover.test.mjs test/npm-update.test.mjs test/agent-start-nonblocking.test.mjs test/fleet-chat-capture.test.mjs test/capture-route.test.mjs test/update-resolver.test.mjs test/agent-identity-safe.test.mjs test/re-pair-stale-token.test.mjs test/gpw-folder-policy.test.mjs test/gpw-activation.test.mjs test/gpw-hardening.test.mjs test/gpw-tamper-gate.test.mjs test/gpw-persistence.test.mjs test/gpw-colors.test.mjs test/gpw-recent-fold.test.mjs test/gpw-auto-approve.test.mjs test/joint-dev-dispatch.test.mjs test/joint-dev-loop.test.mjs test/joint-dev-audit.test.mjs test/joint-dev-redline.test.mjs test/relay-redline-guard.test.mjs test/relay-p0-projection.test.mjs test/guarded-dispatch.test.mjs test/p0-single-matcher.test.mjs test/path-policy.test.mjs test/path-policy-fs.test.mjs test/gpw-inheritance-table.test.mjs test/gpw-policy-adapter.test.mjs test/target-policy.test.mjs test/relay-redline-audit.test.mjs test/relay-repair-ledger.test.mjs test/relay-purge-blobs.test.mjs test/relay-scrub.test.mjs test/joint-dev-plan-store.test.mjs test/relay-basepath-blobs.test.mjs test/operator-token.test.mjs test/relay-health-capabilities.test.mjs test/joint-relay-dispatch.test.mjs test/operator-token-route.test.mjs test/relay-scrub-task-projection.test.mjs test/operator-key-approval.test.mjs test/relay-offer-journal.test.mjs test/joint-r5-wiring.test.mjs test/p1-hardening.test.mjs test/joint-merge-engine.test.mjs test/artifact-ref-dir-sink.test.mjs test/chat-sticker-guard.test.mjs test/relay-task-progress.test.mjs test/gpw-modes.test.mjs test/joint-cli.test.mjs test/joint-command-hash.test.mjs test/joint-dispatch-audit.test.mjs test/tools-cancel-auth.test.mjs test/fleet-mirror.test.mjs test/sink-git-ssh.test.mjs test/agent-sse-watchdog.test.mjs test/version-gate.test.mjs test/joint-merge-cli.test.mjs test/joint-progress.test.mjs test/project-room-truncation.test.mjs test/chat-crypto-aad.test.mjs test/agent-artifact-delivery.test.mjs test/dataplane-sink-route.test.mjs test/artifact-sink-e2e.test.mjs test/project-room-persistence.test.mjs test/project-room-disk-persistence.test.mjs test/project-stream-route.test.mjs test/chat-v2-gate.test.mjs test/xiangqi.test.mjs test/xfer-foundation.test.mjs test/xfer-ferry.test.mjs test/xfer-publish.test.mjs test/xfer-want-block.test.mjs test/p2p-cipher-diag.test.mjs test/chacha-fallback.test.mjs test/fleet-binding.test.mjs test/fleet-home.test.mjs test/fleet-config.test.mjs test/fleet-config-route.test.mjs test/xfer-channel.test.mjs test/p2p-race.test.mjs test/path-scheduler.test.mjs test/transport.test.mjs test/iroh-sidecar.test.mjs test/discovery.test.mjs test/p2p-rtt.test.mjs test/artifact-ref-v3.test.mjs test/xfer-recovery.test.mjs test/xfer-router.test.mjs test/remote-s2-capture.test.mjs test/view-capture.test.mjs test/view-frame-channel.test.mjs test/view-consent.test.mjs test/remote-view-route.test.mjs test/remote-media.test.mjs test/view-session-key.test.mjs test/remote-requests.test.mjs test/relay-target.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": "2.2.1",
+  "version": "2.2.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

@@ -73,6 +73,7 @@ import { createXferFrameRouter } from './transfer/router.mjs';
 import { captureScreen } from './view/capture.mjs';
 import { createViewTarget } from './view/frame-channel.mjs';
 import { startRelayViewTarget } from './view/relay-target.mjs';
+import { viewAllowed } from './view/consent.mjs';
 import { DEFAULT_P2P_MODE, P2P_DEFAULTS, P2PNode, normalizeP2PMode, normalizeP2PPort } from './p2p-node.mjs';
 import { punchSession, reverseDialSession } from './p2p.mjs';
 import { createSigner } from '../signing.mjs';
@@ -1149,6 +1150,7 @@ export function createAgent(options) {
   /** P0-a: xfer.* frames arriving on a P2P channel are routed here, not to task dispatch. */
   const xferRouter = createXferFrameRouter();
   let viewTargets = null;
+  let viewRelayRunner = null;
   /**
    * What each task's direct channel actually was, for the result envelope.
    *
@@ -3978,8 +3980,8 @@ let attemptAttached = false;
       let target = viewTargets.get(key);
       if (target === undefined || payload.type === 'view.hello') {
         target = createViewTarget({
-          capture: () => captureScreen({}),
-          allow: process.env.W2M_VIEW_ALLOW === '1',
+          capture: () => captureScreen({ fast: true }),
+          allow: () => viewAllowed(stateDir),
           send: (frame) => { try { event.channel.send(frame); } catch { /* peer gone */ } },
         });
         viewTargets.set(key, target);
@@ -4434,6 +4436,10 @@ let attemptAttached = false;
     if (idleHeartbeatTimer) clearInterval(idleHeartbeatTimer);
     idleHeartbeatTimer = null;
     heartbeat?.stop();
+    viewRelayRunner?.stop();
+    viewRelayRunner = null;
+    for (const target of viewTargets?.values() ?? []) target?.stop?.();
+    viewTargets = null;
     runAbort?.abort();
     streamAbort?.abort();
     // Final snapshot: a reader must be able to tell "stopped" from "crashed
@@ -4470,10 +4476,17 @@ let attemptAttached = false;
     // the first heartbeat: "is an agent running here?" is the first question a
     // remote operator asks (task-16).
     publishState();
-    const viewRelay = process.env.W2M_VIEW_ALLOW === '1'
-      ? startRelayViewTarget({ rabbitUrl: baseUrl, token: () => identity.device_token, machineId: identity.machine_id, capture: (options) => captureScreen(options), log })
-      : null;
-    void viewRelay;
+    // The poller always runs; the consent file is checked before a request is consumed and before
+    // every frame, so enabling remote viewing in the settings page takes effect without an agent
+    // restart. A disabled machine never consumes a viewer request.
+    viewRelayRunner = startRelayViewTarget({
+      rabbitUrl: baseUrl,
+      token: () => identity.device_token,
+      machineId: identity.machine_id,
+      capture: (options) => captureScreen({ ...(options ?? {}), fast: true }),
+      allow: () => viewAllowed(stateDir),
+      log,
+    });
     if (statePublishIntervalMs > 0) {
       statePublishTimer = setInterval(() => publishState(), statePublishIntervalMs);
       // Never keep the process alive just to refresh a diagnostics file.

package/src/agent/view/capture.mjs

@@ -6,7 +6,7 @@
  * without a reason.
  */
 import { spawnSync } from 'node:child_process';
-import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -59,7 +59,93 @@ function windowsCaptureScript(maxBytes) {
 
 
 /**
- * @param {{platform?: NodeJS.Platform, run?: Function, tempRoot?: string, maxBytes?: number}} [options]
+ * A tiny compiled Windows helper for 1 fps capture.
+ *
+ * Starting PowerShell costs 1.5-3 s per frame on this host, so a 1 fps stream
+ * written as "spawn PowerShell every second" is not 1 fps. The helper is compiled
+ * once with the in-box .NET Framework compiler and then invoked like any small
+ * executable; the fallback keeps working on machines without that compiler.
+ */
+const WINDOWS_HELPER_SOURCE = `using System;
+using System.Drawing;
+using System.Drawing.Imaging;
+using System.IO;
+using System.Windows.Forms;
+class W2MCapture {
+  static void Main(string[] args) {
+    int max = int.Parse(args[1]);
+    var b = Screen.PrimaryScreen.Bounds;
+    using (var src = new Bitmap(b.Width, b.Height)) {
+      using (var g = Graphics.FromImage(src)) g.CopyFromScreen(b.Left, b.Top, 0, 0, src.Size);
+      int[] widths = new int[] { 960, 800, 640 };
+      var codec = Array.Find(ImageCodecInfo.GetImageEncoders(), c => c.MimeType == "image/jpeg");
+      foreach (int w in widths) {
+        int h = Math.Max(1, (int)Math.Round(b.Height * (double)w / b.Width));
+        using (var dst = new Bitmap(w, h)) {
+          using (var dg = Graphics.FromImage(dst)) {
+            dg.InterpolationMode = System.Drawing.Drawing2D.InterpolationMode.HighQualityBicubic;
+            dg.DrawImage(src, 0, 0, w, h);
+          }
+          foreach (int q in new int[] { 40, 30 }) {
+            using (var ms = new MemoryStream()) {
+              var ep = new EncoderParameters(1);
+              ep.Param[0] = new EncoderParameter(System.Drawing.Imaging.Encoder.Quality, (long)q);
+              dst.Save(ms, codec, ep);
+              var bytes = ms.ToArray();
+              if (bytes.Length <= max) {
+                File.WriteAllBytes(args[0], bytes);
+                return;
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+
+let windowsHelperState;
+
+/** Resolve, compiling once, the fast Windows capture helper. */
+function windowsFastHelper() {
+  if (windowsHelperState !== undefined) return windowsHelperState;
+  try {
+    const dir = join(tmpdir(), 'w2m-view-fast');
+    mkdirSync(dir, { recursive: true });
+    const exe = join(dir, 'w2m-capture-v1.exe');
+    if (existsSync(exe)) { windowsHelperState = exe; return exe; }
+    const source = join(dir, 'w2m-capture-v1.cs');
+    writeFileSync(source, WINDOWS_HELPER_SOURCE, 'utf8');
+    const cscCandidates = [
+      join(process.env.WINDIR ?? 'C:\\Windows', 'Microsoft.NET', 'Framework64', 'v4.0.30319', 'csc.exe'),
+      join(process.env.WINDIR ?? 'C:\\Windows', 'Microsoft.NET', 'Framework', 'v4.0.30319', 'csc.exe'),
+    ];
+    const csc = cscCandidates.find(candidate => existsSync(candidate));
+    if (csc !== undefined) {
+      spawnSync(csc, [
+        '/nologo', '/target:exe', `/out:${exe}`,
+        '/r:System.Drawing.dll', '/r:System.Windows.Forms.dll', source,
+      ], { timeout: 60_000, windowsHide: true, encoding: 'utf8' });
+    }
+    if (!existsSync(exe)) {
+      // Some hosts deny csc.exe while allowing PowerShell. Add-Type compiles the same source
+      // once and writes the executable, after which every frame is a small process spawn.
+      const psQuote = value => `'${value.replace(/'/g, "''")}'`;
+      const command = `Add-Type -Path ${psQuote(source)} -OutputAssembly ${psQuote(exe)} -OutputType ConsoleApplication -ReferencedAssemblies System.Drawing.dll,System.Windows.Forms.dll`;
+      spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', command], {
+        timeout: 60_000, windowsHide: true, encoding: 'utf8',
+      });
+    }
+    windowsHelperState = existsSync(exe) ? exe : null;
+    return windowsHelperState;
+  } catch {
+    windowsHelperState = null;
+    return null;
+  }
+}
+
+/**
+ * @param {{platform?: NodeJS.Platform, run?: Function, tempRoot?: string, maxBytes?: number, fast?: boolean}} [options]
  * @returns {{ok: true, code: string, mime: string, data: Buffer, base64: string, bytes: number, capture_ms: number, width: number|null, height: number|null}
  *   | {ok: false, code: string, error: string, capture_ms: number}}
  */
@@ -73,12 +159,32 @@ export function captureScreen(options = {}) {
     let width = null;
     let height = null;
     if (platform === 'win32') {
-      const result = run(['powershell.exe', '-NoProfile', '-NonInteractive', '-STA', '-ExecutionPolicy', 'Bypass', '-Command', windowsCaptureScript(maxBytes)], { timeoutMs: 20000 });
-      // `spawnSync` reports the exit code as `status`; `code` is the execFile-shaped field
-      // and is undefined here, which made every successful capture look like a denial.
-      if (result.status !== 0) return { ok: false, code: VIEW_CAPTURE_CODE.DENIED, error: `PowerShell capture failed (exit ${result.status ?? 'null'}${result.signal ? ', signal ' + result.signal : ''}${result.error?.message ? ', ' + result.error.message : ''})`, capture_ms: Date.now() - started };
-      base64 = String(result.stdout ?? '').trim().split(/\r?\n/).filter(Boolean).pop() ?? '';
-      if (!/^[A-Za-z0-9+/=]{100,}$/.test(base64)) return { ok: false, code: VIEW_CAPTURE_CODE.FAILED, error: 'PowerShell returned no JPEG', capture_ms: Date.now() - started };
+      if (options.fast === true) {
+        const helper = windowsFastHelper();
+        if (helper !== null) {
+          const dir = mkdtempSync(join(options.tempRoot ?? tmpdir(), 'w2m-view-fast-'));
+          const file = join(dir, 'frame.jpg');
+          try {
+            const result = run([helper, file, String(maxBytes)], { timeoutMs: 5000, encoding: 'utf8' });
+            if (result.status === 0 && existsSync(file)) {
+              const data = readFileSync(file);
+              if (data.length >= 1000) base64 = data.toString('base64');
+            }
+          } catch {
+            // Fall through to the PowerShell capture path.
+          } finally {
+            try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ }
+          }
+        }
+      }
+      if (base64 === null) {
+        const result = run(['powershell.exe', '-NoProfile', '-NonInteractive', '-STA', '-ExecutionPolicy', 'Bypass', '-Command', windowsCaptureScript(maxBytes)], { timeoutMs: 20000 });
+        // `spawnSync` reports the exit code as `status`; `code` is the execFile-shaped field
+        // and is undefined here, which made every successful capture look like a denial.
+        if (result.status !== 0) return { ok: false, code: VIEW_CAPTURE_CODE.DENIED, error: `PowerShell capture failed (exit ${result.status ?? 'null'}${result.signal ? ', signal ' + result.signal : ''}${result.error?.message ? ', ' + result.error.message : ''})`, capture_ms: Date.now() - started };
+        base64 = String(result.stdout ?? '').trim().split(/\r?\n/).filter(Boolean).pop() ?? '';
+        if (!/^[A-Za-z0-9+/=]{100,}$/.test(base64)) return { ok: false, code: VIEW_CAPTURE_CODE.FAILED, error: 'PowerShell returned no JPEG', capture_ms: Date.now() - started };
+      }
     } else if (platform === 'darwin') {
       const dir = mkdtempSync(join(options.tempRoot ?? tmpdir(), 'w2m-view-'));
       const file = join(dir, 'frame.jpg');

package/src/agent/view/consent.mjs

@@ -0,0 +1,36 @@
+/**
+ * Target-side remote-view consent.
+ *
+ * Turning on "远程桌面" on a machine is an explicit statement that the machine may be viewed by
+ * the fleet; `W2M_VIEW_ALLOW=0` remains an operator override that denies even an enabled file.
+ * The file is written by the host settings route under the same state directory the agent uses.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** The per-machine settings file shared with `src/plugin/remote-view-route.mjs`. */
+export const REMOTE_VIEW_CONFIG_FILE = 'remote-view.json';
+
+/**
+ * Whether this machine may serve view frames.
+ *
+ * @param {string} stateDir - agent state directory.
+ * @param {NodeJS.ProcessEnv} [env] - process environment for the operator override.
+ * @returns {boolean}
+ */
+export function viewAllowed(stateDir, env = process.env) {
+  if (env.W2M_VIEW_ALLOW === '0') return false;
+  if (env.W2M_VIEW_ALLOW === '1') return true;
+  // The agent's `--state` is the `localside/` child of the plugin's state directory, while the
+  // settings route writes beside `device.json` one level up. Check the agent directory first (an
+  // explicit deployment may keep the file there), then the plugin root.
+  for (const file of [join(stateDir, REMOTE_VIEW_CONFIG_FILE), join(dirname(stateDir), REMOTE_VIEW_CONFIG_FILE)]) {
+    try {
+      const value = JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+      if (value?.enabled === true || value?.allow === true) return true;
+    } catch {
+      // Try the next location.
+    }
+  }
+  return false;
+}

package/src/agent/view/frame-channel.mjs

@@ -48,13 +48,44 @@ export function parseViewFrame(payload) {
   return frame;
 }
 
-/** @param {{capture:Function, allow?:boolean, send:Function, maxBytes?:number, fps?:number}} deps */
-export function createViewTarget({ capture, allow = false, send, maxBytes = 96 * 1024, fps = 1 } = {}) {
+/** @param {{capture:Function, allow?:boolean|Function, send:Function, maxBytes?:number, fps?:number, intervalMs?:number, maxFrames?:number}} deps */
+export function createViewTarget({ capture, allow = false, send, maxBytes = 96 * 1024, fps = 1, intervalMs, maxFrames = 300 } = {}) {
   if (typeof capture !== 'function' || typeof send !== 'function') return { ok: false, code: VIEW_CODE.BAD_FRAME };
   let seq = 0;
+  let frames = 0;
   let stopped = false;
   let vk = null;
+  let timer = null;
+  let sessionId = null;
+  const delay = Number.isInteger(intervalMs) && intervalMs > 0 ? intervalMs : Math.max(100, Math.round(1000 / Math.max(1, fps)));
+  const allowed = () => (typeof allow === 'function' ? allow() === true : allow === true);
   const reply = (frame) => { try { send(JSON.stringify(frame)); } catch { /* channel gone */ } };
+  const stopTimer = () => { if (timer !== null) clearTimeout(timer); timer = null; };
+  const schedule = (waitMs) => {
+    if (stopped || vk === null) return;
+    timer = setTimeout(() => { timer = null; tick(); }, Math.max(0, waitMs));
+    if (typeof timer.unref === 'function') timer.unref();
+  };
+  const fail = (code) => {
+    stopped = true;
+    stopTimer();
+    reply({ type: VIEW_FRAME.ERROR, code, session_id: sessionId });
+  };
+  const tick = () => {
+    if (stopped || vk === null || sessionId === null) { stopTimer(); return; }
+    if (!allowed()) { fail(VIEW_CODE.CONSENT_REQUIRED); return; }
+    if (maxFrames > 0 && frames >= maxFrames) { stopTimer(); return; }
+    const started = Date.now();
+    const result = capture({ maxBytes });
+    if (result?.ok !== true) { fail(result?.code ?? VIEW_CODE.CAPTURE_FAILED); return; }
+    let ct;
+    try { ct = sealViewFrame(vk, result.data ?? Buffer.from(result.base64 ?? '', 'base64')); }
+    catch { fail(VIEW_CODE.VK_BAD); return; }
+    seq += 1;
+    frames += 1;
+    reply({ type: VIEW_FRAME.FRAME, session_id: sessionId, seq, ts_ms: Date.now(), mime: result.mime ?? 'image/jpeg', bytes: result.bytes, enc: 'aes-256-gcm', ct });
+    if (maxFrames <= 0 || frames < maxFrames) schedule(delay - (Date.now() - started));
+  };
   return {
     ok: true,
     handle(payload) {
@@ -65,30 +96,34 @@ export function createViewTarget({ capture, allow = false, send, maxBytes = 96 *
       }
       const frame = parseViewFrame(payload);
       if (frame === null) return false;
-      if (frame.type === VIEW_FRAME.STOP) { stopped = true; return true; }
+      if (frame.type === VIEW_FRAME.STOP) { stopped = true; stopTimer(); return true; }
       if (frame.type === VIEW_FRAME.HELLO) {
-        if (typeof frame.public_key !== 'string' || frame.public_key === '') { reply({ type: VIEW_FRAME.ERROR, code: VIEW_CODE.VK_BAD, session_id: frame.session_id ?? null }); return true; }
+        stopTimer();
+        stopped = false;
+        frames = 0;
+        sessionId = typeof frame.session_id === 'string' ? frame.session_id : null;
+        if (typeof frame.public_key !== 'string' || frame.public_key === '') { reply({ type: VIEW_FRAME.ERROR, code: VIEW_CODE.VK_BAD, session_id: sessionId }); return true; }
         try {
           const side = createViewSide();
           vk = side.finish(frame.public_key).key;
-          reply({ type: VIEW_FRAME.HELLO_ACK, session_id: frame.session_id ?? null, public_key: side.public_key });
-        } catch { reply({ type: VIEW_FRAME.ERROR, code: VIEW_CODE.VK_BAD, session_id: frame.session_id ?? null }); }
+          reply({ type: VIEW_FRAME.HELLO_ACK, session_id: sessionId, public_key: side.public_key });
+        } catch { reply({ type: VIEW_FRAME.ERROR, code: VIEW_CODE.VK_BAD, session_id: sessionId }); }
         return true;
       }
       if (frame.type !== VIEW_FRAME.REQUEST) return true;
-      if (allow !== true) { reply({ type: VIEW_FRAME.ERROR, code: VIEW_CODE.CONSENT_REQUIRED, session_id: frame.session_id ?? null }); return true; }
-      if (stopped) { reply({ type: VIEW_FRAME.ERROR, code: VIEW_CODE.DISABLED, session_id: frame.session_id ?? null }); return true; }
-      if (vk === null) { reply({ type: VIEW_FRAME.ERROR, code: VIEW_CODE.VK_REQUIRED, session_id: frame.session_id ?? null }); return true; }
-      const result = capture({ maxBytes });
-      if (result?.ok !== true) { reply({ type: VIEW_FRAME.ERROR, code: result?.code ?? VIEW_CODE.CAPTURE_FAILED, session_id: frame.session_id ?? null }); return true; }
-      let ct;
-      try { ct = sealViewFrame(vk, result.data ?? Buffer.from(result.base64 ?? '', 'base64')); }
-      catch { reply({ type: VIEW_FRAME.ERROR, code: VIEW_CODE.VK_BAD, session_id: frame.session_id ?? null }); return true; }
-      seq += 1;
-      reply({ type: VIEW_FRAME.FRAME, session_id: frame.session_id ?? null, seq, ts_ms: Date.now(), mime: result.mime ?? 'image/jpeg', bytes: result.bytes, enc: 'aes-256-gcm', ct });
+      if (!allowed()) { fail(VIEW_CODE.CONSENT_REQUIRED); return true; }
+      if (stopped) { fail(VIEW_CODE.DISABLED); return true; }
+      if (vk === null) { fail(VIEW_CODE.VK_REQUIRED); return true; }
+      if (typeof frame.session_id === 'string' && frame.session_id !== '') sessionId = frame.session_id;
+      // A renewal is a fresh viewer request; its budget starts over so an actively polling viewer
+      // keeps the stream alive, while a viewer that disappears leaves the target to expire its budget.
+      frames = 0;
+      stopTimer();
+      tick();
       return true;
     },
-    stats() { return { seq, stopped, allow: allow === true, fps, max_bytes: maxBytes, encrypted: vk !== null }; },
+    stop() { stopped = true; stopTimer(); vk = null; sessionId = null; },
+    stats() { return { seq, frames, stopped, allow: allowed(), fps, intervalMs: delay, max_bytes: maxBytes, encrypted: vk !== null }; },
   };
 }
 

package/src/agent/view/relay-target.mjs

@@ -5,6 +5,11 @@
  * it derives VK from the viewer's ephemeral public key, captures a JPEG, seals
  * it, and posts opaque ciphertext at ≤1 fps. Nothing is written to disk and the
  * relay never sees plaintext.
+ *
+ * The poller is deliberately always running: the operator may enable remote
+ * viewing after the agent started, and `allow` is consulted before every request
+ * and every frame. A disabled machine never consumes a viewer request, so a
+ * later enable does not lose the request to an earlier no-op.
  */
 import { createViewSide, sealViewFrame } from './session-key.mjs';
 
@@ -13,65 +18,104 @@ export const REMOTE_FRAME_PATH = '/v1/remote/frame';
 
 /**
  * @param {{rabbitUrl:string, token:()=>string|null, machineId:string, capture:Function,
- *   intervalMs?:number, maxBytes?:number, fetchImpl?:Function, log?:Function, maxFrames?:number}} deps
+ *   allow?:()=>boolean, intervalMs?:number, maxBytes?:number, maxFrames?:number,
+ *   fetchImpl?:Function, log?:Function}} deps
  */
 export function startRelayViewTarget(deps) {
   const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
-  const intervalMs = Number.isInteger(deps.intervalMs) ? deps.intervalMs : 1000;
-  const maxBytes = Number.isInteger(deps.maxBytes) ? deps.maxBytes : 96 * 1024;
-  const maxFrames = Number.isInteger(deps.maxFrames) ? deps.maxFrames : 60;
+  const intervalMs = Number.isInteger(deps.intervalMs) && deps.intervalMs > 0 ? deps.intervalMs : 1000;
+  // Stay below the relay broker's 47 KiB ciphertext cap after base64 framing.
+  const maxBytes = Number.isInteger(deps.maxBytes) && deps.maxBytes > 0 ? deps.maxBytes : 40 * 1024;
+  const maxFrames = Number.isInteger(deps.maxFrames) && deps.maxFrames > 0 ? deps.maxFrames : 60;
+  const allow = typeof deps.allow === 'function' ? deps.allow : () => process.env.W2M_VIEW_ALLOW === '1';
   const base = String(deps.rabbitUrl ?? '').replace(/\/+$/, '');
   let stopped = false;
-  let timer = null;
-  let busy = false;
+  let pollTimer = null;
+  let frameTimer = null;
+  let active = null;
+
+  const endStream = () => {
+    if (frameTimer !== null) clearTimeout(frameTimer);
+    frameTimer = null;
+    active = null;
+  };
+  const scheduleFrame = (waitMs) => {
+    if (stopped || active === null) return;
+    frameTimer = setTimeout(() => { frameTimer = null; void tick(); }, Math.max(0, waitMs));
+    if (typeof frameTimer.unref === 'function') frameTimer.unref();
+  };
 
-  const stop = () => { stopped = true; if (timer !== null) clearInterval(timer); timer = null; };
+  const tick = async () => {
+    if (stopped || active === null || active.inFlight === true) return;
+    if (!allow()) { endStream(); return; }
+    if (active.frames >= maxFrames) { endStream(); return; }
+    active.inFlight = true;
+    const current = active;
+    const started = Date.now();
+    try {
+      const captured = deps.capture({ maxBytes });
+      if (captured?.ok !== true) { endStream(); return; }
+      let ct;
+      try { ct = sealViewFrame(current.vk, captured.data ?? Buffer.from(captured.base64 ?? '', 'base64')); }
+      catch { endStream(); return; }
+      try {
+        const response = await fetchImpl(base + REMOTE_FRAME_PATH, {
+          method: 'POST',
+          headers: { authorization: 'Bearer ' + deps.token(), 'content-type': 'application/json' },
+          body: JSON.stringify({ session_id: current.sessionId, target: deps.machineId, ct, public_key: current.side.public_key }),
+        });
+        if (response.ok !== true) { endStream(); return; }
+        current.frames += 1;
+        if (current.frames >= maxFrames) endStream();
+        else scheduleFrame(intervalMs - (Date.now() - started));
+      } catch {
+        // The next poll may establish a fresh session; one transient relay failure
+        // ends this stream rather than emitting a burst of stale frames.
+        endStream();
+      }
+    } finally {
+      current.inFlight = false;
+    }
+  };
 
   const poll = async () => {
-    if (stopped || busy) return;
+    if (stopped || active !== null || !allow()) return;
     const token = deps.token();
     if (typeof token !== 'string' || token === '') return;
-    busy = true;
+    let response;
     try {
-      const response = await fetchImpl(base + REMOTE_REQUEST_PATH + '?target=' + encodeURIComponent(deps.machineId), {
+      response = await fetchImpl(base + REMOTE_REQUEST_PATH + '?target=' + encodeURIComponent(deps.machineId), {
         headers: { authorization: 'Bearer ' + token },
       });
-      if (stopped || !response.ok) { busy = false; return; }
-      const body = await response.json().catch(() => null);
-      if (body?.ok !== true || typeof body.viewer_public_key !== 'string') { busy = false; return; }
-      const side = createViewSide();
-      let vk;
-      try { vk = side.finish(body.viewer_public_key).key; } catch { busy = false; return; }
-      const sessionId = body.session_id;
-      let frames = 0;
-      const tick = async () => {
-        if (stopped || frames >= maxFrames) { busy = false; return; }
-        frames += 1;
-        const captured = deps.capture({ maxBytes });
-        if (captured?.ok !== true) { busy = false; return; }
-        let ct;
-        try { ct = sealViewFrame(vk, captured.data ?? Buffer.from(captured.base64 ?? '', 'base64')); } catch { busy = false; return; }
-        try {
-          await fetchImpl(base + REMOTE_FRAME_PATH, {
-            method: 'POST',
-            headers: { authorization: 'Bearer ' + deps.token(), 'content-type': 'application/json' },
-            body: JSON.stringify({ session_id: sessionId, target: deps.machineId, ct, public_key: side.public_key }),
-          });
-        } catch { /* relay transient; next tick retries */ }
-      };
-      await tick();
-      timer = setInterval(() => { void tick(); }, intervalMs);
-      if (typeof timer.unref === 'function') timer.unref();
-    } finally {
-      busy = false;
-    }
+    } catch { return; }
+    if (stopped || !response.ok) return;
+    const body = await response.json().catch(() => null);
+    if (body?.ok !== true || typeof body.viewer_public_key !== 'string' || typeof body.session_id !== 'string') return;
+    const side = createViewSide();
+    let vk;
+    try { vk = side.finish(body.viewer_public_key).key; } catch { return; }
+    active = { sessionId: body.session_id, side, vk, frames: 0, inFlight: false };
+    await tick();
   };
 
-  const pollTimer = setInterval(() => { void poll(); }, intervalMs);
+  pollTimer = setInterval(() => { void poll(); }, intervalMs);
   if (typeof pollTimer.unref === 'function') pollTimer.unref();
   void poll();
   return {
-    stop() { stopped = true; if (timer !== null) clearInterval(timer); clearInterval(pollTimer); },
-    setStop() { stop(); },
+    stop() {
+      stopped = true;
+      if (pollTimer !== null) clearInterval(pollTimer);
+      pollTimer = null;
+      endStream();
+    },
+    stats() {
+      return {
+        stopped,
+        active: active === null ? null : { session_id: active.sessionId, frames: active.frames },
+        interval_ms: intervalMs,
+        max_bytes: maxBytes,
+        max_frames: maxFrames,
+      };
+    },
   };
 }

package/src/plugin/remote-view-route.mjs

@@ -134,7 +134,7 @@ export function registerRemoteViewRoutes(ctx, deps = {}) {
           if (dialled?.ok !== true) p2pError = dialled?.error ?? 'P2P_DIAL_FAILED';
         }
         if (dialled?.ok === true) {
-          active = { mode: 'p2p', machineId, sessionId, channel: dialled.channel, side, vk: null, encrypted: dialled.channel?.encryption?.encrypted === true, latest: null, error: null, startedAt: Date.now() };
+          active = { mode: 'p2p', machineId, sessionId, channel: dialled.channel, side, vk: null, encrypted: dialled.channel?.encryption?.encrypted === true, latest: null, error: null, p2pRenewAt: Date.now() + 10_000, startedAt: Date.now() };
           listener = (event) => {
             const frame = payloadJson(event?.payload);
             if (frame === null || frame?.session_id !== sessionId) return;
@@ -165,7 +165,7 @@ export function registerRemoteViewRoutes(ctx, deps = {}) {
         if (relayRequest.ok !== true) {
           return Response.json({ ok: false, code: 'P2P_UNAVAILABLE', error: p2pError, relay_error: relayRequest.error ?? null }, { status: 502, headers: NO_STORE });
         }
-        active = { mode: 'relay', machineId, sessionId, channel: null, side, vk: null, encrypted: true, latest: null, error: null, startedAt: Date.now() };
+        active = { mode: 'relay', machineId, sessionId, channel: null, side, vk: null, encrypted: true, latest: null, error: null, lastRelayAt: 0, relayRenewAt: Date.now() + 10_000, startedAt: Date.now() };
         return Response.json({ ok: true, machine_id: machineId, session_id: sessionId, encrypted: true, channel: 'relay', relay_ttl_ms: relayRequest.ttl_ms ?? null }, { headers: NO_STORE });
       },
     });
@@ -182,17 +182,41 @@ export function registerRemoteViewRoutes(ctx, deps = {}) {
       fetch: async () => {
         if (readConfig(file).enabled !== true) return Response.json({ ok: false, code: 'VIEW_DISABLED' }, { status: 403, headers: NO_STORE });
         if (active !== null) {
-          if (active.mode === 'relay' && active.latest === null) {
+          // A P2P target stops after its frame budget. The viewer's 1 Hz poll renews the request
+          // every ten seconds so an open page keeps the stream alive; closing the page stops the
+          // renewals and the target's bounded budget expires on its own.
+          if (active.mode === 'p2p' && Date.now() >= active.p2pRenewAt) {
+            active.p2pRenewAt = Date.now() + 10_000;
+            try {
+              void active.channel.send(JSON.stringify({ type: 'view.request', session_id: active.sessionId, machine_id: active.machineId, fps: 1, max_bytes: maxBytes }));
+            } catch { /* peer gone */ }
+          }
+          // The viewer polls at 1 Hz. Relay media is latest-frame-wins, so each poll asks the relay
+          // for the next frame instead of serving the first frame forever.
+          if (active.mode === 'relay' && (active.latest === null || Date.now() - active.lastRelayAt >= 900)) {
+            active.lastRelayAt = Date.now();
+            // The target's relay stream is bounded (60 frames). A renewed request sits in the
+            // mailbox and is consumed by the next poll after that stream ends, so the viewer keeps
+            // receiving frames without reconnect churn.
+            if (Date.now() >= active.relayRenewAt) {
+              active.relayRenewAt = Date.now() + 10_000;
+              void postRelayRequest({ stateDir: deps.stateDir, machineId: active.machineId, sessionId: active.sessionId, publicKey: active.side.public_key });
+            }
             const got = await fetchRelayFrame({ stateDir: deps.stateDir, sessionId: active.sessionId, machineId: active.machineId });
             if (got.ok === true) {
               try {
-                if (active.vk === null) {
-                  if (typeof got.public_key !== 'string') { active.error = 'VIEW_VK_REQUIRED'; return Response.json({ ok: false, code: active.error }, { status: 502, headers: NO_STORE }); }
-                  active.vk = active.side.finish(got.public_key).key;
-                }
+                // A renewed relay stream creates a new target ephemeral keypair; re-derive the
+                // viewer side whenever the target publishes a different public key.
+                if (typeof got.public_key === 'string') active.vk = active.side.finish(got.public_key).key;
+                if (active.vk === null) { active.error = 'VIEW_VK_REQUIRED'; return Response.json({ ok: false, code: active.error }, { status: 502, headers: NO_STORE }); }
                 const plaintext = openViewFrame(active.vk, got.ct);
-                if (plaintext.length <= maxBytes) active.latest = { seq: null, mime: 'image/jpeg', bytes: plaintext.length, data_base64: plaintext.toString('base64'), at: new Date().toISOString(), encrypted: true, channel: 'relay' };
+                if (plaintext.length <= maxBytes) {
+                  active.latest = { seq: null, mime: 'image/jpeg', bytes: plaintext.length, data_base64: plaintext.toString('base64'), at: new Date().toISOString(), encrypted: true, channel: 'relay' };
+                  active.error = null;
+                }
               } catch { active.error = 'VIEW_VK_BAD'; }
+            } else if (got.waiting !== true) {
+              active.error = 'VIEW_RELAY_UNAVAILABLE';
             }
           }
           if (active.latest !== null) return Response.json({ ok: true, ...active.latest }, { headers: NO_STORE });

package/src/plugin/tools.mjs

@@ -296,7 +296,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 = '2.2.1';
+const PLUGIN_VERSION = '2.2.3';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;