Hop Doctor

When a connect fails, the terminal shows a diagnosis instead of a bare error: which hop broke, at which step, the evidence behind it, and fixes shown as the exact host fields they change.

Read the report #

The report has:

• A headline: one line naming the cause, for example permission denied for deploy (server offers: publickey); key refused instead of All configured authentication methods failed.
• A row of checks for every hop: DNS, TCP, SSH, Host key and Login, each marked as passed, failed, skipped or unknown.
• The evidence: what each check found, and what is known locally.
• Suggested fixes, each marked Likely or Check first.

The Hosts view shows the headline as a one-line hint on the host.

Where the evidence comes from #

From the attempt that failed #

The connection keeps what each hop’s attempt left behind:

• The SSH library’s error level and code.
• The bastion’s own reason for refusing a channel, such as connect failed: Connection refused or administratively prohibited.
• Every list of methods the server said it still accepts.
• What happened to each configured login method: offered and refused, or skipped and why (no agent running, key file missing, passphrase not given).

Rules turn that into about twenty failure classes. No model is involved.

From quick checks #

Hop Doctor runs inside the failed connect, while the hops in front of the broken one are still up, and is capped at 3 seconds. It may:

• Look the name up on this computer.
• Make a bare TCP connect to a first hop.
• Read the greeting of the target port through the bastion, when the tunnel opened but SSH never started.
• Run a read-only getent hosts (dscacheutil on macOS) on the bastion, when the bastion could not resolve the name.
• When a first hop’s name does not resolve on this computer, ask up to two bastions you already have open whether they can. Only bastions related to the host (in front of hosts in its group or its domain) are asked, so a bastion that serves another customer never hears the name. If one can resolve it, it is offered as a jump host.

Only the configured target and port are ever probed, once, and every remote check is written to the audit log.

From what is known locally #

• The host’s last successful login, with the account and method, from the audit log.
• The matching alias in ~/.ssh/config, read without running Match exec.
• The agent’s keys, from ssh-add -l. With Pageant on Windows the keys cannot be listed, and the report says so rather than calling the agent empty.
• The key file’s type.

It never logs in again #

Every login attempt counts towards the server’s MaxAuthTries and towards fail2ban. Hop Doctor reads the evidence of the attempt that already happened and never authenticates again. Retrying is your click.

Apply a fix #

Fixes are typed and limited to five host fields:

Each fix is shown as a before → after diff. Some come with an ssh-add command to copy instead, when the answer is to load a key into your agent.

1. Read the fix and its reason.
2. Click Apply & retry.

The patch is checked again when you apply it. It is refused if the host was edited since the report, and it never touches any other field.

• Likely: the rules are confident.
• Check first: the fix was read from your ssh config. The report says when that config uses Include, Match or other directives the check does not follow.

A changed host key gets both fingerprints and an explanation, and never a trust button. See Host keys.

Timeouts #

A hop gets 25 seconds from its TCP connect to a finished login. The clock stops while a host key or password prompt is on screen, so checking a fingerprint with an administrator never reads as a declined key. A server that goes quiet part-way through the login is named as a timeout, not as a refusal. Closing the tab while it is still connecting stops the dial at once.

Explain #

With Pro and the assistant on, Explain streams two or three plain sentences about the report, labelled as a reading of the checks.

• The model sees the report only, with secrets masked.
• When the prompt leaves this computer, every host name (your other saved hosts too), address, user and key path is replaced by a placeholder and swapped back only in what you read. The server’s greeting and SSH ident, ssh config lines, key files, host keys and last-login times stay behind; a sentence that would quote them names them instead, such as From your ssh config.
• It cannot add a fix. It is told to name only the fixes the rules found, and any code or command line in its reply is dropped.