MCP: revert refresh to fire-and-forget, doc TODO

E2E flagged the right edge case: when the FE re-lists in response to `mcp-refresh` and the new listing is byte-identical to the cached state (common on MTP/SMB right after an operation already pushed fresh state), the FE skips the `update_*_pane_state` call to avoid a redundant generation bump. That left `refresh`'s ack helper waiting for a signal that never arrived, timing out at 1500 ms.

- Revert `execute_refresh` to fire-and-forget with a `// TODO(mcp-ack):` comment documenting the two acceptable follow-ups (round-trip ack, or always-bump-generation on re-list).
- Update both CLAUDE.md and the user-facing `docs/tooling/mcp.md` to call out that `refresh` is the one exception in the contract.
- Every other ack-wrapped tool stays as-is; the smb/mtp E2E suite exercises `copy`/`move`/`delete`/`open_under_cursor`/`move_cursor` and they all passed against the new contract.

Author: vdavid

apps/desktop/src-tauri/src/mcp/CLAUDE.md

@@ -65,7 +65,7 @@ The mechanism lives in `executor/ack.rs`. Each tool:
 
 | Variant                  | Fires when                                                              | Used by                                                                                                                          |
 | ------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `GenerationAdvanced`     | `PaneStateStore.generation` is strictly greater than the captured value | Anything that mutates pane state (`refresh`, `select`, `set_view_mode`, `sort`, `toggle_hidden`, `tab`, `nav_*`, auto-confirmed `copy`/`move`/`delete`, `dialog confirm`) |
+| `GenerationAdvanced`     | `PaneStateStore.generation` is strictly greater than the captured value | Anything that mutates pane state (`select`, `set_view_mode`, `sort`, `toggle_hidden`, `tab`, `nav_*`, auto-confirmed `copy`/`move`/`delete`, `dialog confirm`). NOT `refresh` — see TODO note below.                                  |
 | `SoftDialogAppeared(id)` | A soft dialog with that ID is in `SoftDialogTracker`                    | Confirmation dialogs from `copy`/`move`/`delete` (autoConfirm: false), `mkdir`, `mkfile`; `dialog open about`                    |
 | `WindowAppeared(label)`  | A `webview_windows()` entry matches the label (exact, or `viewer-*`)    | `dialog open settings|file-viewer`, `dialog focus`                                                                               |
 | `WindowDisappeared`      | The matching `webview_windows()` entry is gone                          | `dialog close settings|file-viewer|about`                                                                                        |
@@ -77,6 +77,8 @@ The 1500 ms budget is a backend-side latency budget, not a client-facing knob: M
 
 **Note on `update_pane_tabs`.** Tab changes flow through this command (not `set_left`/`set_right`), so it also bumps the generation counter. Without that, the `tab` tool's ack would time out on every call.
 
+**Known TODO: `refresh` is still fire-and-forget.** The FE skips the `update_*_pane_state` push when the new listing is byte-identical to the cached state (correct behavior for state sync but no signal for the ack helper). Switching `refresh` to `mcp_round_trip` is the right follow-up, but requires a FE change to emit `mcp-response` after every re-list. The original "FE silently dropping the action" bug is less acute for refresh than for destructive tools, so this stays open. Search the codebase for `TODO(mcp-ack):` to find this and any future similar cases.
+
 Tools where the backend can't fully validate preconditions use `mcp_round_trip`: emit an event with a `requestId`, wait for the frontend to respond via `mcp-response` with `{ requestId, ok, error? }`, and return the actual outcome. Used by `move_cursor` and `set_setting` (5s timeout). `nav_to_path` uses `mcp_round_trip_with_timeout` with a 30s timeout because it waits for the directory listing to complete (the frontend delays the response until `handleListingComplete` fires in FilePane). Resources that need frontend data use `resource_round_trip` (same pattern but returns `data` from the response). Used by `cmdr://settings`. Use these patterns for any new tool/resource where the backend would otherwise need to replicate frontend knowledge.
 
 ### Configuration (`config.rs`)

apps/desktop/src-tauri/src/mcp/executor/file_ops.rs

@@ -154,16 +154,21 @@ pub async fn execute_mkfile<R: Runtime>(app: &AppHandle<R>) -> ToolResult {
     Ok(json!("OK: Create file dialog opened."))
 }
 
-/// Execute refresh command. Ack: pane generation advances after the FE re-pushes state.
+/// Execute refresh command.
+///
+/// TODO(mcp-ack): No reliable ack signal yet. `refresh` asks the FE to re-list the
+/// current pane. If the listing comes back byte-identical to the cached state (very
+/// common for MTP and SMB after an operation already pushed fresh state, or for any
+/// pane that hasn't drifted since the last update), the FE skips the
+/// `update_*_pane_state` call to avoid a redundant generation bump. That leaves
+/// `refresh` without a `GenerationAdvanced` signal.
+///
+/// Two acceptable follow-ups: (1) switch to `mcp_round_trip` so the FE explicitly
+/// emits `mcp-response` once re-list completes regardless of whether state changed;
+/// (2) always bump generation on re-list. Until one of those, refresh stays
+/// fire-and-forget. The original bug is less acute here than for destructive tools.
 pub async fn execute_refresh<R: Runtime>(app: &AppHandle<R>) -> ToolResult {
-    let pre_gen = snapshot_generation(app);
     app.emit("mcp-refresh", ())?;
-    wait_for_ack(
-        app,
-        AckSignal::GenerationAdvanced { from: pre_gen },
-        DEFAULT_ACK_TIMEOUT,
-    )
-    .await?;
     Ok(json!("OK: Pane refreshed"))
 }
 

docs/tooling/mcp.md

@@ -36,10 +36,14 @@ Code's MCP integration is connected. Always call `tools/list` first if you're un
 
 ## Action-tool ack contract
 
-Action tools (`copy`, `move`, `delete`, `mkdir`, `mkfile`, `refresh`, `select`, `toggle_hidden`, `set_view_mode`,
-`sort`, `tab`, `open_under_cursor`, `nav_to_parent`, `nav_back`, `nav_forward`, and `dialog` open/close/focus/confirm)
-now wait for the frontend to acknowledge the dispatched action before returning `OK`. Default budget is 1500 ms. If the
-FE is stalled, the tool returns a typed error naming the missing signal — no more false-positive `OK`s.
+Action tools (`copy`, `move`, `delete`, `mkdir`, `mkfile`, `select`, `toggle_hidden`, `set_view_mode`, `sort`, `tab`,
+`open_under_cursor`, `nav_to_parent`, `nav_back`, `nav_forward`, and `dialog` open/close/focus/confirm) now wait for the
+frontend to acknowledge the dispatched action before returning `OK`. Default budget is 1500 ms. If the FE is stalled,
+the tool returns a typed error naming the missing signal — no more false-positive `OK`s.
+
+`refresh` is the one tool that stays fire-and-forget for now: the FE skips state pushes when the re-listing is
+byte-identical to the cached state, so there's no reliable ack signal. Search the Rust codebase for `TODO(mcp-ack):` to
+follow this.
 
 What this means for automation: