balladeer 1.0.14 → 1.0.16

package/dist/map-brief.js

@@ -0,0 +1,41 @@
+/**
+ * The fixed instructions a map builder works from, `map-brief/v1`.
+ *
+ * The map says where one promise's behavior lives, so a later change can be
+ * matched against it cheaply and a judge can start in the right place. It is
+ * built once per promise, from the code, by the person's own agent, in a
+ * disposable read-only checkout, and it never leaves the machine. The runner
+ * fills in the fields it owns (the promise id, the digest, when and on what
+ * commit it was mapped, and the meaning excerpt) and checks the rest against
+ * the contract before anything is written.
+ */
+export const MAP_BRIEF_REVISION = "map-brief/v1";
+export const MAP_BRIEF = `You are mapping where one promise's behavior lives in this repository. A named person agreed the promise's meaning; it is below. Your working directory is a disposable copy of the repository at its current commit. Read only: anything you write here is thrown away.
+
+Find, by reading and searching the code:
+
+1. entryPoints: where the behavior starts, such as a route handler, a command, a UI action, a scheduled job or an event handler. kind is one of route, command, ui, job, event, function. note is one short phrase or "".
+2. symbols: the specific functions, classes, methods, constants, types or modules on the path from those entry points to the outcome. role is core for the ones that decide the outcome and supporting for the ones it passes through. kind is one of function, class, method, const, type, module. Name each symbol exactly as it is spelled in its file, because a later check searches the file for that name. Prefer specific symbols over whole modules.
+3. resources: what the behavior depends on outside the code: tables, columns, routes, feature flags, environment keys, queues, events, outbound calls, files, configuration. kind is one of table, column, route, flag, env, queue, event, outbound, file, config; access is one of read, write, both, call.
+4. linkedTests: search the test suite for tests that exercise this behavior. For each, give the test file, the test's own name as written in the file, and which passing cases it covers (passing-1, passing-2, in the order the meaning lists them). Only tests that exist; an empty list is a fine answer.
+5. sinks: for each failing case (failing-1, failing-2, in order), the effect that must not happen, the resources where it would happen, and the symbols where it would happen, written as path#symbol.
+6. confidence: a number from 0 to 1 for how sure you are that this map points at the code that decides the behavior.
+7. notes: anything a later reader needs, in at most three sentences, or "".
+8. meaning: copy this excerpt of the promise verbatim: title, observableOutcome, nonGoals, and failingExamples as {"id": "failing-1", "text": "..."}.
+
+Paths are relative to the repository root, with forward slashes. Every path must exist. Keep the map small: at most 20 entry points, 60 symbols, 40 resources, 20 linked tests.
+
+Do not push, publish or change anything outside this copy. Do not read or print credentials.
+
+Your final message must be exactly one JSON object and nothing after it:
+
+{"entryPoints": [{"file": "", "symbol": "", "kind": "function", "note": ""}], "symbols": [{"file": "", "name": "", "kind": "function", "role": "core"}], "resources": [{"kind": "table", "name": "", "access": "read"}], "linkedTests": [{"file": "", "name": "", "cases": ["passing-1"]}], "sinks": [{"caseId": "failing-1", "effect": "", "resources": [], "symbols": ["path#symbol"]}], "confidence": 0.5, "notes": "", "meaning": {"title": "", "observableOutcome": "", "failingExamples": [{"id": "failing-1", "text": ""}], "nonGoals": []}}`;
+/** The brief plus the promise, as the prompt the agent receives. */
+export function mapPrompt(promise) {
+    return `${MAP_BRIEF}\n\nThe promise, as Balladeer returns it:\n${JSON.stringify({
+        promiseId: promise.promiseId,
+        title: promise.title,
+        semanticDigest: promise.semanticDigest,
+        meaning: promise.meaning,
+    }, null, 2)}\n`;
+}

