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.

Reduce allocations for local terminal control messages (#633)

Deecfb2312bce3d
diff --git a/cli/scripts/benchmark-local-ws.mjs b/cli/scripts/benchmark-local-ws.mjs
new file mode 100644
index 000000000..31186e009
--- /dev/null
+++ b/cli/scripts/benchmark-local-ws.mjs
@@ -0,0 +1,132 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, writeFileSync, mkdirSync, symlinkSync, rmSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { spawnSync, execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { once } from 'node:events';
+import http from 'node:http';
+import { Session } from 'node:inspector';
+// Usage: node scripts/benchmark-local-ws.mjs BASELINE_REF /absolute/new/output-directory
+// Uses disposable loopback sockets only. No app, daemon, or engine session is started.
+const repo = fileURLToPath(new URL('../..', import.meta.url));
+const require = createRequire(join(repo, 'cli/package.json'));
+const { WebSocket } = require('ws');
+const args = process.argv.slice(2);
+if (args[0] === '--worker') {
+ const [_, bundle, mode, batchArg, countArg] = args;
+ const fixture = mkdtempSync(join(dirname(bundle), 'fixture-'));
+ Object.assign(process.env, {
+ ADAPTER_DATA_DIR: join(fixture, 'data'), ADAPTER_RUNTIME_DIR: join(fixture, 'runtime'),
+ ADAPTER_COMPUTER_ID_FILE: join(fixture, 'computer-id'), ADAPTER_COMPUTER_ID: 'benchmark-machine',
+ HARNESS_AUTH_DIR: join(fixture, 'auth'), DSH_DIR: join(fixture, 'dsh'), ZDOTDIR: fixture,
+ HARNESS_LESSONS_DIR: join(fixture, 'lessons'), HARNESS_STORE_CATALOG_URL: 'http://127.0.0.1:9/catalog.json',
+ });
+ const { attachLocalWsServer } = await import(pathToFileURL(bundle));
+ const batch = Number(batchArg), count = Number(countArg);
+ let sink, expected = 0, batchEnd = 0, dispatchError;
+ const backend = {
+ registerLocalClient(_id, value) { sink = value; return true; },
+ async unregisterLocalClient() {},
+ async handleLocalBinary() { throw new Error('unexpected binary'); },
+ handleLocalFrame(_id, frame) {
+ try {
+ assert.equal(frame.payload.sequence, expected);
+ assert.equal(frame.type, expected % 2 ? 'terminal_alive' : 'terminal_ack');
+ expected++;
+ if (expected === batchEnd) sink.sendFrame({ type: 'benchmark_batch', payload: { sequence: expected } });
+ } catch (error) { dispatchError = error; throw error; }
+ },
+ };
+ const server = http.createServer((_req, res) => { res.statusCode = 404; res.end(); });
+ const local = attachLocalWsServer(server, { machineId: 'benchmark-machine', backend });
+ let ws, inspector;
+ const deadline = setTimeout(() => { console.error('worker timeout'); process.exit(2); }, 30000);
+ try {
+ server.listen(0, '127.0.0.1'); await once(server, 'listening');
+ ws = new WebSocket(`ws://127.0.0.1:${server.address().port}/api/local-ws`);
+ await once(ws, 'open');
+ let reply = once(ws, 'message');
+ ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: 'benchmark-machine', localProtocolVersion: 1 } }));
+ assert.equal(JSON.parse((await reply)[0].toString()).type, 'connected');
+ async function run(frames) {
+ const end = expected + frames;
+ while (expected < end) {
+ const start = expected;
+ batchEnd = Math.min(start + batch, end);
+ const completed = once(ws, 'message');
+ for (let seq = start; seq < batchEnd; seq++) {
+ ws.send(JSON.stringify({ type: seq % 2 ? 'terminal_alive' : 'terminal_ack', payload: {
+ streamId: '00112233-4455-6677-8899-aabbccddeeff', sequence: seq, seq,
+ } }));
+ }
+ const received = JSON.parse((await completed)[0].toString());
+ if (dispatchError) throw dispatchError;
+ assert.equal(received.payload.sequence, batchEnd);
+ }
+ }
+ await run(batch === 1 ? 1500 : 5000);
+ let post;
+ if (mode === 'allocations') {
+ inspector = new Session(); inspector.connect();
+ post = (method, params = {}) => new Promise((resolve, reject) => inspector.post(method, params, (error, value) => error ? reject(error) : resolve(value)));
+ await post('HeapProfiler.startSampling', { samplingInterval: 4096, includeObjectsCollectedByMajorGC: true, includeObjectsCollectedByMinorGC: true });
+ }
+ const beforeMemory = process.memoryUsage(), beforeCpu = process.cpuUsage(), before = performance.now();
+ await run(count);
+ const durationMs = performance.now() - before, cpu = process.cpuUsage(beforeCpu), afterMemory = process.memoryUsage();
+ let allocationBytes = null;
+ if (mode === 'allocations') {
+ const { profile } = await post('HeapProfiler.stopSampling');
+ function sum(node) { return node.selfSize + node.children.reduce((n, child) => n + sum(child), 0); }
+ allocationBytes = sum(profile.head);
+ }
+ process.stdout.write(JSON.stringify({ mode, batch, count, durationMs, cpuUs: cpu.user + cpu.system, allocationBytes, beforeMemory, afterMemory, dispatched: expected }) + '\n');
+ } finally {
+ inspector?.disconnect();
+ if (ws?.readyState === WebSocket.OPEN) { const closed = once(ws, 'close'); ws.close(); await closed; }
+ await local.close(); await new Promise(resolve => server.close(resolve));
+ clearTimeout(deadline); rmSync(fixture, { recursive: true, force: true });
+ }
+} else {
+ assert.equal(args.length, 2, 'Expected BASELINE_REF and a new output directory');
+ const baselineRef = args[0];
+ const baselineSha = execFileSync('git', ['rev-parse', '--verify', baselineRef + '^{commit}'], { cwd: repo, encoding: 'utf8' }).trim();
+ const { build } = require('esbuild');
+ const out = resolve(args[1]);
+ mkdirSync(out);
+ symlinkSync(join(repo, 'cli/node_modules'), join(out, 'node_modules'), 'dir');
+ const inputs = {
+ baseline: execFileSync('git', ['show', baselineSha + ':cli/src/localWsServer.ts'], { cwd: repo, encoding: 'utf8' }),
+ candidate: readFileSync(join(repo, 'cli/src/localWsServer.ts'), 'utf8'),
+ };
+ for (const [variant, source] of Object.entries(inputs)) {
+ await build({ stdin: { contents: source, resolveDir: join(repo, 'cli/src'), sourcefile: 'localWsServer.ts', loader: 'ts' }, outfile: join(out, variant + '.mjs'), bundle: true, packages: 'external', platform: 'node', format: 'esm', target: 'node20', minify: true, logLevel: 'silent' });
+ }
+ const rows = [];
+ for (const mode of ['timing', 'allocations']) {
+ for (const batch of [1, 100]) {
+ for (let trial = 0; trial < (mode === 'timing' ? 6 : 3); trial++) {
+ for (const variant of (trial % 2 ? ['candidate', 'baseline'] : ['baseline', 'candidate'])) {
+ const result = spawnSync(process.execPath, [fileURLToPath(import.meta.url), '--worker', join(out, variant + '.mjs'), mode, String(batch), String(batch === 1 ? 6000 : 60000)], { encoding: 'utf8', timeout: 35000, maxBuffer: 1024 * 1024, cwd: out });
+ if (result.status !== 0) throw new Error(`${variant}/${mode}/${batch}: ${result.stderr}\n${result.stdout}`);
+ rows.push({ variant, trial, ...JSON.parse(result.stdout.trim()) });
+ }
+ }
+ }
+ }
+ const median = values => { const s = values.slice().sort((a,b) => a-b); const m = Math.floor(s.length/2); return s.length % 2 ? s[m] : (s[m-1]+s[m])/2; };
+ const summary = [];
+ for (const batch of [1, 100]) for (const metric of ['durationMs', 'cpuUs', 'allocationBytes']) {
+ const mode = metric === 'allocationBytes' ? 'allocations' : 'timing';
+ const group = rows.filter(r => r.batch === batch && r.mode === mode);
+ const baseline = median(group.filter(r => r.variant === 'baseline').map(r => r[metric]));
+ const candidate = median(group.filter(r => r.variant === 'candidate').map(r => r[metric]));
+ summary.push({ batch, metric, baseline, candidate, reductionPercent: (1-candidate/baseline)*100 });
+ }
+ const result = { baselineSha, sourceSha256: Object.fromEntries(Object.entries(inputs).map(([name, source]) => [name, createHash('sha256').update(source).digest('hex')])), finishedAt: new Date().toISOString(), node: process.version, platform: process.platform, arch: process.arch, scope: 'Real loopback WebSocket, synthetic ACK/alive frames, fake backend. CPU includes client and server. Allocation sampling runs separately. No live daemon or app changed.', rows, summary };
+ writeFileSync(join(out, 'results.json'), JSON.stringify(result,null,2)+'\n');
+ console.log(JSON.stringify({ directory: out, summary }, null, 2));
+}
diff --git a/cli/src/localWsServer.spec.ts b/cli/src/localWsServer.spec.ts
index 3a19d6e70..b290d4e5b 100644
--- a/cli/src/localWsServer.spec.ts
+++ b/cli/src/localWsServer.spec.ts
@@ -58,6 +58,12 @@ function onceMessage(ws: WebSocket): Promise<Frame> {
})
}
+function gate(): { promise: Promise<void>; resolve: () => void } {
+ let resolve!: () => void
+ const promise = new Promise<void>((done) => { resolve = done })
+ return { promise, resolve }
+}
+
describe('local CLI WebSocket', () => {
let server: http.Server | null = null
let local: LocalWsServer | null = null
@@ -279,6 +285,148 @@ describe('local CLI WebSocket', () => {
ws.close()
})
+ it.each(['local binary', 'remote JSON', 'remote binary', 'route task'] as const)(
+ 'keeps later messages behind an unfinished %s operation', async (kind) => {
+ const backend = new FakeBackend(), pending = gate(), entered = gate()
+ const trace: string[] = []
+ const first = async () => {
+ trace.push('first started')
+ entered.resolve()
+ await pending.promise
+ trace.push('first finished')
+ }
+ backend.handleLocalFrame = () => { trace.push('second') }
+ backend.handleLocalBinary = first
+ const remote = kind.startsWith('remote')
+ const relay = {
+ send: async (frame: Frame) => {
+ if ((frame.payload as { requestId?: string })?.requestId === 'first') await first()
+ else trace.push('second')
+ },
+ sendBinary: first,
+ detach: () => {},
+ }
+ const ws = new WebSocket(await start(backend, {
+ autonomousEnv: 'test',
+ relayPool: {
+ acquire: async (_id: string, _env: string, _select: Frame, sink: LocalClientSink) => {
+ sink.sendFrame({ type: 'connected', payload: {} })
+ return relay
+ },
+ } as unknown as LocalWsServerOptions['relayPool'],
+ async onRouteTask(this: LocalWsServerOptions) {
+ expect(this.machineId).toBe(machineId)
+ await first()
+ return { agentId: '', machineId: '', name: '', confidence: 0, reason: '', candidates: [], weighed: 0, machines: 0, via: '' }
+ },
+ }))
+ await onceOpen(ws)
+ const connected = onceMessage(ws)
+ ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: remote ? 'remote' : machineId, localProtocolVersion: 1 } }))
+ await connected
+ if (kind.endsWith('binary')) {
+ ws.send(encodeTerminalLocal({ kind: TerminalBinaryKind.input, streamId, seq: 1, bytes: new Uint8Array([97]), compressed: false })!)
+ } else {
+ ws.send(JSON.stringify({ type: kind === 'route task' ? 'route_task' : 'agents_list', payload: { requestId: 'first', text: 'route me' } }))
+ }
+ ws.send(JSON.stringify({ type: 'agents_list', payload: { requestId: 'second' } }))
+ await entered.promise
+ // Let the real socket deliver the queued frame while the first operation is held open.
+ await new Promise((resolve) => setTimeout(resolve, 20))
+ expect(trace).toEqual(['first started'])
+ pending.resolve()
+ await vi.waitFor(() => expect(trace).toEqual(['first started', 'first finished', 'second']))
+ ws.close()
+ },
+ )
+
+ it.each(['local JSON', 'local binary', 'remote JSON', 'remote binary'] as const)(
+ 'closes the socket when %s dispatch fails', async (kind) => {
+ const backend = new FakeBackend()
+ backend.handleLocalFrame = () => { throw new Error('dispatch failed') }
+ backend.handleLocalBinary = async () => { throw new Error('dispatch failed') }
+ const relay = { send: async () => { throw new Error('dispatch failed') }, sendBinary: async () => { throw new Error('dispatch failed') }, detach: () => {} }
+ const ws = new WebSocket(await start(backend, {
+ autonomousEnv: 'test',
+ relayPool: {
+ acquire: async (_id: string, _env: string, _select: Frame, sink: LocalClientSink) => {
+ sink.sendFrame({ type: 'connected', payload: {} })
+ return relay
+ },
+ } as unknown as LocalWsServerOptions['relayPool'],
+ }))
+ await onceOpen(ws)
+ const connected = onceMessage(ws)
+ ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: kind.startsWith('remote') ? 'remote' : machineId, localProtocolVersion: 1 } }))
+ await connected
+ const closed = new Promise<[number, string]>((resolve) => ws.once('close', (code, reason) => resolve([code, reason.toString()])))
+ if (kind.endsWith('binary')) {
+ ws.send(encodeTerminalLocal({ kind: TerminalBinaryKind.input, streamId, seq: 1, bytes: new Uint8Array([97]), compressed: false })!)
+ } else {
+ ws.send(JSON.stringify({ type: 'agents_list', payload: { requestId: 'first' } }))
+ }
+ await expect(closed).resolves.toEqual([1011, 'local dispatch failed'])
+ },
+ )
+
+ it.each(['owned', 'isolated', 'shared'] as const)(
+ 'queues frames during a pending %s relay handshake', async (kind) => {
+ const backend = new FakeBackend(), pending = gate(), entered = gate()
+ const frames: Frame[] = []
+ const acquire = vi.fn(async () => {
+ entered.resolve()
+ await pending.promise
+ return { send: async (frame: Frame) => { frames.push(frame) }, sendBinary: async () => {}, detach: () => {} }
+ })
+ const ws = new WebSocket(await start(backend, {
+ autonomousEnv: 'test',
+ relayPool: { acquire, acquireIsolated: acquire } as unknown as LocalWsServerOptions['relayPool'],
+ shareRelay: { acquire } as unknown as LocalWsServerOptions['shareRelay'],
+ }))
+ await onceOpen(ws)
+ ws.send(JSON.stringify({ type: 'machine_select', payload: {
+ machineId: 'remote', localProtocolVersion: 1,
+ ...(kind === 'shared' ? { shareId: 'share' } : {}), relayIsolation: kind === 'isolated',
+ } }))
+ ws.send(JSON.stringify({ type: 'agents_list', payload: { requestId: 'queued' } }))
+ await entered.promise
+ await new Promise((resolve) => setTimeout(resolve, 20))
+ expect(acquire).toHaveBeenCalledTimes(1)
+ expect(frames).toEqual([])
+ pending.resolve()
+ await vi.waitFor(() => expect(frames).toEqual([{ type: 'agents_list', payload: { requestId: 'queued' } }]))
+ expect(backend.frames).toEqual([])
+ ws.close()
+ },
+ )
+
+ it.each(['owned', 'shared'] as const)('detaches a late %s relay after its window disconnects', async (kind) => {
+ const backend = new FakeBackend(), pending = gate(), entered = gate(), disconnected = gate(), detach = vi.fn()
+ const acquire = async () => {
+ entered.resolve()
+ await pending.promise
+ return { send: async () => {}, sendBinary: async () => {}, detach }
+ }
+ const ws = new WebSocket(await start(backend, {
+ autonomousEnv: 'test',
+ relayPool: { acquire } as unknown as LocalWsServerOptions['relayPool'],
+ shareRelay: { acquire } as unknown as LocalWsServerOptions['shareRelay'],
+ }))
+ server!.once('connection', (socket) => socket.once('close', disconnected.resolve))
+ await onceOpen(ws)
+ ws.send(JSON.stringify({ type: 'machine_select', payload: {
+ machineId: 'remote', localProtocolVersion: 1, ...(kind === 'shared' ? { shareId: 'share' } : {}),
+ } }))
+ await entered.promise
+ const closed = new Promise<void>((resolve) => ws.once('close', () => resolve()))
+ ws.close()
+ await closed
+ await disconnected.promise
+ pending.resolve()
+ await vi.waitFor(() => expect(detach).toHaveBeenCalledTimes(1))
+ expect(backend.unregisters).toEqual([])
+ })
+
// A window from before it introduced itself on `terminal_open` still gets named on the far
// machine's "took control" banner: this daemon knows the window is its own desktop.
it('introduces a silent window on a relayed terminal_open, and believes one that speaks', async () => {
diff --git a/cli/src/localWsServer.ts b/cli/src/localWsServer.ts
index 310f421e5..4ad5371cf 100644
--- a/cli/src/localWsServer.ts
+++ b/cli/src/localWsServer.ts
@@ -382,91 +382,95 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
try { ws.close(code, reason) } catch { ws.terminate() }
}
- ws.on('message', (raw, isBinary) => {
- chain = chain.then(async () => {
- if (!selected) {
- if (isBinary) { close(4400, 'machine_select required'); return }
- const frame = jsonFrame(raw)
- const payload = frame?.payload as Record<string, unknown> | undefined
- const requestedMachineId = payload?.machineId
- if (typeof requestedMachineId === 'string') boundMachineId = requestedMachineId
- if (frame?.type !== 'machine_select'
- || typeof requestedMachineId !== 'string'
- || payload?.localProtocolVersion !== LOCAL_WS_PROTOCOL_VERSION) {
- close(4403, 'machine mismatch')
- return
- }
- if (typeof payload.shareId === 'string') {
- if (!options.shareRelay) { close(4403, 'Sharing is unavailable'); return }
- try {
- relay = await options.shareRelay.acquire(requestedMachineId, payload.shareId, terminalSink, close)
- if (ws.readyState !== WebSocket.OPEN) { relay.detach(); return }
- selected = true
- } catch (error) {
- close(error instanceof SharingEndedError ? 4403 : 1013,
- error instanceof Error ? error.message.slice(0, 120) : 'Sharing unavailable')
- }
- return
- }
- if (requestedMachineId === options.machineId) {
- tool = payload.tool === true
- if (!options.backend.registerLocalClient(connId, terminalSink, tool ? { tool: true } : {})) {
- close(1011, 'local registration failed')
- return
- }
- selected = true
- windowSinks.set(connId, sink)
- sink.sendFrame({
- type: 'connected',
- payload: {
- machineId: options.machineId,
- transport: 'local',
- localProtocolVersion: LOCAL_WS_PROTOCOL_VERSION,
- terminalProtocolVersion: TERMINAL_BINARY_VERSION,
- e2ee: false,
- },
- })
- // Right after, not inside `connected`: the window's handshake parser is shared with the
- // relay path, and a field it does not expect is a field it has to learn to ignore.
- if (options.dialStatus) sink.sendFrame({ type: 'dial_status', payload: options.dialStatus() })
- if (options.openQuestions) {
- const open = options.openQuestions()
- for (const asked of open) sink.sendFrame(asked)
- // Then which questions are open at all, so a window that was here before (its link
- // dropped) lets go of one answered meanwhile. Sent even when there are none.
- const requestIds = open.map((f) => (f.payload as { requestId?: unknown } | undefined)?.requestId).filter((id): id is string => typeof id === 'string')
- sink.sendFrame({ type: 'commander_questions_open', payload: { requestIds } })
- }
- return
- }
- // Not this daemon's own machine — relay to backend for the other machines this same
- // signed-in user owns, if the daemon was wired up to do that (see lib/remoteRelay.ts).
- if (!options.relayPool || !options.autonomousEnv) {
- close(4403, 'machine mismatch')
- return
- }
- // The local client observed a live RPC time out against an otherwise-"connected" machine —
- // its pooled entry is suspect (most commonly the relayed machine's own Harness process
- // restarted, dropping its E2EE session without the transport itself ever closing). Drop it
- // so this select dials fresh instead of handing back the same dead session again.
- if (payload?.forceReconnect === true) {
- if (payload?.relayIsolation === true) options.relayPool.invalidateIsolated(requestedMachineId)
- else options.relayPool.invalidate(requestedMachineId)
- }
- try {
- relay = payload?.relayIsolation === true
- ? await options.relayPool.acquireIsolated(requestedMachineId, options.autonomousEnv, frame, terminalSink, close)
- : await options.relayPool.acquire(requestedMachineId, options.autonomousEnv, frame, terminalSink, close)
- if (ws.readyState !== WebSocket.OPEN) { relay.detach(); return }
- selected = true
- windowSinks.set(connId, sink)
- } catch (err) {
- const noPeerLink = err instanceof RelayConnectError && err.message === 'NO_PEER_LINK'
- const code = noPeerLink ? 4404 : err instanceof RelayConnectError && err.closeCode ? err.closeCode : 1011
- close(code, err instanceof Error ? err.message.slice(0, 120) : 'relay failed')
- }
+ // The handshake is asynchronous; established local control frames are not.
+ // Keep its suspension state out of the per-message hot path.
+ const selectMachine = async (raw: RawData, isBinary: boolean): Promise<void> => {
+ if (isBinary) { close(4400, 'machine_select required'); return }
+ const frame = jsonFrame(raw)
+ const payload = frame?.payload as Record<string, unknown> | undefined
+ const requestedMachineId = payload?.machineId
+ if (typeof requestedMachineId === 'string') boundMachineId = requestedMachineId
+ if (frame?.type !== 'machine_select'
+ || typeof requestedMachineId !== 'string'
+ || payload?.localProtocolVersion !== LOCAL_WS_PROTOCOL_VERSION) {
+ close(4403, 'machine mismatch')
+ return
+ }
+ if (typeof payload.shareId === 'string') {
+ if (!options.shareRelay) { close(4403, 'Sharing is unavailable'); return }
+ try {
+ relay = await options.shareRelay.acquire(requestedMachineId, payload.shareId, terminalSink, close)
+ if (ws.readyState !== WebSocket.OPEN) { relay.detach(); return }
+ selected = true
+ } catch (error) {
+ close(error instanceof SharingEndedError ? 4403 : 1013,
+ error instanceof Error ? error.message.slice(0, 120) : 'Sharing unavailable')
+ }
+ return
+ }
+ if (requestedMachineId === options.machineId) {
+ tool = payload.tool === true
+ if (!options.backend.registerLocalClient(connId, terminalSink, tool ? { tool: true } : {})) {
+ close(1011, 'local registration failed')
return
}
+ selected = true
+ windowSinks.set(connId, sink)
+ sink.sendFrame({
+ type: 'connected',
+ payload: {
+ machineId: options.machineId,
+ transport: 'local',
+ localProtocolVersion: LOCAL_WS_PROTOCOL_VERSION,
+ terminalProtocolVersion: TERMINAL_BINARY_VERSION,
+ e2ee: false,
+ },
+ })
+ // Right after, not inside `connected`: the window's handshake parser is shared with the
+ // relay path, and a field it does not expect is a field it has to learn to ignore.
+ if (options.dialStatus) sink.sendFrame({ type: 'dial_status', payload: options.dialStatus() })
+ if (options.openQuestions) {
+ const open = options.openQuestions()
+ for (const asked of open) sink.sendFrame(asked)
+ // Then which questions are open at all, so a window that was here before (its link
+ // dropped) lets go of one answered meanwhile. Sent even when there are none.
+ const requestIds = open.map((f) => (f.payload as { requestId?: unknown } | undefined)?.requestId).filter((id): id is string => typeof id === 'string')
+ sink.sendFrame({ type: 'commander_questions_open', payload: { requestIds } })
+ }
+ return
+ }
+ // Not this daemon's own machine — relay to backend for the other machines this same
+ // signed-in user owns, if the daemon was wired up to do that (see lib/remoteRelay.ts).
+ if (!options.relayPool || !options.autonomousEnv) {
+ close(4403, 'machine mismatch')
+ return
+ }
+ // The local client observed a live RPC time out against an otherwise-"connected" machine —
+ // its pooled entry is suspect (most commonly the relayed machine's own Harness process
+ // restarted, dropping its E2EE session without the transport itself ever closing). Drop it
+ // so this select dials fresh instead of handing back the same dead session again.
+ if (payload?.forceReconnect === true) {
+ if (payload?.relayIsolation === true) options.relayPool.invalidateIsolated(requestedMachineId)
+ else options.relayPool.invalidate(requestedMachineId)
+ }
+ try {
+ relay = payload?.relayIsolation === true
+ ? await options.relayPool.acquireIsolated(requestedMachineId, options.autonomousEnv, frame, terminalSink, close)
+ : await options.relayPool.acquire(requestedMachineId, options.autonomousEnv, frame, terminalSink, close)
+ if (ws.readyState !== WebSocket.OPEN) { relay.detach(); return }
+ selected = true
+ windowSinks.set(connId, sink)
+ } catch (err) {
+ const noPeerLink = err instanceof RelayConnectError && err.message === 'NO_PEER_LINK'
+ const code = noPeerLink ? 4404 : err instanceof RelayConnectError && err.closeCode ? err.closeCode : 1011
+ close(code, err instanceof Error ? err.message.slice(0, 120) : 'relay failed')
+ }
+ return
+ }
+
+ ws.on('message', (raw, isBinary) => {
+ chain = chain.then(() => {
+ if (!selected) return selectMachine(raw, isBinary)
// Parsed ONCE. Every sniff below used to re-run JSON.parse on the same bytes — up to seven
// times for a frame that matched none of them, which is what a terminal_ack (every 16ms of
@@ -588,21 +592,24 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
// act on.
if (!isBinary && (options.onRouteTask || options.onRouteSend || options.onVoiceRouteReply)) {
if (parsed?.type === 'route_task' && options.onRouteTask) {
- const payload = parsed.payload as Record<string, unknown> | undefined
- const requestId = typeof payload?.requestId === 'string' ? payload.requestId : ''
- const text = typeof payload?.text === 'string' ? payload.text.trim() : ''
- // An answer ALWAYS goes back, even for a question we cannot serve: the window is holding a
- // spinner open on this id, and silence is the one reply it cannot recover from.
- let answer: RouteAnswer = { agentId: '', machineId: '', name: '', confidence: 0, reason: 'empty task', candidates: [], weighed: 0, machines: 0, via: '' }
- if (text) {
- try {
- answer = await options.onRouteTask(text)
- } catch (err) {
- answer = { agentId: '', machineId: '', name: '', confidence: 0, reason: (err as Error).message.slice(0, 120), candidates: [], weighed: 0, machines: 0, via: '' }
+ const onRouteTask = options.onRouteTask
+ return (async () => {
+ const payload = parsed.payload as Record<string, unknown> | undefined
+ const requestId = typeof payload?.requestId === 'string' ? payload.requestId : ''
+ const text = typeof payload?.text === 'string' ? payload.text.trim() : ''
+ // An answer ALWAYS goes back, even for a question we cannot serve: the window is holding a
+ // spinner open on this id, and silence is the one reply it cannot recover from.
+ let answer: RouteAnswer = { agentId: '', machineId: '', name: '', confidence: 0, reason: 'empty task', candidates: [], weighed: 0, machines: 0, via: '' }
+ if (text) {
+ try {
+ answer = await onRouteTask.call(options, text)
+ } catch (err) {
+ answer = { agentId: '', machineId: '', name: '', confidence: 0, reason: (err as Error).message.slice(0, 120), candidates: [], weighed: 0, machines: 0, via: '' }
+ }
}
- }
- sink.sendFrame({ type: 'route_result', payload: { requestId, ...answer } })
- return
+ sink.sendFrame({ type: 'route_result', payload: { requestId, ...answer } })
+ return
+ })()
}
if (parsed?.type === 'voice_route_reply' && options.onVoiceRouteReply) {
const payload = parsed.payload as Record<string, unknown> | undefined
@@ -731,19 +738,16 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
if (isBinary) {
const clear = decodeTerminalLocal(binaryBytes(raw))
if (!clear) { close(4400, 'invalid terminal frame'); return }
- await relay.sendBinary(clear)
- return
+ return relay.sendBinary(clear)
}
if (!parsed) { close(4400, 'invalid json frame'); return }
- await relay.send(withLocalClient(parsed, options.localClient))
- return
+ return relay.send(withLocalClient(parsed, options.localClient))
}
if (isBinary) {
const frame = decodeTerminalLocal(binaryBytes(raw))
if (!frame) { close(4400, 'invalid terminal frame'); return }
- await options.backend.handleLocalBinary(connId, frame)
- return
+ return options.backend.handleLocalBinary(connId, frame)
}
if (!parsed) { close(4400, 'invalid json frame'); return }
options.backend.handleLocalFrame(connId, parsed)
diff --git a/docs/performance/2026-10-02-local-message-allocations.json b/docs/performance/2026-10-02-local-message-allocations.json
new file mode 100644
index 000000000..6d9360206
--- /dev/null
+++ b/docs/performance/2026-10-02-local-message-allocations.json
@@ -0,0 +1,982 @@
+{
+ "baselineSha": "aad71fc576a0a9b0d9b52a2b206d02d08b481967",
+ "sourceSha256": {
+ "baseline": "0156bf993b28ac3421c8aede6f240fb0c22286be440ff027163d9ebf23469882",
+ "candidate": "11d66660996894ccd0339fd429416dbbc6f3ef38d6ab5c38b921bc84261dff8c"
+ },
+ "finishedAt": "2026-10-02T17:28:59.172Z",
+ "node": "v22.23.2",
+ "platform": "darwin",
+ "arch": "arm64",
+ "scope": "Real loopback WebSocket, synthetic ACK/alive frames, fake backend. CPU includes client and server. Allocation sampling runs separately. No live daemon or app changed.",
+ "rows": [
+ {
+ "variant": "baseline",
+ "trial": 0,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 184.186,
+ "cpuUs": 224535,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 111149056,
+ "heapTotal": 56901632,
+ "heapUsed": 29586736,
+ "external": 4197370,
+ "arrayBuffers": 411037
+ },
+ "afterMemory": {
+ "rss": 121815040,
+ "heapTotal": 57163776,
+ "heapUsed": 31131432,
+ "external": 4286784,
+ "arrayBuffers": 500411
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "candidate",
+ "trial": 0,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 195.801417,
+ "cpuUs": 233321,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 111378432,
+ "heapTotal": 57163776,
+ "heapUsed": 28566640,
+ "external": 4182353,
+ "arrayBuffers": 396020
+ },
+ "afterMemory": {
+ "rss": 122028032,
+ "heapTotal": 57425920,
+ "heapUsed": 25930184,
+ "external": 4122350,
+ "arrayBuffers": 335977
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "candidate",
+ "trial": 1,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 185.106416,
+ "cpuUs": 218851,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 110297088,
+ "heapTotal": 56901632,
+ "heapUsed": 28557640,
+ "external": 4182298,
+ "arrayBuffers": 395965
+ },
+ "afterMemory": {
+ "rss": 121012224,
+ "heapTotal": 57163776,
+ "heapUsed": 25866896,
+ "external": 4121530,
+ "arrayBuffers": 335157
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "baseline",
+ "trial": 1,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 182.397292,
+ "cpuUs": 221784,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 111312896,
+ "heapTotal": 57163776,
+ "heapUsed": 29582680,
+ "external": 4197370,
+ "arrayBuffers": 411037
+ },
+ "afterMemory": {
+ "rss": 120832000,
+ "heapTotal": 57425920,
+ "heapUsed": 31081496,
+ "external": 4286028,
+ "arrayBuffers": 499655
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "baseline",
+ "trial": 2,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 178.41716599999998,
+ "cpuUs": 219949,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 111362048,
+ "heapTotal": 57425920,
+ "heapUsed": 29579400,
+ "external": 4197254,
+ "arrayBuffers": 410921
+ },
+ "afterMemory": {
+ "rss": 121110528,
+ "heapTotal": 57688064,
+ "heapUsed": 31120640,
+ "external": 4286552,
+ "arrayBuffers": 500179
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "candidate",
+ "trial": 2,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 183.159875,
+ "cpuUs": 222702,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 110198784,
+ "heapTotal": 56639488,
+ "heapUsed": 28572712,
+ "external": 4182353,
+ "arrayBuffers": 396020
+ },
+ "afterMemory": {
+ "rss": 120782848,
+ "heapTotal": 56901632,
+ "heapUsed": 25865568,
+ "external": 4120306,
+ "arrayBuffers": 333933
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "candidate",
+ "trial": 3,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 188.43008300000002,
+ "cpuUs": 226508,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 110919680,
+ "heapTotal": 56639488,
+ "heapUsed": 28570608,
+ "external": 4182353,
+ "arrayBuffers": 396020
+ },
+ "afterMemory": {
+ "rss": 121569280,
+ "heapTotal": 56901632,
+ "heapUsed": 25929376,
+ "external": 4121706,
+ "arrayBuffers": 335333
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "baseline",
+ "trial": 3,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 188.73499999999999,
+ "cpuUs": 225303,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 111280128,
+ "heapTotal": 56901632,
+ "heapUsed": 29584424,
+ "external": 4197370,
+ "arrayBuffers": 411037
+ },
+ "afterMemory": {
+ "rss": 121110528,
+ "heapTotal": 57163776,
+ "heapUsed": 31189000,
+ "external": 4287428,
+ "arrayBuffers": 501055
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "baseline",
+ "trial": 4,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 181.326916,
+ "cpuUs": 221302,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 111165440,
+ "heapTotal": 56901632,
+ "heapUsed": 29567568,
+ "external": 4197254,
+ "arrayBuffers": 410921
+ },
+ "afterMemory": {
+ "rss": 120684544,
+ "heapTotal": 57163776,
+ "heapUsed": 31146472,
+ "external": 4286784,
+ "arrayBuffers": 500411
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "candidate",
+ "trial": 4,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 189.30058300000002,
+ "cpuUs": 224874,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 110592000,
+ "heapTotal": 56901632,
+ "heapUsed": 28573400,
+ "external": 4182353,
+ "arrayBuffers": 396020
+ },
+ "afterMemory": {
+ "rss": 121290752,
+ "heapTotal": 57163776,
+ "heapUsed": 24877024,
+ "external": 4086246,
+ "arrayBuffers": 299873
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "candidate",
+ "trial": 5,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 219.559166,
+ "cpuUs": 249670,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 111034368,
+ "heapTotal": 57163776,
+ "heapUsed": 28561328,
+ "external": 4182351,
+ "arrayBuffers": 396018
+ },
+ "afterMemory": {
+ "rss": 121929728,
+ "heapTotal": 57425920,
+ "heapUsed": 25938440,
+ "external": 4122515,
+ "arrayBuffers": 336142
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "baseline",
+ "trial": 5,
+ "mode": "timing",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 192.891625,
+ "cpuUs": 231574,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 110903296,
+ "heapTotal": 56639488,
+ "heapUsed": 29577512,
+ "external": 4197370,
+ "arrayBuffers": 411037
+ },
+ "afterMemory": {
+ "rss": 120553472,
+ "heapTotal": 56901632,
+ "heapUsed": 31090728,
+ "external": 4286084,
+ "arrayBuffers": 499711
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "baseline",
+ "trial": 0,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 244.64566700000003,
+ "cpuUs": 256921,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 115605504,
+ "heapTotal": 56901632,
+ "heapUsed": 33453312,
+ "external": 4777972,
+ "arrayBuffers": 991639
+ },
+ "afterMemory": {
+ "rss": 121765888,
+ "heapTotal": 57163776,
+ "heapUsed": 25968904,
+ "external": 4308421,
+ "arrayBuffers": 522048
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "candidate",
+ "trial": 0,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 239.31120800000002,
+ "cpuUs": 246401,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 111624192,
+ "heapTotal": 56639488,
+ "heapUsed": 29941528,
+ "external": 4701023,
+ "arrayBuffers": 914690
+ },
+ "afterMemory": {
+ "rss": 121192448,
+ "heapTotal": 56639488,
+ "heapUsed": 32062264,
+ "external": 4956100,
+ "arrayBuffers": 1169727
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "candidate",
+ "trial": 1,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 245.600917,
+ "cpuUs": 250782,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 112394240,
+ "heapTotal": 56901632,
+ "heapUsed": 29968192,
+ "external": 4701023,
+ "arrayBuffers": 914690
+ },
+ "afterMemory": {
+ "rss": 121962496,
+ "heapTotal": 56901632,
+ "heapUsed": 32632632,
+ "external": 5004990,
+ "arrayBuffers": 1218617
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "baseline",
+ "trial": 1,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 246.938958,
+ "cpuUs": 260071,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 115212288,
+ "heapTotal": 57425920,
+ "heapUsed": 33453712,
+ "external": 4789752,
+ "arrayBuffers": 1003419
+ },
+ "afterMemory": {
+ "rss": 121176064,
+ "heapTotal": 57425920,
+ "heapUsed": 27470056,
+ "external": 4414271,
+ "arrayBuffers": 627898
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "baseline",
+ "trial": 2,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 243.734333,
+ "cpuUs": 252237,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 115785728,
+ "heapTotal": 56639488,
+ "heapUsed": 33456616,
+ "external": 4789752,
+ "arrayBuffers": 1003419
+ },
+ "afterMemory": {
+ "rss": 121782272,
+ "heapTotal": 56639488,
+ "heapUsed": 26935168,
+ "external": 4389339,
+ "arrayBuffers": 602966
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "candidate",
+ "trial": 2,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 242.68029099999998,
+ "cpuUs": 249462,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 112705536,
+ "heapTotal": 57163776,
+ "heapUsed": 30189208,
+ "external": 4712924,
+ "arrayBuffers": 926591
+ },
+ "afterMemory": {
+ "rss": 121847808,
+ "heapTotal": 57163776,
+ "heapUsed": 31935288,
+ "external": 4939605,
+ "arrayBuffers": 1153232
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "candidate",
+ "trial": 3,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 245.96175,
+ "cpuUs": 250692,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 113639424,
+ "heapTotal": 56901632,
+ "heapUsed": 30162696,
+ "external": 4712924,
+ "arrayBuffers": 926591
+ },
+ "afterMemory": {
+ "rss": 122945536,
+ "heapTotal": 56901632,
+ "heapUsed": 32874976,
+ "external": 5017036,
+ "arrayBuffers": 1230663
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "baseline",
+ "trial": 3,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 241.28799999999998,
+ "cpuUs": 253882,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 115458048,
+ "heapTotal": 57163776,
+ "heapUsed": 33450424,
+ "external": 4789752,
+ "arrayBuffers": 1003419
+ },
+ "afterMemory": {
+ "rss": 121700352,
+ "heapTotal": 57163776,
+ "heapUsed": 26202248,
+ "external": 4332257,
+ "arrayBuffers": 545884
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "baseline",
+ "trial": 4,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 255.667542,
+ "cpuUs": 264703,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 116391936,
+ "heapTotal": 56901632,
+ "heapUsed": 33425096,
+ "external": 4789752,
+ "arrayBuffers": 1003419
+ },
+ "afterMemory": {
+ "rss": 122503168,
+ "heapTotal": 56901632,
+ "heapUsed": 27104728,
+ "external": 4397588,
+ "arrayBuffers": 611215
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "candidate",
+ "trial": 4,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 244.4445,
+ "cpuUs": 255167,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 111624192,
+ "heapTotal": 56901632,
+ "heapUsed": 30111040,
+ "external": 4701144,
+ "arrayBuffers": 914811
+ },
+ "afterMemory": {
+ "rss": 120995840,
+ "heapTotal": 56901632,
+ "heapUsed": 32846360,
+ "external": 5017036,
+ "arrayBuffers": 1230663
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "candidate",
+ "trial": 5,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 239.602167,
+ "cpuUs": 247644,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 111493120,
+ "heapTotal": 56377344,
+ "heapUsed": 30185384,
+ "external": 4712924,
+ "arrayBuffers": 926591
+ },
+ "afterMemory": {
+ "rss": 120668160,
+ "heapTotal": 56377344,
+ "heapUsed": 32246136,
+ "external": 4959954,
+ "arrayBuffers": 1173581
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "baseline",
+ "trial": 5,
+ "mode": "timing",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 250.46754199999998,
+ "cpuUs": 258295,
+ "allocationBytes": null,
+ "beforeMemory": {
+ "rss": 115933184,
+ "heapTotal": 56901632,
+ "heapUsed": 33377488,
+ "external": 4789751,
+ "arrayBuffers": 1003418
+ },
+ "afterMemory": {
+ "rss": 122159104,
+ "heapTotal": 56901632,
+ "heapUsed": 26801360,
+ "external": 4393734,
+ "arrayBuffers": 607361
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "baseline",
+ "trial": 0,
+ "mode": "allocations",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 239.62333399999997,
+ "cpuUs": 269715,
+ "allocationBytes": 54916696,
+ "beforeMemory": {
+ "rss": 113442816,
+ "heapTotal": 56901632,
+ "heapUsed": 29594224,
+ "external": 4197254,
+ "arrayBuffers": 410921
+ },
+ "afterMemory": {
+ "rss": 124223488,
+ "heapTotal": 57163776,
+ "heapUsed": 31157208,
+ "external": 4287308,
+ "arrayBuffers": 500935
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "candidate",
+ "trial": 0,
+ "mode": "allocations",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 230.465458,
+ "cpuUs": 262468,
+ "allocationBytes": 50293944,
+ "beforeMemory": {
+ "rss": 110526464,
+ "heapTotal": 56901632,
+ "heapUsed": 28592520,
+ "external": 4182353,
+ "arrayBuffers": 396020
+ },
+ "afterMemory": {
+ "rss": 122322944,
+ "heapTotal": 57163776,
+ "heapUsed": 25915240,
+ "external": 4121650,
+ "arrayBuffers": 335277
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "candidate",
+ "trial": 1,
+ "mode": "allocations",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 238.20437499999997,
+ "cpuUs": 264985,
+ "allocationBytes": 50291928,
+ "beforeMemory": {
+ "rss": 110051328,
+ "heapTotal": 56901632,
+ "heapUsed": 28585064,
+ "external": 4182353,
+ "arrayBuffers": 396020
+ },
+ "afterMemory": {
+ "rss": 122388480,
+ "heapTotal": 57163776,
+ "heapUsed": 25869688,
+ "external": 4121006,
+ "arrayBuffers": 334633
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "baseline",
+ "trial": 1,
+ "mode": "allocations",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 239.948917,
+ "cpuUs": 269375,
+ "allocationBytes": 54934984,
+ "beforeMemory": {
+ "rss": 111788032,
+ "heapTotal": 56901632,
+ "heapUsed": 29599792,
+ "external": 4197370,
+ "arrayBuffers": 411037
+ },
+ "afterMemory": {
+ "rss": 122748928,
+ "heapTotal": 57163776,
+ "heapUsed": 31102912,
+ "external": 4286028,
+ "arrayBuffers": 499655
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "baseline",
+ "trial": 2,
+ "mode": "allocations",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 240.03670900000003,
+ "cpuUs": 271579,
+ "allocationBytes": 54923744,
+ "beforeMemory": {
+ "rss": 111706112,
+ "heapTotal": 56901632,
+ "heapUsed": 29596784,
+ "external": 4197252,
+ "arrayBuffers": 410919
+ },
+ "afterMemory": {
+ "rss": 122535936,
+ "heapTotal": 57163776,
+ "heapUsed": 31198160,
+ "external": 4287187,
+ "arrayBuffers": 500814
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "candidate",
+ "trial": 2,
+ "mode": "allocations",
+ "batch": 1,
+ "count": 6000,
+ "durationMs": 242.70366700000002,
+ "cpuUs": 269772,
+ "allocationBytes": 50411592,
+ "beforeMemory": {
+ "rss": 110444544,
+ "heapTotal": 56639488,
+ "heapUsed": 28589008,
+ "external": 4182351,
+ "arrayBuffers": 396018
+ },
+ "afterMemory": {
+ "rss": 122552320,
+ "heapTotal": 56901632,
+ "heapUsed": 25862800,
+ "external": 4120765,
+ "arrayBuffers": 334392
+ },
+ "dispatched": 7500
+ },
+ {
+ "variant": "baseline",
+ "trial": 0,
+ "mode": "allocations",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 351.00879199999997,
+ "cpuUs": 361362,
+ "allocationBytes": 223778336,
+ "beforeMemory": {
+ "rss": 116162560,
+ "heapTotal": 56639488,
+ "heapUsed": 33457032,
+ "external": 4789752,
+ "arrayBuffers": 1003419
+ },
+ "afterMemory": {
+ "rss": 127107072,
+ "heapTotal": 56639488,
+ "heapUsed": 28212384,
+ "external": 4475019,
+ "arrayBuffers": 688646
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "candidate",
+ "trial": 0,
+ "mode": "allocations",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 330.7920419999999,
+ "cpuUs": 336989,
+ "allocationBytes": 179219672,
+ "beforeMemory": {
+ "rss": 114114560,
+ "heapTotal": 57163776,
+ "heapUsed": 30099968,
+ "external": 4701144,
+ "arrayBuffers": 914811
+ },
+ "afterMemory": {
+ "rss": 127254528,
+ "heapTotal": 57163776,
+ "heapUsed": 32531000,
+ "external": 4988495,
+ "arrayBuffers": 1202122
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "candidate",
+ "trial": 1,
+ "mode": "allocations",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 331.02845899999994,
+ "cpuUs": 337814,
+ "allocationBytes": 179647928,
+ "beforeMemory": {
+ "rss": 112066560,
+ "heapTotal": 56901632,
+ "heapUsed": 30137688,
+ "external": 4701444,
+ "arrayBuffers": 915111
+ },
+ "afterMemory": {
+ "rss": 125222912,
+ "heapTotal": 56901632,
+ "heapUsed": 32268936,
+ "external": 4948474,
+ "arrayBuffers": 1162101
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "baseline",
+ "trial": 1,
+ "mode": "allocations",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 380.814833,
+ "cpuUs": 389620,
+ "allocationBytes": 223563704,
+ "beforeMemory": {
+ "rss": 115654656,
+ "heapTotal": 56639488,
+ "heapUsed": 33412608,
+ "external": 4778272,
+ "arrayBuffers": 991939
+ },
+ "afterMemory": {
+ "rss": 125992960,
+ "heapTotal": 56639488,
+ "heapUsed": 28508216,
+ "external": 4475639,
+ "arrayBuffers": 689266
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "baseline",
+ "trial": 2,
+ "mode": "allocations",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 382.009959,
+ "cpuUs": 391742,
+ "allocationBytes": 225631392,
+ "beforeMemory": {
+ "rss": 115736576,
+ "heapTotal": 56901632,
+ "heapUsed": 33322344,
+ "external": 4789752,
+ "arrayBuffers": 1003419
+ },
+ "afterMemory": {
+ "rss": 126009344,
+ "heapTotal": 56901632,
+ "heapUsed": 29037440,
+ "external": 4512051,
+ "arrayBuffers": 725678
+ },
+ "dispatched": 65000
+ },
+ {
+ "variant": "candidate",
+ "trial": 2,
+ "mode": "allocations",
+ "batch": 100,
+ "count": 60000,
+ "durationMs": 336.49366699999996,
+ "cpuUs": 342848,
+ "allocationBytes": 179608824,
+ "beforeMemory": {
+ "rss": 112508928,
+ "heapTotal": 57163776,
+ "heapUsed": 30218864,
+ "external": 4689535,
+ "arrayBuffers": 903202
+ },
+ "afterMemory": {
+ "rss": 125534208,
+ "heapTotal": 57163776,
+ "heapUsed": 33173104,
+ "external": 5025776,
+ "arrayBuffers": 1239403
+ },
+ "dispatched": 65000
+ }
+ ],
+ "summary": [
+ {
+ "batch": 1,
+ "metric": "durationMs",
+ "baseline": 183.29164600000001,
+ "candidate": 188.86533300000002,
+ "reductionPercent": -3.0408843619637693
+ },
+ {
+ "batch": 1,
+ "metric": "cpuUs",
+ "baseline": 223159.5,
+ "candidate": 225691,
+ "reductionPercent": -1.1343904247858694
+ },
+ {
+ "batch": 1,
+ "metric": "allocationBytes",
+ "baseline": 54923744,
+ "candidate": 50293944,
+ "reductionPercent": 8.429505461244592
+ },
+ {
+ "batch": 100,
+ "metric": "durationMs",
+ "baseline": 245.79231250000004,
+ "candidate": 243.56239549999998,
+ "reductionPercent": 0.9072362667974287
+ },
+ {
+ "batch": 100,
+ "metric": "cpuUs",
+ "baseline": 257608,
+ "candidate": 250077,
+ "reductionPercent": 2.9234340548430215
+ },
+ {
+ "batch": 100,
+ "metric": "allocationBytes",
+ "baseline": 223778336,
+ "candidate": 179608824,
+ "reductionPercent": 19.738064367410434
+ }
+ ],
+ "validation": {
+ "scope": "Typecheck, affected real-socket/relay/terminal/liveness tests locally; full CLI and OS/Node matrix in CI before merge. No production deployment.",
+ "localReceipt": ".harness/validation/20261002T172805.569874Z-43894/receipt.json",
+ "tests": {
+ "files": 7,
+ "passed": 189,
+ "failed": 0,
+ "localWebSocketCases": 47,
+ "newLocalWebSocketCases": 13
+ },
+ "typecheck": "passed",
+ "initialFixtureFailure": {
+ "receipt": ".harness/validation/20261002T172640.119595Z-19381/receipt.json",
+ "description": "Two new late-acquire cases resumed after client close but before server close; fixture corrected to wait for server-side close. Final cases pass."
+ }
+ },
+ "limitations": [
+ "Synthetic component benchmark, not whole-app energy or retained RAM.",
+ "Both variants use the candidate dependency graph; only localWsServer.ts differs.",
+ "Six paired alternating timing trials and three paired allocation trials per traffic shape.",
+ "Allocation sampling includes collected objects and runs separately from timing.",
+ "Live app and daemon were not replaced, restarted, or upgraded.",
+ "No release authorized."
+ ]
+}
diff --git a/docs/performance/2026-10-02-local-message-allocations.md b/docs/performance/2026-10-02-local-message-allocations.md
new file mode 100644
index 000000000..ee5220a16
--- /dev/null
+++ b/docs/performance/2026-10-02-local-message-allocations.md
@@ -0,0 +1,71 @@
+# Local terminal message allocations — October 2, 2026
+
+Established local WebSocket connections receive frequent synchronous JSON control
+messages, including terminal acknowledgements and liveness notices. The entire
+message handler was `async` even when it did no asynchronous work. This allocated
+extra promises and suspension state for every such message.
+
+The handler now returns synchronously for those paths. Handshake and task routing
+retain their asynchronous handlers; binary operations and remote forwarding return
+their existing promises. The same per-connection promise chain still serializes
+all messages and catches failures. Routing callbacks retain their original receiver.
+No wire format, authorization, heartbeat, buffering, or terminal scheduling changes.
+
+## Measured result
+
+[Raw measurements](2026-10-02-local-message-allocations.json) compare
+`aad71fc576a0a9b0d9b52a2b206d02d08b481967` with the changed handler, on macOS ARM64,
+Node 22.23.2. Both variants are minified with esbuild, use the same dependency graph,
+and run in fresh processes. Six paired timing trials alternate baseline/candidate
+order; three separate paired trials sample allocations. Each trial warms up first.
+
+| Workload | Metric, median | Before | After | Change |
+| --- | --- | ---: | ---: | ---: |
+| 6,000 messages, one at a time | Estimated allocated bytes | 54,923,744 | 50,293,944 | 8.4% less |
+| Same | Process CPU | 223.16 ms | 225.69 ms | 1.1% more |
+| Same | Elapsed | 183.29 ms | 188.87 ms | 3.0% more |
+| 60,000 messages, batches of 100 | Estimated allocated bytes | 223,778,336 | 179,608,824 | 19.7% less |
+| Same | Process CPU | 257.61 ms | 250.08 ms | 2.9% less |
+| Same | Elapsed | 245.79 ms | 243.56 ms | 0.9% less |
+
+This is a component allocation improvement. CPU savings are small and were not
+consistent across traffic shapes. The one-at-a-time elapsed increase is about
+0.93 microseconds per round trip. An earlier prototype comparison also reduced
+allocations (6.7% / 20.3%) and had mixed timing (1.6% slower / 3.6% faster).
+
+The benchmark uses real loopback WebSockets with synthetic acknowledgement/alive
+frames and a fake backend. It asserts message sequence and type. CPU includes the
+client and server; allocated bytes are sampled estimates including collected
+objects, **not retained memory**. It does not measure actual terminal rendering,
+agent work, whole-app battery consumption, or macOS's significant-energy label.
+No live app, daemon, shared server, tmux session, or agent was changed.
+
+Reproduce from the repository root, with dependencies already installed:
+
+```sh
+node cli/scripts/benchmark-local-ws.mjs aad71fc576a0a9b0d9b52a2b206d02d08b481967 /tmp/local-ws-comparison-new
+```
+
+The output directory must be new. Workers use private fixture directories and
+loopback ports, close their sockets, and remove their fixture state. The allocation
+sampler attaches in-process and never opens a debug TCP port. Each worker has a
+30-second deadline, with a 35-second parent limit.
+
+## Validation
+
+- TypeScript typecheck passed.
+- 189 tests across seven affected files passed locally, including real local and
+ Unix sockets, remote/shared relays, terminal streams, and liveness behavior.
+- 47 local WebSocket cases include 13 new regression cases: ordering behind slow
+ local binary / remote JSON / remote binary / task routing operations; dispatch
+ failures; queued frames during owned, isolated, and shared handshakes; and
+ releasing late-acquired relays after disconnect.
+- Two new disconnect fixtures initially resumed before server close; they now wait
+ for the server-side close. The failed and passing receipts are retained in the
+ machine-readable record.
+- Required full CLI suite and OS/Node matrix run in CI before merge; its result is
+ recorded on the PR. No desktop rendering code or engine lifecycle changed.
+
+Local validation completed at 17:28:09 UTC. The exact original user request time is
+unavailable in this task context. Merge time and CI evidence belong to the PR;
+publication is intentionally excluded because the user requested a weekend hold.