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
/**
* Ending a process and everything it started, on Windows, with TerminateProcess: the agent signaller's
* (ptyHostBackend.ts `signalProcess`), whose caller (`terminateDeletedAgent`, a restart or a swap) has just
* checked the root's identity itself.
*
* Not `taskkill /T /F`, which this replaced (ruling of 2026-10-16). On Windows 11, `taskkill` refused a standard
* user in an SSH session (a network logon) with `ERROR: Access denied`, even for a process that user had just
* started, while `Stop-Process` (TerminateProcess) ended it: taskkill asks WMI, which turns down a non-admin
* network-logon token (task-B3.21 finding F1). A daemon a standard user starts over SSH — a remote machine, the
* box, our own end-to-end runs — could then end no agent.
*
* The tree is read once from the pty host's process table (windows/processTable.ts), whose rows have parent pids
* and start markers. Windows reuses pids, and a process keeps its parent's pid after that parent exits, so a
* parent pid alone can name an unrelated, newer process: a child is taken only when it started no earlier than its
* parent did. A marker there is `w:<creation time>` (pty/src/ps.rs: GetProcessTimes' FILETIME, 100 ns since 1601,
* as a decimal), read here as a bigint, since a FILETIME is past 2^53. A child, or a parent, whose marker is not
* one cannot be ordered, and is left out: ending too little is the safe side.
*/
import type { PtyHostClient } from '../ptyHost/client.js'
import type { ProcessRow } from '../processTable.js'
import { windowsProcessRows } from './processTable.js'
/** What became of a request: `sent` (the root was ended), `gone` (nothing to end), `failed` (it may still run). */
export type TreeKillOutcome = 'sent' | 'gone' | 'failed'
export interface TreeKillDeps {
/** The process table, read once; null when it could not be read. */
rows(): Promise<ProcessRow[] | null>
/** End [pid] at once (TerminateProcess). Throws, with `code` ESRCH, for a process that is not there. */
kill(pid: number): void
/** This process: never ended. */
self: number
}
/** How many generations below the root are ended: an agent's tree is a few deep, a cycle in the links is not. */
export const TREE_MAX_DEPTH = 32
/** And how many processes under it at most. */
export const TREE_MAX_PROCESSES = 1024
/** A Windows start marker's creation time (`w:<FILETIME>`), or null for a marker that is not one. */
export function windowsStartTime(marker: string): bigint | null {
const match = /^w:(\d{1,20})$/.exec(marker)
return match ? BigInt(match[1]!) : null
}
const usablePid = (pid: number, self: number): boolean => Number.isSafeInteger(pid) && pid > 0 && pid !== self
/** [root]'s descendants in [rows], a generation to an array, nearest first. */
function generations(root: number, rows: readonly ProcessRow[], self: number): ProcessRow[][] {
const rootRow = rows.find((row) => row.pid === root)
if (!rootRow) return []
const children = new Map<number, ProcessRow[]>()
for (const row of rows) {
const siblings = children.get(row.parentPid)
if (siblings) siblings.push(row)
else children.set(row.parentPid, [row])
}
const seen = new Set<number>([root])
const found: ProcessRow[][] = []
let count = 0
let parents = [rootRow]
while (parents.length && found.length < TREE_MAX_DEPTH && count < TREE_MAX_PROCESSES) {
const next: ProcessRow[] = []
for (const parent of parents) {
const started = windowsStartTime(parent.startMarker)
if (started === null) continue
for (const child of children.get(parent.pid) ?? []) {
if (count >= TREE_MAX_PROCESSES) break
if (seen.has(child.pid) || !usablePid(child.pid, self)) continue
const childStarted = windowsStartTime(child.startMarker)
// Started before its parent: the parent pid names a process that came after its real parent had exited.
if (childStarted === null || childStarted < started) continue
seen.add(child.pid)
next.push(child)
count++
}
}
if (next.length) found.push(next)
parents = next
}
return found
}
function isGone(error: unknown): boolean {
return (error as NodeJS.ErrnoException | null)?.code === 'ESRCH'
}
/**
* End [pid] and its descendants: the furthest generation first, so no parent outlives its children to start
* another, then [pid]. A descendant that is gone, or would not end, does not stop the walk (whoever's `kill` it is
* says so). The outcome is the root's. Without a table, the root alone: better than nothing. Never rejects.
*/
export async function endProcessTree(pid: number, deps: TreeKillDeps): Promise<TreeKillOutcome> {
// Never this process (that would end the daemon), never a pid that cannot be one.
if (!usablePid(pid, deps.self)) return 'failed'
let rows: ProcessRow[] | null
try {
rows = await deps.rows()
} catch {
rows = null
}
const below = rows ? generations(pid, rows, deps.self) : []
for (const generation of below.reverse()) {
for (const row of generation) {
try { deps.kill(row.pid) } catch { /* gone, or refused: the root still goes */ }
}
}
try {
deps.kill(pid)
return 'sent'
} catch (error) {
return isGone(error) ? 'gone' : 'failed'
}
}
/** This computer's: the host's table (`harness-pty ps` without a client), and TerminateProcess. */
export function processTreeKillDeps(client: Pick<PtyHostClient, 'call'> | null): TreeKillDeps {
return {
rows: () => windowsProcessRows(client),
// Node's process.kill on Windows is TerminateProcess whatever the signal; ESRCH for a pid that is not there.
kill: (pid) => { process.kill(pid, 'SIGKILL') },
self: process.pid,
}
}