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(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.ts
index 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.ts
index 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, remote
export 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 an
diff --git a/src/main/remote-ssh/remote-hooks.test.ts b/src/main/remote-ssh/remote-hooks.test.ts
index 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.ts
index 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 */
}