Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

60.9 KB
Raw Blame
/**
 * RemoteHost — one SSH connection to one remote machine.
 *
 * State machine:
 *   disconnected → connecting → authenticating → ready
 *                                                  ↓
 *                          (socket loss / keepalive timeout)
 *                                                  ↓
 *                     reconnecting (exp backoff, capped) → ready | failed
 *
 * Phase A: lifecycle (connect/disconnect/keepalive/reconnect).
 * Phase B: exec / execStream channels for one-shot commands and
 *          streaming spawns (Claude/Codex on remote, bootstrap.sh).
 *
 * NOT YET (Phase C): shell PTY tab, sftp, session ingest.
 */

import { EventEmitter } from 'node:events';
import net from 'node:net';
import { StringDecoder } from 'node:string_decoder';
import { Client, type ConnectConfig, type ClientChannel, type TcpConnectionDetails } from 'ssh2';

import type { HostConfig, HostSnapshot, RemoteStatus } from './types.js';
import { resolveAuth } from './credentials.js';
import { type HostKeyStore, hostKeyFingerprint, hostKeyId, decideHostKey } from './hostKeys.js';

export interface RemoteHostDeps {
  logger: {
    debug(msg: string, ctx?: Record<string, unknown>): void;
    info(msg: string, ctx?: Record<string, unknown>): void;
    warn(msg: string, ctx?: Record<string, unknown>): void;
    error(msg: string, ctx?: Record<string, unknown>): void;
  };
  /**
   * Persisted trusted host-key fingerprints (TOFU). When omitted, connects
   * fail closed — we refuse rather than silently trust an unverified key.
   * ConnectionPool injects one built from its `knownHostsPath`.
   */
  hostKeys?: HostKeyStore;
}

const READY_TIMEOUT_MS = 20_000;
const KEEPALIVE_INTERVAL_MS = 30_000;
const KEEPALIVE_COUNT_MAX = 3;
const MAX_RECONNECT_ATTEMPTS = 5;
const RECONNECT_BASE_DELAY_MS = 1_000;

export type StatusListener = (snapshot: HostSnapshot) => void;

export interface ExecOpts {
  /** stdin payload; channel is `end()`-ed after the write. */
  /** Stdin payload — string for text scripts, Buffer for binary bundles (e.g. cc-manager .mjs upload). */
  input?: string | Buffer;
  /** kill the channel after this many ms. Default 60_000. */
  timeoutMs?: number;
  /** environment vars sent to remote (subject to sshd `AcceptEnv`). */
  env?: Record<string, string>;
  /**
   * Caller-controlled label used in timeout / error messages — the raw
   * `cmd` is deliberately NEVER echoed (cmd may carry secrets via inline
   * env vars or wrapper scripts). Falls back to literal `"exec"`.
   */
  label?: string;
  /**
   * Per-stream byte cap enforced **while reading the channel** — the moment
   * stdout or stderr crosses the cap, buffering stops and the remote command
   * is torn down (TERM + close), resolving with `truncated: true`. Without
   * this, an arbitrary command (`cat` on a multi-GB log, `yes`) accumulates
   * unbounded strings in the Electron main process until timeout. Callers
   * running untrusted / model-authored commands (cindy_ssh MCP) MUST set it.
   * Default: unlimited (legacy behavior for short trusted probes).
   */
  maxOutputBytes?: number;
}

export interface ExecResult {
  stdout: string;
  stderr: string;
  exitCode: number | null;
  signal: string | null;
  /** true when `maxOutputBytes` kicked in — output is partial and the command was torn down early. */
  truncated?: boolean;
}

export interface ExecStreamOpts {
  pty?: boolean;
  env?: Record<string, string>;
  /**
   * 建立阶段超时(ms):exec callback 在 timeoutMs 内未返回则 reject, 并确保
   * 晚到的 channel 被 kill(轮 40-w4-t6 HIGH —— 否则调用方卡死在 setup 且
   * late channel 逃逸成孤儿)。0/undefined = 不设超时(默认, 兼容现有调用)。
   */
  timeoutMs?: number;
}

// ── Remote TCP forwarding (OpenSSH `ssh -R` 等价物) ─────────────────────────
//
// 用途: 让远端进程 (codex daemon / claude CLI) 把 HTTPS_PROXY 指向远端
// 127.0.0.1 上的一个端口, 该端口的连接经**同一条 SSH 连接**的多路复用通道
// 转回本机, 再 pipe 到用户自己的本地 Proxy (如 127.0.0.1:7890)。Cindy 不提供
// Proxy, 只提供这条隧道。
//
// 为什么复用同一条 ssh2 Client 而不起第二条连接: SSH 协议按 channel id 解
// 复用, forwardIn 的 tcp-forward channel 与 exec channel 在同一条连接上互
// 不干扰 —— 消息不会"打乱"。多路复用是 SSH 的原生能力。
//
// 端口策略: 用**固定首选端口**而不是 port 0, 这样断线重连后隧道口不变,
// 远端 daemon env (HTTPS_PROXY=http://127.0.0.1:<port>) 不用跟着重写。
// 首选端口被占用时向后探测少量候选; 真换端口时通过 onRearmed 通知上层
// (上层在下次 session start 时重写远端 env marker 并重启 daemon, 自愈)。

/** 首选远端绑定端口基数; 被占用时向后探测 PORT_SCAN_SPAN 个候选。 */
export const DEFAULT_REMOTE_FORWARD_PORT_BASE = 17893;
const REMOTE_FORWARD_PORT_SCAN_SPAN = 8;

export interface RemoteForwardSpec {
  /** 本机 (运行 Cindy 的机器) 转发目标 — 用户本地 Proxy 的监听地址。 */
  localHost: string;
  localPort: number;
  /** 远端 127.0.0.1 首选绑定端口; 缺省 DEFAULT_REMOTE_FORWARD_PORT_BASE。 */
  preferredRemotePort?: number;
  /**
   * true = 只绑 preferredRemotePort, 被占时**不**向后顺延探测 — 用于
   * 「远端 env 写死固定端口」的隧道 (agent-proxy 固定端口模式): 端口漂移
   * 意味着远端 daemon env 失效 + 必须重启 daemon, 比「暂时绑不上等重试」
   * 代价大得多。被占时 armForward 抛错, 由调用方决定重试/清理残留监听。
   */
  exactRemotePort?: boolean;
  /** 断线重连后端口被重绑到不同值时回调一次 (首次绑定不回调)。 */
  onRearmed?: (remotePort: number) => void;
}

export interface RemoteForward {
  /** 当前实际绑定的远端端口 (重连后可能变化)。 */
  readonly remotePort: number;
  /** 停止转发并释放登记。幂等。 */
  close(): Promise<void>;
}

interface ForwardRecord {
  spec: RemoteForwardSpec;
  remotePort: number;
  /** forwardIn 已在当前 live client 上注册成功。 */
  armed: boolean;
  /** 进行中的 arm, 去重 ensureRemoteForward 与 rearmForwards 的并发竞争。 */
  arming?: Promise<void>;
  /**
   * 轮 42 P1(codex-connector):句柄引用计数。同一 (localHost, localPort) 的
   * forward 可能被多个会话共用(同 host 多 Pi 会话共享同一 in-process MCP
   * bridge 端口), 任一方 dispose 不能拆掉别人还在用的隧道 —— 全部句柄释放
   * (refCount 归 0)才真正 unforward。closeRemoteForward / closeAllRemoteForwards
   * 是强制路径(pref 关闭 / 陈旧清理), 清零后直接拆。
   */
  refCount: number;
  /** 本地 Proxy 连接失败的节流日志状态。 */
  lastLocalErrorAt: number;
  localErrorCount: number;
  /** 上次实际打日志时的 localErrorCount — suppressedCount 报「距上次日志被吞掉
   *  几条」而不是单调总计数 (review: PR #715 copilot R3)。 */
  lastLocalErrorLoggedCount: number;
}

/**
 * arm 在飞期间连接被换 (断线/重连), forwardIn 的迟到成功落在旧 client 上。
 * armForward 以此错误收尾; ensureRemoteForward / rearmForwards 识别后立即
 * 在当前连接重试一次, 而不是把隧道误标 active 或等下次 reconnect。
 */
class StaleForwardArmError extends Error {}

function forwardKey(spec: Pick<RemoteForwardSpec, 'localHost' | 'localPort'>): string {
  return `${spec.localHost}:${spec.localPort}`;
}

export interface ExecStreamHandle {
  /** 轮 23-H4 HIGH:返回 boolean —— false = ssh2 内部缓冲满(背压信号),
   *  调用方须等待 'drain' 后再写, 避免无界积压。 */
  write(data: string | Buffer): boolean;
  end(data?: string | Buffer): void;
  /** UTF-8 解码后的文本流; 二进制 transport (codex app-server proxy 的 WS frame)
   *  必须改用 `onStdoutBytes`, 否则 toString 会破坏字节。 */
  onStdout(cb: (chunk: string) => void): () => void;
  /** 原始字节流; 用于在 ssh channel 上跑二进制协议 (e.g. WebSocket frames). */
  onStdoutBytes(cb: (chunk: Buffer) => void): () => void;
  onStderr(cb: (chunk: string) => void): () => void;
  /** 轮 23-H4 HIGH:ssh2 channel 缓冲 drain(背压恢复信号)。 */
  onDrain(cb: () => void): () => void;
  onClose(cb: (info: { code: number | null; signal: string | null }) => void): () => void;
  onError(cb: (err: Error) => void): () => void;
  /** 暂停 / 恢复读取 stdout(背压:下游消费不过来时停读,ssh2 随之停止扩窗,远端暂停发送)。 */
  pause?(): void;
  resume?(): void;
  /**
   * Try to terminate the remote process. ssh2's `channel.signal()` is
   * subject to OpenSSH server config (`AcceptEnv` / `PermitSignal`); many
   * servers reject it silently. As a fallback we also close the channel,
   * which sends SIGHUP via SSH session teardown.
   */
  kill(signal?: string): void;
}

/**
 * Heuristic — does this ssh2 error message indicate an auth failure
 * (as opposed to network / DNS / handshake)? Auth failures are
 * deterministic: retrying with the same credentials will produce the same
 * outcome, so we use this to short-circuit the auto-reconnect loop AND
 * to swap in an actionable "fix your auth" message in place of the
 * opaque "All configured authentication methods failed".
 *
 * Match list comes from ssh2 source + observed messages from common
 * sshd implementations. False positives here just suppress retries
 * (acceptable); false negatives let the loop spin (already capped at 5).
 */
export function isAuthFailure(msg: string): boolean {
  const lower = msg.toLowerCase();
  return (
    lower.includes('all configured authentication') ||
    lower.includes('authentication failed') ||
    lower.includes('auth failed') ||
    lower.includes('permission denied') ||
    lower.includes('no matching authentication') ||
    // authFailureHint() 的改写产物也必须被识别:connect() 失败时 lastError /
    // reject message 已被换成友好文案,后续判定(reconnect 跳过、IPC 分类、
    // cindy_ssh 错误码)都跑在改写后的字符串上。不识别会把确定性的认证失败
    // 降级成"可重试的连接失败"。与 authFailureHint 的三种文案一一对应,
    // 改 hint 措辞时必须同步这里(有 invariant 单测拦截)。
    lower.includes('has no key the remote accepts') ||
    lower.includes('was rejected by the remote')
  );
}

/**
 * Build a one-line user-facing message for an auth failure. Subtitle in
 * the host row + toast both show this verbatim — keep it under ~120 chars
 * so it doesn't ellipsize. CLI command text stays English (shell commands
 * are English) but a future improvement could split this into structured
 * fields for full i18n.
 */
export function authFailureHint(cfg: HostConfig): string {
  const portArg = cfg.port && cfg.port !== 22 ? `-p ${cfg.port} ` : '';
  if (cfg.authMethod === 'agent') {
    const pinned = !!cfg.identityFile
      || (cfg.sshAuthentication?.allowedAgentFingerprints?.length ?? 0) > 0;
    if (pinned) {
      return 'SSH agent has no key the remote accepts from the configured identity set. '
        + 'Load the matching private key with `ssh-add`, then try again.';
    }
    return `SSH agent has no key the remote accepts. Run \`ssh-copy-id ${portArg}${cfg.user}@${cfg.hostname}\` from your terminal to install your pubkey, or re-add this host with "Identity file" auth.`;
  }
  if (cfg.authMethod === 'key') {
    return `The configured identity file was rejected by the remote. Verify it is the right key for ${cfg.user}@${cfg.hostname}, or run \`ssh-copy-id ${portArg}-i <public-key-file> ${cfg.user}@${cfg.hostname}\` with its matching public key.`;
  }
  return `Authentication failed connecting as ${cfg.user}@${cfg.hostname}.`;
}

function wrapChannel(channel: ClientChannel): ExecStreamHandle {
  const stdoutListeners = new Set<(s: string) => void>();
  const stdoutBytesListeners = new Set<(b: Buffer) => void>();
  const stderrListeners = new Set<(s: string) => void>();
  const drainListeners = new Set<() => void>();
  const closeListeners = new Set<(i: { code: number | null; signal: string | null }) => void>();
  const errorListeners = new Set<(e: Error) => void>();
  // 轮 40-w4-t9 HIGH:文本流按 chunk toString('utf8') 会损坏跨 chunk 的多字节
  // 字符(中文/emoji 切在边界 → U+FFFD)。用持续 StringDecoder 按流解码。
  const stdoutDecoder = new StringDecoder('utf8');
  const stderrDecoder = new StringDecoder('utf8');

  channel.on('data', (chunk: Buffer) => {
    // Bytes 路径优先 (二进制协议如 WS frame), 然后 text 路径 — 同一 chunk 可能两边
    // 都有 listener (虽然实际不该混用)。
    if (stdoutBytesListeners.size > 0) {
      for (const cb of stdoutBytesListeners) cb(chunk);
    }
    if (stdoutListeners.size > 0) {
      const s = stdoutDecoder.write(chunk);
      if (s.length > 0) {
        for (const cb of stdoutListeners) cb(s);
      }
    }
  });
  channel.stderr.on('data', (chunk: Buffer) => {
    const s = stderrDecoder.write(chunk);
    if (s.length > 0) {
      for (const cb of stderrListeners) cb(s);
    }
  });
  channel.on('close', (code: number | null, signal: string | null) => {
    // 轮 40-w4-t12 LOW:flush decoder 尾部残留(通道在字符中间关闭时丢尾码点)。
    const tail = stdoutDecoder.end();
    if (tail.length > 0) {
      for (const cb of stdoutListeners) cb(tail);
    }
    const tailErr = stderrDecoder.end();
    if (tailErr.length > 0) {
      for (const cb of stderrListeners) cb(tailErr);
    }
    for (const cb of closeListeners) cb({ code, signal });
  });
  channel.on('error', (err: Error) => {
    for (const cb of errorListeners) cb(err);
  });
  // 轮 23-H4 HIGH:背压恢复信号 —— channel.write 返回 false 后缓冲 drain 时触发。
  channel.on('drain', () => {
    for (const cb of drainListeners) cb();
  });

  return {
    // 轮 23-H4 HIGH:返回 channel.write 的 boolean —— false = ssh2 内部缓冲满
    // (背压信号)。调用方(pi-remote-transport 的 drainPending)据此等待 drain,
    // 避免大输入在慢链路上无界堆积进 Node/ssh2 缓冲。
    write: (data): boolean => channel.write(data),
    end: (data) => { if (data != null) channel.end(data); else channel.end(); },
    onStdout: (cb) => { stdoutListeners.add(cb); return () => { stdoutListeners.delete(cb); }; },
    onStdoutBytes: (cb) => { stdoutBytesListeners.add(cb); return () => { stdoutBytesListeners.delete(cb); }; },
    onStderr: (cb) => { stderrListeners.add(cb); return () => { stderrListeners.delete(cb); }; },
    onDrain: (cb) => { drainListeners.add(cb); return () => { drainListeners.delete(cb); }; },
    onClose: (cb) => { closeListeners.add(cb); return () => { closeListeners.delete(cb); }; },
    onError: (cb) => { errorListeners.add(cb); return () => { errorListeners.delete(cb); }; },
    pause: () => { channel.pause(); },
    resume: () => { channel.resume(); },
    kill: (signal = 'TERM') => {
      try { channel.signal(signal); } catch { /* server may reject */ }
      try { channel.close(); } catch { /* already gone */ }
    },
  };
}

export class RemoteHost {
  readonly id: string;
  private cfg: HostConfig;
  private status: RemoteStatus = 'disconnected';
  private lastError: string | undefined;
  /**
   * The last error thrown by `resolveAuth` during connect, kept as the full
   * Error object. Only set on the local-auth-failure path — where the error
   * carries the synthetic `KEY_FILE_NOT_FOUND_CODE` that `classifyConnectFailure`
   * relies on. The concurrent-join path (connect() while connecting) rethrows
   * this so the structured code survives instead of being flattened into a bare
   * `lastError` string and downgraded to SSH_CONNECT_FAILED.
   */
  private lastAuthError: Error | null = null;
  /**
   * Human-readable label for the credential that succeeded on the most
   * recent successful connect, e.g. "ssh-agent" or "key:id_ed25519".
   * Surfaced to the UI so the user can verify *which* key actually got
   * them in — important when an identityFile is set but agent fallback
   * means the named key isn't actually being used (or vice versa).
   */
  private lastAuthLabel: string | undefined;
  private statusChangedAt = Date.now();
  private client: Client | null = null;
  private reconnectAttempts = 0;
  private reconnectTimer: NodeJS.Timeout | null = null;
  /**
   * Monotonic connection-attempt generation. disconnect() advances it before
   * ending the current client, so an async resolveAuth() or late ssh2 event
   * from the previous endpoint cannot publish status or resurrect a session.
   */
  private connectionEpoch = 0;
  /** The currently running connect attempt, including reconnect attempts. */
  private inFlightConnect: Promise<void> | null = null;
  /** true = user explicitly asked to disconnect; suppress auto-reconnect. */
  private userDisconnected = false;
  private events = new EventEmitter();
  private readonly log: RemoteHostDeps['logger'];
  private readonly hostKeys?: HostKeyStore;
  /**
   * Set by the host-key verifier when it rejects a connect, so onError can
   * surface an actionable message instead of ssh2's opaque handshake error.
   * Reset at the start of every connect attempt.
   */
  private hostKeyError: string | null = null;
  private hostKeyMismatch: HostSnapshot['hostKeyMismatch'];
  /**
   * 已登记的 remote forwarding 愿望清单 (key = localHost:localPort)。
   * 连接断开不清空 — 重连成功后 doConnect 会逐个 re-arm, 尽量绑回原端口。
   */
  private forwards = new Map<string, ForwardRecord>();
  /** 'tcp connection' 是按 client 实例挂的, 每次 doConnect 新建 client 都要重挂。 */
  private forwardListenerClient: Client | null = null;

  constructor(config: HostConfig, deps: RemoteHostDeps) {
    this.id = config.id;
    this.cfg = config;
    this.log = deps.logger;
    this.hostKeys = deps.hostKeys;
  }

  get config(): HostConfig {
    return this.cfg;
  }

  getStatus(): RemoteStatus {
    return this.status;
  }

  /**
   * Replace config (e.g. user edited hostname/port). Caller is responsible
   * for reconnecting — we don't auto-bounce because the caller might have
   * already disconnected first, and bouncing here would re-trigger auth.
   *
   * Emits a `status` event with the new snapshot so renderer's host-list
   * mirror updates without a separate IPC round-trip.
   */
  updateConfig(next: HostConfig): void {
    if (next.id !== this.cfg.id) {
      throw new Error(`RemoteHost.updateConfig: id mismatch (${next.id} != ${this.cfg.id})`);
    }
    this.hostKeyMismatch = undefined;
    this.cfg = next;
    this.events.emit('status', this.snapshot());
  }

  snapshot(): HostSnapshot {
    return {
      config: this.cfg,
      status: this.status,
      lastError: this.lastError,
      hostKeyMismatch: this.hostKeyMismatch ? { ...this.hostKeyMismatch } : undefined,
      lastAuthLabel: this.lastAuthLabel,
      statusChangedAt: this.statusChangedAt,
    };
  }

  onStatus(listener: StatusListener): () => void {
    this.events.on('status', listener);
    return () => this.events.off('status', listener);
  }

  /**
   * Open the connection. Idempotent — if already ready/connecting, returns
   * the in-flight promise. Throws on definitive failure (auth, network).
   */
  async connect(): Promise<void> {
    if (this.status === 'ready') return;
    if (this.status === 'connecting' || this.status === 'authenticating') {
      // Share the actual in-flight attempt instead of waiting only for a
      // future status event. A disconnect can invalidate an attempt after it
      // has emitted its terminal status; joining the Promise guarantees that
      // every caller still receives the cancellation/error outcome.
      if (this.inFlightConnect) {
        await this.inFlightConnect;
      } else {
        await this.waitForTerminal();
      }
      if (this.getStatus() === 'ready') return;
      // Prefer the last resolveAuth error so the structured `.code` survives
      // (classifyConnectFailure needs it); fall back to the string otherwise.
      if (this.lastAuthError) throw this.lastAuthError;
      throw new Error(this.lastError ?? 'connect failed');
    }

    // 'reconnecting' / 'disconnected' / 'failed' 都走立即新建连接路径。
    // 关键: 'reconnecting' 状态下 reconnectTimer 仍在跑, 它稍后还会再调一次
    // doConnect() 覆盖我们刚建好的 SSH client, 产生泄漏的旧连接 + 乱序的
    // status/channel 事件。必须在 doConnect() 前显式清掉 timer 才安全。
    this.clearReconnectTimer();
    this.userDisconnected = false;
    this.reconnectAttempts = 0;
    await this.startConnectAttempt();
  }

  /**
   * Close the connection. Idempotent. Suppresses auto-reconnect until
   * next explicit `connect()` call.
   */
  async disconnect(): Promise<void> {
    this.userDisconnected = true;
    this.connectionEpoch += 1;
    this.clearReconnectTimer();
    this.markForwardsDisarmed();
    if (this.client) {
      try {
        this.client.end();
      } catch {
        // swallow — `end` on a half-dead client occasionally throws
      }
      this.client = null;
    }
    this.setStatus('disconnected');
  }

  // ── channels (Phase B) ──────────────────────────────────────────────────

  /**
   * Run a one-shot command and collect stdout/stderr/exit. Use for short,
   * non-interactive commands (version probes, install scripts).
   *
   * `input`, when set, is written to stdin then the channel is closed.
   * `timeoutMs` defaults to 60 s — long enough for `npm install`. Caller
   * should raise it for known-slow ops (e.g. agent install on a clean box).
   *
   * Error messages NEVER include the cmd string — callers routinely pass
   * commands containing secrets (e.g. `ANTHROPIC_API_KEY=...` env injection
   * via wrapper scripts). Leaking cmd into an error would land it in
   * xdt-maker logs via the unified IPC error path. Use `label` for caller-
   * controlled context in error messages.
   */
  async exec(cmd: string, opts?: ExecOpts): Promise<ExecResult> {
    const client = this.requireReady();
    const timeoutMs = opts?.timeoutMs ?? 60_000;
    const label = opts?.label ?? 'exec';
    // 轮 40-w4-t7 HIGH:默认输出上限 —— 远端命令失控 flood 时无上限缓冲会把
    // 主进程内存/CPU 拉爆。显式传 maxOutputBytes 的调用可覆盖(保持向后兼容;
    // 0 = 显式无上限)。
    const maxOutputBytes = opts?.maxOutputBytes ?? 16 * 1024 * 1024;
    const capActive = maxOutputBytes !== 0;

    return await new Promise<ExecResult>((resolve, reject) => {
      client.exec(cmd, { env: opts?.env }, (err, channel) => {
        if (err) return reject(err);

        let stdout = '';
        let stderr = '';
        let exitCode: number | null = null;
        let signal: string | null = null;
        let settled = false;

        const timer = setTimeout(() => {
          if (settled) return;
          settled = true;
          try { channel.signal('TERM'); } catch { /* server may reject SIGTERM */ }
          try { channel.close(); } catch { /* already gone */ }
          reject(new Error(`${label} timed out after ${timeoutMs}ms`));
        }, timeoutMs);

        // maxOutputBytes:边读边计数,越界即停止缓冲并 teardown 远端命令,
        // 防止任意命令把无上限输出攒进 main 进程内存。teardown 后照常等
        // 'close' 事件 resolve(truncated 标记),与超时路径共用 TERM+close
        // 兜底(channel.signal 可能被 sshd 静默拒绝,close 触发 SIGHUP)。
        let stdoutBytes = 0;
        let stderrBytes = 0;
        let truncated = false;
        const teardownOnCap = (): void => {
          if (truncated) return;
          truncated = true;
          try { channel.signal('TERM'); } catch { /* server may reject SIGTERM */ }
          try { channel.close(); } catch { /* already gone */ }
        };
        const takeCapped = (chunk: Buffer, usedBytes: number): Buffer | null => {
          if (!capActive) return chunk;
          if (usedBytes >= maxOutputBytes) { teardownOnCap(); return null; }
          if (usedBytes + chunk.length <= maxOutputBytes) return chunk;
          teardownOnCap();
          return chunk.subarray(0, maxOutputBytes - usedBytes);
        };

        // 轮 40-w4-t12 MEDIUM:按 chunk toString('utf8') 会损坏跨 chunk 多字节
        // 字符(中文/emoji 切在边界 → U+FFFD)。用持续 StringDecoder 按流解码,
        // close 时 end() flush 尾部残留。
        const stdoutDecoder = new StringDecoder('utf8');
        const stderrDecoder = new StringDecoder('utf8');
        channel.on('data', (chunk: Buffer) => {
          const kept = takeCapped(chunk, stdoutBytes);
          if (!kept) return;
          stdoutBytes += kept.length;
          stdout += stdoutDecoder.write(kept);
        });
        channel.stderr.on('data', (chunk: Buffer) => {
          const kept = takeCapped(chunk, stderrBytes);
          if (!kept) return;
          stderrBytes += kept.length;
          stderr += stderrDecoder.write(kept);
        });
        channel.on('close', (code: number | null, sig: string | null) => {
          if (settled) return;
          settled = true;
          clearTimeout(timer);
          // 轮 40-w4-t12 LOW:flush decoder 尾部残留(通道在字符中间关闭)。
          stdout += stdoutDecoder.end();
          stderr += stderrDecoder.end();
          exitCode = code;
          signal = sig;
          resolve({ stdout, stderr, exitCode, signal, ...(truncated ? { truncated: true } : {}) });
        });
        channel.on('error', (e: Error) => {
          if (settled) return;
          settled = true;
          clearTimeout(timer);
          reject(e);
        });

        if (opts?.input != null) {
          channel.write(opts.input);
          channel.end();
        }
      });
    });
  }

  /**
   * Open a streaming exec channel. Caller drives stdin (for interactive
   * tools like Claude Code's `--input-format stream-json`) and consumes
   * stdout / stderr via callbacks. Lifecycle ends on `close` or `kill()`.
   *
   * No timeout — caller owns lifetime. Streams stay open across long
   * agent sessions.
   */
  async execStream(cmd: string, opts?: ExecStreamOpts): Promise<ExecStreamHandle> {
    const client = this.requireReady();
    return await new Promise<ExecStreamHandle>((resolve, reject) => {
      const execOpts: { pty?: boolean | object; env?: Record<string, string> } = {};
      if (opts?.pty) execOpts.pty = true;
      if (opts?.env) execOpts.env = opts.env;

      // 轮 40-w4-t6 HIGH:建立阶段超时 —— exec callback 晚到时 kill 晚到
      // channel 并 reject, 防调用方无限挂起 + channel 逃逸成孤儿。
      let settled = false;
      let timer: NodeJS.Timeout | undefined;
      const cleanup = (): void => {
        if (timer) { clearTimeout(timer); timer = undefined; }
      };
      if (opts?.timeoutMs && opts.timeoutMs > 0) {
        timer = setTimeout(() => {
          if (settled) return;
          settled = true;
          reject(new Error(`execStream setup timed out after ${opts.timeoutMs}ms`));
        }, opts.timeoutMs);
        timer.unref?.();
      }
      client.exec(cmd, execOpts, (err, channel) => {
        if (settled) {
          // 超时已 reject:晚到 channel 必须关闭(防孤儿;ClientChannel 无 kill,
          // close 关闭 ssh2 channel 流)。
          try { channel?.close(); } catch { /* best-effort */ }
          return;
        }
        settled = true;
        cleanup();
        if (err) return reject(err);
        resolve(wrapChannel(channel));
      });
    });
  }

  // ── remote TCP forwarding (ssh -R) ────────────────────────────────────────

  /**
   * 登记并 (若已连接) 立即建立一条 remote forwarding: 远端 127.0.0.1:<port>
   * 进来的 TCP 连接经本 SSH 连接转回, pipe 到本机 spec.localHost:localPort。
   *
   * 幂等: 同 (localHost, localPort) 重复调用返回同一条 forward。
   * 未连接时只登记愿望, 下次 connect 成功后自动 arm (doConnect → rearmForwards)。
   *
   * 安全约束: 远端只绑 127.0.0.1 — 隧道口仅远端本机进程可达, 不对远端所在
   * 网络暴露 (即不要 GatewayPorts 语义)。本地目标由调用方 (用户 pref) 显式
   * 指定, 通常是 127.0.0.1 上的 Proxy 端口。
   */
  async ensureRemoteForward(spec: RemoteForwardSpec): Promise<RemoteForward> {
    // 引号与空白同样拒 (与 desktop IPC / prefs-store 校验对齐, review:
    // PR #715 copilot R8): localHost 是 net.connect 的目的地, 含引号的值
    // 会晚到 connect 时才以难懂的错误失败, 入口直接给清晰校验错误。
    if (
      !spec.localHost ||
      /\s/.test(spec.localHost) ||
      spec.localHost.includes("'") ||
      spec.localHost.includes('"')
    ) {
      throw new Error(`ensureRemoteForward: invalid localHost "${spec.localHost}"`);
    }
    if (!Number.isInteger(spec.localPort) || spec.localPort < 1 || spec.localPort > 65535) {
      throw new Error(`ensureRemoteForward: invalid localPort ${spec.localPort}`);
    }
    // preferredRemotePort 同样入口校验 (review: PR #715 copilot R7): 0 会静默
    // 变成「远端绑 ephemeral 端口」语义, 越界值则晚到 arm 才失败, 都难排查。
    if (
      spec.preferredRemotePort !== undefined &&
      (!Number.isInteger(spec.preferredRemotePort) ||
        spec.preferredRemotePort < 1 ||
        spec.preferredRemotePort > 65535)
    ) {
      throw new Error(`ensureRemoteForward: invalid preferredRemotePort ${spec.preferredRemotePort}`);
    }
    if (spec.exactRemotePort && spec.preferredRemotePort === undefined) {
      throw new Error('ensureRemoteForward: exactRemotePort requires preferredRemotePort');
    }
    const key = forwardKey(spec);
    const existing = this.forwards.get(key);
    if (existing) {
      // 已登记但未 arm (连接刚建好 / 上次 arm 失败) — 趁 ready 补一次。
      if (!existing.armed && this.status === 'ready') {
        await this.armWithStaleRetry(existing);
      }
      return this.forwardHandle(key, existing);
    }

    const record: ForwardRecord = {
      spec,
      remotePort: spec.preferredRemotePort ?? DEFAULT_REMOTE_FORWARD_PORT_BASE,
      armed: false,
      refCount: 0,
      lastLocalErrorAt: 0,
      localErrorCount: 0,
      lastLocalErrorLoggedCount: 0,
    };
    this.forwards.set(key, record);
    if (this.status === 'ready') {
      await this.armWithStaleRetry(record);
    }
    return this.forwardHandle(key, record);
  }

  /**
   * arm + 旧连接迟到回调的一次即时重试 (见 StaleForwardArmError)。
   * 其余错误原样抛出给调用方 (session 路径 fail-closed / ready-hook 记状态)。
   */
  private async armWithStaleRetry(record: ForwardRecord): Promise<void> {
    try {
      await this.armForwardDeduped(record);
    } catch (err) {
      if (err instanceof StaleForwardArmError && this.status === 'ready') {
        await this.armForwardDeduped(record);
        return;
      }
      throw err;
    }
  }

  /**
   * 当前登记的 forward 列表 (诊断 / snapshot 用)。armed=false 表示愿望已
   * 登记但当前没在转发 (未连接 / arm 失败待重连)。
   */
  listRemoteForwards(): Array<{ localHost: string; localPort: number; remotePort: number; armed: boolean }> {
    return Array.from(this.forwards.values()).map((r) => ({
      localHost: r.spec.localHost,
      localPort: r.spec.localPort,
      remotePort: r.remotePort,
      armed: r.armed,
    }));
  }

  /**
   * 关闭指定本地目标的单条 forward (无该登记时 no-op)。与 closeAll 不同
   * 不会在 ensure 语义下误触发 arm — 用于「目标变了, 先拆旧的」
   * (review: PR #715 R5: pref 的 localHost/localPort 被编辑后, 旧目标的
   * forward 会残留并随重连 re-arm, 远端多暴露一个隧道口)。
   */
  async closeRemoteForward(localHost: string, localPort: number): Promise<void> {
    const key = `${localHost}:${localPort}`;
    const record = this.forwards.get(key);
    if (!record) return;
    // 强制路径(陈旧 forward 清理): 无视引用计数直接拆 —— 调用方语义是「目标
    // 已失效, 旧隧道必须拆除」, 共享者同样不再能指向旧目标。剩余句柄的 close
    // 幂等 no-op(record 已摘除)。
    record.refCount = 0;
    await this.closeForwardRecord(key, record);
  }

  /** 关闭并清除所有已登记 forward (pref 关闭路径)。连接断开时是纯本地清理。 */
  async closeAllRemoteForwards(): Promise<void> {
    const keys = Array.from(this.forwards.keys());
    for (const key of keys) {
      const record = this.forwards.get(key);
      if (!record) continue;
      record.refCount = 0;
      await this.closeForwardRecord(key, record);
    }
  }

  private forwardHandle(key: string, record: ForwardRecord): RemoteForward {
    record.refCount += 1;
    let closed = false;
    return {
      get remotePort() {
        return record.remotePort;
      },
      close: async () => {
        // 同 handle 幂等: 只释放一次计数(调用方 dispose 与 catch 兜底可能双调)。
        if (closed) return;
        closed = true;
        record.refCount -= 1;
        // 轮 42 P1(codex-connector):引用计数 —— 同一 (localHost, localPort) 的
        // forward 被多个会话共享(同 host 多 Pi 会话共用同一 in-process MCP
        // bridge 端口)时, 一个会话 dispose 不得拆掉别人还在用的隧道。
        // 只剩自己(refCount 归 0)才真正 unforward 并摘除 record。
        if (record.refCount > 0) return;
        await this.closeForwardRecord(key, record);
      },
    };
  }

  /** 真正拆除 forward(引用计数归 0 / 强制关闭路径共用)。幂等。 */
  private async closeForwardRecord(key: string, record: ForwardRecord): Promise<void> {
    if (!this.forwards.delete(key)) return;
    record.armed = false;
    // 连接活着就显式 unforward; 断线时服务端侧随连接消失, 无需操作。
    if (this.status === 'ready' && this.client) {
      // 与 forwardIn 对称的看门狗 (review: PR #715 五轮审核 P2): 半开连接
      // 上 ssh2 global request 回调可能丢失, 裸 await 会把 Settings 的
      // 关闭 proxy / 更新 host 流程永久挂住。超时后照常返回 — record 已
      // 摘除, 服务端残留随连接死亡消失。
      await new Promise<void>((resolve) => {
        const timer = setTimeout(() => {
          this.log.warn('unforwardIn timed out — proceeding (server remnant dies with connection)', {
            id: this.id,
            port: record.remotePort,
          });
          resolve();
        }, 5_000);
        timer.unref?.();
        try {
          this.client!.unforwardIn('127.0.0.1', record.remotePort, () => {
            clearTimeout(timer);
            resolve();
          });
        } catch {
          clearTimeout(timer);
          resolve();
        }
      });
    }
  }

