Skip to content

fix(desktop): name the tunnel prerequisite on the local-gateway switch - #17638

Merged
iamwhatever merged 1 commit into
mainfrom
fix/local-gateway-prereq-hint-3810
Oct 7, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/local-gateway-prereq-hint-3810

Conversation

@buluoray

@buluoray buluoray commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

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

What changed (motivation → approach → change)

  • Symptom: the switch's "off" position has a prerequisite that nothing on screen mentions.
  • Approach: put the prerequisite in the row's description, because it is needed to make the choice (SettingsToggle's description contract), 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.
  • Change:
    1. DeveloperPanel.tsx: the description now uses a new key turn_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.js refuses to adopt a foreign owner without a remoteHosts entry), 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.
    2. The old key start_a_gateway_on_this_machine_turn_it_off_to_u is removed. The new description and link label are in all 11 shipped catalogs, and en-XA was regenerated.

Not covered

  • Issue suggestion 3, the Electron "No gateway is answering" dialog wording, was in an earlier head of this draft and was taken out on the conductor's ruling. That dialog cannot be rendered or screenshotted from this Linux host, and the UX lane requires a screenshot. Follow-up: a separate change from a macOS or Windows machine, rewording "(or the connection that reaches it)" in website/electron/gateway-wait.js and 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

Manual verification

Booted a pod from this worktree, stubbed window.localGatewayAPI the way the Electron preload exposes it, and checked the Gateway row in light and dark mode at 1280px. The link target #ssh-tunnel-laptop was checked against the guide's ### SSH tunnel (laptop) heading. The app-held tunnel claim was checked in source: selectLaunchPort targets the configured remote crew's port when the switch is off, ensureManagedTunnel starts 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:

Gateway row, light

Dark:

Gateway row, dark

Full page (dark)

Settings Developer 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 7, 2026
@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of b78b7fe776fc12706be15df5aca3e269a85ec57a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of b78b7fe776fc12706be15df5aca3e269a85ec57a — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 (gateway-supervisor.js:1017). Confirm it also holds in client-only mode.

What this change ships

Inventory (5 items) — 5 justified

Intent: 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).

  1. The "Run a local gateway" description now names the off-state prerequisite (a crew saved via Set Remote Host… plus a tunnel). It also says Remote Crew connections stop when the switch is off. — justified
  2. A "How to set up an SSH tunnel" link under the toggle opens the remote guide's SSH-tunnel section in a new tab. It follows the panel's existing ExternalLink pattern (DeveloperPanel.tsx:67,100) and the same guide-constant pattern as SecretsPanel.tsx:9. — justified
  3. The description no longer includes the {{productName}} interpolation. — justified
  4. The old i18n key is replaced by a new one across all 11 catalogs and en-XA, and the generated settings-search registry entry is updated to match. — justified
  5. Tests now pin the quoted Electron labels in every catalog and pin the guide anchor to a real heading. — justified

[FIRST-PRINCIPLES-REVIEWED] b78b7fe

Description read

[DESCRIPTION-READ] 844f9c9e6931a6210a0a29669c72ee2eeb6f403be6ee485c9942bcae5d7b4277

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — 🟡 CONCERNS

UX-level review of b78b7fe776fc12706be15df5aca3e269a85ec57a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • The prerequisite is buried in a wall of text. The diff replaces a three-sentence description with one long run-on paragraph (shot-01). It mixes a warning ("or the app cannot connect the next time it opens"), two setup steps ("Set Remote Host…" and the tunnel), a note on which systems support the tunnel option and a caveat. The blind reader understood it was an explanation but said: "I have no idea what it actually tells me to do." The text sends the reader to two other places, neither visible from this row. A user deciding whether it's safe to turn the switch off has to pick the steps out of prose. That defeats the PR's goal of making the prerequisite clear before the flip. Severity: moderate. The row isn't visited often, but the cost of getting it wrong is an app that can't connect at the next launch.
  • "so they do not count" is ambiguous. The reader said: "I can't tell what doesn't count, or count toward what." This clause carries the caveat for Remote Crew-only users, who the PR says are hit hardest. Severity: moderate, because it fails exactly the users the caveat is written for.

