@turri-dev/cli 0.1.3-next.04c4f71 → 0.1.3-next.162a2c3

package/dist/regenerate/conformance.js

@@ -9,14 +9,14 @@ import { abandonWork, diffSinceSnapshot, moduleDirOf, recordHistory, startWork,
 import { createWorkLedger, describeAccounts, SUBMIT_WORK_NOTE, unanswered, unansweredPrompt } from "./submit-work.js";
 import { CONFORMANCE_COMPACTION } from "./compaction.js";
 import { NOTES_TURN, notesForSession, passedOutcome, readNotes, reflectOnReview, withNotes } from "./notes.js";
-import { labelsPrompt, labelsPromptFor, misplacedConformanceTests, misplacedTestsPrompt, missingTestLabels } from "./test-kinds.js";
+import { acceptanceLabel, acceptanceText, labelsPrompt, labelsPromptFor, misplacedConformanceTests, misplacedTestsPrompt, missingTestLabels } from "./test-kinds.js";
 import { createScriptTool, findTestScripts, projectRootFor, requireTestScripts, runConformanceScript, runUnitScript, failureSignature, STUCK_ROUNDS, scriptFailure, staticChecksOnly, withTestingScripts, } from "./test-scripts.js";
 import { createWebTools, WEB_TOOLS } from "./web.js";
 import { createMyDiffTool } from "./self-check.js";
 import { createServiceTools } from "./services.js";
-import { missingToolchainError, toolchainError } from "./environment-error.js";
+import { missingToolchainError, timeLimitError, toolchainError } from "./environment-error.js";
 import { workspaceBlock } from "./workspace.js";
-import { codeFixPrompt, conflictKey, createCodeFixer, answerAsExplorer, createAskExplorerTool, exploreInvocation, judgeFailure, SPEC_CONFLICT_RAISES, ENVIRONMENT_RAISES, environmentCheckPrompt, createTestReviewer, testReviewRequest, reviewFeedbackPrompt, testsFixPrompt, sortedRefs, } from "./conformance-agents.js";
+import { codeFixPrompt, conflictKey, escalatedFixPrompt, createCodeFixer, answerAsExplorer, createAskExplorerTool, exploreInvocation, judgeFailure, SPEC_CONFLICT_RAISES, ENVIRONMENT_RAISES, environmentCheckPrompt, createTestReviewer, testReviewRequest, reviewFeedbackPrompt, testsFixPrompt, sortedRefs, } from "./conformance-agents.js";
 import { resolveRequiresChain } from "./requires.js";
 import { notesToRead, recordNote } from "./notes.js";
 import { reportSpecConflict } from "./activity.js";
@@ -157,9 +157,11 @@ export async function renderConformanceTests(options) {
     // may read the code but writes only tests. An explorer reads the code first and writes down how the
     // software is invoked, which is what the tests are written against.
     const label = `${moduleName} ${options.diff !== undefined ? "spec change" : frid}`;
-    const specContext = { moduleName, text: specText(specifications, moduleName, frids, required, options.change ?? options.diff, sectionModules(tree, moduleName)) };
     // For a spec change: the functionalities it touches, whose acceptance tests are labelled, checked and reviewed.
     const touched = forChange ? touchedFunctionalities(tree, frids, options.diff) : [];
+    // The acceptance tests the run's tests carry out: every functionality the change touches, or the one under test.
+    const carriedOut = forChange ? touched : [{ frid: frid, acceptanceTests: specifications[ACCEPTANCE_TESTS] ?? [] }];
+    const specContext = { moduleName, text: specText(specifications, moduleName, frids, required, carriedOut, options.change ?? options.diff, sectionModules(tree, moduleName)) };
     // Any functionality of the codebase - this module's, and those of the modules it requires. A
     // functionality's run may raise a spec conflict only with that functionality; a spec diff's, between any two.
     const own = (forChange ? frids : frids.slice(0, frids.indexOf(frid) + 1)).map((id) => ({ module: moduleName, frid: id }));
@@ -194,6 +196,11 @@ export async function renderConformanceTests(options) {
     let environmentRaises = 0;
     /** How many fixes in a row - the code's or the tests' - changed no file: an agent that will not, or cannot, act on the verdict. */
     let idleFixes = 0;
+    /** The last fix was the tests', for a failure judged theirs: should the run fail the same way again, the judge weighs escalating it. */
+    let testsFix;
+    /** A failure escalated to the code: should the run still fail the same way after the code's fix, the run stops. */
+    let escalated;
+    let escalation;
     /**
      * One attempt at the failing run, written into the notes' pitfalls - what the next judge reads
      * first - as cause and effect: what failed, how it was judged, and what was changed; the next
@@ -218,11 +225,15 @@ export async function renderConformanceTests(options) {
     };
     stage(`exploring the code for how it is invoked${options.model ? ` (${options.model})` : ""}`);
     // The explorer reads the conformance testing script too: it is how the tests are built and run, and so how they reach the software.
+    // The prepare script, where there is one, runs on the build before it - and only once it passes does the suite run.
     const testingScripts = [
+        ...(scripts.prepare !== undefined
+            ? [{ path: relative(root, scripts.prepare), runs: "<script> <copy of the build>, before every run of the conformance testing script", content: readFileSync(scripts.prepare, "utf8"), prepare: true }]
+            : []),
         { path: relative(root, scripts.conformance), runs: "<script> <copy of the build> <copy of the whole conformance suite>", content: readFileSync(scripts.conformance, "utf8") },
     ];
     // The acceptance tests the explorer's plan has to carry out, step by step.
-    const toCarryOut = (forChange ? touched : [{ frid: frid, acceptanceTests: specifications[ACCEPTANCE_TESTS] ?? [] }])
+    const toCarryOut = carriedOut
         .map((item) => ({ module: moduleName, frid: item.frid, count: item.acceptanceTests.length }))
         .filter((item) => item.count > 0);
     let invocation = await exploreInvocation({ buildDir, spec: specContext, scope, testingScripts, acceptance: toCarryOut, label, model: options.model, onDelta: options.onDelta });
@@ -314,6 +325,7 @@ export async function renderConformanceTests(options) {
             ],
             toolNames: ["run_unit_tests", "run_conformance_tests", ...fixerServices.names, "update_notes"],
             checkEnvironment: { run: () => runUnitScript(buildDir, scripts.unit), script: scripts.unit },
+            testingScripts: { scripts, root },
         });
         fixerConformanceRuns.newTurn();
         return ask(fixer, withNotes(text, buildDir), options.onDelta);
@@ -414,6 +426,15 @@ export async function renderConformanceTests(options) {
                     abandonWork(start, moduleName, "the conformance testing script could not run");
                 throw lacking;
             }
+            // A failure escalated to the code, still the same after the code's fix: neither agent could fix it, and the run stops
+            // with why the judge found it the code's. Anything else it fails on is a new failure, judged as any other.
+            if (escalated !== undefined && recheck.exitCode !== 0 && failureSignature(recheck) === escalated.signature) {
+                escalation = { reason: escalated.reason, evidence: escalated.evidence, error: failureLine(recheck), failure: truncateOutput(recheck.output, undefined).slice(-4000) };
+                stage("the failure escalated to the code is still there after the coding agent's fix - stopping");
+                recordNote(conformanceDir, "pitfalls", `stopped after ${rounds} attempts: failed with ${failureLine(recheck)}, escalated to the code - ${escalated.reason.replace(/\s+/g, " ").slice(0, 240)} - and the code's fix did not change it`, `${label} conformance`);
+                break;
+            }
+            escalated = undefined;
             if (recheck.exitCode !== 0) {
                 // Nothing changing: the same failure, taken the same way, round after round. Once, the explorer
                 // is asked what the tests lack - most often how they reach the software; after that, it stops.
@@ -480,19 +501,6 @@ export async function renderConformanceTests(options) {
                         idleFixes = 0;
                     continue;
                 }
-                // A run out of time is not a question of test or code: the tests' environment is the conformance agent's.
-                if (recheck.timedOut === true) {
-                    const moved = await unmoved();
-                    if (moved === "stuck")
-                        break;
-                    if (moved === "asked")
-                        continue;
-                    stage("the conformance run did not get to the tests - back to the conformance agent");
-                    const fixed = await changing(() => askConformance(scriptFailure(recheck, "conformance testing"), options.onDelta));
-                    response = fixed.result;
-                    recordAttempt(rounds, recheck, `not a question of code or tests (${recheck.timedOut === true ? "the time limit" : `exit ${recheck.exitCode}`})`, { who: "conformance agent", files: fixed.files });
-                    continue;
-                }
                 stage(`conformance tests failing - working out whether the code, the tests or the spec are wrong${judgeModel ? ` (${judgeModel})` : ""}`);
                 // A fix that changed no file leaves the next run as this one: IDLE_FIXES of them in a row, and nothing will change.
                 const idle = (files) => {
@@ -504,6 +512,12 @@ export async function renderConformanceTests(options) {
                     recordNote(conformanceDir, "pitfalls", `stuck after ${rounds} attempts: failed with ${failureLine(recheck)}, and ${IDLE_FIXES} fixes in a row changed nothing`, `${label} conformance`);
                     return true;
                 };
+                // The tests were fixed for this very failure, and it is still here: the judge weighs whether it is the code's.
+                const signature = failureSignature(recheck);
+                const escalating = testsFix !== undefined && testsFix.signature === signature ? { reason: testsFix.reason, changed: testsFix.files } : undefined;
+                testsFix = undefined;
+                if (escalating !== undefined)
+                    stage("the tests' fix did not make the failure go away - the judge weighs whether it is the code's");
                 const verdict = await judgeFailure({
                     buildDir,
                     conformanceDir,
@@ -513,11 +527,22 @@ export async function renderConformanceTests(options) {
                     scope,
                     // The tests' notes - every attempt so far - and the code's: it weighs the one against the other.
                     notes: [notesToRead(conformanceDir), notesToRead(buildDir)].filter((part) => part !== "").join("\n\n"),
+                    // The script itself, so the judge checks the explorer's account against it rather than repeating it.
+                    testingScripts,
+                    ...(escalating !== undefined ? { escalation: escalating } : {}),
                     label,
                     model: judgeModel,
                     onDelta: options.onDelta,
                 });
                 const reason = verdict.reason.split("\n")[0].slice(0, 160);
+                // Stopped by the time limit while it was still getting on: no agent can give it more time. The pulse stops now -
+                // rolled back, no retry - and the person is told how to raise the limit.
+                if (verdict.culprit === "environment" && recheck.timedOut === true) {
+                    stage(`the conformance run needs more than the ${Math.round(recheck.timeoutMs / 1000)}s a test run may take - stopping`);
+                    if (start !== undefined)
+                        abandonWork(start, moduleName, "the conformance testing script needs more time than a test run may take");
+                    throw timeLimitError(recheck, { moduleName, script: scripts.conformance, kind: "conformance", reason: verdict.reason });
+                }
                 // The environment - what the run is given - is the person's to fix: once judged so twice in a row, the run stops.
                 if (verdict.culprit === "environment") {
                     environmentRaises += 1;
@@ -585,15 +610,34 @@ export async function renderConformanceTests(options) {
                     recordAttempt(rounds, recheck, `a spec conflict between functionalities ${key}: ${verdict.reason}`, { who: "conformance agent", files: fixed.files });
                 }
                 else if (verdict.culprit === "code") {
-                    reportActivity(`  the code: ${reason}`);
-                    stage("the code is wrong - the coding agent fixes it");
-                    // One fixer for the run, starting each fix from what the ones before it tried: its work is compacted as
-                    // it gets longer, so a session carried through the run does not re-read every earlier fix and suite output
-                    // whole.
-                    const fixed = await changing(() => askFixer(codeFixPrompt({ run: recheck, reason: verdict.reason })));
-                    recordAttempt(rounds, recheck, `the code wrong: ${verdict.reason}`, { who: "coding agent", files: fixed.files });
-                    if (idle(fixed.files))
-                        break;
+                    if (escalating !== undefined) {
+                        // Escalated: the coding agent is handed the script's error, the tests as they stand and the judge's evidence.
+                        // Its fix is the last attempt at this failure - should the run fail the same way after it, the run stops.
+                        const evidence = verdict.evidence ?? [];
+                        reportActivity(`  escalated to the code: ${reason}`);
+                        stage("the judge finds the failure the code's - escalated to the coding agent");
+                        const tests = listFiles(conformanceDir).map((path) => ({ path, content: readFileSync(join(conformanceDir, path), "utf8") }));
+                        const fixed = await changing(() => askFixer(escalatedFixPrompt({ run: recheck, reason: verdict.reason, evidence, tests })));
+                        recordAttempt(rounds, recheck, `escalated to the code: ${verdict.reason}`, { who: "coding agent", files: fixed.files });
+                        if (fixed.files.length === 0) {
+                            escalation = { reason: verdict.reason, evidence, error: failureLine(recheck), failure: truncateOutput(recheck.output, undefined).slice(-4000), changedNothing: true };
+                            stage("the coding agent changed nothing for the failure escalated to it - stopping");
+                            break;
+                        }
+                        idleFixes = 0;
+                        escalated = { signature, reason: verdict.reason, evidence };
+                    }
+                    else {
+                        reportActivity(`  the code: ${reason}`);
+                        stage("the code is wrong - the coding agent fixes it");
+                        // One fixer for the run, starting each fix from what the ones before it tried: its work is compacted as
+                        // it gets longer, so a session carried through the run does not re-read every earlier fix and suite output
+                        // whole.
+                        const fixed = await changing(() => askFixer(codeFixPrompt({ run: recheck, reason: verdict.reason })));
+                        recordAttempt(rounds, recheck, `the code wrong: ${verdict.reason}`, { who: "coding agent", files: fixed.files });
+                        if (idle(fixed.files))
+                            break;
+                    }
                     // The fix has to build and pass its own unit tests before the suite runs again: a build
                     // error is the coding agent's to fix, not a judge's to work out from the suite's output.
                     for (let again = 0; again < FIX_UNIT_CHECKS; again += 1) {
@@ -613,7 +657,11 @@ export async function renderConformanceTests(options) {
                     const fixed = await changing(() => askConformance(testsFixPrompt({ run: recheck, reason: verdict.reason }), options.onDelta));
                     response = fixed.result;
                     recordAttempt(rounds, recheck, `the tests wrong: ${verdict.reason}`, { who: "conformance agent", files: fixed.files });
-                    if (idle(fixed.files))
+                    testsFix = { signature, reason: verdict.reason, files: fixed.files };
+                    // A fix that changed nothing does not stop the run before the judge has weighed escalating the failure.
+                    if (escalating === undefined)
+                        idleFixes = fixed.files.length === 0 ? idleFixes + 1 : 0;
+                    else if (idle(fixed.files))
                         break;
                 }
                 continue;
@@ -646,7 +694,7 @@ export async function renderConformanceTests(options) {
                     buildDir,
                     conformanceDir,
                     spec: specContext,
-                    functionalities: forChange ? touched : [{ frid: frid, acceptanceTests: specifications[ACCEPTANCE_TESTS] ?? [] }],
+                    functionalities: carriedOut,
                     forChange,
                     invocation,
                     label,
@@ -772,6 +820,7 @@ export async function renderConformanceTests(options) {
             ...(specConflict !== undefined ? { specConflict } : {}),
             ...(stuck !== undefined ? { stuck } : {}),
             ...(environment !== undefined ? { environment } : {}),
+            ...(escalation !== undefined ? { escalation } : {}),
             ...(unlabelled !== undefined ? { unlabelled } : {}),
             ...(reviewWaived !== undefined ? { reviewWaived } : {}),
             ...(verified && green !== undefined ? { green } : {}),
@@ -905,9 +954,10 @@ export function failureLine(run) {
 }
 /**
  * The spec as the explorer, the judge and the coding agent are shown it - its functional specs
- * numbered with their ids, so a spec conflict can name them.
+ * numbered with their ids, so a spec conflict can name them, and the acceptance tests the run carries
+ * out labelled as their tests are, so a verdict can quote them.
  */
-function specText(specifications, moduleName, frids, required, diff, modules) {
+function specText(specifications, moduleName, frids, required, acceptance, diff, modules) {
     // Every functionality in the codebase, each with its module: the required modules' first, then this one's.
     const numbered = (key, items) => key === FUNCTIONAL_REQUIREMENTS
         ? [
@@ -915,10 +965,14 @@ function specText(specifications, moduleName, frids, required, diff, modules) {
         ]
         : items;
     // Each section in its tag, as every agent is shown it (see specPrimer).
-    const sections = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, FUNCTIONAL_REQUIREMENTS, ACCEPTANCE_TESTS]
+    const sections = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, FUNCTIONAL_REQUIREMENTS]
         .map((key) => [key, specifications[key] ?? []])
         .filter(([, items]) => items.length > 0)
-        .map(([key, items]) => (key === FUNCTIONAL_REQUIREMENTS || key === ACCEPTANCE_TESTS ? section(key, numbered(key, items)) : moduleSection(key, items, moduleName, modules)));
+        .map(([key, items]) => (key === FUNCTIONAL_REQUIREMENTS ? section(key, numbered(key, items)) : moduleSection(key, items, moduleName, modules)));
+    // Not only the last functionality's: a spec change's run carries out the acceptance tests of every one it touches.
+    const tests = acceptance.flatMap((item) => item.acceptanceTests.map((test, index) => `${acceptanceLabel(item.frid, index + 1)}: ${acceptanceText(test)}`));
+    if (tests.length > 0)
+        sections.push(section(ACCEPTANCE_TESTS, tests));
     if (diff !== undefined)
         sections.push(specChangeBlock(diff));
     return sections.join("\n\n");

package/dist/regenerate/debugger.js

@@ -4,6 +4,7 @@ import { Type } from "typebox";
 import { ask, BEGIN, createExecutor } from "../pi.js";
 import { confinedTools } from "./confine.js";
 import { createWebTools, WEB_TOOLS } from "./web.js";
+import { runTiming } from "./test-scripts.js";
 /**
  * A fresh look at a failure the coding agent keeps hitting.
  *
@@ -24,9 +25,12 @@ export function diagnosisText(diagnosis) {
 }
 function debugPrompt(input) {
     const script = input.script !== undefined && existsSync(input.script) ? readFileSync(input.script, "utf8") : undefined;
+    const timedOut = input.run?.timedOut === true;
     return [
-        `The unit tests of the codebase in ${input.buildDir} have failed the same way ${input.times} times in a row. The coding agent`,
-        "keeps changing things and the failure does not move: it has not seen the cause. You look at it with fresh eyes.",
+        timedOut
+            ? `The unit testing script of the codebase in ${input.buildDir} did not finish: the time limit stopped it. You look at it with fresh eyes.`
+            : `The unit tests of the codebase in ${input.buildDir} have failed the same way ${input.times} times in a row. The coding agent`,
+        ...(timedOut ? [] : ["keeps changing things and the failure does not move: it has not seen the cause. You look at it with fresh eyes."]),
         "",
         "Find the root cause - the one thing that makes this failure happen - and the change that fixes it. Read the failing",
         "run below, the tests it names, the code they exercise, the build files (pyproject.toml, package.json, go.mod, pom.xml,",
@@ -37,6 +41,21 @@ function debugPrompt(input) {
         "",
         "You change nothing - you only read. When you know, call submit_diagnosis: the root cause, with the evidence for it,",
         "and the fix - which files, and exactly what to change in them.",
+        ...(timedOut
+            ? [
+                "",
+                "<timed out>",
+                "The run's output ends where the time limit stopped it: the test running then, or the step after the last one it",
+                "printed, is what did not finish. Find what kept it:",
+                "- something hangs - a test or the code waits on input, keeps a server in the foreground, never exits, loops, blocks",
+                "  on a lock or a network call that never answers: the root cause and the fix, as for any failure;",
+                "- nothing hangs - the output shows the run making steady progress right up to the limit (installing, building, test",
+                "  after test passing) and it needs more time than a test run may take: set too_slow, and say in root_cause from the",
+                "  output how far it got and what took the time. No agent can give it more time: the work stops, and the person is",
+                "  told to raise the limit. Judge from the output and the files, never from the time alone.",
+                "</timed out>",
+            ]
+            : []),
         "",
         "<what the change is meant to do>",
         input.task.trim(),
@@ -44,6 +63,7 @@ function debugPrompt(input) {
         ...(script !== undefined ? ["", `<testing script path="${input.script}">`, script.trimEnd(), "</testing script>"] : []),
         "",
         "<failing run>",
+        ...(input.run !== undefined ? [runTiming(input.run), ""] : []),
         input.failure.trimEnd().slice(-8000),
         "</failing run>",
     ].join("\n");
@@ -58,10 +78,14 @@ export async function debugFailure(input) {
         parameters: Type.Object({
             root_cause: Type.String({ description: "The one thing that makes the failure happen, and the evidence for it: the lines of the run, the code, the docs" }),
             fix: Type.String({ description: "The change that fixes it: which files, and exactly what to change in them" }),
+            too_slow: Type.Optional(Type.Boolean({
+                description: "Only for a run the time limit stopped: true when nothing hangs - it was making progress up to the limit and needs more time than a test run may take",
+            })),
         }),
         async execute(_id, params) {
             const given = params;
-            found = { rootCause: given.root_cause, fix: given.fix };
+            // Too slow is a verdict on a run the limit stopped, and on no other.
+            found = { rootCause: given.root_cause, fix: given.fix, ...(given.too_slow === true && input.run?.timedOut === true ? { tooSlow: true } : {}) };
             return { content: [{ type: "text", text: "Recorded." }], details: {}, terminate: true };
         },
     });

package/dist/regenerate/environment-error.js

@@ -224,6 +224,23 @@ export function toolchainError(missing, details) {
         source: "harness",
     });
 }
+/**
+ * A testing script the time limit stopped while it was still making progress - judged so by the judge or the debugger,
+ * from where its output stops: nothing hangs, the suite needs more time than a test run may take. No agent can give it
+ * that, so the pulse stops and the person is told how to.
+ */
+export function timeLimitError(run, details) {
+    const limit = Math.round(run.timeoutMs / 1000);
+    return new EnvironmentError({
+        moduleName: details.moduleName,
+        missing: `more time for a test run than its ${limit}s limit`,
+        neededBy: `the ${details.kind} testing script, \`${basename(details.script)}\``,
+        shownBy: `it ran ${Math.round((run.elapsedMs ?? run.timeoutMs) / 1000)}s and was stopped at the limit, still making progress - ${details.reason.replace(/\s+/g, " ").trim().slice(0, 400)}`,
+        fix: `give a test run more time - set TURRI_COMMAND_TIMEOUT, in seconds, above ${limit} (e.g. TURRI_COMMAND_TIMEOUT=${limit * 3}) in the ` +
+            "environment turri runs in - or make the suite faster: what it installs or builds on every run, and the tests that take longest.",
+        source: "agent",
+    });
+}
 /** The harness's run of a testing script, when it could not find its toolchain: the error that stops the pulse. */
 export function missingToolchainError(run, details) {
     const missing = missingToolchain(run);

package/dist/regenerate/loop.js

@@ -16,7 +16,7 @@ import { modulesRoot } from "./paths.js";
 import { budgetFor, choosingWhen, configForSpec, conformanceSwitchedOn } from "../config.js";
 import { describeSpecChange } from "./prompt.js";
 import { resolveTemplateDirs } from "./paths.js";
-import { builtTips, copyRequiredCode, newlyRequired, resolveRequiresChain, startFromScratch } from "./requires.js";
+import { builtTips, copyRequiredCode, importingModules, isImportModule, newlyRequired, resolveRequiresChain, startFromScratch } from "./requires.js";
 import { withTryItLine } from "./delivery.js";
 import { describeSpecDiff, renderSpecDiff, specFilesOf } from "./regenerate.js";
 import { locateDiffLines } from "./diff-view.js";
@@ -85,6 +85,23 @@ function chainsFor(plainFile) {
     const tips = builtTips(plainFile);
     return tips.length > 0 ? tips : [resolveRequiresChain(plainFile, [], undefined, { allowNoFunctionalities: true })];
 }
+/**
+ * The modules a .plain file is built as: itself - or, an import module, the modules importing it whose code is started.
+ * An import module is no codebase; one no started module imports has nothing to build yet - its reqs are built with the
+ * first module that imports it.
+ */
+function codebasesOf(plainFile) {
+    if (!isImportModule(plainFile))
+        return [plainFile];
+    return importingModules(plainFile).filter((file) => {
+        try {
+            return builtTips(file).length > 0 || started(resolveRequiresChain(file, [], undefined, { allowNoFunctionalities: true }).at(-1));
+        }
+        catch {
+            return false;
+        }
+    });
+}
 /** How many functional specs of its own a codebase has built - none when it was only started from the code below it. */
 function ownBuilt(entry) {
     return (readRecord(entry.buildDir)?.[FUNCTIONAL_REQUIREMENTS] ?? []).length;
@@ -989,9 +1006,10 @@ export function createWorkLoop(options) {
     };
     const loop = {
         async bringUp(plainFile, request = {}) {
-            const file = resolve(options.cwd, plainFile);
-            asked.set(file, { ...asked.get(file), ...request });
-            const states = withParseCache(() => chainsFor(file).flatMap((chain) => toBuild(chain).map((entry) => track(chain.slice(0, chain.indexOf(entry) + 1), file, request))));
+            const files = codebasesOf(resolve(options.cwd, plainFile));
+            for (const file of files)
+                asked.set(file, { ...asked.get(file), ...request });
+            const states = withParseCache(() => files.flatMap((file) => chainsFor(file).flatMap((chain) => toBuild(chain).map((entry) => track(chain.slice(0, chain.indexOf(entry) + 1), file, request)))));
             // Asked again, a halted codebase is tried again.
             for (const state of states)
                 state.halted = undefined;

package/dist/regenerate/prompt.js

@@ -278,8 +278,10 @@ function itemText(serialized) {
         return item;
     const { markdown, [ACCEPTANCE_TESTS]: tests } = (item ?? {});
     const lines = [markdown ?? JSON.stringify(item)];
+    // Each test is an item of the tree, its text in its markdown - as spec-steps.ts `itemText` reads it.
+    const testText = (test) => (typeof test === "string" ? test : (test?.markdown ?? JSON.stringify(test)));
     if (Array.isArray(tests) && tests.length > 0)
-        lines.push("  <acceptance tests>", ...tests.map((test) => `  ${String(test)}`), "  </acceptance tests>");
+        lines.push("  <acceptance tests>", ...tests.map((test) => `  ${testText(test).replace(/\n/g, "\n  ")}`), "  </acceptance tests>");
     return lines.join("\n");
 }
 const indent = (text, by) => text.split("\n").map((line) => `${by}${line}`).join("\n");

package/dist/regenerate/regenerate.js

@@ -20,7 +20,7 @@ import { createWebTools, WEB_TOOLS } from "./web.js";
 import { createCanItFailTool, createMyDiffTool, selfCheckNote } from "./self-check.js";
 import { createServiceTools } from "./services.js";
 import { createUnitGate } from "./unit-gate.js";
-import { toolchainError } from "./environment-error.js";
+import { timeLimitError, toolchainError } from "./environment-error.js";
 import { workspaceBlock } from "./workspace.js";
 import { ATTEMPTS, describeStop } from "./stop-report.js";
 import { summarizeDiff } from "./job-panel.js";
@@ -333,6 +333,8 @@ export async function renderSpecDiff(options) {
     let draftAsks = 0;
     /** What the unit testing script needs and does not find, last run. */
     let missing;
+    /** The unit testing script needs more time than a test run may take - the debugger's finding: the pulse stops on it. */
+    let slow;
     /** The last round failed on the script's static checks alone: the unit tests passed. */
     let staticOnly = false;
     const testRemovals = [];
@@ -423,24 +425,35 @@ export async function renderSpecDiff(options) {
                         seenFailures.set(key, seen);
                     let prompt = verdict.prompt;
                     const circling = loop.stuck;
-                    if (circling || (key !== undefined && seen >= STUCK_ROUNDS)) {
+                    // A run the time limit stopped is looked at at once: whether something hangs, or the suite only needs more time.
+                    const timedOut = verdict.run.timedOut === true;
+                    if (circling || timedOut || (key !== undefined && seen >= STUCK_ROUNDS)) {
                         if (key !== undefined)
                             seenFailures.delete(key);
                         const times = circling ? Math.max(seen, loop.failing) : seen;
                         loop.reset();
                         stage(circling
                             ? `the coding agent is going round in circles - ${times} failing runs - a debugger looks at it with fresh eyes`
-                            : `the same failure ${seen} times - a debugger looks at it with fresh eyes`);
+                            : timedOut && seen < STUCK_ROUNDS
+                                ? `the unit testing script did not finish in ${Math.round(verdict.run.timeoutMs / 1000)}s - a debugger works out whether something hangs`
+                                : `the same failure ${seen} times - a debugger looks at it with fresh eyes`);
                         const found = await debugFailure({
                             buildDir,
                             failure: verdict.run.output,
                             times,
                             task: steeredChange() ?? codingText ?? changeText ?? options.diff ?? "",
                             script: verdict.script,
+                            run: verdict.run,
                             label: `${moduleName} spec change`,
                             ...(debuggerModel !== undefined ? { model: debuggerModel } : {}),
                             onDelta: options.onDelta,
                         }).catch(() => undefined);
+                        // Nothing hangs: the suite needs more time than a test run may take, and no agent can give it that.
+                        if (found?.tooSlow === true) {
+                            stage(`the unit testing script needs more than the ${Math.round(verdict.run.timeoutMs / 1000)}s a test run may take - stopping`);
+                            slow = timeLimitError(verdict.run, { moduleName, script: verdict.script, kind: "unit", reason: found.rootCause });
+                            return false;
+                        }
                         if (found !== undefined) {
                             const cause = found.rootCause.split("\n")[0].slice(0, 240);
                             reportActivity(`  the debugger: ${cause.slice(0, 160)}`);
@@ -486,6 +499,7 @@ export async function renderSpecDiff(options) {
                 ...(options.cases !== undefined ? { cases: options.cases } : {}),
                 label: `${moduleName} spec change`,
                 ...(scripts.runOn === "copy" ? { unitScript: scripts.unit } : {}),
+                testingScript: { path: relative(root, scripts.unit), content: readFileSync(scripts.unit, "utf8") },
                 model: options.judgeModel ?? modelSpec(inheritModel(configForSpec(tip.plainFile).judgeModel, modelOnly(options.model))),
                 send: async (next) => {
                     response = await ask(executor, next, options.onDelta);
@@ -543,13 +557,17 @@ export async function renderSpecDiff(options) {
         stage(unitReviewStopped ? "the unit tests pass but still leave the change untested - undoing the change" : "unit tests NOT passing - undoing the change");
         abandonWork(unit, moduleName, missing !== undefined
             ? "the unit testing script could not run"
-            : staticOnly
-                ? "the spec change did not pass its static checks"
-                : "the spec change did not pass its unit tests");
+            : slow !== undefined
+                ? "the unit testing script needs more time than a test run may take"
+                : staticOnly
+                    ? "the spec change did not pass its static checks"
+                    : "the spec change did not pass its unit tests");
         // The environment lacks what the testing script needs: the pulse stops, rolled back, and the person is told.
         if (missing !== undefined) {
             throw toolchainError(missing, { moduleName, script: scripts.unit, kind: "unit" });
         }
+        if (slow !== undefined)
+            throw slow;
         return { ...base, passed: false, stoppedAt: "unit tests", ...(staticOnly && !unitReviewStopped ? { staticChecks: true } : {}) };
     }
     stage("unit tests pass - landing the change on them");

package/dist/regenerate/requires.js

@@ -1,6 +1,6 @@
-import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, withParseCache } from "../plain/parser.js";
+import { IMPORT_DIRECTIVE, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata, withParseCache } from "../plain/parser.js";
 import { getFrids, getInheritedFunctionalSpecs } from "../plain/spec.js";
 import { buildDirUnder, modulesRoot, projectDirOf } from "./paths.js";
 import { notesPath } from "./notes.js";
@@ -54,6 +54,59 @@ options = {}) {
     visit(resolve(plainFile), []);
     return chain;
 }
+/** The .plain files that import `plainFile` - read from beside it, and, kept in a `template/` folder, from the folder it is in. */
+function importersOf(plainFile) {
+    const file = resolve(plainFile);
+    const dir = dirname(file);
+    const name = basename(file, PLAIN_SOURCE_FILE_EXTENSION);
+    const dirs = [dir, ...(basename(dir) === "template" ? [dirname(dir)] : [])];
+    return dirs.flatMap((at) => {
+        let names;
+        try {
+            names = readdirSync(at).filter((entry) => entry.endsWith(PLAIN_SOURCE_FILE_EXTENSION));
+        }
+        catch {
+            return [];
+        }
+        return names
+            .map((entry) => join(at, entry))
+            .filter((path) => {
+            if (path === file || !resolveTemplateDirs(path).includes(dir))
+                return false;
+            try {
+                return (readPlainSourceMetadata(readFileSync(path, "utf8")).metadata[IMPORT_DIRECTIVE] ?? []).includes(name);
+            }
+            catch {
+                return false;
+            }
+        });
+    });
+}
+/**
+ * Whether a .plain file is an import module - one a .plain file imports, or one kept in a `template/` folder - rather than
+ * a module of its own. It is no codebase: its reqs and definitions are built in the modules that import it.
+ */
+export function isImportModule(plainFile) {
+    return basename(dirname(resolve(plainFile))) === "template" || importersOf(plainFile).length > 0;
+}
+/** The modules of their own that import an import module, through any import modules between. */
+export function importingModules(plainFile) {
+    const found = new Set();
+    const seen = new Set();
+    const walk = (file) => {
+        if (seen.has(file))
+            return;
+        seen.add(file);
+        for (const importer of importersOf(file)) {
+            if (isImportModule(importer))
+                walk(importer);
+            else
+                found.add(importer);
+        }
+    };
+    walk(resolve(plainFile));
+    return [...found];
+}
 /**
  * The codebase a change to `plainFile`'s module lands in: the furthest-built module whose
  * requires chain includes it, with that chain.

package/dist/regenerate/stop-report.js

@@ -89,6 +89,19 @@ export function describeStop(facts) {
                 `though they were sent back for it again and again. Still missing:\n${facts.conformance.unlabelled.map((line) => `    - ${line}`).join("\n")}`;
         todo = ["If the test reqs leave open where the tests go or how they are built, say so exactly - the folder, the files, the build."];
     }
+    else if (facts.at === "conformance" && facts.conformance?.escalation !== undefined) {
+        const { error, reason, evidence, changedNothing } = facts.conformance.escalation;
+        why =
+            `its conformance tests kept failing with ${error}. The conformance agent's fix of the tests did not make it go away, so ` +
+                `a judge looked again and found it the code's; the coding agent ${changedNothing === true ? "changed nothing for it" : "fixed the code, and the run still failed the same way"}. ` +
+                `Why the judge found it the code's:\n${reason.trim().split("\n").map((line) => `    ${line}`).join("\n")}` +
+                (evidence.length > 0 ? `\n  On the evidence:\n${evidence.map((item) => `    - ${item.source.trim()}: ${item.shows.trim().replace(/\s+/g, " ")}`).join("\n")}` : "");
+        todo = [
+            "If the code has to produce something the spec leaves open - a build output, an entry point, a module the conformance testing " +
+                "script runs or checks for - say exactly what in the implementation reqs: its path and how it is built.",
+            "If the conformance testing script expects something the spec does not ask for, change the script or the test reqs so the two agree.",
+        ];
+    }
     else if (facts.at === "conformance" && facts.conformance?.stuck !== undefined) {
         const { error, times, rounds, changedNothing } = facts.conformance.stuck;
         why =

package/dist/regenerate/test-scripts.js

@@ -335,7 +335,15 @@ async function runScript(cwd, script, args, logDir, options = {}) {
     const noted = withScriptLineNote(text, script);
     // Its failures, counts and end are what the agent is shown; the whole is kept, a read_output away.
     const log = keepTestOutput(logDir, basename(script), noted);
-    return { command: shown(script), exitCode: timedOut === true ? 124 : exitCode, output: shownTestOutput(noted, log), timedOut: timedOut === true, timeoutMs, ...(log !== undefined ? { log } : {}) };
+    return {
+        command: shown(script),
+        exitCode: timedOut === true ? 124 : exitCode,
+        output: shownTestOutput(noted, log),
+        timedOut: timedOut === true,
+        timeoutMs,
+        elapsedMs: Date.now() - started,
+        ...(log !== undefined ? { log } : {}),
+    };
 }
 /** What bash says when a line of the script itself cannot run: a command or file that is not there, or not runnable. */
 const OWN_LINE_FAILURE = /: (No such file or directory|command not found|Permission denied)$/;
@@ -589,6 +597,19 @@ function loopNotice(loop) {
         "the failure with fresh eyes, and you will be given what it finds.",
     ].join("\n");
 }
+/**
+ * How long a run took against its time limit, in a line: for whoever judges it or works out its cause - so a run that
+ * ended on its own is never taken for one the limit stopped, nor the other way.
+ */
+export function runTiming(run) {
+    const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+    const limit = seconds(run.timeoutMs);
+    if (run.timedOut === true) {
+        return `The time limit stopped this run: it had run ${seconds(run.elapsedMs ?? run.timeoutMs)} of the ${limit} a test run may take, and had not finished.`;
+    }
+    const took = run.elapsedMs !== undefined ? `after ${seconds(run.elapsedMs)} of the ${limit} a test run may take` : `well within the ${limit} a test run may take`;
+    return `This run ended on its own - exit ${run.exitCode}, ${took}. The time limit did not stop it and played no part in how it ended.`;
+}
 /** A run the time limit stopped: failed, and what most often keeps a test run from ending. */
 function timedOutFailure(run, what) {
     const limit = Math.round(run.timeoutMs / 1000);

package/dist/regenerate/unit-review.js

@@ -63,6 +63,17 @@ export function unitReviewTask(options) {
         options.spec.trim(),
         "</specification>",
         "",
+        ...(options.testingScript !== undefined
+            ? [
+                "The harness runs the unit tests with this script, and it decides whether they pass. Read it for which tests it",
+                "runs and how: a test it never reaches - a file it does not pick up, a folder it does not look in - is not run, and",
+                "checks nothing.",
+                `<unit testing script path="${options.testingScript.path}">`,
+                options.testingScript.content.trimEnd(),
+                "</unit testing script>",
+                "",
+            ]
+            : []),
         ...(options.cases !== undefined ? [...codeReviewCasesBlock(options.cases), ""] : []),
         // A job that touches no functional spec is held only to that: the checks of behaviour are not its.
         ...(mechanical ? [] : ["Check that the code does what the specification states for this work:"]),