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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* The daemon's Unix domain socket: the desktop app's and hn's way in, beside the loopback TCP port.
*
* The loopback port carries no credential — every process on this computer, any user's, can open it,
* and the Host/Origin checks (lib/loopbackRequest.ts) only keep web pages out. The socket lives in the
* daemon's data directory (0700) and is itself 0600, so the filesystem is the credential: only this
* user's processes can connect. A request that arrives over it is from this user, and needs none of
* the address checks a TCP request does — its peer has no address at all.
*
* TCP stays for what cannot use this (MCP clients, engine plugins, Store agents, old app builds) and for a data folder
* too long for a socket. The CLI, engine hooks and the app use only this socket while it can exist: any account can
* bind the port once it is free (audit H1, lib/localTransport.ts). On Windows the
* daemon serves a named pipe instead (`listenAuthenticated` below). Reaching that pipe is no credential, so every
* request over it proves the daemon's token (lib/windows/pipeAuth.ts).
*/
import { createHash, randomBytes } from 'node:crypto'
import http from 'node:http'
import { connect } from 'node:net'
import type { IncomingMessage } from 'node:http'
import type { Socket } from 'node:net'
import type { Duplex } from 'node:stream'
import { chmodSync, linkSync, lstatSync, mkdirSync, renameSync, unlinkSync, type Stats } from 'node:fs'
import { homedir } from 'node:os'
import { dirname, join } from 'node:path'
import { configuredPortOf, readDaemonRecord } from './daemonRecord.js'
import { daemonPipe, type LocalDaemonOptions } from './windows/daemonPipe.js'
import { checkPipeAuth, newPipePath, NonceWindow, PIPE_AUTH_HEADER, PIPE_PROOF_HEADER, pipeIdOf, pipeProofValue } from './windows/pipeAuth.js'
import { pipeAbsent, pipeRequest, PipeUnproven } from './windows/pipeClient.js'
/**
* One socket per configured port in this OS user's data directory: `daemon-<port>.sock`. Its name
* stays stable when a different user's daemon holds the requested TCP port and this daemon receives
* another one. Native clients derive this private path; CLI TCP clients read the saved actual port.
*/
export function localSocketName(port: number): string {
return `daemon-${port}.sock`
}
/** Whether a file in the data directory is one of these sockets (for `harness reset`). */
export function isLocalSocketName(name: string): boolean {
return /^daemon-\d+\.sock$/.test(name)
}
/** sockaddr_un.sun_path is 104 bytes on macOS, 108 on Linux, terminator included; the socket is
* created under a name 4 bytes longer (see [listenLocalSocket]) and must fit too. */
const MAX_SOCKET_PATH_BYTES = 96
/** The shortest daemon token a pipe accepts (the token is 32 random bytes). */
const MIN_TOKEN_BYTES = 32
const trustedSockets = new WeakSet<Socket>()
/** Requests over the daemon's pipe whose auth checked out, and the proof each answer to them carries. */
const pipeProofs = new WeakMap<IncomingMessage, string>()
/** Where a folder too long to hold a socket keeps its sockets: under the home folder, as /tmp is shared and TMPDIR differs between launchd
* and a shell, so clients would disagree. The same rule is in cli/hook/notify.mjs, store/tools/local-daemon.mjs and Desktop's
* local_daemon_transport.dart. */
export function shortSocketFolder(folder: string, home: string = homedir()): string {
return join(home, '.harness', 's', createHash('sha256').update(folder).digest('hex').slice(0, 16))
}
/** `name` in [folder], or in its short folder when that path is too long for a socket; null when even that is, the one case left on TCP. */
export function socketPathIn(folder: string, name: string, home: string = homedir()): string | null {
const beside = join(folder, name)
if (Buffer.byteLength(beside) <= MAX_SOCKET_PATH_BYTES) return beside
const short = join(shortSocketFolder(folder, home), name)
return Buffer.byteLength(short) <= MAX_SOCKET_PATH_BYTES ? short : null
}
/** The daemon's Unix socket for `port` in this data directory, or null where there is none: Windows, or a home too long as well. */
export function unixSocketPath(dataDir: string, port: number, platform: NodeJS.Platform = process.platform): string | null {
if (platform === 'win32') return null
return socketPathIn(dataDir, localSocketName(port))
}
/**
* Where a client reaches the daemon on `port` of this data directory, or null where there is nothing to reach. That
* is its Unix socket; on Windows, the pipe the running daemon recorded in `daemon-<port>.json`, a new name on each
* start. Reaching that pipe is no trust: every request there proves the daemon's token (lib/windows/pipeAuth.ts).
* A caller that needs a filesystem socket (`ws+unix://`, the services) uses unixSocketPath.
*/
export function localSocketPath(dataDir: string, port: number, platform: NodeJS.Platform = process.platform): string | null {
return platform === 'win32' ? readDaemonRecord(dataDir, configuredPortOf(dataDir, port, platform), platform)?.pipe ?? null : unixSocketPath(dataDir, port, platform)
}
/** Where a daemon starting on `port` listens: its Unix socket, or on Windows a pipe of a new random name. */
export function localSocketListenPath(dataDir: string, port: number, platform: NodeJS.Platform = process.platform): string | null {
return platform === 'win32' ? newPipePath() : unixSocketPath(dataDir, port, platform)
}
/** Whether this request (or raw socket) came in over the daemon's own Unix socket, or over its pipe with valid auth. */
export function isTrustedLocal(target: IncomingMessage | Socket | null | undefined): boolean {
if (!target) return false
if (pipeProofs.has(target as IncomingMessage)) return true
const socket = 'socket' in target && target.socket ? target.socket : target as Socket
return trustedSockets.has(socket)
}
/** The proof every answer to [req] must carry, for a request over the daemon's pipe whose auth checked out. */
export function pipeProofOf(req: IncomingMessage): string | undefined {
return pipeProofs.get(req)
}
export interface ListenLocalSocketOptions {
/**
* The daemon's token (lib/windows/pipeAuth.ts). When given, `path` is a pipe (in the tests, a socket with a pipe's
* name) whose every request must prove the token: Windows. Absent: the Unix socket, trusted by its file mode.
*/
token?: Buffer
}
export interface LocalSocketServer {
server: http.Server
path: string
/** Stop listening and remove the socket file. */
close: () => Promise<void>
/** The same, for the synchronous boot handoff. */
closeSync: () => void
}
/** A short folder (shortSocketFolder) is made here, and it and its parent are this account's real folders, owner only, before a socket goes in. */
function prepareShortFolder(path: string): void {
const folder = dirname(path)
if (!/[\\/]\.harness[\\/]s[\\/][0-9a-f]{16}$/.test(folder)) return
mkdirSync(folder, { recursive: true, mode: 0o700 })
for (const each of [dirname(folder), folder]) {
const seen = lstatSync(each), uid = process.getuid?.()
if (!seen.isDirectory() || (uid !== undefined && seen.uid !== uid)) throw new Error(`${each} is not private: it must be this account's own folder.`)
chmodSync(each, 0o700)
}
}
/**
* Serve `handler` on a Unix socket at `path`. Refuse a live listener or a non-socket file, and remove
* only a stale socket. CLI startup is serialized by the per-user spawn lock; two daemons that start at
* once anyway (two masters) get one socket between them, never one each.
*/
export async function listenLocalSocket(handler: http.RequestListener, path: string, options: ListenLocalSocketOptions = {}): Promise<LocalSocketServer> {
if (options.token) return listenAuthenticated(handler, path, options.token)
// A Harness pipe, or any endpoint on Windows, is never trusted by reachability: it needs the daemon's token.
if (pipeIdOf(path) || process.platform === 'win32') throw new Error(`${path} needs the daemon's token: reaching a pipe is no credential`)
prepareShortFolder(path)
// A TCP collision can now move this user to another port. Holding a TCP port no longer proves
// an existing Unix socket is stale: never unlink a live daemon belonging to this user.
await refuseLiveSocket(path)
const server = http.createServer(handler)
server.on('connection', (socket) => trustedSockets.add(socket))
const unlink = (): void => {
try { if (lstatSync(path).isSocket()) unlinkSync(path) } catch { /* already gone */ }
}
// Stop listening, drop what is connected and remove the file — without waiting on `close`'s
// callback, which waits for every socket to end: an upgraded WebSocket the peer never finishes
// closing would otherwise hold a restart-for-update open indefinitely.
const closeNow = (): void => {
server.closeAllConnections()
server.close()
unlink()
}
// `listen` creates the file with the process umask. It is made owner-only under a private name and
// only then put in place, so no client ever sees it looser than 0600, and the umask (process-wide,
// shared with whatever fs work is in flight) is never touched.
//
// Put in place by a hard link, which fails when the name is taken, where a rename replaces it. Two
// claims at once (two masters racing) both got the socket before — measured, every time in
// localSocket.spec.ts: they staged under one shared name and each renamed into place, and the one
// replaced kept listening where nothing could reach it, bound as far as its master knew. A private
// staging name per claim, no longer than the socket's own (a socket path has 96 bytes: localSocketPath).
const staging = join(dirname(path), `.claim-${randomBytes(3).toString('hex')}`)
return new Promise((resolve, reject) => {
server.once('error', reject)
server.listen(staging, () => {
server.off('error', reject)
void (async () => {
try {
chmodSync(staging, 0o600)
await claim(staging, path)
} catch (error) {
server.closeAllConnections()
server.close()
try { unlinkSync(staging) } catch { /* never created, or already moved */ }
reject(error)
return
}
// The socket is at `path` now; the staged name goes (a rename already took it).
try { unlinkSync(staging) } catch { /* renamed into place */ }
resolve({ server, path, close: async () => closeNow(), closeSync: closeNow })
})()
})
})
}
/**
* The daemon's Windows pipe: the same handler, for requests that prove the token. Node cannot set a pipe's DACL,
* and the default one lets every account open it for reading, so reaching the pipe is no credential. A request
* without valid auth gets a 401 and never reaches the handler. An upgrade without valid auth is dropped here,
* before the local WS server's listener (localWsServer.ts), which then finds its socket destroyed. Every answer
* carries the proof; the local WS server adds it to a 101. There is no file to claim or remove: the name is new on
* each start (localSocketListenPath), and a pipe goes with its last handle.
*/
function listenAuthenticated(handler: http.RequestListener, path: string, token: Buffer): Promise<LocalSocketServer> {
if (token.length < MIN_TOKEN_BYTES) return Promise.reject(new Error(`The daemon's token must be at least ${MIN_TOKEN_BYTES} bytes`))
const pipeId = pipeIdOf(path)
if (!pipeId) return Promise.reject(new Error(`${path} is not a Harness pipe name`))
const seen = new NonceWindow()
const admit = (req: IncomingMessage): boolean => {
const header = req.headers[PIPE_AUTH_HEADER]
const auth = checkPipeAuth(token, typeof header === 'string' ? header : undefined, seen, pipeId)
if (auth) pipeProofs.set(req, pipeProofValue(token, auth.nonce))
return auth !== null
}
const server = http.createServer((req, res) => {
if (!admit(req)) {
res.writeHead(401, { 'Content-Type': 'application/json', Connection: 'close' })
res.end(JSON.stringify({ error: 'PIPE_AUTH_REQUIRED' }))
return
}
res.setHeader(PIPE_PROOF_HEADER, pipeProofs.get(req)!)
handler(req, res)
})
// Must stay the first 'upgrade' listener: it drops an unauthenticated upgrade before any other listener sees it.
server.prependListener('upgrade', (req: IncomingMessage, socket: Duplex) => {
// Alone, this listener would leave an upgrade nobody takes hanging: nothing serves upgrades here yet.
if (!admit(req) || server.listenerCount('upgrade') === 1) socket.destroy()
})
const closeNow = (): void => {
server.closeAllConnections()
server.close()
}
return new Promise((resolve, reject) => {
server.once('error', reject)
server.listen(path, () => {
server.off('error', reject)
resolve({ server, path, close: async () => closeNow(), closeSync: closeNow })
})
})
}
/** What a start finds when another daemon serves its data folder: `EADDRINUSE`, as the bind it spares would have. */
export const alreadyServing = (path: string): Error =>
Object.assign(new Error(`A Harness daemon is already serving ${path}`), { code: 'EADDRINUSE' })
/**
* The core of a master that is gone still serves the data folder once the wait for it is over. Not another
* daemon: it is leaving, slowly (a client that will not answer its close). Its own code, so start-up ends
* in an exit its master starts again, and the next core finds it gone, where EADDRINUSE ends it for good,
* and launchd and systemd do not start a clean exit again (lib/daemonSafeMode.ts).
*/
export const ORPHAN_STILL_SERVING = 'ORPHAN_STILL_SERVING'
export const orphanStillServing = (path: string, corePid: number): Error =>
Object.assign(new Error(`The core (pid ${corePid}) of a master that is gone still serves ${path}`), { code: ORPHAN_STILL_SERVING })
/**
* Put the staged socket at `path`. The name taken: by a daemon serving it (refused), or by the socket of
* one that crashed (replaced). Decided here, at the claim, never earlier: a liveness check made before
* the listen is stale by the time a second daemon claims, and the unlink that followed it removed the
* first daemon's live socket. Only the very file found dead is removed: a socket another daemon has put
* there since is a different file, and is left to it.
*/
async function claim(staging: string, path: string): Promise<void> {
for (let attempt = 0; ; attempt++) {
try {
linkSync(staging, path)
return
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
// A filesystem without hard links: the rename it always used, which replaces rather than refuses.
renameSync(staging, path)
return
}
}
if (attempt > 0) throw alreadyServing(path)
let found: Stats
try { found = lstatSync(path) } catch { continue } // gone meanwhile: try the name again
if (!found.isSocket()) throw new Error(`${path} exists and is not a socket; not replacing it`)
await refuseLiveSocket(path)
try { if (lstatSync(path).ino === found.ino) unlinkSync(path) } catch { /* gone meanwhile */ }
}
}
/** What answers on a data folder's socket: nothing, something that does not say who it is, or a daemon
* and its master (`pid`, the pid file's: the master's under one, its own otherwise) and its core. */
export type DataFolderServer = 'none' | 'unknown' | { pid: number; corePid: number }
export interface ServedFolderDeps {
/** Who serves the socket at `path` (`GET /api/status` over it). */
who(path: string, timeoutMs: number): Promise<DataFolderServer>
alive(pid: number): boolean
sleep(ms: number): Promise<void>
now(): number
log(line: string): void
}
/** How long start-up waits for the core of a master that is gone to leave: well inside the minute the
* master gives a core to bind, and longer than such a core takes to stop. */
export const ORPHAN_WAIT_MS = 20_000
const ORPHAN_POLL_MS = 250
/** What a status answer says: a daemon and its master, or `unknown` when it does not say both pids. */
function folderServerOf(body: string): DataFolderServer {
try {
const status = JSON.parse(body) as { pid?: unknown; corePid?: unknown }
const pid = Number(status.pid)
// A daemon from before harnessd says no core of its own: it is its own master.
const corePid = status.corePid === undefined ? pid : Number(status.corePid)
return Number.isSafeInteger(pid) && pid > 0 && Number.isSafeInteger(corePid) && corePid > 0 ? { pid, corePid } : 'unknown'
} catch {
return 'unknown'
}
}
/** Ask the daemon on a data folder's socket who it is. A socket that takes no connection serves nothing
* (no socket, a stale one, one that cannot be reached: start-up goes on, and the bind decides); one that
* takes it and does not say is `unknown`. With [token] the socket is the Windows pipe: see [askPipeServer]. */
export function askDataFolderServer(path: string, timeoutMs: number, token: Buffer | null = null): Promise<DataFolderServer> {
if (token) return askPipeServer(path, timeoutMs, token)
return new Promise((resolve) => {
let connected = false
// A connection of its own, never one kept alive from an earlier ask: that one may be to a daemon gone.
const request = http.request({ socketPath: path, path: '/api/status', method: 'GET', timeout: timeoutMs, agent: false }, (response) => {
let body = ''
response.setEncoding('utf8')
response.on('data', (chunk: string) => { if (body.length < 65_536) body += chunk })
response.on('end', () => resolve(folderServerOf(body)))
response.on('error', () => resolve('unknown'))
})
request.on('socket', (socket: Socket) => socket.once('connect', () => { connected = true }))
request.on('timeout', () => { request.destroy(); resolve(connected ? 'unknown' : 'none') })
request.on('error', () => resolve(connected ? 'unknown' : 'none'))
request.end()
})
}
/**
* The Windows pipe: the ask proves the token and takes only an answer with the daemon's proof (pipeClient.ts).
* An answer without it serves nothing: whatever took a dead daemon's name must not keep this one down. So does a
* name that is no Harness pipe, or nothing listening there (a stale record). Silence is not that: a listener that
* does not answer in time (a real daemon that is only slow) is `unknown`, and start-up refuses, since each Windows
* start listens on a fresh pipe and this ask is the only guard against a second daemon on the folder. An answer that
* proves the daemon but is unusable (too large) is `unknown` too, as on a Unix socket.
*/
async function askPipeServer(pipe: string, timeoutMs: number, token: Buffer): Promise<DataFolderServer> {
if (!pipeIdOf(pipe)) return 'none'
try {
const reply = await pipeRequest({ pipe, token }, { method: 'GET', path: '/api/status', timeoutMs, maxBytes: 65_536 })
return folderServerOf(reply.body)
} catch (error) {
return error instanceof PipeUnproven || pipeAbsent(error) ? 'none' : 'unknown'
}
}
const SERVED_FOLDER_DEFAULTS: ServedFolderDeps = {
who: askDataFolderServer,
alive: (pid) => { try { process.kill(pid, 0); return true } catch (error) { return (error as NodeJS.ErrnoException).code === 'EPERM' } },
sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
now: () => performance.now(),
log: (line) => console.log(line),
}
/**
* What `refuseServedDataFolder` asks with for the daemon of [dataDir] on [configuredPort]. On Windows it asks the
* recorded pipe with that folder's token (windows/daemonPipe.ts `daemonPipe`). Nothing serves it when there is no token
* (the core makes the token before it listens), no record of a pipe and pid, or a recorded process proven gone: that
* pipe is never dialled, so whatever took a dead daemon's name and hangs cannot keep every start down. Elsewhere it
* asks as it always has.
*/
export function servedFolderDeps(dataDir: string, configuredPort: number, options: LocalDaemonOptions = {}): ServedFolderDeps {
if ((options.platform ?? process.platform) !== 'win32') return SERVED_FOLDER_DEFAULTS
const find = options.pipe ?? daemonPipe
return {
...SERVED_FOLDER_DEFAULTS,
who: async (_path, timeoutMs) => {
const target = await find(dataDir, configuredPort)
return target ? askDataFolderServer(target.pipe, timeoutMs, target.token) : 'none'
},
}
}
/**
* Refuse to start a daemon whose data folder another daemon already serves: start-up asks this before it
* reads or writes anything of that daemon's. Rejects with `EADDRINUSE`, as the bind it spares would have.
* No socket, or a stale one, lets start-up go on, and the bind decides.
*
* A second `harness start --foreground` (a launchd or systemd unit beside the app's daemon), and the core
* of a second master, used to get as far as that bind first: on the way they marked the running daemon's
* agents inactive on disk and reaped its harness viewers as the orphans of a daemon that had died
* (e2e/twodaemons.e2e.ts).
*
* ⚠️ Except the core of a master that is gone, which serves only until it notices and stops. Under launchd
* or systemd a master that died is started again at once, and its new core found the old one still
* there: refused, it exits for good, its master with it, cleanly, and neither launchd's
* `SuccessfulExit=false` nor systemd's `Restart=on-failure` starts a clean exit again, so the daemon stayed
* down until the next login. Such a core is waited for, a bounded while, and once it has said so, so is
* a silence from it while it stops. A daemon whose master is alive, or that runs without one, is another
* daemon, and refused at once as before. So is one that answers without saying who it is: every release
* with this socket has said its pid in `/api/status`, so a silence or an answer without one is a daemon
* that is busy or hung, not one that is leaving, and a person waiting on `harness start` or the app must
* not wait out the orphan's bound for it (cliCommand.spec.ts, the CI runs of #819).
*/
export async function refuseServedDataFolder(
path: string | null, timeoutMs = 1_000, deps: ServedFolderDeps = SERVED_FOLDER_DEFAULTS, waitMs = ORPHAN_WAIT_MS,
): Promise<void> {
if (!path) return
const deadline = deps.now() + waitMs
let orphanSeen = false
let orphanCore = 0
for (;;) {
const server = await deps.who(path, timeoutMs)
if (server === 'none') {
if (orphanSeen) deps.log('[cli] the core whose master is gone has left — starting')
return
}
if (server === 'unknown') {
// Only the core already seen to be an orphan may go quiet while it stops.
if (!orphanSeen) throw alreadyServing(path)
} else {
if (server.pid === server.corePid || deps.alive(server.pid)) throw alreadyServing(path)
if (!orphanSeen) deps.log(`[cli] this data folder is still served by the core (pid ${server.corePid}) of a master that is gone (pid ${server.pid}) — waiting for it to leave`)
orphanSeen = true
orphanCore = server.corePid
}
if (deps.now() >= deadline) throw orphanSeen ? orphanStillServing(path, orphanCore) : alreadyServing(path)
await deps.sleep(ORPHAN_POLL_MS)
}
}
async function refuseLiveSocket(path: string): Promise<void> {
await new Promise<void>((resolve, reject) => {
const socket = connect(path)
socket.once('connect', () => {
socket.destroy()
reject(alreadyServing(path))
})
socket.once('error', (error: NodeJS.ErrnoException) => {
if (error.code === 'ENOENT' || error.code === 'ECONNREFUSED' || error.code === 'ENOTSOCK') resolve()
else reject(error)
})
socket.setTimeout(1_000, () => {
socket.destroy()
reject(new Error(`Could not verify whether ${path} is in use`))
})
})
}