Public: anyone can read this; the crew can change it.
The SSH terminal survives a release swap without dropping the owner #13270
Check · Review · Land · Live done — Landed and live in production.
A release swap now takes the SSH terminal with it. A process that holds the SSH listener no longer refuses the swap. Where the OpenSSH client isn't installed, the terminal check is skipped and named, and the forge's check runs it on every push.
shipped production is serving it deploy 59903fa
3 earlier comments
A release swap now takes the SSH terminal with it. A process that holds the SSH listener no longer refuses the swap. Where the OpenSSH client isn't installed, the terminal check is skipped and named, and the forge's check runs it on every push.
What changed
- Port sharing: under
FORGE_SELF_SWAP=1,serveSshbinds the SSH port with SO_REUSEPORT (newreusePortoption, set insrc/tui/ssh.ts). This is the same way the web port already works, so the release binds the port next to the old process. - Handover:
handover.draininsrc/main.tsnow calls a newSshServer.handOver()before the web handover. The old process stops taking SSH connections at once, so every new one goes to the release and none are refused. That meets the "at most one second" goal, providedtcp_migrate_req=1, which the swap already requires. - Connected sessions: a terminal on the old process is shown
the forge is updating, reconnectingon its screen and in the disconnect message, then closed. A connection still logging in is closed the same way. A running push or clone is left to finish within the normal drain. - Swap refusal:
swapBlocked()insrc/release/swap.tsno longer refuses because SSH is held, and thehandover.sshflag is gone.docs/REFERENCE.mdis updated, including the rollback paragraph.
Tests
- New,
test/ssh-handover.test.ts:
- Two servers share one port. After handOver(), 20 raw TCP connections all get the release's version line: none refused, none left on the old process. It runs without OpenSSH, so it ran here too.
- A connection still logging in on the old process is let go at the handover.
- A real ssh -tt session prints the handover sentence and ends. This one needs OpenSSH and was skipped here.
- Removed: the tests that asserted the old SSH refusal, in
release-swap,capacity-selfswapandtui-capacity. They tested behaviour that is now gone, so the tests were wrong rather than the code. - Changed: the keeper test "cannot swap, cuts nothing" now uses the other remaining blocker,
tcp_migrate_req=0.
Left out
- The session doesn't reconnect by itself. OpenSSH has no way to follow a server redirect, so it takes the issue's alternative and ends with the sentence.
--rollbackdoesn't hand over SSH. It still doesn't drain the old process, so until an operator stops the old process, new SSH connections go to either one.
Checks
bun scripts/gate.ts --fixandbun x tsc --noEmitpass.- The SSH, swap and capacity test files pass apart from the skips.
- One failure:
test/ssh-port-taken.test.ts"main.ts keeps serving / when the SSH port is taken" fails the same way on the base branch. It starts a fullmain.tsand hits its 5 s timeout here.
Try it: run the forge with FORGE_SELF_SWAP=1 and connect with ssh. When a release lands, the terminal prints the forge is updating, reconnecting and closes. Running ssh again connects to the release.
🤖 Generated with Claude Code
The SSH port is now shared during a release swap, so a new connection always lands on the release and is never refused. When the swap happens, a terminal still open on the old process prints "the forge is updating, reconnecting" before it closes, and running ssh again reaches the release.
- The swap: both processes bind the SSH port with SO_REUSEPORT. The old one's
handOverstops accepting at once and lets go of any connection still logging in. - The latest push fixes only
test/ssh-handover.test.ts, which the gate rejected for waiting on real timers:
- I removed the three timeouts that only capped a wait for a version line, a closed socket or an opened session. bun's per-test timeout already catches a server that never answers, so the test now waits on the event itself.
- The one loop that checks every 10 ms for a real TCP connection to arrive keeps its Bun.sleep(10), marked // real-timer: with the reason. A fake clock can't speed up a real network accept.
bun scripts/gate.ts --fix and bun x tsc --noEmit pass. In test/ssh-handover.test.ts, the two port tests pass and the terminal test was skipped by name because this sandbox has no /usr/bin/ssh or ssh-keygen. That test, the one that checks the sentence a terminal prints, runs only in the forge's check.
To try it: run the forge with FORGE_SELF_SWAP=1, connect with ssh and land a release. The terminal prints the sentence, and ssh again reaches the release.
🤖 Generated with Claude Code
Still red on current main: test/ssh-handover.test.ts:97: for (let i = 0; i < 200 && old.sessions() === 0; i++) await Bun.sleep(10); // real-timer: a real TCP accept lands on its own clock. Fix it and push.
When a release lands, the SSH terminal now survives it. The new release binds the same port beside the old process, and once the old one calls handOver() every new connection goes to the release. A connection still logging in on the old process is closed, and an open terminal there sees "the forge is updating, reconnecting" before it ends. Reconnecting with ssh reaches the release.
Fix for the red check: the flake gate's fall-through detector (fallThroughWaits in scripts/flake.ts) flagged the accept poll at test/ssh-handover.test.ts:97. The comment at the end of that line stopped the detector from seeing where the loop ended, so it missed the expect(old.sessions()).toBe(1) on the next line. Moving the comment above the loop doesn't work either: the review rule in src/kernel/review_rules.ts wants // real-timer: on the same line as the sleep. The loop is now in braces with the comment on the sleep line, which satisfies both rules. Only the test's layout changed, not what it checks.
bun scripts/gate.ts --fix and bun x tsc --noEmit are clean, and running the detector on the file finds nothing. bun test test/ssh-handover.test.ts test/flake.test.ts passes with one skip: the case driving a real ssh client is skipped in this sandbox, and the forge's check runs it.
To try it: run the forge with FORGE_SELF_SWAP=1, connect with ssh and land a release. The terminal prints "the forge is updating, reconnecting", and ssh again reaches the release.
🤖 Generated with Claude Code
Approved. The SSH listener is bound with SO_REUSEPORT under FORGE_SELF_SWAP, the old process stops accepting at handover, and terminals get the sentence on screen and in the disconnect. Running push/clone connections are left to the drain. The swap refusal and the handover.ssh flag are gone, and the tests that asserted them went with them. There is no UI surface, so I found no phone, keyboard or JavaScript-off issue.
Two things I would do next:
- Keep a release that is not healthy from taking SSH connections. Because the release binds the SSH port beside the old process before the health read, connections split between them until a failed release is killed. Bind SSH only after health passes, or have the release hold its listener until told to take over. Also cover the
--rollbackpath, where the old process is never told to hand over. - Tidy the diff. test/capacity-selfswap.test.ts is left with a double blank line. The gate rewrap touched unrelated comments in release-keeper-swap.test.ts and the endSwap doc in swap.ts. Reverting those would keep the pull single-purpose.
The real-ssh test skips only when OpenSSH is missing, not under FORGE_TEST_SOCKET. The raw-TCP port test runs everywhere, so the handover itself is proven in both modes.
A release swap now takes the SSH terminal with it. A process that holds the SSH listener no longer refuses the swap. Where the OpenSSH client isn't installed, the terminal check is skipped and named, and the forge's check runs it on every push.
What changed
FORGE_SELF_SWAP=1,serveSshbinds the SSH port with SO_REUSEPORT (newreusePortoption, set insrc/tui/ssh.ts). This is the same way the web port already works, so the release binds the port next to the old process.handover.draininsrc/main.tsnow calls a newSshServer.handOver()before the web handover. The old process stops taking SSH connections at once, so every new one goes to the release and none are refused. That meets the "at most one second" goal, providedtcp_migrate_req=1, which the swap already requires.the forge is updating, reconnectingon its screen and in the disconnect message, then closed. A connection still logging in is closed the same way. A running push or clone is left to finish within the normal drain.swapBlocked()insrc/release/swap.tsno longer refuses because SSH is held, and thehandover.sshflag is gone.docs/REFERENCE.mdis updated, including the rollback paragraph.Tests
test/ssh-handover.test.ts:- Two servers share one port. After
handOver(), 20 raw TCP connections all get the release's version line: none refused, none left on the old process. It runs without OpenSSH, so it ran here too. - A connection still logging in on the old process is let go at the handover. - A realssh -ttsession prints the handover sentence and ends. This one needs OpenSSH and was skipped here.release-swap,capacity-selfswapandtui-capacity. They tested behaviour that is now gone, so the tests were wrong rather than the code.tcp_migrate_req=0.Left out
--rollbackdoesn't hand over SSH. It still doesn't drain the old process, so until an operator stops the old process, new SSH connections go to either one.Checks
bun scripts/gate.ts --fixandbun x tsc --noEmitpass.test/ssh-port-taken.test.ts"main.ts keeps serving / when the SSH port is taken" fails the same way on the base branch. It starts a fullmain.tsand hits its 5 s timeout here.Try it: run the forge with
FORGE_SELF_SWAP=1and connect withssh. When a release lands, the terminal printsthe forge is updating, reconnectingand closes. Runningsshagain connects to the release.🤖 Generated with Claude Code
Closes #13260