@turri-dev/cli 0.0.0-stage → 0.1.2-next.48dacfc

package/dist/regenerate/requires.js

@@ -0,0 +1,241 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, withParseCache } from "../plain/parser.js";
+import { getFrids, getInheritedFunctionalSpecs } from "../plain/spec.js";
+import { buildDirUnder, modulesRoot, projectDirOf } from "./paths.js";
+import { notesPath } from "./notes.js";
+import { resolveTemplateDirs } from "./paths.js";
+import { inheritedRecord, readRecord, RECORD_FILE, writeCodeRecord } from "./records.js";
+import { head, historyLog, recordHistory } from "./lineage.js";
+import { listFiles } from "./testing.js";
+function locateModule(moduleName, templateDirs) {
+    for (const dir of templateDirs) {
+        const candidate = join(dir, moduleName + PLAIN_SOURCE_FILE_EXTENSION);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error(`Required module '${moduleName}' not found in: ${templateDirs.join(", ")}`);
+}
+/**
+ * The chain to build, bottom first.
+ *
+ * Depth-first, post-order: everything a module requires is listed before the module
+ * itself. The parser has already rejected circular requires, and a module reached twice is
+ * emitted once.
+ */
+export function resolveRequiresChain(plainFile, templateDirs = [], buildRoot, 
+/** Accept the named module without functional specs yet. Those it requires must have them. */
+options = {}) {
+    const dirs = resolveTemplateDirs(plainFile, templateDirs);
+    const root = resolve(buildRoot ?? modulesRoot(projectDirOf(plainFile)));
+    const chain = [];
+    const seen = new Set();
+    const visit = (file, requiredBy) => {
+        const [moduleName, tree, requires] = plainFileParser(basename(file), dirs, requiredBy.length === 0 ? options : {});
+        if (requiredBy.includes(moduleName)) {
+            throw new Error(`Circular requires: ${[...requiredBy, moduleName].join(" -> ")}`);
+        }
+        if (seen.has(moduleName))
+            return moduleName;
+        let previous = null;
+        for (const required of requires) {
+            previous = visit(locateModule(required, dirs), [...requiredBy, moduleName]);
+        }
+        seen.add(moduleName);
+        chain.push({
+            moduleName,
+            plainFile: resolve(file),
+            buildDir: buildDirUnder(root, moduleName),
+            requires: previous,
+            frids: [...getFrids(tree)],
+        });
+        return moduleName;
+    };
+    visit(resolve(plainFile), []);
+    return chain;
+}
+/**
+ * The codebase a change to `plainFile`'s module lands in: the furthest-built module whose
+ * requires chain includes it, with that chain.
+ *
+ * Code accumulates up a chain, so once modules have been built on top of this one, its own
+ * build is only an early snapshot - the living codebase is the one at the tip. A change to
+ * this module's spec is made there, where everything built since can be kept working, not
+ * in the snapshot, where it would have to be copied up over newer work.
+ *
+ * Found by reading every .plain file beside this one. Where built descendants sit on
+ * different branches there is no single tip, and choosing one is a decision: `inModule`
+ * names it, and without it this refuses rather than guesses.
+ */
+export function findCodebaseTip(plainFile, options = {}) {
+    return withParseCache(() => findTip(plainFile, options));
+}
+/**
+ * The chains of the built modules whose requires chain includes `plainFile`'s module, and that no other
+ * built module is built on - where its code lives now, one chain per branch. Empty when nothing built is
+ * built on it. Found by reading every .plain file beside it.
+ */
+export function builtTips(plainFile, options = {}) {
+    return withParseCache(() => {
+        const templateDirs = options.templateDirs ?? [];
+        const self = resolveRequiresChain(plainFile, templateDirs, options.buildRoot, { allowNoFunctionalities: true }).at(-1);
+        return tipsOf(builtChainsOver(self.moduleName, plainFile, templateDirs, options.buildRoot));
+    });
+}
+/** Every chain of a built module whose requires chain includes `moduleName`. */
+function builtChainsOver(moduleName, plainFile, templateDirs, buildRoot) {
+    const candidates = [];
+    const seen = new Set();
+    for (const dir of resolveTemplateDirs(plainFile, templateDirs)) {
+        let names;
+        try {
+            names = readdirSync(dir).filter((name) => name.endsWith(PLAIN_SOURCE_FILE_EXTENSION));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const file = join(dir, name);
+            if (seen.has(file))
+                continue;
+            seen.add(file);
+            let chain;
+            try {
+                chain = resolveRequiresChain(file, templateDirs, buildRoot);
+            }
+            catch {
+                // Import modules, and anything that does not parse, are not codebases.
+                continue;
+            }
+            const top = chain.at(-1);
+            const includes = chain.some((entry) => entry.moduleName === moduleName);
+            if (includes && listFiles(top.buildDir).length > 0)
+                candidates.push(chain);
+        }
+    }
+    return candidates;
+}
+/** Of built chains, those no other is built on top of. */
+function tipsOf(candidates) {
+    const within = (chain) => chain.slice(0, -1).map((entry) => entry.moduleName);
+    return candidates.filter((chain) => !candidates.some((other) => other !== chain && within(other).includes(chain.at(-1).moduleName)));
+}
+function findTip(plainFile, options) {
+    const templateDirs = options.templateDirs ?? [];
+    const own = resolveRequiresChain(plainFile, templateDirs, options.buildRoot, {
+        allowNoFunctionalities: options.allowNoFunctionalities,
+    });
+    const self = own.at(-1);
+    const candidates = builtChainsOver(self.moduleName, plainFile, templateDirs, options.buildRoot);
+    if (options.inModule !== undefined) {
+        const chosen = candidates.find((chain) => chain.at(-1).moduleName === options.inModule);
+        if (chosen === undefined) {
+            throw new Error(`'${options.inModule}' is not a built module that requires '${self.moduleName}'. ` +
+                `Built ones that do: ${candidates.map((c) => c.at(-1).moduleName).join(", ") || "none"}.`);
+        }
+        return { tip: chosen.at(-1), chain: chosen };
+    }
+    // A tip is a candidate that no other candidate is built on top of.
+    const tips = tipsOf(candidates);
+    if (tips.length === 0)
+        return { tip: self, chain: own };
+    if (tips.length > 1) {
+        throw new Error(`'${self.moduleName}' is built on in more than one branch: ${tips.map((c) => c.at(-1).moduleName).join(", ")}. ` +
+            "Say which codebase to regenerate in.");
+    }
+    return { tip: tips[0].at(-1), chain: tips[0] };
+}
+/**
+ * Copy a required module's codebase into the build that is about to be created.
+ *
+ * What the code is built from comes too, converted: what the source module built becomes what
+ * the new one inherits, while the new module's own functional specs start empty. Copied as-is, it would claim the source's work as the new
+ * module's own. And the conformance tests come, into the new module's tests directory.
+ */
+export function copyRequiredCode(from, to, toModule, 
+/** The module the code comes from: its functional specs are what the new one inherits. */
+fromModule) {
+    if (!existsSync(from))
+        return [];
+    mkdirSync(to, { recursive: true });
+    const copied = [];
+    for (const file of listFiles(from)) {
+        if (basename(file) === RECORD_FILE)
+            continue;
+        const target = join(to, file);
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(join(from, file), target);
+        copied.push(file);
+    }
+    // The working notes describe this code, so they come up with it.
+    if (existsSync(notesPath(from)) && !existsSync(notesPath(to)))
+        copyFileSync(notesPath(from), notesPath(to));
+    // What the code is built from comes with it, as what the new module inherits - not as its own work.
+    const built = readRecord(from);
+    writeCodeRecord(to, built !== null ? inheritedRecord(built, fromModule) : {});
+    // A new module's history starts here: where its code came from, and at which commit.
+    const source = basename(dirname(from));
+    const at = head(from);
+    const recordStart = () => recordHistory(to, `start from ${source}${at ? ` at ${at}` : ""}`);
+    // So do the conformance tests: they check the code that was just copied, and the new
+    // module's regression suite has to keep them passing. They sit beside the code, in the
+    // module's `tests` directory.
+    const testsFrom = join(dirname(from), "tests");
+    const testsTo = join(dirname(to), "tests");
+    if (existsSync(testsFrom)) {
+        for (const file of listFiles(testsFrom)) {
+            const target = join(testsTo, file);
+            mkdirSync(dirname(target), { recursive: true });
+            copyFileSync(join(testsFrom, file), target);
+        }
+        // And their notes, which listFiles leaves out as it does the code's.
+        if (existsSync(notesPath(testsFrom)) && !existsSync(notesPath(testsTo)))
+            copyFileSync(notesPath(testsFrom), notesPath(testsTo));
+    }
+    recordStart();
+    return copied;
+}
+/**
+ * A module the chain requires now that a module built in it was not built on: one required for
+ * the first time - a new module the specs were split into, say - and the built modules above it,
+ * whose code was started without it and so has to start again from scratch.
+ *
+ * A module was built on what its record lists as inherited; one with nothing recorded, on what it
+ * was started from, as its history says. A module below it with nothing built was never under it.
+ */
+export function newlyRequired(chain) {
+    for (const [index, entry] of chain.entries()) {
+        if (index === 0 || listFiles(entry.buildDir).length === 0)
+            continue;
+        const record = readRecord(entry.buildDir);
+        if (record === null)
+            continue;
+        const recorded = getInheritedFunctionalSpecs(record);
+        const known = new Set(recorded.map((spec) => spec.module));
+        const history = known.size === 0 ? historyLog(entry.buildDir, 10_000) : "";
+        const missing = chain.slice(0, index).filter((below) => {
+            if (listFiles(below.buildDir).length === 0)
+                return true;
+            if (known.size > 0)
+                return !known.has(below.moduleName);
+            // Nothing inherited on record: new only when the history shows the code was never started from it.
+            return below.moduleName === entry.requires && !history.startsWith("No history") && !history.includes(`start from ${below.moduleName}`);
+        });
+        if (missing.length > 0) {
+            return { modules: missing.map((below) => below.moduleName), rebuild: chain.slice(index).filter((above) => listFiles(above.buildDir).length > 0) };
+        }
+    }
+    return undefined;
+}
+/**
+ * Take a module back to nothing - its code, its conformance tests and what they were built from -
+ * so it is built again from the start, on the module it now requires. Committed, so the code that
+ * was there is in its history.
+ */
+export function startFromScratch(entry, why) {
+    const testsDir = join(dirname(entry.buildDir), "tests");
+    for (const dir of [entry.buildDir, testsDir])
+        rmSync(dir, { recursive: true, force: true });
+    mkdirSync(entry.buildDir, { recursive: true });
+    recordHistory(entry.buildDir, `start from scratch: ${why}`);
+}

package/dist/regenerate/resources.js

@@ -0,0 +1,164 @@
+import { copyFileSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { collectLinkedResources } from "../plain/spec.js";
+import { scriptKind } from "./test-scripts.js";
+const MAX_RESOURCE_CHARS = 8000;
+/** The images a spec can link, by extension: a model reading images is sent them as they are. */
+const IMAGE_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg" };
+/** The largest image a model provider takes in one piece. */
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+/** The MIME type of a linked image, by its extension; undefined for any other file. */
+export function imageTypeOf(target) {
+    return IMAGE_TYPES[extname(target).toLowerCase()];
+}
+/** A linked image too large to send, or unreadable: the job stops, saying which file and why. */
+export class LinkedImageError extends Error {
+}
+/**
+ * Load the resources linked from the specifications in scope for one functionality.
+ *
+ * `collectLinkedResources` stops at the requested FRID, so a resource introduced by a
+ * later functionality is not pulled into this prompt.
+ */
+export function loadLinkedResources(tree, 
+/** Up to and including this functionality. Null: the whole module. */
+frid, templateDirs) {
+    const collected = [];
+    collectLinkedResources(tree, collected, null, true, frid);
+    const loaded = [];
+    for (const resource of collected) {
+        // A testing script reaches an agent as one - whole, and only when it is run on its work -
+        // not as a resource, cut short and whether it is used or not.
+        if (scriptKind(resource.target) !== undefined)
+            continue;
+        const mimeType = imageTypeOf(resource.target);
+        if (mimeType !== undefined) {
+            const image = loadImage(templateDirs, resource.target, mimeType);
+            if (image === undefined)
+                continue;
+            const number = loaded.filter((other) => other.image !== undefined).length + 1;
+            loaded.push({ text: resource.text, target: resource.target, content: `[an image: attached to your first message, image ${number}]`, image });
+            continue;
+        }
+        const source = [...templateDirs.map((dir) => join(dir, resource.target)), resource.target].find((path) => isFileAt(path));
+        if (source === undefined)
+            continue;
+        let content = readFileSync(source, "utf8");
+        const whole = content.length;
+        if (whole > MAX_RESOURCE_CHARS) {
+            content = isCodeResource(resource.target)
+                ? `${content.slice(0, MAX_RESOURCE_CHARS)}\n... [cut here: ${whole} characters whole - code that lives outside your codebase: build on it as the specification says, never copy it]`
+                : `${content.slice(0, MAX_RESOURCE_CHARS)}\n... [cut here: ${whole} characters whole - copy_resource puts the whole file at its code-copy path, to read it there]`;
+        }
+        loaded.push({ text: resource.text, target: resource.target, content, source: resolve(source), ...(whole > MAX_RESOURCE_CHARS ? { cutFrom: whole } : {}) });
+    }
+    return loaded;
+}
+function isFileAt(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Source files, by extension: a linked resource that is one is code that lives elsewhere, never copied in. */
+const CODE_EXTENSIONS = new Set([
+    ".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".java", ".kt", ".kts", ".scala", ".groovy", ".go", ".rs", ".rb",
+    ".php", ".cs", ".fs", ".vb", ".swift", ".m", ".mm", ".c", ".h", ".cc", ".cpp", ".cxx", ".hpp", ".dart", ".lua", ".ex",
+    ".exs", ".erl", ".clj", ".hs", ".ml", ".r", ".jl", ".sh", ".bash", ".zsh", ".ps1", ".vue", ".svelte",
+]);
+/** Build manifests and lock files, by name: the dependencies of a codebase that is not this one. */
+const MANIFESTS = /^(requirements[\w.-]*\.txt|pyproject\.toml|setup\.cfg|pipfile(\.lock)?|poetry\.lock|package(-lock)?\.json|yarn\.lock|pnpm-lock\.yaml|pom\.xml|build\.gradle(\.kts)?|settings\.gradle(\.kts)?|go\.(mod|sum)|cargo\.(toml|lock)|gemfile(\.lock)?|composer\.(json|lock)|[\w.-]+\.csproj|makefile|dockerfile)$/i;
+/**
+ * A linked resource that is code - a source file, or a build manifest: the specification points at code that lives
+ * elsewhere, a host's module the code plugs into, for the code to build on as it says. It is never copied into the
+ * codebase, nor recreated there; a resource that is data - a fixture, a schema, a sample - is.
+ */
+export function isCodeResource(target) {
+    const name = target.split(/[\\/]/).pop() ?? target;
+    return CODE_EXTENSIONS.has(extname(name).toLowerCase()) || MANIFESTS.test(name);
+}
+/** Where in a codebase a linked resource's one copy goes: its path, without the steps up and the leading `./`. */
+export function codeCopyOf(target) {
+    return target
+        .split(/[\\/]/)
+        .filter((part) => part !== "" && part !== "." && part !== "..")
+        .join("/");
+}
+/**
+ * `copy_resource`: a linked resource copied whole into the agent's own folder - at its code-copy path, or where it
+ * says - by the harness, byte for byte. The agent's prompt shows a long resource cut short, and the file itself is
+ * outside its walls: copied, it reads the whole of it there, and the code or the tests use that one copy.
+ */
+export function createCopyResourceTool(options) {
+    const root = resolve(options.dir);
+    const copyable = options.resources.filter((resource) => resource.source !== undefined && resource.image === undefined);
+    return defineTool({
+        name: "copy_resource",
+        label: "Copy a linked resource",
+        description: "Copy a linked resource that is data - a fixture, a schema, a sample - whole into your folder, at its code-copy path " +
+            "unless you give another inside your folder, byte for byte: for a file the code or the tests read, or to read one the " +
+            "prompt shows cut short. A resource that is code - a source file, a build manifest - is never copied: it lives elsewhere.",
+        promptSnippet: "copy_resource: a linked resource copied whole into your folder, at its code-copy path",
+        parameters: Type.Object({
+            path: Type.String({ description: "The resource's path, as <linked resources> gives it" }),
+            to: Type.Optional(Type.String({ description: "Where in your folder, relative to it - its code-copy path when left out" })),
+        }),
+        async execute(_id, params) {
+            const { path, to } = params;
+            const resource = copyable.find((candidate) => candidate.target === path || codeCopyOf(candidate.target) === codeCopyOf(path));
+            if (resource === undefined) {
+                const known = copyable.map((candidate) => candidate.target).join(", ");
+                return { content: [{ type: "text", text: `No linked resource ${path}. ${known !== "" ? `The ones you have: ${known}.` : "You have none to copy."}` }], details: {} };
+            }
+            if (isCodeResource(resource.target)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Not copied: ${resource.target} is code - a source file or a build manifest that lives outside your codebase, linked ` +
+                                "so you know what your code plugs into. Build on it as the specification says - import it, call it, depend on " +
+                                "what it lists - and never copy it, nor recreate it or what it belongs to in your codebase.",
+                        },
+                    ],
+                    details: {},
+                };
+            }
+            const target = resolve(root, to ?? codeCopyOf(resource.target));
+            const inside = relative(root, target);
+            if (inside === "" || inside.startsWith("..") || isAbsolute(inside)) {
+                return { content: [{ type: "text", text: `Not copied: ${to} is not inside your folder, ${root}.` }], details: {} };
+            }
+            mkdirSync(dirname(target), { recursive: true });
+            copyFileSync(resource.source, target);
+            const size = statSync(target).size;
+            return { content: [{ type: "text", text: `Copied ${resource.target} whole to ${inside} (${size} bytes). Read it there.` }], details: {} };
+        },
+    });
+}
+/** The images among loaded resources, in the order the prompt numbers them. */
+export function resourceImages(resources) {
+    return resources.flatMap((resource) => (resource.image !== undefined ? [resource.image] : []));
+}
+/** A linked image's bytes, found as a text resource is: the template folders first, then the current directory. */
+function loadImage(templateDirs, target, mimeType) {
+    for (const path of [...templateDirs.map((dir) => join(dir, target)), target]) {
+        let size;
+        try {
+            if (!statSync(path).isFile())
+                continue;
+            size = statSync(path).size;
+        }
+        catch {
+            continue;
+        }
+        if (size > MAX_IMAGE_BYTES) {
+            throw new LinkedImageError(`The linked image ${target} is ${(size / 1024 / 1024).toFixed(1)} MB - a model takes images up to ${MAX_IMAGE_BYTES / 1024 / 1024} MB. Make it smaller, or link a smaller one.`);
+        }
+        return { type: "image", data: readFileSync(path).toString("base64"), mimeType };
+    }
+    return undefined;
+}

package/dist/regenerate/self-check.js

@@ -0,0 +1,111 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { workDiff } from "./lineage.js";
+import { lastPassingMs, runOnCode } from "./test-scripts.js";
+/**
+ * Tools an agent checks its own work with, before the harness and the reviewer do: the diff the reviewer is shown, and
+ * whether a test catches a change to the code. Neither decides anything - the testing scripts, run by the harness, still do.
+ */
+/** The work so far, as the reviewer is shown it: a diff of the folder from the commit the job started from. */
+export function createMyDiffTool(options) {
+    const folder = options.what === "code" ? "code folder" : "tests folder";
+    return defineTool({
+        name: "my_diff",
+        label: "My diff",
+        description: `The diff of the ${folder} from where this work started - every file changed, added or taken out, new files ` +
+            "whole - exactly what the reviewer is shown of your work. Read it before you hand the work in: every part of the " +
+            "change should be in it, and nothing else.",
+        promptSnippet: `my_diff: your work so far, as the reviewer sees it - the ${folder} from where the work started`,
+        parameters: Type.Object({}),
+        async execute() {
+            const diff = workDiff(options.dir);
+            return { content: [{ type: "text", text: diff === "" ? `Nothing in the ${folder} has changed yet.` : diff }], details: {} };
+        },
+    });
+}
+const outputOf = (run) => `${run.command} exited ${run.exitCode}${run.timedOut === true ? " - stopped by the time limit" : ""}\n\n${run.output}`;
+/** How many times can_it_fail runs in one session, by default: each is a run of the unit testing script. */
+export const CAN_IT_FAIL_RUNS = 6;
+/**
+ * How long a can_it_fail run may take: three times the last passing run of the unit tests on this code, within 15 and
+ * 60 seconds - 60 before one has passed. A bug put in the code often makes it loop or wait for ever: that is found out
+ * in a short time, not the whole limit of a test run, and well within the agent's turn.
+ */
+export function canItFailLimitMs(buildDir, script) {
+    const last = lastPassingMs(buildDir, script);
+    return last === undefined ? 60_000 : Math.min(Math.max(last * 3, 15_000), 60_000);
+}
+/**
+ * Whether the unit tests catch a change to the code: the change made to a fresh copy - never to the code itself - and
+ * the unit testing script run on it. A test that passes whatever the code does tests nothing.
+ */
+export function createCanItFailTool(options) {
+    let left = options.runs ?? CAN_IT_FAIL_RUNS;
+    return defineTool({
+        name: "can_it_fail",
+        label: "Can it fail",
+        description: "Check that the unit tests catch a bug: give one change to the code that breaks a behaviour the specification " +
+            "states - a value or a status changed, a check taken out, a condition turned round where it cannot make a loop run for " +
+            "ever - and the unit testing script " +
+            "runs on a copy of the code with that change. The code itself is never touched. The tests should fail; if they all " +
+            "pass, no test catches that bug. Make a change that still builds and runs: a failure only because it no longer " +
+            `compiles or imports says nothing about the tests. ${options.runs ?? CAN_IT_FAIL_RUNS} runs at most.`,
+        promptSnippet: "can_it_fail: whether the unit tests catch a bug you put in a copy of the code",
+        parameters: Type.Object({
+            file: Type.String({ description: "The code file to change, relative to the code folder" }),
+            find: Type.String({ description: "Text that is in the file exactly once - the code to change" }),
+            replace: Type.String({ description: "What it becomes: the bug" }),
+        }),
+        async execute(_id, params) {
+            const { file, find, replace } = params;
+            const say = (text) => ({ content: [{ type: "text", text }], details: {} });
+            if (left <= 0)
+                return say("can_it_fail has no runs left in this session: decide with what it showed.");
+            const path = resolve(options.buildDir, file);
+            if (relative(options.buildDir, path).startsWith(`..${sep}`) || relative(options.buildDir, path) === "..")
+                return say(`${file} is not in the code folder.`);
+            let text;
+            try {
+                text = readFileSync(path, "utf8");
+            }
+            catch {
+                return say(`There is no ${file} in the code folder.`);
+            }
+            const at = text.indexOf(find);
+            if (at === -1)
+                return say(`"${find}" is not in ${file}: give text that is in it exactly as written.`);
+            if (text.indexOf(find, at + 1) !== -1)
+                return say(`"${find}" is in ${file} more than once: give more of it, so it is there once.`);
+            if (find === replace)
+                return say("The change changes nothing.");
+            left -= 1;
+            let run;
+            try {
+                run = await runOnCode(options.buildDir, options.script, "unit testing script, with the change", (copy) => writeFileSync(join(copy, relative(options.buildDir, path)), text.slice(0, at) + replace + text.slice(at + find.length)), canItFailLimitMs(options.buildDir, options.script));
+            }
+            catch (error) {
+                return say(error instanceof Error ? error.message : String(error));
+            }
+            const verdict = run.timedOut === true
+                ? `The unit tests did not finish in ${Math.round(run.timeoutMs / 1000)}s with ${file} changed: the bug makes the code hang - a loop that never ends, a wait for something that never comes. That shows the code breaks, not that a test catches it: the tests hang too. Put in a bug that makes a result wrong instead - a value, a status, a field - and check again.`
+                : run.exitCode === 0
+                    ? `Every unit test passes with ${file} changed: no test catches this bug. A test that should - one for the behaviour this code is for - does not check what it says.`
+                    : `The unit tests fail with ${file} changed: something catches it. Check in the output below that a test's assertion caught it - a failure only because the copy no longer builds or imports says nothing about the tests.`;
+            // A hang prints the same thing over and over: its last lines are enough.
+            const shown = run.timedOut === true ? `${run.command} was stopped after ${Math.round(run.timeoutMs / 1000)}s. Its last output:\n\n${run.output.trimEnd().slice(-2_000)}` : outputOf(run);
+            return { content: [{ type: "text", text: `${verdict} (${left} run${left === 1 ? "" : "s"} left)\n\n${shown}` }], details: { exitCode: run.exitCode } };
+        },
+    });
+}
+/** When the coding agent checks its own work, by the tools it has: before the unit tests, and before it hands the work in. */
+export function selfCheckNote(tools) {
+    const has = (name) => tools.includes(name);
+    const steps = [
+        ...(has("can_it_fail") ? ["for each behaviour you built, check with can_it_fail that a test fails when it breaks"] : []),
+        ...(has("start_service") ? ["where you built a server, start it with start_service and try what you built with curl, as a client would"] : []),
+        ...(has("my_diff") ? ["read my_diff: every part of the change in it, and nothing else"] : []),
+    ];
+    return steps.length > 0 ? [`Check your own work before you hand it in: ${steps.join("; ")}.`, ""] : [];
+}