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 { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import type { GuestRunner } from '../lib/guestAccounts.js'
import { adminPromptShows, adminRunner } from './admin.js'
const cleanup: string[] = []
afterEach(() => { for (const dir of cleanup.splice(0)) rmSync(dir, { recursive: true, force: true }) })
function fixture(answer: { code: number | null; stdout?: string; stderr?: string }) {
const parent = mkdtempSync(join(tmpdir(), 'team-admin-'))
cleanup.push(parent)
const stage = join(parent, 'stage')
const seen: { script?: string; files: Record<string, { text: string; mode: number }> } = { files: {} }
// Never osascript: the fake reads what was staged, as root would, and answers.
const runner = vi.fn<GuestRunner>(async (command, args) => {
const path = command === 'sudo' ? args.at(-1)! : /quoted form of "([^"]+)"/.exec(args[1]!)![1]!
seen.script = readFileSync(path, 'utf8')
for (const name of ['team.json', 'team.plist']) {
const file = join(stage, name)
if (existsSync(file)) seen.files[name] = { text: readFileSync(file, 'utf8'), mode: statSync(file).mode & 0o777 }
}
return { code: answer.code, stdout: answer.stdout ?? '', stderr: answer.stderr ?? '' }
})
const run = adminRunner({ runner, makeStage: () => { mkdirSync(stage); return stage } })
return { run, runner, stage, seen }
}
describe('adminRunner', () => {
it('stages the script and its files privately, runs it behind the administrator prompt, and removes the stage', async () => {
const f = fixture({ code: 0, stdout: 'harness: done\n' })
const result = await f.run((dir) => ({ script: `#!/bin/sh\necho ${dir}\n`, files: { 'team.json': '{}', 'team.plist': '<plist/>' } }), 'Harness wants "this".')
expect(result).toEqual({ ok: true, stdout: 'harness: done\n' })
expect(f.runner).toHaveBeenCalledTimes(1)
const [command, args] = f.runner.mock.calls[0]!
expect(command).toBe('osascript')
expect(args[0]).toBe('-e')
expect(args[1]).toContain('with administrator privileges')
expect(args[1]).toContain('with prompt "Harness wants \\"this\\"."')
expect(f.seen.script).toBe(`#!/bin/sh\necho ${f.stage}\n`)
expect(f.seen.files['team.json']).toEqual({ text: '{}', mode: 0o600 })
expect(existsSync(f.stage)).toBe(false)
})
it('hands on each step the script writes in its stage while it runs, once each, and stops reading when it ends', async () => {
const parent = mkdtempSync(join(tmpdir(), 'team-admin-'))
cleanup.push(parent)
const stage = join(parent, 'stage')
const steps: string[] = []
// As the script does (as the owner): a step a line, the latest replacing the one before. The fake waits between
// steps so the reader sees each one.
const runner = vi.fn<GuestRunner>(async () => {
for (const step of ['account', 'account', 'engines', 'not a step!']) {
writeFileSync(join(stage, 'progress'), `${step}\n`)
await new Promise((resolve) => setTimeout(resolve, 40))
}
return { code: 0, stdout: '', stderr: '' }
})
const run = adminRunner({ runner, makeStage: () => { mkdirSync(stage); return stage }, progressEveryMs: 10 })
expect(await run(() => ({ script: '' }), 'p', undefined, (step) => steps.push(step))).toEqual({ ok: true, stdout: '' })
expect(steps).toEqual(['account', 'engines'])
await new Promise((resolve) => setTimeout(resolve, 40))
expect(steps).toEqual(['account', 'engines'])
})
it('tells a cancelled prompt from a script that stopped, in the script\'s own words', async () => {
expect(await fixture({ code: 1, stderr: '0:180: execution error: User canceled. (-128)' }).run(() => ({ script: '' }), 'p'))
.toEqual({ ok: false, code: 'CANCELLED', message: 'The administrator prompt was cancelled.' })
expect(await fixture({ code: 1, stderr: '0:180: execution error: harness: launchd would not start the team daemon (8)' }).run(() => ({ script: '' }), 'p'))
.toEqual({ ok: false, code: 'FAILED', message: 'launchd would not start the team daemon', status: 8 })
expect(await fixture({ code: 2, stderr: '' }).run(() => ({ script: '' }), 'p'))
.toEqual({ ok: false, code: 'FAILED', message: 'The script stopped (exit 2).' })
})
it('finds the script\'s reason after earlier lines, which osascript ends with CR', async () => {
// As macOS returned it in the VM rig (24 Oct 2026): the owner's CLI said why first, then the script died.
const stderr = '0:296: execution error: ✗ Harness would not give a team sign-in code: Invalid or expired token\r'
+ 'harness: could not get a sign-in code from your Harness sign-in (7)\n'
expect(await fixture({ code: 1, stderr }).run(() => ({ script: '' }), 'p'))
.toEqual({ ok: false, code: 'FAILED', message: 'could not get a sign-in code from your Harness sign-in', status: 7 })
})
it('runs the script with sudo in the terminal when asked, with the prompt\'s sentence, and the password every time', async () => {
const f = fixture({ code: 0, stdout: 'harness: team computer abc\n' })
expect(await f.run((dir) => ({ script: `#!/bin/sh\necho ${dir}\n` }), 'Harness wants to remove 100% of it.', 'sudo'))
.toEqual({ ok: true, stdout: 'harness: team computer abc\n' })
const [command, args] = f.runner.mock.calls[0]!
expect(command).toBe('sudo')
expect(args).toEqual(['-k', '-p', 'Harness wants to remove 100%% of it.\nPassword for %u: ', '/bin/sh', join(f.stage, 'run.sh')])
expect(existsSync(f.stage)).toBe(false)
})
it('with sudo, tells a password sudo never got from a script that stopped, and keeps the script\'s exit status', async () => {
expect(await fixture({ code: 1, stderr: 'Sorry, try again.\nsudo: 3 incorrect password attempts\n' }).run(() => ({ script: '' }), 'p', 'sudo'))
.toEqual({ ok: false, code: 'CANCELLED', message: 'sudo did not get an administrator password.' })
const refused = fixture({ code: 9, stderr: 'harness: could not delete the account harnessteam: macOS did not allow it (eDSPermissionError). Nothing was removed\n' })
expect(await refused.run(() => ({ script: '' }), 'p', 'sudo')).toEqual({ ok: false, code: 'FAILED', status: 9,
message: 'could not delete the account harnessteam: macOS did not allow it (eDSPermissionError). Nothing was removed' })
expect(await fixture({ code: 3, stderr: '' }).run(() => ({ script: '' }), 'p', 'sudo'))
.toEqual({ ok: false, code: 'FAILED', message: 'The script stopped (exit 3).', status: 3 })
})
describe('on Linux', () => {
function linux(answer: { code: number | null; stdout?: string; stderr?: string }, graphical: boolean) {
const parent = mkdtempSync(join(tmpdir(), 'team-admin-'))
cleanup.push(parent)
const stage = join(parent, 'stage')
const seen: { script?: string } = {}
const runner = vi.fn<GuestRunner>(async (_command, args) => {
seen.script = readFileSync(args.at(-1)!, 'utf8')
return { code: answer.code, stdout: answer.stdout ?? '', stderr: answer.stderr ?? '' }
})
const run = adminRunner({ runner, platform: 'linux', graphical, makeStage: () => { mkdirSync(stage); return stage } })
return { run, runner, stage, seen }
}
it('runs the staged script with pkexec in a desktop session, and removes the stage', async () => {
const f = linux({ code: 0, stdout: 'harness: done\n' }, true)
expect(await f.run((dir) => ({ script: `#!/bin/sh\necho ${dir}\n` }), 'p')).toEqual({ ok: true, stdout: 'harness: done\n' })
const [command, args] = f.runner.mock.calls[0]!
expect(command).toBe('pkexec')
expect(args).toEqual(['/bin/sh', join(f.stage, 'run.sh')])
expect(f.seen.script).toBe(`#!/bin/sh\necho ${f.stage}\n`)
expect(existsSync(f.stage)).toBe(false)
})
it('reads pkexec\'s 126 and 127 as a cancelled prompt, and keeps the script\'s own reason and status', async () => {
// pkexec's own words (polkit's pkexec.c): 126 for a dismissed dialog, 127 for a refusal.
for (const [code, stderr] of [[126, ''], [126, 'Error executing command as another user: Request dismissed\n'],
[127, 'Error executing command as another user: Not authorized\n\nThis incident has been reported.\n']] as const) {
expect(await linux({ code, stderr }, true).run(() => ({ script: '' }), 'p'), stderr)
.toEqual({ ok: false, code: 'CANCELLED', message: 'The administrator prompt was cancelled.' })
}
// 127 is also no polkit agent to ask with, and a command the script could not find: a failure, never a "no" the
// person gave, which Desktop's offer would remember for good.
expect(await linux({ code: 127, stderr: 'Error executing command as another user: No authentication agent found.\n' }, true)
.run(() => ({ script: '' }), 'p'))
.toEqual({ ok: false, code: 'FAILED', status: 127, message: 'Error executing command as another user: No authentication agent found.' })
// As pkexec 124 answered in the gridtest VM (Ubuntu 24.04, 2026-10-28), run with no agent and no terminal.
expect(await linux({ code: 127, stderr: 'Error creating textual authentication agent: Error opening current controlling terminal for the process (`/dev/tty\'): No such device or address\n' }, true)
.run(() => ({ script: '' }), 'p')).toMatchObject({ ok: false, code: 'FAILED', status: 127 })
expect(await linux({ code: 127, stderr: '/root/run.sh: 12: setfacl: not found\n' }, true).run(() => ({ script: '' }), 'p'))
.toMatchObject({ ok: false, code: 'FAILED', status: 127 })
expect(await linux({ code: 3, stderr: 'harness: no tmux every account can run: install it (apt install tmux / dnf install tmux)\n' }, true)
.run(() => ({ script: '' }), 'p'))
.toEqual({ ok: false, code: 'FAILED', status: 3, message: 'no tmux every account can run: install it (apt install tmux / dnf install tmux)' })
})
it('without a desktop session, answers that it needs a terminal and runs nothing', async () => {
const f = linux({ code: 0 }, false)
expect(await f.run(() => ({ script: '' }), 'p'))
.toEqual({ ok: false, code: 'NO_PROMPT', message: 'No administrator prompt here: run the command in a terminal.' })
expect(f.runner).not.toHaveBeenCalled()
expect(existsSync(f.stage)).toBe(false)
})
it('can show the prompt only with pkexec and a display', () => {
const pkexec = (path: string) => path === '/usr/bin/pkexec'
expect(adminPromptShows({ DISPLAY: ':0' }, pkexec)).toBe(true)
expect(adminPromptShows({ WAYLAND_DISPLAY: 'wayland-0' }, pkexec)).toBe(true)
// The owner's daemon under systemd --user, as it usually runs: no display in its environment.
expect(adminPromptShows({}, pkexec)).toBe(false)
expect(adminPromptShows({ DISPLAY: ':0' }, () => false)).toBe(false)
})
it('runs it with sudo in the terminal when asked, desktop session or not', async () => {
const f = linux({ code: 0, stdout: 'ok\n' }, false)
expect(await f.run(() => ({ script: '' }), 'Harness wants it.', 'sudo')).toEqual({ ok: true, stdout: 'ok\n' })
expect(f.runner.mock.calls[0]![0]).toBe('sudo')
expect(f.runner.mock.calls[0]![1]).toEqual(['-k', '-p', 'Harness wants it.\nPassword for %u: ', '/bin/sh', join(f.stage, 'run.sh')])
})
})
describe('on Windows', () => {
const OWNER_SID = 'S-1-5-21-1111111111-2222222222-3333333333-1001'
function windows(answer: { code: number | null; stdout?: string; stderr?: string }, icacls = 0, encoding: BufferEncoding = 'utf8',
whoami = `"desktop\\owner-placeholder","${OWNER_SID}"\r\n`) {
const parent = mkdtempSync(join(tmpdir(), 'team-admin-'))
cleanup.push(parent)
const stage = join(parent, 'stage')
const seen: { script?: string; wrapper?: string } = {}
// Never powershell, icacls or whoami: the fake reads what was staged, as the elevated script would, and writes what it said.
const runner = vi.fn<GuestRunner>(async (command) => {
if (command === 'whoami') return { code: whoami ? 0 : 1, stdout: whoami, stderr: '' }
if (command === 'icacls') return { code: icacls, stdout: '', stderr: icacls ? 'Access is denied.' : '' }
seen.script = readFileSync(join(stage, 'run.ps1'), 'utf8')
seen.wrapper = readFileSync(join(stage, 'elevated.ps1'), 'utf8')
if (answer.stdout !== undefined) writeFileSync(join(stage, 'stdout.txt'), answer.stdout)
if (answer.stderr !== undefined) writeFileSync(join(stage, 'stderr.txt'), answer.stderr, encoding)
return { code: answer.code, stdout: '', stderr: '' }
})
const run = adminRunner({ runner, platform: 'win32', makeStage: () => { mkdirSync(stage); return stage } })
return { run, runner, stage, seen }
}
const decoded = (args: readonly string[]) => Buffer.from(args[args.indexOf('-EncodedCommand') + 1]!, 'base64').toString('utf16le')
const callOf = (f: { runner: { mock: { calls: Parameters<GuestRunner>[] } } }, name: string) => f.runner.mock.calls.find(([command]) => command === name)!
it('makes the staging folder the owner\'s alone, by SID, before anything is written in it', async () => {
const f = windows({ code: 0, stdout: '' })
await f.run(() => ({ script: 'exit 0' }), 'p')
expect(f.runner.mock.calls.map(([command]) => command)).toEqual(['whoami', 'icacls', 'powershell.exe'])
expect(callOf(f, 'whoami')[1]).toEqual(['/user', '/fo', 'csv', '/nh'])
// The owner, SYSTEM and Administrators, each by SID: a name could resolve to a same-named domain or local account,
// and SYSTEM's and Administrators' change with the language of Windows. Nothing inherited.
expect(callOf(f, 'icacls')[1]).toEqual([f.stage, '/inheritance:r', '/grant:r', `*${OWNER_SID}:(OI)(CI)F`, '*S-1-5-18:(OI)(CI)F', '*S-1-5-32-544:(OI)(CI)F'])
})
it('runs nothing when it cannot tell the owner\'s SID', async () => {
const f = windows({ code: 0 }, 0, 'utf8', '')
expect(await f.run(() => ({ script: '' }), 'p')).toEqual({ ok: false, code: 'FAILED', message: 'Could not read this account\'s SID (whoami /user).' })
expect(f.runner.mock.calls.map(([command]) => command)).toEqual(['whoami'])
expect(existsSync(f.stage)).toBe(false)
})
it('keeps what the script wrote to its own stdout and stderr: run.ps1 runs as a child whose output goes to the files', async () => {
const f = windows({ code: 0, stdout: '' })
await f.run(() => ({ script: 'exit 0' }), 'p')
// `& run.ps1 1> out 2> err` in the same process keeps PowerShell's streams only, and the scripts write through
// [Console]: every failure read "The script stopped (exit N)" and removal's team computer line never came back.
expect(f.seen.wrapper).not.toContain('1> $out')
expect(f.seen.wrapper).toContain("$ps = Join-Path $env:SystemRoot 'System32\\WindowsPowerShell\\v1.0\\powershell.exe'")
expect(f.seen.wrapper).toContain("-ArgumentList @('-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', \"`\"$run`\"\")")
expect(f.seen.wrapper).toContain('-NoNewWindow -PassThru -RedirectStandardOutput $out -RedirectStandardError $err')
expect(f.seen.wrapper).toContain('exit $p.ExitCode')
})
it('runs run.ps1 elevated through User Account Control, and hands back what it said', async () => {
const f = windows({ code: 0, stdout: 'harness: team computer abc\r\n' })
expect(await f.run((dir) => ({ script: `Write-Output '${dir}'`, files: { 'team.json': '{}' } }), 'p'))
.toEqual({ ok: true, stdout: 'harness: team computer abc\r\n' })
const [command, args] = callOf(f, 'powershell.exe')
expect(command).toBe('powershell.exe')
expect(args.slice(0, 3)).toEqual(['-NoProfile', '-NonInteractive', '-EncodedCommand'])
const outer = decoded(args)
expect(outer).toContain('Start-Process -FilePath powershell.exe -Verb RunAs -Wait -PassThru')
expect(outer).toContain(`'-NoProfile -ExecutionPolicy Bypass -File "${join(f.stage, 'elevated.ps1')}"'`)
// With a byte order mark, which Windows PowerShell 5.1 needs to read anything but ASCII as UTF-8.
expect(f.seen.script).toBe(`Write-Output '${f.stage}'`)
expect(f.seen.wrapper).toContain("Join-Path $PSScriptRoot 'run.ps1'")
expect(existsSync(f.stage)).toBe(false)
})
it('reads 1223 as a cancelled prompt, and keeps the script\'s own reason and status', async () => {
expect(await windows({ code: 1223 }).run(() => ({ script: '' }), 'p'))
.toEqual({ ok: false, code: 'CANCELLED', message: 'The administrator prompt was cancelled.' })
expect(await windows({ code: 4, stderr: 'harness: an account named harnessteam already exists\r\n' }).run(() => ({ script: '' }), 'p'))
.toEqual({ ok: false, code: 'FAILED', status: 4, message: 'an account named harnessteam already exists' })
expect(await windows({ code: 2 }).run(() => ({ script: '' }), 'p'))
.toEqual({ ok: false, code: 'FAILED', status: 2, message: 'The script stopped (exit 2).' })
// As Windows PowerShell 5.1 writes a redirection it was not told the encoding of: UTF-16 with its byte order mark.
const utf16 = `${'harness: could not make the account\r\n'}`
expect(await windows({ code: 5, stderr: Buffer.from(utf16, 'utf16le').toString('latin1') }, 0, 'latin1').run(() => ({ script: '' }), 'p'))
.toEqual({ ok: false, code: 'FAILED', status: 5, message: 'could not make the account' })
})
it('runs nothing when the staging folder cannot be made private', async () => {
const f = windows({ code: 0 }, 5)
expect(await f.run(() => ({ script: '' }), 'p')).toEqual({ ok: false, code: 'FAILED',
message: 'Could not make the staging folder private: Access is denied.' })
expect(f.runner.mock.calls.map(([command]) => command)).toEqual(['whoami', 'icacls'])
expect(existsSync(f.stage)).toBe(false)
})
})
it('removes the stage when building the script throws', async () => {
const f = fixture({ code: 0 })
await expect(f.run(() => { throw new Error('bad input') }, 'p')).rejects.toThrow('bad input')
expect(existsSync(f.stage)).toBe(false)
expect(f.runner).not.toHaveBeenCalled()
})
})