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

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,10 +85,82 @@ 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;
 }
+/**
+ * The functional specs of a spec's whole requires chain, completed or not, in the codebase each chain delivers: its
+ * furthest-built module's code - which holds the code of every module below it. A functional spec is completed when that
+ * codebase's code record, as last committed, holds it as the spec has it now - the same text, the linked files it uses
+ * holding the same, no definition it uses changed, not marked to regenerate again. A record moves only when a pulse
+ * lands, its unit tests passing (and its conformance tests, when they are on), so completed is landed and passing.
+ * The modules above the delivered codebase have nothing completed. One entry per chain; planning nothing, calling no model.
+ */
+export function functionalityCompletion(plainFile) {
+    return withParseCache(() => chainsFor(resolve(plainFile)).map((chain) => {
+        let delivered = -1;
+        chain.forEach((entry, index) => {
+            if (readRecord(entry.buildDir) !== null)
+                delivered = index;
+        });
+        const counts = chain.map((entry) => ({ module: entry.moduleName, specified: entry.frids.length, completed: 0, conformanceTested: 0, incomplete: [...entry.frids] }));
+        if (delivered === -1)
+            return { codebase: tipOf(chain).buildDir, modules: counts };
+        const codebase = chain.slice(0, delivered + 1);
+        const tip = tipOf(codebase);
+        const spec = chainSpec(codebase).tree;
+        const record = readRecord(tip.buildDir);
+        const changes = codeWork(record, spec);
+        // Its own: what the work loop would regenerate - new, changed, a concept it uses changed, or marked again.
+        const cases = casesOf(codeTree(record ?? {}), changes, { module: tip.moduleName });
+        const touched = new Set([...cases.add, ...cases.patch, ...cases.again].map((spec) => `${spec.module ?? tip.moduleName}:${spec.frid}`));
+        // The modules' below it: an item the record does not have as the spec has it.
+        for (const change of changes) {
+            if (change.section !== REQUIRED_FUNCTIONAL_SPECS || change.after === undefined)
+                continue;
+            try {
+                const item = JSON.parse(change.after);
+                if (item.module !== undefined && item.frid !== undefined)
+                    touched.add(`${item.module}:${item.frid}`);
+            }
+            catch {
+                /* not an item */
+            }
+        }
+        const specText = (module, frid) => {
+            const own = module === tip.moduleName;
+            const items = spec[own ? FUNCTIONAL_REQUIREMENTS : REQUIRED_FUNCTIONAL_SPECS] ?? [];
+            return (own ? items[Number(frid) - 1] : items.find((item) => item.module === module && item.frid === frid))?.markdown.trim();
+        };
+        codebase.forEach((entry, index) => {
+            const count = counts[index];
+            const completed = entry.frids.filter((frid) => !touched.has(`${entry.moduleName}:${frid}`));
+            const tested = (readRecord(conformanceDirFor(entry.moduleName, modulesRoot(projectDirOf(entry.plainFile))))?.[FUNCTIONAL_REQUIREMENTS] ?? []).filter((item) => item.frid !== undefined && item.markdown.trim() === specText(entry.moduleName, item.frid));
+            count.completed = completed.length;
+            count.conformanceTested = completed.filter((frid) => tested.some((item) => item.frid === frid)).length;
+            count.incomplete = entry.frids.filter((frid) => !completed.includes(frid));
+        });
+        return { codebase: tip.buildDir, modules: counts };
+    }));
+}
 /** The modules of a chain to build: its furthest-built one, and those above it - or, none built, all of it. */
 function toBuild(chain) {
     let from = 0;
@@ -434,7 +506,7 @@ export function createWorkLoop(options) {
             title: planned.title,
             diff: shown.diff,
             ...(state.model !== undefined ? { model: state.model } : {}),
-            lanes: [...moduleLanes(tip.plainFile, options.buildDir)],
+            lanes: [...moduleLanes(tip.plainFile)],
             rerun: `turri regenerate ${relative(options.cwd, tip.plainFile) || basename(tip.plainFile)}`,
             run: async (onDelta) => {
                 // The guardrail: a conformance job tests only code that is built - the code record, read as the job starts, has every functional spec it tests as it tests it.
@@ -934,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;
@@ -1313,7 +1386,6 @@ export async function previewJobs(options) {
         registry: createJobRegistry(),
         cwd: options.cwd,
         dryRun: true,
-        ...(options.buildDir !== undefined ? { buildDir: options.buildDir } : {}),
         ...(options.model !== undefined ? { modelFor: () => options.model } : {}),
         ...(options.plannerModel !== undefined ? { plannerModel: options.plannerModel } : {}),
         ...(options.steering !== undefined ? { steering: options.steering } : {}),

package/dist/regenerate/panel-dock.js

@@ -0,0 +1,86 @@
+import { HStack } from "@earendil-works/pi-tui";
+/**
+ * The side panel beside the chat rather than over it: the chat drawn on the left in what the panel leaves it, the panel
+ * laid over the columns on the right.
+ *
+ * pi draws its screen one of two ways, and the chat is narrowed in each as it is drawn: full screen (pi's default), a
+ * layout - its root put in a row beside a filler as wide as the panel; the regular screen, the lines its render gives -
+ * asked for in fewer columns.
+ */
+/** Narrower than this, the chat and the panel have no room side by side: the panel takes the whole screen. */
+const SHARED_FROM = 100;
+/** The columns the panel takes beside the chat: half the screen, the rule between them in the middle - 0 when the terminal is too narrow to share. */
+export function dockedWidth(columns) {
+    return columns < SHARED_FROM ? 0 : Math.floor(columns / 2);
+}
+/**
+ * The chat narrowed by `panelWidth()` columns, read at each frame - 0 gives it the whole width. Returns what gives it the
+ * whole width back for good.
+ */
+export function narrowChat(tui, panelWidth) {
+    const screen = tui;
+    if (typeof screen.setLayoutRoot === "function" && screen.layoutRoot !== undefined) {
+        const root = screen.layoutRoot;
+        // A line as wide as the panel: the row gives the filler what it measures, the chat the rest.
+        const filler = { render: () => [" ".repeat(panelWidth())], invalidate() { } };
+        screen.setLayoutRoot(new HStack([{ component: root, basis: 0, grow: 1 }, { component: filler }]));
+        return () => screen.setLayoutRoot(root);
+    }
+    // Read from the prototype: the screen's own render, not one laid over it.
+    const render = Object.getPrototypeOf(tui).render;
+    screen.render = function (width) {
+        return render.call(this, Math.max(1, width - panelWidth()));
+    };
+    return () => {
+        screen.render = render;
+    };
+}
+/**
+ * A press of a mouse button, as pi's full screen takes it - `side` told whether it was in the chat, left of `chatWidth()`
+ * columns, or in the panel - before the press goes on as it would have. Motion and the wheel are not presses. pi's
+ * regular screen reads no mouse: nothing is done there. Returns what takes the watch off.
+ */
+export function clickToFocus(tui, chatWidth, side) {
+    const screen = tui;
+    const handle = screen.handleMouseEvent;
+    if (typeof handle !== "function")
+        return () => { };
+    screen.handleMouseEvent = function (raw) {
+        // 32: motion; 64: the wheel.
+        if (raw.release !== true && (raw.button & (32 | 64)) === 0)
+            side(raw.x < chatWidth() ? "chat" : "panel");
+        return handle.call(this, raw);
+    };
+    return () => {
+        screen.handleMouseEvent = handle;
+    };
+}
+/**
+ * A line drawn faint - the side that does not have the keys, in the shade. Faint (SGR 2) holds through a line's colours;
+ * only a reset - SGR 0, or 22 - ends it, so it is set again after each one. A line holding an image is left as it is.
+ */
+export function shade(line) {
+    // Kitty's image escape, or iTerm2's.
+    if (line.includes("\x1b_G") || line.includes("\x1b]1337;File="))
+        return line;
+    const again = line.replace(/\x1b\[([\d;]*)m/g, (sgr, params) => (params.split(";").some((param) => param === "" || param === "0" || param === "22") ? `${sgr}${FAINT}` : sgr));
+    return `${FAINT}${again}${NOT_FAINT}`;
+}
+const FAINT = "\x1b[2m";
+const NOT_FAINT = "\x1b[22m";
+/**
+ * The chat in the shade while `shaded()`: each of its rows drawn faint as the screen lays the overlays over it - the
+ * docked panel the last of them, which covers its own columns. Returns what takes the shade off.
+ */
+export function shadeChat(tui, shaded) {
+    const screen = tui;
+    const composite = screen.compositeLineAt;
+    if (typeof composite !== "function")
+        return () => { };
+    screen.compositeLineAt = function (base, overlay, col, width, total) {
+        return composite.call(this, shaded() ? shade(base) : base, overlay, col, width, total);
+    };
+    return () => {
+        screen.compositeLineAt = composite;
+    };
+}

package/dist/regenerate/prompt.js

@@ -24,7 +24,7 @@ function alreadyImplemented(moduleName, own, required) {
  * one another, the current module marked - and each tagged with its module and its id there. A codebase holds the
  * functionalities of every module it is built on, and each module numbers its own from 1, so
  * "functionality 1" alone is ambiguous: the first listed may be base's 1 and the next top's 3.
- * (plain2code's _get_implemented_functional_requirements_prompt_section, as tags.)
+ * (the reference implementation's implemented functional requirements prompt section, as tags.)
  */
 export function functionalitiesByModule(entries, currentModule, status) {
     // In the order given: the bottom of the chain first. A regeneration in a later module's
@@ -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/release.js

@@ -1,5 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { connect } from "node:net";
 import { dirname, join, relative } from "node:path";
 import { HISTORY_DIR } from "./lineage.js";
@@ -38,15 +38,17 @@ export function deployTarget(plainFile, inModule) {
     throw new Error(`Nothing is built yet for ${tip.moduleName}${candidates.length > 1 ? " or the modules it requires" : ""}: there is no code to deploy. Render it first.`);
 }
 /**
- * Export the module's code at its last commit into `dist/<module>`, replacing whatever was there - the
- * harness's own files (what the code is built from, the agents' notes) left out.
+ * Export the module's code at its last commit into `dist/<module>` - or `into`, `turri regenerate --build-dir` -
+ * replacing whatever was there, the harness's own files (what the code is built from, the agents' notes) left out.
  */
-export function exportModule(plainFile, inModule) {
+export function exportModule(plainFile, inModule, into) {
     const { entry, commit, instead } = deployTarget(plainFile, inModule);
     const moduleDir = dirname(entry.buildDir);
-    const dir = distDirFor(projectDirOf(entry.plainFile), entry.moduleName);
-    rmSync(dir, { recursive: true, force: true });
+    const dir = into ?? distDirFor(projectDirOf(entry.plainFile), entry.moduleName);
+    // Emptied, not removed: the folder may be a mount point - a container's volume - that cannot be removed.
     mkdirSync(dir, { recursive: true });
+    for (const entry of readdirSync(dir))
+        rmSync(join(dir, entry), { recursive: true, force: true });
     const exported = spawnSync("bash", ["-o", "pipefail", "-c", 'git --git-dir "$1" archive --format=tar "$2" | tar -x -f - -C "$3"', "export", join(moduleDir, HISTORY_DIR), `${commit}:code`, dir], { encoding: "utf8" });
     if (exported.status !== 0)
         throw new Error(`Could not export ${entry.moduleName}'s code at ${commit.slice(0, 8)}: ${(exported.stderr ?? "").trim()}`);

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.