Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(pairing): say beside the QR that pairing needs the same network

reviewdada9ef0dfdd
diff --git a/src/renderer/components/PhonePairPopover.test.tsx b/src/renderer/components/PhonePairPopover.test.tsx
new file mode 100644
index 000000000..9740323c6
--- /dev/null
+++ b/src/renderer/components/PhonePairPopover.test.tsx
@@ -0,0 +1,68 @@
+// @vitest-environment jsdom
+//
+// The quick-pair popover says what Settings → Phone says beside the QR: pairing is a direct request
+// from the phone, so a phone on another network can only time out (a field report on 5G: "The
+// computer didn't respond.").
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { PhonePairPopover } from './PhonePairPopover'
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+vi.mock('qrcode', () => ({ toDataURL: async () => 'data:image/png;base64,QR' }))
+
+let root: Root
+let host: HTMLElement
+
+function stubBridge(start: Record<string, unknown>): void {
+ ;(window as unknown as { nodeTerminal: unknown }).nodeTerminal = {
+ pairing: {
+ start: vi.fn(async () => ({ payload: '{"v":1}', sshOpen: true, ...start })),
+ stop: vi.fn(async () => undefined),
+ onDone: vi.fn(() => () => undefined),
+ probeSsh: vi.fn(async () => true),
+ openRemoteLoginSettings: vi.fn()
+ },
+ remoteHost: { setPhoneAccess: vi.fn() },
+ shell: { openExternal: vi.fn() }
+ }
+}
+
+async function open(): Promise<string> {
+ act(() =>
+ root.render(<PhonePairPopover anchor={{ right: 100, bottom: 40 }} onClose={() => undefined} onOpenSettings={() => undefined} />)
+ )
+ await act(async () => undefined)
+ await act(async () => undefined)
+ return document.body.textContent ?? ''
+}
+
+beforeEach(() => {
+ host = document.createElement('div')
+ document.body.appendChild(host)
+ root = createRoot(host)
+})
+afterEach(() => {
+ act(() => root.unmount())
+ host.remove()
+ vi.restoreAllMocks()
+})
+
+describe('PhonePairPopover', () => {
+ it('says beside the QR that this first pairing needs the same network', async () => {
+ stubBridge({ sshKey: false, relayPlan: 'ok' })
+ expect(await open()).toMatch(/same Wi-Fi network.*connects from anywhere/)
+ })
+
+ it('promises nothing about "anywhere" on a LAN-only code', async () => {
+ stubBridge({ sshKey: true, relayPlan: 'off' })
+ const text = await open()
+ expect(text).toMatch(/same Wi-Fi network/)
+ expect(text).not.toMatch(/connects from anywhere/)
+ })
+
+ it('has no network note while the QR is withheld', async () => {
+ stubBridge({ sshKey: false, relayPlan: 'off' })
+ expect(await open()).not.toMatch(/same Wi-Fi network/)
+ })
+})
diff --git a/src/renderer/components/PhonePairPopover.tsx b/src/renderer/components/PhonePairPopover.tsx
index ee0be3edb..d1707da2e 100644
--- a/src/renderer/components/PhonePairPopover.tsx
+++ b/src/renderer/components/PhonePairPopover.tsx
@@ -8,6 +8,7 @@ import { hostOsFromNavigator, sshServerCopy } from '@shared/ssh-server'
import {
pairingEndedMessage,
pairingGate,
+ pairingNetworkHint,
relayGateMessage,
relayOnlyExplanation
} from '@shared/pairing-gate'
@@ -118,6 +119,7 @@ export function PhonePairPopover({
<>
<img src={qr} width={208} height={208} alt="Pairing QR code" className="phone-pair__qr" />
<div className="phone-pair__hint">Scan with the nodeterm mobile app · waiting (10 min)</div>
+ <div className="phone-pair__hint">{pairingNetworkHint(relayPlan === 'ok')}</div>
{!sshKey ? (
<div className="phone-pair__hint">{relayOnlyExplanation(windowsKeyFile)}</div>
) : relayPlan === 'dev' ? (
diff --git a/src/renderer/components/settings/sections/PhoneSection.tsx b/src/renderer/components/settings/sections/PhoneSection.tsx
index b71440b78..9584cac99 100644
--- a/src/renderer/components/settings/sections/PhoneSection.tsx
+++ b/src/renderer/components/settings/sections/PhoneSection.tsx
@@ -12,6 +12,7 @@ import { hostOsFromNavigator, sshServerCopy } from '@shared/ssh-server'
import {
pairingEndedMessage,
pairingGate,
+ pairingNetworkHint,
relayGateMessage,
relayOnlyExplanation
} from '@shared/pairing-gate'
@@ -280,6 +281,7 @@ export function PhoneSection({ isActive }: { isActive: boolean }): React.JSX.Ele
className="rounded-lg bg-white p-2"
/>
<p className="text-sm text-muted">Waiting for your phone… (10 min)</p>
+ <p className="text-sm text-muted">{pairingNetworkHint(relayPlan === 'ok')}</p>
{/* eneskirca/nodeterm#745: the default QR encodes the payload as raw JSON,
which the iPhone's Camera app can only show as text — there is nothing in
it to open. This switches the SAME live token to the app's URL scheme so
diff --git a/src/renderer/components/settings/sections/PhoneSection.windows.test.tsx b/src/renderer/components/settings/sections/PhoneSection.windows.test.tsx
index 8824f2670..1b969e64c 100644
--- a/src/renderer/components/settings/sections/PhoneSection.windows.test.tsx
+++ b/src/renderer/components/settings/sections/PhoneSection.windows.test.tsx
@@ -80,6 +80,23 @@ describe('PhoneSection on a relay-only (Windows) host', () => {
expect(text).toMatch(/administrators_authorized_keys/)
})
+ it('says beside the QR that this first pairing needs the same network, and only then', async () => {
+ stubBridge({ sshKey: false, relayPlan: 'ok' })
+ expect(await startPairing()).toMatch(/same Wi-Fi network.*connects from anywhere/)
+ })
+
+ it('has no network note while the QR is withheld', async () => {
+ stubBridge({ sshKey: false, relayPlan: 'off' })
+ expect(await startPairing()).not.toMatch(/same Wi-Fi network/)
+ })
+
+ it('promises nothing about "anywhere" on an SSH host pairing LAN-only', async () => {
+ stubBridge({ sshKey: true, sshOpen: true, relayPlan: 'off' })
+ const text = await startPairing()
+ expect(text).toMatch(/same Wi-Fi network/)
+ expect(text).not.toMatch(/connects from anywhere/)
+ })
+
it('does not claim a key-based connection once paired', async () => {
stubBridge({ sshKey: false, relayPlan: 'ok' })
await startPairing()
diff --git a/src/shared/pairing-gate.test.ts b/src/shared/pairing-gate.test.ts
index fd98ce602..1689f6b3e 100644
--- a/src/shared/pairing-gate.test.ts
+++ b/src/shared/pairing-gate.test.ts
@@ -1,5 +1,11 @@
import { describe, it, expect } from 'vitest'
-import { pairingEndedMessage, pairingGate, relayGateMessage, relayOnlyExplanation } from './pairing-gate'
+import {
+ pairingEndedMessage,
+ pairingGate,
+ pairingNetworkHint,
+ relayGateMessage,
+ relayOnlyExplanation
+} from './pairing-gate'
describe('pairingGate', () => {
it('gates an SSH host on sshd alone — the relay plan does not matter there', () => {
@@ -30,6 +36,19 @@ describe('copy', () => {
expect(relayOnlyExplanation(undefined)).not.toContain('administrators_authorized_keys')
})
+ it('says pairing needs the same network, and promises "anywhere" only with the relay on', () => {
+ expect(pairingNetworkHint(true)).toMatch(/same Wi-Fi network/)
+ expect(pairingNetworkHint(true)).toMatch(/connects from anywhere/)
+ expect(pairingNetworkHint(false)).toMatch(/same Wi-Fi network/)
+ expect(pairingNetworkHint(false)).not.toMatch(/anywhere/)
+ })
+
+ it('asks about the network before it blames the firewall', () => {
+ const text = pairingEndedMessage({ reason: 'timeout', reached: false, windows: true })
+ expect(text.indexOf('same Wi-Fi network')).toBeGreaterThan(-1)
+ expect(text.indexOf('same Wi-Fi network')).toBeLessThan(text.indexOf('Firewall'))
+ })
+
it('blames the firewall only for a Windows timeout that nothing reached', () => {
expect(pairingEndedMessage({ reason: 'timeout', reached: false, windows: true })).toMatch(/Firewall/)
expect(pairingEndedMessage({ reason: 'timeout', reached: true, windows: true })).not.toMatch(/Firewall/)
diff --git a/src/shared/pairing-gate.ts b/src/shared/pairing-gate.ts
index 06c28afd9..31935c21e 100644
--- a/src/shared/pairing-gate.ts
+++ b/src/shared/pairing-gate.ts
@@ -50,6 +50,18 @@ export function relayGateMessage(gate: 'relay-off' | 'relay-dev', toggle: string
: `On Windows your phone connects only through remote access. Turn on “${toggle}” and the code appears here.`
}
+/**
+ * The line beside a live QR. Pairing is one direct request from the phone to this computer's LAN
+ * address, and the relay only starts from its answer — so a phone on cellular can only time out,
+ * and neither side could say why. `remoteAccess` = this code mints a relay identity: only then is
+ * "just this once" true (a LAN-only code keeps the phone on this network for good).
+ */
+export function pairingNetworkHint(remoteAccess: boolean): string {
+ const base =
+ 'To pair, your phone has to be on the same Wi-Fi network as this computer, with any VPN turned off.'
+ return remoteAccess ? `${base} You only need this once: after pairing, it connects from anywhere.` : base
+}
+
/** Copy for a pairing that ended without pairing. `windows` = relay-only host. */
export function pairingEndedMessage(end: {
reason?: 'timeout' | 'relay-failed'
@@ -62,7 +74,7 @@ export function pairingEndedMessage(end: {
if (end.windows && end.reached === false)
return (
base +
- ' Your phone never reached this computer: if it did scan the code, Windows Defender Firewall is probably blocking nodeterm on this network — allow it for Private networks (or set this Wi-Fi to Private) and try again.'
+ ' Your phone never reached this computer: to pair, it has to be on the same Wi-Fi network. If it was, Windows Defender Firewall is probably blocking nodeterm on this network — allow it for Private networks (or set this Wi-Fi to Private) and try again.'
)
return base
}