@dyx9/rosetta 0.0.0-stage → 0.0.1

package/build/server/records/turn-recording.js

@@ -0,0 +1,151 @@
+/** Adds one response's usage to a running total, starting the total when there is none. */
+export function addTokenUsage(total, usage) {
+    return {
+        input: (total?.input ?? 0) + usage.input,
+        output: (total?.output ?? 0) + usage.output,
+        cacheRead: (total?.cacheRead ?? 0) + usage.cacheRead,
+        cacheWrite: (total?.cacheWrite ?? 0) + usage.cacheWrite,
+        totalTokens: (total?.totalTokens ?? 0) + usage.totalTokens,
+    };
+}
+/** Adds a question to the transcript and returns the recording of its reply. */
+export function startTurnRecording(session, question) {
+    return new TurnRecording(session, question);
+}
+/** Gathers the model responses, tools, and documents of one question under a single reply. */
+export class TurnRecording {
+    #session;
+    #reply;
+    /** Text of the responses that have ended. */
+    #completedText = "";
+    /** Text of the response still arriving. */
+    #currentText = "";
+    #hasProviderOutcome = false;
+    /** Responses that reported usage, and those that did not. */
+    #measured = 0;
+    #missing = 0;
+    #estimatedCostUsd = null;
+    #unpricedMessages = 0;
+    #ended = false;
+    #timer;
+    constructor(session, question) {
+        this.#session = session;
+        session.add({ role: "user", at: new Date().toISOString(), text: question });
+        this.#reply = {
+            role: "assistant",
+            at: new Date().toISOString(),
+            text: "",
+            status: "generating",
+            userFoundHelpful: null,
+            tokens: null,
+            usageComplete: false,
+            contextPercent: null,
+            tools: [],
+            documents: [],
+            skills: [],
+        };
+        session.add(this.#reply);
+        // A partial answer reaches the disk while the model is still writing.
+        this.#timer = setInterval(() => session.save(), 2000);
+        this.#timer.unref();
+    }
+    /** Records feedback on the reply. False while the reply is still being written. */
+    setFeedback(value) {
+        if (!this.#ended)
+            return false;
+        this.#reply.userFoundHelpful = value;
+        this.#session.save();
+        return true;
+    }
+    event(event) {
+        if (this.#ended)
+            return;
+        const reply = this.#reply;
+        switch (event.type) {
+            case "assistant_delta":
+                this.#currentText += event.data.text;
+                reply.text = this.#completedText + this.#currentText;
+                return;
+            case "assistant_message":
+                this.#responseEnded(event.data);
+                return;
+            case "tool_used":
+                addOnce(reply.tools, event.data.name);
+                return;
+            case "document_read":
+                addOnce(reply.documents, event.data.path);
+                return;
+            case "skill_loaded":
+                addOnce(reply.skills, event.data.skill);
+                return;
+            case "context_usage":
+                reply.contextPercent = event.data.percent;
+                return;
+            case "provider_outcome":
+                this.#hasProviderOutcome = true;
+                reply.status = event.data.outcome;
+                if (typeof event.data.error === "string")
+                    reply.error = event.data.error;
+                return;
+        }
+    }
+    /** One model response ended: keep its text, and count its usage and cost. */
+    #responseEnded({ text, usage, estimatedCostUsd: cost, }) {
+        const reply = this.#reply;
+        // Text that arrived in pieces is kept as it arrived; otherwise the response's own text is used.
+        this.#completedText += this.#currentText || text;
+        this.#currentText = "";
+        reply.text = this.#completedText;
+        if (usage) {
+            reply.tokens = addTokenUsage(reply.tokens, usage);
+            this.#measured++;
+        }
+        else
+            this.#missing++;
+        if (usage && typeof cost === "number" && Number.isFinite(cost) && cost >= 0)
+            this.#estimatedCostUsd = (this.#estimatedCostUsd ?? 0) + cost;
+        else
+            this.#unpricedMessages++;
+        reply.usageComplete = this.#measured > 0 && this.#missing === 0;
+        this.#session.save();
+    }
+    /**
+     * Closes the reply and returns what the turn measured. The caller's outcome is
+     * written, except that "failed" does not replace an outcome the provider gave:
+     * that one says more. A second call does nothing.
+     */
+    finish(override) {
+        if (this.#ended)
+            return;
+        clearInterval(this.#timer);
+        this.#ended = true;
+        const reply = this.#reply;
+        if (override &&
+            !(override.outcome === "failed" && this.#hasProviderOutcome))
+            reply.status = override.outcome;
+        if (override?.error)
+            reply.error = override.error;
+        if (reply.status === "generating")
+            reply.status = "incomplete";
+        // A response cut off while arriving never reported its usage.
+        if (this.#currentText)
+            reply.usageComplete = false;
+        this.#session.save();
+        return {
+            outcome: reply.status,
+            error: reply.error,
+            tokens: reply.tokens,
+            estimatedCostUsd: this.#estimatedCostUsd,
+            costComplete: this.#estimatedCostUsd !== null &&
+                this.#unpricedMessages === 0 &&
+                reply.usageComplete &&
+                reply.status === "completed",
+            usageComplete: reply.usageComplete,
+            contextPercent: reply.contextPercent,
+        };
+    }
+}
+function addOnce(list, value) {
+    if (!list.includes(value))
+        list.push(value);
+}

package/build/server/stone/file-boundary.js

@@ -0,0 +1,57 @@
+import { lstat, readdir, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
+/** The one containment rule for stone files; callers pass paths with symbolic links resolved. */
+export function contains(root, path) {
+    const rel = relative(root, path);
+    return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/** Application boundary for a trusted stone that is not modified while serving. */
+export async function stoneToolPath(root, requested = ".", scan = "none", signal) {
+    signal?.throwIfAborted();
+    const candidate = resolve(root, requested);
+    const path = await realpath(candidate);
+    if (!contains(root, path))
+        throw new Error("Access denied: tools can only access the active stone.");
+    const info = await stat(path);
+    if (!info.isFile() && !info.isDirectory())
+        throw new Error("Access denied: only regular files and directories are supported.");
+    if (info.isDirectory() && scan !== "none") {
+        // Check before invoking SDK tools, including ignored/hidden entries. Refusing
+        // links avoids relying on subprocess defaults or host search configuration.
+        const pending = [path];
+        while (pending.length) {
+            signal?.throwIfAborted();
+            const dir = pending.pop();
+            for (const entry of await readdir(dir, { withFileTypes: true })) {
+                if (!entry.isFile() && !entry.isDirectory()) {
+                    throw new Error("Access denied: directory scans cannot include symbolic links or special files. Choose a directory containing only stone resources.");
+                }
+                if (entry.isDirectory() && scan === "recursive")
+                    pending.push(join(dir, entry.name));
+            }
+        }
+    }
+    return path;
+}
+/** Resolve missing destination suffixes too, without creating/pruning anything. */
+async function canonicalDestination(path) {
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        return join(await canonicalDestination(dirname(path)), basename(path));
+    }
+    // A dangling symlink is an error, not a missing directory we can safely accept.
+    return realpath(path);
+}
+export async function assertRecordingsOutsideStone(stonePath, directory) {
+    if (directory === false)
+        return;
+    const root = await realpath(stonePath);
+    const destination = await canonicalDestination(resolve(directory));
+    if (contains(root, destination)) {
+        throw new Error("ROSETTA_RECORDINGS must be outside the active stone so agent tools cannot read saved conversations.");
+    }
+}

package/build/server/stone/prompt.js

@@ -0,0 +1,83 @@
+/**
+ * What the agent is told before it sees a question.
+ *
+ * Kept apart from stone loading: one file reads a directory, this one decides
+ * the posture the assistant takes.
+ */
+/**
+ * Replaces pi's coding-assistant system prompt outright, rather than appending
+ * to it: the stock prompt describes an agent that edits files and runs
+ * commands, which is the opposite of the posture wanted here.
+ *
+ * A stone may ship SYSTEM.md to replace this entirely. `{{agentName}}`,
+ * `{{languageName}}` and `{{answersAbout}}` are substituted from rosetta.json in
+ * either case.
+ *
+ * The assistant *is* {{agentName}} rather than an assistant working for it: "You
+ * are the assistant for X" makes X a separate entity, and the model then
+ * introduces itself as "X's assistant".
+ *
+ * Deliberately says nothing about the domain: what the scripts control, and
+ * what a wrong one costs, belongs in the stone. Presenting output as a draft is
+ * kept because it is right for any assistant whose users may not be able to
+ * judge the code themselves.
+ */
+const DEFAULT_SYSTEM_PROMPT = `You are {{agentName}}.
+
+You help people write scripts in {{languageName}}. Your users are not all programmers.
+
+# Scope
+
+You answer questions about {{answersAbout}}, and nothing else.
+
+If asked anything outside that scope — general programming unrelated to this language,
+questions about this computer, its files, its environment or its configuration, or any
+other subject — decline in one sentence and say what you do cover. Do not comply, and do
+not explain how the request could be accomplished elsewhere.
+
+# Grounding
+
+Everything you state about the language must come from the reference material you have been
+given. You have tools to read further documentation and examples; use them rather than
+guessing.
+
+If the material does not answer a question, say that you do not know and suggest who might.
+An admission of ignorance is a correct answer. An invented function name is not.
+
+# Producing scripts
+
+Present every script as a draft for a person to review rather than as ready to run.
+
+Before offering a script, check it against every constraint in your reference material. If a
+request cannot be satisfied without breaking one, say which rule applies and offer the
+nearest version that respects it.
+
+Never use a function that is not documented in your reference material.`;
+/**
+ * Appended after the stone's prompt, whether that is SYSTEM.md or the default.
+ *
+ * It goes here rather than in the template because it is a Rosetta-level
+ * contract about a tool Rosetta registers — a stone author overriding the
+ * prompt must not be able to silently switch the safety gate off.
+ */
+const VERIFICATION_CONTRACT = `
+
+# Checking your work
+
+A check_script tool is available and you must use it.
+
+Draft the script, call check_script, and only then write it into your reply. Never show a
+script you have not checked: the person reading may not be able to tell a working script from
+a broken one.
+
+If a check fails, read the diagnostics, fix the script and check again. If it still fails
+after that second attempt, do not show the script at all. Say plainly what the checker
+rejected and what you would need in order to get it right.`;
+/** `template` is a stone's SYSTEM.md, or undefined to use the built-in prompt. */
+export function buildSystemPrompt(template, fields, options = { verified: false }) {
+    const base = (template ?? DEFAULT_SYSTEM_PROMPT)
+        .replaceAll("{{agentName}}", fields.agentName)
+        .replaceAll("{{languageName}}", fields.languageName)
+        .replaceAll("{{answersAbout}}", fields.answersAbout);
+    return options.verified ? base + VERIFICATION_CONTRACT : base;
+}

package/build/server/stone/stone.js

@@ -0,0 +1,245 @@
+import { existsSync } from "node:fs";
+import { glob, readFile, realpath, stat } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+import { closest, distance } from "fastest-levenshtein";
+import { z } from "zod";
+import { BUNDLED_LANGUAGES } from "../../src/shared/protocol.js";
+import { contains } from "./file-boundary.js";
+import { buildSystemPrompt } from "./prompt.js";
+import { resolveCommand } from "./verify.js";
+/**
+ * What is always in context when the manifest does not say.
+ *
+ * AGENTS.md carries the cheatsheet and hard constraints; constraints/ carries
+ * the rules the language cannot express; examples/ carries the counter-examples,
+ * which teach a rule better than stating it does.
+ *
+ * Reference material under docs/ is left to the read/grep tools: it is the part
+ * of a stone most likely to grow, and the part the model can most safely be
+ * trusted to look up when a question actually calls for it. A stone can add it
+ * with `context` in rosetta.json.
+ */
+const DEFAULT_CONTEXT = ["AGENTS.md", "constraints/**/*.md", "examples/**/*"];
+/** Past this, a stone should move its bulkiest material out of `context`. */
+const CONTEXT_WARN_CHARS = 200_000;
+const MAX_FILE_BYTES = 512 * 1024;
+/**
+ * A stone that cannot be loaded. Carries every problem found, not just the
+ * first, so an author fixing a manifest sees the whole list in one run.
+ */
+export class StoneError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems.join("; "));
+        this.name = "StoneError";
+        this.problems = problems;
+    }
+}
+/**
+ * The manifest schema.
+ *
+ * Strict, so an unrecognised key is an error rather than a silent no-op — a
+ * misspelled "suggestions" that quietly does nothing is the failure this
+ * milestone exists to catch, and JSON has no comments, so a stray key is
+ * almost always a typo.
+ *
+ * Everything is optional: a stone with an empty manifest still runs, and the
+ * gaps that matter come back as warnings from loadStone rather than errors.
+ */
+const ManifestSchema = z.strictObject({
+    agentName: z.string().min(1).optional(),
+    languageName: z.string().min(1).optional(),
+    welcomeMessage: z.string().min(1).optional(),
+    answersAbout: z.string().min(1).optional(),
+    syntaxHighlighting: z.string().min(1).optional(),
+    suggestedQuestions: z.array(z.string()).optional(),
+    alwaysInContext: z
+        .array(z.string())
+        .min(1, "must list at least one glob, or the assistant has no reference material")
+        .optional(),
+    checks: z
+        .array(z.strictObject({
+        name: z.string().min(1),
+        // An argv array, never a shell string: the script being checked is
+        // model-generated and must never reach a shell.
+        command: z.array(z.string().min(1)).min(1),
+        input: z.enum(["stdin", "file"]).optional(),
+        timeoutMs: z.number().int().positive().max(120_000).optional(),
+        successExitCodes: z.array(z.number().int()).optional(),
+    }))
+        .optional(),
+});
+const FIELD_NAMES = Object.keys(ManifestSchema.shape);
+/** Operator details that moved from the manifest to .env, so an older stone is told where they went. */
+const MOVED_TO_ENV = new Map([
+    ["contact", "ROSETTA_PRIVACY_CONTACT"],
+    ["controller", "ROSETTA_PRIVACY_CONTROLLER"],
+    ["lawfulBasis", "ROSETTA_PRIVACY_LAWFUL_BASIS"],
+    ["providerProcessing", "ROSETTA_PRIVACY_PROVIDER_PROCESSING"],
+    ["additionalInformation", "ROSETTA_PRIVACY_ADDITIONAL_INFORMATION"],
+    ["privacyUpdated", "ROSETTA_PRIVACY_UPDATED"],
+]);
+/** zod issues, rendered for someone editing a JSON file rather than reading a stack trace. */
+function formatIssue(issue, file) {
+    if (issue.code === "unrecognized_keys") {
+        return issue.keys.map((key) => {
+            const variable = MOVED_TO_ENV.get(key);
+            if (variable)
+                return `${file}: "${key}" moved to .env — set ${variable} instead`;
+            const near = closest(key.toLowerCase(), FIELD_NAMES);
+            return distance(key.toLowerCase(), near) <= 3
+                ? `${file}: unknown field "${key}" — did you mean "${near}"?`
+                : `${file}: unknown field "${key}"`;
+        });
+    }
+    // zod prefixes type errors with "Invalid input: "; the file and field already
+    // say that much, so drop it.
+    const message = issue.message.replace(/^Invalid input:\s*/, "");
+    const field = issue.path.join(".");
+    return [field ? `${file}: "${field}" ${message}` : `${file}: ${message}`];
+}
+export async function loadStone(path) {
+    const dir = resolve(path);
+    const manifest = await readManifest(dir);
+    const warnings = [];
+    if (manifest.languageName === undefined) {
+        warnings.push('rosetta.json has no "languageName"; the prompt will call it "the language"');
+    }
+    if (manifest.answersAbout === undefined) {
+        warnings.push('rosetta.json has no "answersAbout"; the assistant will not know what to decline');
+    }
+    const syntaxHighlighting = manifest.syntaxHighlighting ?? "text";
+    if (syntaxHighlighting !== "text" &&
+        !BUNDLED_LANGUAGES.includes(syntaxHighlighting)) {
+        warnings.push(`"syntaxHighlighting": "${syntaxHighlighting}" is not a bundled grammar (${BUNDLED_LANGUAGES.join(", ")}); code will render as plain text`);
+    }
+    // A stone that names its context explicitly should hear about a glob that
+    // matches nothing; the defaults are a convention, and an absent optional
+    // directory is not worth a warning.
+    const explicit = manifest.alwaysInContext !== undefined;
+    const context = await collectContext(dir, manifest.alwaysInContext ?? DEFAULT_CONTEXT, explicit, warnings);
+    if (!context.some((file) => file.path === "AGENTS.md")) {
+        warnings.push("No AGENTS.md in context — the assistant starts with no always-on reference");
+    }
+    const checks = resolveChecks(manifest.checks, dir, warnings);
+    const stone = {
+        path: dir,
+        agentName: manifest.agentName ?? "Rosetta",
+        languageName: manifest.languageName ?? "the language",
+        welcomeMessage: manifest.welcomeMessage ?? "Ask a question about the scripting language.",
+        suggestedQuestions: manifest.suggestedQuestions ?? [],
+        answersAbout: manifest.answersAbout ??
+            "the scripting language documented in this stone",
+        syntaxHighlighting,
+        context,
+        checks,
+        warnings,
+    };
+    return {
+        ...stone,
+        systemPrompt: buildSystemPrompt(await readPromptTemplate(dir), stone, {
+            verified: checks.length > 0,
+        }),
+    };
+}
+/** Reads and validates rosetta.json. Every problem in it is reported in one StoneError. */
+async function readManifest(dir) {
+    const manifestPath = resolve(dir, "rosetta.json");
+    let raw;
+    try {
+        raw = await readFile(manifestPath, "utf8");
+    }
+    catch {
+        throw new StoneError([
+            `${manifestPath} not found — a stone needs a rosetta.json`,
+        ]);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new StoneError([
+            `${manifestPath} is not valid JSON: ${error.message}`,
+        ]);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new StoneError([`${manifestPath} must contain a JSON object`]);
+    }
+    const result = ManifestSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new StoneError(result.error.issues.flatMap((issue) => formatIssue(issue, "rosetta.json")));
+    }
+    return result.data;
+}
+/** The manifest's checks with their defaults filled in and stone-relative commands resolved. */
+function resolveChecks(declared, dir, warnings) {
+    const checks = (declared ?? []).map((check) => ({
+        name: check.name,
+        command: resolveCommand(check.command, dir),
+        input: check.input ?? "stdin",
+        timeoutMs: check.timeoutMs ?? 10_000,
+        successExitCodes: check.successExitCodes ?? [0],
+    }));
+    for (const check of checks) {
+        const binary = check.command[0];
+        // Only a path can be checked here; a bare name is resolved from PATH at
+        // run time, and the tool reports "command not found" clearly if it is not.
+        if (binary.includes("/") && !existsSync(binary)) {
+            warnings.push(`checks "${check.name}": ${binary} does not exist`);
+        }
+    }
+    return checks;
+}
+/** The stone's SYSTEM.md, or undefined when it has none and the built-in prompt applies. */
+async function readPromptTemplate(dir) {
+    const templatePath = await realpath(resolve(dir, "SYSTEM.md")).catch(() => undefined);
+    if (!templatePath)
+        return undefined;
+    // An override that resolves outside the stone is refused.
+    if (!contains(await realpath(dir), templatePath)) {
+        throw new StoneError(["SYSTEM.md resolves outside the stone"]);
+    }
+    return readFile(templatePath, "utf8");
+}
+async function collectContext(dir, patterns, explicit, warnings) {
+    const root = await realpath(dir);
+    const seen = new Set();
+    const files = [];
+    for (const pattern of patterns) {
+        const matches = [];
+        for await (const match of glob(pattern, { cwd: dir }))
+            matches.push(match);
+        matches.sort();
+        if (!matches.length && explicit)
+            warnings.push(`context pattern "${pattern}" matched nothing`);
+        for (const rel of matches) {
+            const abs = await realpath(resolve(dir, rel));
+            if (!contains(root, abs)) {
+                warnings.push(`skipped ${rel}: outside the stone`);
+                continue;
+            }
+            if (seen.has(abs))
+                continue;
+            const info = await stat(abs);
+            if (!info.isFile())
+                continue;
+            if (info.size > MAX_FILE_BYTES) {
+                warnings.push(`skipped ${rel}: larger than ${MAX_FILE_BYTES / 1024} KB`);
+                continue;
+            }
+            const content = await readFile(abs, "utf8");
+            if (content.includes("\0")) {
+                warnings.push(`skipped ${rel}: not a text file`);
+                continue;
+            }
+            seen.add(abs);
+            files.push({ path: relative(dir, resolve(dir, rel)), content });
+        }
+    }
+    const total = files.reduce((sum, file) => sum + file.content.length, 0);
+    if (total > CONTEXT_WARN_CHARS) {
+        warnings.push(`always-on context is ${Math.round(total / 1000)}k characters; consider moving reference material out of "context" so the tools fetch it instead`);
+    }
+    return files;
+}

package/build/server/stone/verify.js

@@ -0,0 +1,141 @@
+/**
+ * Runs a stone's checkers against a draft script.
+ *
+ * Deliberately knows nothing about pi: it spawns processes and reports what
+ * they said. The harness wraps this in a tool.
+ */
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+/** Beyond this the model is reading noise, not diagnostics. */
+const MAX_OUTPUT_CHARS = 4_000;
+/** Placeholder in argv that receives the temp file path when input is "file". */
+const FILE_PLACEHOLDER = "{}";
+/**
+ * Runs a stone's checks on a draft script, in the directory `cwd`.
+ *
+ * Ordered, and stopped at the first failure: a domain check run against
+ * syntactically invalid input produces noise, not information.
+ */
+export async function runChecks(checks, script, cwd, signal) {
+    const results = [];
+    for (const check of checks) {
+        const result = await runCheck(check, script, cwd, signal);
+        results.push(result);
+        if (!result.ok)
+            return { ok: false, checks: results };
+    }
+    return { ok: true, checks: results };
+}
+/** Runs one check, giving it the script on stdin or in a temporary file that is removed afterwards. */
+async function runCheck(check, script, cwd, signal) {
+    const cancelled = {
+        name: check.name,
+        ok: false,
+        output: `${check.name} was cancelled`,
+    };
+    if (signal?.aborted)
+        return cancelled;
+    let scratch;
+    let argv = check.command;
+    try {
+        if (check.input === "file") {
+            scratch = await mkdtemp(join(tmpdir(), "rosetta-check-"));
+            if (signal?.aborted)
+                return cancelled;
+            const file = join(scratch, "script");
+            await writeFile(file, script, "utf8");
+            argv = argv.includes(FILE_PLACEHOLDER)
+                ? argv.map((part) => (part === FILE_PLACEHOLDER ? file : part))
+                : [...argv, file];
+        }
+        // Cancellation can arrive while file input is being prepared.
+        if (signal?.aborted)
+            return cancelled;
+        return await runChecker(check, argv, script, cwd, signal);
+    }
+    finally {
+        if (scratch)
+            await rm(scratch, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/** Starts the checker and resolves with how it ended: its exit, a timeout, a cancel, or a failure to start. */
+function runChecker(check, argv, script, cwd, signal) {
+    return new Promise((settle) => {
+        const [command, ...args] = argv;
+        // shell: false is the point. The script is model-generated, so it must
+        // never reach a shell where backticks or $(...) would be interpreted.
+        // The model chooses the script; the stone author chose the command.
+        const child = spawn(command, args, {
+            cwd,
+            shell: false,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let output = "";
+        let settled = false;
+        const collect = (chunk) => {
+            if (output.length < MAX_OUTPUT_CHARS)
+                output += chunk.toString("utf8");
+        };
+        child.stdout.on("data", collect);
+        child.stderr.on("data", collect);
+        // An 'error' event with no listener is fatal in Node, and every session shares this
+        // one process, so one misbehaving checker would take the server down with every
+        // other session on it.
+        //
+        // The reachable case is EPIPE on stdin: a checker that reads a prefix and
+        // exits, or one this function SIGKILLs on timeout or abort, closes the read
+        // end while a script larger than the pipe buffer is still being written.
+        // Ignoring is right rather than merely quiet — what decides the result is the
+        // exit code delivered to 'close' below, not whether the write landed.
+        const ignoreStreamError = () => { };
+        child.stdin.on("error", ignoreStreamError);
+        child.stdout.on("error", ignoreStreamError);
+        child.stderr.on("error", ignoreStreamError);
+        const finish = (ok, text) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            settle({
+                name: check.name,
+                ok,
+                output: text.trim().slice(0, MAX_OUTPUT_CHARS),
+            });
+        };
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            finish(false, `${check.name} timed out after ${check.timeoutMs}ms`);
+        }, check.timeoutMs);
+        const onAbort = () => {
+            child.kill("SIGKILL");
+            finish(false, `${check.name} was cancelled`);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        child.once("error", (error) => {
+            const hint = error.code === "ENOENT"
+                ? `command not found: ${command}. Check "checks" in rosetta.json.`
+                : error.message;
+            finish(false, hint);
+        });
+        child.once("close", (code) => {
+            finish(check.successExitCodes.includes(code ?? -1), output);
+        });
+        if (check.input === "stdin") {
+            child.stdin.end(script, "utf8");
+        }
+        else {
+            child.stdin.end();
+        }
+    });
+}
+/** Resolves a stone-relative command so a checker can ship inside the stone. */
+export function resolveCommand(command, stonePath) {
+    const [head, ...rest] = command;
+    if (head?.startsWith("./") || head?.startsWith("../")) {
+        return [resolve(stonePath, head), ...rest];
+    }
+    return command;
+}