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
import * as fs from 'node:fs'
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { homedir, tmpdir } from 'node:os'
import { dirname, join, resolve } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { env } from '../config/env.js'
import {
adoptEngineHomes, adoptHomes, claudeProjectsRoots, codexHomeRoots, launchClaudeConfigDir, launchCodexHome, launchHomeOf, movedEngineHomes, movedHomes,
ownHomeOf, profileEnvironment, resetEngineHomes, sessionClaudeHome, sessionCodexHome, sessionFolderOf, sessionRoots,
confirmHomes, durableEngineHomes, nativeSessionRoots, recoverEngineHomes, engineHomeSnapshot,
} from './engineHomes.js'
// The login shell's environment, as the daemon captured it at start-up: none, unless a test says so.
const shell = vi.hoisted(() => ({ env: {} as NodeJS.ProcessEnv }))
vi.mock('./loginShellEnv.js', () => ({ loginShellEnvironment: () => shell.env }))
const host = vi.hoisted(() => ({ win32: false }))
vi.mock('../engines/kit/windowsFiles.js', async original => {
const actual = await original<typeof import('../engines/kit/windowsFiles.js')>()
return { ...actual, hostPlatform: () => host.win32 ? 'win32' : actual.hostPlatform() }
})
vi.mock('../engines/kit/homeAdoption.js', async original => {
const actual = await original<typeof import('../engines/kit/homeAdoption.js')>()
return { ...actual, homeIsNetworkOrDevice: (path: string, platform?: NodeJS.Platform) => path.startsWith('//net/') || actual.homeIsNetworkOrDevice(path, platform) }
})
const clock = vi.hoisted(() => ({ remaining: Infinity }))
vi.mock('node:perf_hooks', async original => ({ ...await original<object>(), performance: { now: () => --clock.remaining < 0 ? 3_001 : 0 } })) // past NATIVE_EVIDENCE_MS
vi.mock('node:fs', async original => {
const actual = await original<typeof fs>()
return { ...actual, linkSync: vi.fn(actual.linkSync), lstatSync: vi.fn(actual.lstatSync) }
})
const saved = () => join(env.ADAPTER_DATA_DIR, 'engine-homes.json')
const defaults = { claudeHome: '/home/someone/.claude', codexHome: '/home/someone/.codex' }
describe('the homes the person moved', () => {
let root: string
let originalData: string
beforeEach(async () => {
clock.remaining = Infinity
const actual = await vi.importActual<typeof fs>('node:fs')
vi.mocked(fs.linkSync).mockReset().mockImplementation(actual.linkSync)
vi.mocked(fs.lstatSync).mockReset().mockImplementation(actual.lstatSync)
root = mkdtempSync(join(tmpdir(), 'engine-homes-'))
originalData = env.ADAPTER_DATA_DIR
env.ADAPTER_DATA_DIR = join(root, 'data')
mkdirSync(env.ADAPTER_DATA_DIR, { mode: 0o700 })
resetEngineHomes()
})
afterEach(() => {
rmSync(root, { recursive: true, force: true })
env.ADAPTER_DATA_DIR = originalData
resetEngineHomes()
})
it('adopts each absolute home that is not the daemon\'s own, once, beside the defaults', () => {
const claude = join(root, 'claude-work'), codex = join(root, 'codex-work')
expect(adoptEngineHomes({ CLAUDE_CONFIG_DIR: claude, CODEX_HOME: `${codex}/` }, defaults)).toEqual({ claude, codex })
// The same environment again moves nothing new.
expect(adoptEngineHomes({ CLAUDE_CONFIG_DIR: claude, CODEX_HOME: codex }, defaults)).toEqual({ claude: null, codex: null })
expect(claudeProjectsRoots('/own/projects')).toEqual(['/own/projects', join(claude, 'projects')])
expect(codexHomeRoots('/own/codex')).toEqual(['/own/codex', codex])
expect(movedEngineHomes()).toEqual({ claude: [claude], codex: [codex] })
})
it.each(['\\\\server\\share\\.claude', '\\\\?\\C:\\Users\\u\\.claude', '//server/share/.claude', '\\\\.\\pipe\\x'])(
'on Windows drops the network or device path %s for that engine alone, says so once, and writes nothing', (path) => {
host.win32 = true
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
try {
expect(adoptEngineHomes({ CODEX_HOME: path }, defaults)).toEqual({ claude: null, codex: null })
expect(adoptEngineHomes({ CODEX_HOME: path }, defaults)).toEqual({ claude: null, codex: null })
expect(confirmHomes({ CODEX_HOME: path })).toEqual({ claude: null, codex: null })
expect(warn).toHaveBeenCalledTimes(1)
expect(String(warn.mock.calls[0][0])).toContain('CODEX_HOME names a network or device path, which Harness does not use for an engine home on Windows. Set it to')
expect(existsSync(saved())).toBe(false)
} finally { host.win32 = false; warn.mockRestore() }
})
it('drops a network Codex home alone: the valid Claude home beside it is adopted', () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
try {
const claude = join(root, 'claude-work')
expect(adoptEngineHomes({ CLAUDE_CONFIG_DIR: claude, CODEX_HOME: '//net/x' }, defaults)).toEqual({ claude, codex: null })
expect(movedEngineHomes().claude).toEqual([claude])
expect(movedEngineHomes().codex).toEqual([])
} finally { warn.mockRestore() }
})
it('reads stay lenient on Windows: a network CODEX_HOME never throws from the read paths', () => {
host.win32 = true
try {
const environment = { CODEX_HOME: '\\\\server\\share\\x', CLAUDE_CONFIG_DIR: '\\\\server\\share\\y' }
expect(() => sessionCodexHome({})).not.toThrow()
expect(() => sessionClaudeHome({})).not.toThrow()
expect(() => launchCodexHome(null, environment)).not.toThrow()
expect(() => launchClaudeConfigDir(environment)).not.toThrow()
} finally { host.win32 = false }
})
it('does not change on mac or Linux: a leading double slash is an ordinary path there', () => {
const odd = '//server/share/.codex'
expect(adoptEngineHomes({ CODEX_HOME: odd }, defaults).codex).toBe(resolve(odd))
})
it('takes no relative, `~`, empty or unset path, and not the daemon\'s own home', () => {
for (const value of ['work/.claude', '~/.claude-work', ' ', undefined]) {
expect(adoptEngineHomes({ CLAUDE_CONFIG_DIR: value, CODEX_HOME: value }, defaults)).toEqual({ claude: null, codex: null })
}
expect(adoptEngineHomes({ CLAUDE_CONFIG_DIR: '/home/someone/.claude/', CODEX_HOME: defaults.codexHome }, defaults)).toEqual({ claude: null, codex: null })
expect(movedEngineHomes()).toEqual({ claude: [], codex: [] })
expect(existsSync(saved())).toBe(false)
})
// The login shell is read after the registry checks the saved agents' transcripts: a home known only
// from this boot's shell lost every agent bound in it at each restart.
it('remembers what it adopted in the data folder, and knows it on the next boot before any root is asked for', () => {
const claude = join(root, 'claude-work'), codex = join(root, 'codex-work')
adoptEngineHomes({ CLAUDE_CONFIG_DIR: claude }, defaults)
adoptEngineHomes({ CODEX_HOME: codex }, defaults)
expect(durableEngineHomes()).toEqual({ claude: [claude], codex: [codex] })
resetEngineHomes()
expect(claudeProjectsRoots('/own')).toEqual(['/own', join(claude, 'projects')])
resetEngineHomes()
expect(codexHomeRoots('/own')).toEqual(['/own', codex])
})
it('reads past a malformed or foreign file: only absolute paths it has not read already', () => {
writeFileSync(saved(), JSON.stringify({ claude: ['/a/claude', 'relative', 7, '/a/claude'], codex: 'not a list' }))
expect(movedEngineHomes()).toEqual({ claude: ['/a/claude'], codex: [] })
resetEngineHomes()
writeFileSync(saved(), '{ not json')
expect(movedEngineHomes()).toEqual({ claude: [], codex: [] })
})
it('refreshes a previously read home list when another process adopts a new login', () => {
writeFileSync(saved(), JSON.stringify({ codex: [join(root, 'previous')] }))
expect(codexHomeRoots('/default')).toEqual(['/default', join(root, 'previous')])
writeFileSync(saved(), JSON.stringify({ codex: [join(root, 'previous'), join(root, 'new-login')] }))
expect(codexHomeRoots('/default')).toEqual(['/default', join(root, 'previous'), join(root, 'new-login')])
rmSync(saved())
expect(codexHomeRoots('/default')).toEqual(['/default', join(root, 'previous'), join(root, 'new-login')])
})
it('holds an unwritable adoption without exposing it as a usable root, then confirms the same request after recovery', () => {
const blocked = join(root, 'blocked')
writeFileSync(blocked, 'a file where the folder should be')
const before = env.ADAPTER_DATA_DIR
env.ADAPTER_DATA_DIR = join(blocked, 'data')
try {
const claude = join(root, 'claude-work')
expect(() => adoptEngineHomes({ CLAUDE_CONFIG_DIR: claude }, defaults)).toThrow(/held/)
expect(claudeProjectsRoots('/own')).toEqual(['/own'])
expect(() => nativeSessionRoots('codex')).toThrow(/held/)
rmSync(blocked)
mkdirSync(env.ADAPTER_DATA_DIR, { recursive: true, mode: 0o700 })
expect(() => nativeSessionRoots('codex')).toThrow('previously observed or unsaved home')
expect(adoptEngineHomes({ CLAUDE_CONFIG_DIR: claude }, defaults)).toEqual({ claude, codex: null })
expect(claudeProjectsRoots('/own')).toEqual(['/own', join(claude, 'projects')])
expect(confirmHomes({ CLAUDE_CONFIG_DIR: claude })).toEqual({ claude, codex: null })
} finally {
env.ADAPTER_DATA_DIR = before
}
mkdirSync(root, { recursive: true })
})
it('shares held observations with native roots and empty-environment recovery', async () => {
const actual = await vi.importActual<typeof fs>('node:fs')
const file = saved(), requested = join(root, 'requested'), competitor = join(root, 'competitor')
let probes = 0
vi.mocked(fs.linkSync).mockImplementation((from, to) => {
if (String(to).endsWith('/000.json')) actual.writeFileSync(file, JSON.stringify({ codex: [competitor] }), { mode: 0o600 })
return actual.linkSync(from, to)
})
vi.mocked(fs.lstatSync).mockImplementation(((path, options) => {
if (String(path) === file + '.adoptions/127.json' && ++probes === 2) clock.remaining = 1
return actual.lstatSync(path, options)
}) as typeof fs.lstatSync)
expect(() => confirmHomes({ CODEX_HOME: requested })).toThrow('work deadline')
clock.remaining = Infinity
vi.mocked(fs.lstatSync).mockImplementation(actual.lstatSync)
actual.writeFileSync(file, '{}', { mode: 0o600 })
expect(movedHomes('codex')).not.toContain(competitor)
expect(() => nativeSessionRoots('codex')).toThrow('previously observed or unsaved home')
expect(recoverEngineHomes().codex).toEqual([requested, competitor])
expect(nativeSessionRoots('codex')).toContain(join(competitor, 'sessions'))
})
it('does not transfer catalog observations or pending requests into another data directory', () => {
adoptHomes({ CODEX_HOME: join(root, 'first-catalog-home') })
env.ADAPTER_DATA_DIR = join(root, 'second-catalog')
mkdirSync(env.ADAPTER_DATA_DIR, { mode: 0o700 })
expect(movedHomes('codex')).toEqual([])
expect(nativeSessionRoots('codex')).toEqual([join(env.CODEX_HOME, 'sessions')])
expect(confirmHomes({ CODEX_HOME: join(root, 'second-catalog-home') }).codex).toBe(join(root, 'second-catalog-home'))
expect(recoverEngineHomes().codex).toEqual([join(root, 'second-catalog-home')])
})
it('requires a fresh final proof for an explicit immutable batch snapshot', () => {
const before = join(root, 'before'), after = join(root, 'after')
adoptHomes({ CODEX_HOME: before })
const snapshot = engineHomeSnapshot()
expect(() => snapshot.homes.codex.push(after)).toThrow(TypeError)
expect(sessionRoots('codex', undefined, snapshot)).toContain(join(before, 'sessions'))
expect(sessionCodexHome({ transcriptPath: join(before, 'sessions', 'thread.jsonl') }, snapshot)).toBe(before)
writeFileSync(saved(), JSON.stringify({ codex: [after] }), { mode: 0o600 })
expect(() => snapshot.verify()).toThrow('changed during the operation')
const fresh = engineHomeSnapshot()
expect(fresh.homes.codex).toEqual([before, after])
expect(() => fresh.verify()).not.toThrow()
})
it('a bound conversation stays in its known home even when the current shell changes or a service has no shell cache', () => {
const home = join(root, 'previous-login'), current = join(root, 'current-login')
adoptEngineHomes({ CODEX_HOME: home }, defaults)
shell.env = { CODEX_HOME: current }
try {
for (const folder of ['sessions', 'archived_sessions']) {
const transcriptPath = join(home, folder, 'thread.jsonl')
expect(sessionCodexHome({ transcriptPath })).toBe(home)
expect(sessionCodexHome({ transcriptPath, codexHome: '/explicit-profile' })).toBe('/explicit-profile')
}
expect(sessionCodexHome({ transcriptPath: join(home, 'sessions-other', 'thread.jsonl') })).toBe(current)
expect(sessionCodexHome({ transcriptPath: join(home, '..', 'elsewhere', 'thread.jsonl') })).toBe(current)
shell.env = {}
expect(sessionCodexHome({ transcriptPath: join(home, 'sessions', 'thread.jsonl') })).toBe(home)
} finally { shell.env = {} }
})
// Each engine's session store declares its movable home (engines/sessionStoreContracts.ts): which variable moves
// it, the daemon's own, and the folder its sessions are in below it.
it('adopts and searches every engine\'s home by its declared session store', () => {
expect(ownHomeOf('claude')).toBe(dirname(env.CLAUDE_PROJECTS_DIR))
expect(ownHomeOf('codex')).toBe(env.CODEX_HOME)
const claude = join(root, 'claude-work'), codex = join(root, 'codex-work')
// The daemon's own homes, as declared, move nothing.
expect(adoptHomes({ CLAUDE_CONFIG_DIR: dirname(env.CLAUDE_PROJECTS_DIR), CODEX_HOME: env.CODEX_HOME })).toEqual({ claude: null, codex: null })
expect(adoptHomes({ CLAUDE_CONFIG_DIR: claude, CODEX_HOME: codex })).toEqual({ claude, codex })
expect([movedHomes('claude'), movedHomes('codex'), movedHomes('pi'), movedHomes('toString')]).toEqual([[claude], [codex], [], []])
expect(sessionRoots('claude')).toEqual([env.CLAUDE_PROJECTS_DIR, join(claude, 'projects')])
// Claude Code's sessions follow no profile of an agent's own; Codex's are on that profile alone.
expect(sessionRoots('claude', '/profile')).toEqual(sessionRoots('claude'))
expect(sessionRoots('codex')).toEqual([join(env.CODEX_HOME, 'sessions'), join(codex, 'sessions')])
expect(sessionRoots('codex', '/profile')).toEqual([join('/profile', 'sessions')])
expect([sessionRoots('pi'), sessionRoots('opencode', '/profile')]).toEqual([[], []])
// The sessions folder a session's file is in, for the parent beside it.
expect(sessionFolderOf('codex', { transcriptPath: join(codex, 'archived_sessions', 'thread.jsonl') })).toBe(join(codex, 'sessions'))
expect(sessionFolderOf('codex', { profile: '/profile', transcriptPath: join(codex, 'sessions', 'thread.jsonl') })).toBe(join('/profile', 'sessions'))
// An agent launched on its own profile is given it by the variable that moves its engine's home.
expect([profileEnvironment('codex', '/profile'), profileEnvironment('claude', '/profile'), profileEnvironment('pi', '/profile')])
.toEqual([{ CODEX_HOME: '/profile' }, undefined, undefined])
})
it('Claude settings follow the bound home or current shell, with the settings default separate from folder trust', () => {
const previous = join(root, 'previous-claude'), current = join(root, 'current-claude')
adoptEngineHomes({ CLAUDE_CONFIG_DIR: previous }, defaults)
shell.env = { CLAUDE_CONFIG_DIR: current }
try {
expect(sessionClaudeHome({})).toBe(current)
expect(sessionClaudeHome({ transcriptPath: join(previous, 'projects', 'workspace', 'thread.jsonl') })).toBe(previous)
expect(sessionClaudeHome({ transcriptPath: join(previous, 'projects-other', 'thread.jsonl') })).toBe(current)
expect(sessionClaudeHome({ transcriptPath: join(previous, 'projects', '..', '..', 'thread.jsonl') })).toBe(current)
shell.env = {}
expect(sessionClaudeHome({ transcriptPath: join(previous, 'projects', 'workspace', 'thread.jsonl') })).toBe(previous)
expect(sessionClaudeHome({})).toBe(dirname(env.CLAUDE_PROJECTS_DIR))
} finally { shell.env = {} }
})
})
// The home an agent launched now writes in, for what has to be in that engine's own config before it
// starts (its folder trust): the pane runs through the person's login shell, so the home that shell
// moves is the engine's, over the daemon's own environment; an agent's own Codex profile outranks both.
describe('the home an engine launched now uses', () => {
afterEach(() => { shell.env = {}; vi.unstubAllEnvs() })
it('Codex: the agent\'s own profile, else the CODEX_HOME the environment moves, else the daemon\'s', () => {
expect(launchCodexHome('/profiles/work', { CODEX_HOME: '/moved' })).toBe('/profiles/work')
expect(launchCodexHome(null, { CODEX_HOME: '/moved/' })).toBe('/moved')
expect(launchCodexHome(undefined, {})).toBe(env.CODEX_HOME)
// A relative or `~` path is not one the engine resolves the same way from every folder.
expect(launchCodexHome(null, { CODEX_HOME: '~/codex' })).toBe(env.CODEX_HOME)
expect(launchCodexHome(null, { CODEX_HOME: ' ' })).toBe(env.CODEX_HOME)
})
it('Claude Code: the CLAUDE_CONFIG_DIR the environment moves, else the home folder, as Claude Code resolves .claude.json', () => {
expect(launchClaudeConfigDir({ CLAUDE_CONFIG_DIR: '/claude-work' })).toBe('/claude-work')
expect(launchClaudeConfigDir({ CLAUDE_CONFIG_DIR: 'relative' })).toBe(homedir())
expect(launchClaudeConfigDir({})).toBe(homedir())
})
it('launchHomeOf honours the profile for CLAUDE_CONFIG_DIR homes (the trust file resolves into it)', () => {
const trustHome = { variable: 'CLAUDE_CONFIG_DIR', otherwise: 'home' } as const
expect(launchHomeOf(trustHome, '/profiles/work', { CLAUDE_CONFIG_DIR: '/moved' })).toBe('/profiles/work')
expect(launchHomeOf(trustHome, null, { CLAUDE_CONFIG_DIR: '/moved' })).toBe('/moved')
})
it('reads the login shell\'s environment over the daemon\'s own: the profile is what the pane runs', () => {
vi.stubEnv('CODEX_HOME', '/daemon-codex')
vi.stubEnv('CLAUDE_CONFIG_DIR', '/daemon-claude')
expect(launchCodexHome(null)).toBe('/daemon-codex')
expect(launchClaudeConfigDir()).toBe('/daemon-claude')
shell.env = { CODEX_HOME: '/profile-codex', CLAUDE_CONFIG_DIR: '/profile-claude' }
expect(launchCodexHome(null)).toBe('/profile-codex')
expect(launchClaudeConfigDir()).toBe('/profile-claude')
})
})