@nomix-ai/nomix-harness 0.2.6 → 0.2.9

package/dist/kernel/subprocess-local/lib/types/terminal.d.ts

@@ -1,60 +0,0 @@
-/** Local node-pty terminal-process implementation for the subprocess seam. */
-import { PassThrough } from 'node:stream';
-import type { IPty } from 'node-pty';
-import type { SubprocessOutcome, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal } from '../../../subprocess/lib/index.js';
-import type { ProcessInspector } from './process-inspector.ts';
-/**
- * A local terminal whose process-session ownership stays below the PTY backend.
- * The seam's terminate() promise — no write, inspection, or signal in flight
- * after settlement — holds here without operation tracking only because every
- * handle call completes synchronously under the hood (node-pty write, ps-based
- * inspection). A first genuinely asynchronous step in any handle call must add
- * the tracking a remote provider needs.
- */
-export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
-    private readonly terminal;
-    private readonly inspector;
-    private readonly graceMs;
-    private readonly platform;
-    readonly pid: number;
-    readonly output: PassThrough;
-    readonly done: Promise<SubprocessOutcome>;
-    private readonly outcome;
-    private readonly dataDisposable;
-    private readonly exitDisposable;
-    private cleanup;
-    private exited;
-    private trackedDescendants;
-    /** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */
-    private readonly rootIdentity;
-    /**
-     * @param terminal - allocated node-pty process.
-     * @param inspector - platform process/session operations.
-     * @param graceMs - TERM-to-KILL and exit-wait grace.
-     * @param platform - host platform; defaults to the running platform, injectable for deterministic tests.
-     */
-    constructor(terminal: IPty, inspector: ProcessInspector, graceMs: number, platform?: NodeJS.Platform);
-    write(data: string): Promise<void>;
-    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
-    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
-    terminate(): Promise<void>;
-    /**
-     * Force-terminate the observable session synchronously during Node's exit
-     * event. This does not claim quiescence and does not replace terminate().
-     */
-    terminateForHostExit(): void;
-    private forceStopShell;
-    private survivors;
-    private descendants;
-    private waitForMembers;
-    private signalMembers;
-    private forceStopDescendants;
-    private unionMembers;
-    private stopDescendants;
-    private stopShell;
-    private stopShellWindows;
-    private waitForWindowsShellExit;
-    private closeOnce;
-    private settleExitIfGone;
-}
-//# sourceMappingURL=terminal.d.ts.map

package/dist/kernel/subprocess-local/lib/types/terminal.js

