zai-org / zai-org/feedback

[Bug] Remote SSH connect always fails: "Handshake timeout: no zcode-hello received within timeout"

Open
#686 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

priority: P2 status: 待评估 type: Bug
Dominant language
No language data
Stars
22
Forks
1
PR merge metrics
No merged PRs in 30d

Description

提交前确认 · Pre-submission checklist
  • 我已搜索过现有 issue,确认这不是重复 / I searched existing issues and confirmed this isn't a duplicate.
  • 我已阅读 CONTRIBUTING.md / I've read CONTRIBUTING.md.
问题类别 · Category

其他 / 不确定 · Other / Not sure

涉及的 Agent 框架 · Agent framework

ZCode Agent(自研)

严重程度 · Severity

阻塞使用 · Blocking (无法使用核心功能 / core function unusable)

复现频率 · Reproducibility

必现 · Always

问题描述 · Description

ZCode Desktop cannot connect to a remote host over SSH. The client gives the
remote server a fixed 10 seconds to print its first stdout line ("zcode-hello").
On a slow remote the server needs well over 10 s just to load its ~11.4 MB
bundle (measured on my setup: ~18 s steady-state, up to ~2.5 min under load),
so the handshake deterministically times out. The server itself is healthy:
"zcode-hello" is the very first thing it prints — it simply boots later than
the client is willing to wait. No stderr, no crash. The 10 s timeout is
hardcoded (default arg 1e4 ms, two copies in app.asar), with no setting or
env var to change it.

Possible fixes (either one works):

  1. A user-facing setting for the remote handshake timeout;
  2. A higher default value (e.g. 90 s instead of the current 10 s).
复现步骤 · Steps to reproduce
  1. Prepare a slow remote host. For easy reproduction, run a Linux x64 VM under QEMU with software emulation (TCG), i.e. WITHOUT hardware acceleration, e.g.:
    qemu-system-x86_64 -accel tcg -smp 1 -m 2G
    -drive file=linux-x64.qcow2,if=virtio
    -nic user,hostfwd=tcp::2222-:22
    This is just a convenient way to get a slow CPU — any slow or heavily loaded remote host triggers the same failure.
  2. In ZCode Desktop, open the remote connection dialog and connect to this host over SSH (fill in user / host / port in the UI).
  3. Watch the connection progress: remote components deploy successfully, then the client switches to establishing the session.
  4. About 10 seconds later the connection fails with the error message "Handshake timeout: no zcode-hello received within timeout". Retrying always gives the same result.
期望表现 · Expected behavior

The connection should succeed: the remote server does print "zcode-hello". Ideally the handshake timeout would be configurable via a user-facing setting, so slow-but-healthy remotes can connect.

实际表现 · Actual behavior

The connection always fails ~10 s after the deploy phase, before the remote server finishes loading. Remote SSH workspaces are completely unusable on such hosts.

ZCode 版本 · ZCode version

3.12.3

设备 / 系统 / 浏览器 · Device / OS / Browser

Mac Pro/ Mac OS

截图 / 录屏 / 日志 · Screenshots / Recordings / Logs
Image

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by examining the remote SSH connection and handshake entry point in the app.asar bundle, where the report identifies two copies of the hardcoded timeout. Reproduce with a slow remote host and confirm that increasing or exposing the timeout lets the server reach the zcode-hello handshake and complete the connection.

Written by the indexing model from the issue text.

Assessment

Tech stack
macos
Domain
desktop, networking
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.