Suggestions

  • Split the turn_it_off_only_when_a_gateway_already_answers text into three parts:
    • a one-line description: "Leave on unless another machine's crew already answers on this app's port. Takes effect next launch."
    • a short list headed "Before turning off:" with "1. Save the crew with Set Remote Host… (Connection menu)" and "2. Tick 'Keep an SSH tunnel to this crew open', or run your own tunnel."
  • Replace "Settings → Remote Crew connections stop when this is off, so they do not count" with "Remote Crew connections stop when this is off, so they can't stand in for the tunnel."

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of b78b7fe776fc12706be15df5aca3e269a85ec57a and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b78b7fe

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b78b7fe776fc12706be15df5aca3e269a85ec57a: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed b78b7fe776fc12706be15df5aca3e269a85ec57a — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] b78b7fe

Verdict parsed from the review's SHA-scoped output markers for commit b78b7fe776fc12706be15df5aca3e269a85ec57a.

False positive or not applicable? A repository writer can comment:
/ai-review override fable b78b7fe776fc12706be15df5aca3e269a85ec57a: <one-sentence reason>

@buluoray
buluoray force-pushed the fix/local-gateway-prereq-hint-3810 branch from 8c78382 to ec23bf5 Compare October 7, 2026 08:12
@buluoray

buluoray commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

Review dispositions for 8c783823e5 (fixed in ec23bf5f4c):

  1. Guide link opens a macOS-only section (Design, First Principles, UX, Opus): fixed. The link now points to #ssh-tunnel-laptop. That section covers macOS, Linux and Windows, describes the app-held tunnel, and leads into the LaunchAgent section.
  2. "A Remote Crew entry does not count" is wrong for a crew saved with "Keep an SSH tunnel to this crew open" (Opus): fixed. I confirmed it in source. With the switch off, selectLaunchPort (website/electron/host-config.js) targets the configured crew's port. ensureManagedTunnel (gateway-supervisor.js) then starts the tunnel keeper, which requires manageTunnel === true. The form offers that option only when not on Windows. The description now names both routes: a tunnel you run yourself, or one the app keeps open for you (macOS and Linux). It also says connections on the Remote Crew settings page do not count, because the local gateway supervises those. The text is updated in all 11 catalogs and en-XA, and the test asserts both clauses and the new href.
  3. UX: the description is dense, and a user cannot check whether they already have a tunnel. Acknowledged, not changed. The rewrite reduces it to one condition plus two examples. A live "is something answering on this port" readout is the switch-off probe that this draft leaves to the owner (see "Decision for the owner"). Adding it here would decide that question.

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.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 7, 2026
@buluoray
buluoray force-pushed the fix/local-gateway-prereq-hint-3810 branch from ec23bf5 to 16cfd23 Compare October 7, 2026 08:34
@buluoray

buluoray commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

Review dispositions for ec23bf5f4c (fixed in 16cfd230ac):

  1. UX BLOCK, evidence gap: the screenshots showed copy that no longer ships. Fixed. The light and dark crops of the Gateway row were recaptured at the current head and are in the PR body.
  2. UX and Design: the description says Remote Crew connections do not count but never says where the app-held tunnel is set up. Fixed. The description now names the option: "the app's own tunnel, turned on with “Keep an SSH tunnel to this crew open” when you add a remote crew from the desktop app's connection dialog (macOS and Linux)". It also says "Connections on the Settings → Remote Crew page do not count", which uses the sidebar name. The label is quoted in English in every locale because the Electron form is English-only. A new test pins all 11 catalogs to TUNNEL_OPTION_LABEL, and mutating the constant makes it fail.
  3. UX suggestion to rename the link to "How to set up an SSH tunnel": taken, in all 11 locales.
  4. UX, carried over: the blind reader would still not turn the switch off. Acknowledged. For a user without a tunnel, that hesitation is what this PR is meant to produce.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 7, 2026
