Skip to content

feat(remote): pair two machines over SSH, and report partial pairings - #98

Merged
teo-goulois merged 7 commits into
mainfrom
t3/pairing-over-ssh
Nov 9, 2026
Merged

teo-goulois merged 7 commits into
mainfrom
t3/pairing-over-ssh

Conversation

@teo-goulois

@teo-goulois teo-goulois commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Implements pairing over SSH (ADR 0035) and the partial results of "Pairing" in docs/remote-machines.md. The contract commits from docs/remote-cli-and-agent-pairing (up to bb7dca1) are cherry-picked first, so this PR carries the contract with the code.

What changes

Daemon

  • remote_pair_accept {machineId, account} (streaming) registers a one-shot acceptor bound to the account and the initiating machine id. Only a pairing request from that machine consumes it; any other request is declined busy. Registration follows the one-active-pairing rule and counts against the 5-per-hour limit right away, just before ready. B's 2 minutes start at registration, on the monotonic clock.
  • remote_pair {machineId, attempt?} echoes attempt on every event.
  • remote_status adds machineId and account while connected, which both sides check.
  • Partial results, on the initiator and the target, including the app and --accept: a pairing session now ends paired, cancelled or partial {local, peer}. "Nothing was saved" is said only when nothing could have been written: this side wrote no pin, and it either never sent accept: true or got the peer's accept: false. To tell when the peer saved, session protocol 3 adds pair.saved: a side sends it only once its pin is durably written, then waits up to 30 s for the peer's. Nothing else, bye done included, counts as saved.
  • A 1.7.0 peer speaks protocol 1 to 2, so it never receives pair.saved. With such a peer, a side ends as soon as it wrote its own pin, as 1.7.0 does, and reports the peer unknown with reason unconfirmed (exit 4). The app and the CLI then say to check that machine or update it, since pairing again would end the same way. pair_partial carries that reason.
  • A pairing never replaces a pin that has another key. It stops after the handshake with key_mismatch, and the pin write checks again under the pins' lock, so two pairings in flight for one machine id never overwrite each other.

CLI

  • localify machines pair --accept --for-ssh --from <id> --account <userId> (hidden flags). It refuses a terminal on stdin or stdout. Its daemon checks the account and that --from is not this machine. stdout carries only versioned JSON lines (ready, code, result) and diagnostics go to stderr. It confirms only on an exact code match, cancels on a closed stdin, a cancel line or a malformed line, and writes nothing to stdout when it fails before ready.
  • localify machines pair <B> --over-ssh <destination> [--remote-localify <path>]:
    • Runs ssh directly with exactly the contract's option set and --.
    • Refuses a destination that starts with -, plus empty values, whitespace and control characters. Each word of the remote command is quoted for a POSIX shell. --remote-localify must be one absolute path with no newline or NUL.
    • Drains stdout and stderr at the same time; B's stderr is logged with control characters stripped and never parsed.
    • Checks ready (machine id and account), starts its own pairing with the attempt, compares the codes, then confirms or cancels both sides. It keeps B's stdin open until B's result, then reaps ssh.
    • Deadlines: 30 s to ready (15 s connect plus 15 s), then 2 minutes. The helper bounds its daemon's first answer to 15 s and watches stdin while it registers.
    • A line that breaks the protocol marks B's stdout invalid for good: later lines, an earlier result included, are ignored, B is never reported pinned, and the report keeps the break as its reason (exit 2 or 4).
    • Checks ssh -V for OpenSSH 8.7 or later first (StdinNull, ForkAfterAuthentication), and fails with exit 2 and the version needed otherwise.
    • Exits 0 when paired, 2 when nothing was saved, 4 when partial. Output is human on a TTY and JSON otherwise.
  • The interactive pair and --accept show partial results.

Desktop app: handles the new partial and pair_partial events, so it no longer says "Nothing was saved" after a partial pairing. Its checks for session protocol 2 accept later versions.

Docs: the contract's Daemon table and "Partial results", the user guide (docs/README.md), and changes/pair-over-ssh.md.

Tested

