@juzser/blacksmith 0.1.1 → 0.2.0

package/factory/orchestrator/dist/plan.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { unreadTaskBudgetFields } from './budgets.js';
+import { claimCoversPath } from './claims.js';
 import { SmithError } from './errors.js';
 import { topoSort } from './graph.js';
 import { SPECS_ACTIVE_DIR } from './paths.js';
@@ -170,6 +171,62 @@ function describeAllowed(err) {
  * validateRequiredDimensions directly rather than acquiring a second register
  * of what an edge must carry, which could then drift from taxonomy.yml's.
  */
+const GLOB_CHARS = /[*?[{]/;
+/**
+ * A `keeps_exports` promise is a file the task swears to keep the exports of,
+ * and the post-run verifier reads it back against the task's diff. Three
+ * things make a promise unverifiable, and each is caught here, at plan time:
+ * a pattern (the verifier diffs one file, not a glob), a file outside the
+ * task's claims (the task cannot edit it, so its diff never shows it), and a
+ * file listed twice (which entry did the verifier report?). Shape is the
+ * schema's business; when the schema already rejected the field, this reads
+ * nothing and reports nothing, so the operator sees one error, not two.
+ */
+function unkeptPromises(t, schemaIssues) {
+    const promises = t.keeps_exports;
+    if (promises === undefined)
+        return [];
+    if (schemaIssues.some((issue) => issue.path.startsWith('/keeps_exports')))
+        return [];
+    if (!Array.isArray(promises) || !promises.every((p) => typeof p === 'string')) {
+        return [{ path: '/keeps_exports', message: 'keeps_exports is not a list of file paths.' }];
+    }
+    const claims = Array.isArray(t.claims)
+        ? t.claims.filter((c) => typeof c === 'string')
+        : [];
+    const issues = [];
+    const seen = new Set();
+    promises.forEach((promise, index) => {
+        const at = `/keeps_exports/${index}`;
+        if (promise === '') {
+            issues.push({
+                path: at,
+                message: `keeps_exports entry ${index} is an empty string, not a file path.`,
+            });
+            return;
+        }
+        if (GLOB_CHARS.test(promise)) {
+            issues.push({
+                path: at,
+                message: `keeps_exports entry "${promise}" is a pattern: a promise names one file, not a pattern.`,
+            });
+            return;
+        }
+        if (!claims.some((claim) => claimCoversPath(claim, promise))) {
+            issues.push({
+                path: at,
+                message: `keeps_exports entry "${promise}" lies outside the task's claims: a task can only keep the exports of a file it may edit.`,
+            });
+            return;
+        }
+        if (seen.has(promise)) {
+            issues.push({ path: at, message: `keeps_exports entry "${promise}" is listed twice.` });
+            return;
+        }
+        seen.add(promise);
+    });
+    return issues;
+}
 export function validatePlan(plan, opts = {}) {
     const { taxonomy, schemas } = resolveTaxonomyAndSchemas(opts);
     const errors = [];
@@ -192,6 +249,9 @@ export function validatePlan(plan, opts = {}) {
                 errors.push({ path: `/tasks/${t.task_id}${issue.path}`, message: issue.message });
             }
         }
+        for (const issue of unkeptPromises(t, result.valid ? [] : result.errors)) {
+            errors.push({ path: `/tasks/${t.task_id}${issue.path}`, message: issue.message });
+        }
         if (t.plan_version !== plan.version) {
             errors.push({
                 path: `/tasks/${t.task_id}/plan_version`,

package/factory/orchestrator/dist/providers/cli-transport.js

@@ -3,7 +3,7 @@
 // providers.md). Prompt delivery: STDIN, not a temp file — no filesystem
 // cleanup/race to manage, and a CLI judge that reads a prompt off stdin
 // (same as an interactive paste) needs no extra flag wiring per provider.
-import { spawn } from 'node:child_process';
+import { spawnCapped } from '../spawn.js';
 import { extractAndValidate } from './schema-validate.js';
 import { ProviderError } from './types.js';
 const NUDGE = '\n\nReturn only valid JSON per schema.';
@@ -40,80 +40,14 @@ function diagnosticFor(outcome) {
     return combined === '' ? errOnly : `${errOnly} | ${combined}`;
 }
 /**
- * One CLI judge invocation: detached process group (POSIX `setsid` via
- * `detached: true`) + group-kill on timeout or size-cap breach — mirrors
- * testgate.ts's runOne() exactly (a judge CLI can spawn its own child
- * processes; a plain per-child kill would orphan them the same way
- * testgate's own regression note describes).
+ * One CLI judge invocation via the shared capped spawn (src/spawn.ts). No
+ * `cwd` in the call: a CLI judge transport is handed a prompt and nothing
+ * else — architecture §18 rule 5, "judges never gain write access" — and a
+ * process started with no working directory of its own has no worktree to
+ * write into even if its command line wanted one.
  */
 function spawnOnce(config, prompt, budget) {
-    return new Promise((resolve) => {
-        const child = spawn(config.command, config.args, {
-            detached: true,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        let combined = '';
-        let stderr = '';
-        let totalBytes = 0;
-        let timedOut = false;
-        let sizeExceeded = false;
-        let settled = false;
-        let spawnError;
-        const killGroup = () => {
-            if (child.pid !== undefined) {
-                try {
-                    process.kill(-child.pid, 'SIGKILL');
-                }
-                catch {
-                    // Group already gone — fine.
-                }
-            }
-        };
-        const timer = setTimeout(() => {
-            timedOut = true;
-            killGroup();
-        }, budget.timeout_ms);
-        const onChunk = (chunk) => {
-            totalBytes += chunk.length;
-            if (totalBytes > budget.max_output_bytes) {
-                if (!sizeExceeded) {
-                    sizeExceeded = true;
-                    killGroup();
-                }
-                return;
-            }
-            combined += chunk.toString('utf8');
-        };
-        child.stdout?.on('data', onChunk);
-        child.stderr?.on('data', (chunk) => {
-            // Still folded into `combined` for extraction — a judge that writes its
-            // verdict to stderr has always worked and must keep working. The second
-            // copy exists only so a refusal reason can be reported on its own.
-            stderr += chunk.toString('utf8');
-            onChunk(chunk);
-        });
-        child.stdin?.on('error', () => {
-            // Judge exited before consuming stdin (e.g. a fixture that errors
-            // immediately) — writing to a closed pipe would otherwise raise an
-            // unhandled EPIPE; the close handler below still resolves correctly.
-        });
-        child.stdin?.write(prompt);
-        child.stdin?.end();
-        const finish = (exitCode, signal) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            resolve({ combined, stderr, exitCode, signal, spawnError, timedOut, sizeExceeded });
-        };
-        child.on('error', (err) => {
-            // The child never ran (ENOENT, EACCES, …). Distinct from a child that
-            // ran and failed: 'close' carries no code in this case.
-            spawnError = err;
-            finish(null, null);
-        });
-        child.on('close', finish);
-    });
+    return spawnCapped({ command: config.command, args: config.args }, prompt, budget);
 }
 /**
  * The buffer minus the prompt this process just sent, for the extractor to

package/factory/orchestrator/dist/run-cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// smith-run: a separate executable, not a `smith` verb. `smith harness plan`
+// renders a WorkerInvocation and stops there — architecture §18 rule 3,
+// "nothing that observes may dispatch". This program is the only thing in
+// this repo that actually starts one, and it does nothing else: no event
+// log, no state/, no DB (see runner.ts's own header and its source-level
+// test in test/runner.test.ts).
+import { readFileSync, writeFileSync } from 'node:fs';
+import { parseArgs } from './args.js';
+import { runInvocation } from './runner.js';
+const HELP = `Usage: smith-run <invocation.json | -> [--prompt-file <path>] [--timeout-ms <n>] [--out <file>]
+
+Spawns ONE already-rendered worker invocation (the JSON \`smith harness plan\`
+prints) and reports what happened as JSON. This is not \`smith harness run\`:
+\`smith\` only ever renders an invocation and never starts it (§18 rule 3,
+"nothing that observes may dispatch"), so starting the process an invocation
+describes lives in its own binary instead.
+
+Arguments:
+  <invocation.json>     Path to a rendered WorkerInvocation, or "-" for stdin.
+
+Options:
+  --prompt-file <path>  Read the prompt from this file instead of invocation.promptFile.
+  --timeout-ms <n>       Override invocation.budget.timeout_ms for this run.
+  --out <file>           Write the JSON result here instead of stdout.
+  --help                 Show this message.
+
+Exit codes:
+  0  completed (exit 0), answer validated against its schema (or no schema set)
+  1  the harness process failed to start, or exited non-zero, or the harness
+     reported an error in its output
+  2  completed (exit 0), but schema validation failed
+  3  timed out, or exceeded the output size cap
+`;
+const FLAG_SPEC = new Map([
+    ['prompt-file', true],
+    ['timeout-ms', true],
+    ['out', true],
+    ['help', false],
+]);
+function readInvocation(source) {
+    const text = source === '-' ? readFileSync(0, 'utf8') : readFileSync(source, 'utf8');
+    return JSON.parse(text);
+}
+/** See HELP's own exit-code table — kept in one place so the two cannot drift. */
+function exitCodeFor(outcome) {
+    if (outcome.spawnError !== null)
+        return 1;
+    if (outcome.timedOut || outcome.sizeExceeded)
+        return 3;
+    if (outcome.exitCode !== 0)
+        return 1;
+    // The process exited 0, but its own output reported a failure (a codex
+    // top-level `error` event, or claude's `is_error: true`) — only reachable
+    // for a clean exit, since a nonzero exitCode above already returned 1.
+    if (outcome.harness_error !== null)
+        return 1;
+    if (outcome.validation !== null && !outcome.validation.ok)
+        return 2;
+    return 0;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const parsed = parseArgs(argv, FLAG_SPEC);
+    if (parsed.flags.help === 'true') {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    const source = parsed.positional[0];
+    if (source === undefined) {
+        process.stderr.write('smith-run: missing <invocation.json | -> argument.\n\n');
+        process.stderr.write(HELP);
+        return 1;
+    }
+    let invocation;
+    try {
+        invocation = readInvocation(source);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`smith-run: could not read/parse invocation: ${message}\n`);
+        return 1;
+    }
+    const timeoutOverride = parsed.flags['timeout-ms'];
+    if (timeoutOverride !== undefined && invocation.kind === 'cli') {
+        const timeout_ms = Number.parseInt(timeoutOverride, 10);
+        if (Number.isNaN(timeout_ms)) {
+            process.stderr.write(`smith-run: --timeout-ms must be a number, got "${timeoutOverride}".\n`);
+            return 1;
+        }
+        invocation = { ...invocation, budget: { ...invocation.budget, timeout_ms } };
+    }
+    const opts = {};
+    const promptFile = parsed.flags['prompt-file'];
+    if (promptFile !== undefined) {
+        try {
+            opts.promptText = readFileSync(promptFile, 'utf8');
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`smith-run: could not read --prompt-file: ${message}\n`);
+            return 1;
+        }
+    }
+    let outcome;
+    try {
+        outcome = await runInvocation(invocation, opts);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`smith-run: ${message}\n`);
+        return 1;
+    }
+    const json = `${JSON.stringify(outcome, null, 2)}\n`;
+    const outFile = parsed.flags.out;
+    if (outFile !== undefined) {
+        writeFileSync(outFile, json);
+    }
+    else {
+        process.stdout.write(json);
+    }
+    return exitCodeFor(outcome);
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+    process.stderr.write(`smith-run: unexpected error: ${message}\n`);
+    process.exitCode = 1;
+});

package/factory/orchestrator/dist/runner.js

@@ -0,0 +1,264 @@
+// smith-run's library half (architecture §18 rule 3: "nothing that observes
+// may dispatch"). harness.ts's planWorkerTurn() renders a WorkerInvocation
+// but never spawns it — this is the one function that actually starts a
+// harness program. Imports nothing under src/db/, src/events.ts or
+// src/projector.ts on purpose (see test/runner.test.ts's own source-level
+// check): a function that can start a process has no business also being
+// able to see or extend the event log.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { SmithError } from './errors.js';
+import { REPO_ROOT } from './paths.js';
+import { extractAndValidate, extractBalancedJson } from './providers/schema-validate.js';
+import { spawnCapped } from './spawn.js';
+export class RunnerError extends SmithError {
+}
+/**
+ * harness.yml's own two shipped CLI harnesses both set an explicit
+ * `timeout_ms`; this only covers a hand-built WorkerInvocation (or a future
+ * policy entry) that leaves it null. 30 minutes, same order of magnitude as
+ * those two examples.
+ */
+export const RUNNER_DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+const FRONTMATTER = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/;
+/** Strips a role template's leading `---`-delimited YAML frontmatter, keeping only the markdown body. */
+function stripFrontmatter(templateText) {
+    return templateText.replace(FRONTMATTER, '');
+}
+/** Builds the child's environment from the invocation's allowlist only — never the full parent env. */
+function buildEnv(envAllowlist, parentEnv) {
+    const env = {};
+    for (const name of envAllowlist) {
+        const value = parentEnv[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    return env;
+}
+const DIAGNOSTIC_TAIL_BYTES = 400;
+/** Last few hundred bytes of stderr, collapsed to one line — same convention as cli-transport.ts's tail(). */
+function tail(text) {
+    const trimmed = text.trim();
+    const cut = trimmed.length > DIAGNOSTIC_TAIL_BYTES ? trimmed.slice(-DIAGNOSTIC_TAIL_BYTES) : trimmed;
+    return cut.replace(/\s+/g, ' ');
+}
+/** codex's own `input_tokens` already includes its `cached_input_tokens` — pass through as-is. */
+function normalizeCodexUsage(raw) {
+    const input = raw.input_tokens ?? 0;
+    const output = raw.output_tokens ?? 0;
+    const cached = raw.cached_input_tokens;
+    return {
+        input_tokens: input,
+        output_tokens: output,
+        ...(cached !== undefined ? { cached_input_tokens: cached } : {}),
+        total_tokens: input + output,
+    };
+}
+/**
+ * Parses a `codex exec --json` JSONL stream: last `agent_message` item wins,
+ * `turn.completed` carries usage, and a top-level `{"type":"error", ...}`
+ * line — distinct from a non-fatal `item.completed` item whose own
+ * `item.type` is `"error"`, which stays ignored — sets `harness_error` (last
+ * one wins, same convention as `agent_message`). The process can still exit
+ * 0 and carry both an answer and a harness_error: codex reports partial
+ * progress before a failure, and neither field should hide the other.
+ */
+function parseCodexJson(combined) {
+    let answer = '';
+    let usage = null;
+    let harness_error = null;
+    for (const line of combined.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (typeof event !== 'object' || event === null)
+            continue;
+        const record = event;
+        if (record.type === 'item.completed') {
+            const item = record.item;
+            if (item !== undefined && item.type === 'agent_message' && typeof item.text === 'string') {
+                answer = item.text;
+            }
+        }
+        else if (record.type === 'turn.completed') {
+            const rawUsage = record.usage;
+            if (rawUsage !== undefined)
+                usage = normalizeCodexUsage(rawUsage);
+        }
+        else if (record.type === 'error' && typeof record.message === 'string') {
+            harness_error = record.message;
+        }
+    }
+    return { answer, usage, harness_error };
+}
+/** Anthropic's raw `input_tokens` excludes cache tokens — fold cache-creation + cache-read into it. */
+function normalizeClaudeUsage(raw) {
+    const cached = (raw.cache_creation_input_tokens ?? 0) + (raw.cache_read_input_tokens ?? 0);
+    const input = (raw.input_tokens ?? 0) + cached;
+    const output = raw.output_tokens ?? 0;
+    return {
+        input_tokens: input,
+        output_tokens: output,
+        cached_input_tokens: cached,
+        total_tokens: input + output,
+    };
+}
+/**
+ * Parses a `claude -p --output-format json` single JSON object.
+ * `is_error: true` is `claude -p`'s own way of reporting a failed turn while
+ * still exiting 0 — `harness_error` prefers `subtype` (e.g.
+ * `error_during_execution`), falls back to `result` when that is the only
+ * string the payload carries, and otherwise names the shape generically.
+ * `answer` still comes from `result` either way, unchanged from today.
+ */
+function parseClaudeJson(combined) {
+    const value = extractBalancedJson(combined);
+    if (typeof value !== 'object' || value === null) {
+        return { answer: combined.trim(), usage: null, harness_error: null };
+    }
+    const record = value;
+    const answer = typeof record.result === 'string' ? record.result : combined.trim();
+    const rawUsage = record.usage;
+    const usage = rawUsage !== undefined ? normalizeClaudeUsage(rawUsage) : null;
+    const harness_error = record.is_error === true
+        ? typeof record.subtype === 'string' && record.subtype !== ''
+            ? record.subtype
+            : typeof record.result === 'string' && record.result !== ''
+                ? record.result
+                : 'claude reported is_error'
+        : null;
+    return {
+        answer,
+        usage,
+        harness_error,
+        ...(typeof record.session_id === 'string' ? { session_id: record.session_id } : {}),
+        ...(typeof record.total_cost_usd === 'number' ? { cost_usd: record.total_cost_usd } : {}),
+    };
+}
+/** Dispatches on the invocation's declared output mode — never sniffs the payload to guess it. */
+function parseOutput(mode, combined) {
+    if (mode === 'codex-json')
+        return parseCodexJson(combined);
+    if (mode === 'claude-json')
+        return parseClaudeJson(combined);
+    return { answer: combined.trim(), usage: null, harness_error: null };
+}
+/** Validates the answer against a schema when one is set; reports failure, never throws. */
+function validate(answer, schema) {
+    if (schema === null)
+        return { validation: null, parsed: null };
+    const result = extractAndValidate(answer, schema);
+    if (result.valid)
+        return { validation: { ok: true }, parsed: result.value };
+    const errors = 'errors' in result
+        ? result.errors.map((issue) => `${issue.path}: ${issue.message}`)
+        : [result.reason];
+    return { validation: { ok: false, errors }, parsed: null };
+}
+/**
+ * Actually spawns a rendered `WorkerInvocation` — the one thing harness.ts
+ * itself is forbidden from doing. Refuses `in-process` invocations: those are
+ * Agent-tool subagent turns, not programs smith-run knows how to start.
+ */
+export async function runInvocation(invocation, opts = {}) {
+    if (invocation.kind === 'in-process') {
+        throw new RunnerError('runner.in-process', `Invocation for role "${invocation.role}" is in-process (harness "${invocation.harness}") — ` +
+            'smith-run starts programs, not Agent-tool subagents. In-process harnesses run inside the ' +
+            'orchestrator session itself and have no separate binary for smith-run to spawn.', { harness: invocation.harness, role: invocation.role });
+    }
+    const now = opts.now ?? Date.now;
+    const start = now();
+    const prompt = opts.promptText ?? readFileSync(invocation.promptFile, 'utf8');
+    const templatePath = path.join(REPO_ROOT, invocation.template);
+    const templateBody = stripFrontmatter(readFileSync(templatePath, 'utf8'));
+    const stdin = `${templateBody}\n\n${prompt}`;
+    const env = buildEnv(invocation.envAllowlist, opts.env ?? process.env);
+    const timeout_ms = invocation.budget.timeout_ms ?? RUNNER_DEFAULT_TIMEOUT_MS;
+    let outcome;
+    try {
+        outcome = await spawnCapped({
+            command: invocation.command,
+            args: [...invocation.args],
+            cwd: invocation.cwd ?? undefined,
+            env,
+        }, stdin, { timeout_ms, max_output_bytes: invocation.budget.max_output_bytes });
+    }
+    catch (err) {
+        // spawnCapped resolves rather than rejects on a spawn failure; this catch
+        // is defensive only, kept so a future change there cannot turn into an
+        // uncaught rejection here.
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            harness: invocation.harness,
+            role: invocation.role,
+            taskId: invocation.taskId,
+            exitCode: null,
+            signal: null,
+            timedOut: false,
+            sizeExceeded: false,
+            spawnError: message,
+            latency_ms: now() - start,
+            answer: '',
+            parsed: null,
+            validation: null,
+            usage: null,
+            over_budget: null,
+            stderr_tail: '',
+            harness_error: null,
+        };
+    }
+    const latency_ms = now() - start;
+    if (outcome.spawnError !== undefined) {
+        const reason = outcome.spawnError.code ?? outcome.spawnError.message;
+        return {
+            harness: invocation.harness,
+            role: invocation.role,
+            taskId: invocation.taskId,
+            exitCode: null,
+            signal: null,
+            timedOut: outcome.timedOut,
+            sizeExceeded: outcome.sizeExceeded,
+            spawnError: reason,
+            latency_ms,
+            answer: '',
+            parsed: null,
+            validation: null,
+            usage: null,
+            over_budget: null,
+            stderr_tail: tail(outcome.stderr),
+            harness_error: null,
+        };
+    }
+    const { answer, usage, harness_error } = parseOutput(invocation.output, outcome.combined);
+    const { validation, parsed } = validate(answer, invocation.schema);
+    // Unknown (null) unless the harness both sets a cap and the output mode
+    // reported usage to compare it against — never guess a verdict either way.
+    const over_budget = invocation.budget.cap_tokens === null || usage === null
+        ? null
+        : usage.total_tokens > invocation.budget.cap_tokens;
+    return {
+        harness: invocation.harness,
+        role: invocation.role,
+        taskId: invocation.taskId,
+        exitCode: outcome.exitCode,
+        signal: outcome.signal,
+        timedOut: outcome.timedOut,
+        sizeExceeded: outcome.sizeExceeded,
+        spawnError: null,
+        latency_ms,
+        answer,
+        parsed,
+        validation,
+        usage,
+        over_budget,
+        stderr_tail: tail(outcome.stderr),
+        harness_error,
+    };
+}

package/factory/orchestrator/dist/spawn.js

@@ -0,0 +1,84 @@
+// A capped, detached-group child process — the mechanics both cli-transport.ts
+// (an external judge, no worktree, no cwd) and runner.ts (smith-run, a
+// harness that may hold a worktree) spawn a process the same way. Extracted
+// so the two do not carry two copies of a timeout/size-cap/group-kill
+// implementation that drift the way SpawnOnce's original inline copy would
+// have, the day a second caller needed it.
+import { spawn } from 'node:child_process';
+/**
+ * One spawn: detached process group (POSIX `setsid` via `detached: true`) +
+ * group-kill on timeout or size-cap breach — mirrors testgate.ts's runOne()
+ * exactly (a spawned CLI can start its own children; a plain per-child kill
+ * would orphan them the same way testgate's own regression note describes).
+ */
+export function spawnCapped(config, stdin, budget) {
+    return new Promise((resolve) => {
+        const child = spawn(config.command, config.args, {
+            cwd: config.cwd,
+            env: config.env,
+            detached: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let combined = '';
+        let stderr = '';
+        let totalBytes = 0;
+        let timedOut = false;
+        let sizeExceeded = false;
+        let settled = false;
+        let spawnError;
+        const killGroup = () => {
+            if (child.pid !== undefined) {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch {
+                    // Group already gone — fine.
+                }
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup();
+        }, budget.timeout_ms);
+        const onChunk = (chunk) => {
+            totalBytes += chunk.length;
+            if (totalBytes > budget.max_output_bytes) {
+                if (!sizeExceeded) {
+                    sizeExceeded = true;
+                    killGroup();
+                }
+                return;
+            }
+            combined += chunk.toString('utf8');
+        };
+        child.stdout?.on('data', onChunk);
+        child.stderr?.on('data', (chunk) => {
+            // Still folded into `combined` for extraction — a judge that writes its
+            // verdict to stderr has always worked and must keep working. The second
+            // copy exists only so a refusal reason can be reported on its own.
+            stderr += chunk.toString('utf8');
+            onChunk(chunk);
+        });
+        child.stdin?.on('error', () => {
+            // Child exited before consuming stdin (e.g. a fixture that errors
+            // immediately) — writing to a closed pipe would otherwise raise an
+            // unhandled EPIPE; the close handler below still resolves correctly.
+        });
+        child.stdin?.write(stdin);
+        child.stdin?.end();
+        const finish = (exitCode, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ combined, stderr, exitCode, signal, spawnError, timedOut, sizeExceeded });
+        };
+        child.on('error', (err) => {
+            // The child never ran (ENOENT, EACCES, …). Distinct from a child that
+            // ran and failed: 'close' carries no code in this case.
+            spawnError = err;
+            finish(null, null);
+        });
+        child.on('close', finish);
+    });
+}