@buluoray
buluoray force-pushed the fix/local-gateway-prereq-hint-3810 branch from 16cfd23 to 0331b6d Compare October 7, 2026 08:55
@buluoray

buluoray commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

Review dispositions for 16cfd230ac (fixed in 0331b6d4ae):

  1. Opus: a hand-run tunnel alone is refused. Confirmed in source and fixed. resolveGatewayConflict returns foreign-holder when the port owner is foreign and no remoteHosts entry exists. The comment there explains why: posting this machine's .local_secret to an unattributed tunnel would leak it. So the copy now says both routes need the crew saved for this port with "Set Remote Host…" in the Connection menu, and that a tunnel is needed on top of that. The tunnel is either "Keep an SSH tunnel to this crew open" (macOS and Linux) or one you keep running yourself.
    • The disabled-state dialog sentence I changed is left as it is. It already ends with "If your crew runs on another machine, choose Add Remote Crew to name it". A Retry without a saved crew lands on the foreign-holder message, which also names Add Remote Crew.
  2. UX: why Remote Crew connections "do not count". Fixed. The copy now gives the reason: "Settings → Remote Crew connections stop when this is off, so they do not count."
  3. UX: lead with the consequence. Taken. The copy now opens with: "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."
  4. UX: break the copy into bullets. Declined. SettingsToggle.description renders a single line of text, and changing that component is out of scope here. Leading with the consequence covers what bullets would have done.
  5. UX: no screenshot of the Electron dialog. Not possible here. This Linux host cannot run the Electron shell, so the PR body lists it as unverified. The change is one phrase and is covered by gateway-wait.test.js.
  6. Design: nothing pinned #ssh-tunnel-laptop. Fixed. A new test slugs the guide's headings and fails if the anchor matches none; mutating the anchor makes it fail. The menu label is also now pinned against app-menu.js.

Screenshots in the body were recaptured at this head.

@buluoray
buluoray force-pushed the fix/local-gateway-prereq-hint-3810 branch from 0331b6d to d8bee23 Compare October 7, 2026 09:29
@buluoray
buluoray force-pushed the fix/local-gateway-prereq-hint-3810 branch from d8bee23 to b78b7fe Compare October 7, 2026 09:41
@buluoray

buluoray commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

Advisory dispositions for b78b7fe776. Under the fleet's current rate-limit rules, advisory findings get a comment only, so nothing here is pushed.

  • First Principles: does the hand-run-tunnel refusal also apply in client-only mode? Yes, from reading the source. The refusal at gateway-supervisor.js:1017 (decision.action === "reuse" && localOwner === "foreign" && !remoteHost → "foreign-holder") does not depend on runLocalGateway. That flag only gates the bundledGateway stale-bundle probe at line 988. startGateway reaches resolveGatewayConflict through adoptOrSpawn in both modes (ensureManagedTunnel().then(checkBackend).then(adoptOrSpawn, …), line 1220). The existing win32 never prompts for a foreign listener test pins the refusal on the shared path, though only with the local gateway on; I have not added a client-only case.
  • Design: readability at the narrowest Settings width. Not measured. The screenshots are at 1280px only. The description reuses SettingsToggle's existing wrapping text-[12px] block and the link is a single inline element, so nothing new can overflow.
  • UX: the copy is still one dense paragraph. Acknowledged, not changed in this draft. A short line followed by a bulleted list would need either a change to SettingsToggle or a second element under the row. That is a layout decision for the owner, alongside the switch-off probe.

@buluoray
buluoray marked this pull request as ready for review October 7, 2026 18:20
@buluoray
buluoray requested a review from a team as a code owner October 7, 2026 18:20
@buluoray
buluoray requested a review from iamwhatever October 7, 2026 18:20
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 7, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@iamwhatever
iamwhatever enabled auto-merge (squash) October 7, 2026 22:15
@iamwhatever
iamwhatever merged commit 835f26d into main Oct 7, 2026
105 checks passed
@iamwhatever
iamwhatever deleted the fix/local-gateway-prereq-hint-3810 branch October 7, 2026 22:17

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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.

3 participants