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
/**
* Runs a privileged team script once as root, behind the system's own administrator prompt (password or Touch ID),
* as the guest helper's install does (lib/guestHelperInstall.ts), or with sudo in the terminal the command runs in. The
* script and the files it installs are staged in a folder private to this account (mkdtemp is 0700), so nobody can swap
* one in between, and removed after.
*
* Why sudo at all: macOS 26 deletes an account only for an app the person allowed to administer the computer, and it
* cannot ask that for the administrator prompt's process (authtrampoline), so it refuses it. With sudo in a terminal the
* terminal app is the one asking, and macOS asks the person once: "Terminal would like to administer your computer".
*
* On Linux the prompt is polkit's (`pkexec`), as for the guest helper, when a desktop session can show it. Without one
* (over SSH, or a daemon with no display) it is sudo in a terminal, and a caller with no terminal is told so (`NO_PROMPT`).
*
* Everything that touches the system goes through [AdminDeps]; the specs never run osascript, pkexec or sudo.
*/
import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { runGuestCommand, type GuestRunner } from '../lib/guestAccounts.js'
import { adminAppleScript } from '../lib/guestHelperInstall.js'
import { WHOAMI_USER_ARGS, windowsUserSid } from './windowsTeam.js'
export type AdminResult =
| { ok: true; stdout: string }
/** [status]: the script's own exit status, when it stopped with one (`do shell script` ends its error with it).
* `NO_PROMPT`: no administrator prompt can be shown here, and nothing ran. */
| { ok: false; code: 'CANCELLED' | 'FAILED' | 'NO_PROMPT'; message: string; status?: number }
export interface AdminScript {
script: string
/** Files the script installs from the staging folder, by name. */
files?: Record<string, string>
}
/** How root is asked for: the administrator prompt (a dialog), or sudo in this terminal, which asks for the password there. */
export type AdminVia = 'prompt' | 'sudo'
/** Builds the script once the staging folder exists (the script names it), then runs it as root. [progress] hears each
* step the script says it is on ([readProgress]), while it runs. */
export type RunAdmin = (build: (stageDir: string) => AdminScript, prompt: string, via?: AdminVia, progress?: (step: string) => void) => Promise<AdminResult>
/** The file a setup script writes its step in, in its staging folder (./script.ts `step`). */
export const PROGRESS_FILE = 'progress'
const STEP = /^[a-z][a-z-]{0,23}$/
/** The step the script last wrote, or null: anything but a step's name is ignored. */
function readProgress(stageDir: string): string | null {
try {
const step = readFileSync(join(stageDir, PROGRESS_FILE), 'utf8').trim()
return STEP.test(step) ? step : null
} catch { return null }
}
export interface AdminDeps {
runner?: GuestRunner
makeStage?: () => string
removeStage?: (dir: string) => void
/** Which system's prompt asks. A Mac's unless told: the owner's CLI passes its own (./deps.ts). */
platform?: NodeJS.Platform
/** Linux: whether `pkexec` and a desktop session to show its dialog in are there. */
graphical?: boolean
/** How often the script's step is read while it runs. */
progressEveryMs?: number
}
/** Linux: whether polkit's dialog can be shown from this process (pkexec and a desktop session to show it in), as the
* guest helper's install decides it (lib/guestHelperInstall.ts). Without it, the prompt answers `NO_PROMPT`. */
export function adminPromptShows(env: NodeJS.ProcessEnv = process.env, exists: (path: string) => boolean = existsSync): boolean {
return exists('/usr/bin/pkexec') && !!(env.DISPLAY || env.WAYLAND_DISPLAY)
}
/** What a Linux computer with no desktop session answers for the prompt (over SSH, or Desktop's daemon with no display). */
export const NO_PROMPT_MESSAGE = 'No administrator prompt here: run the command in a terminal.'
/**
* Whether pkexec's answer is the person's "no". 126 is a dismissed dialog. 127 is a refused authorization only when pkexec
* says so: it is also no authentication agent to ask with (pkexec 124 with no session: "Error creating textual
* authentication agent", gridtest VM, 2026-10-28) and a command the script could not find. Those are failures, not the person's
* answer.
*/
function pkexecCancelled(code: number | null, stderr: string): boolean {
if (code === 126) return true
return code === 127 && (stderr.includes('Error executing command as another user: Not authorized')
|| stderr.includes('Error executing command as another user: Request dismissed'))
}
/** The script's own reason, its last `harness:` line, or its exit status when it said none. */
function stopped(stderr: string, code: number | null): AdminResult {
const last = stderr.trim().split(/[\r\n]+/).pop() ?? ''
return { ok: false, code: 'FAILED', message: last.replace(/^.*harness: /, '') || `The script stopped (exit ${code}).`,
...(code !== null ? { status: code } : {}) }
}
/** PowerShell single quotes: nothing is special inside but the quote itself, doubled. */
export const psQuote = (word: string): string => `'${word.replaceAll("'", "''")}'`
/**
* What runs elevated on Windows: the team script, with what it says kept in the staging folder. `Start-Process -Verb
* RunAs` cannot hand an elevated process's output back, and this is how it reaches the owner's `harness team`.
*
* run.ps1 runs as a child powershell.exe whose own stdout and stderr are the two files. Run in this process with
* `1> $out 2> $err`, only PowerShell's streams were kept, and the team scripts write through [Console]
* (./windowsScript.ts `say`/`die`): every failure read "The script stopped (exit N)", and removal's `team computer <id>`
* never reached the CLI (review, 2026-10-28). The child's handle is read once before waiting, so its exit code is kept.
*/
const ELEVATED_PS1 = [
'# Runs the Harness Team script elevated and keeps what it said (cli/src/team/admin.ts).',
"$out = Join-Path $PSScriptRoot 'stdout.txt'",
"$err = Join-Path $PSScriptRoot 'stderr.txt'",
"$run = Join-Path $PSScriptRoot 'run.ps1'",
"$ps = Join-Path $env:SystemRoot 'System32\\WindowsPowerShell\\v1.0\\powershell.exe'",
'try {',
" $p = Start-Process -FilePath $ps -ArgumentList @('-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', \"`\"$run`\"\") -NoNewWindow -PassThru -RedirectStandardOutput $out -RedirectStandardError $err",
' $null = $p.Handle',
' $p.WaitForExit()',
' exit $p.ExitCode',
'} catch {',
' "harness: $($_.Exception.Message)" | Out-File -Append -Encoding utf8 $err',
' exit 1',
'}',
'',
].join('\r\n')
/** A file Windows PowerShell wrote: UTF-8, or UTF-16 by its byte order mark, without the mark. */
function decodeText(bytes: Buffer): string {
if (bytes[0] === 0xff && bytes[1] === 0xfe) return bytes.subarray(2).toString('utf16le')
const text = bytes.toString('utf8')
return text.startsWith('') ? text.slice(1) : text
}
/** Win32's ERROR_CANCELLED: the person chose No in User Account Control's prompt. */
const UAC_CANCELLED = 1223
/**
* Windows: User Account Control's prompt (Windows PowerShell's own, signed), for `run.ps1` in a staging folder only the
* owner, SYSTEM and Administrators can open. Inheritance is removed first, before anything is written in it.
* docs/superpowers/plans/2026-10-28-harness-team-account-windows.md, Task 3.
*/
async function runElevatedOnWindows(runner: GuestRunner, stageDir: string, build: (stageDir: string) => AdminScript): Promise<AdminResult> {
// Every principal by SID. The owner's from this process's own token: a bare name could resolve to a same-named
// domain or local account. SYSTEM's and Administrators' names change with the language of Windows.
const who = await runner('whoami', WHOAMI_USER_ARGS, { timeoutMs: 30_000 })
const ownerSid = who.code === 0 ? windowsUserSid(who.stdout) : null
if (!ownerSid) return { ok: false, code: 'FAILED', message: 'Could not read this account\'s SID (whoami /user).' }
const acl = await runner('icacls', [stageDir, '/inheritance:r', '/grant:r', `*${ownerSid}:(OI)(CI)F`, '*S-1-5-18:(OI)(CI)F', '*S-1-5-32-544:(OI)(CI)F'],
{ timeoutMs: 30_000 })
if (acl.code !== 0) {
return { ok: false, code: 'FAILED', message: `Could not make the staging folder private: ${(acl.stderr || acl.stdout).trim() || `icacls exited ${acl.code}`}` }
}
const { script, files = {} } = build(stageDir)
for (const [name, content] of Object.entries(files)) writeFileSync(join(stageDir, name), content)
// With a byte order mark: Windows PowerShell 5.1 reads a script without one in the computer's ANSI code page.
writeFileSync(join(stageDir, 'run.ps1'), `${script}`)
const elevated = join(stageDir, 'elevated.ps1')
writeFileSync(elevated, `${ELEVATED_PS1}`)
// Windows names cannot hold a double quote, which would end the path inside the argument list.
if (elevated.includes('"')) throw new Error(`not a usable staging folder: ${JSON.stringify(stageDir)}`)
const outer = [
'try {',
` $p = Start-Process -FilePath powershell.exe -Verb RunAs -Wait -PassThru -WindowStyle Hidden -ArgumentList ${psQuote(`-NoProfile -ExecutionPolicy Bypass -File "${elevated}"`)}`,
' exit $p.ExitCode',
'} catch {',
` if ($_.Exception.NativeErrorCode -eq ${UAC_CANCELLED} -or $_.Exception.InnerException.NativeErrorCode -eq ${UAC_CANCELLED}) { exit ${UAC_CANCELLED} }`,
' [Console]::Error.WriteLine("harness: $($_.Exception.Message)")',
' exit 1',
'}',
].join('\n')
// Encoded, so no quoting of the command line between Node and PowerShell can change it.
const result = await runner('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(outer, 'utf16le').toString('base64')],
{ timeoutMs: 15 * 60_000 })
if (result.code === UAC_CANCELLED) return { ok: false, code: 'CANCELLED', message: 'The administrator prompt was cancelled.' }
const said = (name: string) => { try { return decodeText(readFileSync(join(stageDir, name))) } catch { return '' } }
if (result.code === 0) return { ok: true, stdout: said('stdout.txt') }
return stopped(said('stderr.txt') || result.stderr, result.code)
}
export function adminRunner(deps: AdminDeps = {}): RunAdmin {
const runner = deps.runner ?? runGuestCommand
const makeStage = deps.makeStage ?? (() => mkdtempSync(join(tmpdir(), 'harness-team-')))
const removeStage = deps.removeStage ?? ((dir: string) => rmSync(dir, { recursive: true, force: true }))
const platform = deps.platform ?? 'darwin'
const graphical = () => deps.graphical ?? adminPromptShows()
return async (build, prompt, via = 'prompt', progress) => {
const stageDir = makeStage()
// The script's step, read while it runs (osascript hands back its output only at the end), each new one said once.
let said: string | null = null
const watch = progress ? setInterval(() => {
const step = readProgress(stageDir)
if (step && step !== said) { said = step; progress(step) }
}, deps.progressEveryMs ?? 1_000) : null
try {
if (platform === 'win32') return await runElevatedOnWindows(runner, stageDir, build)
chmodSync(stageDir, 0o700)
// Nothing is staged for a prompt that cannot be shown: a Desktop offer answers at once, never waits on a dialog.
if (platform === 'linux' && via === 'prompt' && !graphical()) return { ok: false, code: 'NO_PROMPT', message: NO_PROMPT_MESSAGE }
const { script, files = {} } = build(stageDir)
for (const [name, content] of Object.entries(files)) writeFileSync(join(stageDir, name), content, { mode: 0o600 })
const path = join(stageDir, 'run.sh')
writeFileSync(path, script, { mode: 0o700 })
if (platform === 'linux' && via === 'prompt') {
// polkit's own dialog. pkexec hands back the script's output and exit status.
const result = await runner('pkexec', ['/bin/sh', path], { timeoutMs: 15 * 60_000 })
if (result.code === 0) return { ok: true, stdout: result.stdout }
if (pkexecCancelled(result.code, result.stderr)) return { ok: false, code: 'CANCELLED', message: 'The administrator prompt was cancelled.' }
return stopped(result.stderr, result.code)
}
if (via === 'sudo') {
// sudo asks on the terminal itself (/dev/tty), so the script's output is still collected here. `-k`: the password
// every time, as the dialog asks for it, never a few minutes' leftover sudo from something else.
const ask = `${prompt.replaceAll('%', '%%')}\nPassword for %u: `
const result = await runner('sudo', ['-k', '-p', ask, '/bin/sh', path], { timeoutMs: 15 * 60_000 })
if (result.code === 0) return { ok: true, stdout: result.stdout }
const lines = result.stderr.trim().split(/[\r\n]+/)
const last = lines.pop() ?? ''
if (!/^harness: /.test(last) && /incorrect password|password is required|terminal is required|no tty present/i.test(result.stderr)) {
return { ok: false, code: 'CANCELLED', message: 'sudo did not get an administrator password.' }
}
return { ok: false, code: 'FAILED', message: last.replace(/^.*harness: /, '') || `The script stopped (exit ${result.code}).`,
...(result.code !== null ? { status: result.code } : {}) }
}
const result = await runner('osascript', ['-e', adminAppleScript(path, prompt)], { timeoutMs: 15 * 60_000 })
// -128 is the prompt's Cancel.
if (result.code !== 0 && /-128|User canceled/i.test(result.stderr)) {
return { ok: false, code: 'CANCELLED', message: 'The administrator prompt was cancelled.' }
}
if (result.code !== 0) {
// `do shell script` hands the script's stderr back with its lines ended by CR, not LF: split on both, or a reason
// after an earlier line is never found, and the CR left in it makes a terminal print the line over itself.
const last = result.stderr.trim().split(/[\r\n]+/).pop() ?? ''
const status = /\((\d+)\)$/.exec(last)?.[1]
const said = last.replace(/^.*harness: /, '').replace(/\s*\(\d+\)$/, '')
return { ok: false, code: 'FAILED', message: said || `The script stopped (exit ${result.code}).`, ...(status ? { status: Number(status) } : {}) }
}
return { ok: true, stdout: result.stdout }
} finally {
if (watch) clearInterval(watch)
removeStage(stageDir)
}
}
}