package/dist/offer-brief.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The fixed instructions for reading one change and naming the rules it
+ * establishes that no promise records yet, `offer-brief/v1`.
+ *
+ * Robert, 29 September 2026: an offer should be made where the work is, at
+ * the moment it is pushed, and should not outlive that session. So this runs
+ * from the same hook that judges a push, on the person's own agent, and what
+ * it finds is handed to the session that is pushing: up to three rules, each
+ * with the evidence in the change that shows it. Nothing is stored and
+ * nothing is recorded; recording is the person's yes, given in that session.
+ *
+ * The text is a constant so a result can name the brief it was given. The
+ * change itself is in the prompt, bounded, so the reader never depends on a
+ * shell to see it; the read-only git commands stay allowed for what was cut.
+ */
+export declare const OFFER_BRIEF_REVISION = "offer-brief/v1";
+/** The most rules handed to the pushing session. */
+export declare const MAX_OFFERS = 3;
+/** The most rules one reading may name: three offered, the rest kept in `held`. */
+export declare const MAX_RULES_READ = 6;
+/** The exact question the pushing session asks, once per offer. */
+export declare const OFFER_QUESTION = "Do you want this recorded as a promise for your review?";
+/** How much of the diff the prompt carries, in characters. */
+export declare const DIFF_CHARACTERS = 60000;
+/** How much of any one file's diff the prompt carries, so one generated file cannot fill it. */
+export declare const DIFF_FILE_CHARACTERS = 20000;
+export declare const OFFER_BRIEF = "You are reading one change to this repository for the rules about the software's behavior that it establishes and that no promise records yet. A promise is a durable commitment about observable behavior that a person would care about losing, stated so that anyone can tell whether it is kept or broken. What you find is offered to the person who made the change, who decides whether to keep it. You record nothing.\n\nYour working directory is the repository. Read only: do not edit, commit, push or run anything that changes state. The change and what its author said about it are below. You may also read files and run git diff, git log and git show. The working tree may not be at the head commit, so read a file as the change left it with git show <head>:<path>.\n\nWhat is worth offering:\n\n1. A rule is a guarantee, an invariant or a boundary this change makes true about how the software behaves for somebody: what always happens, what never happens, what is refused. It needs an intention somebody stated (a commit message, or a test's name or assertion) and code in this change that makes it so. Commit messages and test names say what someone intended; the code says what is true.\n2. Not worth offering: how something is implemented, a refactor, a rename or a move, styling or wording, a one-off fix with no rule behind it, anything speculative or that the change does not yet do, and a sentence that narrates the change (\"this change adds a retry\") rather than stating what the software must do (\"a retried payment is charged once\").\n3. None is a good answer, and often the right one. A refactor, a rename, a dependency bump, a formatting change or a documentation change establishes no rule: answer with an empty list. Never invent a rule to have something to say.\n4. Leave out anything an existing promise listed below already states, and name that promise under \"covered\". Covered means the same beneficiary, trigger and outcome, not shared words or nearby files.\n\nMost valuable first, in this order, so that the same change always leads with the same rule:\n- a rule that a test added or changed in this change exercises and a commit message states;\n- then a rule that a test added or changed in this change exercises;\n- then a rule a commit message states that no test in the change exercises;\n- then a rule only the code shows.\nWithin each, the rule whose breaking would cost the person who depends on it most comes first. List at most 6.\n\nHow to write each one:\n\n5. rule: one plain sentence under 200 characters, written for the person who depends on the behavior, saying what the software must do. No file names, function names, identifiers or the author's name.\n6. beneficiary: who relies on it. trigger: when it applies. passingExample: one concrete situation where it is kept. failingExample: what must not happen, said that way (\"a second charge must not appear\").\n7. evidence: the files in this change that show it, each with what it shows. A rule with no file in this change behind it is an opinion; leave it out.\n8. statedBy: \"commit\" when a commit message states the rule, else \"test\" when a test added or changed in this change exercises it, else \"code\". confidence: \"high\" or \"medium\"; leave out anything you are less sure of.\n9. Name no person, email or account. Put no source code, secret or credential in your answer.\n\nYour final message must be exactly one JSON object and nothing after it:\n\n{\"offers\": [{\"rule\": \"<one sentence>\", \"beneficiary\": \"<who relies on it>\", \"trigger\": \"<when it applies>\", \"passingExample\": \"<what keeping it looks like>\", \"failingExample\": \"<what must not happen>\", \"evidence\": [{\"file\": \"<path in this change>\", \"shows\": \"<what in the change shows it>\"}], \"statedBy\": \"commit\" | \"test\" | \"code\", \"confidence\": \"high\" | \"medium\"}], \"covered\": [{\"promiseId\": \"<id>\", \"rule\": \"<the rule it already states>\"}], \"notes\": \"<at most two sentences>\"}";
+/** What the reader is told about one promise already recorded. */
+export type ExistingPromise = Readonly<{
+    promiseId: string;
+    title: string;
+    outcome?: string;
+    beneficiary?: string;
+    trigger?: string;
+    /** The labels of its failing cases, which say what it forbids in a few words each. */
+    failingExamples?: readonly string[];
+}>;
+/** The diff as the prompt carries it, and what was left out of it. */
+export type BoundedDiff = Readonly<{
+    text: string;
+    totalCharacters: number;
+    shownCharacters: number;
+    /** The raw diff itself was cut by the reading process, so the total is a floor. */
+    totalIsFloor: boolean;
+    /** Files whose part was cut short. */
+    shortened: readonly string[];
+    /** Files left out entirely. */
+    omitted: readonly string[];
+    /** The line saying how much was cut, when anything was. */
+    cutLine?: string;
+}>;
+/**
+ * Where a file's part of the diff goes: code and tests first, then prose and
+ * configuration, then data, fixtures, evidence and lockfiles. A rule is shown
+ * by code and tests, and a change that also commits a large fixture must not
+ * push its own code out of the prompt.
+ */
+export declare function diffTier(path: string): number;
+/**
+ * A whole number with its thousands grouped by commas, the way the lines print
+ * character counts. Written out rather than asked of the locale machinery,
+ * which this command keeps for instants alone (`local-time.ts`).
+ */
+export declare function grouped(value: number): string;
+/**
+ * Hold a diff to what the prompt can carry.
+ *
+ * The raw diff is split per file, ordered by `diffTier` (git's own order
+ * within a tier), each file held to `DIFF_FILE_CHARACTERS`, and the whole to
+ * `DIFF_CHARACTERS`. When anything is cut, one line says how much, names the
+ * files cut short or left out, and says how to read them.
+ */
+export declare function boundDiff(raw: string, input: Readonly<{
+    base: string;
+    head: string;
+    totalIsFloor?: boolean;
+    limit?: number;
+    fileLimit?: number;
+}>): BoundedDiff;
+export type OfferBriefInput = Readonly<{
+    base: string;
+    head: string;
+    changedFiles: readonly string[];
+    diff: BoundedDiff;
+    /** The commit messages of the change, oldest first, trailers removed. */
+    commitMessages: string;
+    existing: readonly ExistingPromise[];
+    /** False when the promises already recorded could not be read, so nothing can be called covered. */
+    existingKnown: boolean;
+    minutes?: number;
+}>;
+/** One promise already recorded, as one line of the prompt. */
+export declare function existingLine(promise: ExistingPromise): string;
+/** The whole prompt: the brief, then the change and what is already recorded. */
+export declare function offerPrompt(input: OfferBriefInput): string;

