@znmin/claude-remote-cli 0.2.6 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@
 
 ## 安装
 
-要求：Node.js **20.11 或更高版本**、npm 和 OpenSSH 客户端。本地模式需要 `ssh`，自动配置免密登录需要 `ssh-keygen`，服务器同步模式另外需要 `scp` 和系统 `tar`。支持 macOS/Linux 的 x64、arm64；Windows 请在 WSL 内使用。本地无需 Python、Homebrew 或 Anthropic 的 Claude Code。
+要求：Node.js **20.11 或更高版本**、npm 和 OpenSSH 客户端。本地模式需要 `ssh`，自动配置免密登录需要 `ssh-keygen`，服务器同步模式另外需要 `scp` 和系统 `tar`。支持 macOS、Linux 和 Windows 10/11 的 x64、arm64（Windows 见下方说明，也仍可在 WSL 内按 Linux 方式使用）。本地无需 Python、Homebrew 或 Anthropic 的 Claude Code。
 
 npm 包名为 `@znmin/claude-remote-cli`，安装后提供 `claude` 和 `claude-remote` 命令。
 
@@ -25,15 +25,33 @@ npm install -g git+https://github.com/znmin/claude-remote-cli.git
 也可以从已下载的分发包安装：
 
 ```bash
-npm install -g ./znmin-claude-remote-cli-0.2.6.tgz
+npm install -g ./znmin-claude-remote-cli-0.3.0.tgz
 ```
 
-若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.2.6.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
+若系统 npm 全局目录不可写，可使用 `npm install -g --prefix "$HOME/.local" ./znmin-claude-remote-cli-0.3.0.tgz`，并确保 `~/.local/bin` 在 PATH 中；卸载时也使用相同的 `--prefix`。
 
 npm 中不带作用域的 `claude-remote-cli` 属于其他项目。本项目使用独立的 `@znmin/claude-remote-cli` 作用域包名；请安装完整包名，或使用上述 GitHub 地址及本项目分发的 `.tgz` 文件。
 
 依赖按模式准备：本地模式首次启动准备 Playwright Chromium，服务器模式首次启动准备 Mutagen 0.18.1。Mutagen 复用 PATH 中的匹配版本，或从官方 GitHub Release 下载并校验内置 SHA-256。浏览器和同步组件需要网络和额外磁盘空间；npm 安装本身不强制下载这些二进制文件。
 
+### Windows（0.3.0）
+
+在 PowerShell 或 Windows Terminal 中直接安装和运行，与 macOS/Linux 使用同一套命令：
+
+```powershell
+npm install -g @znmin/claude-remote-cli
+claude-remote configure user@example.com
+cd C:\path\to\project
+claude
+```
+
+- 需要 Windows 自带的 OpenSSH 客户端（Windows 11 和 Windows 10 1809 以上默认安装；若 `ssh` 不可用，在“设置 → 系统 → 可选功能”中添加“OpenSSH 客户端”）。服务器同步模式另外使用系统自带的 `C:\Windows\System32\tar.exe`。
+- 本地终端工具优先使用 Git Bash（[Git for Windows](https://git-scm.com/download/win)，与 Claude Code 原生 Windows 版相同的查找顺序，也读取 `CLAUDE_CODE_GIT_BASH_PATH`）；未安装时使用 PowerShell（优先 `pwsh`）。可用 `CLAUDE_REMOTE_SHELL` 指定 `bash.exe` 或 `powershell.exe`/`pwsh.exe` 的完整路径。`claude-remote doctor` 会显示当前选择。建议安装 Git Bash，模型编写 bash 命令更可靠。
+- Windows 的 OpenSSH 不支持连接复用（ControlMaster）。本地模式的反向隧道使用独立 SSH 连接，其他服务器命令各自建立连接，依赖已配置的免密登录。首次 `setup-ssh` 可能需要输入两次服务器密码（读取服务器策略、添加公钥各一次）；完成后不再需要。`~/.ssh/config` 中写入的 `IdentityFile` 使用正斜杠路径。
+- 停止本地后台进程时使用 `taskkill /T /F` 结束整个进程树；父进程已退出后自行脱离的子进程不在清理范围内。
+- 文件工具在 Windows 上按不区分大小写的方式判断路径是否位于项目内。CRLF 换行的文件读取和搜索时不显示 `\r`，`edit_file` 按 LF 文本匹配时会保留原有 CRLF 换行（适用于所有平台）。
+- 卸载、配置和缓存目录与其他平台相同，分别位于 `%USERPROFILE%\.config\claude-remote`、`%USERPROFILE%\.cache\claude-remote` 和 `%USERPROFILE%\.ssh\claude-remote`。
+
 如果用户已经安装其他提供 `claude` 命令的软件，应先卸载旧客户端，避免 npm 命令冲突或 PATH 指向旧程序。无需使用 `--force` 覆盖。
 
 ## 开始使用
@@ -131,6 +149,7 @@ claude-remote configure my-server --mode local
 - 浏览器元素选择器在多次快照间保持不变；快照包含 iframe（选择器形如 `frame=1 >> …`）和开放的 Shadow DOM 元素；截图支持整页和单个元素。
 - 本地项目的 `CLAUDE.md`、`.claude/CLAUDE.md`、`CLAUDE.local.md` 在启动时读取并放入系统提示（合计最多 64 KiB），不再依赖模型自行读取。
 - 关闭终端窗口（SIGHUP）或被 `kill`（SIGTERM）时也会清理浏览器、后台命令、SSH 隧道和服务器临时文件。
+- 0.2.7 起，SSH 断线等原因导致远程 Claude 异常结束时，会自动关闭它遗留的鼠标上报、焦点事件、括号粘贴和扩展键盘等终端模式，避免移动鼠标或按键时输出乱码。若仍显示异常（例如停留在全屏界面），可运行 `reset`。
 - 启动时浏览器检查与 SSH 连接并行，浏览器已就绪时不再调用 Playwright 安装程序；服务器上的版本检查和配置写入合并为一次往返。
 
 Git、npm、pnpm、Python、Go、Docker、数据库 CLI、`gh` 等共用本地终端，不需要逐项适配，仍需在本机安装并具备必要的登录、连接配置及权限。终端继承启动用户环境和登录 shell，默认工作目录为当前项目。长任务使用后台进程，再查询日志和停止；退出会话会停止仍受本工具管理的进程组，自行 daemonize 或逃离原进程组的程序不在自动清理保证内。
@@ -219,6 +238,7 @@ CLAUDE_REMOTE_DEBUG=1 claude
 | `CLAUDE_REMOTE_PREPARE_SYNC=1` | npm 安装阶段提前准备同步工具，默认按需准备 |
 | `CLAUDE_REMOTE_SKIP_DOWNLOAD=1` | 跳过安装阶段的同步工具准备 |
 | `CLAUDE_REMOTE_DEBUG=1` | 显示详细启动过程和错误堆栈 |
+| `CLAUDE_REMOTE_SHELL` | 仅 Windows：本地终端使用的 `bash.exe` 或 `pwsh.exe`/`powershell.exe` 完整路径 |
 
 `npm install --ignore-scripts` 也受支持，首次使用各模式时准备对应组件。无法访问 GitHub 时可自行准备 Mutagen 并使用 `CLAUDE_REMOTE_MUTAGEN`。浏览器缓存由 Playwright 管理，支持其 `PLAYWRIGHT_BROWSERS_PATH` 环境变量。
 
@@ -230,12 +250,13 @@ CLAUDE_REMOTE_DEBUG=1 claude
 npm ci --ignore-scripts
 npm run lint
 npm test
+npm run test:windows   # Windows 上运行的客户端测试（CI 在 windows-latest 运行）
 
 # 可选：真实本地同步与受控浏览器测试
 CLAUDE_REMOTE_INTEGRATION=1 CLAUDE_REMOTE_BROWSER_TEST=1 npm test
 
 npm pack
-npm install -g ./znmin-claude-remote-cli-0.2.6.tgz
+npm install -g ./znmin-claude-remote-cli-0.3.0.tgz
 
 # 确定包名、版本和使用条款后，使用有发布权限的 npm 账号发布
 npm login
@@ -244,6 +265,6 @@ npm publish --access public
 
 GitHub 仓库名为 `claude-remote-cli`，npm 包名为 `@znmin/claude-remote-cli`，命令名为 `claude` 和 `claude-remote`。发布账号必须拥有 npm 用户作用域 `@znmin`，或拥有同名 npm 组织的发布权限；GitHub 身份不会自动授予 npm 权限。当前 `license` 为 `UNLICENSED`，尚未指定开源许可证。
 
-测试覆盖真实 MCP HTTP 调用、本机文件与进程、受控浏览器交互、本地真实同步、模拟 SSH/Claude 的完整启动清理链路，以及官方安装流程的隔离模拟。真实服务器完整启动、Claude 模型端到端调用、Linux 和其他 CPU 架构尚未完成实测。
+测试覆盖真实 MCP HTTP 调用、本机文件与进程、受控浏览器交互、本地真实同步、模拟 SSH/Claude 的完整启动清理链路，以及官方安装流程的隔离模拟。真实服务器完整启动、Claude 模型端到端调用、Linux 和其他 CPU 架构尚未完成实测。Windows 客户端的命令构造、隧道端口解析和免密配置流程在 macOS 上以模拟方式测试，真实 Windows 终端测试在 CI 的 windows-latest 运行；尚未在真实 Windows 电脑上连接服务器实测。
 
 参考：[npm 命令入口配置](https://docs.npmjs.com/cli/configuring-npm/package-json#bin)、[Mutagen 同步机制](https://mutagen.io/documentation/synchronization/)、[Mutagen SSH 支持](https://mutagen.io/documentation/transports/ssh/)。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@znmin/claude-remote-cli",
-  "version": "0.2.6",
-  "description": "Run Claude Code on an SSH server with local filesystem, terminal and browser tools, or remote bidirectional sync",
+  "version": "0.3.0",
+  "description": "Run Claude Code on an SSH server from macOS, Linux or Windows with local filesystem, terminal and browser tools, or remote bidirectional sync",
   "type": "module",
   "license": "UNLICENSED",
   "engines": {
@@ -9,7 +9,8 @@
   },
   "os": [
     "darwin",
-    "linux"
+    "linux",
+    "win32"
   ],
   "cpu": [
     "x64",
@@ -30,6 +31,7 @@
     "postinstall": "node scripts/postinstall.js",
     "lint": "eslint .",
     "test": "node --test test/*.test.js",
+    "test:windows": "node --test test/windows.test.js test/local-tools.test.js",
     "prepublishOnly": "npm run lint && npm test"
   },
   "keywords": [

package/src/cli.js

@@ -1,7 +1,7 @@
 import { parseArgs } from 'node:util';
 import { createInterface } from 'node:readline/promises';
 import { Client, DEFAULTS } from './client.js';
-import { cachedBinary, ensureMutagen, VERSION } from './installer.js';
+import { cachedBinary, ensureMutagen, findTar, VERSION } from './installer.js';
 import { exists, installSignalHandlers, readJSON, which } from './system.js';
 import { readFileSync } from 'node:fs';
 
@@ -121,7 +121,13 @@ export async function main(asClaude, args = process.argv.slice(2), client = new
     const [major, minor] = process.versions.node.split('.').map(Number);
     const nodeOk = major > 20 || major === 20 && minor >= 11;
     console.log(`Node.js：${process.version}${nodeOk ? '' : '（需要 20.11 或更高版本）'}\n平台：${process.platform}/${process.arch}`);
-    for (const tool of ['ssh', 'ssh-keygen', 'scp', 'tar']) console.log(`${tool}：${await which(tool, client.env.PATH) || '未安装'}`);
+    for (const tool of ['ssh', 'ssh-keygen', 'scp']) console.log(`${tool}：${await which(tool, client.env.PATH) || '未安装'}`);
+    console.log(`tar：${await findTar(client.env) || '未安装'}`);
+    if (process.platform === 'win32') {
+      const { describeShell, findShell } = await import('./local/shell.js');
+      const shell = await findShell(client.env);
+      console.log(`本地终端：${describeShell(shell)}（${shell.file}）${shell.kind === 'powershell' ? '；安装 Git for Windows 后改用 Git Bash' : ''}`);
+    }
     try {
       const { browserReady } = await import('./local/browser.js');
       const { chromium } = await import('playwright');

package/src/client.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import { createHash, randomUUID } from 'node:crypto';
-import { execute, exists, quote, readJSON, shellJoin, which, withLock, writeJSON } from './system.js';
+import { execute, exists, quote, readJSON, restoreTerminal, shellJoin, which, withLock, writeJSON } from './system.js';
 import { ensureMutagen } from './installer.js';
 import { ensureRemoteClaude, remoteEnvironment as prefix } from './remote-claude.js';
 import { sshArgs } from './ssh.js';
@@ -54,6 +54,7 @@ export class Client {
     this.env = options.env || process.env;
     this.home = options.home || os.homedir();
     this.cwd = options.cwd || process.cwd();
+    this.platform = options.platform || process.platform;
     this.directory = options.configDir || this.env.CLAUDE_REMOTE_CONFIG_DIR || path.join(this.home, '.config', 'claude-remote');
     this.configFile = path.join(this.directory, 'config.json');
     this.registryFile = path.join(this.directory, 'projects.json');
@@ -67,6 +68,7 @@ export class Client {
       if (this.env.CLAUDE_REMOTE_DEBUG === '1') this.log(...messages);
     };
     this.tty = options.tty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    this.restoreTerminal = options.restoreTerminal || (() => restoreTerminal());
   }
 
   async configure(input) {
@@ -204,6 +206,8 @@ export class Client {
     try {
       code = (await this.remote(config, prefix + 'cd -- ' + remotePath(item.remote) +
         ' && exec ' + shellJoin([config.claude, ...extra]), true)).code;
+      // A dropped connection leaves the remote UI's terminal modes switched on.
+      if (code !== 0) this.restoreTerminal();
     } finally {
       try { await this.flush(item.name); }
       catch (error) {

package/src/installer.js

@@ -5,7 +5,7 @@ import { Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { execute, exists, which, withLock } from './system.js';
+import { execute, exists, rename, which, withLock } from './system.js';
 
 export const VERSION = '0.18.1';
 // SHA256SUMS from the official v0.18.1 release, pinned in this package.
@@ -13,12 +13,26 @@ export const RELEASES = {
   'darwin-x64': ['darwin_amd64', '7d06f7d8fcfe90bc7e55cc834a2f2f20c2e0af9ea9bc35911fc4341ad56a9bbf'],
   'darwin-arm64': ['darwin_arm64', '6f810416d9e5fc4fd5e18431146f8b3c5a2056ba5a24f76c1e66da86eb3257e2'],
   'linux-x64': ['linux_amd64', '7735286c778cc438418209f24d03a64f3a0151c8065ef0fe079cfaf093af6f8f'],
-  'linux-arm64': ['linux_arm64', 'bcba735aebf8cbc11da9b3742118a665599ac697fa06bc5751cac8dcd540db8a']
+  'linux-arm64': ['linux_arm64', 'bcba735aebf8cbc11da9b3742118a665599ac697fa06bc5751cac8dcd540db8a'],
+  'win32-x64': ['windows_amd64', '3e237e77f69959ed520a0f877330a431507bb0a85d9da7919764ba0c87b702c7'],
+  'win32-arm64': ['windows_arm64', '9ac53447e46f019be9d37f49c00eeed8635966b885ed29ef06b3ff19afdee532']
 };
 
+const executableName = (platform = process.platform) => platform === 'win32' ? 'mutagen.exe' : 'mutagen';
+
+// Windows ships bsdtar in System32, which reads these archives. A GNU tar
+// earlier in PATH (e.g. from Git) would treat "C:" in a path as a remote host.
+export async function findTar(env = process.env, platform = process.platform) {
+  if (platform === 'win32') {
+    const system = path.win32.join(env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows', 'System32', 'tar.exe');
+    if (await exists(system)) return system;
+  }
+  return which('tar', env.PATH, { platform });
+}
+
 export function cachedBinary(env = process.env) {
   return path.join(env.CLAUDE_REMOTE_CACHE_DIR || path.join(os.homedir(), '.cache', 'claude-remote'),
-    `mutagen-${VERSION}-${process.platform}-${process.arch}`, 'mutagen');
+    `mutagen-${VERSION}-${process.platform}-${process.arch}`, executableName());
 }
 
 export async function verifyChecksum(file, expected) {
@@ -39,7 +53,7 @@ async function download(url, file) {
 }
 
 export async function ensureMutagen({ env = process.env, forceDownload = false } = {}) {
-  if (!RELEASES[`${process.platform}-${process.arch}`]) throw new Error('此版本支持 macOS/Linux 的 x64、arm64；Windows 请在 WSL 中使用。');
+  if (!RELEASES[`${process.platform}-${process.arch}`]) throw new Error('同步工具支持 macOS、Linux 和 Windows 的 x64、arm64。');
   if (env.CLAUDE_REMOTE_MUTAGEN) {
     const binary = path.resolve(env.CLAUDE_REMOTE_MUTAGEN);
     await execute(binary, ['version'], { capture: true, timeout: 10000, env });
@@ -57,8 +71,8 @@ export async function ensureMutagen({ env = process.env, forceDownload = false }
   const destination = path.dirname(binary);
   return withLock(destination + '.lock', async () => {
     if (await exists(binary) && await exists(path.join(destination, 'mutagen-agents.tar.gz'))) return binary;
-    const tar = await which('tar', env.PATH);
-    if (!tar) throw new Error('找不到系统 tar，无法解压同步工具。请安装 tar 后重试。');
+    const tar = await findTar(env);
+    if (!tar) throw new Error('找不到系统 tar，无法解压同步工具。请安装 tar 后重试（Windows 10 1803 及以上自带）。');
     const [platform, checksum] = RELEASES[`${process.platform}-${process.arch}`];
     const archiveName = `mutagen_${platform}_v${VERSION}.tar.gz`;
     const temporary = await fs.mkdtemp(path.join(path.dirname(destination), '.mutagen-install-'));
@@ -70,11 +84,12 @@ export async function ensureMutagen({ env = process.env, forceDownload = false }
       // Extract only the two required files from the authenticated archive.
       const unpacked = path.join(temporary, 'unpacked');
       await fs.mkdir(unpacked);
-      await execute(tar, ['-xzf', archive, '-C', unpacked, 'mutagen', 'mutagen-agents.tar.gz'], { timeout: 60000, env });
-      await fs.chmod(path.join(unpacked, 'mutagen'), 0o755);
-      await execute(path.join(unpacked, 'mutagen'), ['version'], { capture: true, timeout: 10000, env });
-      if (await exists(destination)) await fs.rename(destination, path.join(temporary, 'old-cache'));
-      await fs.rename(unpacked, destination);
+      const name = executableName();
+      await execute(tar, ['-xzf', archive, '-C', unpacked, name, 'mutagen-agents.tar.gz'], { timeout: 60000, env });
+      await fs.chmod(path.join(unpacked, name), 0o755);
+      await execute(path.join(unpacked, name), ['version'], { capture: true, timeout: 10000, env });
+      if (await exists(destination)) await rename(destination, path.join(temporary, 'old-cache'));
+      await rename(unpacked, destination);
       return binary;
     } finally { await fs.rm(temporary, { recursive: true, force: true }); }
   });

package/src/local/processes.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { quote } from '../system.js';
+import path from 'node:path';
+import { findShell, prepareCommand } from './shell.js';
 
 // Characters retained per stream; older output is dropped but offsets stay absolute.
 const LIMIT = 256 * 1024;
@@ -8,7 +9,12 @@ const PREVIEW = 8000;
 const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
 
 export class Processes {
-  constructor(workspace, env = process.env) { this.workspace = workspace; this.env = env; this.jobs = new Map(); }
+  constructor(workspace, env = process.env, { platform = process.platform, shell } = {}) {
+    this.workspace = workspace; this.env = env; this.platform = platform; this.jobs = new Map();
+    if (shell) this.shellChoice = Promise.resolve(shell);
+  }
+
+  shell() { return this.shellChoice ||= findShell(this.env, this.platform); }
 
   job(id) {
     const job = this.jobs.get(id);
@@ -49,10 +55,16 @@ export class Processes {
     if ([...this.jobs.values()].filter(job => !job.ended).length >= 16) throw new Error('后台进程过多，请先停止部分进程。');
     for (const [id, job] of this.jobs) if (this.jobs.size >= 64 && job.ended) this.jobs.delete(id);
     const directory = await this.workspace.resolve(cwd);
-    const shell = this.env.SHELL || '/bin/bash';
-    const child = spawn(shell, ['-lc', `cd -- ${quote(directory)} && ${command}`], {
-      cwd: directory, env: this.env, detached: true, stdio: ['ignore', 'pipe', 'pipe']
-    });
+    const prepared = await prepareCommand(await this.shell(), command, directory, this.env);
+    const windows = this.platform === 'win32';
+    // POSIX: a new process group, stopped as a whole. Windows: no new console
+    // window; the process tree is stopped with taskkill instead.
+    let child;
+    try {
+      child = spawn(prepared.file, prepared.args, {
+        cwd: directory, env: prepared.env, detached: !windows, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe']
+      });
+    } catch (error) { await prepared.cleanup(); throw error; }
     const id = randomUUID();
     const job = { child, cwd: directory, ended: false,
       stdout: { text: '', dropped: 0 }, stderr: { text: '', dropped: 0 } };
@@ -70,7 +82,7 @@ export class Processes {
       });
       child.once('error', error => { job.stderr.text += error.message; job.code = 127; job.ended = true; resolve(); });
       child.once('close', (code, sig) => { job.code = code; job.signal = sig; job.ended = true; resolve(); });
-    });
+    }).finally(prepared.cleanup);
     if (background) {
       await Promise.race([job.done, delay(80)]);
       return this.status(id);
@@ -91,9 +103,27 @@ export class Processes {
     catch (error) { if (error.code !== 'ESRCH') throw error; }
   }
 
+  // Console programs ignore taskkill's polite close request, so the tree is
+  // stopped forcefully. It only reaches processes whose parent is still alive.
+  killTree(job) {
+    if (!job.child.pid) return Promise.resolve();
+    const taskkill = path.win32.join(this.env.SystemRoot || this.env.SYSTEMROOT || 'C:\\Windows', 'System32', 'taskkill.exe');
+    return new Promise(resolve => {
+      const killer = spawn(taskkill, ['/PID', String(job.child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+      killer.once('error', resolve); killer.once('close', resolve);
+    });
+  }
+
   async stop(id) {
     const job = this.job(id);
     if (job.ended) return this.status(id);
+    if (this.platform === 'win32') {
+      await this.killTree(job);
+      await Promise.race([job.done, delay(1500)]);
+      if (!job.ended) job.child.kill();
+      await Promise.race([job.done, delay(1000)]);
+      return this.status(id);
+    }
     // Kill the owned group even if its parent shell has already exited.
     this.killGroup(job, 'SIGTERM');
     await Promise.race([job.done, delay(1500)]);

package/src/local/server.js

@@ -8,6 +8,7 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { z } from 'zod';
 import { Workspace } from './workspace.js';
 import { Processes } from './processes.js';
+import { describeShell } from './shell.js';
 import { Browser } from './browser.js';
 
 const PACKAGE = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
@@ -60,8 +61,15 @@ export async function startLocalServer({ root, env = process.env, headless = fal
       });
     };
     register('workspace_info', 'Describe the LOCAL computer and project. All tools execute on this computer, not the SSH server.', {},
-      () => ({ root: workspace.root, platform: os.platform(), shell: env.SHELL || '/bin/bash',
-        instructions: 'Use local absolute or project-relative paths. Use background=true for development servers, then process_status for logs. Browser selectors come from browser_snapshot. Terminal commands run as the local user.' }), true);
+      async () => {
+        const shell = await processes.shell();
+        const windows = os.platform() === 'win32';
+        const shellNote = !windows ? '' : shell.kind === 'bash'
+          ? ' This is Windows: run_command uses Git Bash, so write bash; Windows programs (git, npm, node, python) are on PATH, and C:/path style paths work.'
+          : ' This is Windows without Git Bash: run_command uses PowerShell, so write PowerShell commands (not bash or cmd syntax).';
+        return { root: workspace.root, platform: os.platform(), shell: shell.file, ...(windows ? { shell_kind: describeShell(shell) } : {}),
+          instructions: 'Use local absolute or project-relative paths. Use background=true for development servers, then process_status for logs. Browser selectors come from browser_snapshot. Terminal commands run as the local user.' + shellNote };
+      }, true);
     register('read_file', 'Read a LOCAL project text file, with line numbers and a SHA-256 for safe replacement. Large reads stop early and return next_offset to continue from.', {
       path: file, offset: z.number().int().min(1).default(1), limit: z.number().int().min(1).max(2000).default(200)
     }, args => workspace.read(args.path, args.offset, args.limit), true);

package/src/local/shell.js

@@ -0,0 +1,72 @@
+import * as fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { exists, quote, which } from '../system.js';
+
+const win = path.win32;
+export const psQuote = value => "'" + String(value).replaceAll("'", "''") + "'";
+
+// Git Bash locations, in the order Claude Code itself looks for them.
+export async function gitBashCandidates(env = process.env) {
+  const candidates = [];
+  if (env.CLAUDE_CODE_GIT_BASH_PATH) candidates.push(env.CLAUDE_CODE_GIT_BASH_PATH);
+  const git = await which('git', env.PATH || env.Path || '', { platform: 'win32' });
+  if (git) {
+    // <Git>\cmd\git.exe, <Git>\bin\git.exe or <Git>\mingw64\bin\git.exe
+    let root = win.dirname(win.dirname(git));
+    if (/^mingw(32|64)$/i.test(win.basename(root))) root = win.dirname(root);
+    candidates.push(win.join(root, 'bin', 'bash.exe'));
+  }
+  for (const base of [env.ProgramFiles, env.ProgramW6432, env['ProgramFiles(x86)']]) if (base) candidates.push(win.join(base, 'Git', 'bin', 'bash.exe'));
+  if (env.LOCALAPPDATA) candidates.push(win.join(env.LOCALAPPDATA, 'Programs', 'Git', 'bin', 'bash.exe'));
+  return [...new Set(candidates)];
+}
+
+// The shell behind run_command. POSIX keeps the user's login shell. Windows
+// prefers Git Bash (the model writes bash most reliably), then PowerShell.
+// C:\Windows\System32\bash.exe is WSL, which would run in a different system,
+// so bash is never taken from PATH there.
+export async function findShell(env = process.env, platform = process.platform) {
+  if (platform !== 'win32') return { kind: 'posix', file: env.SHELL || '/bin/bash' };
+  const chosen = env.CLAUDE_REMOTE_SHELL;
+  if (chosen) return { kind: /(^|[\\/])(pwsh|powershell)(\.exe)?$/i.test(chosen) ? 'powershell' : 'bash', file: chosen };
+  for (const file of await gitBashCandidates(env)) if (await exists(file)) return { kind: 'bash', file };
+  const pwsh = await which('pwsh', env.PATH || env.Path || '', { platform });
+  if (pwsh) return { kind: 'powershell', file: pwsh };
+  return { kind: 'powershell',
+    file: win.join(env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe') };
+}
+
+export function describeShell(shell) {
+  if (shell.kind === 'bash') return 'Git Bash';
+  if (shell.kind === 'powershell') return 'PowerShell';
+  return path.basename(shell.file);
+}
+
+// Windows limits a command line to 32767 characters, so commands there are
+// written to a temporary script instead of being passed as an argument.
+export async function prepareCommand(shell, command, directory, env = process.env) {
+  if (shell.kind === 'posix')
+    return { file: shell.file, args: ['-lc', `cd -- ${quote(directory)} && ${command}`], env, cleanup: async () => {} };
+  const script = path.join(os.tmpdir(), `claude-remote-${randomUUID()}.${shell.kind === 'bash' ? 'sh' : 'ps1'}`);
+  const cleanup = () => fs.rm(script, { force: true }).catch(() => {});
+  if (shell.kind === 'bash') {
+    // MSYS accepts C:/x paths. CHERE_INVOKING stops the login profile from changing to $HOME.
+    await fs.writeFile(script, `cd -- ${quote(directory.replaceAll('\\', '/'))} || exit 1\n${command}\n`, { mode: 0o600 });
+    return { file: shell.file, args: ['-l', script.replaceAll('\\', '/')], env: { ...env, CHERE_INVOKING: '1' }, cleanup };
+  }
+  // A BOM makes Windows PowerShell 5.1 read the script as UTF-8. Mirror bash:
+  // the exit code follows the last statement, including native programs.
+  await fs.writeFile(script, '\uFEFF' + [
+    "$ProgressPreference = 'SilentlyContinue'",
+    'try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}',
+    '$OutputEncoding = [System.Text.Encoding]::UTF8',
+    'Set-Location -LiteralPath ' + psQuote(directory),
+    command,
+    'if (-not $?) { if ($LASTEXITCODE) { exit $LASTEXITCODE }; exit 1 }',
+    'exit 0', ''
+  ].join('\r\n'), { mode: 0o600 });
+  return { file: shell.file, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', script],
+    env, cleanup };
+}

package/src/local/tunnel.js

@@ -6,7 +6,55 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { execute, exists, trackChild } from '../system.js';
 import { sshBase } from '../ssh.js';
 
-export async function openTunnel(config, localPort, { env = process.env, run = execute } = {}) {
+const ALLOCATED = /^Allocated port (\d+) for remote forward\b/;
+
+// Windows OpenSSH has no connection multiplexing (ControlMaster), so the
+// reverse forward runs in its own connection and the server-chosen port is
+// read from ssh's "Allocated port" message. Other commands then open their own
+// connections, which works because key login is set up before this point.
+export async function openDirectTunnel(config, localPort, { env = process.env, spawnProcess = spawn, timeoutMs = 120000 } = {}) {
+  const child = trackChild(spawnProcess('ssh', [...sshBase(config), '-o', 'ExitOnForwardFailure=yes', '-o', 'LogLevel=INFO',
+    '-N', '-T', '-R', `127.0.0.1:0:127.0.0.1:${localPort}`, config.host],
+  { env, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true }));
+  let closed = false, errorText = '', spawnError, port, pending = '', announce;
+  const allocated = new Promise(resolve => { announce = resolve; });
+  const done = new Promise(resolve => {
+    child.once('error', error => { spawnError = error; closed = true; resolve(); announce(); });
+    child.once('close', () => { closed = true; resolve(); announce(); });
+  });
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', chunk => {
+    const lines = (pending + chunk).split(/\r?\n/);
+    pending = lines.pop();
+    for (const line of lines) {
+      const match = line.match(ALLOCATED);
+      if (match && port === undefined) { port = Number(match[1]); announce(); continue; }
+      errorText = (errorText + line + '\n').slice(-8000);
+      process.stderr.write(line + '\n');
+    }
+  });
+  const stop = async () => {
+    if (closed) return;
+    child.kill('SIGTERM');
+    await Promise.race([done, delay(1000)]);
+    if (!closed) { child.kill('SIGKILL'); await done; }
+  };
+  try {
+    let timer;
+    const expired = new Promise(resolve => { timer = setTimeout(resolve, timeoutMs); });
+    await Promise.race([allocated, expired]);
+    clearTimeout(timer);
+    if (port === undefined) {
+      if (closed) throw new Error('SSH 工具连接失败：' + (spawnError?.message || errorText.trim() || '连接已关闭'));
+      throw new Error('无法获取 SSH 反向隧道端口。请检查服务器是否允许 TCP 转发。');
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('无法获取 SSH 反向隧道端口。请检查服务器是否允许 TCP 转发。');
+    return { controlPath: undefined, port, close: stop };
+  } catch (error) { await stop(); throw error; }
+}
+
+export async function openTunnel(config, localPort, { env = process.env, run = execute, platform = process.platform } = {}) {
+  if (platform === 'win32') return openDirectTunnel(config, localPort, { env });
   // Keep the control socket below the short Unix-domain path limit on macOS.
   const base = os.tmpdir().length > 55 ? '/tmp' : os.tmpdir();
   const directory = await fs.mkdtemp(path.join(base, 'ccr-'));

package/src/local/workspace.js

@@ -2,9 +2,14 @@ import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { execFile } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
+import { rename } from '../system.js';
 
 const hash = text => createHash('sha256').update(text).digest('hex');
-const inside = (root, target) => target === root || target.startsWith(root + path.sep);
+// Windows paths are case-insensitive: C:\Project and c:\project are the same folder.
+const fold = process.platform === 'win32' ? value => value.toLowerCase() : value => value;
+const inside = (root, target) => fold(target) === fold(root) || fold(target).startsWith(fold(root) + path.sep);
+// Lines are shown without a trailing \r, so CRLF files read like LF files.
+const stripCR = line => line.endsWith('\r') ? line.slice(0, -1) : line;
 
 // Keep read_file results below the MCP response limit (JSON escaping adds overhead).
 const READ_BUDGET = 28000;
@@ -77,7 +82,7 @@ export class Workspace {
     const output = [];
     let used = 0, sizeLimited = false;
     for (let i = offset - 1; i < Math.min(total, offset - 1 + limit); i++) {
-      const line = `${i + 1}: ${lines[i]}`;
+      const line = `${i + 1}: ${stripCR(lines[i])}`;
       if (used + line.length > READ_BUDGET) {
         sizeLimited = true;
         if (!output.length) output.push(line.slice(0, READ_BUDGET) + ` …[本行过长已截断，共 ${lines[i].length} 字符，请用终端查看]`);
@@ -89,6 +94,7 @@ export class Workspace {
     const next = offset + output.length;
     return { path: path.relative(this.root, target), sha256: hash(content), total_lines: total,
       content: output.join('\n'),
+      ...(content.includes('\r\n') ? { line_endings: 'crlf' } : {}),
       ...(next <= total ? { next_offset: next } : {}),
       ...(sizeLimited ? { truncated_by_size: true } : {}) };
   }
@@ -98,7 +104,7 @@ export class Workspace {
     const temp = path.join(path.dirname(target), '.claude-write-' + randomUUID());
     try {
       await fs.writeFile(temp, content, { flag: 'wx', mode });
-      await fs.rename(temp, target);
+      await rename(temp, target);
     } finally { await fs.rm(temp, { force: true }); }
     return { path: path.relative(this.root, target), sha256: hash(content), bytes: Buffer.byteLength(content) };
   }
@@ -121,6 +127,11 @@ export class Workspace {
     const stat = await fs.stat(target);
     if (stat.size > 2 * 1024 * 1024) throw new Error('编辑文件大小上限为 2 MiB。');
     const content = await fs.readFile(target, 'utf8');
+    // read_file hides \r, so text copied from it uses \n; match CRLF files too.
+    if (!content.includes(oldText) && content.includes('\r\n') && !oldText.includes('\r')) {
+      oldText = oldText.replaceAll('\n', '\r\n');
+      newText = newText.replaceAll('\r\n', '\n').replaceAll('\n', '\r\n');
+    }
     const matches = content.split(oldText).length - 1;
     if (!matches) throw new Error('找不到 old_text，请重新读取文件。');
     if (matches > 1 && !replaceAll) throw new Error('old_text 出现多次，请提供更精确的上下文或使用 replace_all。');
@@ -192,7 +203,7 @@ export class Workspace {
         if (text.includes('\0')) return null;
         const found = [];
         for (const [i, line] of text.split('\n').entries())
-          if (test(line)) found.push({ path: path.relative(this.root, target), line: i + 1, text: line.slice(0, 1000) });
+          if (test(stripCR(line))) found.push({ path: path.relative(this.root, target), line: i + 1, text: stripCR(line).slice(0, 1000) });
         return found;
       } catch (error) {
         if (error.code !== 'ENOENT') errors++; // Deleted tracked files are not errors.

package/src/local-mode.js

@@ -87,7 +87,7 @@ export async function projectInstructions(root) {
   return sections.join('\n\n');
 }
 
-export function localPrompt(root, { instructions = '', appended = [] } = {}) {
+export function localPrompt(root, { instructions = '', appended = [], platform = 'posix' } = {}) {
   const parts = [`All project operations run on the developer's LOCAL computer through the local MCP server. ` +
     `The LOCAL project root is ${JSON.stringify(root)}. The server working directory is only for session metadata, not project files. ` +
     'Call workspace_info before working. Use only local tools for file access, shell commands and browser operations. ' +
@@ -96,7 +96,8 @@ export function localPrompt(root, { instructions = '', appended = [] } = {}) {
     'Never send local development URLs to server-side WebFetch. If WebSearch or WebFetch is unavailable or fails for ordinary public research, report it and ask before using the local browser as a fallback. ' +
     'Project instructions from the LOCAL CLAUDE.md files are included below when present; also read CLAUDE.md files in LOCAL subdirectories with read_file when working there. ' +
     'Use background commands for development servers, inspect their logs, and stop owned processes when finished. ' +
-    'If the local connection fails, report it and stop local project operations; never fall back to server filesystem, shell or browser tools.'];
+    'If the local connection fails, report it and stop local project operations; never fall back to server filesystem, shell or browser tools.' +
+    (platform === 'win32' ? ' The LOCAL computer runs Windows while the server runs Linux: use Windows paths for local tools and check workspace_info for the shell used by run_command.' : '')];
   if (instructions) parts.push('# Project instructions (LOCAL)\n\n' + instructions);
   if (appended.length) parts.push('# Additional instructions from the user\n\n' + appended.join('\n\n'));
   return parts.join('\n\n');
@@ -125,7 +126,8 @@ export async function launchLocal(client, config, extra, dependencies = {}) {
   if (!await which('ssh', client.env.PATH)) throw new Error('找不到系统 SSH 客户端。');
   const root = await fs.realpath(client.cwd), home = await fs.realpath(client.home);
   if (root === home || root === path.parse(root).root) throw new Error('请进入具体项目目录，不允许以用户目录或磁盘根目录作为项目。');
-  const prompt = localPrompt(root, { instructions: await projectInstructions(root), appended: extractAppendedPrompts(extra).prompts });
+  const prompt = localPrompt(root, { instructions: await projectInstructions(root), appended: extractAppendedPrompts(extra).prompts,
+    platform: client.platform });
   // Prepare the browser while SSH connects; it is only needed before Claude starts.
   const browserReady = (dependencies.installBrowser || installBrowser)(client.log, { debug: client.debug });
   browserReady.catch(() => {}); // Reported when awaited below.
@@ -169,7 +171,10 @@ export async function launchLocal(client, config, extra, dependencies = {}) {
     const script = remoteEnvironment + 'cd -- ' + remotePath(remoteDirectory) + ' || exit 1; ' +
       'trap ' + quote('rm -f -- ' + remotePath(configFile) + ' ' + remotePath(promptFile)) + ' EXIT; ' +
       shellJoin([config.claude, ...args]);
-    return (await remote(script, { interactive: true, check: false })).code;
+    const code = (await remote(script, { interactive: true, check: false })).code;
+    // A dropped connection leaves the remote UI's terminal modes switched on.
+    if (code !== 0) client.restoreTerminal();
+    return code;
   } finally {
     removeCleanup();
     await cleanup();

package/src/ssh-auth.js

@@ -33,19 +33,28 @@ export async function ensureSSH(client, config, { enablePubkey = false } = {}) {
   if (!await which('ssh-keygen', client.env.PATH)) throw new Error('找不到 ssh-keygen，请安装 OpenSSH 客户端。');
 
   const directory = path.join(client.home, '.ssh', 'claude-remote');
+  // Windows OpenSSH cannot share one login through a control socket, so each
+  // step there opens its own connection and may ask for the password again.
+  const multiplex = (client.platform ?? process.platform) !== 'win32';
   await withLock(path.join(directory, 'setup'), async () => {
     if (await probe()) return;
-    const base = os.tmpdir().length > 55 ? '/tmp' : os.tmpdir();
-    const temporary = await fs.mkdtemp(path.join(base, 'ccra-'));
-    const socket = path.join(temporary, 'ssh');
+    let temporary, socket;
+    const login = args => multiplex ? ['-S', socket, ...args] : args;
+    // Without multiplexing, prompts belong to these commands: keep them visible and allow time to answer.
+    const prompted = multiplex ? {} : { prompt: true, timeout: 180000 };
     try {
-      client.log('请按提示完成 SSH 验证。');
-      // Authenticate once; subsequent installation reuses this private socket.
-      // Do not capture authentication output or handle passwords in JavaScript.
-      await run(['-M', '-S', socket, '-o', 'ControlPersist=no', '-o', 'ControlMaster=yes',
-        '-f', '-N', config.host], { timeout: 180000, capture: false });
-      const inspect = await run(['-S', socket, config.host, 'sh -c ' + quote(sshPolicyScript({ enable: enablePubkey }))],
-        { capture: true });
+      if (multiplex) {
+        const base = os.tmpdir().length > 55 ? '/tmp' : os.tmpdir();
+        temporary = await fs.mkdtemp(path.join(base, 'ccra-'));
+        socket = path.join(temporary, 'ssh');
+        client.log('请按提示完成 SSH 验证。');
+        // Authenticate once; subsequent installation reuses this private socket.
+        // Do not capture authentication output or handle passwords in JavaScript.
+        await run(['-M', '-S', socket, '-o', 'ControlPersist=no', '-o', 'ControlMaster=yes',
+          '-f', '-N', config.host], { timeout: 180000, capture: false });
+      } else client.log('请按提示完成 SSH 验证。Windows 的 OpenSSH 不支持连接复用，可能需要输入两次密码。');
+      const inspect = await run(login([config.host, 'sh -c ' + quote(sshPolicyScript({ enable: enablePubkey }))]),
+        { capture: true, ...prompted });
       const policy = parseSSHPolicy(inspect.stdout);
       if (policy.backup) client.log('已开启公钥登录。配置备份：' + policy.backup);
       if (policy.pubkeyauthentication === 'no')
@@ -76,7 +85,7 @@ export async function ensureSSH(client, config, { enablePubkey = false } = {}) {
         { env: client.env, capture: true, timeout: 30000 });
       const publicKey = derived.stdout.trim();
       const script = authorizeKeyScript(publicKey);
-      await run(['-S', socket, config.host, 'sh -c ' + quote(script)], { capture: false });
+      await run(login([config.host, 'sh -c ' + quote(script)]), { capture: false, ...(multiplex ? {} : { timeout: 180000 }) });
       if (!await probe(['-i', key, '-o', 'IdentitiesOnly=yes', '-o', 'IdentityAgent=none']))
         throw new Error('公钥已添加，但独立密钥登录验证失败。请检查服务器的公钥登录策略和 authorized_keys 设置；未修改本机 SSH 配置。');
 
@@ -84,7 +93,9 @@ export async function ensureSSH(client, config, { enablePubkey = false } = {}) {
       // IdentityFile is additive; do not replace existing host/user/proxy rules.
       const configFile = path.join(client.home, '.ssh', 'config');
       const host = config.host.split('@').at(-1);
-      const escaped = key.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+      // Forward slashes avoid backslash escaping differences between OpenSSH versions on Windows.
+      const file = (client.platform ?? process.platform) === 'win32' ? key.replaceAll('\\', '/') : key;
+      const escaped = file.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"');
       const block = `\n# claude-remote-cli ${id}\nHost ${host}\n  IdentityFile "${escaped}"\nHost *\n`;
       const previous = await fs.readFile(configFile, 'utf8').catch(error => {
         if (error.code === 'ENOENT') return ''; throw error;
@@ -93,8 +104,10 @@ export async function ensureSSH(client, config, { enablePubkey = false } = {}) {
       if (!await probe()) throw new Error('密钥已授权，但默认 SSH 配置验证失败。请检查 ~/.ssh/config 的 IdentityFile 和 IdentitiesOnly 设置。');
       client.debug('SSH 免密登录已配置并验证成功。');
     } finally {
-      await run(['-S', socket, '-O', 'exit', config.host], { capture: true, check: false, timeout: 5000 }).catch(() => {});
-      await fs.rm(temporary, { recursive: true, force: true });
+      if (multiplex) {
+        if (socket) await run(['-S', socket, '-O', 'exit', config.host], { capture: true, check: false, timeout: 5000 }).catch(() => {});
+        if (temporary) await fs.rm(temporary, { recursive: true, force: true });
+      }
     }
   });
 }

package/src/system.js

@@ -14,17 +14,36 @@ export async function exists(file) {
   catch (error) { if (error.code === 'ENOENT') return false; throw error; }
 }
 
-export async function which(name, search = process.env.PATH || '') {
-  for (const directory of search.split(path.delimiter)) {
-    const file = path.resolve(directory || '.', name);
-    try {
-      await fs.access(file, constants.X_OK);
-      if ((await fs.stat(file)).isFile()) return file;
-    } catch (error) { if (!['ENOENT', 'EACCES', 'ENOTDIR'].includes(error.code)) throw error; }
+// On Windows, try the same extensions as spawn() does (.com, .exe); there is no
+// execute permission bit, so existence is the check.
+export async function which(name, search = process.env.PATH || '', { platform = process.platform } = {}) {
+  const windows = platform === 'win32';
+  const names = windows && !path.extname(name) ? [name + '.com', name + '.exe'] : [name];
+  for (const entry of search.split(windows ? ';' : path.delimiter)) {
+    const directory = windows ? entry.replace(/^"(.*)"$/, '$1') : entry;
+    for (const candidate of names) {
+      const file = path.resolve(directory || '.', candidate);
+      try {
+        await fs.access(file, windows ? constants.F_OK : constants.X_OK);
+        if ((await fs.stat(file)).isFile()) return file;
+      } catch (error) { if (!['ENOENT', 'EACCES', 'ENOTDIR', 'EINVAL'].includes(error.code)) throw error; }
+    }
   }
   return null;
 }
 
+// Windows refuses to replace a file another process (editor, antivirus,
+// indexer) briefly holds open; retry a few times before giving up.
+export async function rename(from, to, { platform = process.platform, attempts = 10 } = {}) {
+  for (let attempt = 1; ; attempt++) {
+    try { return await fs.rename(from, to); }
+    catch (error) {
+      if (platform !== 'win32' || attempt >= attempts || !['EPERM', 'EACCES', 'EBUSY'].includes(error.code)) throw error;
+      await new Promise(resolve => setTimeout(resolve, 20 * attempt));
+    }
+  }
+}
+
 export async function readJSON(file, fallback) {
   try { return JSON.parse(await fs.readFile(file, 'utf8')); }
   catch (error) { if (error.code === 'ENOENT') return fallback; throw error; }
@@ -35,7 +54,7 @@ export async function writeJSON(file, value) {
   const temp = file + '.' + randomUUID() + '.tmp';
   try {
     await fs.writeFile(temp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
-    await fs.rename(temp, file);
+    await rename(temp, file);
   } finally { await fs.rm(temp, { force: true }); }
 }
 
@@ -57,7 +76,7 @@ export function onCleanup(callback) {
   return () => cleanups.delete(callback);
 }
 
-export function terminate(signal, { exit = code => process.exit(code), graceMs = 10000 } = {}) {
+export function terminate(signal, { exit = code => process.exit(code), graceMs = 10000, terminal = process.stdout } = {}) {
   if (terminating) return terminating;
   const code = 128 + (os.constants.signals[signal] || 15);
   terminating = (async () => {
@@ -71,25 +90,52 @@ export function terminate(signal, { exit = code => process.exit(code), graceMs =
     for (const child of trackedChildren) {
       try { child.kill('SIGTERM'); } catch { /* already gone */ }
     }
+    restoreTerminal(terminal);
     exit(code);
   })();
   return terminating;
 }
 
+// A remote full-screen program that loses its connection cannot switch off the
+// terminal modes it enabled, so mouse moves, focus changes and keys show up as
+// stray escape codes. Every sequence here only turns a mode off and is a no-op
+// when the mode is already off. The alternate screen (?1049l) is deliberately
+// left alone: leaving it when not active can move the cursor on some terminals.
+export const TERMINAL_RESET = [
+  '\x1b[?1000l', '\x1b[?1002l', '\x1b[?1003l', '\x1b[?1005l', '\x1b[?1006l', '\x1b[?1015l', // mouse reporting
+  '\x1b[?1004l', // focus in/out events
+  '\x1b[?2004l', // bracketed paste
+  '\x1b[=0;1u', '\x1b[<99u', // kitty keyboard protocol: clear flags, pop pushed levels
+  '\x1b[>4m', // xterm modifyOtherKeys
+  '\x1b[?1l', '\x1b>', // normal cursor keys and keypad
+  '\x1b[0m', '\x1b[?25h' // plain text attributes, visible cursor
+].join('');
+
+export function restoreTerminal(stream = process.stdout) {
+  if (!stream?.isTTY) return false;
+  try { stream.write(TERMINAL_RESET); return true; }
+  catch { return false; } // The terminal may already be gone (SIGHUP).
+}
+
 export function installSignalHandlers() {
   for (const signal of ['SIGHUP', 'SIGTERM']) process.on(signal, () => { terminate(signal); });
 }
 
-export function execute(command, args = [], { capture = false, timeout = 0, check = true, env = process.env, input } = {}) {
+// `prompt` captures stdout but leaves stdin and stderr on the terminal, so a
+// password or host-key prompt from ssh stays visible and answerable.
+export function execute(command, args = [], { capture = false, timeout = 0, check = true, env = process.env, input, prompt = false } = {}) {
   return new Promise((resolve, reject) => {
-    const child = trackChild(spawn(command, args, { stdio: [input !== undefined ? 'pipe' : capture ? 'ignore' : 'inherit',
-      capture ? 'pipe' : 'inherit', capture ? 'pipe' : 'inherit'], env }));
+    const stdio = prompt ? ['inherit', 'pipe', 'inherit'] : [input !== undefined ? 'pipe' : capture ? 'ignore' : 'inherit',
+      capture ? 'pipe' : 'inherit', capture ? 'pipe' : 'inherit'];
+    const child = trackChild(spawn(command, args, { stdio, env }));
     if (input !== undefined) {
       child.stdin.on('error', () => {}); // An early remote failure is reported by the exit status.
       child.stdin.end(input);
     }
     let stdout = '', stderr = '', timedOut = false, overflow = false, killTimer;
-    const interrupt = () => child.kill('SIGINT');
+    // The Windows console already delivers Ctrl+C to the child, and kill()
+    // there would terminate it outright instead of interrupting it.
+    const interrupt = () => { if (process.platform !== 'win32') child.kill('SIGINT'); };
     process.on('SIGINT', interrupt);
     const timer = timeout ? setTimeout(() => {
       timedOut = true;
@@ -100,12 +146,15 @@ export function execute(command, args = [], { capture = false, timeout = 0, chec
       clearTimeout(timer); clearTimeout(killTimer);
       process.off('SIGINT', interrupt);
     };
-    if (capture) {
-      child.stdout.setEncoding('utf8'); child.stderr.setEncoding('utf8');
+    if (child.stdout) {
+      child.stdout.setEncoding('utf8');
       child.stdout.on('data', chunk => {
         stdout += chunk;
         if (stdout.length > 32 * 1024 * 1024) { overflow = true; child.kill('SIGKILL'); }
       });
+    }
+    if (child.stderr) {
+      child.stderr.setEncoding('utf8');
       child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-65536); });
     }
     child.once('error', error => { cleanup(); reject(new Error(`无法执行 ${command}：${error.message}`)); });