@turri-dev/cli 0.1.3-next.2babf06 → 0.1.3-next.420ce7e

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 });
@@ -267,6 +278,7 @@ export async function renderConformanceTests(options) {
         cwd: conformanceDir,
         customTools: [
             notes.tool,
+            notes.gapTool,
             work.tool,
             ...createWebTools(),
             ...fence.tools,
@@ -280,7 +292,7 @@ export async function renderConformanceTests(options) {
             }),
             createCopyResourceTool({ resources: linkedResources, dir: conformanceDir }),
         ],
-        tools: [...fence.names, "run_conformance_tests", "my_diff", "ask_explorer", "update_notes", "submit_work", "copy_resource", ...WEB_TOOLS],
+        tools: [...fence.names, "run_conformance_tests", "my_diff", "ask_explorer", "update_notes", "report_spec_gap", "submit_work", "copy_resource", ...WEB_TOOLS],
         model: options.model,
         label: `${label} conformance agent`,
         role: "conformance",
@@ -308,12 +320,14 @@ export async function renderConformanceTests(options) {
             // The unit tests, and the conformance suite - to reproduce the failure and check the fix, seeing only its output.
             tools: [
                 fixerNotes.tool,
+                fixerNotes.gapTool,
                 createScriptTool({ kind: "unit", script: scripts.unit, run: () => runUnitScript(buildDir, scripts.unit), runs: unitRuns }),
                 fixerConformanceRuns.tool,
                 ...fixerServices.tools,
             ],
-            toolNames: ["run_unit_tests", "run_conformance_tests", ...fixerServices.names, "update_notes"],
+            toolNames: ["run_unit_tests", "run_conformance_tests", ...fixerServices.names, "update_notes", "report_spec_gap"],
             checkEnvironment: { run: () => runUnitScript(buildDir, scripts.unit), script: scripts.unit },
+            testingScripts: { scripts, root },
         });
         fixerConformanceRuns.newTurn();
         return ask(fixer, withNotes(text, buildDir), options.onDelta);
