@znmin/claude-remote-cli 0.3.1 → 0.4.0

package/src/client.js

@@ -1,232 +1,232 @@
-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, 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';
-import { ensureSSH } from './ssh-auth.js';
-export { sshArgs } from './ssh.js';
-
-export const DEFAULTS = {
-  root: '.local/share/claude-remote/projects', claude: 'claude',
-  ignores: ['.DS_Store', 'node_modules', '.venv', '__pycache__']
-};
-
-export function validate(config) {
-  if (config.mode != null && !['local', 'remote'].includes(config.mode)) throw new Error('模式只能是 local 或 remote。');
-  if (config.browserHeadless != null && typeof config.browserHeadless !== 'boolean') throw new Error('browserHeadless 必须是布尔值。');
-  if (!/^(?:[A-Za-z0-9_][A-Za-z0-9_.-]*@)?[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(config.host || ''))
-    throw new Error('服务器请填写 SSH 别名或 user@host，不要包含端口、空格或 SSH 参数。IPv6 请使用 SSH 别名。');
-  if (config.port != null && (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535))
-    throw new Error('端口必须在 1–65535 之间。');
-  if (typeof config.root !== 'string' || !/^\/?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(config.root) ||
-      config.root.split('/').some(part => ['.', '..'].includes(part)))
-    throw new Error('远程根目录仅支持字母、数字、点、短横线、下划线和斜杠，不支持 ..。');
-  if (typeof config.claude !== 'string' || !config.claude || /[\r\n\0]/.test(config.claude) || config.claude.startsWith('-'))
-    throw new Error('远程 Claude 程序路径无效。');
-  if (!Array.isArray(config.ignores) || config.ignores.some(pattern => typeof pattern !== 'string' || !pattern))
-    throw new Error('忽略规则需要是非空字符串列表。');
-  if (config.client_id != null && (typeof config.client_id !== 'string' || !config.client_id))
-    throw new Error('配置文件中的 client_id 无效。');
-  return config;
-}
-
-export const remotePath = file => file.startsWith('/') ? quote(file) : '"$HOME"/' + quote(file);
-
-export function assertSynchronized(current) {
-  if (!current) throw new Error('同步会话不存在。');
-  if (current.conflicts?.length || current.excludedConflicts)
-    throw new Error('发现双向修改冲突，未自动覆盖。运行 claude-remote status 查看路径，备份后将两边文件统一，再运行 claude-remote flush。');
-  for (const side of ['alpha', 'beta']) {
-    const state = current[side] || {};
-    if (state.scanProblems?.length || state.transitionProblems?.length || state.excludedScanProblems || state.excludedTransitionProblems)
-      throw new Error('同步端点有文件处理错误，请运行 claude-remote status 查看详情。');
-    if (state.connected === false) throw new Error('同步端点已断开，请检查连接后重试。');
-  }
-  if (current.lastError) throw new Error('同步尚有错误：' + current.lastError);
-  if (current.paused) throw new Error('同步会话已暂停，请重新运行 claude 恢复。');
-}
-
-export class Client {
-  constructor(options = {}) {
-    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');
-    this.lockFile = path.join(this.directory, 'npm-state');
-    this.execute = options.execute || execute;
-    this.ensureSSH = options.ensureSSH || ensureSSH;
-    this.ensureMutagen = options.ensureMutagen || ensureMutagen;
-    this.log = options.log || console.error;
-    this.warn = options.warn || console.error;
-    this.debug = (...messages) => {
-      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) {
-    return withLock(this.lockFile, async () => {
-      const old = await readJSON(this.configFile, {});
-      const config = validate({ ...DEFAULTS, ...input,
-        mode: input.mode ?? old.mode ?? 'local', browserHeadless: input.browserHeadless ?? old.browserHeadless ?? false,
-        ignores: [...DEFAULTS.ignores, ...(input.ignores || [])],
-        client_id: old.client_id || randomUUID().replaceAll('-', '').slice(0, 12) });
-      await writeJSON(this.configFile, config);
-      this.log(`已保存：${config.host}（${config.mode === 'local' ? '本地执行' : '远程同步'}）。`);
-      this.debug(`配置文件：${this.configFile}`);
-      if (old.host && (old.host !== config.host || (old.mode || 'remote') !== config.mode))
-        this.log('停止旧同步：claude-remote stop --all');
-      return config;
-    });
-  }
-
-  async settings() {
-    return withLock(this.lockFile, async () => {
-      const stored = await readJSON(this.configFile, {});
-      const config = { ...DEFAULTS, ...stored };
-      if (this.env.CLAUDE_REMOTE_HOST) config.host = this.env.CLAUDE_REMOTE_HOST;
-      if (this.env.CLAUDE_REMOTE_PORT !== undefined) config.port = Number(this.env.CLAUDE_REMOTE_PORT);
-      config.mode = this.env.CLAUDE_REMOTE_MODE || config.mode || 'remote';
-      if (!config.host) throw new Error('尚未配置服务器。请运行：claude-remote configure 用户名@服务器（自定义端口加 --port 2222）。');
-      validate(config);
-      if (!config.client_id) {
-        config.client_id = randomUUID().replaceAll('-', '').slice(0, 12);
-        // Temporary environment overrides must not change the saved server.
-        await writeJSON(this.configFile, { ...stored, client_id: config.client_id });
-      }
-      return config;
-    });
-  }
-
-  async project(config) {
-    const local = await fs.realpath(this.cwd);
-    const home = await fs.realpath(this.home);
-    if (local === home || local === path.parse(local).root)
-      throw new Error('请进入具体项目目录；不允许同步整个用户目录或磁盘根目录。');
-    const git = path.join(local, '.git');
-    if (await exists(git) && (await fs.stat(git)).isFile())
-      throw new Error('当前目录的 .git 指向外部仓库，暂不支持 Git worktree/子模块；请使用普通独立仓库。');
-    // Keep the original Python implementation's stable project identifiers.
-    const identity = '[' + [config.client_id, config.host, config.port ?? null, config.root, local]
-      .map(value => JSON.stringify(value)).join(', ') + ']';
-    const key = createHash('sha256').update(identity).digest('hex').slice(0, 24);
-    return { name: 'claude-remote-' + key, local, remote: config.root + '/' + key,
-      host: config.host, port: config.port ?? null };
-  }
-
-  async setMode(mode) {
-    if (!['local', 'remote'].includes(mode)) throw new Error('模式只能是 local 或 remote。');
-    await withLock(this.lockFile, async () => {
-      const stored = await readJSON(this.configFile, {});
-      await writeJSON(this.configFile, { ...stored, mode });
-    });
-    this.log(`默认模式已设为 ${mode}。旧后台同步不会自动停止；如需停止请运行 claude-remote stop --all。`);
-  }
-
-  async prepare() {
-    if (!this.mutagen) this.mutagen = await this.ensureMutagen({ env: this.env });
-    return this.mutagen;
-  }
-
-  async sync(args, options = {}) {
-    const binary = await this.prepare();
-    return this.execute(binary, ['sync', ...args], { env: this.env, capture: true, ...options });
-  }
-
-  async sessions() {
-    const result = await this.sync(['list', '--label-selector', 'claude-remote=true', '--template', '{{json .}}'],
-      { capture: true, timeout: 30000 });
-    return JSON.parse(result.stdout) || [];
-  }
-
-  async flush(name) {
-    await this.sync(['flush', name], { timeout: 120000 });
-    assertSynchronized((await this.sessions()).find(session => session.name === name));
-  }
-
-  async remote(config, script, interactive = false, { timeout = 180000 } = {}) {
-    return this.execute('ssh', sshArgs(config, script, { interactive, tty: interactive && this.tty }),
-      { env: this.env, timeout: interactive ? 0 : timeout, check: !interactive });
-  }
-
-  async launch(config, extra) {
-    this.debug(`连接：${config.host}${config.port ? ':' + config.port : ''}，模式：${config.mode || 'remote'}`);
-    await this.ensureSSH(this, config);
-    if (config.mode === 'local') {
-      const { launchLocal } = await import('./local-mode.js');
-      return launchLocal(this, config, extra);
-    }
-    for (const tool of ['ssh', 'scp']) if (!await which(tool, this.env.PATH))
-      throw new Error(`找不到系统 ${tool}，请安装 OpenSSH 客户端。`);
-    const item = await this.project(config);
-    await this.prepare();
-    await withLock(this.lockFile, async () => {
-      const existing = await this.sessions();
-      const registry = await readJSON(this.registryFile, {});
-      for (const session of existing) {
-        if (session.name === item.name) continue;
-        const storedPath = session.alpha?.path || registry[session.name]?.local;
-        if (!storedPath) continue;
-        let other;
-        try { other = await fs.realpath(storedPath); }
-        catch (error) { if (error.code !== 'ENOENT') throw error; other = path.resolve(storedPath); }
-        const relative = path.relative(other, item.local);
-        const reverse = path.relative(item.local, other);
-        const inside = value => value === '' || (!value.startsWith('..' + path.sep) && value !== '..' && !path.isAbsolute(value));
-        if (inside(relative) || inside(reverse))
-          throw new Error(`目录与正在同步的项目重叠：${other}\n先运行：claude-remote stop --name ${session.name}`);
-      }
-      await this.remote(config, ensureRemoteClaude(config.claude) +
-        'mkdir -p -- ' + remotePath(item.remote), false, { timeout: 600000 });
-      if (existing.some(session => session.name === item.name)) {
-        await this.sync(['resume', item.name], { timeout: 60000, capture: this.env.CLAUDE_REMOTE_DEBUG !== '1' || !this.tty });
-      } else {
-        const endpoint = config.host + ':' + (config.port != null ? config.port + ':' : '') +
-          (item.remote.startsWith('/') ? item.remote : '~/' + item.remote);
-        const args = ['create', '--name', item.name, '--label', 'claude-remote=true', '--mode', 'two-way-safe',
-          '--no-global-configuration', '--no-ignore-vcs', '--watch-polling-interval', '2'];
-        for (const pattern of config.ignores) args.push('--ignore', pattern);
-        await this.sync([...args, item.local, endpoint], { timeout: 180000, capture: this.env.CLAUDE_REMOTE_DEBUG !== '1' || !this.tty });
-      }
-      registry[item.name] = item;
-      await writeJSON(this.registryFile, registry);
-    });
-    this.debug(`本地：${item.local}\n远程：${config.host}:${item.remote}`);
-    this.log('正在同步…');
-    await this.flush(item.name);
-    this.debug('同步完成，启动远程 Claude Code。退出后继续后台同步；停止请运行 claude-remote stop。');
-    let code = 1;
-    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) {
-        this.warn(`退出时同步未确认完成：${error.message}\n会话保留，可用 claude-remote status 检查。`);
-        if (code === 0) code = 1;
-      }
-    }
-    return code;
-  }
-
-  async stop({ all = false, name } = {}) {
-    const selected = all || name ? name : (await this.project(await this.settings())).name;
-    return withLock(this.lockFile, async () => {
-      const available = (await this.sessions()).map(session => session.name);
-      const targets = all ? available : [selected];
-      if (!targets.length || targets.some(target => !available.includes(target)))
-        throw new Error('没有找到对应同步会话；运行 claude-remote status 查看。');
-      await this.sync(['terminate', ...targets], { timeout: 30000 });
-      this.log('已停止同步，保留本地和远程文件。');
-    });
-  }
-}
+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, 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';
+import { ensureSSH } from './ssh-auth.js';
+export { sshArgs } from './ssh.js';
+
+export const DEFAULTS = {
+  root: '.local/share/claude-remote/projects', claude: 'claude',
+  ignores: ['.DS_Store', 'node_modules', '.venv', '__pycache__']
+};
+
+export function validate(config) {
+  if (config.mode != null && !['local', 'remote'].includes(config.mode)) throw new Error('模式只能是 local 或 remote。');
+  if (config.browserHeadless != null && typeof config.browserHeadless !== 'boolean') throw new Error('browserHeadless 必须是布尔值。');
+  if (!/^(?:[A-Za-z0-9_][A-Za-z0-9_.-]*@)?[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(config.host || ''))
+    throw new Error('服务器请填写 SSH 别名或 user@host，不要包含端口、空格或 SSH 参数。IPv6 请使用 SSH 别名。');
+  if (config.port != null && (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535))
+    throw new Error('端口必须在 1–65535 之间。');
+  if (typeof config.root !== 'string' || !/^\/?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(config.root) ||
+      config.root.split('/').some(part => ['.', '..'].includes(part)))
+    throw new Error('远程根目录仅支持字母、数字、点、短横线、下划线和斜杠，不支持 ..。');
+  if (typeof config.claude !== 'string' || !config.claude || /[\r\n\0]/.test(config.claude) || config.claude.startsWith('-'))
+    throw new Error('远程 Claude 程序路径无效。');
+  if (!Array.isArray(config.ignores) || config.ignores.some(pattern => typeof pattern !== 'string' || !pattern))
+    throw new Error('忽略规则需要是非空字符串列表。');
+  if (config.client_id != null && (typeof config.client_id !== 'string' || !config.client_id))
+    throw new Error('配置文件中的 client_id 无效。');
+  return config;
+}
+
+export const remotePath = file => file.startsWith('/') ? quote(file) : '"$HOME"/' + quote(file);
+
+export function assertSynchronized(current) {
+  if (!current) throw new Error('同步会话不存在。');
+  if (current.conflicts?.length || current.excludedConflicts)
+    throw new Error('发现双向修改冲突，未自动覆盖。运行 claude-remote status 查看路径，备份后将两边文件统一，再运行 claude-remote flush。');
+  for (const side of ['alpha', 'beta']) {
+    const state = current[side] || {};
+    if (state.scanProblems?.length || state.transitionProblems?.length || state.excludedScanProblems || state.excludedTransitionProblems)
+      throw new Error('同步端点有文件处理错误，请运行 claude-remote status 查看详情。');
+    if (state.connected === false) throw new Error('同步端点已断开，请检查连接后重试。');
+  }
+  if (current.lastError) throw new Error('同步尚有错误：' + current.lastError);
+  if (current.paused) throw new Error('同步会话已暂停，请重新运行 claude 恢复。');
+}
+
+export class Client {
+  constructor(options = {}) {
+    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');
+    this.lockFile = path.join(this.directory, 'npm-state');
+    this.execute = options.execute || execute;
+    this.ensureSSH = options.ensureSSH || ensureSSH;
+    this.ensureMutagen = options.ensureMutagen || ensureMutagen;
+    this.log = options.log || console.error;
+    this.warn = options.warn || console.error;
+    this.debug = (...messages) => {
+      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) {
+    return withLock(this.lockFile, async () => {
+      const old = await readJSON(this.configFile, {});
+      const config = validate({ ...DEFAULTS, ...input,
+        mode: input.mode ?? old.mode ?? 'local', browserHeadless: input.browserHeadless ?? old.browserHeadless ?? false,
+        ignores: [...DEFAULTS.ignores, ...(input.ignores || [])],
+        client_id: old.client_id || randomUUID().replaceAll('-', '').slice(0, 12) });
+      await writeJSON(this.configFile, config);
+      this.log(`已保存：${config.host}（${config.mode === 'local' ? '本地执行' : '远程同步'}）。`);
+      this.debug(`配置文件：${this.configFile}`);
+      if (old.host && (old.host !== config.host || (old.mode || 'remote') !== config.mode))
+        this.log('停止旧同步：claude-remote stop --all');
+      return config;
+    });
+  }
+
+  async settings() {
+    return withLock(this.lockFile, async () => {
+      const stored = await readJSON(this.configFile, {});
+      const config = { ...DEFAULTS, ...stored };
+      if (this.env.CLAUDE_REMOTE_HOST) config.host = this.env.CLAUDE_REMOTE_HOST;
+      if (this.env.CLAUDE_REMOTE_PORT !== undefined) config.port = Number(this.env.CLAUDE_REMOTE_PORT);
+      config.mode = this.env.CLAUDE_REMOTE_MODE || config.mode || 'remote';
+      if (!config.host) throw new Error('尚未配置服务器。请运行：claude-remote configure 用户名@服务器（自定义端口加 --port 2222）。');
+      validate(config);
+      if (!config.client_id) {
+        config.client_id = randomUUID().replaceAll('-', '').slice(0, 12);
+        // Temporary environment overrides must not change the saved server.
+        await writeJSON(this.configFile, { ...stored, client_id: config.client_id });
+      }
+      return config;
+    });
+  }
+
+  async project(config) {
+    const local = await fs.realpath(this.cwd);
+    const home = await fs.realpath(this.home);
+    if (local === home || local === path.parse(local).root)
+      throw new Error('请进入具体项目目录；不允许同步整个用户目录或磁盘根目录。');
+    const git = path.join(local, '.git');
+    if (await exists(git) && (await fs.stat(git)).isFile())
+      throw new Error('当前目录的 .git 指向外部仓库，暂不支持 Git worktree/子模块；请使用普通独立仓库。');
+    // Keep the original Python implementation's stable project identifiers.
+    const identity = '[' + [config.client_id, config.host, config.port ?? null, config.root, local]
+      .map(value => JSON.stringify(value)).join(', ') + ']';
+    const key = createHash('sha256').update(identity).digest('hex').slice(0, 24);
+    return { name: 'claude-remote-' + key, local, remote: config.root + '/' + key,
+      host: config.host, port: config.port ?? null };
+  }
+
+  async setMode(mode) {
+    if (!['local', 'remote'].includes(mode)) throw new Error('模式只能是 local 或 remote。');
+    await withLock(this.lockFile, async () => {
+      const stored = await readJSON(this.configFile, {});
+      await writeJSON(this.configFile, { ...stored, mode });
+    });
+    this.log(`默认模式已设为 ${mode}。旧后台同步不会自动停止；如需停止请运行 claude-remote stop --all。`);
+  }
+
+  async prepare() {
+    if (!this.mutagen) this.mutagen = await this.ensureMutagen({ env: this.env });
+    return this.mutagen;
+  }
+
+  async sync(args, options = {}) {
+    const binary = await this.prepare();
+    return this.execute(binary, ['sync', ...args], { env: this.env, capture: true, ...options });
+  }
+
+  async sessions() {
+    const result = await this.sync(['list', '--label-selector', 'claude-remote=true', '--template', '{{json .}}'],
+      { capture: true, timeout: 30000 });
+    return JSON.parse(result.stdout) || [];
+  }
+
+  async flush(name) {
+    await this.sync(['flush', name], { timeout: 120000 });
+    assertSynchronized((await this.sessions()).find(session => session.name === name));
+  }
+
+  async remote(config, script, interactive = false, { timeout = 180000 } = {}) {
+    return this.execute('ssh', sshArgs(config, script, { interactive, tty: interactive && this.tty }),
+      { env: this.env, timeout: interactive ? 0 : timeout, check: !interactive });
+  }
+
+  async launch(config, extra) {
+    this.debug(`连接：${config.host}${config.port ? ':' + config.port : ''}，模式：${config.mode || 'remote'}`);
+    await this.ensureSSH(this, config);
+    if (config.mode === 'local') {
+      const { launchLocal } = await import('./local-mode.js');
+      return launchLocal(this, config, extra);
+    }
+    for (const tool of ['ssh', 'scp']) if (!await which(tool, this.env.PATH))
+      throw new Error(`找不到系统 ${tool}，请安装 OpenSSH 客户端。`);
+    const item = await this.project(config);
+    await this.prepare();
+    await withLock(this.lockFile, async () => {
+      const existing = await this.sessions();
+      const registry = await readJSON(this.registryFile, {});
+      for (const session of existing) {
+        if (session.name === item.name) continue;
+        const storedPath = session.alpha?.path || registry[session.name]?.local;
+        if (!storedPath) continue;
+        let other;
+        try { other = await fs.realpath(storedPath); }
+        catch (error) { if (error.code !== 'ENOENT') throw error; other = path.resolve(storedPath); }
+        const relative = path.relative(other, item.local);
+        const reverse = path.relative(item.local, other);
+        const inside = value => value === '' || (!value.startsWith('..' + path.sep) && value !== '..' && !path.isAbsolute(value));
+        if (inside(relative) || inside(reverse))
+          throw new Error(`目录与正在同步的项目重叠：${other}\n先运行：claude-remote stop --name ${session.name}`);
+      }
+      await this.remote(config, ensureRemoteClaude(config.claude) +
+        'mkdir -p -- ' + remotePath(item.remote), false, { timeout: 600000 });
+      if (existing.some(session => session.name === item.name)) {
+        await this.sync(['resume', item.name], { timeout: 60000, capture: this.env.CLAUDE_REMOTE_DEBUG !== '1' || !this.tty });
+      } else {
+        const endpoint = config.host + ':' + (config.port != null ? config.port + ':' : '') +
+          (item.remote.startsWith('/') ? item.remote : '~/' + item.remote);
+        const args = ['create', '--name', item.name, '--label', 'claude-remote=true', '--mode', 'two-way-safe',
+          '--no-global-configuration', '--no-ignore-vcs', '--watch-polling-interval', '2'];
+        for (const pattern of config.ignores) args.push('--ignore', pattern);
+        await this.sync([...args, item.local, endpoint], { timeout: 180000, capture: this.env.CLAUDE_REMOTE_DEBUG !== '1' || !this.tty });
+      }
+      registry[item.name] = item;
+      await writeJSON(this.registryFile, registry);
+    });
+    this.debug(`本地：${item.local}\n远程：${config.host}:${item.remote}`);
+    this.log('正在同步…');
+    await this.flush(item.name);
+    this.debug('同步完成，启动远程 Claude Code。退出后继续后台同步；停止请运行 claude-remote stop。');
+    let code = 1;
+    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) {
+        this.warn(`退出时同步未确认完成：${error.message}\n会话保留，可用 claude-remote status 检查。`);
+        if (code === 0) code = 1;
+      }
+    }
+    return code;
+  }
+
+  async stop({ all = false, name } = {}) {
+    const selected = all || name ? name : (await this.project(await this.settings())).name;
+    return withLock(this.lockFile, async () => {
+      const available = (await this.sessions()).map(session => session.name);
+      const targets = all ? available : [selected];
+      if (!targets.length || targets.some(target => !available.includes(target)))
+        throw new Error('没有找到对应同步会话；运行 claude-remote status 查看。');
+      await this.sync(['terminate', ...targets], { timeout: 30000 });
+      this.log('已停止同步，保留本地和远程文件。');
+    });
+  }
+}