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
fix(ssh): fall back to a loopback TCP hook tunnel when the unix socket is unusable
Luigys Toro626627ddfc89
diff --git a/src/core/remote-ssh/control-master.test.ts b/src/core/remote-ssh/control-master.test.tsindex c1ca6a104..cd2bf788a 100644--- a/src/core/remote-ssh/control-master.test.ts+++ b/src/core/remote-ssh/control-master.test.ts@@ -28,8 +28,11 @@ import {remoteTmuxKillEverySocketArgs,hookForwardArgs,hookForwardCancelArgs,+ hookTcpForwardArgs,+ hookTcpForwardCancelArgs,remoteHookEnvArgs,remoteEndpointFileContents,+ remoteTcpEndpointFileContents,scpArgs,scpDownArgs,remoteScpPath@@ -493,6 +496,25 @@ describe('hook forwarding', () => {expect(body).toContain("NODETERM_HOOK_SOCK='/home/u/App Support/hook.sock'\n")expect(body).toContain("NODETERM_NODE_TOKEN_DIR='/home/u/App Support/node-tokens'\n")})+ it('hookTcpForwardArgs binds the host side to loopback only, and its cancel mirrors it', () => {+ expect(hookTcpForwardArgs(conn, '/s.sock', 45001, 51234)).toEqual([+ '-O', 'forward', '-R', '127.0.0.1:45001:127.0.0.1:51234',+ '-o', 'ControlPath=/s.sock', '-p', '2222', '[email protected]'+ ])+ const cancel = hookTcpForwardCancelArgs(conn, '/s.sock', 45001, 51234)+ expect(cancel.slice(0, 4)).toEqual(['-O', 'cancel', '-R', '127.0.0.1:45001:127.0.0.1:51234'])+ })+ it('hookTcpForwardArgs refuses a non-port value instead of building an ssh argument from it', () => {+ expect(() => hookTcpForwardArgs(conn, '/s.sock', 0, 51234)).toThrow()+ expect(() => hookTcpForwardArgs(conn, '/s.sock', 70000, 51234)).toThrow()+ expect(() => hookTcpForwardArgs(conn, '/s.sock', 1.5, 51234)).toThrow()+ })+ it('remoteTcpEndpointFileContents advertises the port and empties the socket', () => {+ expect(remoteTcpEndpointFileContents(45001, 'tok', '2', '/home/u/.nodeterm/node-tokens')).toBe(+ "NODETERM_HOOK_SOCK=''\nNODETERM_HOOK_PORT='45001'\nNODETERM_HOOK_TOKEN='tok'\nNODETERM_HOOK_VERSION='2'\n" ++ "NODETERM_NODE_TOKEN_DIR='/home/u/.nodeterm/node-tokens'\n"+ )+ })})describe('scpArgs', () => {diff --git a/src/core/remote-ssh/control-master.ts b/src/core/remote-ssh/control-master.tsindex 744782057..83e33aec1 100644--- a/src/core/remote-ssh/control-master.ts+++ b/src/core/remote-ssh/control-master.ts@@ -868,6 +868,27 @@ export function hookForwardArgs(conn: SshConnection, controlPath: string, remoteexport function hookForwardCancelArgs(conn: SshConnection, controlPath: string, remoteSock: string, hookPort: number): string[] {return ['-O', 'cancel', '-R', fwdSpec(remoteSock, hookPort), '-o', `ControlPath=${controlPath}`, ...portArgs(conn), target(conn)]}+/**+ * The loopback-TCP twin of `hookForwardArgs`: `-R 127.0.0.1:<remotePort>:127.0.0.1:<hookPort>`.+ *+ * Used ONLY as a fallback when the unix-socket forward binds but fails verification. Field case:+ * Tailscale SSH. `tailscaled` serves the session as root and creates the `-R` stream-local socket+ * owned by root with mode 0600, so the login user's `curl --unix-socket` can never connect and the+ * project silently runs without hooks (no status badges, no session names, no canvas control). A+ * loopback TCP listener carries no file ownership, and every generated client already speaks the+ * `NODETERM_HOOK_PORT` transport. Bound to 127.0.0.1 explicitly so it is never exposed off-host.+ */+function tcpFwdSpec(remotePort: number, hookPort: number): string {+ const okPort = (n: number): boolean => Number.isInteger(n) && n >= 1 && n <= 65535+ if (!okPort(remotePort) || !okPort(hookPort)) throw new Error('invalid forward spec')+ return `127.0.0.1:${remotePort}:127.0.0.1:${hookPort}`+}+export function hookTcpForwardArgs(conn: SshConnection, controlPath: string, remotePort: number, hookPort: number): string[] {+ return ['-O', 'forward', '-R', tcpFwdSpec(remotePort, hookPort), '-o', `ControlPath=${controlPath}`, ...portArgs(conn), target(conn)]+}+export function hookTcpForwardCancelArgs(conn: SshConnection, controlPath: string, remotePort: number, hookPort: number): string[] {+ return ['-O', 'cancel', '-R', tcpFwdSpec(remotePort, hookPort), '-o', `ControlPath=${controlPath}`, ...portArgs(conn), target(conn)]+}/*** A dev-server LOCAL forward over the existing master (`ssh -O forward -L`): this machine's* `127.0.0.1:<localPort>` → the host's `<target>:<remotePort>`. The local side binds loopback ONLY@@ -952,6 +973,25 @@ export function remoteEndpointFileContents(`NODETERM_NODE_TOKEN_DIR=${posixQuote(tokenDir)}\n`)}+/**+ * Endpoint file for the loopback-TCP fallback tunnel (`hookTcpForwardArgs`). `NODETERM_HOOK_SOCK` is+ * written EMPTY on purpose: every client tries the socket first (`[ -n "$NODETERM_HOOK_SOCK" ]`), so+ * a socket path inherited from a session env or an earlier endpoint must not shadow the port.+ */+export function remoteTcpEndpointFileContents(+ remotePort: number,+ token: string,+ version: string,+ tokenDir: string+): string {+ return (+ `NODETERM_HOOK_SOCK=''\n` ++ `NODETERM_HOOK_PORT=${posixQuote(String(remotePort))}\n` ++ `NODETERM_HOOK_TOKEN=${posixQuote(token)}\n` ++ `NODETERM_HOOK_VERSION=${posixQuote(version)}\n` ++ `NODETERM_NODE_TOKEN_DIR=${posixQuote(tokenDir)}\n`+ )+}/*** The remote PTY program is `ssh <childArgs> host -t '<remoteTmuxCommand>'`. `extraEnv` is andiff --git a/src/main/remote-ssh/remote-hooks.test.ts b/src/main/remote-ssh/remote-hooks.test.tsindex fb178ab49..1324962d6 100644--- a/src/main/remote-ssh/remote-hooks.test.ts+++ b/src/main/remote-ssh/remote-hooks.test.ts@@ -2,7 +2,13 @@ import { allRemote, ALL_REMOTE_INTEGRATION } from './remote-hooks.test-plan'import { createHash } from 'crypto'import { execFileSync } from 'child_process'import { describe, expect, it, vi } from 'vitest'-import { RemoteHooks, type RemoteIntegrationPlan, openCodeInstructionsTarget } from './remote-hooks'+import {+ RemoteHooks,+ type RemoteIntegrationPlan,+ openCodeInstructionsTarget,+ TCP_FALLBACK_PORT_MAX,+ TCP_FALLBACK_PORT_MIN+} from './remote-hooks'import { isSafeRemoteHome } from '../../core/remote-safety'import { hookServer } from '../../core/agents/hook-server'@@ -240,11 +246,52 @@ describe('RemoteHooks.setup', () => {})it('refuses to advertise a tunnel that never verifies — no endpoint file, null result', async () => {- const { rh, calls } = harness({ verifyAnswers: ['000', '000'] })+ // 2 unix-socket attempts + 3 loopback-TCP fallback attempts, all dead.+ const { rh, calls } = harness({ verifyAnswers: ['000', '000', '000', '000', '000'] })const res = await rh.setup('p1', conn, '/s.sock', { port: 51234, token: 'tok', version: '1' })expect(res).toBeNull()// The endpoint file must NOT be written: sessions would source a socket that answers nothing.expect(calls.map((c) => c.args.join(' ')).some((j) => j.includes('hook-endpoint-p1-'))).toBe(false)+ // Every TCP spec the fallback opened was cancelled again.+ const opened = calls.filter((c) => c.cmd.includes('-O forward -R 127.0.0.1:')).length+ const cancelled = calls.filter((c) => c.cmd.includes('-O cancel -R 127.0.0.1:')).length+ expect(opened).toBe(3)+ expect(cancelled).toBe(3)+ })++ // Tailscale SSH creates the `-R` stream-local socket as root, mode 0600: it binds, but the login+ // user can never connect, so the socket probe answers 000 on every attempt.+ it('falls back to a loopback TCP forward when the unix socket binds but never answers', async () => {+ const { rh, calls } = harness({ verifyAnswers: ['000', '000', '204'] })+ const res = await rh.setup('p1', conn, '/s.sock', { port: 51234, token: 'tok', version: '1' })+ expect(res).not.toBeNull()+ const tcpForward = calls.find((c) => c.cmd.includes('-O forward -R 127.0.0.1:'))+ const remotePort = Number(tcpForward?.cmd.match(/-R 127\.0\.0\.1:(\d+):127\.0\.0\.1:51234/)?.[1])+ expect(remotePort).toBeGreaterThanOrEqual(TCP_FALLBACK_PORT_MIN)+ expect(remotePort).toBeLessThanOrEqual(TCP_FALLBACK_PORT_MAX)+ // The TCP probe hits loopback on the host, bearer still on stdin only.+ const tcpProbe = calls.filter((c) => c.cmd.includes('%{http_code}')).at(-1)+ expect(tcpProbe?.cmd).toContain(`http://127.0.0.1:${remotePort}/verify`)+ expect(tcpProbe?.cmd).not.toContain('--unix-socket')+ expect(tcpProbe?.cmd).not.toContain('tok')+ // The endpoint advertises the port and explicitly empties the socket (clients try SOCK first).+ const endpoint = calls.find((c) => c.cmd.includes('hook-endpoint-p1-') && c.stdin?.includes('NODETERM_HOOK_PORT'))+ expect(endpoint?.stdin).toContain(`NODETERM_HOOK_PORT='${remotePort}'`)+ expect(endpoint?.stdin).toContain("NODETERM_HOOK_SOCK=''")+ // Liveness and teardown follow the TCP spec, not a socket path.+ const alive = await rh.tunnelAlive('p1', conn, '/s.sock', 'tok')+ expect(alive.alive).toBe(true)+ expect(calls.filter((c) => c.cmd.includes('%{http_code}')).at(-1)?.cmd).toContain(`127.0.0.1:${remotePort}/verify`)+ await rh.teardown('p1', conn, '/s.sock')+ expect(calls.at(-1)?.cmd).toContain(`-O cancel -R 127.0.0.1:${remotePort}:127.0.0.1:51234`)+ })++ it('keeps the unix socket when it verifies — no TCP forward is opened', async () => {+ const { rh, calls } = harness()+ expect(await rh.setup('p1', conn, '/s.sock', { port: 51234, token: 'tok', version: '1' })).not.toBeNull()+ expect(calls.some((c) => c.cmd.includes('-R 127.0.0.1:'))).toBe(false)+ const endpoint = calls.find((c) => c.cmd.includes('hook-endpoint-p1-') && c.stdin?.includes('NODETERM_HOOK_SOCK'))+ expect(endpoint?.stdin).not.toContain('NODETERM_HOOK_PORT')})it('does not advertise an endpoint whose atomic credential publish returns non-zero', async () => {diff --git a/src/main/remote-ssh/remote-hooks.ts b/src/main/remote-ssh/remote-hooks.tsindex d06392495..8e727fe43 100644--- a/src/main/remote-ssh/remote-hooks.ts+++ b/src/main/remote-ssh/remote-hooks.ts@@ -1,14 +1,23 @@-import { createHash, randomUUID } from 'crypto'+import { createHash, randomInt, randomUUID } from 'crypto'import { parseEndpointEnv } from '../../core/agents/hook-endpoint-parse'import { legacyEndpointMigration } from './legacy-hook-endpoint'// Connection-time remote hook setup for SSH projects: opens the reverse unix-socket tunnel-// (local loopback hook server → remote socket), writes the owner-only remote endpoint file,+// (local loopback hook server → remote socket; loopback TCP on the host as the fallback when the+// socket is unusable, e.g. Tailscale SSH), writes the owner-only remote endpoint file,// and installs the managed hook into the remote agent configs (claude + gemini JSON settings,// codex's hooks.json + config.toml trust, and grok's own file inside the host's hooks directory).// Every step fails open: any remote failure → setup returns null (or, for codex/grok, that agent// simply runs without status). Takes an INJECTED runner so the flow is unit-testable without real// ssh/electron.-import { childArgs, hookForwardArgs, hookForwardCancelArgs, remoteEndpointFileContents } from '../../core/remote-ssh/control-master'+import {+ childArgs,+ hookForwardArgs,+ hookForwardCancelArgs,+ hookTcpForwardArgs,+ hookTcpForwardCancelArgs,+ remoteEndpointFileContents,+ remoteTcpEndpointFileContents+} from '../../core/remote-ssh/control-master'import { CLAUDE_HOOK_EVENTS, GEMINI_HOOK_EVENTS, type ManagedHookEvent } from '@shared/agents/hook-events'import { GROK_EVENTS } from '../../core/agents/hooks/grok'import { GROK_HOOK_FILE, REMOTE_GROK_HOME_PROBE, resolveReportedGrokHome } from '../../core/agents/grok-paths'@@ -254,10 +263,29 @@ function describeArtifact(a: AgentToolArtifact): string {return a.kind === 'file' ? a.path : `the ${a.target} instructions file (${a.label} block)`}+/**+ * Where a project's reverse hook tunnel lands on the host. `sock` is the normal path; `tcp` is the+ * loopback fallback for hosts whose SSH server creates the stream-local socket as another user+ * (Tailscale SSH: root, mode 0600), which the login user can never connect to.+ */+export type HookTunnel = { kind: 'sock'; sock: string } | { kind: 'tcp'; remotePort: number }++/** The exact `-R` cancel for a tunnel — ssh matches a cancel against the opened spec verbatim. */+function tunnelCancelArgs(conn: SshConnection, controlPath: string, t: HookTunnel, hookPort: number): string[] {+ return t.kind === 'sock'+ ? hookForwardCancelArgs(conn, controlPath, t.sock, hookPort)+ : hookTcpForwardCancelArgs(conn, controlPath, t.remotePort, hookPort)+}++/** Remote loopback port range the TCP fallback draws from (above the usual dev-server ports). */+export const TCP_FALLBACK_PORT_MIN = 41000+export const TCP_FALLBACK_PORT_MAX = 60999+const TCP_FALLBACK_ATTEMPTS = 3+export class RemoteHooks {// Remember the absolute sock path + hook port used at setup per project so teardown cancels// the exact `-R` spec (teardown does not re-resolve $HOME).- private specs = new Map<string, { sock: string; port: number }>()+ private specs = new Map<string, { tunnel: HookTunnel; port: number }>()/** Per HOST (user, host, port, remote $HOME — several projects share one host's files): what the* last agent-tools check confirmed, and the backoff after failed ones. See agent-tools-freshness. */private agentToolsState = new Map<string, AgentToolsHostState>()@@ -315,7 +343,7 @@ export class RemoteHooks {const spec = this.specs.get(projectId)if (!spec) return { alive: false, detail: 'no forward registered for this project in this app run' }if (!token) return { alive: false, detail: 'no hook token' }- return this.probeTunnel(conn, controlPath, spec.sock, token)+ return this.probeTunnel(conn, controlPath, spec.tunnel, token)}async setup(@@ -384,15 +412,32 @@ export class RemoteHooks {await this.r.run(childArgs(conn, controlPath, `mkdir -p ${posixQuote(remoteDir)}`))const fwd = await this.r.run(hookForwardArgs(conn, controlPath, sock, hook.port))if (fwd.code !== 0) continue- verified = await this.verifyTunnel(conn, controlPath, sock, hook.token)+ verified = await this.verifyTunnel(conn, controlPath, { kind: 'sock', sock }, hook.token)}+ let tunnel: HookTunnel = { kind: 'sock', sock }if (!verified) {await this.r.run(hookForwardCancelArgs(conn, controlPath, sock, hook.port)).catch(() => {})+ // 1b. Loopback-TCP fallback. A socket that binds but never answers is not always a stale+ // forward: under Tailscale SSH the socket is created by root with mode 0600, so the login+ // user can never connect to it, however many times it is rebound. A loopback TCP listener+ // has no file owner. Same end-to-end verification bar as the socket — only this run's hook+ // server answering 204 counts — and a bind that fails (port taken) simply tries another.+ const tcp = await this.setupTcpTunnel(conn, controlPath, hook)+ if (!tcp) {+ console.warn(+ `[remote-hooks] reverse hook tunnel failed verification for ${projectId} (unix socket and loopback TCP) — remote agents run without status hooks`+ )+ return null+ }console.warn(- `[remote-hooks] reverse hook tunnel failed verification for ${projectId} — remote agents run without status hooks`+ `[remote-hooks] unix-socket hook tunnel failed verification for ${projectId}; using loopback TCP port ${tcp.remotePort} on the host instead`)- return null+ tunnel = tcp}+ const endpointContents = (): string =>+ tunnel.kind === 'sock'+ ? remoteEndpointFileContents(tunnel.sock, hook.token, hook.version, `${remoteDir}/node-tokens`)+ : remoteTcpEndpointFileContents(tunnel.remotePort, hook.token, hook.version, `${remoteDir}/node-tokens`)const previous = this.specs.get(projectId)// Read the installation-qualified file BEFORE replacing it: its prior bearer can prove// ownership after a normal app quit removed the local endpoint advertisement.@@ -405,7 +450,7 @@ export class RemoteHooks {// publish a new 0600 inode through an invocation-owned temp instead.const endpointWrite = remoteAtomicWrite(endpoint,- remoteEndpointFileContents(sock, hook.token, hook.version, `${remoteDir}/node-tokens`),+ endpointContents(),{ restrictPermissions: true, mode: '600', makeParent: false })const endpointResult = await this.r.run(@@ -413,7 +458,7 @@ export class RemoteHooks {endpointWrite.stdin)if (endpointResult.code !== 0) {- await this.r.run(hookForwardCancelArgs(conn, controlPath, sock, hook.port)).catch(() => {})+ await this.r.run(tunnelCancelArgs(conn, controlPath, tunnel, hook.port)).catch(() => {})return null}const legacy = `${remoteDir}/hook-endpoint-${projectId}.env`@@ -422,7 +467,7 @@ export class RemoteHooks {`test ! -L ${posixQuote(legacy)} && cat ${posixQuote(legacy)} 2>/dev/null`))if (old.code === 0 && old.stdout) {const migration = legacyEndpointMigration(legacy, old.stdout,- remoteEndpointFileContents(sock, hook.token, hook.version, `${remoteDir}/node-tokens`),+ endpointContents(),[hook.token, previousToken ?? '', hookServer.getPreviousEndpointToken()])const migrated = migration && await this.r.run(childArgs(conn, controlPath, migration.command), migration.stdin)if (!migrated || migrated.code !== 0) {@@ -433,9 +478,9 @@ export class RemoteHooks {} catch {console.warn('[remote-hooks] Legacy hook endpoint migration unavailable; restart affected agent sessions to adopt the new endpoint directly.')}- this.specs.set(projectId, { sock, port: hook.port })+ this.specs.set(projectId, { tunnel, port: hook.port })if (previous) {- await this.r.run(hookForwardCancelArgs(conn, controlPath, previous.sock, previous.port)).catch(() => {})+ await this.r.run(tunnelCancelArgs(conn, controlPath, previous.tunnel, previous.port)).catch(() => {})}// 3-6. Per-agent hook installs — CONCURRENT, because they are independent of each other.//@@ -1497,28 +1542,56 @@ export class RemoteHooks {private async verifyTunnel(conn: SshConnection,controlPath: string,- sock: string,+ tunnel: HookTunnel,token: string): Promise<boolean> {- return (await this.probeTunnel(conn, controlPath, sock, token)).alive+ return (await this.probeTunnel(conn, controlPath, tunnel, token)).alive+ }++ /**+ * Open + verify the loopback-TCP fallback (see `hookTcpForwardArgs`). A random port in+ * [TCP_FALLBACK_PORT_MIN, TCP_FALLBACK_PORT_MAX]; a forward the host refuses (port already bound —+ * the mux master waits for the host's answer, so a refused bind exits non-zero) just tries another.+ * Because WE hold the bind when the forward succeeds, the probe's bearer can only reach our own+ * tunnel. Returns null when no attempt verifies; every failed spec is cancelled before returning.+ */+ private async setupTcpTunnel(+ conn: SshConnection,+ controlPath: string,+ hook: { port: number; token: string }+ ): Promise<{ kind: 'tcp'; remotePort: number } | null> {+ for (let attempt = 0; attempt < TCP_FALLBACK_ATTEMPTS; attempt++) {+ const remotePort = randomInt(TCP_FALLBACK_PORT_MIN, TCP_FALLBACK_PORT_MAX + 1)+ const tunnel = { kind: 'tcp' as const, remotePort }+ const fwd = await this.r.run(hookTcpForwardArgs(conn, controlPath, remotePort, hook.port)).catch(() => null)+ if (!fwd || fwd.code !== 0) continue+ if (await this.verifyTunnel(conn, controlPath, tunnel, hook.token)) return tunnel+ await this.r.run(hookTcpForwardCancelArgs(conn, controlPath, remotePort, hook.port)).catch(() => {})+ }+ return null}/** `verifyTunnel` with the reason kept: the watchdog logs WHY a live tunnel stopped answering. */private async probeTunnel(conn: SshConnection,controlPath: string,- sock: string,+ tunnel: HookTunnel,token: string): Promise<{ alive: boolean; detail: string }> {try {+ // Same request over either transport; only the curl target differs.+ const target =+ tunnel.kind === 'sock'+ ? `--unix-socket ${posixQuote(tunnel.sock)} --config - http://localhost/verify`+ : `--config - http://127.0.0.1:${tunnel.remotePort}/verify`const cmd =- `curl -s -m 5 -o /dev/null -w '%{http_code}' -X POST --unix-socket ${posixQuote(sock)} ` ++ `curl -s -m 5 -o /dev/null -w '%{http_code}' -X POST ${target} ` +// `/verify` — the probe's OWN route, which answers 204 on the bearer alone and takes no// node identity at all. It used to POST `/hook/verify`, where it 204'd only as a side// effect of sending no payload; the identity label on `/hook/*` would have started judging// it there. `nodeId=verify` is kept in the body only so an OLDER desktop's script and this// one send the same bytes; the route reads nothing.- `--config - http://localhost/verify --data nodeId=verify`+ `--data nodeId=verify`// ONE COPY OF THE QUOTING RULE. This used to build its own `header = "…"` line, escaping `\`// and `"` and ignoring the two line breaks — a second, weaker version of the rule that// `hook-curl-config-sh.ts` states for the generated sh clients. `curlHeaderConfigLine` is@@ -1540,7 +1613,7 @@ export class RemoteHooks {this.specs.delete(projectId)if (!spec) return // nothing was set up (or already torn down)try {- await this.r.run(hookForwardCancelArgs(conn, controlPath, spec.sock, spec.port))+ await this.r.run(tunnelCancelArgs(conn, controlPath, spec.tunnel, spec.port))} catch {/* fail open */}