@saifymatteo/pi-x-ide 0.0.0-stage → 1.20.2

package/docs/reference/protocol.md

@@ -0,0 +1,71 @@
+# Protocol reference
+
+Pi × IDE connects Pi to an IDE through a local WebSocket discovered by lock files.
+This page is a quick reference; for exact field semantics, message shapes, and the
+full specification, see [`docs/specs/ide-protocol.md`](../specs/ide-protocol.md).
+
+## Lock files
+
+- **Directory:** `~/.pi/pi-x-ide/lock/` (mode `0700`)
+- **Naming:** `<ide>-<pid>-<port>.lock` - for example `vscode-12345-48123.lock`,
+  `nvim-98765-50001.lock`, `jetbrains-4242-51234.lock`
+- **Permissions:** files are mode `0600`, written atomically (temp file + rename)
+
+A lock file advertises the WebSocket endpoint, an auth token, workspace folders,
+and timestamps.
+
+## Transport
+
+- **Protocol:** WebSocket (`ws://host:port`)
+- **Wire format:** JSON-RPC 2.0
+
+## Authentication
+
+Pi connects with the header:
+
+```text
+x-pi-x-ide-authorization: <authToken>
+```
+
+The token is a 64-character hex string (`randomBytes(32)`) generated per IDE
+session and written to the lock file. The server rejects connections with missing
+or invalid tokens.
+
+## Handshake
+
+Pi sends an `initialize` request with its `cwd`; the IDE responds with server info
+and immediately sends an initial `selection_changed` or `selection_cleared`
+notification.
+
+## Notifications
+
+| Method                     | Sent when                                                            |
+| -------------------------- | -------------------------------------------------------------------- |
+| `selection_changed`        | The active editor or selection changes.                              |
+| `selection_cleared`        | There is no active local text editor (JetBrains).                    |
+| `at_mentioned`             | The user invokes an IDE attach-selection command.                    |
+| `diagnostic_fix_requested` | The user picks a Pi Quick Fix on a diagnostic (VS Code-family only). |
+
+Line and character offsets are zero-based, matching VS Code/LSP. Neovim converts
+byte columns to UTF-16 character offsets; JetBrains derives character offsets from
+UTF-16 code-unit counts.
+
+## TUI behavior
+
+When connected, Pi shows IDE connection status in one place, selected by
+`status_display` (project config overrides global; set via `/ide settings`):
+
+- `widget` (default): an above-editor widget via `ctx.ui.setWidget("pi-x-ide", ...)`.
+- `statusline`: the default footer status line via `ctx.ui.setStatus("pi-x-ide", ...)`.
+
+Both placements show the compact connection/selection state (IDE icon, spinner or
+status mark, file, range, and `pending` / `sent` attach state). Selected text
+content is intentionally omitted. See
+[Configuration](configuration.md#top-level-options).
+
+## Full specification
+
+See [`docs/specs/ide-protocol.md`](../specs/ide-protocol.md) for the complete
+lock file schema, the WSL2 discovery and host-resolution rules, and the exact
+JSON for every notification. For the design rationale behind the per-editor
+transports, see [Architecture](../explanation/architecture.md).

package/docs/specs/ide-protocol.md

@@ -0,0 +1,215 @@
+# Pi x IDE Protocol
+
+Pi x IDE connects Pi to an IDE through a local WebSocket discovered by lock files.
+
+## Lock files
+
+Directory: `~/.pi/pi-x-ide/lock`.
+
+Example file: `vscode-12345-48123.lock`
+
+Neovim uses the same protocol version and writes files named `nvim-<pid>-<port>.lock`. JetBrains IDEs use the same protocol version and write files named `jetbrains-<pid>-<port>.lock`.
+
+```json
+{
+  "version": 1,
+  "ide": "vscode",
+  "name": "Visual Studio Code",
+  "transport": "ws",
+  "host": "127.0.0.1",
+  "port": 48123,
+  "authToken": "random-hex-token",
+  "workspaceFolders": ["/home/user/project"],
+  "pid": 12345,
+  "runningInWindows": false,
+  "createdAt": "2026-06-09T00:00:00.000Z",
+  "updatedAt": "2026-06-09T00:00:00.000Z"
+}
+```
+
+Rules:
+
+- Lock directory should be mode `0700`.
+- Lock files should be mode `0600`.
+- Writers should write a temp file and rename it into place.
+- `host` remains required for compatibility, but Pi may resolve a different connection host before opening the WebSocket.
+- `runningInWindows` is optional and backward-compatible. When present and `true`, it declares that the IDE server process is running on native Windows.
+- A consumer must not remove a lock only because of age after it proves the producer is live.
+- A usable local PID is a positive safe integer. When PID checking is enabled, keep a lock with a live usable PID at any age, and remove a lock with a dead usable PID at any age.
+- If the PID is missing or unusable, or if PID checking is disabled, use age-only cleanup.
+- When Pi runs in WSL and a lock has `runningInWindows: true`, TCP reachability is authoritative while PID checking is enabled. Keep the lock if the host and port are reachable. Remove the lock if the probe fails or throws.
+- Malformed lock files remain removable.
+- Repository lock producers for VS Code, Neovim, and JetBrains refresh owned locks every 15 minutes while active. Refresh preserves endpoint identity and the auth token, updates freshness data, and can recreate an externally deleted owned lock.
+- TypeScript producers drain every accepted refresh before they remove the lock. JetBrains stops its EDT timer synchronously before cleanup.
+
+## WSL2 discovery and host resolution
+
+The primary lock directory is always `~/.pi/pi-x-ide/lock`. When Pi runs inside WSL, it also scans Windows user lock directories such as `/mnt/c/Users/<user>/.pi/pi-x-ide/lock`, skipping Windows system profiles.
+
+For connection hosts, Pi resolves in this order:
+
+1. `PI_X_IDE_HOST_OVERRIDE`, either from the real environment or `~/.pi/pi-x-ide/config.json` `env`.
+2. If Pi runs in WSL and the lock has `runningInWindows: true`, parse the WSL default gateway from `ip route show` and use it only if a short TCP probe to `<gateway>:<port>` succeeds.
+3. The lock file `host` value.
+4. `127.0.0.1` if `host` is empty.
+
+Incoming editor paths are normalized to the Pi host before workspace matching, UI display, `@file#Lx-Ly` mention formatting, and prompt context formatting. Matching WSL UNC paths such as `\\wsl.localhost\Ubuntu\home\user\project` become `/home/user/project` when Pi is running in the `Ubuntu` distro.
+
+## Authentication
+
+Pi connects to `ws://host:port` with the header:
+
+```text
+x-pi-x-ide-authorization: <authToken>
+```
+
+The IDE server rejects connections with missing or invalid tokens.
+
+## Handshake
+
+Pi sends:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": 1,
+    "client": { "name": "pi-x-ide", "version": "0.1.0" },
+    "cwd": "/home/user/project"
+  }
+}
+```
+
+IDE responds:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": 1,
+    "server": {
+      "name": "Pi x IDE VS Code",
+      "version": "0.1.0",
+      "ide": "vscode"
+    }
+  }
+}
+```
+
+## Notifications
+
+### `selection_changed`
+
+Sent whenever the active editor or selection changes.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "selection_changed",
+  "params": {
+    "source": "vscode",
+    "filePath": "/home/user/project/src/main.ts",
+    "workspaceFolder": "/home/user/project",
+    "ranges": [
+      {
+        "text": "const x = 1;",
+        "selection": {
+          "start": { "line": 9, "character": 0 },
+          "end": { "line": 9, "character": 12 }
+        }
+      }
+    ],
+    "receivedAt": 1780963200000
+  }
+}
+```
+
+`source` is one of `vscode`, `zed`, `nvim`, `jetbrains`, or `unknown`. `line` and `character` are zero-based, matching VS Code/LSP. Neovim converts byte columns to UTF-16 character offsets before sending snapshots. JetBrains derives `character` from document offsets and line-start offsets, which are UTF-16 code-unit counts.
+
+JetBrains sends `selection_changed` both for non-empty selections and for an active local file with no selected text (`ranges: []`). It sends `selection_cleared` when there is no active local text editor.
+
+### `at_mentioned`
+
+Sent when the user invokes an IDE attach-selection command, such as VS Code's command, Neovim's `:PiXIdeAttach`, or the JetBrains **Pi x IDE: Attach Selection** action.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "at_mentioned",
+  "params": {
+    "source": "vscode",
+    "filePath": "/home/user/project/src/main.ts",
+    "workspaceFolder": "/home/user/project",
+    "rangeText": "@src/main.ts#L10-L20",
+    "ranges": [
+      {
+        "text": "selected text",
+        "selection": {
+          "start": { "line": 9, "character": 0 },
+          "end": { "line": 19, "character": 3 }
+        }
+      }
+    ]
+  }
+}
+```
+
+Pi inserts `rangeText` into the TUI editor and caches the corresponding selection text for context injection. JetBrains sends selection and attach notifications in the MVP; it does not send diagnostic Quick Fix notifications.
+
+### `diagnostic_fix_requested`
+
+Sent by the VS Code-family extension when the user selects **Pi: Fix it** or **Pi: Send diagnostic** from Quick Fix on an error or warning diagnostic. This notification is additive under protocol version `1`; clients that do not understand it may ignore it.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "diagnostic_fix_requested",
+  "params": {
+    "action": "fix",
+    "source": "vscode",
+    "filePath": "/home/user/project/src/main.ts",
+    "workspaceFolder": "/home/user/project",
+    "documentVersion": 7,
+    "triggerRange": {
+      "start": { "line": 9, "character": 4 },
+      "end": { "line": 9, "character": 10 }
+    },
+    "diagnostics": [
+      {
+        "severity": "error",
+        "message": "Type 'string' is not assignable to type 'number'.",
+        "source": "ts",
+        "code": 2322,
+        "range": {
+          "start": { "line": 9, "character": 4 },
+          "end": { "line": 9, "character": 10 }
+        },
+        "selectedText": "value",
+        "contextLines": [
+          { "line": 8, "text": "const value = getValue();", "isPrimary": false },
+          { "line": 9, "text": "const count: number = value;", "isPrimary": true },
+          { "line": 10, "text": "console.log(count);", "isPrimary": false }
+        ]
+      }
+    ],
+    "receivedAt": 1780963200000
+  }
+}
+```
+
+When `action` is `"fix"` or omitted, Pi formats the diagnostics into a prompt and sends it as a user message. If the agent is busy, Pi queues the diagnostic prompt as a follow-up. When `action` is `"send-diagnostic"`, Pi formats only the diagnostic context and pastes it into the TUI input box without starting an agent turn.
+
+## TUI behavior
+
+When connected, Pi displays IDE connection status in one place, selected by
+`status_display` (project config overrides global; set via `/ide settings`):
+
+- `widget` (default): above-editor widget via `ctx.ui.setWidget("pi-x-ide", ...)`.
+- `statusline`: default footer status line via `ctx.ui.setStatus("pi-x-ide", ...)`.
+
+Both placements show the compact connection/selection state (IDE icon, spinner or
+status mark, file, range, and `pending` / `sent` attach state). Selected text
+content is intentionally omitted.

package/docs/tutorials/get-started.md

@@ -0,0 +1,133 @@
+# Get started with Pi × IDE
+
+This tutorial walks you from a fresh install to your first IDE selection flowing
+into an LLM conversation in Pi. It takes about five minutes and uses VS Code as
+the vehicle — the same flow works for Cursor and Windsurf.
+
+> Already set up and just want to attach a selection? Jump to
+> [Attach the selection](#step-5-attach-the-selection-and-chat).
+> Using a different editor? See the [How-to guides](../how-to/) for Zed, Neovim,
+> and JetBrains.
+
+## What you will learn
+
+- How to install the Pi extension package and the VS Code extension.
+- How to start Pi so it discovers your IDE automatically.
+- How a text selection becomes LLM context.
+
+## Before you begin
+
+You need:
+
+- The [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI installed and
+  on your `PATH`.
+- VS Code, Cursor, or Windsurf installed.
+- A project folder with at least one source file you can open.
+
+## Step 1: Install the Pi extension package
+
+```bash
+pi install npm:pi-x-ide
+```
+
+This adds the `pi-x-ide` package to Pi. It is loaded automatically the next time
+Pi starts — no extra wiring required.
+
+## Step 2: Install the VS Code extension
+
+Open your IDE's **Extensions** panel and search for
+[`balaenis.pi-x-ide`](https://marketplace.visualstudio.com/items?itemName=balaenis.pi-x-ide),
+then install it.
+
+> Alternatively, run `/ide install` inside Pi's TUI — it auto-detects `code`,
+> `cursor`, or `windsurf` and installs the extension for you. On startup, Pi also
+> tries to auto-install the extension when it detects a supported VS Code
+> integrated terminal.
+
+Reload the IDE window after installing so the extension activates.
+
+## Step 3: Start Pi in your project
+
+Open a terminal **inside your IDE** (Terminal → New Terminal), then start Pi from
+the same project directory your IDE workspace is using:
+
+```bash
+pi
+```
+
+Pi loads `pi-x-ide` and looks for an IDE connection. When your terminal's working
+directory is inside one of the IDE's workspace folders, Pi connects automatically.
+A widget appears above the Pi input box showing the connection and selection
+state.
+
+## Step 4: Open a file and select some text
+
+Back in your IDE, open a source file and select a few lines. The Pi widget should
+update in real time:
+
+```
+⧉ ⇡ foo.ts#L10-L20
+```
+
+The `⇡` marker means a selection is **pending** — Pi has noticed it but has not
+attached it to a message yet.
+
+If the widget does not appear, see
+[Troubleshoot a missing connection](../how-to/troubleshoot-connection.md).
+
+## Step 5: Attach the selection and chat
+
+With text selected in your IDE, focus the Pi TUI and press `Ctrl+Alt+K`
+(macOS: `Ctrl+Option+K`). Pi inserts a mention into the input box:
+
+```
+@src/foo.ts#L10-L20
+```
+
+Now type a question and submit it. The selected text is injected into the LLM
+context for that turn. After submission, the widget marker changes to `✓`:
+
+```
+⧉ ✓ foo.ts#L10-L20
+```
+
+The transcript keeps your prompt and IDE context separate. Pi displays the IDE
+metadata as a purple custom message and sends that same metadata to the agent:
+
+```text
+Your prompt
+### IDE Context
+- **IDE**: vscode
+- **File**: `src/foo.ts`
+- **Selection**: L10-L20
+```
+
+Only IDE, file, and selection-range metadata are attached—not selected source
+contents. This lets the agent inspect the file itself when it needs more context.
+For an open file with no selection, the `Selection` line is omitted. The user's
+blue prompt remains unchanged.
+
+You can press `Ctrl+Alt+K` repeatedly to append several ranges to the same
+message, or select new text between turns to attach fresh context each time.
+
+## What just happened
+
+When you select text, the IDE broadcasts a `selection_changed` notification
+over a local WebSocket to Pi. Pi caches the latest selection and marks it
+pending. When you press the attach shortcut, Pi inserts the `@file#Lx-Ly` mention
+into your input. When you submit the message, Pi adds the IDE name, file path,
+and selected line range as a separate purple custom message. The selected source
+text is not sent automatically.
+
+For the full mechanism — lock files, host resolution, the Neovim sidecar, and why
+Zed is polled differently — read [How discovery works](../explanation/discovery.md)
+and [Architecture](../explanation/architecture.md).
+
+## Where to go next
+
+- [Install another editor](../how-to/) — Zed, Neovim, or JetBrains.
+- [Use Pi × IDE over WSL2](../how-to/use-wsl2.md) — Pi in WSL, IDE on Windows.
+- [Configuration reference](../reference/configuration.md) — env vars, keymaps,
+  `fixPrompt`, and `status_display`.
+- [`/ide` command reference](../reference/commands.md) — manage connections from
+  the TUI.