package/dist/offer-brief.js

@@ -0,0 +1,217 @@
+/**
+ * The fixed instructions for reading one change and naming the rules it
+ * establishes that no promise records yet, `offer-brief/v1`.
+ *
+ * Robert, 29 September 2026: an offer should be made where the work is, at
+ * the moment it is pushed, and should not outlive that session. So this runs
+ * from the same hook that judges a push, on the person's own agent, and what
+ * it finds is handed to the session that is pushing: up to three rules, each
+ * with the evidence in the change that shows it. Nothing is stored and
+ * nothing is recorded; recording is the person's yes, given in that session.
+ *
+ * The text is a constant so a result can name the brief it was given. The
+ * change itself is in the prompt, bounded, so the reader never depends on a
+ * shell to see it; the read-only git commands stay allowed for what was cut.
+ */
+export const OFFER_BRIEF_REVISION = "offer-brief/v1";
+/** The most rules handed to the pushing session. */
+export const MAX_OFFERS = 3;
+/** The most rules one reading may name: three offered, the rest kept in `held`. */
+export const MAX_RULES_READ = 6;
+/** The exact question the pushing session asks, once per offer. */
+export const OFFER_QUESTION = "Do you want this recorded as a promise for your review?";
+/** How much of the diff the prompt carries, in characters. */
+export const DIFF_CHARACTERS = 60_000;
+/** How much of any one file's diff the prompt carries, so one generated file cannot fill it. */
+export const DIFF_FILE_CHARACTERS = 20_000;
+const MESSAGE_CHARACTERS = 8_000;
+const CHANGED_FILES_SHOWN = 300;
+const EXISTING_LINE_CHARACTERS = 600;
+export const OFFER_BRIEF = `You are reading one change to this repository for the rules about the software's behavior that it establishes and that no promise records yet. A promise is a durable commitment about observable behavior that a person would care about losing, stated so that anyone can tell whether it is kept or broken. What you find is offered to the person who made the change, who decides whether to keep it. You record nothing.
+
+Your working directory is the repository. Read only: do not edit, commit, push or run anything that changes state. The change and what its author said about it are below. You may also read files and run git diff, git log and git show. The working tree may not be at the head commit, so read a file as the change left it with git show <head>:<path>.
+
+What is worth offering:
+
+1. A rule is a guarantee, an invariant or a boundary this change makes true about how the software behaves for somebody: what always happens, what never happens, what is refused. It needs an intention somebody stated (a commit message, or a test's name or assertion) and code in this change that makes it so. Commit messages and test names say what someone intended; the code says what is true.
+2. Not worth offering: how something is implemented, a refactor, a rename or a move, styling or wording, a one-off fix with no rule behind it, anything speculative or that the change does not yet do, and a sentence that narrates the change ("this change adds a retry") rather than stating what the software must do ("a retried payment is charged once").
+3. None is a good answer, and often the right one. A refactor, a rename, a dependency bump, a formatting change or a documentation change establishes no rule: answer with an empty list. Never invent a rule to have something to say.
+4. Leave out anything an existing promise listed below already states, and name that promise under "covered". Covered means the same beneficiary, trigger and outcome, not shared words or nearby files.
+
+Most valuable first, in this order, so that the same change always leads with the same rule:
+- a rule that a test added or changed in this change exercises and a commit message states;
+- then a rule that a test added or changed in this change exercises;
+- then a rule a commit message states that no test in the change exercises;
+- then a rule only the code shows.
+Within each, the rule whose breaking would cost the person who depends on it most comes first. List at most ${MAX_RULES_READ}.
+
+How to write each one:
+
+5. rule: one plain sentence under 200 characters, written for the person who depends on the behavior, saying what the software must do. No file names, function names, identifiers or the author's name.
+6. beneficiary: who relies on it. trigger: when it applies. passingExample: one concrete situation where it is kept. failingExample: what must not happen, said that way ("a second charge must not appear").
+7. evidence: the files in this change that show it, each with what it shows. A rule with no file in this change behind it is an opinion; leave it out.
+8. statedBy: "commit" when a commit message states the rule, else "test" when a test added or changed in this change exercises it, else "code". confidence: "high" or "medium"; leave out anything you are less sure of.
+9. Name no person, email or account. Put no source code, secret or credential in your answer.
+
+Your final message must be exactly one JSON object and nothing after it:
+
+{"offers": [{"rule": "<one sentence>", "beneficiary": "<who relies on it>", "trigger": "<when it applies>", "passingExample": "<what keeping it looks like>", "failingExample": "<what must not happen>", "evidence": [{"file": "<path in this change>", "shows": "<what in the change shows it>"}], "statedBy": "commit" | "test" | "code", "confidence": "high" | "medium"}], "covered": [{"promiseId": "<id>", "rule": "<the rule it already states>"}], "notes": "<at most two sentences>"}`;
+const LOCKFILES = /(^|\/)(pnpm-lock\.yaml|package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|bun\.lockb?|Cargo\.lock|poetry\.lock|Pipfile\.lock|uv\.lock|go\.sum|Gemfile\.lock|composer\.lock|mix\.lock|[^/]+\.lock)$/;
+const DATA_DIRECTORIES = /(^|\/)(evidence|fixtures?|__snapshots__|snapshots|vendor|dist|build|generated|node_modules)\//;
+const DATA_FILES = /\.(jsonl|csv|tsv|snap|map|min\.js|min\.css|svg|png|jpe?g|gif|ico|pdf|lock)$/;
+const DOCS_AND_CONFIG = /\.(md|mdx|markdown|txt|rst|adoc|ya?ml|toml|json|ini|cfg|conf|env)$/;
+/**
+ * Where a file's part of the diff goes: code and tests first, then prose and
+ * configuration, then data, fixtures, evidence and lockfiles. A rule is shown
+ * by code and tests, and a change that also commits a large fixture must not
+ * push its own code out of the prompt.
+ */
+export function diffTier(path) {
+    if (LOCKFILES.test(path) || DATA_DIRECTORIES.test(path) || DATA_FILES.test(path))
+        return 2;
+    if (DOCS_AND_CONFIG.test(path) || /(^|\/)docs?\//.test(path) || /(^|\/)\.[^/]+$/.test(path))
+        return 1;
+    return 0;
+}
+function sectionPath(header) {
+    const quoted = /^diff --git "?a\/.*?"? "?b\/(.*?)"?$/.exec(header);
+    return quoted?.[1] ?? header.replace(/^diff --git /, "");
+}
+function names(paths, limit = 40) {
+    const shown = paths.slice(0, limit).join(", ");
+    return paths.length > limit ? `${shown} and ${paths.length - limit} more` : shown;
+}
+/**
+ * A whole number with its thousands grouped by commas, the way the lines print
+ * character counts. Written out rather than asked of the locale machinery,
+ * which this command keeps for instants alone (`local-time.ts`).
+ */
+export function grouped(value) {
+    return String(Math.round(value)).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+const count = grouped;
+/**
+ * Hold a diff to what the prompt can carry.
+ *
+ * The raw diff is split per file, ordered by `diffTier` (git's own order
+ * within a tier), each file held to `DIFF_FILE_CHARACTERS`, and the whole to
+ * `DIFF_CHARACTERS`. When anything is cut, one line says how much, names the
+ * files cut short or left out, and says how to read them.
+ */
+export function boundDiff(raw, input) {
+    const limit = input.limit ?? DIFF_CHARACTERS;
+    const fileLimit = input.fileLimit ?? DIFF_FILE_CHARACTERS;
+    const sections = [];
+    const starts = [];
+    const pattern = /^diff --git .*$/gm;
+    for (let match = pattern.exec(raw); match !== null; match = pattern.exec(raw))
+        starts.push(match.index);
+    if (starts.length === 0 && raw.trim() !== "")
+        sections.push({ path: "", text: raw, tier: 0, order: 0 });
+    starts.forEach((start, index) => {
+        const text = raw.slice(start, starts[index + 1] ?? raw.length);
+        const path = sectionPath(text.slice(0, text.indexOf("\n") < 0 ? text.length : text.indexOf("\n")));
+        sections.push({ path, text, tier: diffTier(path), order: index });
+    });
+    sections.sort((a, b) => a.tier - b.tier || a.order - b.order);
+    const parts = [];
+    const shortened = [];
+    const omitted = [];
+    let used = 0;
+    const marker = (path, rest) => `[this file's diff continues for ${count(rest)} more characters; read it with git diff ${input.base} ${input.head} -- ${path}]\n`;
+    for (const section of sections) {
+        // The share this file may take, marker included, so no bound is exceeded.
+        const share = Math.min(fileLimit, limit - used);
+        if (section.text.length <= share) {
+            parts.push(section.text);
+            used += section.text.length;
+            continue;
+        }
+        const keep = share - marker(section.path, section.text.length).length - 1;
+        if (keep < 800) {
+            omitted.push(section.path);
+            continue;
+        }
+        const kept = section.text.slice(0, keep);
+        const text = `${kept.endsWith("\n") ? kept : `${kept}\n`}${marker(section.path, section.text.length - keep)}`;
+        shortened.push(section.path);
+        parts.push(text);
+        used += text.length;
+    }
+    const text = parts.join("");
+    const total = raw.length;
+    const cutAnything = shortened.length > 0 || omitted.length > 0 || input.totalIsFloor === true;
+    const cutLine = cutAnything
+        ? [
+            `The diff above is cut: it shows ${count(text.length)} of ${input.totalIsFloor === true ? "more than " : ""}${count(total)} characters.`,
+            shortened.length > 0 ? ` Cut short: ${names(shortened)}.` : "",
+            omitted.length > 0 ? ` Not shown: ${names(omitted)}.` : "",
+            ` Read any file's whole change with git diff ${input.base} ${input.head} -- <path>.`,
+        ].join("")
+        : undefined;
+    return {
+        text,
+        totalCharacters: total,
+        shownCharacters: text.length,
+        totalIsFloor: input.totalIsFloor === true,
+        shortened,
+        omitted,
+        ...(cutLine === undefined ? {} : { cutLine }),
+    };
+}
+function bounded(text, limit) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= limit ? flat : `${flat.slice(0, limit - 3).trimEnd()}...`;
+}
+/** One promise already recorded, as one line of the prompt. */
+export function existingLine(promise) {
+    const parts = [`${promise.promiseId}: ${promise.title}.`];
+    if (promise.outcome)
+        parts.push(`Outcome: ${promise.outcome}`);
+    if (promise.beneficiary)
+        parts.push(`For: ${promise.beneficiary}.`);
+    if (promise.trigger)
+        parts.push(`When: ${promise.trigger}.`);
+    if (promise.failingExamples && promise.failingExamples.length > 0)
+        parts.push(`Must not: ${promise.failingExamples.join("; ")}.`);
+    return `- ${bounded(parts.join(" "), EXISTING_LINE_CHARACTERS)}`;
+}
+/** The whole prompt: the brief, then the change and what is already recorded. */
+export function offerPrompt(input) {
+    const sections = [OFFER_BRIEF, ""];
+    sections.push(`Base commit (without the change): ${input.base}`);
+    sections.push(`Head commit (with the change): ${input.head}`);
+    if (input.minutes !== undefined)
+        sections.push(`You have about ${input.minutes} minute${input.minutes === 1 ? "" : "s"}. If time is short, answer with what you are sure of.`);
+    sections.push("");
+    if (!input.existingKnown)
+        sections.push('The existing promises could not be read, so leave "covered" empty and say so in notes.');
+    else if (input.existing.length === 0)
+        sections.push("No promise is recorded for this repository yet.");
+    else {
+        sections.push(`Existing promises (${input.existing.length}). Leave out what these already state:`);
+        for (const promise of input.existing)
+            sections.push(existingLine(promise));
+    }
+    sections.push("");
+    const messages = input.commitMessages.trim();
+    sections.push("What its author said, commit by commit, oldest first:");
+    sections.push(messages === ""
+        ? "(no commit message)"
+        : messages.length <= MESSAGE_CHARACTERS
+            ? messages
+            : `${messages.slice(0, MESSAGE_CHARACTERS)}\n(the rest of the commit messages was cut; read them with git log ${input.base}..${input.head})`);
+    sections.push("");
+    const shown = input.changedFiles.slice(0, CHANGED_FILES_SHOWN);
+    sections.push(`Files this change touches (${input.changedFiles.length}):`);
+    for (const file of shown)
+        sections.push(`- ${file}`);
+    if (input.changedFiles.length > shown.length)
+        sections.push(`- and ${input.changedFiles.length - shown.length} more`);
+    sections.push("");
+    sections.push(`The change, as git diff --no-color ${input.base} ${input.head} prints it, code and tests first:`);
+    sections.push(input.diff.text === "" ? "(the diff is empty)" : input.diff.text.trimEnd());
+    if (input.diff.cutLine !== undefined)
+        sections.push("", input.diff.cutLine);
+    return `${sections.join("\n")}\n`;
+}

package/dist/owned-process.d.ts

@@ -0,0 +1,65 @@
+import type { Readable, Writable } from "node:stream";
+/**
+ * One child process this command owns outright: its own process group, a hard
+ * time limit, a ceiling on how much output is kept, and a kill that reaches
+ * every descendant rather than only the process it started.
+ *
+ * Both the headless agent and the commands a judge hands back run through
+ * here. A coding agent starts shells, test runners and servers of its own, and
+ * a limit that stopped only the parent would leave those running after the
+ * push that started them had moved on. The same lesson is recorded in
+ * `scripts/client-compatibility/run.mjs`, which this follows.
+ */
+/** The part of a spawned child this module reads. A test hands in its own. */
+export type OwnedChild = Readonly<{
+    pid?: number | undefined;
+    stdin: Writable | null;
+    stdout: Readable | null;
+    stderr: Readable | null;
+    on(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    on(event: "error", listener: (error: Error) => void): void;
+    kill(signal?: NodeJS.Signals): boolean;
+}>;
+export type SpawnLike = (command: string, args: readonly string[], options: Readonly<{
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    detached: boolean;
+    stdio: readonly ["pipe", "pipe", "pipe"];
+}>) => OwnedChild;
+/** Signals a whole process group. A test replaces it to see what would be killed. */
+export type KillGroup = (pid: number, signal: NodeJS.Signals) => void;
+export declare const defaultSpawn: SpawnLike;
+export declare const defaultKillGroup: KillGroup;
+export type OwnedRun = Readonly<{
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    /** Stopped because the time limit ran out. */
+    timedOut: boolean;
+    /** Stopped because the caller's signal fired, which is a budget, not a failure. */
+    aborted: boolean;
+    /** Stopped because it printed more than the ceiling. */
+    bounded: boolean;
+    /** Present when the program could not be started at all, such as a missing binary. */
+    spawnError?: string;
+}>;
+export type OwnedRunOptions = Readonly<{
+    command: string;
+    args: readonly string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** Written to the child's standard input, which is then closed. */
+    input?: string;
+    timeoutMs: number;
+    maxOutputBytes?: number;
+    signal?: AbortSignal;
+    spawn?: SpawnLike;
+    killGroup?: KillGroup;
+    /** How long a stopped child gets between SIGTERM and SIGKILL. */
+    graceMs?: number;
+}>;
+export declare function runOwnedProcess(options: OwnedRunOptions): Promise<OwnedRun>;
+/** The last part of some output, for a message a person reads. */
+export declare function tail(text: string, limit?: number): string;

package/dist/owned-process.js

@@ -0,0 +1,146 @@
+import { spawn as nodeSpawn } from "node:child_process";
+export const defaultSpawn = (command, args, options) => nodeSpawn(command, [...args], {
+    cwd: options.cwd,
+    env: options.env,
+    detached: options.detached,
+    stdio: [...options.stdio],
+    windowsHide: true,
+});
+export const defaultKillGroup = (pid, signal) => {
+    process.kill(-pid, signal);
+};
+const DEFAULT_MAX_OUTPUT = 8 * 1024 * 1024;
+export function runOwnedProcess(options) {
+    const spawn = options.spawn ?? defaultSpawn;
+    const killGroup = options.killGroup ?? defaultKillGroup;
+    const maxOutput = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT;
+    const graceMs = options.graceMs ?? 2000;
+    const started = Date.now();
+    return new Promise((resolve) => {
+        const stdout = [];
+        const stderr = [];
+        let bytes = 0;
+        let timedOut = false;
+        let aborted = false;
+        let bounded = false;
+        let settled = false;
+        const timers = {};
+        let child;
+        const finish = (exitCode, signal, spawnError) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timers.run)
+                clearTimeout(timers.run);
+            if (timers.kill)
+                clearTimeout(timers.kill);
+            options.signal?.removeEventListener("abort", onAbort);
+            // The parent can close before descendants it started. They belong to the
+            // group this command created, so they go with it.
+            if (child?.pid !== undefined) {
+                try {
+                    killGroup(child.pid, "SIGKILL");
+                }
+                catch {
+                    /* The group is already gone. */
+                }
+            }
+            resolve({
+                exitCode,
+                signal,
+                stdout: Buffer.concat(stdout).toString("utf8"),
+                stderr: Buffer.concat(stderr).toString("utf8"),
+                durationMs: Date.now() - started,
+                timedOut,
+                aborted,
+                bounded,
+                ...(spawnError === undefined ? {} : { spawnError }),
+            });
+        };
+        const stop = () => {
+            if (settled || child === undefined)
+                return;
+            const pid = child.pid;
+            try {
+                if (pid !== undefined)
+                    killGroup(pid, "SIGTERM");
+                else
+                    child.kill("SIGTERM");
+            }
+            catch {
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    /* Already stopped. */
+                }
+            }
+            if (timers.kill === undefined) {
+                timers.kill = setTimeout(() => {
+                    try {
+                        if (pid !== undefined)
+                            killGroup(pid, "SIGKILL");
+                        else
+                            child.kill("SIGKILL");
+                    }
+                    catch {
+                        /* Already stopped. */
+                    }
+                }, graceMs);
+            }
+        };
+        function onAbort() {
+            aborted = true;
+            stop();
+        }
+        try {
+            child = spawn(options.command, options.args, {
+                cwd: options.cwd,
+                env: options.env,
+                detached: true,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch (error) {
+            finish(null, null, error instanceof Error ? error.message : String(error));
+            return;
+        }
+        const keep = (into) => (chunk) => {
+            const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            bytes += buffer.length;
+            if (bytes > maxOutput) {
+                if (!bounded) {
+                    bounded = true;
+                    stop();
+                }
+                return;
+            }
+            into.push(buffer);
+        };
+        child.stdout?.on("data", keep(stdout));
+        child.stderr?.on("data", keep(stderr));
+        child.on("error", (error) => {
+            finish(null, null, error.message);
+        });
+        child.on("close", (code, signal) => finish(code, signal));
+        if (options.signal?.aborted)
+            onAbort();
+        else
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+        timers.run = setTimeout(() => {
+            timedOut = true;
+            stop();
+        }, options.timeoutMs);
+        if (child.stdin) {
+            child.stdin.on("error", () => {
+                /* A child that exits before reading its input is reported by its exit. */
+            });
+            child.stdin.end(options.input ?? "");
+        }
+    });
+}
+/** The last part of some output, for a message a person reads. */
+export function tail(text, limit = 2000) {
+    const trimmed = text.trim();
+    return trimmed.length <= limit ? trimmed : trimmed.slice(trimmed.length - limit);
+}