@@ -1,312 +0,0 @@
-/** Local node-pty terminal-process implementation for the subprocess seam. */
-import { Buffer } from 'node:buffer';
-import { constants } from 'node:os';
-import { PassThrough } from 'node:stream';
-function delay(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
-function signalName(number) {
-    if (number === undefined || number === 0)
-        return null;
-    for (const [name, value] of Object.entries(constants.signals)) {
-        if (value === number)
-            return name;
-    }
-    return null;
-}
-/**
- * A local terminal whose process-session ownership stays below the PTY backend.
- * The seam's terminate() promise — no write, inspection, or signal in flight
- * after settlement — holds here without operation tracking only because every
- * handle call completes synchronously under the hood (node-pty write, ps-based
- * inspection). A first genuinely asynchronous step in any handle call must add
- * the tracking a remote provider needs.
- */
-export class LocalTerminalHandle {
-    terminal;
-    inspector;
-    graceMs;
-    platform;
-    pid;
-    output = new PassThrough();
-    done;
-    outcome = Promise.withResolvers();
-    dataDisposable;
-    exitDisposable;
-    cleanup;
-    exited = false;
-    trackedDescendants = [];
-    /** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */
-    rootIdentity;
-    /**
-     * @param terminal - allocated node-pty process.
-     * @param inspector - platform process/session operations.
-     * @param graceMs - TERM-to-KILL and exit-wait grace.
-     * @param platform - host platform; defaults to the running platform, injectable for deterministic tests.
-     */
-    constructor(terminal, inspector, graceMs, platform = process.platform) {
-        this.terminal = terminal;
-        this.inspector = inspector;
-        this.graceMs = graceMs;
-        this.platform = platform;
-        this.pid = terminal.pid;
-        this.rootIdentity = inspector.processTree(this.pid).find(member => member.pid === this.pid);
-        this.done = this.outcome.promise;
-        this.dataDisposable = terminal.onData((data) => { this.output.write(Buffer.from(data, 'utf8')); });
-        this.exitDisposable = terminal.onExit(({ exitCode, signal: exitSignal }) => {
-            if (this.exited)
-                return;
-            this.exited = true;
-            this.output.end();
-            this.outcome.resolve({
-                exitCode: exitSignal === undefined || exitSignal === 0 ? exitCode : null,
-                signal: signalName(exitSignal),
-            });
-        });
-    }
-    // node-pty writes synchronously; the seam returns a promise for remote transports.
-    // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider contract.
-    async write(data) {
-        if (this.exited)
-            throw new Error('terminal process has exited');
-        this.terminal.write(data);
-    }
-    // Local inspection is synchronous; the seam returns a promise for remote transports.
-    // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider contract.
-    async inspectForeground() {
-        this.descendants();
-        const processGroupId = this.inspector.foregroundPgid(this.pid);
-        if (processGroupId === undefined)
-            return undefined;
-        return {
-            processGroupId,
-            inputWaiting: this.inspector.isStdinWaiting(processGroupId),
-        };
-    }
-    async signalForeground(signal) {
-        const foreground = await this.inspectForeground();
-        if (foreground === undefined) {
-            throw new Error(`cannot resolve foreground process group for terminal ${this.pid}`);
-        }
-        if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
-            throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead');
-        }
-        if (this.platform === 'win32') {
-            if (signal === 'SIGINT') {
-                // Windows has no process-group signalling: a `\x03` input write is the
-                // Ctrl-C delivery path conhost turns into a console-wide CTRL_C event
-                // for attached processes. node-pty's signal kills throw on Windows, so
-                // no signal ever reaches the inspector.
-                this.terminal.write('\x03');
-                return foreground.processGroupId;
-            }
-            if (signal === 'SIGTSTP' || signal === 'SIGHUP') {
-                throw new Error(`signal ${signal} is unsupported on Windows; only SIGINT, SIGTERM, and SIGKILL are available`);
-            }
-        }
-        this.inspector.signalGroup(foreground.processGroupId, signal);
-        return foreground.processGroupId;
-    }
-    terminate() {
-        if (this.cleanup !== undefined)
-            return this.cleanup;
-        const cleanup = this.closeOnce();
-        this.cleanup = cleanup;
-        void cleanup.catch(() => { this.cleanup = undefined; });
-        return cleanup;
-    }
-    /**
-     * Force-terminate the observable session synchronously during Node's exit
-     * event. This does not claim quiescence and does not replace terminate().
-     */
-    terminateForHostExit() {
-        this.forceStopDescendants();
-        this.forceStopShell();
-        this.forceStopDescendants();
-    }
-    forceStopShell() {
-        if (this.exited)
-            return;
-        if (this.rootIdentity !== undefined) {
-            try {
-                this.inspector.signalProcess(this.rootIdentity, 'SIGKILL');
-            }
-            catch (_rootExitedDuringHostExit) {
-                // Exact identity signalling contains both exit races and PID reuse.
-            }
-            return;
-        }
-        try {
-            this.terminal.kill('SIGKILL');
-        }
-        catch (_unidentifiedShellExitedDuringHostExit) {
-            // Without a captured identity, node-pty is the only root kill primitive.
-        }
-    }
-    survivors(members) {
-        return members.filter(member => this.inspector.isAlive(member));
-    }
-    descendants() {
-        // Adopt newly scanned members only while the numeric root pid provably
-        // still carries the spawned shell's start identity: after the shell dies,
-        // a recycled pid's tree and session must not donate an unrelated
-        // process's children to this session's signalling. Already-adopted
-        // members keep their own start identities, which every signal rechecks.
-        const tree = this.inspector.processTree(this.pid);
-        const root = tree.find(member => member.pid === this.pid);
-        const rootVerified = this.rootIdentity !== undefined
-            && root !== undefined
-            && root.started === this.rootIdentity.started;
-        this.trackedDescendants = this.survivors(this.unionMembers(this.trackedDescendants, ...rootVerified ? [tree, this.inspector.processSession(this.pid)] : []).filter(member => member.pid !== this.pid));
-        return this.trackedDescendants;
-    }
-    async waitForMembers(members) {
-        const until = Date.now() + this.graceMs;
-        let survivors = this.survivors(members);
-        while (survivors.length > 0 && Date.now() < until) {
-            await delay(Math.min(25, Math.max(1, until - Date.now())));
-            survivors = this.survivors(members);
-        }
-        return survivors;
-    }
-    signalMembers(members, signal) {
-        for (const member of members) {
-            try {
-                this.inspector.signalProcess(member, signal);
-            }
-            catch (_alreadyExitedDuringSignal) {
-                // The exact process identity is rechecked; a same-tick exit is success.
-            }
-        }
-    }
-    forceStopDescendants() {
-        let members = this.trackedDescendants;
-        try {
-            members = this.descendants();
-        }
-        catch (_processTableUnavailableDuringHostExit) {
-            // Preserve already-captured identities when a final process-table scan fails.
-        }
-        this.signalMembers(members, 'SIGKILL');
-    }
-    unionMembers(...groups) {
-        const members = [];
-        const seen = new Set();
-        for (const group of groups) {
-            for (const member of group) {
-                const key = `${member.pid}:${member.started}`;
-                if (seen.has(key))
-                    continue;
-                seen.add(key);
-                members.push(member);
-            }
-        }
-        return members;
-    }
-    async stopDescendants() {
-        const captured = this.descendants();
-        this.signalMembers(captured, 'SIGTERM');
-        const capturedSurvivors = await this.waitForMembers(captured);
-        const members = this.unionMembers(capturedSurvivors, this.descendants());
-        this.signalMembers(members, 'SIGKILL');
-        const survivors = await this.waitForMembers(members);
-        return this.survivors(this.unionMembers(survivors, this.descendants()));
-    }
-    async stopShell() {
-        if (this.platform === 'win32') {
-            await this.stopShellWindows();
-            return;
-        }
-        if (!this.exited) {
-            try {
-                this.terminal.kill('SIGTERM');
-            }
-            catch (_topLevelAlreadyExitedDuringTerm) {
-                // The exit callback is authoritative.
-            }
-            await Promise.race([this.done.then(() => undefined), delay(this.graceMs)]);
-        }
-        if (!this.exited) {
-            try {
-                this.terminal.kill('SIGKILL');
-            }
-            catch (_topLevelAlreadyExitedDuringKill) {
-                // The exit callback is authoritative.
-            }
-            await Promise.race([this.done.then(() => undefined), delay(this.graceMs)]);
-        }
-        if (!this.exited)
-            throw new Error(`terminal cleanup failed; surviving pid: ${this.pid}`);
-    }
-    async stopShellWindows() {
-        // node-pty's Windows kill(signal) throws ("Signals not supported on
-        // windows"), and its bare kill() delegates to a console-list agent that
-        // fails when the parent has no console. taskkill tree escalation is the
-        // teardown path, fenced on the shell's start identity like every
-        // descendant; a root identity miss falls back to the bare kill. taskkill
-        // termination also does not reliably fire node-pty's exit notification
-        // (the same console-list agent), so the tiers verify the shell's absence
-        // through the inspector instead of waiting on `done` alone.
-        const shellGone = () => this.exited || (this.rootIdentity !== undefined && !this.inspector.isAlive(this.rootIdentity));
-        if (!shellGone() && this.rootIdentity !== undefined) {
-            this.inspector.signalProcess(this.rootIdentity, 'SIGTERM');
-            await this.waitForWindowsShellExit();
-        }
-        if (!shellGone() && this.rootIdentity === undefined) {
-            try {
-                this.terminal.kill();
-            }
-            catch (_topLevelAlreadyExitedDuringKill) {
-                // The exit callback is authoritative.
-            }
-            await Promise.race([this.done.then(() => undefined), delay(this.graceMs)]);
-        }
-        if (!shellGone() && this.rootIdentity !== undefined) {
-            this.inspector.signalProcess(this.rootIdentity, 'SIGKILL');
-            await this.waitForWindowsShellExit();
-        }
-        if (!shellGone())
-            throw new Error(`terminal cleanup failed; surviving pid: ${this.pid}`);
-    }
-    async waitForWindowsShellExit() {
-        const until = Date.now() + this.graceMs;
-        while (!this.exited && Date.now() < until) {
-            if (this.rootIdentity !== undefined && !this.inspector.isAlive(this.rootIdentity))
-                return;
-            await delay(Math.min(25, Math.max(1, until - Date.now())));
-        }
-    }
-    async closeOnce() {
-        let survivors = await this.stopDescendants();
-        if (survivors.length > 0) {
-            throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`);
-        }
-        await this.stopShell();
-        survivors = await this.stopDescendants();
-        if (survivors.length > 0) {
-            throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`);
-        }
-        this.settleExitIfGone();
-        this.dataDisposable.dispose();
-        this.exitDisposable.dispose();
-    }
-    settleExitIfGone() {
-        // An externally taskkilled Windows shell may never fire node-pty's exit
-        // notification (its console-list agent fails without a parent console),
-        // which would leave `done` — and every consumer awaiting it — unsettled
-        // forever. Teardown has just verified the shell's absence through the
-        // inspector, so a missing exit event is itself the outcome.
-        if (this.platform !== 'win32')
-            return;
-        if (this.exited)
-            return;
-        /* v8 ignore next -- stopShellWindows() verified the shell is gone or threw;
-           the identity re-check is a defensive fence for a future caller. */
-        if (this.rootIdentity !== undefined && this.inspector.isAlive(this.rootIdentity))
-            return;
-        this.exited = true;
-        this.output.end();
-        this.outcome.resolve({ exitCode: null, signal: null });
-    }
-}
-//# sourceMappingURL=terminal.js.map

package/dist/kernel/subprocess-local/lib/types/windows-inspector.d.ts

@@ -1,80 +0,0 @@
-/**
- * Windows process-table operations for terminal readiness, signalling, and
- * teardown: Toolhelp32 snapshot enumeration with GetProcessTimes creation-time
- * identity and process-handle wait-state liveness, the shell pid as a pseudo
- * process group (Windows has no POSIX groups), and taskkill tree signalling.
- * The koffi bindings load lazily so
- * non-Windows processes never touch Win32 libraries; all decision logic takes
- * an injectable internals boundary so suites can pin it on any host.
- * @module nomix-subprocess-local/windows-inspector
- */
-import type { SubprocessTerminalSignal } from '../../../subprocess/lib/index.js';
-import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts';
-/** One Toolhelp32 process-table row. */
-export interface ProcessEntry {
-    pid: number;
-    parentPid: number;
-}
-/** Creation identity plus the process object's current wait state. */
-export interface WindowsProcessState {
-    /** GetProcessTimes creation identity used to fence PID reuse. */
-    started: string;
-    /** Whether a zero-time process-handle wait reports the process still running. */
-    active: boolean;
-}
-/** Injectable Windows process operations used by one local PTY session. */
-export interface WindowsProcessInspectorInternals {
-    /** Enumerate the current process table (pid/parent pairs). */
-    snapshot(): ProcessEntry[];
-    /** Return one process's creation identity and wait state, or undefined when unreadable. */
-    processState(pid: number): WindowsProcessState | undefined;
-    /** Terminate one process tree; `force` maps to taskkill `/F`. */
-    taskkill(pid: number, force: boolean): void;
-}
-/**
- * Walk a process table from one root in children-first order, retaining only
- * members whose start identity is readable (unreadable members are detector
- * misses, exactly like an unreadable `/proc` entry on Linux).
- * @param entries - the process table snapshot.
- * @param rootPid - the tree root to descend from.
- * @param started - creation-time identity resolver for one member.
- * @returns the root and its current transitive descendants, children first.
- */
-export declare function windowsProcessTree(entries: ProcessEntry[], rootPid: number, started: (pid: number) => string | undefined): ProcessIdentity[];
-/**
- * Windows {@link ProcessInspector}. The shell pid stands in for a foreground
- * process group: it is a stable pseudo-group that lets the prompt-marker
- * readiness path compare foreground identities, while every actual signal
- * targets the console-wide tree through taskkill (SIGINT is delivered by the
- * terminal handle as a `\x03` input write and never reaches this layer).
- */
-export declare class WindowsProcessInspector implements ProcessInspector {
-    private readonly internals;
-    constructor(internals?: WindowsProcessInspectorInternals);
-    foregroundPgid(shellPid: number): number;
-    isStdinWaiting(_pgid: number): boolean;
-    processTree(rootPid: number): ProcessIdentity[];
-    processSession(_sessionId: number): ProcessIdentity[];
-    isAlive(identity: ProcessIdentity): boolean;
-    signalGroup(pgid: number, signal: SubprocessTerminalSignal): void;
-    signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void;
-}
-/**
- * Create the Windows process inspector.
- * @param internals - injectable process operations; defaults to the koffi-backed table.
- * @returns the Windows inspector.
- */
-export declare function createWindowsProcessInspector(internals?: WindowsProcessInspectorInternals): WindowsProcessInspector;
-declare const nativePtr: unique symbol;
-/** Koffi 3 native pointer (a BigInt address), branded so it cannot silently enter numeric contexts. */
-export type NativePtr = bigint & {
-    readonly [nativePtr]: true;
-};
-/**
- * True for NULL and INVALID_HANDLE_VALUE returns from Win32 handle APIs.
- * @param value - a handle as koffi may hand it back (pointer, null, or 0n).
- * @returns whether the value signals an invalid handle.
- */
-export declare function isInvalidHandle(value: NativePtr | null | undefined): boolean;
-export {};
-//# sourceMappingURL=windows-inspector.d.ts.map