package/docs/zh-CN/explanation/architecture.md

@@ -0,0 +1,93 @@
+# 架构
+
+Pi × IDE 在两个通常互不感知的进程之间搭桥：你的 IDE 和 Pi TUI。本页解释各组件、数据流，以及为什么不同编辑器的连接方式不同。这是面向理解的文档 - 确切的消息结构和字段语义见 [协议规范](../../specs/ide-protocol.md)。
+
+## 三个角色
+
+| 角色          | 谁                                                      | 职责                                                               |
+| ------------- | ------------------------------------------------------- | ------------------------------------------------------------------ |
+| **IDE 插件**  | VS Code 扩展、JetBrains 插件、Neovim Lua 插件 + sidecar | 观察活跃编辑器和选区，通过本地 WebSocket 暴露它们。                |
+| **Lock file** | IDE 插件写入，Pi 读取                                   | 广播 WebSocket 端点（host、port、auth token）和 workspace 文件夹。 |
+| **Pi 扩展**   | 加载到 Pi TUI 的 `pi-x-ide`                             | 发现 lock file、建立连接、接收选区、注入为 LLM 上下文。            |
+
+Zed 是例外：它没有插件，Pi 直接读取 Zed 的本地状态数据库。见 [为什么不同编辑器连接方式不同](#为什么不同编辑器连接方式不同)。
+
+## 数据流
+
+```
+用户在 IDE 中选中文本
+        │
+        ▼
+┌──────────────────────────────────────────────────────────┐
+│ IDE 插件（VS Code / JetBrains / Neovim sidecar）         │
+│                                                          │
+│  捕获编辑器 + 选区，广播一条                              │
+│  JSON-RPC "selection_changed" 通知。                     │
+└──────────────────────┬───────────────────────────────────┘
+                       │  WebSocket  ws://127.0.0.1:<port>
+                       │  认证：x-pi-x-ide-authorization 头
+                       ▼
+┌──────────────────────────────────────────────────────────┐
+│ Pi 扩展  (src/pi/connection.ts)                          │
+│                                                          │
+│  接收通知，缓存为 runtime.latestSelection，              │
+│  置 attachState = "pending"，更新 TUI widget（⇡ 标记）。 │
+└──────────────────────┬───────────────────────────────────┘
+                       │  下一条用户消息时
+                       ▼
+┌──────────────────────────────────────────────────────────┐
+│ Pi prompt 生命周期  (src/pi/context.ts)                  │
+│                                                          │
+│  before_agent_start：快照 pending 的选区。               │
+│  添加一条可见的自定义消息，仅包含 IDE、文件和选区行范围。│
+│  用户 prompt 保持不变；代理可按需自行读取源文件。       │
+│  attachState = "sent"。                                  │
+└──────────────────────────────────────────────────────────┘
+```
+
+附加快捷键（TUI 中的 `Ctrl+Alt+K`，或 IDE 的 attach 命令）发送的是 `at_mentioned` 通知。它把 `@file#Lx-Ly` mention 插入 Pi 输入框，并缓存选中文本，为下一轮做好准备。
+
+## 为什么不同编辑器连接方式不同
+
+每个 IDE 的扩展 API 决定了传输方式。
+
+| 编辑器        | 机制                          | 原因                                                                                                                           |
+| ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| **VS Code**   | 扩展宿主内的 WebSocket 服务器 | 扩展 API 丰富：`onDidChangeTextEditorSelection`、文件系统访问、终端创建。轻量服务器在进程内运行，无需独立进程。                |
+| **JetBrains** | IDE 进程内的 WebSocket 服务器 | 同理：`com.intellij` API 提供编辑器监听和 project service 生命周期。Kotlin 插件在进程内运行服务器。                            |
+| **Neovim**    | 独立的 **sidecar** 进程       | Lua 无法原生运行 WebSocket 服务器。sidecar 是独立进程，通过 stdin/stdout（JSON lines）与 Neovim 通信，并向 Pi 暴露 WebSocket。 |
+| **Zed**       | **Pi 侧 SQLite 轮询**         | Zed 没有扩展 API，把编辑器状态存在本地 SQLite 数据库中，Pi 每秒直接读取。轮询在 Pi 侧进行，不在 Zed 侧。                       |
+
+### Neovim sidecar
+
+由于 Neovim 无法承载 WebSocket 服务器，Lua 插件会 spawn 一个 sidecar 进程（`src/nvim/sidecar.ts`），由它持有服务器和 lock file。插件通过 Neovim autocmd（`CursorMoved`、`BufEnter`、visual 模式 mark）捕获选区，去抖后把 JSON 消息写入 sidecar 的 stdin。sidecar 再以 JSON-RPC 通知广播给 Pi。
+
+sidecar 的解析顺序（`ide-plugins/nvim/lua/pi_x_ide/download.lua`）：
+
+1. `ide-plugins/nvim/bin/` 中的平台二进制。
+2. 从 GitHub Releases 下载并缓存、经 SHA256 校验的二进制。
+3. 回退到 Node.js 脚本（`pi-x-ide-nvim-sidecar.cjs`）。
+
+这就是 Neovim 插件首次启动"开箱即用"的原因：它为你的平台下载合适的二进制，下载失败时回退到 Node。
+
+### Zed 轮询
+
+Pi 直接读取 Zed 的状态数据库（`src/pi/zed.ts`）。每次轮询（默认 1000 ms，可通过 `PI_X_IDE_ZED_POLL_INTERVAL_MS` 限制在 100–2000 ms）：
+
+1. 检查 SQLite WAL 文件的 mtime - 未变化则跳过昂贵的读取（在 WSL 下尤为重要，否则每次都要拷贝完整快照）。
+2. 通过 join Zed 的 `items`、`panes`、`workspaces`、`editors` 表查询活跃编辑器。
+3. 按 workspace 匹配度打分，选出最佳。
+4. 把 UTF-8 字节偏移转换为 VS Code/LSP 风格的 line/character 位置。
+
+## 认证模型
+
+每个 IDE 进程每次会话用 `randomBytes(32).toString("hex")` 生成新 token - 64 字符的十六进制串（`src/shared/lock-file.ts`）。JetBrains 用 `SecureRandom` 生成等价 token。token 写入 lock file（mode `0600`），仅在 WebSocket 升级握手时通过 `x-pi-x-ide-authorization` 头发送。服务器的 `verifyClient` 回调会拒绝头不匹配的连接（`src/shared/ide-server.ts`）。
+
+token 除了跨越 WSL 边界外不会离开 localhost - 此时 WebSocket 仍指向解析出的 Windows host。
+
+## 相关
+
+- [发现机制](discovery.md) - Pi 如何找到 lock file 并选择连接。
+- [Effect 采用说明](effect.md) - Pi 侧 TypeScript 如何在内部用 Effect 处理错误、Schema 校验与 IO 边界。
+- [协议规范](../../specs/ide-protocol.md) - 确切的消息结构、握手和通知。
+- [功能对比](../reference/feature-parity.md) - 各编辑器支持的能力。

package/docs/zh-CN/explanation/discovery.md

@@ -0,0 +1,71 @@
+# 发现机制
+
+Pi 通过 **lock file** 发现 IDE 连接：每个运行中的 IDE 插件写入的小型 JSON 文件，用来广播自己的 WebSocket 端点。本页解释它们的位置、Pi 如何选择正确的连接，以及如何跨越 WSL 边界。确切的文件 schema 见 [协议规范](../../specs/ide-protocol.md)。
+
+## lock 目录
+
+主 lock 目录始终是：
+
+```
+~/.pi/pi-x-ide/lock/
+```
+
+每个文件命名为 `<ide>-<pid>-<port>.lock`，例如：
+
+- `vscode-12345-48123.lock`
+- `nvim-98765-50001.lock`
+- `jetbrains-4242-51234.lock`
+
+lock file 包含 IDE 来源、WebSocket host 和 port、auth token、workspace 文件夹、进程 PID 和时间戳。写入方先写临时文件再原子 rename；目录权限 `0700`，文件权限 `0600`。
+
+## Pi 如何选择连接
+
+Pi 启动时扫描它知道的所有 lock 目录，解析每个文件并为候选排序。排序优先 workspace **包含**终端当前工作目录的连接（`src/shared/paths.ts` 中的 `relationshipMatchLength`）：
+
+1. 包含你 `cwd` 的 workspace 文件夹得分最高。
+2. 被你 `cwd` **包含**的 workspace 文件夹（你在父目录启动了 Pi）得分较低。
+3. 无关系得分为零。
+
+这就是为什么推荐工作流是 **在项目目录内** 启动 Pi：匹配精确，Pi 自动连接。如果 `cwd` 只是父目录（例如 `~/`），没有候选胜出 - 运行 `/ide` 手动选择，或 `/ide auto` 重新匹配。
+
+## lock file 生命周期
+
+lock file 是临时的。Pi 先解析每个 lock，再应用过期策略。当 Pi 能证明生产者仍在运行时，会在任何年龄保留该 lock。
+
+- **活的本地 PID：** 可用的本地 PID 是正的安全整数。活的可用 PID 会保留 lock。死的可用 PID 会删除 lock。
+- **仅按年龄清理：** 若 PID 缺失或不可用，或禁用了 PID 检查，Pi 按年龄处理。超过 24 小时的文件随后会被删除。
+- **WSL Windows lock：** 当 lock 为 `runningInWindows: true` 且 Pi 在 WSL 中运行时，TCP 可达性是权威依据。可达则保留，不可达则删除。
+- **格式错误：** 无法解析的文件会被删除。
+
+VS Code、Neovim 和 JetBrains 在活动期间每 15 分钟刷新自己拥有的 lock。刷新会保留端点身份和 auth token，并更新新鲜度数据。若生产者仍在运行时文件被删除，lock 可能直到下一次心跳才重新出现。
+
+Zed 不写入这种 lock file。Pi 从 SQLite 读取 Zed 状态。
+
+关闭 IDE 时插件会移除自己的 lock file。IDE 崩溃时，Pi 在下次扫描中于活性检查失败或仅按年龄清理时回收该文件。
+
+## WSL2：发现 Windows 上的 IDE
+
+当 Pi 运行在 WSL 内、IDE 运行在原生 Windows 上时，IDE 把 lock file 写到 Windows 用户目录。Pi 同时扫描 Linux home 的 lock 目录 **和** Windows 用户目录（如 `/mnt/c/Users/<user>/.pi/pi-x-ide/lock/`），跳过 Windows 系统配置文件。
+
+Windows lock file 设置 `runningInWindows: true`。当 Pi 在 WSL 中运行时，到 Windows 生产者的 TCP 可达性是权威依据。Pi 不把 Windows PID 当作 Linux 进程活性证据。
+
+### 解析连接 host
+
+lock file 的 `host` 始终是 `127.0.0.1`，对 IDE 进程正确，但 **从 WSL 内部不可达**。Pi 按以下顺序解析可用 host（`src/pi/ide-host.ts`）：
+
+1. **`PI_X_IDE_HOST_OVERRIDE`** - 若设置（环境变量或 `~/.pi/pi-x-ide/config.json` 的 `env`），直接使用。
+2. **WSL 默认网关** - 若 lock 有 `runningInWindows: true` 且 Pi 在 WSL 中，从 `ip route show` 解析网关，仅当对 `<gateway>:<port>` 的短 TCP 探测成功（500 ms 超时）时使用。
+3. **lock file 的 `host` 值** - 同主机连接用 `127.0.0.1`。
+4. **`127.0.0.1`** - `host` 为空时。
+
+大多数 WSL 配置无需任何设置：第 2 步会自动处理。如果你的 WSL 网络模式、防火墙或终端安全策略阻止探测，显式设置 `PI_X_IDE_HOST_OVERRIDE`。见 [在 WSL2 中使用](../how-to/use-wsl2.md)。
+
+## 路径规范化
+
+来自 Windows IDE 的编辑器路径是 Windows 风格。Pi 在 workspace 匹配、UI 显示、`@file#Lx-Ly` mention 格式化和 prompt 上下文格式化之前，把它们规范化为 Linux host 路径。例如 WSL UNC 路径 `\\wsl.localhost\Ubuntu\home\user\project` 在 Pi 运行于 `Ubuntu` 发行版时变为 `/home/user/project`（`src/shared/platform.ts`）。
+
+## 相关
+
+- [架构](architecture.md) - 端到端数据流和各编辑器传输方式。
+- [协议规范](../../specs/ide-protocol.md) - lock file schema、握手和通知语义。
+- [排查连接问题](../how-to/troubleshoot-connection.md) - 发现未能连接时怎么办。