# Reported issues for desktop-touch-mcp

Pod holds 20 of 53 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [desktop-touch-mcp](/mcp/desktop-touch-mcp).

## Most discussed

### epic(audit): LLM Operation Audit — 28 tool LLM-perspective 総点検 (Phase 2-5 tracking)

## Summary

`docs/llm-operation-audit.md` (PR #210 で land) の Phase 2-5 を tracking する epic issue。

1.3 版で複数発見された silent-success / regression / contract drift / schema reject / foreground refusal silent regression / test residue (#173 / #196 / #198 / #202 / #204 / #208) を踏まえ、LLM agent (Claude Code 等) が tool を呼ぶ実環境視点で **動作 + 文書 contract** を L5 全 28 tool 総点検する企画。

Plan body は `docs/llm-operation-audit.md` を SSOT 参照。

## Phase 分割

- ✅ **Phase 1**: Plan + template land (PR #210 で完了)
- [ ] **Phase 2**:

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/211) · 2026-05-09 · closed · 10 comments

### epic(adr): Phase 4 — Windows Terminal への信頼性ある BG 入力経路 (#173 stretch)

## Background

issue #173 で起票された **Phase 4 (ストレッチ)**。v1.3.2 (PR #174) で Windows Terminal は WM_CHAR fast-path から外され、auto-route で foreground 経路にフォールバックするようになった。これは正しい修正だが、**WT 既定環境で BG (foreground-independent) 入力ができない** という制約も同時に生まれた。

Phase 4 では WT に対して **再び** foreground を奪わずに入力する手段を取り戻す。これは別 ADR としての検討案件、優先度は低 (workaround として foreground 経路があるため)。

## 候補となる代替案

### A. ConPTY API 直接

- Windows 10 1809+ で導入された Pseudo Console API (\`CreatePseudoConsole\`)
- WT は内部的に ConPTY を使用しているので、外部から ConPTY ハンドル

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/185) · 2026-05-08 · closed · 4 comments

### observability: idle CPU 動向 + Win+L 後の dormant 化 + MCP 死亡経路の特定

# observability: idle CPU 動向 + Win+L 後の dormant 化 + MCP 死亡経路の特定

## TL;DR

dogfood 環境で「desktop-touch の CPU 負荷が高い気がする」という体感から計測したところ、3 つの観察が出た。いずれも単独では P1 級ではないが、**MCP プロセスのライフサイクル / リソース挙動に対する観測経路が薄い**ことが共通根の可能性。先に観測経路（dormant 状態の検出・記録）を整える issue として扱いたい。

## 観察 1: idle baseline (2 MCP インスタンス合算) で tree CPU avg 0.65% + 60s 周期スパイク

`.tmp/perf-record/record-mcp-cpu.ps1` で **2 個の MCP インスタンスのプロセスツリー** (node x2 + 各 tray powershell + 各 conhost、計 6 プロセス) を 2 秒間隔 5 分サンプリング。CSV 上の "tree CPU" は **両 MCP の合算

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/365) · 2026-05-19 · closed · 3 comments

### v1.7.0 release blocked — Stage 5 dogfood degrade observations (7 items A-G)

## Summary

v1.7.0 release is blocked by 7 dogfood degrades / regression candidates observed during Stage 5 (PR #326) pre-PR smoke on 2026-05-17. Three items (B/C/D) are flagged as high priority because they look like daily-use regressions that would erode user trust if shipped. This issue tracks all 7 items, narrows PR #326 to lint fix only, and coordinates per-item investigation.

## Observed (2026-05-17)

| ID | Observation | Hypothesis | Priority |
|----|-------------|------------|----------

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/327) · 2026-05-16 · closed · 3 comments

### terminal action='run' の until:{mode:'pattern'} で、出力が改行で終わらないと \s*\n 等の末尾改行依存パターンが永久に不一致になり timeout する

## 概要
`terminal(action='run')` + `until:{mode:'pattern'}` で、コマンドの**最終出力行が改行で終わらない**場合、`\s*\n` のように末尾の改行を要求するパターンが永遠にマッチせず、`completion.reason='timeout'` まで待ち続ける。

これは #383 (until:pattern が echo 行に自己マッチする) の回避策として「パターンを厳しくする」(例 `MARKER\s*\n`) を試みると踏む二次的な問題。なお **#383 修正後は素のマーカー (`MARKER`) で実出力にマッチできるようになるため、`\s*\n` 回避策自体が不要になり、本問題の実害は大きく下がる見込み**。ただし「改行で終わらない出力 + 改行依存パターン」という組合せ自体は独立した欠陥として残る。

## 再現手順 (2026-05-22 実機計測 / WSL Ubuntu への SSH セッション)
```
terminal(action='run',
  input="sleep 2; printf 'N

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/384) · 2026-05-22 · closed · 2 comments

### feat(keyboard,docs): align keyboard.ts WT BG reject code with operation-verification-matrix §3.1 (BackgroundInputNotDelivered vs Unsupported)

## Summary

`docs/operation-verification-matrix.md` §3.1 (line 140) は **`keyboard` (action:`type` BG) → code: `BackgroundInputNotDelivered` (terminal と共有、同 channel WM_CHAR / 同症状 silent drop)** と SSOT で規定。しかし現実の `src/tools/keyboard.ts` line 815-826 / 829-834 は `canInjectViaPostMessage` の early reject (reason: `wt_xaml_pipeline` 等) を `BackgroundInputUnsupported` で返している。

Issue #195 PR では terminal.ts 側を matrix doc 整合（`BackgroundInputNotDelivered`）に修正し、test 1 (keyboard-bg-verification.test.ts:88) は 

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/198) · 2026-05-08 · closed · 2 comments

### Add `detail="som"` mode to `screenshot` for explicit Set-of-Marks requests

## Background

The `screenshot` tool currently exposes three `detail` levels: `meta`, `text`, and `image`. Set-of-Marks (SoM) overlay is produced automatically only as a fallback when UIA is blind (for apps UIA cannot introspect).

However, there are legitimate cases where SoM is useful even for UIA-friendly apps:

- Reasoning about **spatial layout** (relative positions, grouping)
- **Icon-only UIs** where text labels are absent
- Disambiguating **multiple elements with the same name/role**

To

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/26) · 2026-04-20 · closed · 2 comments

### chore: remove deprecated sourceId field from UiEntity/UiEntityCandidate

## Motivation

`sourceId` field on `UiEntity` / `UiEntityCandidate` is `@deprecated` — a legacy single-string locator shared across CDP, terminal, and UIA backends. The type-safe replacement `locator.*` (per-backend discriminated fields) already exists but callers still fall through to `sourceId`.

## Scope

- **24 files** reference `sourceId` across `resolver.ts`, `guarded-touch.ts`, `session-registry.ts`, `desktop-executor.ts`, `desktop-register.ts`, `desktop.ts`, type definitions, and tests.

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/470) · 2026-06-26 · closed · outside contributor · 1 comment

## Most recent

### feat: screenshot disk-path model — save to disk, return file refs

**Description**
Currently, screenshot responses embed images as inline base64 strings in MCP messages. This consumes significant message tokens and may hit transport limits on large screenshots.

**Solution**
Replace inline base64 with a disk-path model:
- Save images to .screenshots/ directory
- Return file refs instead of base64 payloads
- Add screenshot_query tool for read-only cache queries (by tag/window/time range)
- Add screenshot_gc tool for disk cache garbage collection with dry-run mod

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/466) · 2026-06-26 · closed · outside contributor · 1 comment

### mouse_click: homing delta correction silently disabled when window focus triggers cache overwrite

## Problem

In \src/tools/mouse.ts\, the \pplyHoming\ function has a logic ordering bug where Tier 2 (focus) calls \updateWindowCache()\ **before** Tier 1 (delta correction) runs \computeWindowDelta()\. Since \updateWindowCache\ overwrites the cached window position with the **current** position, \computeWindowDelta\ always computes a delta of \(0,0)\ — effectively disabling homing correction whenever a focus attempt was made.

## Reproduction

1. Take a screenshot via \screenshot(detail='text'

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/443) · 2026-06-06 · closed · outside contributor · 1 comment

### browser_click should prefer visible candidates when selector matches hidden duplicates

## 背景

Google Search Console の URL 検査画面を `desktop-touch-mcp` 経由で操作しているとき、同じ `aria-label` を持つ hidden / zero-size 要素と可視ボタンが同時に存在し、`browser_click(selector=...)` が hidden 側を掴んで失敗した。

実例:

```text
browser_click failed: Element has zero size (hidden or not rendered): div[aria-label="インデックス登録をリクエスト再リクエスト"]
```

同じ画面では、可視のボタンも存在していた。

```text
text: インデックス登録をリクエスト
aria: インデックス登録をリクエスト再リクエスト
rect: x=828.4, y=381, width=218.6, height=36
```

