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
/** Installer-only dependencies survive core restart; engine dispatch returns to core. */
import { spawn } from 'node:child_process'
import { createHash, randomUUID } from 'node:crypto'
import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from 'node:fs'
import { basename, dirname, isAbsolute, join } from 'node:path'
import { buildEngineInstallationArgv } from '../../lib/engineLaunch.js'
import type { EngineInstallRecipe } from '../../lib/engineInstall.js'
import { failureReason } from '../../lib/failureReason.js'
import { managedNodePath } from '../../lib/nodeRuntime.js'
import { secureStateDirectory } from '../../lib/secureState.js'
import type { AgentEngine } from '../types.js'
import { LAUNCH_LOCATION_VARIABLES } from './nativeLocations.js'
import { NativeEvidenceBudget } from './nativeEvidence.js'
import { NativeFiles } from './nativeFiles.js'
import { inspectHookFile, runHookPreparation } from './nativeHookFiles.js'
import { NativePaths, verifyNativePathFacts, withoutDevice, type NativePathFact } from './nativePaths.js'
const LIMIT = 262_144
// This is installation history, not launch history: ordinary launches never add
// an entry. Bound exceptional recovery instead of making Stop wait on an ever
// larger synchronous ownership fence. Full records stay on disk for review.
const MAX_INSTALLATIONS = 128
const digest = (text: string): string => createHash('sha256').update(text).digest('hex')
const identity = (s: BigIntStats): string => `${s.dev}:${s.ino}:${s.mode}:${s.uid}`
const version = (s: BigIntStats): string => `${identity(s)}:${s.size}:${s.mtimeNs}:${s.ctimeNs}`
const directoryStamp = (directory: string): string => version(lstatSync(directory, { bigint: true }))
const missing = (error: unknown): boolean => (error as NodeJS.ErrnoException).code === 'ENOENT'
interface Link { file: string; digest: string }
interface Authority { version: 1; directory: string }
interface Claim {
version: 1; token: string; request: string; engine: AgentEngine; recipe: string
argv: string[]; environment: Record<string, string>
routes: ReturnType<NativePaths['snapshot']>; previous: Link[]; authority: string; witness: string
}
interface Dispatch { token: string; claim: string; kind: 'run' | 'cancelled' }
interface Result { token: string; claim: string; code: number | null; signal: string | null; notDispatched?: true; detail?: string }
/** `running`: an installer is dispatched and has not settled. `failed`: this request's own installer settled with a
* failure, and `detail` is why, in its output's words; it is never run again for this request. */
export type NativeInstallation = { complete: true } | { complete: false; detail: string; running?: true; failed?: true }
const hold = (detail: string): NativeInstallation => ({ complete: false, detail })
const running = (detail: string): NativeInstallation => ({ complete: false, detail, running: true })
// The helper ends its installer at 20 minutes and then records the result. A dispatch older than that with no result
// is a helper that died (a reboot during an install): it is never replayed, and no longer said to be installing, which
// `harness new` would otherwise wait on for minutes at every attempt.
const INSTALLER_SETTLES_MS = 1_200_000 + 60_000
const installing = (dispatched: { file: string } | undefined, detail: string): NativeInstallation => {
try { if (dispatched && Date.now() - lstatSync(dispatched.file).mtimeMs < INSTALLER_SETTLES_MS) return running(detail) } catch { /* A vanished record is not a live installer. */ }
return hold(detail)
}
/** Never read a growing journal file without a bound, or tighten foreign permissions to trust it. */
function readRecord(file: string): { text: string; file: string; stamp: string; facts: NativePathFact[]; verify(): void } {
const paths = new NativePaths(new NativeEvidenceBudget())
const location = paths.resolveSync(file, true), facts = paths.snapshot()
if (!location) {
// An ancestor may be an ordinary alias, such as macOS /var. Absence
// belongs to the observed physical parent, never a dangling leaf alias.
const parent = paths.resolveSync(dirname(file), true)
if (!parent?.info.isDirectory() || !paths.absentLeaf(join(parent.path, basename(file)))) throw Error('Unconfirmed missing installation route')
paths.verify()
throw Object.assign(Error('Missing installation record'), { code: 'ENOENT' })
}
if (lstatSync(file).isSymbolicLink()) throw Error('Aliased installation record')
const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
let stamp: string, text: string
try {
const before = fstatSync(fd, { bigint: true })
if (!before.isFile() || before.size > LIMIT || before.ino !== location.info.ino || before.dev !== location.info.dev
|| (before.mode & 0o022n) !== 0n || before.uid !== BigInt(process.getuid!())) throw Error('Unsafe installation record')
stamp = version(before)
const bytes = Buffer.alloc(Number(before.size))
let offset = 0
for (let calls = 0; offset < bytes.length; calls++) {
if (calls >= 64) throw Error('Installation record read limit')
const count = readSync(fd, bytes, offset, bytes.length - offset, offset)
if (!count) throw Error('Truncated installation record')
offset += count
}
if (version(fstatSync(fd, { bigint: true })) !== stamp) throw Error('Changed installation record')
text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
} finally { closeSync(fd) }
const verify = () => { verifyNativePathFacts(facts); if (version(lstatSync(file, { bigint: true })) !== stamp) throw Error('Changed installation record') }
verify()
return { text, file, stamp, facts, verify }
}
/** The helper records this one installation after core dies. Its shell has job control off,
* so the deadline kills the installer group, including stopped children. It never runs an engine. */
export const NATIVE_INSTALL_WORKER = String.raw`
const fs=require('node:fs'),cp=require('node:child_process'),path=require('node:path'),crypto=require('node:crypto');
const [file,expected,testDeadline]=process.argv.slice(1),directory=path.dirname(file),C=fs.constants;
const hash=s=>crypto.createHash('sha256').update(s).digest('hex');
const id=s=>String(s.dev)+':'+String(s.ino)+':'+String(s.mode)+':'+String(s.uid);
const ver=s=>id(s)+':'+String(s.size)+':'+String(s.mtimeNs)+':'+String(s.ctimeNs);
const nodev=s=>s&&s.slice(s.indexOf(':')+1);
function read(file){const fd=fs.openSync(file,C.O_RDONLY|C.O_NOFOLLOW|C.O_NONBLOCK);try{
const s=fs.fstatSync(fd,{bigint:true});if(!s.isFile()||s.size>262144n||s.uid!==BigInt(process.getuid())||(s.mode&0o022n))throw Error('Unsafe installation record');
const bytes=Buffer.alloc(Number(s.size));let offset=0;for(let calls=0;offset<bytes.length;calls++){
if(calls>=64)throw Error('Installation record read limit');const n=fs.readSync(fd,bytes,offset,bytes.length-offset,offset);if(!n)throw Error('Truncated record');offset+=n}
if(ver(fs.fstatSync(fd,{bigint:true}))!==ver(s)||ver(fs.lstatSync(file,{bigint:true}))!==ver(s))throw Error('Changed installation record');
return new TextDecoder('utf-8',{fatal:true}).decode(bytes)
}finally{fs.closeSync(fd)}}
const directoryFd=fs.openSync(directory,C.O_RDONLY|C.O_DIRECTORY|C.O_NOFOLLOW),directoryId=id(fs.fstatSync(directoryFd,{bigint:true}));
const text=read(file);if(hash(text)!==expected)throw Error('Changed installation claim');
const claim=JSON.parse(text),authorityText=read(claim.authority),authority=JSON.parse(authorityText),dispatchText=read(claim.witness),dispatch=JSON.parse(dispatchText);
if(nodev(authority.directory)!==nodev(directoryId)||read(file+'.dispatch')!==dispatchText||dispatch.kind!=='run'||dispatch.token!==claim.token||dispatch.claim!==expected)throw Error('Unconfirmed installer dispatch');
try{fs.lstatSync(file+'.result');throw Error('Installer already settled')}catch(e){if(e.code!=='ENOENT')throw e}
function current(){
if(id(fs.lstatSync(directory,{bigint:true}))!==directoryId||read(file)!==text||read(claim.authority)!==authorityText||read(claim.witness)!==dispatchText||read(file+'.dispatch')!==dispatchText)throw Error('Changed installation authority');
for(const p of claim.previous)if(hash(read(p.file))!==p.digest)throw Error('Changed installation predecessor');
for(const r of claim.routes){let s;try{s=fs.lstatSync(r.path,{bigint:true})}catch(e){if(e.code!=='ENOENT')throw e;s=null}
if(nodev(s?id(s):null)!==nodev(r.identity))throw Error('Changed installation target');
if(r.alias&&(!s||nodev(ver(s))!==nodev(r.alias.version)||fs.readlinkSync(r.path)!==r.alias.target))throw Error('Changed installation alias');}
}
function publish(value){
current();const temporary=file+'.'+claim.token+'.result-tmp',result=file+'.result';
const bytes=JSON.stringify(value);if(Buffer.byteLength(bytes)>262144)throw Error('Oversized installation result');
const fd=fs.openSync(temporary,C.O_WRONLY|C.O_CREAT|C.O_EXCL|C.O_NOFOLLOW,0o600);
try{
fs.writeFileSync(fd,bytes);const staged=ver(fs.fstatSync(fd,{bigint:true}));fs.fsyncSync(fd);
if(ver(fs.fstatSync(fd,{bigint:true}))!==staged||ver(fs.lstatSync(temporary,{bigint:true}))!==staged)throw Error('Changed result staging file');
current();fs.linkSync(temporary,result);
if(id(fs.lstatSync(result,{bigint:true}))!==id(fs.fstatSync(fd,{bigint:true}))||read(result)!==bytes)throw Error('Changed published result');
if(id(fs.lstatSync(temporary,{bigint:true}))!==id(fs.fstatSync(fd,{bigint:true})))throw Error('Changed result staging file');
fs.unlinkSync(temporary);if(process.platform!=='win32')fs.fsyncSync(directoryFd);
if(id(fs.lstatSync(result,{bigint:true}))!==id(fs.fstatSync(fd,{bigint:true}))||read(result)!==bytes)throw Error('Changed confirmed result');
}finally{fs.closeSync(fd)}
}
current();
let output='',finished=false,leaderGone=false,uncertain=false,deadline,drain;
const environment={...process.env};for(const key of ${JSON.stringify(LAUNCH_LOCATION_VARIABLES)})delete environment[key];Object.assign(environment,claim.environment);
const child=cp.spawn(claim.argv[0],claim.argv.slice(1),{env:environment,cwd:claim.environment.HOME,detached:true,stdio:['ignore','pipe','pipe']});
const collect=chunk=>{output=(output+chunk.toString()).slice(-32768)};
child.stdout.on('data',collect);child.stderr.on('data',collect);
child.on('error',error=>{output=String(error).slice(0,2000)});
child.on('exit',()=>{
leaderGone=true;clearTimeout(deadline);
drain=setTimeout(()=>{if(finished)return;uncertain=true;child.stdout.destroy();child.stderr.destroy()},250);
});
child.on('close',(code,signal)=>{if(finished)return;finished=true;clearTimeout(deadline);clearTimeout(drain);try{if(!uncertain)publish({token:claim.token,claim:expected,code,signal,detail:output})}finally{fs.closeSync(directoryFd)}});
deadline=setTimeout(()=>{if(leaderGone||child.exitCode!==null||child.signalCode!==null)return;try{process.kill(-child.pid,'SIGKILL')}catch{}},Math.max(20,Math.min(1200000,Number(testDeadline)||1200000)));
`
export function createNativeInstallations({ directory, node = managedNodePath, dispatch = defaultDispatch }: {
directory: string; node?: () => string; dispatch?: (node: string, file: string, digest: string) => void
}) {
// Outside the claim directory: recreating or emptying that directory cannot erase its active owner.
const authorityFile = `${directory}.authority`
const examine = async (engine: AgentEngine, inputRecipe: EngineInstallRecipe, inputEnvironment: Record<string, string>, request: string,
current: () => boolean, query = false): Promise<NativeInstallation | null> => {
try {
if (!current()) return hold('The saved launch request changed before installation.')
// Snapshot caller-owned objects before any yield. The fingerprint and executed bytes agree.
const recipe = structuredClone(inputRecipe), environment = { ...inputEnvironment }, runtime = query ? '' : node()
if (!isAbsolute(directory) || typeof request !== 'string' || !request || request.length > 4096
|| (!query && (!isAbsolute(environment.HOME ?? '') || !isAbsolute(runtime)
|| Object.entries(environment).some(([key, value]) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof value !== 'string' || value.includes('\0'))
|| typeof recipe.command !== 'string' || recipe.command.includes('\0')))) throw Error('Invalid installation input')
const wantedRecipe = digest(JSON.stringify({ recipe, environment }))
const argv = query ? [] : buildEngineInstallationArgv(engine, recipe, environment, runtime)
// Enforce the helper's read limit before publishing any irreversible claim.
if (Buffer.byteLength(JSON.stringify({ recipe, environment, argv })) > LIMIT - 32768) throw Error('Oversized installation input')
const maybe = (file: string) => {
try { return readRecord(file) } catch (error) { if (!missing(error)) throw error; return undefined }
}
const witness = (index: number) => `${directory}.${String(index).padStart(8, '0')}.dispatch`
let authority = maybe(authorityFile)
if (!authority && maybe(witness(0))) return hold('The engine installation authority is missing; previous work cannot be replayed.')
if (query && !authority) {
const absent = new NativeFiles()
if (absent.entries(directory, true).length) return hold('The engine installation authority is missing; existing work cannot be replayed.')
absent.verify()
if (!current() || maybe(authorityFile) || maybe(witness(0))) return hold('Waiting to confirm current installation ownership.')
return null
}
secureStateDirectory(directory, !authority)
const paths = new NativePaths(new NativeEvidenceBudget())
paths.resolveSync(directory)
const directoryFacts = paths.snapshot(), directoryId = identity(lstatSync(directory, { bigint: true }))
const physical = () => { try { verifyNativePathFacts(directoryFacts); return true } catch { return false } }
const publish = async (file: string, bytes: string, owner = physical) => {
if (Buffer.byteLength(bytes) > LIMIT) throw Error('Oversized installation record')
return runHookPreparation([file], attempt => inspectHookFile(file, 0o600).replace(bytes, attempt, true), { current: owner, retainConflicts: true })
}
const confirm = async (file: string, record: ReturnType<typeof readRecord>, owner = physical) => {
await runHookPreparation([file], attempt => {
record.verify()
const observed = inspectHookFile(file, 0o600)
if (observed.content !== record.text) throw Error('Changed installation confirmation')
record.verify()
// Equal bytes take only the fsync path; confirmation can never overwrite newer evidence.
return observed.replace(record.text, attempt)
}, { current: owner, retainConflicts: true })
record.verify()
}
if (!authority) {
if (new NativeFiles().entries(directory).length) return hold('The engine installation authority is missing; existing work cannot be replayed.')
await publish(authorityFile, JSON.stringify({ version: 1, directory: directoryId } satisfies Authority))
authority = readRecord(authorityFile)
}
const genesis = JSON.parse(authority.text) as Authority
if (genesis.version !== 1 || withoutDevice(genesis.directory) !== withoutDevice(directoryId)) return hold('The engine installation history was replaced; its previous owner is still unconfirmed.')
const stamp = directoryStamp(directory)
// NativeFiles retains iterator acquisition and ancestor evidence, including ABA route swaps.
const entries = new NativeFiles().entries(directory), names = entries.filter(name => /^\d{8}\.json$/.test(name)).sort()
if (names.length > MAX_INSTALLATIONS) return hold('The engine installation history exceeds the automatic recovery limit. Its saved records need review before another installation.')
if (maybe(witness(names.length)) || entries.some(name => /^\d{8}\.json\.(result|dispatch)$/.test(name) && !names.includes(name.replace(/\.(result|dispatch)$/, '')))) {
return hold('The engine installation history is incomplete; a previous installation may still own its target.')
}
const previous: Link[] = []
const routesByPath = new Map<string, NativePathFact>(), leaves = new Map<string, string>()
const retain = (record: ReturnType<typeof readRecord>) => {
for (const fact of record.facts) {
if (fact.path === record.file) continue // The leaf's complete version is checked below.
const prior = routesByPath.get(fact.path)
if (prior && JSON.stringify(prior) !== JSON.stringify(fact)) throw Error('Changed installation ancestry')
routesByPath.set(fact.path, fact)
}
const prior = leaves.get(record.file)
if (prior && prior !== record.stamp) throw Error('Changed installation record')
leaves.set(record.file, record.stamp)
}
retain(authority)
let complete = false, began = performance.now()
let pending: { file: string; record: ReturnType<typeof readRecord>; claim: Claim; slot?: ReturnType<typeof readRecord> } | undefined
let lastResult: { file: string; record: ReturnType<typeof readRecord> } | undefined
for (const [index, name] of names.entries()) {
if (name !== `${String(index).padStart(8, '0')}.json`) return hold('The engine installation history has an unconfirmed gap.')
const file = join(directory, name), record = readRecord(file), hash = digest(record.text), claim = JSON.parse(record.text) as Claim
retain(record)
if (claim.version !== 1 || typeof claim.token !== 'string' || !claim.token || typeof claim.request !== 'string'
|| claim.authority !== authorityFile || claim.witness !== witness(index) || JSON.stringify(claim.previous) !== JSON.stringify(previous)) throw Error('Invalid installation claim')
if (claim.request === request && (claim.engine !== engine || (!query && claim.recipe !== wantedRecipe))) return hold('The saved request’s installation choices changed.')
const resultRecord = maybe(`${file}.result`), slot = maybe(claim.witness)
if (slot) retain(slot)
if (!resultRecord) {
if (index !== names.length - 1) throw Error('Unfinished installation predecessor')
pending = { file, record, claim, slot }; break
}
if (!slot) throw Error('Missing installation dispatch witness')
const markerRecord = readRecord(`${file}.dispatch`)
retain(markerRecord); retain(resultRecord)
const result = JSON.parse(resultRecord.text) as Result, marker = JSON.parse(slot.text) as Dispatch
if (markerRecord.text !== slot.text || marker.token !== claim.token || marker.claim !== hash || !['run', 'cancelled'].includes(marker.kind)
|| result.token !== claim.token || result.claim !== hash || (result.code !== null && !Number.isInteger(result.code))
|| (result.signal !== null && (typeof result.signal !== 'string' || !/^SIG[A-Z0-9]+$/.test(result.signal)))
|| (result.notDispatched !== true && (result.code === null) === (result.signal === null))
|| (result.notDispatched !== undefined && (result.notDispatched !== true || result.code !== null || result.signal !== null))
|| (marker.kind === 'cancelled' && result.notDispatched !== true)) throw Error('Invalid installation result')
// A settled failure is certain, not an uncertain dispatch. This request's own is never run again: its
// launch is refused with the installer's words. Another request's no longer holds every later launch of
// the engine, as it did with nothing that could release it: a person asking again is a new attempt, with
// an installer of its own (a fresh Ubuntu VM, 2026-10-12, where one failed install would have ended
// every later `harness new` of that engine).
if (claim.request === request && !result.notDispatched) {
if (result.code !== 0 || result.signal !== null) {
return { complete: false, failed: true, detail: failureReason(typeof result.detail === 'string' ? result.detail : '',
result.signal ? `its installer was stopped (${result.signal})` : `its installer exited with status ${result.code}`) }
}
complete = true
}
lastResult = { file: `${file}.result`, record: resultRecord }
previous.splice(0, previous.length, { file, digest: hash }, { file: `${file}.result`, digest: digest(resultRecord.text) })
if (performance.now() - began > 20) { await new Promise<void>(done => setImmediate(done)); began = performance.now() }
}
const historyOwner = () => {
try {
const began = performance.now()
verifyNativePathFacts([...routesByPath.values()])
for (const [file, stamp] of leaves) {
if (performance.now() - began > 20 || version(lstatSync(file, { bigint: true })) !== stamp) return false
}
return physical()
} catch { return false }
}
const historyCurrent = () => historyOwner() && directoryStamp(directory) === stamp
if (!current() || !historyCurrent()) return hold('Waiting to confirm current installation ownership.')
// A helper may have linked its result just before its final directory sync failed.
if (lastResult) await confirm(lastResult.file, lastResult.record, historyCurrent)
if (!current() || !historyCurrent()) return hold('Waiting to confirm current installation ownership.')
if (pending?.slot) {
const { file, record, claim, slot } = pending
const marker = JSON.parse(slot.text) as Dispatch, hash = digest(record.text)
if (marker.token !== claim.token || marker.claim !== hash || !['run', 'cancelled'].includes(marker.kind)) throw Error('Invalid pending installer dispatch')
if (marker.kind === 'cancelled') {
// A durable cancellation proves the helper never ran. Complete only
// that result, including when a ready executable takes the status path.
const retained = () => {
try { record.verify(); slot.verify(); verifyNativePathFacts(claim.routes); return historyOwner() }
catch { return false }
}
const inside = maybe(`${file}.dispatch`)
if (inside) {
if (inside.text !== slot.text) throw Error('Changed cancellation marker')
await confirm(`${file}.dispatch`, inside, retained)
} else await publish(`${file}.dispatch`, slot.text, retained)
await confirm(claim.witness, slot, retained)
await publish(`${file}.result`, JSON.stringify({ token: claim.token, claim: hash, code: null, signal: null, notDispatched: true } satisfies Result), retained)
return hold('The cancelled installer is settled; the saved launch can retry.')
}
}
if (complete && !pending) return { complete: true }
if (query) return pending && (pending.claim.engine === engine || pending.claim.request === request)
? installing(pending.slot, 'Waiting for the saved installer to settle. An executable appearing before completion is not installation authority.')
: complete ? { complete: true } : null
if (!pending && names.length >= MAX_INSTALLATIONS) return hold('The engine installation history is full. Its saved records need review before another installation.')
// HOME gets a fresh budget after history enumeration and yields.
const homes = new NativePaths(new NativeEvidenceBudget()), home = homes.resolveSync(environment.HOME)
if (!home?.info.isDirectory()) return hold('Waiting to confirm the native installation home.')
const routes = [...directoryFacts, ...homes.snapshot()]
const file = pending?.file ?? join(directory, `${String(names.length).padStart(8, '0')}.json`)
const claim: Claim = pending?.claim ?? { version: 1, token: randomUUID(), request, engine, recipe: wantedRecipe,
argv, environment, routes, previous, authority: authorityFile, witness: witness(names.length) }
const bytes = pending?.record.text ?? JSON.stringify(claim), hash = digest(bytes)
verifyNativePathFacts(claim.routes)
if (!current() || !historyCurrent()) return hold('Waiting to confirm current installation ownership.')
if (pending) await confirm(file, pending.record, historyCurrent)
else await publish(file, bytes, historyOwner)
const claimed = readRecord(file)
const claimCurrent = () => { try { authority!.verify(); claimed.verify(); verifyNativePathFacts(claim.routes); return physical() } catch { return false } }
const result = JSON.stringify({ token: claim.token, claim: hash, code: null, signal: null, notDispatched: true } satisfies Result)
if (pending?.slot) {
return installing(pending.slot, 'Waiting for the dispatched installer result. An uncertain dispatch is never repeated.')
}
// A missing outside witness with an inside sentinel is a lost history, not a new dispatch.
if (maybe(`${file}.dispatch`)) return hold('The installer dispatch witness is missing; its previous worker may still own the installation.')
if (!claimCurrent()) return hold('Waiting to confirm the installer claim.')
// Another request may settle an inert reservation, but cannot replay or cancel an actual installer.
const kind = current() && claim.request === request ? 'run' : 'cancelled'
const markerBytes = JSON.stringify({ token: claim.token, claim: hash, kind } satisfies Dispatch)
await publish(claim.witness, markerBytes, claimCurrent)
const slot = readRecord(claim.witness)
const dispatchCurrent = () => { try { slot.verify(); return claimCurrent() } catch { return false } }
await publish(`${file}.dispatch`, markerBytes, dispatchCurrent)
if (kind === 'cancelled' || !current()) {
await publish(`${file}.result`, result, dispatchCurrent)
return hold('The launch changed before installation. No installer was dispatched.')
}
if (!dispatchCurrent()) return hold('Waiting to confirm the installer claim.')
dispatch(runtime, file, hash)
return running('Installing the required engine. The saved launch continues after installation is confirmed.')
} catch (error) {
// Any failed check lands here, and the person sees only this line. Without the reason in the log, a hold
// that never cleared could only be traced by hand over many round trips with the user (2026-10-19).
console.warn(`[native-install] ${engine} held:`, error instanceof Error ? error.message : error)
return hold('Waiting to confirm durable engine installation ownership.')
}
}
const ensure = async (engine: AgentEngine, recipe: EngineInstallRecipe, environment: Record<string, string>, request: string, current: () => boolean): Promise<NativeInstallation> =>
(await examine(engine, recipe, environment, request, current))!
const status = (engine: AgentEngine, request: string, current: () => boolean) => examine(engine,
{ command: '', source: '', executable: { names: [] } }, {}, request, current, true)
return { ensure, status }
}
function defaultDispatch(node: string, file: string, hash: string): void {
const child = spawn(node, ['-e', NATIVE_INSTALL_WORKER, file, hash], { detached: true, stdio: 'ignore' })
child.on('error', () => { /* The durable dispatch stays uncertain; it never authorizes a replay. */ })
child.unref()
}