@@ -414,6 +428,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 +503,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 +514,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 +529,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 +612,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 +659,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 +696,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 +822,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 +956,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 +967,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

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, sep } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -35,7 +36,7 @@ export class EnvironmentError extends Error {
     sandbox;
     constructor(details) {
         super(details.sandbox !== undefined
-            ? `${details.moduleName} stopped: turri's sandbox kept its agents from ${details.sandbox.paths[0]}, which is on this machine.`
+            ? `${details.moduleName} stopped: turri's sandbox kept its agents from ${details.sandbox.access === "write" ? "writing" : "reading"} ${details.sandbox.paths[0]}, which is on this machine.`
             : `${details.moduleName} stopped: the environment lacks ${details.missing}.`);
         this.name = "EnvironmentError";
         this.moduleName = details.moduleName;
@@ -50,6 +51,10 @@ export class EnvironmentError extends Error {
             this.sandbox = details.sandbox;
     }
 }
+/** A file's name that says it is a lock: `lockfile`, `x.lock`, `x.lck`, `.lock-x`, `x.lock.y`. */
+const LOCK_FILE = /(?:^|[._-])(?:lock|lck|lockfile)(?:$|[._-])/i;
+/** What says the sandbox refused a write, not a read: writing, creating, a lock not taken - not a name with "lock" in it. */
+const WRITE_REFUSED = /\b(?:writ(?:e|es|ing|able)|creat(?:e|es|ing)|acquir(?:e|ing)|(?:take|obtain|get) (?:a |the )?lock|locking|read-only file system)\b/i;
 /** A folder named for a version - `24.16.0`, `v22.3.0`, `3.12.4` - the root of a version manager's install. */
 const VERSION = /^v?\d+\.\d+/;
 /** The parts of an install below its root, where the root ends: `…/24.16.0/lib/node_modules/…` ends before `lib`. */
@@ -74,27 +79,59 @@ export function sandboxGapOf(text, options = {}) {
     const system = (options.platform ?? process.platform) === "darwin" ? MACOS_MACHINE : LINUX_MACHINE;
     const within = (path, root) => path === root || path.startsWith(`${root}/`);
     const named = [...text.matchAll(/(?:^|[\s'"`(=:])(\/[^\s'"`()<>,;]+)/g)].map((match) => match[1].replace(/[.:]+$/, ""));
-    const paths = [...new Set(named)].filter((path) => path.split("/").length > 3 && exists(path) && !system.some((root) => within(path, root)) && (options.project === undefined || !within(path, options.project)));
-    return paths.length > 0 ? { paths, folder: toolchainFolder(paths[0]) } : undefined;
+    const isLock = (path) => LOCK_FILE.test(basename(path));
+    // A lock file the tool could not create is not there: its folder is.
+    const found = [...new Set(named)].filter((path) => path.split("/").length > 3 &&
+        (exists(path) || (isLock(path) && exists(dirname(path)))) &&
+        !system.some((root) => within(path, root)) &&
+        (options.project === undefined || !within(path, options.project)));
+    if (found.length === 0)
+        return undefined;
+    // The lock first: it is what the build could not take.
+    const paths = [...found.filter(isLock), ...found.filter((path) => !isLock(path))];
+    const lock = isLock(paths[0]);
+    return { paths, folder: toolchainFolder(paths[0]), access: lock || WRITE_REFUSED.test(text) ? "write" : "read", ...(lock ? { lock } : {}) };
 }
 /**
  * What the person is told, in the chat, at the end of `turri regenerate`, and in the job's log. `rerun`: the command that runs
  * the work again, as the pulse knows it - the spec the person ran; without it, the module's own spec by its name.
  */
 export function describeEnvironmentError(error, rerun) {
-    if (error.sandbox !== undefined) {
+    const again = `Then re-run: \`${rerun ?? `turri regenerate ${error.moduleName}.plain`}\`, or say "resume" in the chat.`;
+    const needed = `Needed by: ${error.neededBy}${error.shownBy !== undefined ? ` (${error.shownBy})` : ""}.`;
+    const gap = error.sandbox;
+    if (gap?.access === "write") {
+        const what = gap.lock === true ? `the lock file \`${gap.paths[0]}\`, which the build takes as it runs` : `\`${gap.paths[0]}\``;
+        const home = homedir();
+        const inHome = gap.paths[0] === home || gap.paths[0].startsWith(`${home}/`);
         return [
-            `**${error.moduleName} stopped: turri's sandbox kept its agents from reading \`${error.sandbox.paths[0]}\` - it is on this machine; nothing is missing.**`,
-            `Needed by: ${error.neededBy}${error.shownBy !== undefined ? ` (${error.shownBy})` : ""}.`,
-            `To fix: let the agents read that toolchain - add its folder to \`toolchains:\` in config.yaml, keeping what is there: \`toolchains: [${error.sandbox.folder}]\`. Nothing needs installing.`,
-            `Then re-run: \`${rerun ?? `turri regenerate ${error.moduleName}.plain`}\`, or say "resume" in the chat.`,
+            `**${error.moduleName} stopped: turri's sandbox kept its agents from writing ${what} - it is on this machine; nothing is missing, and nothing needs installing.**`,
+            needed,
+            "An agent's commands write only their module's folders, their own home and temporary folder, and the package caches turri " +
+                "points the build tools at - no setting lets them write anywhere else, and `toolchains:` lets them read a folder, not write it.",
+            inHome
+                ? "To fix: it is in your home, not the agents' own - the tool found your home without `$HOME`, as a JVM does for `user.home`, " +
+                    "or a setting of yours points it there. Have it use `$HOME` instead - for a JVM tool, `-Duser.home=$HOME` where the build " +
+                    "starts its JVM - and the agents' own home takes it."
+                : `To fix: it is in a toolchain's own install, \`${gap.folder}\`, which the build writes into as it runs - and the agents may ` +
+                    "not change a toolchain. Have the build keep it elsewhere if the tool has a setting for it, or install a copy of the " +
+                    "toolchain that keeps its writes in its cache.",
+            again,
+        ].join("\n");
+    }
+    if (gap !== undefined) {
+        return [
+            `**${error.moduleName} stopped: turri's sandbox kept its agents from reading \`${gap.paths[0]}\` - it is on this machine; nothing is missing.**`,
+            needed,
+            `To fix: let the agents read that toolchain - add its folder to \`toolchains:\` in config.turri.yaml, keeping what is there: \`toolchains: [${gap.folder}]\`. Nothing needs installing.`,
+            again,
         ].join("\n");
     }
     return [
         `**${error.moduleName} stopped: the environment lacks ${error.missing}.**`,
         `Needed by: ${error.neededBy}${error.shownBy !== undefined ? ` (${error.shownBy})` : ""}.`,
         `To fix: ${error.fix ?? "provide it on this machine, then run it again."}`,
-        `Then re-run: \`${rerun ?? `turri regenerate ${error.moduleName}.plain`}\`, or say "resume" in the chat.`,
+        again,
     ].join("\n");
 }
 /** The name agents know the tool by - their wall text names it. */
@@ -187,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;