Repository navigation
fix(desktop): name the tunnel prerequisite on the local-gateway switch - #17638
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Check that the long toggle description and the link stay readable on the narrowest Settings width the desktop app allows. The screenshots show only 1280px. [DESIGN-REVIEWED] b78b7fe Description read[DESCRIPTION-READ] 08e99de9111861a01d07f8f5f06b37aac081f82199c7ae36f49b7ae5a4369b8f That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS One thing to check: the copy says a hand-run tunnel with no saved crew gets refused. That is true on the local-start reuse path ( What this change shipsInventory (5 items) — 5 justifiedIntent: help a desktop user see, before turning off "Run a local gateway", that "off" only works if a tunnel and a saved crew already exist. FIX (refs #3810).
[FIRST-PRINCIPLES-REVIEWED] b78b7fe Description read[DESCRIPTION-READ] 844f9c9e6931a6210a0a29669c72ee2eeb6f403be6ee485c9942bcae5d7b4277 That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Opus 5.5) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS The new help text is a five-sentence paragraph, and a first-time reader couldn't work out the steps it asks for or what "so they do not count" means. Watch
Suggestions
[UX-REVIEWED] b78b7fe Description read[DESCRIPTION-READ] ff90cb07b6093018bdc6974b7202c01d70c411d97d3773a91233a1800d068b76 That sha256 names everything this verdict read: the PR description, plus the 6 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
8c78382 to
ec23bf5
Compare
|
Review dispositions for
The "Not a goal" section is frozen and still says "such an entry does not count". Read that as the Remote Crew settings page: connections there are supervised by the gateway this switch turns off. It does not cover the app-held tunnel. |
ec23bf5 to
16cfd23
Compare
|
Review dispositions for
|
16cfd23 to
0331b6d
Compare
|
Review dispositions for
Screenshots in the body were recaptured at this head. |
0331b6d to
d8bee23
Compare
d8bee23 to
b78b7fe
Compare
|
Advisory dispositions for
|
iamwhatever
left a comment
There was a problem hiding this comment.
This solves the problem in #3810. The "Run a local gateway" row now says, before the user flips it, that "off" needs a crew saved with "Set Remote Host…" plus a tunnel, and that Remote Crew connections stop when it's off. It also links the platform-neutral #ssh-tunnel-laptop guide section. The change is copy plus one link, with no change to the switch or the supervisor. The removed key's only reader moves to the new key, and i18n checks pass. The tests check the copy, the link, every catalog's quoting of the Electron labels, and that the guide anchor exists, so a rename fails CI. The UX CONCERNS about the long paragraph are advisory and answered. No binaries are committed and the screenshots are attachments.
bolichen97
left a comment
There was a problem hiding this comment.
The guide link and the tests that pin the menu label and anchor in DeveloperPanel.tsx look good. The new turn_it_off_only_when_a_gateway_already_answers text is what this PR ships, though, and its key sentence reads wrong: "Leave it on unless this app's port already reaches a crew on another machine, or the app cannot connect the next time it opens" reads as if failing to connect were a second reason to turn it off.
Please split it into a plain condition and a plain consequence, for example: "Leave this on unless this app's port already reaches a crew on another machine. If nothing answers there, the app cannot connect the next time it opens." At about 70 words it is also long for a toggle row, so trim it. Then regenerate settings-registry.generated.json, settingsRegistry.gen.ts and the locale catalogs from the new en.json text.
Problem / Motivation
Goal: A desktop user who turns off "Run a local gateway" learns, before flipping it, that "off" needs a tunnel they run themselves, and can reach the guide that sets one up.
Settings → Developer → Gateway → "Run a local gateway" says turning it off makes the app "a client only, connecting to the gateway you have configured". It never says that something must already be answering on the app's port, that the app does not open that forward, or that a Remote Crew entry does not satisfy it. The user finds out at the next launch, from the "No gateway is answering on port 5476" dialog, whose wording ("the connection that reaches it") still does not name the mechanism.
Why it matters
A user who flips the switch without a tunnel gets an app that cannot connect on its next launch. Users whose only remote access is a Remote Crew entry are hit hardest: turning the local gateway off also removes the process that supervises those tunnels.
Not a goal
remoteHosts. The help text now says plainly that such an entry does not count.fetchRemoteToken#9380).What changed (motivation → approach → change)
SettingsToggle'sdescriptioncontract), and link the guide's platform-neutral SSH-tunnel section (docs/guides/remote-and-mobile.md#ssh-tunnel-laptop), which covers a hand-run forward, the app-held tunnel for a remote crew, and leads into the LaunchAgent section updated by docs(remote): explain local gateway toggle prerequisite #4259.DeveloperPanel.tsx: the description now uses a new keyturn_it_off_only_when_a_gateway_already_answers. It says to leave the switch on unless this app's port already reaches a crew on another machine, because otherwise the app cannot connect on its next launch (which is when the setting takes effect). That needs two things: the crew saved for this port with “Set Remote Host…” in the Connection menu, and a tunnel. The tunnel is either “Keep an SSH tunnel to this crew open” (macOS and Linux) or one the user keeps running. A hand-run tunnel with no saved crew is refused as a foreign holder (gateway-supervisor.jsrefuses to adopt aforeignowner without aremoteHostsentry), so the saved crew is required either way. The text also says Settings → Remote Crew connections stop when the switch is off, so they do not count. A "How to set up an SSH tunnel" link opens the guide section in a new tab. The Electron labels are quoted in English in every locale because the Electron menus and forms are English-only.start_a_gateway_on_this_machine_turn_it_off_to_uis removed. The new description and link label are in all 11 shipped catalogs, anden-XAwas regenerated.Not covered
website/electron/gateway-wait.jsand attaching the rendered dialog.Backwards compatibility
Compatible: copy-only change. The setting, its storage and its next-launch semantics are untouched.
Removes nothing: the only thing removed is an i18n key. Its single reader (
DeveloperPanel.tsx) moves to the new key in this diff, and the i18n key-refs gate passes.Tests
website/src/test/DeveloperPanel.test.tsx› "names the tunnel prerequisite and links the guide that sets it up (Local-gateway toggle gives no hint that "off" requires an existing port forward #3810)". It asserts the prerequisite sentence, the Set Remote Host… step, the named tunnel option, the Settings → Remote Crew clause, and the link's name, href andtarget=_blank. It fails onorigin/main.website/electron/test/remote-crew-setup.test.js› "the Developer panel's local-gateway help names the tunnel option verbatim in every catalog (Local-gateway toggle gives no hint that "off" requires an existing port forward #3810)". It pins every shipped catalog toTUNNEL_OPTION_LABELand to theSet Remote Host…item read fromapp-menu.js; renaming either one fails it. › "the local-gateway guide link targets a heading that exists in the remote guide (Local-gateway toggle gives no hint that "off" requires an existing port forward #3810)": it slugs every heading indocs/guides/remote-and-mobile.mdand fails if the panel's anchor matches none. Mutating the anchor fails it (17 pass / 1 fail).npm run i18n:checkwithI18N_BASE_REF=origin/main: every gate ok.eslintis clean on every touched source and test file.Manual verification
Booted a pod from this worktree, stubbed
window.localGatewayAPIthe way the Electron preload exposes it, and checked the Gateway row in light and dark mode at 1280px. The link target#ssh-tunnel-laptopwas checked against the guide's### SSH tunnel (laptop)heading. The app-held tunnel claim was checked in source:selectLaunchPorttargets the configured remote crew's port when the switch is off,ensureManagedTunnelstarts the tunnel keeper, and the form only offers the option off Windows (offerTunnel = isLaunchPort && !IS_WINDOWS).Screenshots / video
Gateway row at the current head, light:
Dark:
Full page (dark)
Related Issues
Refs #3810. This draft covers suggestion 1 only. Suggestion 2 and the Remote Crew-only annotation stay with the owner. Related: #9380, #4259.
Pattern harvest
Not generalizable: a single missing prerequisite in one setting's copy.
Decision for the owner
The issue asks whether the local-gateway switch should only explain its tunnel prerequisite or also probe and confirm on switch-off (and annotate the Remote Crew-only case). This draft only explains it, adding the prerequisite, the saved-crew and tunnel steps, a Remote Crew caveat and a guide link to the settings row, and skips the switch-off probe because the setting applies at the next launch, so a probe now can only describe the port as it is today.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.