  /**
   * 在当前 client 上注册 forwardIn。端口冲突 / sshd 拒绝时按候选序列重试,
   * 全部失败抛错 (调用方决定是登记愿望待重试还是直接失败)。
   *
   * 候选顺序: 先试上次实际绑定的端口 (record.remotePort) — 重连后隧道口
   * 尽量不变, 远端进程 env (HTTPS_PROXY=http://127.0.0.1:<port>) 不用跟着
   * 重写; 再按首选基数顺延。每次 forwardIn 带 10s 看门狗: 连接在请求在飞
   * 时断开的话, ssh2 对 outstanding global request 的回调不保证触发,
   * 裸 await 会永久挂起。
   */
  private async armForward(record: ForwardRecord): Promise<void> {
    const client = this.requireReady();
    this.attachForwardListener(client);

    const base = record.spec.preferredRemotePort ?? DEFAULT_REMOTE_FORWARD_PORT_BASE;
    // exact 模式恒试 preferred 而非 record.remotePort (review: PR #992
    // copilot): 同 key 的 record 可能是在非 exact 阶段顺延漂到别的端口的,
    // 以漂移值为种子会把「固定端口」语义吃回去。
    const candidates = record.spec.exactRemotePort ? [base] : [record.remotePort];
    if (!record.spec.exactRemotePort) {
      for (let i = 0; i < REMOTE_FORWARD_PORT_SCAN_SPAN; i++) {
        if (!candidates.includes(base + i)) candidates.push(base + i);
      }
    }
    const errors: string[] = [];
    for (const port of candidates) {
      const bound = await new Promise<number | null>((resolve) => {
        let settled = false;
        const timer = setTimeout(() => {
          settled = true;
          errors.push(`${port}: forwardIn timed out after 10s`);
          resolve(null);
        }, 10_000);
        timer.unref?.();
        try {
          client.forwardIn('127.0.0.1', port, (err, boundPort) => {
            clearTimeout(timer);
            if (settled) {
              // 看门狗已判失败, 迟到的成功会在服务端留下没有 record 的野
              // 监听 (端口被占 + 连接被默默转走) — 立刻拆除。
              if (!err) {
                this.log.warn('late forwardIn success after watchdog timeout — unbinding', {
                  id: this.id,
                  port: boundPort || port,
                });
                try {
                  client.unforwardIn('127.0.0.1', boundPort || port, () => { /* best-effort */ });
                } catch { /* client may be dead */ }
              }
              return;
            }
            settled = true;
            if (err) {
              errors.push(`${port}: ${err.message}`);
              resolve(null);
            } else {
              resolve(boundPort || port);
            }
          });
        } catch (err) {
          clearTimeout(timer);
          if (settled) return;
          settled = true;
          errors.push(`${port}: ${(err as Error).message}`);
          resolve(null);
        }
      });
      if (bound == null) continue;
      // close() 可能发生在 arm 在飞期间: record 已被摘除的话, 刚绑上的
      // 端口同样是野监听 — 立即 unforward, 以失败收尾 (armForwardDeduped
      // 的调用方都已 catch)。
      if (this.forwards.get(forwardKey(record.spec)) !== record) {
        this.log.warn('forward closed while arming — unbinding just-bound port', {
          id: this.id,
          port: bound,
        });
        // 与 forwardHandle.close() 相同的 5s 看门狗: 半开连接上 unforwardIn
        // 回调可能丢失, 这里挂住会把 ensureRemoteForward 的调用方
        // (Settings 关闭 proxy / 更新 host) 一起拖死 (worker 核验补充)。
        await new Promise<void>((resolve) => {
          const timer = setTimeout(() => resolve(), 5_000);
          timer.unref?.();
          try {
            client.unforwardIn('127.0.0.1', bound, () => {
              clearTimeout(timer);
              resolve();
            });
          } catch {
            clearTimeout(timer);
            resolve();
          }
        });
        throw new Error(`remote forward to ${forwardKey(record.spec)} was closed while arming`);
      }
      // 连接代际校验 (review: PR #715 五轮审核 P1): arm 在飞期间发生了
      // 断线/重连的话, this.client 已换成新连接, 这个绑定落在旧 (将死) 连接
      // 上 — 若不拦截, record 会被误标 armed, rearmForwards 见 armed 直接
      // 跳过, 隧道「以为建好了实际新连接上没有」。旧 client 上 best-effort
      // 拆除 (多半已死), 以专门错误收尾让调用方立即在当前连接重试。
      if (this.client !== client) {
        this.log.warn('forwardIn resolved on a stale connection — unbinding and re-arming', {
          id: this.id,
          port: bound,
        });
        try {
          client.unforwardIn('127.0.0.1', bound, () => { /* best-effort; client likely dead */ });
        } catch { /* dead */ }
        throw new StaleForwardArmError(
          `remote forward to ${forwardKey(record.spec)} armed on a stale connection`,
        );
      }
      record.remotePort = bound;
      record.armed = true;
      this.log.info('ssh remote forward armed', {
        id: this.id,
        remotePort: bound,
        localTarget: forwardKey(record.spec),
      });
      return;
    }
    throw new Error(
      `remote port forwarding failed on ${this.id} (tried 127.0.0.1:${candidates.join(',')}). ` +
      `The remote sshd may disallow remote forwarding (AllowTcpForwarding) or the ports are busy. ` +
      errors.slice(0, 3).join('; '),
    );
  }

  /** connect 成功后重挂所有已登记 forward; 端口变了通知上层。 */
  private async rearmForwards(): Promise<void> {
    for (const record of this.forwards.values()) {
      const prevPort = record.remotePort;
      record.armed = false;
      // 旧连接的迟到 arm 回调会以 StaleForwardArmError 收尾 — 当前连接还没
      // arm, 立即重试一次 (record.arming 已被 finally 清掉, 可重新发起)。
      // 其余错误 (端口占用 / sshd 拒绝) 不重试, 等下次 reconnect 或 session
      // 路径的 ensureRemoteForward 显式触发。
      let armed = false;
      let lastErr: Error | null = null;
      for (let attempt = 0; attempt < 2 && !armed; attempt++) {
        try {
          await this.armForwardDeduped(record);
          armed = true;
        } catch (err) {
          lastErr = err as Error;
          if (!(err instanceof StaleForwardArmError)) break;
        }
      }
      if (!armed) {
        // arm 失败不阻断连接 — 记日志, 下次 reconnect 再试; session 路径
        // (ensureRemoteForward on ready host) 会显式重试并拿到错误。
        this.log.warn('ssh remote forward re-arm failed', {
          id: this.id,
          localTarget: forwardKey(record.spec),
          error: lastErr?.message,
        });
        continue;
      }
      if (record.remotePort !== prevPort) {
        this.log.warn('ssh remote forward re-bound to a different port', {
          id: this.id,
          prevPort,
          remotePort: record.remotePort,
        });
        try {
          record.spec.onRearmed?.(record.remotePort);
        } catch { /* listener must not throw */ }
      }
    }
  }

  /** 同一条 forward 的并发 arm 共享一个 in-flight promise。 */
  private armForwardDeduped(record: ForwardRecord): Promise<void> {
    if (record.armed) return Promise.resolve();
    if (!record.arming) {
      // finally 只在引用仍是自己时清 — markForwardsDisarmed 可能在在飞期间
      // 清掉旧引用, 新 arm 已重新赋值; 无条件清会误删新 promise 再造竞争。
      const p = this.armForward(record).finally(() => {
        if (record.arming === p) record.arming = undefined;
      });
      record.arming = p;
    }
    return record.arming;
  }

  /** 每个 client 实例挂一次 'tcp connection' 分发器。 */
  private attachForwardListener(client: Client): void {
    if (this.forwardListenerClient === client) return;
    this.forwardListenerClient = client;
    client.on('tcp connection', (details: TcpConnectionDetails, accept, reject) => {
      this.handleForwardedConnection(details, accept, reject);
    });
  }

  private handleForwardedConnection(
    details: TcpConnectionDetails,
    accept: () => ClientChannel,
    reject: () => void,
  ): void {
    // fail-closed (PR #715 copilot): 远端 sshd 若配了 permissive GatewayPorts,
    // 隧道口可能绑在非 loopback 接口 — 远端网络的任意机器都能经隧道借用
    // 本机的本地 Proxy。只接受 loopback 来源的转发连接 (远端 daemon 与
    // sshd 同机, 合法来源恒为 loopback; IPv6 / IPv4-mapped 形式都认)。
    if (
      details.srcIP !== '127.0.0.1'
      && details.srcIP !== '::1'
      && details.srcIP !== '::ffff:127.0.0.1'
    ) {
      this.log.warn('ssh remote forward: rejecting non-loopback forwarded connection', {
        id: this.id,
        srcIP: details.srcIP,
        destPort: details.destPort,
      });
      reject();
      return;
    }
    let record: ForwardRecord | undefined;
    for (const r of this.forwards.values()) {
      if (r.armed && r.remotePort === details.destPort) {
        record = r;
        break;
      }
    }
    if (!record) {
      reject();
      return;
    }
    const rec = record;
    const channel = accept();
    const sock = net.connect({ host: rec.spec.localHost, port: rec.spec.localPort });

    sock.on('error', (err) => {
      // 本地 Proxy 没起 / 拒连 — 远端 agent 会看到连接立刻被断, 错误在
      // agent 侧浮现 (proxy connect failed)。这里只做节流日志。
      rec.localErrorCount += 1;
      const now = Date.now();
      if (now - rec.lastLocalErrorAt > 30_000) {
        rec.lastLocalErrorAt = now;
        // 距上次日志被吞掉的条数, 不含本次 (localErrorCount 已含本次, -1 扣除;
        // 否则首条日志就会误报 suppressed=1, review: PR #715 greptile R4)。
        const suppressed = rec.localErrorCount - rec.lastLocalErrorLoggedCount - 1;
        rec.lastLocalErrorLoggedCount = rec.localErrorCount;
        this.log.warn('ssh remote forward: local target unreachable', {
          id: this.id,
          localTarget: forwardKey(rec.spec),
          error: err.message,
          suppressedCount: suppressed,
        });
      }
      // error 后 socket 必须销毁 (review: PR #715 copilot R3) — 只关 channel
      // 不 destroy 会把本地侧留成半开, Proxy 进程上积 CLOSE_WAIT。
      sock.destroy();
      try { channel.close(); } catch { /* already gone */ }
    });
    channel.on('error', () => {
      sock.destroy();
    });
    // 远端关掉转发 channel → 本地到 Proxy 的 socket 同步销毁; 否则本地
    // Proxy 侧会积一堆半开连接 (pipe 的 end 只处理正常 EOF, 不覆盖 destroy)。
    channel.on('close', () => {
      sock.destroy();
    });
    sock.on('close', () => {
      try { channel.close(); } catch { /* already gone */ }
    });
    channel.pipe(sock);
    sock.pipe(channel);
  }

  // ── internals ────────────────────────────────────────────────────────────

  /** Guard for channel ops. */
  private requireReady(): Client {
    if (this.status !== 'ready' || !this.client) {
      throw new Error(`remote host "${this.id}" is not ready (status=${this.status})`);
    }
    return this.client;
  }

  /**
   * ssh2 `hostVerifier` — TOFU against the injected store. Returns true to
   * accept the handshake, false to reject it (ssh2 then emits an error which
   * onError maps to `hostKeyError`). Fails closed: a missing store or a read
   * error refuses the connect rather than trusting an unverified key.
   */
  private async verifyHostKey(
    hostKey: Buffer,
    storeKey: string,
    isCurrentAttempt: () => boolean,
  ): Promise<boolean> {
    // A cancelled client must not even touch the shared TOFU store. In
    // particular, updateConfig() may already have published a new endpoint
    // while the old ssh2 client delivers a late hostVerifier callback.
    if (!isCurrentAttempt()) return false;
    const store = this.hostKeys;
    if (!store) {
      if (isCurrentAttempt()) {
        this.hostKeyError =
          'SSH host key verification is not configured; refusing to connect without it.';
      }
      this.log.error('ssh host key store missing — refusing connect', { id: this.id });
      return false;
    }
    // Discard any stale in-memory cache so a user who repaired known-hosts.json
    // (e.g. removed a stale entry after a legitimate server re-key) sees the
    // update on reconnect without restarting the app.
    store.reload();
    if (!isCurrentAttempt()) return false;
    const presented = hostKeyFingerprint(hostKey);
    let stored: string | null;
    try {
      stored = await store.get(storeKey);
    } catch (err) {
      if (isCurrentAttempt()) {
        this.hostKeyError = `failed to read trusted host keys: ${(err as Error).message}`;
      }
      this.log.error('ssh known-hosts read failed — refusing connect', {
        id: this.id,
        error: (err as Error).message,
      });
      return false;
    }
    if (!isCurrentAttempt()) return false;

    const decision = decideHostKey(stored, presented);
    if (decision === 'match') return true;
    if (decision === 'trust-new') {
      if (!isCurrentAttempt()) return false;
      try {
        await store.set(storeKey, presented, isCurrentAttempt);
      } catch (err) {
        // Cannot persist the trusted fingerprint — refuse the connection.
        // Proceeding without persistence means the next reconnect would
        // re-enter trust-new and silently accept any key, defeating TOFU.
        if (isCurrentAttempt()) {
          this.hostKeyError = `failed to persist trusted host key: ${(err as Error).message}`;
        }
        this.log.error('ssh known-hosts write failed — refusing connect', {
          id: this.id,
          error: (err as Error).message,
        });
        return false;
      }
      if (!isCurrentAttempt()) return false;
      this.log.info('ssh host key trusted on first use', {
        id: this.id,
        host: storeKey,
        fingerprint: presented,
      });
      return true;
    }
    // mismatch
    if (isCurrentAttempt()) {
      this.hostKeyMismatch = { host: storeKey, trusted: stored!, presented };
      this.hostKeyError =
        `SSH host key changed for ${storeKey}. Connection refused.\n` +
        `Previously trusted: ${stored}\nPresented: ${presented}\n` +
        `This may be a server reinstall or an intercepted connection. Verify the new fingerprint ` +
        `with the server administrator through a trusted channel, then review the host key in ` +
        `Cindy Settings > Remote. Cindy uses its own remote-ssh/known-hosts.json, not ` +
        `~/.ssh/known_hosts. Changing your login key will not fix this error.`;
    }
    this.log.error('ssh host key mismatch — refusing connect', {
      id: this.id,
      host: storeKey,
      presented,
      trusted: stored,
    });
    return false;
  }

