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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { useEffect, useRef, useState } from 'react'
import { toDataURL } from 'qrcode'
import { DEFAULT_PAIR_QR_FORM, encodePairQr, type PairQrForm } from '@shared/pair-qr'
import type { WindowsKeyFileHint } from '@shared/pairing-gate'
export type PairingPhase = 'idle' | 'waiting' | 'paired' | 'timeout'
/** How often the Remote Login warning re-probes sshd while it is showing. */
const SSH_RECHECK_MS = 2000
/**
* The phone-pairing state machine, shared by Settings → Phone and the quick-pair popover:
* start/stop, the QR data URL, the completion event, and the live Remote-Login (sshd) re-probe
* while the warning is visible. Any in-flight pairing is stopped when the OWNING view unmounts —
* both hosts are transient surfaces, and a headless listener would silently pair whoever scans a
* QR that is no longer on screen.
*/
export function usePhonePairing(onPaired?: () => void): {
phase: PairingPhase
qr: string
/** Which envelope the QR on screen encodes. Switching it re-renders the SAME live token —
* it never restarts pairing (eneskirca/nodeterm#745). */
qrForm: PairQrForm
setQrForm: (form: PairQrForm) => void
sshOpen: boolean
sshHealed: boolean
/** false = relay-only host (Windows) — see `pairingGate`. Kept after the pairing ends, so the
* ended/paired copy can still tell which kind of host this is. */
sshKey: boolean
windowsKeyFile: WindowsKeyFileHint | undefined
/** On phase 'timeout': why it ended and whether the phone ever reached the listener. */
ended: { reason?: 'timeout' | 'relay-failed'; reached?: boolean } | null
/** On phase 'paired': whether the pairing came with a relay leg ('off' = toggle disabled,
* 'failed' = mint failed → LAN-only). Surfaced so the silent degrade is visible at the one
* moment the user is looking. */
relayResult: 'ok' | 'off' | 'failed' | 'dev' | null
/** While 'waiting': what the QR on screen WILL mint — lets the surfaces warn beside the QR
* (esp. 'dev': unpackaged build, relay off regardless of the toggle). */
relayPlan: 'ok' | 'dev' | 'off' | null
error: string
busy: boolean
start: () => Promise<void>
stop: () => void
reset: () => void
} {
const [phase, setPhase] = useState<PairingPhase>('idle')
const [qr, setQr] = useState('')
// The built payload JSON, kept so the QR can be re-encoded in the other envelope without
// minting a new token — the listener on the other end is keyed to THIS one.
const [payload, setPayload] = useState('')
const [qrForm, setQrForm] = useState<PairQrForm>(DEFAULT_PAIR_QR_FORM)
const [sshOpen, setSshOpen] = useState(true)
// Went from unreachable → reachable while the warning was showing: show a green confirmation
// instead of silently dropping the warning (the user just flipped a toggle; acknowledge it).
const [sshHealed, setSshHealed] = useState(false)
const [sshKey, setSshKey] = useState(true)
const [windowsKeyFile, setWindowsKeyFile] = useState<WindowsKeyFileHint | undefined>(undefined)
const [ended, setEnded] = useState<{ reason?: 'timeout' | 'relay-failed'; reached?: boolean } | null>(null)
const [relayResult, setRelayResult] = useState<'ok' | 'off' | 'failed' | 'dev' | null>(null)
const [relayPlan, setRelayPlan] = useState<'ok' | 'dev' | 'off' | null>(null)
const [error, setError] = useState('')
const [busy, setBusy] = useState(false)
// Track whether a pairing listener is currently running so unmount can stop it.
const runningRef = useRef(false)
// Live re-check while the Remote Login warning is visible: the initial probe runs once at
// pairing start, so without this the warning could never clear — the user enables Remote Login
// in System Settings and nothing changes on screen. Poll only in that exact state (waiting +
// unreachable); the interval dies with the warning.
useEffect(() => {
// A relay-only host never shows the sshd warning, so there is nothing to re-probe for.
if (phase !== 'waiting' || sshOpen || !sshKey) return
let cancelled = false
const timer = setInterval(() => {
void window.nodeTerminal.pairing
.probeSsh()
.then((open) => {
if (!cancelled && open) {
setSshOpen(true)
setSshHealed(true)
}
})
.catch(() => {
// transient probe error: keep the warning, try again on the next tick
})
}, SSH_RECHECK_MS)
return () => {
cancelled = true
clearInterval(timer)
}
}, [phase, sshOpen, sshKey])
const start = async (): Promise<void> => {
setError('')
setBusy(true)
try {
const {
payload: built,
sshOpen: open,
relayPlan: plan,
sshKey: key,
windowsKeyFile: keyFile
} = await window.nodeTerminal.pairing.start()
setRelayPlan(plan ?? null)
setSshKey(key !== false)
setWindowsKeyFile(keyFile)
setEnded(null)
// The image itself is rendered by the effect below, which also handles a later switch
// between the JSON and URL envelopes.
setPayload(built)
setSshOpen(open)
setSshHealed(false)
setRelayResult(null)
setPhase('waiting')
runningRef.current = true
} catch (err) {
setError((err as Error).message)
} finally {
setBusy(false)
}
}
// Render the QR for whatever payload + envelope is current. Re-runs when the user switches
// envelope, which is deliberately NOT a restart: same token, same listener, different
// encoding of the same bytes.
useEffect(() => {
if (!payload) {
setQr('')
return
}
let cancelled = false
void toDataURL(encodePairQr(payload, qrForm), { margin: 1, width: 240 })
.then((dataUrl) => {
if (!cancelled) setQr(dataUrl)
})
.catch(() => {
// Keep whatever image is already up; the pairing listener is unaffected by a render
// failure, and a blank QR with no explanation is the failure mode #745 was about.
})
return () => {
cancelled = true
}
}, [payload, qrForm])
const stop = (): void => {
if (runningRef.current) {
runningRef.current = false
void window.nodeTerminal.pairing.stop()
}
setPhase('idle')
setPayload('')
setQr('')
}
// Subscribe to the completion event; drives paired/timeout state. `onPaired` rides a ref so
// a re-rendered callback never resubscribes the event.
const onPairedRef = useRef(onPaired)
onPairedRef.current = onPaired
useEffect(() => {
return window.nodeTerminal.pairing.onDone((result) => {
runningRef.current = false
setPayload('')
setQr('')
setPhase(result.ok ? 'paired' : 'timeout')
setRelayResult(result.ok ? (result.relay ?? null) : null)
setEnded(result.ok ? null : { reason: result.reason, reached: result.reached })
if (result.ok) onPairedRef.current?.()
})
}, [])
// Stop any in-flight pairing when the owning view unmounts (closed / navigated away).
useEffect(() => {
return () => {
if (runningRef.current) {
runningRef.current = false
void window.nodeTerminal.pairing.stop()
}
}
}, [])
return {
phase,
qr,
qrForm,
setQrForm,
sshOpen,
sshHealed,
sshKey,
windowsKeyFile,
ended,
relayResult,
relayPlan,
error,
busy,
start,
stop,
reset: () => setPhase('idle')
}
}