`browser_eval` で `getBoundingClientRect()` を確認し、可視要素だけを絞って `click

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/441) · 2026-06-06 · closed · 1 comment

### terminal action='run' until:{mode:'pattern'} は複数行 input で echo 自己マッチが残る (単一行は #383 で修正済)

## 概要
#383 で `terminal(action='run')` + `until:{mode:'pattern'}` の echo 自己マッチを **単一行コマンド** (例 `cmd; echo "SENTINEL"`) について修正した。しかし **複数行 input**（埋め込み改行を含む input）では、echo 自己マッチが残る場合がある。これは #383 以前から存在する挙動で、**新規回帰ではない**。

## なぜ単一行のみ修正したか（構造的理由）
修正は「エコーされた input をバッファ内で locate し、その**後ろ**だけを pattern 走査する」方式。単一行ではエコーが連続して現れるので確実に locate できる。

複数行 input では、shell/terminal がエコーを以下のように出すため、バッファだけからは「エコー境界」を確実に決められない:
- 継続プロンプト（Bash PS2 `> ` / PowerShell `>>`）が行間に挿入される。
- conhost/pwsh は埋め込み改行を**行ごとに実行**し、各

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/386) · 2026-05-22 · closed · 1 comment

### terminal action='run' の until:{mode:'pattern'} がコマンドのエコーにマッチし、コマンド実行前に pattern_matched を返す

## 概要
  `terminal action='run'` ＋ `until:{mode:'pattern', pattern:'<X>'}` を使うとき、
  送信コマンドthat内にパターン文字列が含まれていると（例: 完了検出用の番兵
  `...; echo "<X>"`）、マッチャが**エコーされたコマンド行そのもの**にマッチし、
  コマンドが何も出力していない段階で即座に `completion.reason='pattern_matched'`
  を返してしまう。結果、実際の出力を得るには `action='read'` での取り直しが必要に
  なり、「send → wait → read を1回で」という `run` の利点が失われる。

  これはツールのドキュメントが長時間コマンド向けに推奨している方式
  （"use until:{mode:'pattern', pattern:'<final marker>'}"）そのものなので、
  推奨パターンが自爆する形になっている。

  ## 再現手順
  terminal(action='run',
  

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/383) · 2026-05-22 · closed · 0 comments

### feat(envelope): success-path advisory hints for tool-selection correction

# feat(envelope): success-path advisory hints for tool-selection correction

## 背景

LLM が tool 選択を誤るパターンが定常的に観測されている。代表 case (2026-05-18 dogfood で再現):

**症状**: 「メモ帳に文字を書く」タスクで、LLM は以下の誤選択を行う:
1. `desktop_discover` を skip して直接 `desktop_act` を呼ぼうとする (lease を発明 or 省略 → schema reject)
2. `desktop_act({action:'setValue', ...})` を選ぶ (entity の `primaryAction='type'` を読まない)
3. 結果的に「desktop_act で文字が書けない」と判断し、`keyboard(action='type', windowTitle=...)` に fallback して終わる
4. keyboard 経路は成功するので、LLM は当該 convers

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/352) · 2026-05-18 · closed · 1 comment

### ADR-018 Phase 4 — Tier 3 PostMessage (Word _WwG + WM_MOUSEWHEEL background scroll)

## 概要

ADR-018 scroll Tier ladder の Tier 3。Phase 1a/1b/2a/2b/3 は merge 済 (memory `project_adr018_scroll_uia.md` / PR #298)。Phase 4 は **Tier 3 = PostMessage WM_MOUSEWHEEL** を実装する塊で、UIA / CDP が届かない native アプリ (代表例: Word `_WwG` HWND) のスクロールを背後 (focus を奪わず) に dispatch する。

## スコープ

- `src/engine/_input-pipeline.ts` に `postWheelToHwnd(hwnd, delta, modifiers)` 追加
- `WM_MOUSEWHEEL` の符号反転処理 (UIA-internal の up/down 表現 vs Win32 wParam の HIWORD 符号)
- Word `_WwG` window class の調査 (`__test__/fixtures/word-cl

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/303) · 2026-05-15 · closed · 0 comments

### bug(modal): hasModal (タイトル regex) と blockingElement (UIA role='unknown') と evaluateModalAbove (所有関係) の判定ロジックが乖離 — 不整合シグナルが LLM を誤誘導

## 概要

modal の検出ロジックが API ごとに **異なるシグナル** を使っており、`hasModal=false` なのに `blockingElement` が立つ／逆、という不整合シグナルが返り、LLM のオリエンテーションを誤誘導する余地がある。