  private async doConnect(): Promise<void> {
    const attemptEpoch = ++this.connectionEpoch;
    const isCurrentAttempt = (): boolean => attemptEpoch === this.connectionEpoch;
    const cancelledError = (): Error => new Error('SSH connection attempt cancelled');
    const attemptConfig: HostConfig = {
      ...this.cfg,
      ...(this.cfg.sshAuthentication
        ? {
            sshAuthentication: {
              ...this.cfg.sshAuthentication,
              configuredIdentityFiles: [
                ...this.cfg.sshAuthentication.configuredIdentityFiles,
              ],
              ...(this.cfg.sshAuthentication.allowedAgentFingerprints
                ? {
                    allowedAgentFingerprints: [
                      ...this.cfg.sshAuthentication.allowedAgentFingerprints,
                    ],
                  }
                : {}),
            },
          }
        : {}),
    };
    this.setStatus('connecting');
    this.hostKeyError = null;
    this.hostKeyMismatch = undefined;
    this.lastAuthError = null;

    let auth;
    try {
      auth = await resolveAuth(attemptConfig);
    } catch (err) {
      if (!isCurrentAttempt()) throw cancelledError();
      const msg = (err as Error).message;
      this.lastError = msg;
      // Keep the full error so concurrent connect() joiners can rethrow it
      // with its structured `.code` intact (see lastAuthError + connect()).
      this.lastAuthError = err instanceof Error ? err : new Error(msg);
      this.setStatus('failed');
      throw err;
    }

    // disconnect() may have run while local credentials were being resolved.
    // Do not create an ssh2 client after that cancellation boundary.
    if (!isCurrentAttempt()) throw cancelledError();

    // Unsupported configuration fails in resolveAuth above. Only a usable,
    // fully-resolved endpoint may participate in TOFU identity calculation.
    const attemptHostKeyId = hostKeyId(attemptConfig.hostname, attemptConfig.port);
    const client = new Client();
    this.client = client;

    const connectConfig: ConnectConfig = {
      host: attemptConfig.hostname,
      port: attemptConfig.port,
      username: attemptConfig.user,
      readyTimeout: READY_TIMEOUT_MS,
      keepaliveInterval: KEEPALIVE_INTERVAL_MS,
      keepaliveCountMax: KEEPALIVE_COUNT_MAX,
      // TOFU host key check — without this ssh2 trusts any presented key (MITM).
      hostVerifier: (hostKey: Buffer, verify: (valid: boolean) => void): void => {
        if (!isCurrentAttempt()) {
          verify(false);
          return;
        }
        void this.verifyHostKey(hostKey, attemptHostKeyId, isCurrentAttempt).then(
          (valid) => verify(isCurrentAttempt() ? valid : false),
          () => verify(false),
        );
      },
      ...(auth.agent ? { agent: auth.agent } : {}),
      ...(auth.privateKey ? { privateKey: auth.privateKey } : {}),
      ...(auth.passphrase ? { passphrase: auth.passphrase } : {}),
    };

    this.log.debug('ssh connecting', {
      id: this.id,
      hostname: attemptConfig.hostname,
      port: attemptConfig.port,
      auth: auth.label,
    });

    await new Promise<void>((resolve, reject) => {
      let settled = false;

      const onReady = () => {
        if (settled) return;
        if (!isCurrentAttempt()) {
          settled = true;
          try { client.end(); } catch { /* stale client is already closing */ }
          reject(cancelledError());
          return;
        }
        settled = true;
        this.lastError = undefined;
        this.lastAuthLabel = auth.label;
        this.reconnectAttempts = 0;
        this.setStatus('ready');
        this.log.info('ssh ready', { id: this.id, auth: auth.label });
        // 后台重挂已登记的 remote forwards; 不阻塞 connect 返回 (session
        // 路径会自己 await ensureRemoteForward 拿到 arm 错误)。
        void this.rearmForwards();
        resolve();
      };

      const onError = (err: Error) => {
        if (!isCurrentAttempt()) {
          if (!settled) {
            settled = true;
            reject(cancelledError());
          }
          return;
        }
        if (settled) {
          // Post-ready error — feed into reconnect path, not the connect promise.
          this.handlePostReadyError(err);
          return;
        }
        settled = true;
        // A rejected host key surfaces here as an opaque ssh2 handshake error;
        // prefer the actionable MITM/re-key message the verifier stashed.
        // Otherwise swap opaque "All configured authentication methods failed"
        // for a hint pointing at ssh-copy-id / identity file. The host row
        // subtitle + connect-failure toast both surface this verbatim.
        this.lastError = this.hostKeyError
          ? this.hostKeyError
          : isAuthFailure(err.message)
            ? authFailureHint(attemptConfig)
            : err.message;
        this.client = null;
        this.setStatus('failed');
        this.log.warn('ssh connect failed', { id: this.id, error: err.message });
        // Reject with the friendly message so IPC layer's toast also gets
        // the actionable copy (it pulls from `.message`).
        const rejectErr = new Error(this.lastError);
        if (this.hostKeyMismatch) Object.assign(rejectErr, { code: 'SSH_HOST_KEY_MISMATCH' });
        // Preserve original for tests / debugging that key off message text.
        (rejectErr as Error & { cause?: unknown }).cause = err;
        reject(rejectErr);
      };

      const onClose = () => {
        if (!isCurrentAttempt()) {
          if (!settled) {
            settled = true;
            reject(cancelledError());
          }
          return;
        }
        if (!settled) {
          settled = true;
          const msg = this.lastError ?? 'connection closed before ready';
          this.lastError = msg;
          this.client = null;
          this.setStatus('failed');
          reject(new Error(msg));
          return;
        }
        // Post-ready close — schedule reconnect unless user-initiated.
        this.handlePostReadyClose();
      };

      // ssh2 emits 'handshake' before 'ready' — repurpose to advance state
      // so renderer can show "authenticating" instead of staying on
      // "connecting" throughout auth. ssh2 also emits it after every later
      // key exchange (server-initiated rekey, e.g. Dropbear every 8h) without
      // a following 'ready', so only the attempt's first, unsettled handshake
      // may move the status; a rekey must leave a ready host ready (#5715).
      client.on('handshake', () => {
        if (!settled && isCurrentAttempt()) this.setStatus('authenticating');
      });
      client.on('ready', onReady);
      client.on('error', onError);
      client.on('close', onClose);

      try {
        client.connect(connectConfig);
      } catch (err) {
        onError(err as Error);
      }
    });
  }

  /** Start and register a connect attempt so concurrent callers can join it. */
  private startConnectAttempt(): Promise<void> {
    const attempt = this.doConnect();
    this.inFlightConnect = attempt;
    void attempt.then(
      () => {
        if (this.inFlightConnect === attempt) this.inFlightConnect = null;
      },
      () => {
        if (this.inFlightConnect === attempt) this.inFlightConnect = null;
      },
    );
    return attempt;
  }

  private handlePostReadyError(err: Error): void {
    this.lastError = err.message;
    this.log.warn('ssh post-ready error', { id: this.id, error: err.message });
    // 'close' will follow — reconnect is handled there to avoid double-scheduling.
  }

  private handlePostReadyClose(): void {
    this.client = null;
    this.markForwardsDisarmed();
    if (this.userDisconnected) {
      this.setStatus('disconnected');
      return;
    }
    if (this.hostKeyError) {
      this.clearReconnectTimer();
      this.setStatus('failed');
      return;
    }
    // Auth failures are deterministic — retrying with the same agent / key
    // produces the same outcome. Fail fast so the user sees the actionable
    // hint immediately instead of waiting 30+ s for the backoff to give up.
    // Auto-reconnect's intended target is transient network failures
    // (DNS hiccup, keepalive timeout) — those benefit from retry.
    if (this.lastError && isAuthFailure(this.lastError)) {
      this.log.info('ssh skipping reconnect (auth failure is deterministic)', {
        id: this.id,
      });
      this.setStatus('failed');
      return;
    }
    if (this.reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
      this.setStatus('failed');
      return;
    }
    this.scheduleReconnect();
  }

  private scheduleReconnect(): void {
    this.clearReconnectTimer();
    this.reconnectAttempts += 1;
    // Exponential backoff capped at 30s. attempt=1 → 1s, 2 → 2s, 3 → 4s, ...
    const delay = Math.min(
      RECONNECT_BASE_DELAY_MS * 2 ** (this.reconnectAttempts - 1),
      30_000,
    );
    this.setStatus('reconnecting');
    this.log.info('ssh scheduling reconnect', {
      id: this.id,
      attempt: this.reconnectAttempts,
      delayMs: delay,
    });
    this.reconnectTimer = setTimeout(() => {
      this.reconnectTimer = null;
      void this.startConnectAttempt().catch((err) => {
        // doConnect already set status=failed and recorded lastError.
        // If we still have attempts left, schedule again.
        if (this.userDisconnected || this.hostKeyError) return;
        if (this.reconnectAttempts < MAX_RECONNECT_ATTEMPTS) {
          this.scheduleReconnect();
        } else {
          this.log.error('ssh reconnect exhausted', { id: this.id, error: (err as Error).message });
        }
      });
    }, delay);
  }

  private clearReconnectTimer(): void {
    if (this.reconnectTimer) {
      clearTimeout(this.reconnectTimer);
      this.reconnectTimer = null;
    }
  }

  /** 连接断了后服务端侧的转发监听随之消失; 愿望保留, 等下次 ready 重挂。 */
  private markForwardsDisarmed(): void {
    for (const record of this.forwards.values()) {
      record.armed = false;
      // 在飞 arm 是在旧连接上发起的 — 清掉引用让新连接的 rearm 重新发起,
      // 旧 promise 的迟到成功由 armForward 的连接代际校验拦截
      // (StaleForwardArmError), 不会误标 armed。
      record.arming = undefined;
    }
    // 分发器挂在旧 client 上 — 清掉引用, 否则 RemoteHost 长期持有死 client
    // (抑制 GC + 多次重连后旧 client 上 listener 堆积, review: PR #715
    // copilot R3)。新 client 首次 arm 时 attachForwardListener 会重新挂。
    this.forwardListenerClient = null;
  }

  private setStatus(next: RemoteStatus): void {
    if (this.status === next) return;
    this.status = next;
    this.statusChangedAt = Date.now();
    this.events.emit('status', this.snapshot());
  }

  /** Wait until status leaves {connecting, authenticating}. */
  private waitForTerminal(): Promise<void> {
    if (this.status !== 'connecting' && this.status !== 'authenticating') {
      return Promise.resolve();
    }
    return new Promise((resolve) => {
      const off = this.onStatus((snap) => {
        if (snap.status !== 'connecting' && snap.status !== 'authenticating') {
          off();
          resolve();
        }
      });
    });
  }
}