@rjfan/dsh-presence 0.0.0-stage → 0.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fanrj3
+
+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

@@ -1,3 +1,349 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="assets/icon-180.png" width="88" alt="Presence icon" />
+
+# Presence
+
+**Your SSH hosts, as local tabs.**
+
+Persistent remote workspaces, native file editing, search, exec, terminals and port
+forwards for coding agents — with **nothing installed on the remote host**.
+
+[English](README.md) · [简体中文](README.zh-CN.md) · [Releases](docs/RELEASE.md) · [MCP server](mcp/README.md)
+
+[![npm plugin](https://img.shields.io/npm/v/@rjfan/dsh-presence?label=dsh%20plugin&color=2f6bff)](https://www.npmjs.com/package/@rjfan/dsh-presence)
+[![npm mcp](https://img.shields.io/npm/v/presence-mcp?label=presence-mcp&color=2f6bff)](https://www.npmjs.com/package/presence-mcp)
+[![license](https://img.shields.io/badge/license-MIT-2f6bff)](LICENSE)
+[![awesome-dsh-plugin](https://img.shields.io/badge/awesome--dsh--plugin-listing-2f6bff)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+
+</div>
+
+![Presence — remote machines as local tabs](docs/social/cover-light.png)
+
+---
+
+## Why
+
+Running an agent on every remote machine means installing it N times, upgrading it N
+times and configuring proxies per host. Running `ssh host '<command>'` from the local
+agent means a new handshake per command, no native file tools and no continuity.
+
+Presence keeps the agent local and **extends its reach through one persistent SSH
+connection per host**. The remote side is still plain `sshd`: SFTP, exec and a PTY.
+
+| Approach | Cost |
+| --- | --- |
+| Install the agent on every host | N installs, N upgrades, per-host proxying |
+| `ssh host '<command>'` per call | Handshake per command, no file tools, no sessions |
+| **Presence** | One connection per host, native tools, nothing installed remotely |
+
+## Features
+
+- **Remote zero-install** — uses only `sshd` built-ins: the SFTP subsystem, exec channels and a PTY.
+- **One handshake** — a pool keeps one connection per host; every later call is a request on it.
+- **Native remote tools** — `rg`/`grep` runs on the target, commands run in the target shell; path, permission and encoding semantics are the remote ones.
+- **Local-like edits** — atomic writes, mode preservation, ambiguity refusal, read-before-write guard, `presence_edit` with dry-run diffs.
+- **Real workspaces** — a remote directory becomes a normal DSH workspace with a file tree and terminals that open **on the remote machine**.
+- **Recoverable deletes** — destructive shell commands dry-run first; `presence_trash` moves paths to a remote trash with restore.
+- **`@` completes remote files** — inside a remote workspace, file-reference completion indexes the machine itself (`rg --files`, `find` fallback), not a local mirror.
+- **File operations, not just reads** — `presence_mkdir` / `move` / `copy` / `chmod` plus a right-click menu in the file tree; deletes go to the recoverable trash.
+- **Diff and live logs** — unified diff between two remote files or a remote file and a local one; follow a log file from the panel without keeping a `tail -f` job around.
+- **Ports that come back** — save forwards with auto-restore on reconnect, and let the Ports panel discover newly listening ports and forward them with one click.
+- **Job notifications** — a toast (and desktop notification) when a background job finishes, plus an optional local `notifyCommand` for daemons and phones.
+- **Two shells, one kernel** — the DSH plugin and a standalone MCP server (`presence-mcp`, 20 core tools) share the same kernel.
+
+## Screenshots
+
+<table>
+  <tr>
+    <td width="50%"><img src="docs/social/screenshot/setting.png" alt="Settings — Presence hosts and workspaces" /></td>
+    <td width="50%"><img src="docs/social/screenshot/explorer.png" alt="Remote workspace: file tree and editor" /></td>
+  </tr>
+  <tr>
+    <td align="center"><sub><b>Settings</b> — every host and folder is a local tab</sub></td>
+    <td align="center"><sub><b>Remote workspace</b> — the file tree and editor are on the host</sub></td>
+  </tr>
+  <tr>
+    <td width="50%"><img src="docs/social/screenshot/@file.png" alt="@ completes remote file paths" /></td>
+    <td width="50%"><img src="docs/social/screenshot/terminal.png" alt="A terminal on the remote host" /></td>
+  </tr>
+  <tr>
+    <td align="center"><sub><b>@ files</b> — completion indexes the remote machine itself</sub></td>
+    <td align="center"><sub><b>Terminal</b> — the shell runs on the host, not locally</sub></td>
+  </tr>
+</table>
+
+### A real trajectory
+
+These three figures are rendered from a recorded 22-call session: train an MNIST
+classifier twice on a remote 64-core host, compare two learning rates, and export
+the result. Every row is one tool call with its measured duration; red rows are
+real failures kept verbatim.
+
+<p align="center"><img src="docs/social/figures/figure-1.png" width="100%" alt="Trajectory 1/3: staging the data and launching the first run" /></p>
+
+<p align="center"><img src="docs/social/figures/figure-2.png" width="100%" alt="Trajectory 2/3: comparing the two runs and archiving" /></p>
+
+<p align="center"><img src="docs/social/figures/figure-3.png" width="100%" alt="Time composition: Presence vs bare SSH" /></p>
+
+<sub>Figure 3 stacks end-to-end time into think / wait / tool. The same task through
+bare <code>ssh</code>/<code>scp</code> takes 452.5 s versus 272.8 s, with a 10.4×
+higher median interaction latency.</sub>
+
+## Quick start
+
+### 1. Install the DSH plugin
+
+```sh
+dsh plugin add @rjfan/dsh-presence@0.19.0
+```
+
+From a source checkout:
+
+```sh
+dsh plugin add /path/to/dsh-presence
+```
+
+### 2. Pick a host and open a workspace
+
+Open **Settings → Presence → New**, choose a host from `~/.ssh/config` (or paste a
+manual `ssh` command), then pick a remote folder. It appears as a workspace; the
+left sidebar, file tree, terminal and agent tools all use that remote directory.
+
+### 3. Work
+
+```text
+You: 把远程 8000 端口转发到本地，然后打开看看
+Agent: presence_forward { remotePort: 8000 }
+       → http://127.0.0.1:8000
+```
+
+## MCP server
+
+The same kernel is available to agents that cannot install DSH plugins (Codex CLI,
+Claude Code, OpenCode, Cursor, …).
+
+```sh
+npx -y presence-mcp            # 20 tools over stdio
+```
+
+```jsonc
+// Claude Desktop / OpenCode style
+{
+  "mcpServers": {
+    "presence": {
+      "command": "npx",
+      "args": ["-y", "presence-mcp"],
+      "env": {
+        "PRESENCE_HOST": "server",
+        "PRESENCE_WORKSPACE": "server:/srv/app"
+      }
+    }
+  }
+}
+```
+
+See [mcp/README.md](mcp/README.md) for Codex TOML, Claude Code, OpenCode and
+Cursor/Windsurf examples.
+
+## How it works
+
+```text
+┌───────────────────────────────┐
+│  DSH plugin  /  MCP server    │  two shells, one kernel
+└──────────────┬────────────────┘
+               │
+        Presence kernel
+        ├── ssh-config   hosts, ports, users, keys, jumps from ~/.ssh/config
+        ├── connection   one persistent connection: SFTP / exec / PTY + pool + cancel
+        └── host pool    one connection per host, created on demand, idle-collected
+               │
+        SSH (your existing keys, known_hosts, jumps, proxies)
+               │
+        target: Linux / macOS, stock sshd
+```
+
+| Agent operation | Channel | Remote dependency |
+| --- | --- | --- |
+| read / write / edit / list / stat | SFTP subsystem | `sftp-server` (stock sshd) |
+| exec, search (`rg`/`grep`), git | exec channel | commands already on the host |
+| interactive terminal | shell channel + PTY | the host's login shell |
+
+Measured on a Linux host:
+
+| Operation | Latency |
+| --- | --- |
+| `ssh host '<cmd>'` (new connection every time) | 520–540 ms |
+| Presence connect (one handshake, key auth) | 145 ms |
+| Presence `sftp stat` | p50 0.6 ms / p95 0.9 ms |
+| Presence `exec true` (new channel + shell) | p50 7.6 ms |
+| 8 concurrent exec channels | 15 ms total |
+
+> Keep TCP_NODELAY on: without it, request/response hits delayed ACK and p95 goes
+> from 0.9 ms to 48 ms.
+
+## Tools
+
+The DSH plugin exposes 24 tools. Relative paths resolve against the active remote
+workspace; `host` is optional inside a workspace. Argument aliases are accepted at
+execute time (`path`/`file_path`/`filePath`, `old`/`oldString`, `new`/`newString`,
+`cwd`/`workdir`, …), so an agent's habitual spelling still works.
+
+<details>
+<summary><b>Show all tools</b></summary>
+
+| Tool | What it does |
+| --- | --- |
+| `presence_hosts` | List SSH hosts, connection state and default host (`format:"json"` supported); `workspace:true` marks this session's machine and `degraded` rows carry the last error. |
+| `presence_connect` | Open/reuse a host connection and report the remote identity. |
+| `presence_exec` | Run a remote command; `pipefail`, `background`, `waitForPort`, structured JSON, `saveStdout`; timeout defaults to 300 s; `progress` normalizes `\r` progress bars; long output spills to a remote file whose path is returned (`tailLines`); destructive commands dry-run first — `confirm:true` runs the whole command, `confirm:"partial"` runs only the safe segments. |
+| `presence_jobs` | Manage background jobs: `list`, `status`, `wait` (with `timedOut`), `stop` (with `alive`/`verified`/`portReleased`). |
+| `presence_read` | Read a remote file with line numbers, `offset`/`limit`, or `raw:true` for verbatim content. |
+| `presence_read_many` | Read 1–50 remote files in one call, with per-file byte/line caps. |
+| `presence_write` | Atomic write; preserves mode; returns real mode, size and full sha256; `ifMatchSha256` optimistic lock. |
+| `presence_edit` | Exact-text replacement or line-range replacement, with compact diff, `dryRun`, JSON fields. |
+| `presence_ls` | List a directory; `recursive`, `totalBytes`, JSON output. |
+| `presence_stat` | Batch `stat` for 1–100 paths: type, size, mode, mtime, optional sha256; missing paths return `exists:false`. |
+| `presence_mkdir` | Create a remote directory (recursive by default); idempotent when it already exists. |
+| `presence_move` | Rename or move a path inside the same machine; refuses to replace an existing file unless `overwrite:true`. |
+| `presence_copy` | Copy a remote file (SFTP stream, or `cp -p` for large files) or a directory with `recursive:true`. |
+| `presence_chmod` | Change permissions with an octal mode (`755`, `0644`), optionally recursive. |
+| `presence_diff` | Unified diff of two remote files, or a remote file against a local one; context lines and JSON stats. |
+| `presence_tail` | Read the last N lines of a remote file, or follow it for a bounded time (`follow:true`, `timeoutMs`). |
+| `presence_search` | Remote `rg`/`grep` search, count-only mode, JSON matches. |
+| `presence_glob` | Find remote files by glob with size/mtime. |
+| `presence_import` | Local → remote binary-safe upload with mode and sha256. |
+| `presence_export` | Remote → local real file (content-addressed), for preview or native apps. |
+| `presence_forward` | Forward a remote port to `127.0.0.1`; open/list/close with JSON. |
+| `presence_port_probe` | Check listeners and TCP reachability for up to 20 ports; `expect:open|closed`, polling. |
+| `presence_http_probe` | Wait for port → forward → local HTTP assertions → close → verify the local port was released. |
+| `presence_terminal` | Persistent PTY: `open` with `cwd`/`command`, `write` (`ackOnly`), `read`, `close`; tmux-backed sessions survive reconnects. |
+| `presence_trash` | Recoverable delete: move to remote trash, list/restore; batch `paths[]`; returns `sourceRemoved` and `restoreHint`. |
+
+</details>
+
+## Which tool for which path
+
+| Where the path lives | Use | Why |
+| --- | --- | --- |
+| under the workspace mount (`~/.dsh/presence/mounts/...`) | built-in `read` / `write` / `edit` / `grep` / `glob` | they reach the remote machine; `grep`/`glob` are routed to it automatically |
+| remote absolute path outside the workspace (`/data`, `/scratch`, GPFS) | `presence_read` / `write` / `edit` / `ls` / `stat` / `search` / `glob` | the built-in tools only see the mount, not the rest of the machine |
+| local file, for preview or Office | `presence_export` first, then `present` / native open | the mount path is virtual; only a real local file can be opened natively |
+
+## Long-running tasks
+
+`presence_exec` waits for the command, so it is the wrong tool for a training run, a
+build or a server. The recipe:
+
+```text
+1. presence_exec { command: "python train.py --lr 3e-4", background: true, label: "train-3e-4" }
+   → { id: "j7", pid: 4242, logPath: "/tmp/presence-jobs/....log" }
+2. presence_jobs { action: "wait", jobId: "j7" }        # blocks; no sleep+poll loop
+3. presence_tail { path: "/tmp/presence-jobs/....log", follow: true }   # watch progress
+```
+
+- `presence_jobs { action: "status" }` gives a snapshot; `stop` terminates the process
+  group and verifies the port was released.
+- Interactive work: `presence_terminal { action: "open", session: "train" }` — the
+  tmux-backed session survives a reconnect.
+- **Do not** start `nohup`, `tmux new-session` or a trailing `&` inside a foreground
+  `presence_exec` for long jobs: when the login-node session ends, the cluster may clean
+  up what it left behind. `background: true` already detaches through `setsid`; on
+  scheduler-managed clusters start the job with the cluster's own launcher
+  (`rlaunch -d …`, `salloc`/`sbatch`) so the scheduler owns it.
+
+## Safety and recovery
+
+- **Destructive commands never run unconfirmed.** `rm -r/-f`, `git clean -fdx`,
+  `find -delete`, `shred`, `truncate` and `dd of=` are first replayed with
+  no-op shims to expand their real targets; unset variables and protected paths
+  (workspace root, home, `/`, `.git`) are refused. A second call with
+  `confirm:true` is required to execute. A rejected mixed command also lists the
+  segments that are safe on their own (`Safe segments you can run separately:`);
+  `confirm:"partial"` runs only those. Removing one file with a literal
+  `rm -f <path>` inside the workspace is exempt — it cannot remove a tree.
+- **Prefer `presence_trash`** for anything under a workspace: it moves the path to
+  `~/.dsh/presence-trash/<timestamp>/` and returns a restore hint.
+- **Writes are atomic** and keep the original file mode; `presence_edit` refuses
+  ambiguous anchors instead of guessing.
+- **Read before write**: built-in `read`/`write`/`edit` share a read-before-write
+  guard; `presence_write` records the observation so both APIs can be mixed.
+
+## Configuration
+
+The plugin reads these environment variables on the host process:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `PRESENCE_HOST` | — | Default SSH host (alias from `~/.ssh/config` or a manual host). |
+| `PRESENCE_WORKSPACE` | — | `host:/abs/path` to bind a remote workspace. |
+| `PRESENCE_PASSWORD_<ALIAS>` | — | Password for a host; `<ALIAS>` is uppercase with non-alphanumerics replaced by `_`. |
+| `PRESENCE_MAX_CHANNELS` | 8 | Concurrent channels per connection. |
+| `PRESENCE_CONNECT_TIMEOUT_MS` | 25000 | Connection attempt timeout. |
+| `PRESENCE_IDLE_TIMEOUT_MS` | 900000 | Idle connection timeout (connections with terminals are kept). |
+| `PRESENCE_READ_ONLY` | false | Refuse writes/edits; reads, search and exec still work. |
+
+Full configuration and the path/permission matrix are in
+[docs/VERIFICATION.md](docs/VERIFICATION.md) and [docs/HANDOFF.md](docs/HANDOFF.md).
+
+## Development
+
+```sh
+npm install
+npm install --prefix .dev --ignore-scripts rollup @rollup/plugin-node-resolve \
+  @rollup/plugin-commonjs @rollup/plugin-terser codemirror @codemirror/language-data \
+  @codemirror/theme-one-dark
+node scripts/build-client.mjs
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/package.ps1 -Version 0.19.0
+# → dist/presence-plugin-0.19.0.zip
+```
+
+Tests need one SSH-reachable host unless noted:
+
+```sh
+node scripts/regression.mjs server     # transport, symlinks, timeouts, binary
+node scripts/job-probe.mjs server      # jobs + port forwarding
+node scripts/feature-probe.mjs server  # wait, sessions, pgid, readiness, search
+node scripts/import-probe.mjs server   # local→remote binary, mode, sha256
+node scripts/safety-probe.mjs server   # destructive guard + observation store
+node scripts/p0-guard-probe.mjs        # guard split/partial/single-rm (no host needed)
+```
+
+## Known limits
+
+- The mount path (`~/.dsh/presence/mounts/...`) is virtual: it works through
+  `ctx.fs` / agent tools, but native apps (Explorer, Office, host Python) cannot
+  see it — use `presence_export` first.
+- `presence_exec` defaults to a 300 s timeout; longer work must use `background: true`
+  (foreground output over the cap is spilled to a remote file, and `tailLines` keeps the
+  end of a long report). Background jobs are tracked per session, not persisted across a
+  DSH restart.
+- A login node may clean up processes left behind when a session closes: do not rely on
+  `nohup` / `tmux new-session` / `&` started inside a foreground `presence_exec` for long
+  jobs. Use `background: true` (detached with `setsid`) or `presence_terminal` (tmux),
+  and let the cluster scheduler own the job where required (`rlaunch -d`, `salloc`/`sbatch`).
+- Argument aliases are accepted (`path`/`file_path`/`filePath`, `old`/`oldString`,
+  `new`/`newString`, `replaceAll`/`replace_all`, `dryRun`/`dry_run`, `cwd`/`workdir`);
+  the canonical name is what the tool schema documents.
+- SSH `MaxSessions` (default 10) bounds concurrent channels; the pool uses at most 8.
+- PTY terminals follow the connection; cross-reconnect shells need `tmux` on the target
+  (used automatically by `presence_terminal { session }`).
+- ProxyJump/ProxyCommand are parsed and warned about, but not used for dialing yet.
+- `@` file completion indexes the remote tree lazily (about 10 s per workspace);
+  on a very large tree the first query can take a few seconds.
+- Port auto-restore runs when the connection is re-established; a forward whose
+  saved local port is already taken falls back to another free port.
+
+## Contributing
+
+Issues and PRs are welcome. For a feature, open an issue describing the remote
+workflow you want; for a fix, keep the diff focused and add a probe under
+`scripts/` when behavior changes.
+
+## License
+
+[MIT](LICENSE)
+
+## Star History
+
+[![Star History Chart](assets/star-history.png)](https://star-history.com/#fanrj3/dsh-presence&Date)

package/README.zh-CN.md

@@ -0,0 +1,288 @@
+<div align="center">
+
+<img src="assets/icon-180.png" width="88" alt="Presence icon" />
+
+# Presence
+
+**把 SSH 机器变成本地标签页。**
+
+给 coding agent 用的持久远程工作区、原生文件编辑、搜索、命令执行、终端和端口转发
+—— **远端不需要安装任何东西**。
+
+[English](README.md) · [简体中文](README.zh-CN.md) · [版本记录](docs/RELEASE.md) · [MCP server](mcp/README.md)
+
+[![npm plugin](https://img.shields.io/npm/v/@rjfan/dsh-presence?label=dsh%20plugin&color=2f6bff)](https://www.npmjs.com/package/@rjfan/dsh-presence)
+[![npm mcp](https://img.shields.io/npm/v/presence-mcp?label=presence-mcp&color=2f6bff)](https://www.npmjs.com/package/presence-mcp)
+[![license](https://img.shields.io/badge/license-MIT-2f6bff)](LICENSE)
+[![awesome-dsh-plugin](https://img.shields.io/badge/awesome--dsh--plugin-listing-2f6bff)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+
+</div>
+
+![Presence — 远程机器就是本地标签页](docs/social/cover-light.png)
+
+---
+
+## 为什么不是「agent 跑在远端」
+
+在每台服务器上装 agent，意味着装 N 次、升级 N 次、逐台配代理；让本地 agent 每次
+`ssh host '<command>'`，意味着每条命令一次握手、用不上原生文件工具、上下文不连续。
+
+Presence 让 agent 留在本机，**通过每台机器一条常驻 SSH 连接把能力伸到远端**。远端
+仍然只是普通的 `sshd`：SFTP、exec 和一个 PTY。
+
+| 方案 | 代价 |
+| --- | --- |
+| 每台机器装 agent | N 次安装、N 次升级、逐台代理配置 |
+| 每个操作 `ssh host '<cmd>'` | 每条命令一次握手、无文件工具、无会话 |
+| **Presence** | 每台机器一条连接、原生工具、远端零安装 |
+
+## 特性
+
+- **远端零安装** —— 只用 `sshd` 自带能力：SFTP 子系统、exec 通道和 PTY。
+- **一次握手** —— 连接池为每台机器保持一条连接，之后的调用都是这条连接上的请求。
+- **用目标机的原生工具** —— `rg`/`grep` 在目标机跑，命令在目标 shell 里执行；路径、权限、编码都是远端的语义。
+- **接近本地的编辑** —— 原子写、保留 mode、锚点歧义拒绝、读后写守卫、`presence_edit` 的 dry-run diff。
+- **真正的远程工作区** —— 远端目录注册成普通 DSH 工作区，文件树、终端都**开在远端机器上**。
+- **可恢复的删除** —— 危险 shell 命令先 dry-run；`presence_trash` 移入远端回收站并可恢复。
+- **`@` 能补全远端文件** —— 远程工作区里，文件引用补全直接索引目标机（`rg --files`，回退 `find`），不是本地镜像。
+- **文件操作不只是读** —— `presence_mkdir` / `move` / `copy` / `chmod`，文件树右键菜单直接操作；删除走可恢复回收站。
+- **Diff 与实时日志** —— 两个远端文件、或远端与本地文件之间的统一 diff；面板里直接跟随日志，不用常驻 `tail -f` 任务。
+- **转发会自己回来** —— 保存转发并自动恢复；端口面板发现新监听端口后可一键转发。
+- **任务完成通知** —— 后台任务结束时弹 toast（及桌面通知），也可配置本地 `notifyCommand` 推送到手机或守护进程。
+- **两种外壳，同一个内核** —— DSH 插件与独立 MCP server（`presence-mcp`，20 个核心工具）共用同一套内核。
+
+## 快速开始
+
+### 1. 安装 DSH 插件
+
+```sh
+dsh plugin add @rjfan/dsh-presence@0.19.0
+```
+
+从源码安装：
+
+```sh
+dsh plugin add /path/to/dsh-presence
+```
+
+### 2. 选一台机器，打开工作区
+
+打开 **设置 → Presence → 新建**，从 `~/.ssh/config` 选一台机器（或直接粘贴一条
+`ssh` 命令），再选一个远端目录。它会以工作区出现：左侧文件树、终端和 agent 工具
+都使用这个远端目录。
+
+### 3. 开始用
+
+```text
+你：把远程 8000 端口转发到本地，然后打开看看
+Agent: presence_forward { remotePort: 8000 }
+       → http://127.0.0.1:8000
+```
+
+## MCP server
+
+同样的能力也提供给装不了 DSH 插件的 agent（Codex CLI、Claude Code、OpenCode、Cursor 等）。
+
+```sh
+npx -y presence-mcp            # 20 个工具，走 stdio
+```
+
+```jsonc
+// Claude Desktop / OpenCode 风格
+{
+  "mcpServers": {
+    "presence": {
+      "command": "npx",
+      "args": ["-y", "presence-mcp"],
+      "env": {
+        "PRESENCE_HOST": "server",
+        "PRESENCE_WORKSPACE": "server:/srv/app"
+      }
+    }
+  }
+}
+```
+
+Codex TOML、Claude Code、OpenCode、Cursor/Windsurf 的完整配置见
+[mcp/README.md](mcp/README.md)。
+
+## 工作原理
+
+```text
+┌───────────────────────────────┐
+│  DSH 插件  /  MCP server      │  两种外壳，同一个内核
+└──────────────┬────────────────┘
+               │
+        Presence 内核
+        ├── ssh-config  从 ~/.ssh/config 读主机、端口、用户、密钥、跳板
+        ├── connection  一条常驻连接：SFTP / exec / PTY + 通道池 + 取消
+        └── host pool   每台机器一条连接，按需建立、闲置回收
+               │
+        SSH（沿用你已有的密钥、known_hosts、跳板、代理）
+               │
+        目标机：Linux / macOS，原生 sshd
+```
+
+| Agent 操作 | 通道 | 远端依赖 |
+| --- | --- | --- |
+| 读 / 写 / 编辑 / 列目录 / stat | SFTP 子系统 | sshd 自带 `sftp-server` |
+| 执行命令、搜索（rg/grep）、git | exec 通道 | 目标机已有的命令 |
+| 交互式终端 | shell 通道 + PTY | 目标机的登录 shell |
+
+Linux 主机上的实测：
+
+| 操作 | 延迟 |
+| --- | --- |
+| `ssh host '<cmd>'`（每次新连接） | 520–540 ms |
+| Presence 建连（一次握手，含密钥认证） | 145 ms |
+| Presence `sftp stat` | p50 0.6 ms / p95 0.9 ms |
+| Presence `exec true`（新通道 + shell） | p50 7.6 ms |
+| 8 个 exec 通道并发 | 合计 15 ms |
+
+> 必须保持 TCP_NODELAY：否则请求/响应会撞上 delayed ACK，p95 从 0.9 ms 劣化到 48 ms。
+
+## 工具
+
+DSH 插件提供 24 个工具。相对路径相对当前远程工作区；在工作区里 `host` 可省略。执行时接受
+参数别名（`path`/`file_path`/`filePath`、`old`/`oldString`、`new`/`newString`、
+`cwd`/`workdir` 等），习惯写法都能用。
+
+<details>
+<summary><b>展开全部工具</b></summary>
+
+| 工具 | 说明 |
+| --- | --- |
+| `presence_hosts` | 列出 SSH 主机、连接状态和默认主机（支持 `format:"json"`）；`workspace:true` 标记当前会话的机器，`degraded` 行带最后一次错误。 |
+| `presence_connect` | 建立/复用连接并返回远端身份。 |
+| `presence_exec` | 执行远端命令；`pipefail`、`background`、`waitForPort`、结构化 JSON、`saveStdout`；超时默认 300 秒；`progress` 归一化 `\r` 进度条；超长输出落盘到远端文件并返回路径（`tailLines`）；危险命令先 dry-run —— `confirm:true` 执行整条命令，`confirm:"partial"` 只执行安全分段。 |
+| `presence_jobs` | 后台任务：`list`、`status`、`wait`（含 `timedOut`）、`stop`（`alive`/`verified`/`portReleased`）。 |
+| `presence_read` | 读远端文件，带行号、`offset`/`limit`，`raw:true` 返回逐字节原样内容。 |
+| `presence_read_many` | 一次读 1–50 个文件，支持每文件字节/行数上限。 |
+| `presence_write` | 原子写；保留 mode；返回真实 mode、字节数和完整 sha256；`ifMatchSha256` 乐观锁。 |
+| `presence_edit` | 精确文本替换或行号区间替换，带紧凑 diff、`dryRun` 和 JSON 字段。 |
+| `presence_ls` | 列目录；`recursive`、`totalBytes`、JSON 输出。 |
+| `presence_stat` | 批量 `stat` 1–100 个路径：类型、大小、mode、mtime、可选 sha256；缺失路径返回 `exists:false`。 |
+| `presence_mkdir` | 创建远端目录（默认递归）；已存在时幂等成功。 |
+| `presence_move` | 同一台机器内重命名/移动；目标已存在时除非 `overwrite:true` 否则拒绝。 |
+| `presence_copy` | 复制远端文件（SFTP 流，大文件走 `cp -p`），目录需 `recursive:true`。 |
+| `presence_chmod` | 按八进制 mode 改权限（`755`/`0644`），可递归。 |
+| `presence_diff` | 两个远端文件、或远端与本地文件的统一 diff；支持上下文行数和 JSON 统计。 |
+| `presence_tail` | 读远端文件最后 N 行，或在限定时间内跟随（`follow:true`、`timeoutMs`）。 |
+| `presence_search` | 远端 `rg`/`grep` 搜索，`countOnly`，JSON matches。 |
+| `presence_glob` | 远端 glob 找文件，带 size/mtime。 |
+| `presence_import` | 本地 → 远端二进制安全上传，可设 mode，返回 sha256。 |
+| `presence_export` | 远端 → 本地真实文件（内容寻址），供预览或原生程序打开。 |
+| `presence_forward` | 远端端口转发到 `127.0.0.1`；open/list/close 支持 JSON。 |
+| `presence_port_probe` | 检查最多 20 个端口的监听与 TCP 可达性；`expect:open|closed` 可轮询。 |
+| `presence_http_probe` | 等端口 → 开转发 → 本地 HTTP 断言 → 关转发 → 验证本地端口已释放。 |
+| `presence_terminal` | 持久 PTY：`open` 可带 `cwd`/`command`，`write`（`ackOnly`）、`read`、`close`；tmux 会话可跨重连。 |
+| `presence_trash` | 可恢复删除：移入远端回收站、list/restore；支持批量 `paths[]`；返回 `sourceRemoved` 和 `restoreHint`。 |
+
+</details>
+
+## 路径与工具怎么选
+
+| 路径在哪 | 用什么 | 说明 |
+| --- | --- | --- |
+| 工作区挂载目录下（`~/.dsh/presence/mounts/...`） | 内置 `read` / `write` / `edit` / `grep` / `glob` | 都直达远端机器；`grep`/`glob` 会自动路由过去 |
+| 工作区之外的远端绝对路径（`/data`、`/scratch`、GPFS） | `presence_read` / `write` / `edit` / `ls` / `stat` / `search` / `glob` | 内置工具只看得到挂载目录，看不到整台机器 |
+| 本地文件（预览或 Office） | 先 `presence_export`，再 `present` / 原生打开 | 挂载路径是虚拟的，只有真实本地文件能被原生程序打开 |
+
+## 长时间任务
+
+`presence_exec` 会等命令结束，所以训练、构建、起服务都不该直接用它。推荐流程：
+
+```text
+1. presence_exec { command: "python train.py --lr 3e-4", background: true, label: "train-3e-4" }
+   → { id: "j7", pid: 4242, logPath: "/tmp/presence-jobs/....log" }
+2. presence_jobs { action: "wait", jobId: "j7" }        # 阻塞等待，不要 sleep+poll
+3. presence_tail { path: "/tmp/presence-jobs/....log", follow: true }   # 看进度
+```
+
+- `presence_jobs { action: "status" }` 取快照；`stop` 结束进程组并验证端口已释放。
+- 交互式任务：`presence_terminal { action: "open", session: "train" }`，tmux 会话跨重连存活。
+- **不要**在前台 `presence_exec` 里用 `nohup`、`tmux new-session` 或结尾 `&` 跑长任务：登录节点
+  会话结束时，集群可能清理残留进程。`background: true` 本身用 `setsid` 脱离；调度器管理的集群
+  请用集群自己的启动器（`rlaunch -d …`、`salloc`/`sbatch`），让调度器持有任务。
+
+## 安全与恢复
+
+- **危险命令不会直接执行。** `rm -r/-f`、`git clean -fdx`、`find -delete`、`shred`、
+  `truncate`、`dd of=` 会先用 no-op shim 重放以展开真实目标；未设置变量和受保护路径
+  （工作区根、家目录、`/`、`.git`）直接拒绝。必须再带 `confirm:true` 才会执行。被拒绝的
+  混合命令还会列出可单独执行的安全分段（`Safe segments you can run separately:`），
+  `confirm:"partial"` 只执行这些分段；工作区内对单个文件的字面量 `rm -f <路径>` 免检
+  （它不可能删掉一棵树）。
+- **工作区内删除优先 `presence_trash`**：移动到 `~/.dsh/presence-trash/<时间戳>/` 并返回恢复提示。
+- **写入是原子的**，保留原文件 mode；`presence_edit` 锚点不唯一时报错而不是猜。
+- **读后写守卫**：内置 `read`/`write`/`edit` 共享读后写守卫；`presence_write` 也会记账，两套 API 可混用。
+
+## 配置
+
+插件从宿主进程环境变量读取：
+
+| 变量 | 默认 | 含义 |
+| --- | --- | --- |
+| `PRESENCE_HOST` | — | 默认 SSH 主机（`~/.ssh/config` 别名或手动主机）。 |
+| `PRESENCE_WORKSPACE` | — | `host:/abs/path`，绑定一个远程工作区。 |
+| `PRESENCE_PASSWORD_<ALIAS>` | — | 某台机器的密码；`<ALIAS>` 大写、非字母数字换成 `_`。 |
+| `PRESENCE_MAX_CHANNELS` | 8 | 每连接并发通道数。 |
+| `PRESENCE_CONNECT_TIMEOUT_MS` | 25000 | 连接尝试超时。 |
+| `PRESENCE_IDLE_TIMEOUT_MS` | 900000 | 空闲连接回收时间（持终端连接不回收）。 |
+| `PRESENCE_READ_ONLY` | false | 拒绝写入/编辑；读取、搜索、执行不受影响。 |
+
+完整配置与路径/权限矩阵见 [docs/VERIFICATION.md](docs/VERIFICATION.md) 和
+[docs/HANDOFF.md](docs/HANDOFF.md)。
+
+## 开发
+
+```sh
+npm install
+npm install --prefix .dev --ignore-scripts rollup @rollup/plugin-node-resolve \
+  @rollup/plugin-commonjs @rollup/plugin-terser codemirror @codemirror/language-data \
+  @codemirror/theme-one-dark
+node scripts/build-client.mjs
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/package.ps1 -Version 0.19.0
+# → dist/presence-plugin-0.19.0.zip
+```
+
+验证脚本需要一台可 SSH 的主机（标注“不需要真机”的除外）：
+
+```sh
+node scripts/regression.mjs server     # 传输层、符号链接、超时、二进制
+node scripts/job-probe.mjs server      # 后台任务 + 端口转发
+node scripts/feature-probe.mjs server  # wait、会话、pgid、就绪、搜索
+node scripts/import-probe.mjs server   # 本地→远端二进制、mode、sha256
+node scripts/safety-probe.mjs server   # 危险命令护栏 + 观测状态
+node scripts/p0-guard-probe.mjs        # 危险命令分段/单文件豁免（不需要真机）
+```
+
+## 已知边界
+
+- 挂载路径（`~/.dsh/presence/mounts/...`）是虚拟的：对 `ctx.fs` / agent 工具有效，
+  但 Explorer、Office、宿主 Python 看不到 —— 需要先用 `presence_export`。
+- `presence_exec` 超时默认 300 秒；更长的任务必须用 `background: true`（前台输出超限会
+  落盘到远端文件，`tailLines` 保留长报告末尾）。后台任务按会话跟踪，不跨 DSH 重启持久化。
+- 登录节点可能在会话结束时清理残留进程：不要在前台 `presence_exec` 里用 `nohup` /
+  `tmux new-session` / `&` 跑长任务。用 `background: true`（`setsid` 脱离）或
+  `presence_terminal`（tmux）；集群上让调度器持有任务（`rlaunch -d`、`salloc`/`sbatch`）。
+- 参数别名可用（`path`/`file_path`/`filePath`、`old`/`oldString`、`new`/`newString`、
+  `replaceAll`/`replace_all`、`dryRun`/`dry_run`、`cwd`/`workdir`）；schema 里记录的是规范名。
+- sshd 的 `MaxSessions`（默认 10）限制并发通道；连接池最多用 8 个。
+- PTY 终端跟随连接存活；跨重连的 shell 需要目标机有 `tmux`（`presence_terminal { session }` 自动使用）。
+- ProxyJump / ProxyCommand 会被解析并提示，但目前不用于实际拨号。
+- `@` 文件补全按工作区惰性索引远端树（约 10 秒缓存）；超大目录首次查询可能要几秒。
+- 端口自动恢复在连接重建时执行；若保存的本地端口已被占用，会回退到其它空闲端口。
+
+## 参与贡献
+
+欢迎 issue 和 PR。新功能请先开 issue 描述你的远程工作流；修 bug 请保持 diff 聚焦，
+行为变化时在 `scripts/` 下补一个探针。
+
+## License
+
+[MIT](LICENSE)
+
+## Star History
+
+[![Star History Chart](assets/star-history.png)](https://star-history.com/#fanrj3/dsh-presence&Date)