Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

harnessd: the gateway's process runs once this machine is signed in, has anything paired, or needs it (#972)

Dee93ed970ed071
diff --git a/cli/AGENTS.md b/cli/AGENTS.md
index f87596be4..d422da186 100644
--- a/cli/AGENTS.md
+++ b/cli/AGENTS.md
@@ -28,7 +28,7 @@ they show as `harnessd`, `harnessd-core` and `harnessd-<process>` (`src/harnessd
| search | session search | always |
| viewers | the harness viewers, their remote streams and rendered surfaces, and the Store | always |
| edge | workspaces, usage, the monitor, the project readers, the change-agent handoff, the recaps | always |
-| gateway | the relay and its E2EE (`src/gateway/`) | always |
+| gateway | the relay and its E2EE (`src/gateway/`) | on demand: as the core starts when signed in or anything is paired here, or when something needs it (a pairing, a window's E2EE request, a key command, the Wi-Fi device) |
| models | grid, local models, the Model Manager | on demand: once grid is in use here (a managed grid, saved grid pictures, local models), or on a models request |
| updater | checks, downloads and stages a new build (`src/services/updaterProcess.ts`) | by the master, for the installed copy only |
| devices | the dials, the window bridges, the fleet, the voice router, the Wi-Fi device | on demand: once there is a device |
diff --git a/cli/e2e/gatewayOnDemand.e2e.ts b/cli/e2e/gatewayOnDemand.e2e.ts
new file mode 100644
index 000000000..f0cc9eb0d
--- /dev/null
+++ b/cli/e2e/gatewayOnDemand.e2e.ts
@@ -0,0 +1,152 @@
+/**
+ * The gateway's process on demand (core/gatewayWake.ts, core/gatewayLink.ts, harnessd/services.ts `gateway`), on
+ * the real daemon: a computer signed out with nothing paired runs no gateway, about 75 MiB it never pays, since
+ * it would dial nothing and nothing could reach it; the first thing that needs it starts it.
+ * - Signed out, nothing paired: no process, and `/api/status` is answered without it.
+ * - A window's E2EE request and a key command: the first starts it, waits for it and is answered by it; killed, it
+ * comes back.
+ * - Something paired here: asked for as the core starts, signed out too.
+ * - Signed in: asked for as the core starts, before it binds, so the relay comes up beside it and a phone reaches
+ * the machine as it did when the gateway started with every other process.
+ * - Named in `HARNESSD_SERVICES` (tests, support), it starts with the daemon, as before.
+ * A core too old to ask has it started as it binds: e2e/reexec.e2e.ts, under a released core.
+ */
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, onTestFailed } from 'vitest'
+import { b64e, newIdentity } from '../src/lib/e2ee/core.js'
+import { LocalClient, type Frame } from './harness/client.js'
+import { IsolatedDaemon, until } from './harness/daemon.js'
+import { FakeBackend } from './harness/fakeBackend.js'
+import { remoteSettings, signIn, writeE2ee } from './harness/fleet.js'
+import { RelayPhone, type PhoneFrame } from './harness/relayPhone.js'
+
+const starts = (d: IsolatedDaemon) => [...d.log().matchAll(/\[harnessd\] service gateway started/g)].length
+const connections = (d: IsolatedDaemon) => d.log().split('\n').filter((line) => line.includes('[services] gateway connected')).length
+const pidsOf = (d: IsolatedDaemon) => [...d.log().matchAll(/\[harnessd\] service gateway started \(pid (\d+)\)/g)].map((match) => Number(match[1]))
+const status = async (d: IsolatedDaemon) => await (await fetch(`http://127.0.0.1:${d.port}/api/status`)).json() as Record<string, any>
+const isTurn = (type: string, agentId: string) => (frame: Frame | PhoneFrame) => frame.type === type && frame.agentId === agentId
+
+describe('the gateway\'s process, once it is needed', () => {
+ let daemon: IsolatedDaemon | undefined
+ let backend: FakeBackend | undefined
+ let phone: RelayPhone | undefined
+ afterEach(async () => {
+ phone?.close()
+ await daemon?.close()
+ await backend?.close()
+ daemon = undefined; backend = undefined; phone = undefined
+ })
+ const settled = async (d: IsolatedDaemon) => {
+ onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-150).join('\n')}`) })
+ await d.start()
+ // The others are up, and the core has had time to ask for anything it would ask for as it starts.
+ await until('the services to connect', () => d.log().includes('[services] search connected') || null, 30_000, 200)
+ await new Promise((resolve) => setTimeout(resolve, 3_000))
+ }
+ const fresh = async (env: Record<string, string> = {}, before?: (d: IsolatedDaemon) => void) => {
+ const d = await IsolatedDaemon.create({ env: { HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200', ...env } })
+ daemon = d
+ before?.(d)
+ await settled(d)
+ return d
+ }
+
+ it('runs no gateway signed out with nothing paired, answers its status without it, and a window\'s E2EE request starts it', async () => {
+ const d = await fresh()
+ expect(starts(d), 'a gateway signed out with nothing paired').toBe(0)
+ expect(d.log()).not.toContain('asking for the gateway\'s process')
+ // `/api/status`, which everything asks: answered, and no gateway for it.
+ expect(await status(d)).toMatchObject({ signedIn: false, fingerprint: null, pairs: [], pending: null })
+ expect(starts(d)).toBe(0)
+ // A window's E2EE request: it starts the gateway, waits for its start, and is the gateway's answer.
+ const window = await LocalClient.connect(d)
+ const [first, second] = await Promise.all([
+ window.request('e2ee_pairings_list', {}, 30_000),
+ window.request('e2ee_pairings_list', {}, 30_000),
+ ])
+ expect(first).toMatchObject({ pairs: [] })
+ expect(second).toMatchObject({ pairs: [] })
+ expect(starts(d)).toBe(1)
+ expect(connections(d)).toBe(1)
+ // Started, it answers the status from then on.
+ expect((await status(d)).fingerprint).toEqual(expect.any(String))
+ expect(d.coresStarted()).toBe(1)
+ window.close()
+ })
+
+ it('a key command starts it and is answered by it; killed, it comes back and answers again', async () => {
+ const d = await fresh()
+ const pairs = async () => await (await fetch(`http://127.0.0.1:${d.port}/api/pairs`)).json() as Record<string, any>
+ expect(await pairs()).toEqual({ pairs: [] })
+ expect(starts(d)).toBe(1)
+ const [pid] = pidsOf(d)
+ process.kill(pid, 'SIGKILL')
+ await until('the master to start the gateway again', () => starts(d) >= 2 || null, 30_000, 200)
+ await until('the gateway to connect again', () => connections(d) >= 2 || null, 30_000, 200)
+ expect(await pairs()).toEqual({ pairs: [] })
+ expect(d.coresStarted()).toBe(1)
+ })
+
+ it('asks for it as the core starts with anything paired here, signed out too', async () => {
+ const d = await fresh({}, (d) => {
+ mkdirSync(join(d.dataDir, 'e2e'), { recursive: true })
+ writeFileSync(join(d.dataDir, 'e2e', 'paired.json'), JSON.stringify([{ identityPub: b64e(newIdentity().pub), label: 'browser', pairedAt: 1, role: 'web' }]))
+ })
+ expect(d.log()).toContain('[gateway] a pairing: asking for the gateway\'s process')
+ await until('the gateway to connect', () => connections(d) >= 1 || null, 30_000, 200)
+ expect((await status(d)).pairs).toEqual([expect.objectContaining({ label: 'browser' })])
+ })
+
+ it('signing in starts it as the core starts, before it binds, and a phone reaches the machine', async () => {
+ const fake = await FakeBackend.start()
+ backend = fake
+ const machine = { machineId: 'a1'.repeat(16), computerId: 'e2e-computer-0000-0000-00000000000a', name: 'machine-a', token: 'e2e-token-machine-a', identity: newIdentity() }
+ fake.addMachine(machine)
+ const phoneUser = { identity: newIdentity(), token: 'e2e-token-phone' }
+ fake.addUser(phoneUser.token)
+ const d = await IsolatedDaemon.create({ env: { ...remoteSettings(fake), ADAPTER_COMPUTER_ID: machine.computerId } })
+ daemon = d
+ await settled(d)
+ expect(starts(d), 'a gateway before the sign-in').toBe(0)
+ // `harness login` signs the computer in and restarts the daemon on it; the phone was paired with it.
+ await d.stop()
+ await signIn(d, machine)
+ await writeE2ee(d, {
+ 'identity.json': { priv: b64e(machine.identity.priv), pub: b64e(machine.identity.pub) },
+ 'paired.json': [{ identityPub: b64e(phoneUser.identity.pub), label: 'phone', pairedAt: Date.now(), role: 'web' }],
+ })
+ const from = d.log().length
+ const startedAt = Date.now()
+ await d.start()
+ const after = () => d.log().slice(from)
+ expect(after()).toContain('[gateway] signed in: asking for the gateway\'s process')
+ await until('the machine to be on the relay', () => fake.nodeUp(machine.machineId) || null, 30_000, 50)
+ const onRelayMs = Date.now() - startedAt
+ // Asked before the core bound: started beside it, not after it.
+ const lines = after().split('\n')
+ expect(lines.findIndex((line) => line.includes('[harnessd] service gateway started'))).toBeLessThan(lines.findIndex((line) => line.includes('[harnessd] core bound')))
+ if (process.env.E2E_MEASURE) appendFileSync(process.env.E2E_MEASURE, `start to on the relay: ${onRelayMs} ms\n`)
+ phone = new RelayPhone({ backend: fake, machineId: machine.machineId, identity: phoneUser.identity, machinePub: machine.identity.pub, token: phoneUser.token })
+ await phone.open(30_000)
+ const window = await LocalClient.connect(d, { machineId: machine.machineId })
+ const cwd = join(d.projectsDir, 'signed-in')
+ mkdirSync(cwd, { recursive: true })
+ const created = await window.request('agent_create', { engine: 'claude', cwd, bypassPermission: true }, 60_000)
+ expect(created.error, JSON.stringify(created)).toBeUndefined()
+ await until('the agent to bind', async () => {
+ const rows = (await window.request<{ agents: Array<Record<string, any>> }>('agents_list', {}, 30_000)).agents
+ return rows.find((row) => row.id === created.agent.id)?.sessionId || null
+ }, 45_000, 500)
+ const ended = phone.next(isTurn('turn_ended', created.agent.id), 45_000, 'turn_ended on the phone')
+ expect(phone.send('message', { agentId: created.agent.id, content: 'from the phone, after signing in' })).toBe(true)
+ await ended
+ window.close()
+ })
+
+ it('named in HARNESSD_SERVICES, it starts with the daemon, signed out with nothing paired', async () => {
+ const d = await fresh({ HARNESSD_SERVICES: 'search,gateway' })
+ await until('the gateway to connect', () => connections(d) >= 1 || null, 30_000, 200)
+ expect(d.log()).not.toContain('asking for the gateway\'s process')
+ })
+})
diff --git a/cli/e2e/harness/fleet.ts b/cli/e2e/harness/fleet.ts
index 01736c79f..dbd8b9116 100644
--- a/cli/e2e/harness/fleet.ts
+++ b/cli/e2e/harness/fleet.ts
@@ -38,7 +38,7 @@ export interface FleetOptions {
}
/** Every daemon setting whose default is a server somewhere else, all pointed at the fake. */
-function remoteSettings(backend: FakeBackend): Record<string, string> {
+export function remoteSettings(backend: FakeBackend): Record<string, string> {
return {
BACKEND_WS_URL: backend.wsUrl,
WEB_URL: backend.httpUrl,
@@ -71,7 +71,7 @@ export function assertLocalOnly(env: NodeJS.ProcessEnv, backend: FakeBackend): v
}
/** Sign a daemon in, as `harness login` leaves a computer: a session for its machine on this account. */
-async function signIn(daemon: IsolatedDaemon, machine: FakeMachine): Promise<void> {
+export async function signIn(daemon: IsolatedDaemon, machine: FakeMachine): Promise<void> {
await writeFile(join(daemon.root, 'auth', 'session.json'), JSON.stringify({
version: 1, accessToken: machine.token, autonomousEnv: 'prod', computerId: machine.computerId,
machineId: machine.machineId, expiresAt: Date.now() + 30 * 24 * 3600_000, updatedAt: Date.now(), signInEpoch: 'e2e',
@@ -79,7 +79,7 @@ async function signIn(daemon: IsolatedDaemon, machine: FakeMachine): Promise<voi
}
/** The E2EE files `harness link connect` and pairing leave, written before the daemon first starts. */
-async function writeE2ee(daemon: IsolatedDaemon, files: Record<string, unknown>): Promise<void> {
+export async function writeE2ee(daemon: IsolatedDaemon, files: Record<string, unknown>): Promise<void> {
const dir = join(daemon.dataDir, 'e2e')
await mkdir(dir, { recursive: true, mode: 0o700 })
for (const [name, value] of Object.entries(files)) await writeFile(join(dir, name), JSON.stringify(value, null, 2), { mode: 0o600 })
diff --git a/cli/e2e/reexec.e2e.ts b/cli/e2e/reexec.e2e.ts
index 7dae75022..44d89c161 100644
--- a/cli/e2e/reexec.e2e.ts
+++ b/cli/e2e/reexec.e2e.ts
@@ -378,7 +378,10 @@ describe.skipIf(!RELEASED)('a released master and this one, each over the other\
? `now v${releasedVersion}`
: 'did not answer its probe (Unknown command: __harnessd-probe) — keeping this master')
// This master over a core too old to ask for a process on demand starts each as that core binds
- // (harnessd/services.ts `unasked`): models, which a core of protocol 4 asks for only once grid is in use.
- if (!releasedCanReexec) await until('this master to start models for the older core', () => daemon!.log().slice(from).includes('[harnessd] service models started') || null, 30_000, 200)
+ // (harnessd/services.ts `unasked`): models, which a core of protocol 4 asks for only once grid is in use,
+ // and the gateway, which it asks for only signed in or with something paired.
+ for (const name of releasedCanReexec ? [] : ['models', 'gateway']) {
+ await until(`this master to start ${name} for the older core`, () => daemon!.log().slice(from).includes(`[harnessd] service ${name} started`) || null, 30_000, 200)
+ }
})
})
diff --git a/cli/src/core/AGENTS.md b/cli/src/core/AGENTS.md
index 1df14a26f..b23fee873 100644
--- a/cli/src/core/AGENTS.md
+++ b/cli/src/core/AGENTS.md
@@ -72,3 +72,5 @@ questions. Everything else is a service ([../services/AGENTS.md](../services/AGE
agent made for a Store harness); `wifiLink.ts`: its service in the devices' process. `devicesWake.ts`: when
that process is asked for, once there is a device (a dial's port in /dev, a paired Wi-Fi device).
`modelsWake.ts`: when models' process is asked for as the core starts, once grid is in use here.
+ `gatewayWake.ts`: when the gateway's process is asked for as the core starts, before it binds: signed in, or
+ anything paired here.
diff --git a/cli/src/core/devicesWake.ts b/cli/src/core/devicesWake.ts
index 1d478b1e6..af0c1f3e9 100644
--- a/cli/src/core/devicesWake.ts
+++ b/cli/src/core/devicesWake.ts
@@ -23,8 +23,8 @@ export const DEVICES_ON_DEMAND = ['devices', 'wifi'] as const
export const DIAL_LOOK_MS = 2_000
/** The Wi-Fi device's direct links (lib/autonomous-device/direct.ts) and the gateway's pairings (lib/e2ee/store.ts),
* read no further than this. */
-const DIRECT_LINKS = 'autonomous-device-connections.json'
-const PAIRINGS = join('e2e', 'paired.json')
+export const DIRECT_LINKS = 'autonomous-device-connections.json'
+export const PAIRINGS = join('e2e', 'paired.json')
const SAVED_MAX = 1_048_576
/** Whether a dial's port may be there: a USB modem's node, or one of the end-to-end suite's dials (a
@@ -43,20 +43,24 @@ export function dialPortThere(deps: { platform: NodeJS.Platform; listDev: () =>
}
}
+/** The rows of one of the gateway's saved lists in the data folder, read no further than a bound; none when it is
+ * not there, too big or not a list. */
+export function savedRows(dataDir: string, name: string, read: (file: string) => string = (file) => readFileSync(file, 'utf8')): unknown[] {
+ const file = join(dataDir, name)
+ try {
+ if (statSync(file).size > SAVED_MAX) return []
+ const listed: unknown = JSON.parse(read(file))
+ return Array.isArray(listed) ? listed : []
+ } catch {
+ return []
+ }
+}
+
/** Whether a Wi-Fi device is paired here: the gateway's pairings name one as a device, or its direct links
* connect out to one. */
export function wifiDeviceSaved(dataDir: string, read: (file: string) => string = (file) => readFileSync(file, 'utf8')): boolean {
- const rows = (name: string): unknown[] => {
- const file = join(dataDir, name)
- try {
- if (statSync(file).size > SAVED_MAX) return []
- const listed: unknown = JSON.parse(read(file))
- return Array.isArray(listed) ? listed : []
- } catch {
- return []
- }
- }
- return rows(DIRECT_LINKS).length > 0 || rows(PAIRINGS).some((pair) => (pair as { role?: unknown } | null)?.role === 'device')
+ return savedRows(dataDir, DIRECT_LINKS, read).length > 0
+ || savedRows(dataDir, PAIRINGS, read).some((pair) => (pair as { role?: unknown } | null)?.role === 'device')
}
export interface DevicesWakeDeps {
diff --git a/cli/src/core/gatewayLink.spec.ts b/cli/src/core/gatewayLink.spec.ts
index f6154c8d9..d0b8bdad2 100644
--- a/cli/src/core/gatewayLink.spec.ts
+++ b/cli/src/core/gatewayLink.spec.ts
@@ -3,7 +3,8 @@ import { decodeGatewayBinary, encodeGatewayBinary, GatewayBinary, GATEWAY_CALLS
import { RelayConnectError } from '../lib/relayFrames.js'
import { decodeTerminalLocal, encodeTerminalLocal, TerminalBinaryKind, type TerminalBinaryClear } from '../lib/terminalBinary.js'
import type { GatewayEvents, LaneSeal } from './api.js'
-import { createGatewayLink, GATEWAY_BUFFER_LIMIT, LANE_WAIT_MS, laneOf, PAIR_WAIT_MS, WINDOW_GATEWAY_GONE } from './gatewayLink.js'
+import { createGatewayLink, GATEWAY_BUFFER_LIMIT, LANE_WAIT_MS, laneOf, OWED_MAX, PAIR_WAIT_MS, WINDOW_GATEWAY_GONE } from './gatewayLink.js'
+import { ON_DEMAND_START_MS } from './serviceLinks.js'
const STREAM = '00000000-0000-4000-8000-000000000001'
const bytesOf = (text: string): TerminalBinaryClear => ({ kind: TerminalBinaryKind.output, streamId: STREAM, seq: 1, compressed: false, bytes: new TextEncoder().encode(text) })
@@ -16,7 +17,7 @@ function events(): { [K in keyof GatewayEvents]: ReturnType<typeof vi.fn> } {
}
}
-function setup(over: { buffered?: number; call?: (type: string, payload: Record<string, unknown>, waitMs?: number) => Promise<Record<string, unknown>> } = {}) {
+function setup(over: { buffered?: number; call?: (type: string, payload: Record<string, unknown>, waitMs?: number) => Promise<Record<string, unknown>>; startWaitMs?: number } = {}) {
const heard = events()
const sent: Array<Record<string, unknown>> = []
const binary: Uint8Array[] = []
@@ -26,6 +27,7 @@ function setup(over: { buffered?: number; call?: (type: string, payload: Record<
const call = vi.fn(over.call ?? (async () => ({ status: 200, body: { ok: true } })))
const tokens = { accessToken: vi.fn(async () => 'token-1') }
const backend = vi.fn(async () => ({ status: 200, body: { data: { seen: {} } } }))
+ const want = vi.fn()
const link = createGatewayLink({
events: heard as unknown as GatewayEvents,
notify: (frame) => { sent.push(frame.payload as Record<string, unknown>); return true },
@@ -33,10 +35,10 @@ function setup(over: { buffered?: number; call?: (type: string, payload: Record<
buffered: () => buffered,
call,
start: () => ({ machineId: 'm1', computerId: 'c1', autonomousEnv: 'prod', signedIn: true }),
- tokens, backend, log, now: () => clock,
+ tokens, backend, log, now: () => clock, want, ...(over.startWaitMs ? { startWaitMs: over.startWaitMs } : {}),
})
return {
- link, heard, sent, binary, call, tokens, backend, log,
+ link, heard, sent, binary, call, tokens, backend, log, want,
kinds: () => sent.map((payload) => payload.kind),
setBuffered: (bytes: number) => { buffered = bytes },
tick: (ms: number) => { clock += ms },
@@ -226,16 +228,87 @@ describe('the gateway in its own process, as the core sees it', () => {
expect(call).toHaveBeenCalledWith(GATEWAY_CALLS.devicesRebaseline, { confirm: false }, undefined)
})
- it('reads the gateway\'s status, with nothing to show while it is down', async () => {
+ it('reads the gateway\'s status, with nothing to show while it is down, and never starts it for that', async () => {
const said = { fingerprint: 'AB12', pairs: [{ fingerprint: 'CD34' }], pending: { label: 'Phone' } }
let answer: Record<string, unknown> = said
- const { link, call } = setup({ call: async () => answer })
+ const { link, call, want } = setup({ call: async () => answer })
+ // Never started: `/api/status` is answered without it, and does not ask for it.
+ expect(await link.ops.status()).toEqual({ fingerprint: null, pairs: [], pending: null })
+ expect(call).not.toHaveBeenCalled()
+ expect(want).not.toHaveBeenCalled()
+ link.connected()
expect(await link.ops.status()).toEqual(said)
expect(call).toHaveBeenCalledWith(GATEWAY_CALLS.status, {}, 2_000)
+ link.disconnected()
answer = { error: 'SERVICE_UNAVAILABLE' }
expect(await link.ops.status()).toEqual({ fingerprint: null, pairs: [], pending: null })
})
+ it('is asked for once, by the first thing that needs it, and tells it what waited, in order, after its start', () => {
+ const { link, sent, kinds, want } = setup()
+ // What only says how things stand asks for nothing: it is told in the start.
+ link.port.localClients({ desktop: 1, tui: 0 })
+ link.ops.wifiService(false)
+ expect(want).not.toHaveBeenCalled()
+ // A window's E2EE request: asked for, and held.
+ void link.port.local('conn-1', { type: 'e2ee_pairings_list', payload: { requestId: 'r1' } })
+ expect(want).toHaveBeenCalledTimes(1)
+ void link.port.local('conn-2', { type: 'phone_pair', payload: { requestId: 'r2' } })
+ link.port.connect()
+ link.ops.wifiService(true)
+ expect(want).toHaveBeenCalledTimes(1)
+ expect(sent).toEqual([])
+ link.connected()
+ expect(kinds()).toEqual(['start', 'localFrame', 'localFrame'])
+ expect(sent[1]).toEqual({ kind: 'localFrame', connId: 'conn-1', frame: { type: 'e2ee_pairings_list', payload: { requestId: 'r1' } } })
+ expect(sent[2]).toMatchObject({ connId: 'conn-2' })
+ // Gone later, it is the master's to restart: nothing waits for it, and it is not asked for again.
+ link.disconnected()
+ void link.port.local('conn-3', { type: 'e2ee_pairings_list', payload: {} })
+ link.connected()
+ expect(kinds()).toEqual(['start', 'localFrame', 'localFrame', 'start'])
+ expect(want).toHaveBeenCalledTimes(1)
+ })
+
+ it('is asked for by a sign-in\'s dial and by the Wi-Fi device\'s service, each once', () => {
+ const dialed = setup()
+ dialed.link.port.connect()
+ expect(dialed.want).toHaveBeenCalledTimes(1)
+ const wifi = setup()
+ wifi.link.ops.wifiService(true)
+ wifi.link.port.connect()
+ expect(wifi.want).toHaveBeenCalledTimes(1)
+ })
+
+ it('lets go of what waited when it does not start in time, the oldest first when too much waits', async () => {
+ vi.useFakeTimers()
+ try {
+ const { link, sent } = setup({ startWaitMs: 20_000 })
+ const select = { type: 'machine_select', payload: {} }
+ const sink = { sendFrame: vi.fn(() => true), sendBinary: vi.fn(() => true) }
+ const opening = link.windowRelay.acquire('m2', 'prod', select, sink, vi.fn())
+ void link.port.local('conn-1', { type: 'e2ee_pairings_list', payload: {} })
+ vi.advanceTimersByTime(20_000)
+ await expect(opening).rejects.toEqual(new RelayConnectError('the relay did not start', WINDOW_GATEWAY_GONE))
+ // Its E2EE request is the window's own deadline's: not sent late to a gateway that came after all.
+ link.connected()
+ expect(sent.map((payload) => payload.kind)).toEqual(['start'])
+
+ const crowded = setup()
+ const first = crowded.link.windowRelay.acquire('m2', 'prod', select, sink, vi.fn())
+ for (let i = 0; i < OWED_MAX; i++) void crowded.link.port.local(`conn-${i}`, { type: 'e2ee_pairings_list', payload: {} })
+ await expect(first).rejects.toEqual(new RelayConnectError('the relay did not start', WINDOW_GATEWAY_GONE))
+ crowded.link.connected()
+ expect(crowded.sent).toHaveLength(1 + OWED_MAX)
+ // The default wait, when none is given.
+ const plain = setup()
+ void plain.link.port.local('conn-1', { type: 'e2ee_pairings_list', payload: {} })
+ vi.advanceTimersByTime(ON_DEMAND_START_MS)
+ plain.link.connected()
+ expect(plain.sent).toHaveLength(1)
+ } finally { vi.useRealTimers() }
+ })
+
it('carries the Wi-Fi device\'s requests, a refusal as the device\'s local API words it', async () => {
let answer: Record<string, unknown> = { result: { devices: [] } }
const { link, call } = setup({ call: async () => answer })
@@ -412,12 +485,13 @@ describe('a window here working on another machine, through the gateway', () =>
})
it('watches a harness shared with this account through the gateway, and is told 4403 when the share ended', async () => {
- const { link, sent } = setup()
- // The gateway not there: out of reach just now, as the Share relay said when it could not dial.
- await expect(link.windowRelay.acquireShare!('owner', 'share-1', sink(), vi.fn())).rejects.toMatchObject({ closeCode: WINDOW_GATEWAY_GONE })
- link.connected()
+ const { link, sent, want } = setup()
+ // The gateway not started yet: asked for, and the window opened once it has.
const window = sink()
const watching = link.windowRelay.acquireShare!('owner', 'share-1', window, vi.fn())
+ expect(want).toHaveBeenCalledTimes(1)
+ expect(sent).toEqual([])
+ link.connected()
expect(sent.at(-1)).toEqual({ kind: 'windowOpen', id: 'window-1', machineId: 'owner', share: 'share-1' })
link.notice({ kind: 'windowOpened', id: 'window-1' })
await watching
@@ -430,6 +504,9 @@ describe('a window here working on another machine, through the gateway', () =>
it('the gateway gone: a window waiting to open and one open are both told to try again', async () => {
const { link } = setup()
+ link.connected()
+ link.disconnected()
+ // Gone, out of reach just now, as the relay said when it could not dial.
await expect(link.windowRelay.acquire('m2', 'prod', select, sink(), vi.fn())).rejects.toMatchObject({ closeCode: WINDOW_GATEWAY_GONE })
link.connected()
const onClosed = vi.fn()
diff --git a/cli/src/core/gatewayLink.ts b/cli/src/core/gatewayLink.ts
index 7a575d279..3cc0dee7f 100644
--- a/cli/src/core/gatewayLink.ts
+++ b/cli/src/core/gatewayLink.ts
@@ -25,7 +25,7 @@ import type {
BackendNotice, GatewayEvents, LocalWindows, GatewayOps, GatewayPort, GatewayRefusal, GatewayStatus, HttpAnswer, LaneSeal,
RemoteClient, RemoteRole, RemoteTransport, WindowRelay, WindowRelaySession, WindowRelaySink,
} from './api.js'
-import type { ServiceFrame } from './serviceLinks.js'
+import { ON_DEMAND_START_MS, type ServiceFrame } from './serviceLinks.js'
export interface GatewayLinkDeps {
/** The core's side of what the gateway tells it (BackendSocket's `fromGateway`). */
@@ -41,6 +41,10 @@ export interface GatewayLinkDeps {
tokens: { accessToken(opts?: { force?: boolean; failedToken?: string }): Promise<string> }
/** A read of the backend's REST API under the account's session (the core's proxy). */
backend(method: 'GET', path: string): Promise<HttpAnswer>
+ /** Ask the master for the gateway's process (harnessd/coreLink.ts `want`): it runs on demand (core/gatewayWake.ts). */
+ want?(): void
+ /** How long what waits for the gateway's first start waits (core/serviceLinks.ts `ON_DEMAND_START_MS`). */
+ startWaitMs?: number
newId?: () => string
now?: () => number
log?: (line: string) => void
@@ -57,6 +61,9 @@ export const PAIR_WAIT_MS = 120_000
/** The close a window on another machine gets when the gateway it went through is gone: try again shortly. */
export const WINDOW_GATEWAY_GONE = 1013
+/** The most a window's E2EE requests and sessions to open wait for the gateway's first start; the oldest go. */
+export const OWED_MAX = 256
+
/** How long the fleet's lane waits on the gateway to seal or open a frame. The frames behind it wait too,
* in order; a gateway that has not answered in this long is hung, and the master ends it soon after. */
export const LANE_WAIT_MS = 5_000
@@ -81,6 +88,13 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
const newId = deps.newId ?? (() => `window-${++counter}`)
/** The gateway's process is connected to this core. */
let up = false
+ /** It has connected in this core's life. Before that it runs on demand: what needs it asks for it, once, and
+ * what a window asked of it meanwhile (an E2EE request, a session to another machine) waits for it, in order,
+ * to be told after its `start`. Gone again later it is the master's to restart, and nothing waits. */
+ let seen = false
+ let asked = false
+ const owed: Array<Record<string, unknown>> = []
+ let owedTimer: ReturnType<typeof setTimeout> | null = null
/** The backend link, as the gateway last said. */
let linkUp = false
// What the gateway is told again whenever it connects.
@@ -111,9 +125,26 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
}
const bulk = (kind: string, payload: Record<string, unknown>): boolean => up && fits() && send(kind, payload)
const reachableClient = (connId: string): boolean => up && clients.has(connId)
+ const need = (): void => {
+ if (up || seen || asked) return
+ asked = true
+ deps.want?.()
+ }
+ /** What waits for the first start gives up when it has not come in time: a session to open is closed, to be
+ * tried again; an E2EE request is left to the window's own deadline. */
+ const giveUp = (item: Record<string, unknown>): void => {
+ if (item.kind === 'windowOpen') closeWindow(text(item.id), WINDOW_GATEWAY_GONE, 'the relay did not start')
+ }
+ const owe = (kind: string, payload: Record<string, unknown>): void => {
+ owed.push({ ...payload, kind })
+ if (owed.length > OWED_MAX) giveUp(owed.shift()!)
+ need()
+ owedTimer ??= setTimeout(() => { owedTimer = null; for (const item of owed.splice(0)) giveUp(item) }, deps.startWaitMs ?? ON_DEMAND_START_MS)
+ owedTimer.unref?.()
+ }
const port: GatewayPort = {
- connect: () => { dial = 'connect'; send('connect') },
+ connect: () => { dial = 'connect'; need(); send('connect') },
serveThisComputerOnly: () => { dial = 'local'; send('thisComputerOnly') },
holdRequests: () => { requestsOpen = false; send('hold') },
openRequests: () => { requestsOpen = true; send('open') },
@@ -133,7 +164,7 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
observer: (connId, type, payload) => up && linkUp && send('observer', { connId, type, payload }),
windowOpened: (surface) => { send('windowOpened', { surface }) },
localClients: (windows) => { localClients = windows; send('localClients', { windows }) },
- local: async (connId, frame) => { send('localFrame', { connId, frame }) },
+ local: async (connId, frame) => { if (up || seen) send('localFrame', { connId, frame }); else owe('localFrame', { connId, frame }) },
device: (connId, type, payload) => reachableClient(connId) && send('device', { connId, type, payload }),
deviceClient: (connId, identity) => { send('deviceClient', { connId, identity }) },
stop: async () => { send('stop') },
@@ -180,6 +211,9 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
const ops: GatewayOps = {
status: async (): Promise<GatewayStatus> => {
+ // Never started, it has no pairing under way and nothing to say; `/api/status` is asked far too often to
+ // start it for.
+ if (!up && !seen) return { fingerprint: null, pairs: [], pending: null }
const answer = await deps.call(GATEWAY_CALLS.status, {}, 2_000)
return {
fingerprint: typeof answer.fingerprint === 'string' ? answer.fingerprint : null,
@@ -212,7 +246,7 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
: { code: 'UNAVAILABLE', message: 'The Wi-Fi device link is not reachable on this computer right now. Try again.' }
return { refused: why }
},
- wifiService: (on) => { wifiService = on; send('wifiService', { on }) },
+ wifiService: (on) => { wifiService = on; if (on) need(); send('wifiService', { on }) },
revokeIdentity: (identity) => { send('revokeIdentity', { identity }) },
account: (next) => { send('account', { account: next }) },
reachable: (machineIds) => { reachable = machineIds; send('reachable', { machineIds }) },
@@ -227,10 +261,11 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
* with this account (`share`). */
const openWindow = (open: Record<string, unknown>, sink: WindowRelaySink, onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession> =>
new Promise((resolve, reject) => {
- if (!up) { reject(new RelayConnectError('the relay is restarting', WINDOW_GATEWAY_GONE)); return }
+ if (!up && seen) { reject(new RelayConnectError('the relay is restarting', WINDOW_GATEWAY_GONE)); return }
const id = newId()
windows.set(id, { sink, onClosed, opening: { resolve, reject } })
- send('windowOpen', { ...open, id })
+ if (up) send('windowOpen', { ...open, id })
+ else owe('windowOpen', { ...open, id })
})
const open = (isolated: boolean) => (machineId: string, autonomousEnv: string, selectFrame: Record<string, unknown>,
sink: WindowRelaySink, onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession> =>
@@ -380,8 +415,13 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
// all the same: what the core kept of the last one goes first.
if (up) this.disconnected()
up = true
+ seen = true
// The account as the core reads it now (`start`), which is never older than the last one it said.
send('start', { requestsOpen, dial, localClients, wifiService, reachable, ...deps.start() })
+ // Then what waited for its first start, in the order it came.
+ if (owedTimer) clearTimeout(owedTimer)
+ owedTimer = null
+ for (const { kind, ...payload } of owed.splice(0)) send(text(kind), payload)
},
/** The gateway's process went: the relay with it, as far as everything in the core is concerned. */
disconnected(): void {
diff --git a/cli/src/core/gatewayWake.spec.ts b/cli/src/core/gatewayWake.spec.ts
new file mode 100644
index 000000000..eee2bf48d
--- /dev/null
+++ b/cli/src/core/gatewayWake.spec.ts
@@ -0,0 +1,58 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { gatewayNeeded, wakeGateway } from './gatewayWake.js'
+
+describe('the gateway needed as the core starts', () => {
+ let dataDir: string
+ beforeEach(() => { dataDir = mkdtempSync(join(tmpdir(), 'gateway-wake-')) })
+ afterEach(() => rmSync(dataDir, { recursive: true, force: true }))
+
+ it('is not, signed out with nothing paired: nothing could reach it, and it would dial nothing', () => {
+ expect(gatewayNeeded({ signedIn: false, dataDir })).toBeNull()
+ // Lists that are there and empty, or not lists, pair nothing.
+ mkdirSync(join(dataDir, 'e2e'))
+ writeFileSync(join(dataDir, 'e2e', 'paired.json'), '[]')
+ writeFileSync(join(dataDir, 'autonomous-device-connections.json'), '{"not":"a list"}')
+ expect(gatewayNeeded({ signedIn: false, dataDir })).toBeNull()
+ })
+
+ it('is, signed in: the relay, the remote clients, the trust group and the device key log are its', () => {
+ expect(gatewayNeeded({ signedIn: true, dataDir })).toBe('signed in')
+ })
+
+ it('is, with anything paired here, whatever its role, or a Wi-Fi device linked directly', () => {
+ mkdirSync(join(dataDir, 'e2e'))
+ writeFileSync(join(dataDir, 'e2e', 'paired.json'), JSON.stringify([{ identityPub: 'p', label: 'browser', pairedAt: 1, role: 'web' }]))
+ expect(gatewayNeeded({ signedIn: false, dataDir })).toBe('a pairing')
+ writeFileSync(join(dataDir, 'e2e', 'paired.json'), '[]')
+ writeFileSync(join(dataDir, 'autonomous-device-connections.json'), JSON.stringify([{ discoveryId: 'd', fingerprint: 'f' }]))
+ expect(gatewayNeeded({ signedIn: false, dataDir })).toBe('a direct link')
+ })
+})
+
+describe('the gateway asked for as the core starts', () => {
+ it('when it runs out here and is needed, saying why', () => {
+ const wanted: string[] = []
+ const lines: string[] = []
+ wakeGateway({ outOfProcess: new Set(['gateway']), signedIn: true, dataDir: '/nowhere', want: (service) => wanted.push(service), log: (line) => lines.push(line) })
+ expect(wanted).toEqual(['gateway'])
+ expect(lines).toEqual(['[gateway] signed in: asking for the gateway\'s process'])
+ })
+
+ it('not when it is not needed, nor when it runs in the core\'s process', () => {
+ const wanted: string[] = []
+ wakeGateway({ outOfProcess: new Set(['gateway']), signedIn: false, dataDir: '/nowhere', want: (service) => wanted.push(service) })
+ wakeGateway({ outOfProcess: new Set(['search']), signedIn: true, dataDir: '/nowhere', want: (service) => wanted.push(service) })
+ expect(wanted).toEqual([])
+ })
+
+ it('says why on the console by default', () => {
+ const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+ try {
+ wakeGateway({ outOfProcess: new Set(['gateway']), signedIn: true, dataDir: '/nowhere', want: () => {} })
+ expect(log).toHaveBeenCalledWith('[gateway] signed in: asking for the gateway\'s process')
+ } finally { log.mockRestore() }
+ })
+})
diff --git a/cli/src/core/gatewayWake.ts b/cli/src/core/gatewayWake.ts
new file mode 100644
index 000000000..1b3f7334b
--- /dev/null
+++ b/cli/src/core/gatewayWake.ts
@@ -0,0 +1,27 @@
+/**
+ * When the gateway's process starts (harnessd/services.ts `gateway`, on demand since protocol 4).
+ *
+ * As the core starts, before it binds, when the gateway has work of its own here: this machine is signed in (the
+ * relay to the backend, the remote clients' sessions, the trust group and the device key log), or anything is
+ * paired (`e2e/paired.json`: a browser, a phone, a Wi-Fi device) or linked directly (the Wi-Fi device's direct
+ * links). Asked that early, it comes up beside the core, as it did when it started with every other process, and
+ * a phone reaches this machine as soon as it did. Otherwise the first thing that needs it asks for it
+ * (core/gatewayLink.ts): a pairing, a window's E2EE request, a key or device command, the Wi-Fi device's service.
+ * Signed out with nothing paired it has nothing to do: the relay is never dialed, and nothing could reach it.
+ */
+import { DIRECT_LINKS, PAIRINGS, savedRows } from './devicesWake.js'
+
+/** Why the gateway is needed as the core starts, as the log says it; null when it is not. */
+export function gatewayNeeded(deps: { signedIn: boolean; dataDir: string; read?: (file: string) => string }): string | null {
+ if (deps.signedIn) return 'signed in'
+ if (savedRows(deps.dataDir, PAIRINGS, deps.read).length) return 'a pairing'
+ return savedRows(deps.dataDir, DIRECT_LINKS, deps.read).length ? 'a direct link' : null
+}
+
+/** At the core's start: the gateway's process asked for when it runs out here and is needed. */
+export function wakeGateway(deps: { outOfProcess: ReadonlySet<string>; signedIn: boolean; dataDir: string; want(service: string): void; log?(line: string): void }): void {
+ const why = deps.outOfProcess.has('gateway') ? gatewayNeeded(deps) : null
+ if (!why) return
+ ;(deps.log ?? console.log)(`[gateway] ${why}: asking for the gateway's process`)
+ deps.want('gateway')
+}
diff --git a/cli/src/core/main.ts b/cli/src/core/main.ts
index 196d413b7..31a486545 100644
--- a/cli/src/core/main.ts
+++ b/cli/src/core/main.ts
@@ -151,6 +151,7 @@ import { createGatewayLink, laneOf } from './gatewayLink.js'
import { createWifiCore, WIFI_START_MS } from './wifi.js'
import { createDevicesWake, DEVICES_ON_DEMAND } from './devicesWake.js'
import { wakeModels } from './modelsWake.js'
+import { wakeGateway } from './gatewayWake.js'
import { createWifiLink } from './wifiLink.js'
import { wifiDoors } from './wifiAgents.js'
import { autonomousDeviceLocalRequest } from '../lib/autonomous-device/localApi.js'
@@ -382,6 +383,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// move (it tears down two dozen subsystems declared further down). Until it is ready, a staged update is
// applied by `bootHandoff`, which hands the machine over without finishing start-up.
coreLink.onUpdate((version) => { void daemonBoot.applyStagedUpdate(version) })
+ wakeGateway({ outOfProcess: servicesTheMasterRuns(process.env, KNOWN_SERVICES), signedIn: !!session, dataDir: env.ADAPTER_DATA_DIR, want: (service) => coreLink.want(service) })
// …or, under a master too old to run the updater, from the updater this core runs beside itself
// (core/updaterBeside.ts), in a process of its own: the core downloads no build either way.
if (needsUpdaterBeside(process.env, coreLink.supervised, isInstalledCopy(SCRIPT_PATH, env.ADAPTER_CLI_DIR), env.ADAPTER_UPDATE_DISABLE)) {
@@ -789,7 +791,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
buffered: () => serviceLinksRef?.buffered('gateway') ?? 0,
call: (type, payload, waitMs) => serviceLinksRef?.call('gateway', type, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }),
start: () => ({ machineId: backend.machineId, computerId: computerId(), autonomousEnv, signedIn: !!session?.machineId, account: account() }),
- tokens: auth, backend: (method, path) => proxyBackend(method, path),
+ tokens: auth, backend: (method, path) => proxyBackend(method, path), want: () => coreLink.want('gateway'),
}) : null
const gateway = gatewayLink ?? inline!.startGateway({
events: backend.fromGateway, machineId: backend.machineId, computerId: computerId(), autonomousEnv,
@@ -1138,8 +1140,8 @@ async function runForeground(session: AuthSession | null): Promise<void> {
token: serviceToken,
owned: Object.fromEntries([...outOfProcess].map((name) => [name, requestsOf[name] ?? []])),
waits: LONG_ANSWERS,
- // An experiment's process runs once it is on, the devices' once there is one, models' once grid is used: a request asks.
- onDemand: new Set([...experiments, ...DEVICES_ON_DEMAND, 'models']),
+ // An experiment's process runs once on, the devices' once there is one, models' and the gateway's once needed: a request asks.
+ onDemand: new Set([...experiments, ...DEVICES_ON_DEMAND, 'models', 'gateway']),
want: (service) => experimentHooks.want(service),
// The gateway's first: its `backend` reads (the device key log) were refused below as NOT_AN_EXPERIMENT.
answer: async (service, query, payload) => (service === 'gateway' && gatewayLink ? gatewayLink.answer(query, payload) : null) ?? deliveries.answer(service, query, payload)
diff --git a/cli/src/core/serviceLinks.ts b/cli/src/core/serviceLinks.ts
index 3c7e07290..5e032fb8b 100644
--- a/cli/src/core/serviceLinks.ts
+++ b/cli/src/core/serviceLinks.ts
@@ -182,6 +182,9 @@ export function createServiceLinks(options: ServiceLinksOptions) {
const owed = held.get(service) ?? []
held.delete(service)
for (const frame of owed) sink.sendFrame(frame)
+ // What the core tells it as it connects comes before the requests that woke it: the gateway answers
+ // nothing until it is told what to start from (core/gatewayLink.ts `connected`).
+ options.connected?.(service)
// The requests that woke an experiment, in the order they came.
for (const [id, entry] of waiting) {
if (entry.service !== service || !entry.frame) continue
@@ -192,7 +195,6 @@ export function createServiceLinks(options: ServiceLinksOptions) {
clearTimer(entry.timer)
entry.timer = setTimer(() => settle(id, entry, unavailable(service)), entry.wait)
}
- options.connected?.(service)
return {
receive: (frame) => {
const payload = frame.payload ?? {}
diff --git a/cli/src/harnessd/AGENTS.md b/cli/src/harnessd/AGENTS.md
index 1daf741e4..1b00acb9b 100644
--- a/cli/src/harnessd/AGENTS.md
+++ b/cli/src/harnessd/AGENTS.md
@@ -50,3 +50,5 @@ It keeps the core and the services running, and nothing else.
The core sends `harnessd:want` for one of its services; from then on it is kept running like any other.
A core that speaks an older protocol than the process's `askedSince` never asks, so `unasked` starts it
as that core binds. Making a process on demand bumps `HARNESSD_PROTOCOL` and sets `askedSince` to it.
+ A `want` is heard before the core binds too: a core signed in asks for the gateway as it starts, so the
+ relay comes up beside it.
diff --git a/cli/src/harnessd/coreLink.ts b/cli/src/harnessd/coreLink.ts
index bc2f1b119..1ea3de61f 100644
--- a/cli/src/harnessd/coreLink.ts
+++ b/cli/src/harnessd/coreLink.ts
@@ -68,7 +68,7 @@ export interface CoreLink {
* waiting for it either way, and rolls back an update whose first core ends up in safe mode. */
ready(safeMode?: string): void
/** Ask the master to start the process on demand that runs [service]: an experiment that is on (protocol 3),
- * or the devices, now that there is one (protocol 4). */
+ * or the devices, models or the gateway, now that they are needed (protocol 4, before `bound` too). */
want(service: string): void
/** Tell the master, every `heartbeatInterval`, that this core is alive and how big it is. */
startHeartbeat(): void
diff --git a/cli/src/harnessd/protocol.ts b/cli/src/harnessd/protocol.ts
index bfeec360c..49ab92f65 100644
--- a/cli/src/harnessd/protocol.ts
+++ b/cli/src/harnessd/protocol.ts
@@ -15,8 +15,9 @@ import type { SupervisorStatus } from './supervisor.js'
/** 2: `ready`, the event-loop delay on the heartbeat, and the exit-code contract below. 3: `want`, and the
* master's updater: the master tells its core to hand over for a build its updater staged (`harnessd:update`).
- * 4: `want` for the devices' process too, which runs only once there is a device, and for models', which runs
- * only once grid is in use here or a request needs it (./services.ts `askedSince`). */
+ * 4: `want` for the devices' process too, which runs only once there is a device, for models', which runs
+ * only once grid is in use here or a request needs it, and for the gateway's, which runs once this machine is
+ * signed in, has anything paired or needs it; and `want` before `bound` (./services.ts `askedSince`). */
export const HARNESSD_PROTOCOL = 4
/** The command a bundle's master answers its probe on, and what it answers. */
@@ -64,8 +65,8 @@ export type CoreMessage =
* loop was held since the last one (protocol 2). */
| { type: 'harnessd:heartbeat'; rssBytes: number; heapUsedBytes: number; loopDelayMs?: number }
/** Start the process that runs this service (harnessd/services.ts `onDemand`): an experiment that is on now
- * (protocol 3), or the devices, now that there is one, or models, now that grid is in use or asked for
- * (protocol 4). A master from before ignores it, having started every service at once. */
+ * (protocol 3), or the devices, models or the gateway, now that they are needed (protocol 4, and before
+ * `bound` too). A master from before ignores it, having started every service at once. */
| { type: 'harnessd:want'; service: string }
export type MasterMessage =
diff --git a/cli/src/harnessd/services.ts b/cli/src/harnessd/services.ts
index 1abe314a9..58cb672ca 100644
--- a/cli/src/harnessd/services.ts
+++ b/cli/src/harnessd/services.ts
@@ -393,7 +393,10 @@ export const SERVICE_HOSTS: Readonly<Record<string, ServiceHostSpec>> = {
// The relay and its E2EE (gateway/gatewayProcess.ts): the backend link, every remote client's session,
// the terminals' WebRTC channels and their queues. Network, crypto and pure-JS WebRTC, the attack surface,
// where a fault costs the remote clients and nothing else (docs/design/2026-10-06-core-boundary-next.md).
- gateway: { services: ['gateway'], heapLimitMiB: 512, rssLimitMiB: 1_024 },
+ // Started as the core starts when it is signed in or anything is paired here, and otherwise by the first
+ // thing that needs it (core/gatewayWake.ts): about 75 MiB at idle a computer signed out with nothing
+ // paired never pays.
+ gateway: { services: ['gateway'], heapLimitMiB: 512, rssLimitMiB: 1_024, onDemand: true, askedSince: 4 },
// Grid's pictures, the Model Manager's catalog and the models found on this machine. Its downloads, model
// servers and `grid` commands run in processes of their own, outside this budget. Started only once grid is
// in use here or a request needs it (core/modelsWake.ts): about 70 MiB at idle, which a computer that uses
diff --git a/cli/src/harnessd/supervisor.spec.ts b/cli/src/harnessd/supervisor.spec.ts
index 1aeff287a..8471083b1 100644
--- a/cli/src/harnessd/supervisor.spec.ts
+++ b/cli/src/harnessd/supervisor.spec.ts
@@ -116,15 +116,16 @@ describe('Supervisor', () => {
expect(statuses).toHaveLength(3)
})
- it('starts the process a bound core asks for, and those a core too old to ask for them never would', () => {
+ it('starts the process a core asks for, bound or still starting, and those a core too old to ask for them never would', () => {
const wanted: string[] = []
const unasked: number[] = []
make({}, { want: (service) => wanted.push(service), unasked: (protocol) => unasked.push(protocol) }).start()
- core().say({ type: 'harnessd:want', service: 'orchestrator' })
- expect(wanted).toEqual([])
+ // The gateway of a core signed in, asked for as it starts: up beside it, not a bind later.
+ core().say({ type: 'harnessd:want', service: 'gateway' })
+ expect(wanted).toEqual(['gateway'])
core().bind()
core().say({ type: 'harnessd:want', service: 'orchestrator' })
- expect(wanted).toEqual(['orchestrator'])
+ expect(wanted).toEqual(['gateway', 'orchestrator'])
expect(unasked).toEqual([])
crash()
core().bind(2)
diff --git a/cli/src/harnessd/supervisor.ts b/cli/src/harnessd/supervisor.ts
index ae61b0c67..df42bad54 100644
--- a/cli/src/harnessd/supervisor.ts
+++ b/cli/src/harnessd/supervisor.ts
@@ -448,7 +448,10 @@ export class Supervisor {
this.up()
return
case 'harnessd:want':
- if (this.bound) this.deps.want?.(message.service)
+ // Before its bind too: a core signed in asks for the gateway as it starts, so that the relay comes up
+ // beside it, as it did when the gateway started with every other process. A core too old to ask sends
+ // none, before or after.
+ this.deps.want?.(message.service)
return
case 'harnessd:heartbeat': {
if (!this.bound) return
diff --git a/cli/src/services/AGENTS.md b/cli/src/services/AGENTS.md
index 7565d491e..14a16075a 100644
--- a/cli/src/services/AGENTS.md
+++ b/cli/src/services/AGENTS.md
@@ -179,14 +179,18 @@ like any other. Named in `HARNESSD_SERVICES`, it starts with the others.
a dial's port in /dev, a paired Wi-Fi device, or its session (`src/core/devicesWake.ts`). Models is asked
for as the core starts when grid is in use here: a managed grid, whose pin it follows, saved grid pictures,
which agents' grid notes are read from, or local models (`src/core/modelsWake.ts`); otherwise its first
- request asks for it.
+ request asks for it. The gateway is asked for as the core starts, before it binds, when this machine is
+ signed in or has anything paired or linked directly (`src/core/gatewayWake.ts`), so the relay comes up
+ beside the core as before; otherwise by what needs it (`src/core/gatewayLink.ts`): a pairing, a window's
+ E2EE request or session to another machine, which wait for its first start, a key or device command, or
+ the Wi-Fi device's service. `/api/status` never starts it.
- **Older cores.** `askedSince` is the core protocol (`HARNESSD_PROTOCOL`, `src/harnessd/protocol.ts`) from
which a core asks for this process. A core that speaks an older one never asks, so the master starts the
process as that core binds (`ServiceSupervisor.unasked`). It is 3 by default, the experiments'; the
- devices and models became on demand at protocol 4. Making another process on demand needs a protocol bump, and that
+ devices, models and the gateway became on demand at protocol 4, which may also ask before it binds. Making another process on demand needs a protocol bump, and that
number in its `askedSince`.
-- **Proof.** `e2e/experiments.e2e.ts`, `e2e/devicesOnDemand.e2e.ts` and `e2e/modelsOnDemand.e2e.ts`: off, it has
- no process; asked for, it starts and answers.
+- **Proof.** `e2e/experiments.e2e.ts`, `e2e/devicesOnDemand.e2e.ts`, `e2e/modelsOnDemand.e2e.ts` and
+ `e2e/gatewayOnDemand.e2e.ts`: off, it has no process; asked for, it starts and answers.
## Experiments