dsh-codex-style-computer-use 1.2.0-rc.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ltmroberthk915
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# Computer Use · Codex-style desktop control
+
+Windows desktop computer use for **DeepSeek Harness**: 18 desktop tools plus an Agent activation entry that observe and drive
+native Windows applications through prebuilt C# workers included in the package. No PowerShell 7,
+SDK, terminal commands or install-time builds are needed.
+
+English | [中文](README.zh.md)
+
+Windows only (`os: win32`). Requires Node.js ≥ 22 and the .NET Framework 4.x that Windows ships with.
+
+## What it does
+
+- **Observe** — window list, screenshots (region / JPEG / PNG / downscaled), a Set-of-Marks map of
+  clickable elements, and the UI Automation tree with exact `AutomationId`s.
+- **Act** — click, move, drag, scroll, select a text range, type, press keys, and drive controls
+  through their own UI Automation patterns instead of blind coordinates.
+- **Batch** — one `computer_batch` call runs a list of actions serially and stops at the first
+  failure, so a known sequence costs one model round trip instead of ten.
+- **Ask** — `computer_ask` raises a question on the same chat card DSH uses for `ask_user_question`,
+  with no countdown.
+- **A human brake that reaches the model** — a stop is pushed into the running session, so the agent
+  learns it was interrupted instead of discovering it on the next turn.
+
+The tools read the desktop; they do not read your files. The only file the plugin writes on its own
+is the Worker binary in `%LOCALAPPDATA%\dsh-computer-use\worker\`, plus the audit log and screenshots
+under `$DSH_HOME/data/computer-use/`.
+
+## Install and update in dsh-market
+
+Search **computer-use** and select **dsh-codex-style-computer-use**, by **ltmroberthk915** (npm maintainer: **ltmroberthk**). Click **Install**. Later, click **Update** or **Update all** in the market. The package includes both native helpers; no PowerShell 7 or build permission is needed.
+
+If the catalog has not synced yet, use **Settings → Plugins → Add plugin**, enter `dsh-codex-style-computer-use`, and install. This also creates an ordinary registry installation that can be updated from the market. If DSH reports **restart required**, fully exit DSH from its tray menu and reopen it.
+
+**Migrating an older Git/tarball installation from this repository:** remove the old **dsh-computer-use** entry in the market, then install **dsh-codex-style-computer-use**. The unscoped npm name `dsh-computer-use` belongs to a different repository; do not install it as an upgrade of this plugin. A Git installation cannot switch its dependency identity just by fetching a new commit. After this one-time UI migration, use normal market updates. Existing `computer_*` tool names and the `computer-use` settings namespace are retained.
+
+The GitHub Release also includes `dsh-computer-use.tgz` for offline/manual installation; registry installation is the default for market updates.
+
+CLI users (web profile):
+
+```sh
+dsh plugin --profile web add dsh-codex-style-computer-use
+```
+
+## The bundled skill
+
+The driving tools stay locked until the session produces a receipt phrase that exists only inside
+`skills/computer-use/SKILL.md`. That is deliberate — it is the strongest honest version of "read the
+manual before driving", because no tool layer can see whether a model read a document.
+
+The plugin registers the bundled skill through `ctx.skills.register()` when available. If that service is absent, `computer_use_activate` returns the same manual, its absolute source path and the scoped tool list. The receipt and all existing approval/brake checks still apply.
+
+## Shared input in 1.2.0-rc.2
+
+This pre-release introduces immediate human takeover, automatic waiting after 2 seconds of continued input, and continuation after 3 quiet seconds. Waiting happens locally without model polling. Interrupted writes require a fresh readback and are never blindly replayed. Host cancellation releases accepted automation-owned input without creating a new persistent pause. Existing DSH Pet/main-window and original-topmost handling is retained.
+
+The configured GLM 5.3 Max, GLM 5.3 Flash and DeepSeek Flash routes passed a controlled continuation-protocol test. Native input and physical hotkeys were verified separately; this is not a general desktop or vision benchmark. See [release verification](docs/RELEASE-1.2.0-rc.2.md) for scope.
+
+## On-demand controls in 1.1
+
+- **Per-Agent tools:** idle Agents see `computer_use_activate`, `computer_ctrl` and `computer_ask`. A successful computer-use skill load, receipt or activation exposes the 18 existing tools plus the activation entry to that Agent. Other Agents and children activate independently. Native calls and Node `run_code` are supported. Activation does not start control or release a human brake.
+- **Observed UIA targets:** a scoped name/id query returns an opaque target handle. Use it for pattern actions; opt-in `rebind:true` allows unique identity or semantic recovery after replacement in the same window. Changed context, ambiguity and incomplete scans refuse. Broad queries skip recovery handles unless `targets:true`; creating witnesses for a large list costs extra native work.
+- **Incremental observations:** pass the previous observation ID as `since` with the same query. Deltas preserve additions, changes, removals and ordering. Each Agent retains 64 complete snapshots; `snapshot` retrieves an exact historical result. Missing bases, changed scope, incomplete evidence or a larger delta fall back to full output.
+
+See [the detailed protocol](skills/computer-use/references/progressive-control.md) for cache limits and recovery boundaries. UIA snapshots preserve provider-returned fields within existing provider limits; historical retrieval is not fresh outcome verification.
+
+## Tools
+
+| Group | Tools |
+|---|---|
+| Activate | `computer_use_activate` |
+| Observe | `computer_state` `computer_shot` `computer_marks` `computer_uia` |
+| Act | `computer_click` `computer_move` `computer_drag` `computer_scroll` `computer_select` `computer_key` `computer_type` `computer_uia_act` `computer_window` `computer_clip` |
+| Flow | `computer_wait` `computer_batch` |
+| Meta | `computer_ask` `computer_ctrl` |
+
+`computer_marks` returns numbered marks for the elements it found on screen; `computer_marks {shot:true}` also saves an annotated image. `computer_shot` returns a plain screenshot and, on image-capable routes, a native image attachment. A mark is a snapshot ID: it is validated against window
+identity and sampled pixels before any input is dispatched, so a stale mark is refused rather than
+clicked at the wrong place.
+
+## Approval modes
+
+`automationMode` is set in the plugin's settings and defaults to `standard`:
+
+| Mode | Observation | Actuation |
+|---|---|---|
+| `read-only` | allowed | denied |
+| `standard` | allowed | every action asks through the host's approval card |
+| `autonomous` | allowed | allowed, high-risk operations still ask |
+| `unrestricted` | allowed | allowed (worker failsafe and rate limit still apply) |
+
+High-risk operations (closing a window, `alt+f4`, `win+r`, and the like) ask in every mode. Password
+fields are detected through UI Automation's `IsPassword` and refused by default.
+
+## Safety model
+
+- **Shared input** — physical typing, scrolling, mouse movement and mouse buttons immediately yield control. Continued input or a held key/button for 2 seconds enters automatic waiting. After all keys/buttons are released and 3 seconds pass without physical input, the agent takes a fresh observation and continues the authorized task. A brief touch also waits for the 3-second quiet interval. A gentle pale-yellow edge gradient shows human ownership.
+- **Manual pause** — only physical `Ctrl+Esc` raises a persistent input brake; `Ctrl+Alt+R` resumes. Ordinary Esc, typing, scrolling, pointer distance/frequency and the screen corner do not create this pause. Explicit question/diagnostic holds remain separate.
+- **Exit** — `Ctrl+Alt+Q` ends the session: the overlay goes away, its listeners are torn down, and
+  further actuation is refused until a later turn opens a new one.
+- **The brake is a fact about the machine, not one process** — the engaged state is persisted, and
+  every worker adopts it, including one started later from a shell.
+- **Audit** — every actuation is appended to `$DSH_HOME/data/computer-use/audit.jsonl` with argument
+  sanitisation.
+- **Kill switch for the plugin itself** — `DSH_COMPUTER_USE_KILL=1` makes the plugin refuse to start;
+  `dryRun: true` simulates actuations and only logs them.
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---:|---|
+| `automationMode` | `standard` | approval mode (above) |
+| `progressiveTools` | `true` | per-Agent activation; `false` keeps the original 18 global tools |
+| `dryRun` | `false` | simulate actuations, log only |
+| `maxActionsPerMinute` | `60` | core-level actuation rate limit |
+| `annotateMarks` | `true` | draw Set-of-Marks boxes on screenshots |
+| `workerExe` | `""` | explicit worker path; empty = autodiscover or compile |
+| `snapshotDir` | `""` | screenshot directory; empty = `$DSH_HOME/data/computer-use/shots` |
+
+## MCP server
+
+`mcp/` is a zero-dependency MCP stdio server over the same core, for clients that speak MCP rather
+than Cordis:
+
+```sh
+node mcp/src/index.js
+```
+
+## Development
+
+The repository ships the guard suite that protects the invariants above — the cycle lifetime, the
+ask/brake protocol, the operation classification, the skill gate, and the bundled-skill wiring:
+
+```sh
+pwsh -NoProfile -ExecutionPolicy Bypass -File build/run-guards.ps1   # all guards
+node build/verify-tools-schema.mjs                                   # tool-schema load guard
+```
+
+The tool definitions are compiled through the real `@deepseek-ai/dsh-tools` DSL, so a schema mistake
+fails here instead of taking the host's plugin tree down on restart. Some guards compile the native
+worker and are Windows-only.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,132 @@
+# Computer Use · Codex 风格桌面操控
+
+给 **DeepSeek Harness** 用的 Windows 桌面操控插件：18 个桌面工具加一个 Agent 激活入口，通过一个 C# worker
+观察并驱动原生 Windows 应用。发布包已包含编译好的原生组件，无需安装 PowerShell 7、SDK 或执行编译命令。
+
+[English](README.md) | 中文
+
+仅支持 Windows（`os: win32`）。需要 Node.js ≥ 22 与 Windows 自带的 .NET Framework 4.x。
+
+## 它能做什么
+
+- **观察** —— 窗口列表、截图（区域 / JPEG / PNG / 降采样）、可点元素的 Set-of-Marks 编号图，
+  以及带精确 `AutomationId` 的 UI Automation 树。
+- **操作** —— 点击、移动、拖拽、滚动、选中文本区间、键入、按键，并可走控件**自身的 UI
+  Automation 模式**，而不是盲猜坐标。
+- **批量** —— 一次 `computer_batch` 串行执行一组动作，遇错即停，因此一段已知流程只花一轮模型往返。
+- **提问** —— `computer_ask` 把问题发到 DSH 与 `ask_user_question` 相同的那张聊天卡片上，且没有倒计时。
+- **能传到模型的人为刹车** —— 停止事件被推入正在运行的会话，agent 当场知道自己被打断，
+  而不是等到下一轮才发现。
+
+工具读的是桌面，不读你的文件。插件自己只写三处：worker 二进制
+（`%LOCALAPPDATA%\dsh-computer-use\worker\`）、审计日志与截图（`$DSH_HOME/data/computer-use/`）。
+
+## 在 dsh-market 安装和更新
+
+搜索 **computer-use**，选择 **dsh-codex-style-computer-use**，作者 **ltmroberthk915**（npm 维护者 **ltmroberthk**），点击**安装**。以后直接点市场里的**更新**或**全部更新**。两份原生组件都已随包提供，无需终端、PowerShell 7、SDK 或手改构建白名单。
+
+目录尚未同步时，可在 **设置 → 插件 → 添加插件** 输入 `dsh-codex-style-computer-use` 安装；这同样是可由市场更新的 npm 安装。如果界面提示**需要重启**，从托盘彻底退出 DSH 后重新打开。
+
+**已有本仓库旧 Git/tgz 版本：**在市场卸载旧的 **dsh-computer-use**，再安装 **dsh-codex-style-computer-use**。npm 上的无 scope 包 `dsh-computer-use` 属于另一仓库，不能用作本插件的更新。旧 Git 依赖不会因仓库改名自动迁移；完成这一次界面内迁移后，后续使用普通市场更新即可。原有 `computer_*` 工具名与 `computer-use` 设置命名空间保留。
+
+GitHub Release 仍提供 `dsh-computer-use.tgz`，供离线或手动安装。市场自动更新优先使用 npm 包。
+
+网页版的命令行安装方式：
+
+```sh
+dsh plugin --profile web add dsh-codex-style-computer-use
+```
+
+## 随包 skill
+
+驱动类工具会被锁住，直到会话给出那句只存在于 `skills/computer-use/SKILL.md` 里的回执短语。
+这是刻意的——没有任何工具层能"看见"模型是否读过文档，这是"先读规程再动手"最诚实的一种实现。
+
+插件在宿主提供 skills 服务时通过 `ctx.skills.register()` 注册随包规程。服务缺失时，`computer_use_activate` 也能返回同一份规程、源文件绝对路径及当前 Agent 的工具列表。回执门禁和既有审批、刹车检查仍然有效。
+
+## 1.2.0-rc.2 的人机共用输入
+
+本预发布版采用“立即让权 → 持续输入 2 秒进入等待 → 静默 3 秒后继续”。等待由本地事件完成，不消耗模型轮询。中途被打断的写入先读回实际结果，避免重复执行。宿主取消任务时释放自动化实际按下的输入，不新增持续暂停。此前 DSH Pet 主窗口识别和原有置顶位恢复修复均保留。
+
+已配置的 GLM 5.3 Max、GLM 5.3 Flash 和 DeepSeek Flash 通过受控续作协议测试；原生操作与实体热键另行验证。这些结果不代表任意真实桌面或视觉任务的成功率，详见[发布验证说明](docs/RELEASE-1.2.0-rc.2.md)。
+
+## 1.1 的按需控制
+
+- **按 Agent 加载：**未激活时暴露 `computer_use_activate`、`computer_ctrl`、`computer_ask`。成功读取 computer-use skill、确认规程或调用激活入口后，该 Agent 获得原有 18 个工具，加入口共 19 个。其他 Agent 和子 Agent 独立启用，支持原生调用和 Node `run_code`。激活本身不启动控制，也不释放人为刹车。
+- **已观察的 UIA 目标：**指定窗口和 name/id 的聚焦查询默认生成 target 句柄。控件重建时，显式 `rebind:true` 才允许在同一窗口内进行唯一身份或语义匹配。上下文变化、歧义、扫描不完整时拒绝动作。宽查询需 `targets:true` 才生成恢复句柄，避免普通观察承担额外开销。
+- **增量观察：**重复相同查询并传入上一 observation 的 `since`，返回新增、变化、删除及顺序信息。每 Agent 保留最近 64 份完整快照，`snapshot` 可取回确切的历史结果。缺少基线、范围变化、证据不完整或增量更大时自动回退全量。
+
+保留的是提供器实际返回的完整字段，沿用原有提供器限制；历史快照不代替动作后的新验证。缓存上限和恢复边界见[详细协议](skills/computer-use/references/progressive-control.md)。
+
+## 工具
+
+| 分组 | 工具 |
+|---|---|
+| 激活 | `computer_use_activate` |
+| 观察 | `computer_state` `computer_shot` `computer_marks` `computer_uia` |
+| 操作 | `computer_click` `computer_move` `computer_drag` `computer_scroll` `computer_select` `computer_key` `computer_type` `computer_uia_act` `computer_window` `computer_clip` |
+| 流程 | `computer_wait` `computer_batch` |
+| 元 | `computer_ask` `computer_ctrl` |
+
+`computer_marks` 返回屏幕上元素的编号列表；`computer_marks {shot:true}` 额外保存对应的标注图。`computer_shot` 返回普通截图，在支持图片输入的模型路由上直接附带图片。mark 是一次**快照
+ID**：派发输入前会核对窗口身份与采样像素，因此过期的 mark 会被拒绝，而不是点到错误的位置。
+
+## 审批模式
+
+`automationMode` 在插件设置里配置，默认 `standard`：
+
+| 模式 | 观察 | 操作 |
+|---|---|---|
+| `read-only` | 允许 | 拒绝 |
+| `standard` | 允许 | 每个动作都经宿主审批卡确认 |
+| `autonomous` | 允许 | 允许，高危动作仍需确认 |
+| `unrestricted` | 允许 | 允许（worker 自身的失效保护与限速仍在） |
+
+高危动作（关闭窗口、`alt+f4`、`win+r` 等）在任何模式下都要确认。
+密码框通过 UI Automation 的 `IsPassword` 识别，默认拒绝输入。
+
+## 安全模型
+
+- **人机共用输入** —— 实体键盘、滚轮、鼠标移动或按钮操作立即让出控制。持续输入或按住键/按钮 2 秒进入自动等待；全部松开并静默 3 秒后，重新观察目标并继续已授权任务。短暂触碰也等待 3 秒静默。人操作时显示温和的淡黄色边缘渐变。
+- **人工暂停** —— 只有实体 `Ctrl+Esc` 触发持续输入刹车，`Ctrl+Alt+R` 恢复。普通 Esc、打字、滚动、鼠标距离/频率和屏幕左上角不再触发这种暂停；显式提问、诊断暂停保持独立。
+- **退出** —— `Ctrl+Alt+Q` 结束会话：覆盖层消失、监听全部拆除，后续注入被拒，直到之后某一轮重新开启。
+- **刹车是关于机器的事实，不属于某一个进程** —— 闩锁状态落盘，每个 worker 都会遵守，包括之后从命令行启动的。
+- **审计** —— 每次操作连同脱敏后的参数追加到 `$DSH_HOME/data/computer-use/audit.jsonl`。
+- **插件级开关** —— `DSH_COMPUTER_USE_KILL=1` 让插件拒绝启动；`dryRun: true` 只模拟并记录。
+
+## 配置
+
+| 键 | 默认 | 含义 |
+|---|---:|---|
+| `automationMode` | `standard` | 审批模式（见上） |
+| `progressiveTools` | `true` | 按 Agent 激活；设为 `false` 可保留原有 18 个全局工具 |
+| `dryRun` | `false` | 只模拟操作并记录 |
+| `maxActionsPerMinute` | `60` | 核心层操作限速 |
+| `annotateMarks` | `true` | 在截图上绘制 Set-of-Marks 方框 |
+| `workerExe` | `""` | 显式指定 worker 路径；留空则自动发现或编译 |
+| `snapshotDir` | `""` | 截图目录；留空为 `$DSH_HOME/data/computer-use/shots` |
+
+## MCP 服务
+
+`mcp/` 是建立在同一核心之上的零依赖 MCP stdio 服务，供只讲 MCP、不讲 Cordis 的客户端使用：
+
+```sh
+node mcp/src/index.js
+```
+
+## 开发
+
+仓库自带守卫套件，保护上面这些不变量——循环生命周期、提问/刹车协议、操作分类、skill 门禁，
+以及随包 skill 的注册接线：
+
+```sh
+pwsh -NoProfile -ExecutionPolicy Bypass -File build/run-guards.ps1   # 全部守卫
+node build/verify-tools-schema.mjs                                   # 工具 schema 加载守卫
+```
+
+工具定义走真实的 `@deepseek-ai/dsh-tools` DSL 编译，因此 schema 写错会在这里失败，
+而不是在宿主重启时把整棵插件树带崩。部分守卫会编译原生 worker，仅 Windows 可跑。
+
+## 许可
+
+MIT —— 见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# cordis.patch.yml — dsh-computer-use bundle layer.
+# `dsh.bundle.patch` in package.json points here; installing this package into a profile
+# reconciles this insert into the profile's plugin stack.
+#
+# automationMode defaults to `standard` on purpose: observation is free, and every actuation
+# (click / type / key / drag / scroll / clipboard write) goes through the host's approval card.
+# Raise it to `autonomous` (high-risk operations still ask) or `unrestricted` deliberately, in
+# Settings → computer-use, once you have decided the machine may be driven without a prompt.
+- insert:
+  - id: computer-use
+    name: dsh-codex-style-computer-use
+    config:
+      enabled: true
+      automationMode: standard   # read-only | standard | autonomous | unrestricted
+      dryRun: false
+      maxActionsPerMinute: 60
+      annotateMarks: true

package/lib/artifacts.js

@@ -0,0 +1,35 @@
+import { appendFileSync, readFileSync, lstatSync, unlinkSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import { createHash } from 'node:crypto'
+
+const digest = bytes => createHash('sha256').update(bytes).digest('hex')
+const manifest = dir => join(dir.root, 'owned-shots.jsonl')
+
+export function saveOwnedShot (dir, path, bytes) {
+  if (resolve(dirname(path)) !== resolve(dir.shots)) throw new Error('shot path outside its owned directory')
+  writeFileSync(path, bytes, { flag: 'wx' })
+  // A failed manifest write merely makes this image ineligible for cleanup.
+  try { appendFileSync(manifest(dir), JSON.stringify({ file: basename(path), sha256: digest(bytes), size: bytes.length, createdAt: Date.now() }) + '\n') } catch {}
+  return path
+}
+
+export function cleanupOwnedShots (dir, { before, dryRun = true } = {}) {
+  if (!Number.isFinite(before)) throw new Error('an explicit created-before timestamp is required')
+  let lines
+  try { lines = readFileSync(manifest(dir), 'utf8').split('\n') } catch { return { dryRun, files: [], bytes: 0 } }
+  const result = { dryRun, files: [], bytes: 0 }
+  const seen = new Set()
+  for (const line of lines) {
+    try {
+      const record = JSON.parse(line)
+      if (!record.file || record.file !== basename(record.file) || seen.has(record.file) ||
+          !/^shot-[\w-]+\.(jpg|png)$/.test(record.file) || !(record.createdAt < before)) continue
+      seen.add(record.file)
+      const path = join(dir.shots, record.file), stat = lstatSync(path)
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== record.size || digest(readFileSync(path)) !== record.sha256) continue
+      if (!dryRun) unlinkSync(path)
+      result.files.push(path); result.bytes += stat.size
+    } catch { /* missing, locked, modified or malformed entries are retained */ }
+  }
+  return result
+}

package/lib/attention-native.js

@@ -0,0 +1,93 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { spawn } from 'node:child_process'
+import { prepareNativeBinary } from './core/native-runtime.js'
+
+export class AttentionNative {
+  constructor ({ exe = process.execPath, hostPid = process.pid, ownerPid = 0, dataDir, timeoutMs = 1800 } = {}) {
+    this.target = { exe, hostPid, ownerPid }
+    this.timeoutMs = timeoutMs
+    this.dataDir = dataDir || path.join(process.env.DSH_HOME || path.join(os.homedir(), '.dsh'), 'data', 'computer-use')
+    this.pending = new Map()
+    this.starting = null
+    this.child = null
+    this.closed = false
+    this.journal = path.join(this.dataDir, 'attention-native.jsonl')
+    fs.mkdirSync(this.dataDir, { recursive: true })
+  }
+  log (record) {
+    try { fs.appendFileSync(path.join(this.dataDir, 'attention.jsonl'), JSON.stringify({ utc: new Date().toISOString(), version: 'attention-v1', ...record }) + '\n') } catch (error) { console.error('[dsh-attention] log write failed:', error.message) }
+  }
+  async compile () {
+    const source = fileURLToPath(new URL('./attention-worker.cs', import.meta.url))
+    return prepareNativeBinary({ source, name: 'attention-worker.exe', cache: 'attention',
+      references: ['System.Web.Extensions.dll'] }, { log: message => this.log({ stage: 'helper-prepare', message }) })
+  }
+  async start () {
+    if (this.closed) throw new Error('attention helper disposed')
+    if (this.child) return
+    if (this.starting) return this.starting
+    this.starting = (async () => {
+      const binary = await this.compile()
+      if (this.closed) throw new Error('attention helper disposed')
+      await new Promise((resolve, reject) => {
+        const child = spawn(binary, [this.journal], { windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] })
+        this.child = child
+        let buffer = '', ready = false
+        const timer = setTimeout(() => { reject(new Error('attention helper startup timeout')); child.stdin.end() }, 5000)
+        const fail = (error) => {
+          clearTimeout(timer)
+          if (this.child === child) this.child = null
+          for (const p of this.pending.values()) { clearTimeout(p.timer); p.reject(error) }
+          this.pending.clear()
+          if (!ready) reject(error)
+          this.log({ stage: 'helper-exit', error: error.message })
+        }
+        child.once('error', fail)
+        child.once('exit', (code, signal) => fail(new Error(`attention helper exited: ${code}/${signal}`)))
+        child.stderr.on('data', b => this.log({ stage: 'helper-stderr', text: String(b).slice(0, 4000) }))
+        child.stdin.on('error', e => this.log({ stage: 'helper-stdin-error', error: e.message }))
+        child.stdout.on('data', chunk => {
+          buffer += chunk.toString('utf8')
+          for (let eol; (eol = buffer.indexOf('\n')) >= 0;) {
+            const line = buffer.slice(0, eol).trim(); buffer = buffer.slice(eol + 1)
+            if (!line) continue
+            let event
+            try { event = JSON.parse(line) } catch { this.log({ stage: 'helper-protocol-error', line: line.slice(0, 500) }); continue }
+            if (event.stage === 'ready') { ready = true; clearTimeout(timer); this.log({ stage: 'helper-ready', ...event.data, binary }); resolve() }
+            if ('result' in event || event.error) {
+              const pending = this.pending.get(event.id)
+              if (!pending) continue
+              clearTimeout(pending.timer); this.pending.delete(event.id)
+              if (event.error) pending.reject(new Error(event.error)); else pending.resolve(event.result)
+            }
+          }
+        })
+      })
+    })()
+    try { await this.starting } finally { this.starting = null }
+  }
+  async request (op, options = {}) {
+    const started = performance.now()
+    await this.start()
+    const id = randomUUID()
+    const result = await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`attention ${op} timed out (${this.timeoutMs} ms)`)) }, this.timeoutMs)
+      this.pending.set(id, { resolve, reject, timer })
+      this.child.stdin.write(JSON.stringify({ ...this.target, ...options, op, id }) + '\n', error => {
+        if (error) { clearTimeout(timer); this.pending.delete(id); reject(error) }
+      })
+    })
+    return { ...result, roundTripMs: Math.round(performance.now() - started), requestId: id }
+  }
+  async close () {
+    this.closed = true
+    if (this.starting) await this.starting.catch(() => {})
+    const child = this.child
+    if (!child) return
+    // EOF executes the native finally; do not terminate it while it owns a topmost lease.
+    await new Promise(resolve => { child.once('exit', resolve); child.stdin.end(); setTimeout(resolve, 2000).unref() })
+  }
+}

package/lib/attention-worker.cs

@@ -0,0 +1,194 @@
+// C# 5, Windows inbox .NET Framework only. No input injection or attached queues.
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading;
+using System.Web.Script.Serialization;
+
+class AttentionWorker
+{
+    [StructLayout(LayoutKind.Sequential)] struct RECT { public int L, T, R, B; }
+    [StructLayout(LayoutKind.Sequential)] struct POINT { public int X, Y; public POINT(int x, int y) { X=x; Y=y; } }
+    [StructLayout(LayoutKind.Sequential)] struct FLASH { public uint size; public IntPtr hwnd; public uint flags, count, timeout; }
+    [StructLayout(LayoutKind.Sequential, CharSet=CharSet.Unicode)] struct ENTRY {
+        public uint size, usage, pid; public IntPtr heap; public uint module, threads, parent; public int priority; public uint flags;
+        [MarshalAs(UnmanagedType.ByValTStr, SizeConst=260)] public string exe;
+    }
+    delegate bool EnumProc(IntPtr h, IntPtr p);
+    [DllImport("user32.dll")] static extern bool EnumWindows(EnumProc cb, IntPtr p);
+    [DllImport("user32.dll")] static extern bool IsWindow(IntPtr h);
+    [DllImport("user32.dll")] static extern bool IsWindowVisible(IntPtr h);
+    [DllImport("user32.dll")] static extern bool IsIconic(IntPtr h);
+    [DllImport("user32.dll")] static extern IntPtr GetForegroundWindow();
+    [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+    [DllImport("user32.dll")] static extern IntPtr GetWindow(IntPtr h, uint cmd);
+    [DllImport("user32.dll")] static extern IntPtr GetAncestor(IntPtr h, uint flags);
+    [DllImport("user32.dll", CharSet=CharSet.Unicode)] static extern int GetWindowTextLength(IntPtr h);
+    [DllImport("user32.dll", CharSet=CharSet.Unicode)] static extern int GetWindowText(IntPtr h, StringBuilder title, int length);
+    [DllImport("user32.dll")] static extern int GetWindowLong(IntPtr h, int n);
+    [DllImport("user32.dll")] static extern bool GetClientRect(IntPtr h, out RECT r);
+    [DllImport("user32.dll")] static extern bool ClientToScreen(IntPtr h, ref POINT p);
+    [DllImport("user32.dll")] static extern IntPtr WindowFromPoint(POINT p);
+    [DllImport("user32.dll", SetLastError=true)] static extern bool SetWindowPos(IntPtr h, IntPtr after, int x, int y, int w, int t, uint flags);
+    [DllImport("user32.dll")] static extern bool ShowWindowAsync(IntPtr h, int cmd);
+    [DllImport("user32.dll")] static extern bool SetForegroundWindow(IntPtr h);
+    [DllImport("user32.dll")] static extern bool FlashWindowEx(ref FLASH f);
+    [DllImport("user32.dll")] static extern IntPtr SetThreadDpiAwarenessContext(IntPtr v);
+    [DllImport("dwmapi.dll")] static extern int DwmGetWindowAttribute(IntPtr h, int a, out int v, int size);
+    [DllImport("kernel32.dll", SetLastError=true)] static extern IntPtr OpenProcess(uint access, bool inherit, uint pid);
+    [DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)] static extern bool QueryFullProcessImageName(IntPtr p, int flags, StringBuilder b, ref int n);
+    [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr p);
+    [DllImport("kernel32.dll")] static extern IntPtr CreateToolhelp32Snapshot(uint flags, uint pid);
+    [DllImport("kernel32.dll", CharSet=CharSet.Unicode)] static extern bool Process32First(IntPtr s, ref ENTRY e);
+    [DllImport("kernel32.dll", CharSet=CharSet.Unicode)] static extern bool Process32Next(IntPtr s, ref ENTRY e);
+
+    const uint POSITION = 0x0001 | 0x0002 | 0x0010 | 0x0200 | 0x4000; // no size/move/activate/owner-z, async
+    static readonly object outputLock = new object(), leaseLock = new object();
+    static readonly Dictionary<long, Lease> leases = new Dictionary<long, Lease>();
+    static string journal;
+    class Lease { public IntPtr h; public uint pid; public long until; public string id; }
+    static Dictionary<string,object> D(params object[] pairs) {
+        var d = new Dictionary<string,object>(); for (int i=0;i<pairs.Length;i+=2) d[(string)pairs[i]]=pairs[i+1]; return d;
+    }
+    static void Write(object d) {
+        lock(outputLock) {
+            string s = new JavaScriptSerializer().Serialize(d);
+            try { Console.WriteLine(s); Console.Out.Flush(); } catch { }
+            if (journal != null) try { File.AppendAllText(journal, s+Environment.NewLine, new UTF8Encoding(false)); } catch { }
+        }
+    }
+    static void Stage(string id, string stage, object data) { Write(D("id",id,"utc",DateTime.UtcNow.ToString("o"),"stage",stage,"data",data)); }
+    static string S(Dictionary<string,object> d,string k,string fallback="") { return d.ContainsKey(k) ? Convert.ToString(d[k]) : fallback; }
+    static long N(Dictionary<string,object> d,string k,long fallback=0) { return d.ContainsKey(k) ? Convert.ToInt64(d[k]) : fallback; }
+    static bool B(Dictionary<string,object> d,string k) { return d.ContainsKey(k) && Convert.ToBoolean(d[k]); }
+    static uint Pid(IntPtr h) { uint p; GetWindowThreadProcessId(h,out p); return p; }
+    static string PathOf(uint pid) {
+        IntPtr p=OpenProcess(0x1000,false,pid); if(p==IntPtr.Zero) return "";
+        try { var b=new StringBuilder(32768); int n=b.Capacity; return QueryFullProcessImageName(p,0,b,ref n) ? b.ToString() : ""; }
+        finally { CloseHandle(p); }
+    }
+    static HashSet<uint> Family(uint host) {
+        var parents=new Dictionary<uint,uint>(); IntPtr snap=CreateToolhelp32Snapshot(2,0);
+        try { ENTRY e=new ENTRY(); e.size=(uint)Marshal.SizeOf(typeof(ENTRY));
+            if(Process32First(snap,ref e)) do { parents[e.pid]=e.parent; } while(Process32Next(snap,ref e));
+        } finally { if(snap!=new IntPtr(-1)) CloseHandle(snap); }
+        var family=new HashSet<uint>(); uint p=host;
+        for(int i=0;i<32 && p!=0 && family.Add(p);i++) { if(!parents.TryGetValue(p,out p)) break; }
+        return family;
+    }
+    static IntPtr Resolve(Dictionary<string,object> q) {
+        string exe=S(q,"exe"); uint wanted=(uint)N(q,"ownerPid");
+        var family=Family((uint)N(q,"hostPid")); var candidates=new List<IntPtr>();
+        EnumWindows(delegate(IntPtr h,IntPtr unused) {
+            uint p=Pid(h);
+            if(GetWindow(h,4)!=IntPtr.Zero || GetWindowTextLength(h)==0 || (GetWindowLong(h,-20)&0x80)!=0) return true;
+            if(wanted!=0 && p!=wanted) return true;
+            var title=new StringBuilder(512); GetWindowText(h,title,title.Capacity);
+            if(title.ToString()=="DSH Pet") return true; // legacy independent pet, never the main window
+            if(!String.Equals(PathOf(p),exe,StringComparison.OrdinalIgnoreCase)) return true;
+            candidates.Add(h); return true;
+        },IntPtr.Zero);
+        var related=candidates.FindAll(h=>family.Contains(Pid(h)));
+        if(related.Count==1) return related[0];
+        if(candidates.Count==1) return candidates[0];
+        if(candidates.Count>1) throw new Exception("ambiguous-window: "+candidates.Count+" matching windows; no arbitrary selection");
+        return IntPtr.Zero;
+    }
+    static bool Top(IntPtr h) { return (GetWindowLong(h,-20)&8)!=0; }
+    static Dictionary<string,object> Probe(IntPtr h) {
+        // Coordinates are derived and consumed on this same PMv2 thread.
+        SetThreadDpiAwarenessContext(new IntPtr(-4));
+        int cloaked=0; int dwm=DwmGetWindowAttribute(h,14,out cloaked,4);
+        RECT r; POINT origin=new POINT(0,0);
+        bool bounds=GetClientRect(h,out r) && ClientToScreen(h,ref origin);
+        bool shown=IsWindow(h) && IsWindowVisible(h) && !IsIconic(h) && dwm==0 && cloaked==0 && bounds && r.R>r.L && r.B>r.T;
+        var owners=new List<long>(); int visible=0;
+        if(shown) for(int y=1;y<=3;y++) for(int x=1;x<=3;x++) {
+            IntPtr at=GetAncestor(WindowFromPoint(new POINT(origin.X+(r.R-r.L)*x/4,origin.Y+(r.B-r.T)*y/4)),2);
+            owners.Add(at.ToInt64()); if(at==h) visible++;
+        }
+        return D("hwnd",h.ToInt64(),"pid",Pid(h),"foreground",GetForegroundWindow().ToInt64(),
+            "focused",GetForegroundWindow()==h,"shown",shown,"minimized",IsIconic(h),"cloaked",cloaked,"dwmResult",dwm,
+            "topmost",Top(h),"clientRect",new int[]{origin.X,origin.Y,r.R-r.L,r.B-r.T},
+            "sampleOwners",owners,"exposedPoints",visible,"sampledVisible",shown && visible==9);
+    }
+    static bool Flash(IntPtr h, bool start) {
+        FLASH f=new FLASH(); f.size=(uint)Marshal.SizeOf(typeof(FLASH)); f.hwnd=h;
+        f.flags=start ? 2u|12u : 0u; f.count=uint.MaxValue;
+        return FlashWindowEx(ref f); // PREVIOUS caption state, not success!
+    }
+    static void Cleanup(bool all) {
+        lock(leaseLock) {
+            foreach(var item in new List<Lease>(leases.Values)) {
+                if(!all && DateTime.UtcNow.Ticks<item.until && GetForegroundWindow()!=item.h) continue;
+                bool same=IsWindow(item.h) && Pid(item.h)==item.pid;
+                bool requested=false;
+                if(same) {
+                    requested=SetWindowPos(item.h,new IntPtr(-2),0,0,0,0,POSITION);
+                    for(int i=0;i<20 && Top(item.h);i++) Thread.Sleep(10);
+                    if(GetForegroundWindow()==item.h) Flash(item.h,false);
+                }
+                bool restored=!same || !Top(item.h);
+                Stage(item.id,"cleanup",D("hwnd",item.h.ToInt64(),"sameOwner",same,"requested",requested,"restored",restored));
+                if(restored || all) leases.Remove(item.h.ToInt64());
+            }
+        }
+    }
+    static object Run(Dictionary<string,object> q) {
+        string id=S(q,"id"), op=S(q,"op","probe");
+        if(op=="cleanup") { Cleanup(true); return D("status","cleanup-complete"); }
+        var clock=Stopwatch.StartNew(); IntPtr h=Resolve(q);
+        if(h==IntPtr.Zero) return D("status","no-window","elapsedMs",clock.ElapsedMilliseconds,"visible",false,"focused",false);
+        var before=Probe(h); Stage(id,"resolved",before);
+        if(op=="probe") return before;
+        if(op!="raise") throw new Exception("unsupported operation: "+op);
+        bool foregroundApi=false, topApi=false, flashPrevious=false;
+        bool already=(bool)before["focused"] && (bool)before["sampledVisible"];
+        if(!already) {
+            flashPrevious=Flash(h,true); Stage(id,"flash",D("state","requested","previousActive",flashPrevious,"observed",false));
+            if(IsIconic(h)) ShowWindowAsync(h,9); else if(!IsWindowVisible(h)) ShowWindowAsync(h,4);
+            if(!B(q,"skipFocus")) foregroundApi=SetForegroundWindow(h);
+            // SetForegroundWindow has an asynchronous cross-queue phase; do not judge immediately.
+            for(int i=0;i<5 && GetForegroundWindow()!=h;i++) Thread.Sleep(10);
+            Stage(id,"focus",D("apiReturn",foregroundApi,"observed",GetForegroundWindow()==h,"skipped",B(q,"skipFocus")));
+            var afterFocus=Probe(h);
+            if(!(bool)afterFocus["sampledVisible"] || GetForegroundWindow()!=h || B(q,"skipFocus")) {
+                lock(leaseLock) {
+                    // Remember original state BEFORE promotion. A repeat extends the same lease.
+                    Lease lease;
+                    if(leases.TryGetValue(h.ToInt64(),out lease)) lease.until=DateTime.UtcNow.AddMilliseconds(4000).Ticks;
+                    else if(!Top(h)) leases[h.ToInt64()]=new Lease {h=h,pid=Pid(h),id=id,until=DateTime.UtcNow.AddMilliseconds(4000).Ticks};
+                    topApi=SetWindowPos(h,new IntPtr(-1),0,0,0,0,POSITION|0x0040);
+                }
+                Stage(id,"topmost-request",D("apiReturn",topApi,"lastError",topApi ? 0 : Marshal.GetLastWin32Error()));
+            }
+        }
+        Dictionary<string,object> after=Probe(h);
+        for(int i=0;i<25 && !(bool)after["sampledVisible"];i++) { Thread.Sleep(10); after=Probe(h); }
+        bool visible=(bool)after["sampledVisible"], focused=(bool)after["focused"];
+        return D("status",visible ? (focused ? "foreground" : "visible-without-focus") : "not-visible",
+            "visible",visible,"focused",focused,"already",already,"elapsedMs",clock.ElapsedMilliseconds,
+            "foregroundApi",foregroundApi,"topmostApi",topApi,"flash",already ? "not-needed" : "requested-unverified",
+            "before",before,"after",after,"cleanupLeaseMs",4000);
+    }
+    static int Main(string[] args) {
+        Console.InputEncoding=new UTF8Encoding(false); Console.OutputEncoding=new UTF8Encoding(false);
+        if(args.Length>0) { journal=args[0]; Directory.CreateDirectory(System.IO.Path.GetDirectoryName(journal)); }
+        SetThreadDpiAwarenessContext(new IntPtr(-4));
+        var timer=new Timer(_=>{try { Cleanup(false); } catch(Exception e) { Stage("","cleanup-error",e.ToString()); }},null,100,100);
+        Stage("","ready",D("pid",Process.GetCurrentProcess().Id,"version","attention-v1","inputInjection",false,"attachedQueues",false));
+        try {
+            string line;
+            while((line=Console.ReadLine())!=null) {
+                string id="";
+                try { var q=new JavaScriptSerializer().Deserialize<Dictionary<string,object>>(line); id=S(q,"id");
+                    object r=Run(q); Write(D("id",id,"utc",DateTime.UtcNow.ToString("o"),"result",r));
+                } catch(Exception e) { Write(D("id",id,"utc",DateTime.UtcNow.ToString("o"),"error",e.ToString())); }
+            }
+        } finally { timer.Dispose(); Cleanup(true); }
+        return 0;
+    }
+}