| API | 判定ロジック | 場所 |
|-----|---|---|
| `desktop_state.hasModal` / `pageState` | **ウィンドウタイトルの regex のみ** | `src/tools/desktop-state.ts:547-550` |
| `desktop_act.blockingElement` (`isModalCandidate`) | **UIA `role: 'unknown'`** | `src/engine/world-graph/session-registry.ts:23-28` |
| `evaluateModalAbove` (強度スコア) | 所有関係 + className="#32770" + disabled | `src/engin

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/297) · 2026-05-15 · closed · 0 comments

### enhancement(discover/capabilities): entity に UIA InvokePattern サポート情報を載せ、click_element → 失敗 → mouse_click の 1RT を削減

## 概要

`desktop_discover` が返す entity に「`click_element` (UIA Invoke) で押せるか / 座標クリックが必要か」のヒントがない。LLM は毎回:

1. `click_element` 試行
2. `InvokePatternNotSupported` で失敗
3. `mouse_click` にフォールバック

という 1 ラウンドトリップを払う。

## ユーザー報告（LLM 側 dogfood）

> `click_element` が `InvokePatternNotSupported` で失敗するケースが頻発:
> - 設定ダイアログのナビタブ（ListItem）
> - 「編集を許可する」チェックボックス
> - 「中止」ボタン（カスタム描画？）
>
> これらは毎回 `mouse_click` にフォールバック。discover の entity 情報に「invoke 可 / 座標クリック必要」のフラグが欲しい。

## 現状

- `EntityView` (`src/tools/desktop.ts:33

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/296) · 2026-05-15 · closed · 0 comments

### bug(perception/attention): uiaCache stale を attention='stale' に反映していない — 古い actionable[] で動く silent failure

## 概要

UIA cache が stale（age が TTL を超え `expiresInMs=0` など）でも、レスポンスの `attention` は `ok` のまま返される。LLM が古い `actionable[]` を信じて action してしまう **silent failure**。

## ユーザー報告（LLM 側 dogfood）

> `ageMs` が大きく `expiresInMs=0` のキャッシュが返ってきて、実際の画面と矛盾する `actionable[]` が出ることがあった。`uiaCached:true` フラグはあるが、stale な時に自動 invalidate するかフラグを目立たせると判断しやすい。

## 仮説

`deriveAttention()` が `FluentStatus` の dirty/settling/stale だけを参照するため、UIA cache の age/expire を attention に合流させる経路がない。

## 根拠

### attention 計算は FluentStatus のみ参

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/295) · 2026-05-15 · closed · 0 comments

### bug(scroll/verify): action='raw' verifyDelivery で delta が {x:null,y:null} オブジェクト形式のまま返り status='unverifiable' と二重シグナルで誤読される余地

## 概要

`scroll(action='raw')` が `status='unverifiable', reason='page_end_inferred'` を返す経路で、`scrollObserved.delta` が文字列 `'unverifiable'` ではなく `{x:null, y:null}` オブジェクト形式のまま返されるケースがある。LLM が `delta` オブジェクトを見て「観測手段がなかった」と読み取り、`status` と二重シグナルで判断を曇らせる。

## ユーザー報告（LLM 側 dogfood）

> Avalonia ScrollViewer に対し raw でスクロールしたが、`verifyDelivery=page_end_inferred` が返ってきて「ページ末端推定」と読めた。実際は 1mm しか動いていなかった。`scrollObserved:{delta:{x:null,y:null}}` で観測手段がなかった。

## 設計意図（コードコメント）

`src/tools/mouse.ts:1027-1030`:

> Im

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/294) · 2026-05-15 · closed · 1 comment

### fix(adr-018-phase-1b): scroll Tier 1 UIA falls through for top-level HWND — add downward subtree search for ScrollPattern

## 概要

`scroll(action='raw', windowTitle='...')` で Tier 1 UIA ScrollPattern が常に Tier 4 SendInput に fall-through する。

ADR-018 Phase 1b で実装した `scroll_by_wheel_at_hwnd_impl` が、渡された HWND の UIA 要素から **上方向（親）のみ**を辿る設計のため、ScrollPattern が **子要素**に存在するアプリ（メモ帳 / Windows 11 Notepad 等）で `"No ScrollPattern ancestor found"` を返し Tier 1 を使えない。

## 再現手順

```ts
scroll({ action: 'raw', direction: 'down', amount: 5, windowTitle: 'メモ帳' })
```

**実際の結果**
```json
{
  "hints": {
    "verifyDelivery": {
      "channel":

[Read the thread](https://github.com/Harusame64/desktop-touch-mcp/issues/291) · 2026-05-15 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/Harusame64/desktop-touch-mcp/issues).