Everything ran in this process against the fake relay, with temporary data directories and homes. Nothing ran against real machines, real pairings, or any machine's real remote state.

  • cargo fmt --check, cargo clippy -- -D warnings, and cargo test: lib 967, bin 1306, and all integration tests pass. tests/app_bridge.rs failed once under the full run's load and passed on three reruns; it doesn't touch pairing. --all-targets clippy shows only the existing testkit.rs findings.
  • pnpm run typecheck, node --test desktop-ui/src/lib/util.remote.test.ts, oxlint and oxfmt on the changed files.
  • The pairing gate:
    • A cut after the first confirm reports partial with each side's verified state (A not_pinned/unknown, B pinned/unknown), and pairing again completes it.
    • Accepting and then timing out, or signing out, is partial rather than "Nothing was saved". Timeouts and cancels before any confirm still pin nothing.
    • A pin with another key is never replaced.
  • Saved pins, at head 7a27036. Each of these fails on 40549d5:
    • A 1.7.0 target played by the fake relay, byte for byte on the wire. After its timeout, and after a failed pin write, its bye done leaves A pinned/unknown, unconfirmed. Everything A sent it is a type 1.7.0 knows, and A's hello range holds 2.
    • New and new: with B's pair.saved swallowed, A reports B unknown even though B's bye arrives. With it, both sides are paired.
    • A pin of another key written between the handshake and the confirms is kept, and the pairing ends key_mismatch.
    • The helper against a socket that never answers: it gives up after its wait, or at once when stdin closes, with nothing on stdout.
    • An invalid line from B, then a result claiming success, while A's daemon still waits: A reports B unknown, exit 4, with the invalid line as the reason.
  • Protocol parser: malformed, duplicate, out-of-order and foreign lines, the 4 KiB cap, and v other than 1. Control lines are exactly confirm or cancel.
  • ssh argv: the exact option string; destination refusals (-o…, -p, spaces, newline, NUL); quoting checked through a real sh with spaces, quotes, $ and backticks; NUL and newline refused.
  • Acceptor: consumed only by its machine and only once, one at a time, counted at registration, wrong account and own id refused, and its 2 minutes start at registration.
  • Helper (on OS pipes, against B's management socket):
    • Refuses a TTY, another account and its own machine, with an empty stdout.
    • Confirms only on the exact code: the same digits without the space cancel.
    • A closed stdin cancels, both before and after the code.
  • End to end: the SSH hop is replaced by a direct subprocess pipe. The test seam spawns the real localify binary (--accept --for-ssh, env_clear, temporary HOME) instead of ssh, against B's management socket.
    • Matching codes pin both sides, with A as initiator and with B as initiator.
    • Mismatched codes (B's code line altered on the way) pin nothing and exit 2.
    • A session cut after the first confirm gives partial, exit 4, B pinned and A not. Pairing again completes it.
  • The driver ends the attempt and tells B to cancel on a ready for another machine or account, and on a malformed, v: 2 or foreign line.

Notes

Merge with main (#97)

origin/main is merged in (b7c11d0), not rebased. #97 added --machine to the CLI and MCP.

  • docs/remote-machines.md: the conflicts are resolved by keeping both PRs' edits. That means feat: act on another machine's services from the CLI and MCP #97's CLI output rules and its MCP snapshot line, plus this PR's pairing over SSH exceptions for pair and for agents.
  • src/cli/machines.rs: feat: act on another machine's services from the CLI and MCP #97 changed machines() to take the management client, so the SSH pairing now passes ctx.mgmt_client.
  • Session protocol 3: the CLI and MCP code from feat: act on another machine's services from the CLI and MCP #97 (src/cli/remote/, src/cli/mcp/) never reads the session version, and the daemon's version gates already compare with >=. Nothing assumed exactly version 2, so no code changed.
  • Test: the CLI's --machine end-to-end test (daemon::remote::tests::cli) now holds a session between A and B through the fake relay. It checks that both agree on the latest protocol (3, which has pair.saved, or later) before the commands run and after the stop. Snapshot, logs, follow, a stop and a refused start then all run in that version-3 session.
  • Checked after the merge: cargo fmt --check, cargo clippy -- -D warnings, full cargo test (lib 967, bin 1342, all integration tests), pnpm run typecheck, pnpm desktop:test (63). In the first full run, tests/app_bridge.rs failed once with the same flake as above; it passed 3 times alone and in a second full run.

ADR 0035: `localify machines pair B --over-ssh <destination>` starts the
accepting side over SSH and compares both codes in Localify's own code,
so the relay-in-the-middle check holds without a person; `--for-ssh`
only answers its parent process. The MCP server still has no pairing
tool, and removing a machine stays a person's decision.
Mandatory host key trust, one quoted remote command with no shell on A,
a ready event binding B's one-shot acceptor to the expected account,
initiator and attempt, versioned JSON lines, deadlines from B's ready,
the usual limits counted on ready, and an honest partial result after
confirmations started (which every pairing can hit).
An agent a person gave SSH access to both machines can now pair them
without a person at either screen (ADR 0035):
`localify machines pair <B> --over-ssh <destination>` runs `ssh` itself
with the contract's fixed options, starts
`localify machines pair --accept --for-ssh` on B, reads both codes over
the line protocol, and confirms both sides only when they match.

The daemon gets a one-shot acceptor bound to the account and the
initiating machine id (`remote_pair_accept`), counted against the hour's
5 attempts when it is registered, with B's 2 minutes starting there.
`remote_pair` takes an `attempt` it echoes, and `remote_status` gives the
machine id and account both sides check.

A pairing cut after a `pair.confirm` used to say "Nothing was saved"
while one side could hold a pin. Each side now reports its own pin as
the disk has it and the peer's as it said (`partial`, exit 4): a side
that wrote its pin ends with `bye` `done` and waits for the peer's, and
one that accepted without saving ends with `error`. A pin with another
key is never replaced by a pairing. The app and the interactive CLI show
partial results too.
…ng over SSH

A 1.7.0 peer ends a pairing with `bye` `done` even when its pin write failed
or its 2 minutes ran out, so reading that `bye` as "saved" reported `paired`
with only one pin. Session protocol 3 adds `pair.saved`, sent only once the
pin is durably written. A 1.7.0 peer speaks 1 to 2, so it never receives it:
with such a peer, a side ends as soon as it wrote its own pin, as 1.7.0
does, and reports the peer `unknown` with reason `unconfirmed`. The app and
the CLI then say to check that machine or update it, since pairing again
would end the same way. The desktop's checks for protocol 2 now accept later
versions.

The pin write now checks the existing pin's key under the pins' lock, so two
pairings in flight for one machine id never overwrite each other's key: the
second ends with `key_mismatch`.

The `--for-ssh` helper bounds its daemon's first answer to 15 s and watches
stdin during registration, so it never blocks before `ready`. On the
initiator, a line that breaks the protocol marks B's stdout invalid for good:
later lines, an earlier `result` included, are ignored, B is never reported
pinned, and the report keeps the break as its reason.

`--over-ssh` checks `ssh -V` for OpenSSH 8.7 or later first, and fails with
exit 2 instead of letting ssh reject StdinNull and ForkAfterAuthentication.

The tests play a 1.7.0 target in the fake relay, byte for byte on the wire,
to check a timeout and a failed pin write against it, and that nothing a new
peer sends is unknown to 1.7.0.
Brings in --machine for the CLI and MCP (#97).

- docs/remote-machines.md: keeps #97's CLI output and MCP snapshot text and
  #98's pairing over SSH exceptions.
- src/cli/machines.rs: machines() now takes the management client, so the
  SSH pairing passes ctx.mgmt_client.
- The CLI's --machine end-to-end test holds a session between A and B and
  checks that both agree on the latest protocol (3, pair.saved, or later)
  for the whole run. The CLI and MCP code from #97 never checks the
  session version, so nothing else needed to change.
…re pair.saved, and exit 2 or 4 from interactive pairing

- A line B writes after its result is still checked, so a protocol break
  after a claimed success undoes it instead of being ignored.
- A pin is synced to disk, and so is its folder after the rename, before
  pair.saved says it was saved.
- `machines pair` and `pair --accept` exit 2 when nothing was saved and
  4 when only one side is known pinned, as the contract says, instead of 1.
@teo-goulois
teo-goulois merged commit 183a87f into main Nov 9, 2026
4 checks passed
@teo-goulois
teo-goulois deleted the t3/pairing-over-ssh branch November 9, 2026 22:36
@teo-goulois teo-goulois mentioned this pull request Nov 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant