@zq-silk/yui 2.1.0 → 2.2.0

package/dist/nativeAgent/agent.js

@@ -1,74 +1,154 @@
+import { createToolExecutor } from './toolManager/index.js';
+import { createContextBuilder, ContextBuildError } from './context/index.js';
 import { AgentFault, history, limits, response, size, snapshot, validOutcome } from './validation.js';
 const failed = (code, message, effect = 'none') => ({ ok: false, error: { code, message, effect } });
 export function createAgent(options) {
-    const tools = new Map(options.tools.map(t => [t.definition.name, t]));
-    if (tools.size !== options.tools.length || [...tools.keys()].some(name => !name.trim())) {
-        throw new Error('Tool names must be unique and nonempty');
+    if (!options.provider || typeof options.provider.complete !== 'function'
+        || (options.tools === undefined) === (options.toolExecutor === undefined)) {
+        throw new Error('A provider and exactly one of tools or toolExecutor are required');
     }
-    const definitions = snapshot(options.tools.map(t => t.definition));
+    // tools is an explicitly preauthorized, prebound capability set. This lease
+    // owns no resources and does not pretend to narrow those tools' authority.
+    const executor = options.toolExecutor ?? createToolExecutor({
+        tools: options.tools,
+        environment: { async acquire() { return { value: undefined, async release() { } }; } },
+        permission: { async check() { return { allowed: true }; } },
+    });
+    const definitions = snapshot(executor.definitions);
+    if (typeof executor.executeBatch !== 'function' || !Array.isArray(definitions)
+        || definitions.some(d => !d || typeof d.name !== 'string' || !d.name.trim())
+        || new Set(definitions.map(d => d.name)).size !== definitions.length) {
+        throw new Error('An executor with unique nonempty tool definitions is required');
+    }
+    const { provider, recorder, observer } = options;
+    const contextBuilder = options.contextBuilder ?? createContextBuilder();
+    const contextBudget = snapshot(options.contextBudget ?? { capacity: limits.historyBytes, reserveOutput: 0 });
     return {
         async runTurn(input) {
             const scope = { sessionId: input.sessionId, turnId: input.turnId };
             const signal = input.signal ?? new AbortController().signal;
+            const { maxSteps, input: userInput } = input;
             const messages = [];
             const events = [];
+            const contextReports = [];
             let steps = 0;
             let reason = 'error';
             let error;
-            let sinkFailed = false;
+            let recording = recorder
+                ? { status: 'recorded', lastRecordedSeq: 0 } : { status: 'memory', lastRecordedSeq: 0 };
+            let recordingFailed = false;
+            const observerErrors = [];
             const emit = async (data) => {
-                const event = snapshot({ ...scope, seq: events.length + 1, data });
+                let event = snapshot({ ...scope, seq: events.length + 1, data });
                 events.push(event);
-                if (options.onEvent && !sinkFailed) {
+                if (recorder && !recordingFailed) {
                     try {
-                        await options.onEvent(event);
+                        await recorder.record(event);
+                        recording = { status: 'recorded', lastRecordedSeq: event.seq };
                     }
-                    catch {
-                        sinkFailed = true;
-                        error = { code: 'event_sink_failed', message: 'Event sink rejected a fact; inspect in-memory evidence' };
+                    catch (cause) {
+                        recordingFailed = true;
+                        recording = { status: 'failed', lastRecordedSeq: recording.lastRecordedSeq, failedSeq: event.seq };
+                        error = { code: 'recording_failed',
+                            message: `Required recording failed: ${cause instanceof Error ? cause.message : String(cause)}; inspect recorder before recovery` };
+                    }
+                }
+                // A failed terminal write has unknown external persistence. Publish
+                // exactly one truthful local terminal to observers and the caller.
+                if (data.type === 'turn_ended' && recordingFailed) {
+                    reason = 'error';
+                    event = snapshot({ ...event, data: { type: 'turn_ended', reason, errorCode: error.code } });
+                    events[events.length - 1] = event;
+                }
+                // Observers enqueue synchronously. Never await display/telemetry delivery.
+                // Detach an invalid async consumer and observe its rejection without
+                // misrepresenting notification as transport or persistence confirmation.
+                if (observer && !observerErrors.length) {
+                    try {
+                        const returned = observer.observe(event);
+                        if (returned && typeof returned.then === 'function') {
+                            void Promise.resolve(returned).catch(() => { });
+                            throw new Error('Observer must return synchronously; enqueue asynchronous transport in the consumer');
+                        }
+                    }
+                    catch (cause) {
+                        observerErrors.push({ seq: event.seq, message: cause instanceof Error ? cause.message : String(cause) });
                     }
                 }
             };
-            const append = async (message, step) => {
+            const append = async (message, step, settlement) => {
                 const saved = snapshot(message);
                 messages.push(saved);
-                await emit({ type: 'message_appended', step, message: saved });
+                const evidence = settlement && { started: settlement.started, status: settlement.status,
+                    cancellationRequested: settlement.cancellationRequested, cleanup: settlement.cleanup };
+                await emit({ type: 'message_appended', step, message: saved, ...(evidence ? { settlement: evidence } : {}) });
             };
             await emit({ type: 'turn_started' });
             try {
                 if (!scope.sessionId?.trim() || !scope.turnId?.trim()
-                    || !Number.isSafeInteger(input.maxSteps) || input.maxSteps < 1 || typeof input.input !== 'string'
-                    || size({ role: 'user', content: input.input }) > limits.messageBytes) {
+                    || !Number.isSafeInteger(maxSteps) || maxSteps < 1 || typeof userInput !== 'string'
+                    || size({ role: 'user', content: userInput }) > limits.messageBytes) {
                     throw new AgentFault('invalid_input', 'Nonempty identities, bounded input and positive integer maxSteps required');
                 }
-                const prior = history(input.history ?? []);
+                // Canonical history can exceed the model request budget. The context
+                // builder may project it, but must not hide unresolved effects or IDs.
+                const prior = history(input.history ?? [], Infinity);
+                if (prior.some(m => m.role === 'tool' && !m.outcome.ok && m.outcome.error.effect === 'unknown')) {
+                    throw new AgentFault('unresolved_effect', 'History contains an unknown tool effect; reconcile it explicitly before continuing');
+                }
                 const usedIds = new Set(prior.flatMap(m => m.role === 'assistant' ? m.toolCalls.map(c => c.id) : []));
-                await append({ role: 'user', content: input.input });
-                while (!sinkFailed) {
+                await append({ role: 'user', content: userInput });
+                while (!recordingFailed) {
                     if (signal.aborted) {
                         reason = 'cancelled';
                         break;
                     }
-                    if (steps >= input.maxSteps) {
+                    if (steps >= maxSteps) {
                         reason = 'budget_exhausted';
                         break;
                     }
                     const all = [...prior, ...messages];
-                    if (size(all) > limits.historyBytes)
-                        throw new AgentFault('context_limit', 'History exceeds context byte limit');
                     steps++;
                     await emit({ type: 'step_started', step: steps });
                     try {
-                        if (sinkFailed)
+                        if (recordingFailed)
                             break;
                         if (signal.aborted) {
                             reason = 'cancelled';
                             break;
                         }
-                        const request = snapshot({ ...scope, step: steps, messages: all, tools: definitions });
+                        const source = snapshot({ ...scope, step: steps, messages: all, tools: definitions });
+                        let request;
+                        try {
+                            const built = await contextBuilder.build({ ...options.contextRetention, ...input.context,
+                                request: source, budget: contextBudget }, signal);
+                            if (signal.aborted) {
+                                reason = 'cancelled';
+                                break;
+                            }
+                            if (built.request.sessionId !== scope.sessionId || built.request.turnId !== scope.turnId
+                                || built.request.step !== steps || JSON.stringify(built.request.tools) !== JSON.stringify(definitions)) {
+                                throw new Error('Context builder changed execution identity or tool definitions');
+                            }
+                            request = snapshot({ ...built.request, messages: history(built.request.messages, Infinity) });
+                            contextReports.push(snapshot({ step: steps, status: 'prepared', report: built.report }));
+                        }
+                        catch (cause) {
+                            if (cause instanceof ContextBuildError && cause.report) {
+                                contextReports.push(snapshot({ step: steps, status: 'failed', report: cause.report }));
+                            }
+                            if (signal.aborted) {
+                                reason = 'cancelled';
+                                break;
+                            }
+                            throw new AgentFault('context_error', cause instanceof Error ? cause.message : String(cause));
+                        }
+                        if (size(request) > limits.historyBytes) {
+                            throw new AgentFault('context_limit', 'Model request exceeds context byte limit');
+                        }
                         let raw;
                         try {
-                            raw = await options.provider.complete(request, signal);
+                            raw = await provider.complete(request, signal);
                         }
                         catch (cause) {
                             if (signal.aborted) {
@@ -89,56 +169,85 @@ export function createAgent(options) {
                         }
                         await append({ role: 'assistant', content: model.content, toolCalls: model.calls }, steps);
                         let uncertain = false;
-                        for (const call of model.calls) {
-                            usedIds.add(call.id);
-                            let outcome;
-                            if (sinkFailed || uncertain || signal.aborted) {
-                                outcome = failed(signal.aborted ? 'cancelled_before_start' : 'not_started', 'Tool was not started');
+                        const settled = new Map();
+                        let batchFailed = false;
+                        const acceptSettlement = async (settlement) => {
+                            const call = model.calls[settled.size];
+                            if (!call || settlement.identity.sessionId !== scope.sessionId
+                                || settlement.identity.turnId !== scope.turnId || settlement.identity.step !== steps
+                                || settlement.identity.toolCallId !== call.id || settlement.identity.name !== call.name
+                                || !validOutcome(settlement.outcome) || typeof settlement.started !== 'boolean'
+                                || !['not_acquired', 'released', 'failed', 'acquire_failed'].includes(settlement.cleanup?.status)) {
+                                throw new Error('Executor returned an invalid or out-of-order settlement');
                             }
-                            else {
-                                const tool = tools.get(call.name);
-                                if (!tool)
-                                    outcome = failed('unknown_tool', `Unknown tool: ${call.name}`);
-                                else {
-                                    // Validation has no effects. Unexpected execution failures conservatively
-                                    // preserve uncertainty and stop the batch; never retry a write.
-                                    try {
-                                        const invalid = tool.validate(call.arguments);
-                                        if (invalid) {
-                                            outcome = { ok: false, error: invalid };
-                                            if (!validOutcome(outcome))
-                                                outcome = failed('tool_protocol', 'Invalid tool validation result');
-                                        }
-                                        else {
-                                            await emit({ type: 'tool_started', step: steps, toolCallId: call.id, name: call.name });
-                                            if (sinkFailed || signal.aborted)
-                                                outcome = failed('not_started', 'Tool was not started');
-                                            else {
-                                                try {
-                                                    outcome = await tool.execute(call.arguments, { ...scope, step: steps, toolCallId: call.id }, signal);
-                                                    if (!validOutcome(outcome))
-                                                        outcome = failed('tool_protocol', 'Invalid tool result', 'unknown');
-                                                }
-                                                catch (cause) {
-                                                    outcome = failed('tool_exception', cause instanceof Error ? cause.message : String(cause), 'unknown');
-                                                }
-                                            }
-                                        }
-                                    }
-                                    catch {
-                                        outcome = failed('tool_validation', 'Tool validation failed');
+                            const saved = snapshot(settlement);
+                            settled.set(call.id, saved);
+                            await append({ role: 'tool', toolCallId: call.id, name: call.name, outcome: saved.outcome }, steps, saved);
+                        };
+                        if (!recordingFailed && !signal.aborted) {
+                            try {
+                                const batch = await executor.executeBatch({
+                                    calls: model.calls, scope: snapshot({ ...scope, step: steps }), signal,
+                                    async beforeExecute(identity) {
+                                        const call = model.calls[settled.size];
+                                        if (!call || identity.sessionId !== scope.sessionId || identity.turnId !== scope.turnId
+                                            || identity.step !== steps || identity.toolCallId !== call.id || identity.name !== call.name)
+                                            throw new Error('Executor intent identity does not match the next call');
+                                        if (recordingFailed)
+                                            throw new Error('Turn no longer permits a new tool effect');
+                                        if (signal.aborted)
+                                            return;
+                                        await emit({ type: 'tool_started', step: steps, toolCallId: call.id, name: call.name });
+                                        if (recordingFailed)
+                                            throw new Error('Required intent recording stopped execution');
+                                        // The executor checks cancellation after this barrier. A
+                                        // successful write followed by cancellation is not a failed write.
+                                    },
+                                    async afterExecute(settlement) {
+                                        await acceptSettlement(settlement);
+                                        if (recordingFailed)
+                                            throw new Error('Required settlement recording failed; do not start further effects');
+                                    },
+                                });
+                                if (batch.results.length !== model.calls.length)
+                                    throw new Error('Executor omitted settlements');
+                                for (const settlement of batch.results) {
+                                    const recorded = settled.get(settlement.identity.toolCallId);
+                                    if (recorded) {
+                                        if (JSON.stringify(recorded) !== JSON.stringify(settlement))
+                                            throw new Error('Executor changed a recorded settlement');
                                     }
+                                    else
+                                        await acceptSettlement(settlement);
+                                }
+                                batchFailed = !!batch.recordingError || (batch.stopped !== null && batch.stopped !== 'cancelled');
+                                if (batchFailed) {
+                                    const unknown = batch.results.find(r => !r.outcome.ok && r.outcome.error.effect === 'unknown')?.outcome;
+                                    error ??= unknown && !unknown.ok ? unknown.error : {
+                                        code: batch.recordingError?.code ?? batch.stopped,
+                                        message: batch.recordingError?.message ?? `Tool batch stopped: ${batch.stopped}; inspect settlement evidence`,
+                                    };
                                 }
                             }
-                            if (!validOutcome(outcome))
-                                outcome = failed('tool_protocol', 'Invalid tool failure result', 'unknown');
+                            catch (cause) {
+                                batchFailed = true;
+                                error ??= { code: 'tool_protocol', message: cause instanceof Error ? cause.message : String(cause) };
+                            }
+                        }
+                        for (const call of model.calls) {
+                            usedIds.add(call.id);
+                            const receipt = settled.get(call.id);
+                            const outcome = receipt?.outcome ?? (batchFailed
+                                ? failed('tool_protocol', 'Executor did not return a confirmed settlement', 'unknown')
+                                : failed(signal.aborted ? 'cancelled_before_start' : 'not_started', 'Tool was not started'));
                             if (!outcome.ok && outcome.error.effect === 'unknown') {
                                 uncertain = true;
                                 error ??= { code: outcome.error.code, message: outcome.error.message };
                             }
-                            await append({ role: 'tool', toolCallId: call.id, name: call.name, outcome }, steps);
+                            if (!receipt)
+                                await append({ role: 'tool', toolCallId: call.id, name: call.name, outcome }, steps);
                         }
-                        if (uncertain || sinkFailed) {
+                        if (uncertain || recordingFailed || batchFailed) {
                             reason = 'error';
                             break;
                         }
@@ -157,17 +266,10 @@ export function createAgent(options) {
                     message: cause instanceof Error ? cause.message : String(cause) };
                 reason = 'error';
             }
-            if (sinkFailed)
+            if (recordingFailed)
                 reason = 'error';
-            // If the sink rejects the terminal itself, replace that one in-memory
-            // terminal with the truthful failure. Never recursively retry the sink.
             await emit({ type: 'turn_ended', reason, ...(error ? { errorCode: error.code } : {}) });
-            if (sinkFailed) {
-                reason = 'error';
-                const last = events[events.length - 1];
-                events[events.length - 1] = snapshot({ ...last, data: { type: 'turn_ended', reason, errorCode: error.code } });
-            }
-            return snapshot({ ...scope, reason, messages, events, steps, ...(error ? { error } : {}) });
+            return snapshot({ ...scope, reason, messages, events, steps, recording, observerErrors, contextReports, ...(error ? { error } : {}) });
         },
     };
 }

package/dist/nativeAgent/cliDemo.js

@@ -0,0 +1,37 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { createMockProvider, createTextTools } from './index.js';
+import { createMemoryDemoSessions, openCli } from './interaction/index.js';
+// This program owns its disposable files and execution service. The CLI itself
+// only detaches; this owner explicitly cancels and settles turns on process exit.
+let root;
+let sessions;
+let cli;
+let stopping = false;
+const interrupt = () => { stopping = true; cli?.close(); };
+process.on('SIGINT', interrupt);
+process.on('SIGTERM', interrupt);
+try {
+    root = await mkdtemp(path.join(tmpdir(), 'independent-agent-cli-'));
+    await writeFile(path.join(root, 'input.txt'), 'Disposable mock CLI example.\n');
+    let draw = 0;
+    sessions = createMemoryDemoSessions({
+        provider: createMockProvider({ toolCallProbability: 0.5, random: () => [0.1, 0.2, 0.9][draw++ % 3] }),
+        tools: createTextTools({ root }),
+    });
+    cli = await openCli({ sessions, input: process.stdin, output: process.stdout });
+    if (stopping)
+        cli.close();
+    const end = await cli.done;
+    if (end.reason === 'display-error' || end.reason === 'input-error')
+        process.exitCode = 1;
+}
+finally {
+    process.off('SIGINT', interrupt);
+    process.off('SIGTERM', interrupt);
+    cli?.close();
+    await sessions?.close();
+    if (root)
+        await rm(root, { recursive: true, force: true });
+}

package/dist/nativeAgent/codingTools.js

@@ -0,0 +1,11 @@
+import { createTextTools } from './textTools.js';
+import { createSearchTools } from './searchTools.js';
+import { createCommandTool } from './commandTool.js';
+/** Explicit assembly only; each returned Tool can instead be selected or replaced independently. */
+export function createCodingTools(options) {
+    return [
+        ...createTextTools({ ...options.text, root: options.root }),
+        ...createSearchTools({ ...options.search, root: options.root }),
+        ...(options.command ? [createCommandTool({ ...options.command, root: options.root })] : []),
+    ];
+}

package/dist/nativeAgent/commandTool.js

@@ -0,0 +1,215 @@
+import { spawn } from 'node:child_process';
+import { realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+const failure = (code, message, effect = 'none') => ({ ok: false, error: { code, message, effect } });
+const inRoot = (root, cwd) => {
+    const relative = path.relative(root, cwd);
+    return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+};
+const bounded = (value, maximum, label) => {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+        throw new Error(`${label} must be an integer in [1, ${maximum}]`);
+    }
+    return value;
+};
+/**
+ * Controlled POSIX commands only, not an OS sandbox. Commands can access paths
+ * outside cwd, perform external effects, or escape the process group themselves.
+ * Callers must authorize the executable/arguments and supply a deliberate env.
+ */
+export function createCommandTool(options) {
+    if (process.platform === 'win32')
+        throw new Error('Command tool requires POSIX process groups');
+    if (!options || typeof options.root !== 'string' || !path.isAbsolute(options.root)) {
+        throw new Error('An explicit absolute workspace root is required');
+    }
+    const root = realpathSync(options.root);
+    if (!statSync(root).isDirectory())
+        throw new Error('Workspace root must be a directory');
+    if (!options.env || typeof options.env !== 'object' || Array.isArray(options.env)
+        || Object.entries(options.env).some(([key, value]) => !key || /[=\0]/.test(key) || typeof value !== 'string' || value.includes('\0'))) {
+        throw new Error('An explicit string environment without NUL or invalid keys is required');
+    }
+    const env = { ...options.env };
+    const timeoutMs = bounded(options.timeoutMs ?? 10_000, 60_000, 'timeoutMs');
+    const maxOutputBytes = bounded(options.maxOutputBytes ?? 64 * 1024, 64 * 1024, 'maxOutputBytes');
+    const killGraceMs = bounded(options.killGraceMs ?? 100, 1000, 'killGraceMs');
+    const validate = (args) => {
+        if (!args || typeof args !== 'object' || Array.isArray(args)
+            || Object.keys(args).some(key => !['command', 'argv', 'cwd'].includes(key))
+            || typeof args.command !== 'string' || !path.isAbsolute(args.command) || args.command.includes('\0')
+            || typeof args.cwd !== 'string' || !path.isAbsolute(args.cwd) || args.cwd.includes('\0')
+            || !Array.isArray(args.argv) || args.argv.length > 256
+            || args.argv.some(arg => typeof arg !== 'string' || arg.includes('\0'))
+            // Evidence echoes argv. Its JSON string is encoded once more in the
+            // ToolOutcome: reserve room for 64KiB of worst-case control-byte output
+            // (7x after both JSON encodings) within the public 512KiB message bound.
+            || Buffer.byteLength(JSON.stringify(args)) > 16 * 1024) {
+            return { code: 'invalid_arguments', message: 'Expected absolute command/cwd and bounded string argv only', effect: 'none' };
+        }
+        if (!inRoot(root, path.resolve(args.cwd))) {
+            return { code: 'path_out_of_scope', message: 'cwd must be within the explicit workspace root', effect: 'none' };
+        }
+        return null;
+    };
+    return {
+        definition: {
+            name: 'command',
+            description: 'Execute an explicitly authorized POSIX executable and argv in a controlled workspace; no implicit shell or OS sandbox',
+            inputSchema: {
+                type: 'object', properties: {
+                    command: { type: 'string', description: 'Absolute executable path' },
+                    argv: { type: 'array', items: { type: 'string' }, maxItems: 256 },
+                    cwd: { type: 'string', description: 'Absolute working directory within configured root' },
+                }, required: ['command', 'argv', 'cwd'], additionalProperties: false,
+            },
+        },
+        validate,
+        async execute(args, _scope, signal) {
+            const invalid = validate(args);
+            if (invalid)
+                return { ok: false, error: invalid };
+            if (signal.aborted)
+                return failure('cancelled_before_start', 'Command was not started');
+            const input = args;
+            // Copy caller-owned data before spawning; direct execute calls receive the
+            // same checks as calls through the Agent loop.
+            const command = input.command;
+            const argv = [...input.argv];
+            let cwd;
+            try {
+                cwd = realpathSync(input.cwd);
+                if (!inRoot(root, cwd))
+                    return failure('path_out_of_scope', 'Resolved cwd is outside workspace root');
+                if (!statSync(cwd).isDirectory())
+                    return failure('invalid_cwd', 'cwd is not a directory');
+            }
+            catch {
+                return failure('invalid_cwd', 'cwd cannot be resolved as an accessible directory');
+            }
+            return new Promise(resolve => {
+                let child;
+                try {
+                    child = spawn(command, argv, { cwd, env, shell: false, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+                }
+                catch (error) {
+                    resolve(failure('spawn_failed', `Command could not be spawned (${error.code ?? 'unknown'})`));
+                    return;
+                }
+                let settled = false;
+                let started = false;
+                let directChildExited = false;
+                let exitCode = null;
+                let exitSignal = null;
+                let reason;
+                let processErrorCode = null;
+                let captured = 0;
+                let outputTruncated = false;
+                const stdout = [];
+                const stderr = [];
+                const signalErrors = [];
+                let grace;
+                let settle;
+                const groupState = () => {
+                    if (!child.pid)
+                        return 'absent';
+                    try {
+                        process.kill(-child.pid, 0);
+                        return 'present';
+                    }
+                    catch (error) {
+                        return error.code === 'ESRCH' ? 'absent' : 'unknown';
+                    }
+                };
+                const signalGroup = (kind) => {
+                    if (!child.pid)
+                        return;
+                    try {
+                        process.kill(-child.pid, kind);
+                    }
+                    catch (error) {
+                        const code = error.code;
+                        if (code !== 'ESRCH')
+                            signalErrors.push(`${kind}:${code ?? 'unknown'}`);
+                    }
+                };
+                const finish = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(deadline);
+                    clearTimeout(grace);
+                    clearTimeout(settle);
+                    signal.removeEventListener('abort', abort);
+                    child.stdout.destroy();
+                    child.stderr.destroy();
+                    // A failure to observe termination must not keep the caller waiting
+                    // forever. Keep the pid and uncertainty in the returned evidence.
+                    child.unref();
+                    const evidence = {
+                        command, argv, cwd, pid: child.pid ?? null, exitCode, signal: exitSignal,
+                        stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8'),
+                        capturedBytes: captured, outputTruncated, directChildExited,
+                        processGroup: groupState(), signalErrors, processErrorCode,
+                        descendantsMayHaveEscaped: true,
+                    };
+                    resolve(reason
+                        ? failure(reason, JSON.stringify(evidence), started ? 'unknown' : 'none')
+                        : { ok: true, content: JSON.stringify(evidence) });
+                };
+                const stop = (code) => {
+                    if (settled || reason)
+                        return;
+                    reason = code;
+                    signalGroup('SIGTERM');
+                    grace = setTimeout(() => {
+                        signalGroup('SIGKILL');
+                        // Bound observation after escalation; never infer quiescence from a
+                        // successful signal syscall, or wait forever on inherited pipes.
+                        settle = setTimeout(finish, 100);
+                    }, killGraceMs);
+                };
+                const abort = () => stop('cancelled');
+                const deadline = setTimeout(() => stop('timeout'), timeoutMs);
+                signal.addEventListener('abort', abort, { once: true });
+                const capture = (target, chunk) => {
+                    const available = maxOutputBytes - captured;
+                    if (available > 0) {
+                        const kept = chunk.subarray(0, available);
+                        target.push(Buffer.from(kept));
+                        captured += kept.length;
+                    }
+                    if (chunk.length > available) {
+                        outputTruncated = true;
+                        stop('output_limit');
+                    }
+                };
+                child.stdout.on('data', (chunk) => capture(stdout, chunk));
+                child.stderr.on('data', (chunk) => capture(stderr, chunk));
+                child.once('spawn', () => { started = true; });
+                child.once('error', error => {
+                    processErrorCode = error.code ?? 'unknown';
+                    if (started)
+                        stop('process_error');
+                    else {
+                        reason = 'spawn_failed';
+                        finish();
+                    }
+                });
+                child.once('exit', (code, receivedSignal) => {
+                    directChildExited = true;
+                    exitCode = code;
+                    exitSignal = receivedSignal;
+                    if (!reason && groupState() !== 'absent')
+                        stop('background_processes');
+                });
+                child.once('close', () => {
+                    if (!reason)
+                        finish();
+                });
+                if (signal.aborted)
+                    abort();
+            });
+        },
+    };
+}