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

package/dist/regenerate/notes.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { reportActivity } from "./activity.js";
@@ -40,7 +40,6 @@ export const SECTIONS = {
     where: "Where things are",
     run: "How to build, run and test",
     assumptions: "Assumptions",
-    gaps: "Spec gaps",
     pitfalls: "Pitfalls",
     pulses: "Pulses",
 };
@@ -53,8 +52,13 @@ export function notesPath(buildDir) {
     return join(buildDir, NOTES_FILE);
 }
 function empty() {
-    return { where: [], run: [], assumptions: [], gaps: [], pitfalls: [], pulses: [] };
+    return { where: [], run: [], assumptions: [], pitfalls: [], pulses: [] };
 }
+/**
+ * Sections the notes no longer have, their lines dropped as they are read: the spec gaps are the person's, reported
+ * with report_spec_gap - the choice made meanwhile is an assumption, which stays.
+ */
+const DROPPED = new Set(["spec gaps"]);
 /** The notes, as lines per section. Lines under no known heading go to pitfalls, not lost. */
 export function parseNotes(text) {
     const notes = empty();
@@ -63,11 +67,12 @@ export function parseNotes(text) {
         const line = raw.trim();
         const heading = /^##\s+(.+)$/.exec(line);
         if (heading) {
-            section = ORDER.find((key) => SECTIONS[key].toLowerCase() === heading[1].trim().toLowerCase()) ?? section;
+            const named = heading[1].trim().toLowerCase();
+            section = DROPPED.has(named) ? undefined : (ORDER.find((key) => SECTIONS[key].toLowerCase() === named) ?? section ?? "pitfalls");
             continue;
         }
         const item = /^[-*]\s+(.+)$/.exec(line);
-        if (item)
+        if (item && section !== undefined)
             notes[section].push(item[1].trim());
     }
     return notes;
@@ -93,14 +98,14 @@ const GUIDANCE = [
     `- ${SECTIONS.where}: entry points, layout, where each functionality and its tests live.`,
     `- ${SECTIONS.run}: the commands that build, run and test it, and what had to be installed for them.`,
     `- ${SECTIONS.assumptions}: what you assumed where the specification is silent - a format, a default, a`,
-    "  choice it leaves open. Build on the assumptions already there; change or remove one the moment the code",
-    "  or the specification shows it wrong.",
-    `- ${SECTIONS.gaps}: what the specification should say and does not - a behaviour you had to decide that the`,
-    "  person would want to decide, not a detail of how. Each is put to the person, to be written into the",
-    "  specification. One a line, as the question it leaves: \"What happens to a contact archived in HubSpot after it",
-    "  was synced?\"",
+    "  choice it leaves open - and the tests that assert it, when any do: \"A Dash drains Pulses at 1/s - asserted in",
+    "  predators.test.ts, The Dash\". One no test asserts is written down all the same. Build on the assumptions",
+    "  already there; change or remove one the moment the code or the specification shows it wrong - and the tests",
+    "  it names with it.",
     `- ${SECTIONS.pitfalls}: what went wrong and what fixed it, approaches that did not work.`,
     `- ${SECTIONS.pulses}: written by turri as each pulse ends - read them, never write them.`,
+    "A behaviour you had to decide that the person would want to decide - not a detail of how - is not a note: report",
+    "it with report_spec_gap, with the assumption you made meanwhile.",
     "Each line stands on its own, for someone who never saw your work. When and where it came from is added",
     "to it for you - do not write it. Where two lines disagree, the later one is right: change the older one",
     'rather than add a contradicting line. Leave a section with nothing new alone: "none" is not a note.',
@@ -232,7 +237,7 @@ export function createNotesTool(buildDir, onWrite, before = () => { }, source) {
         label: "Update notes",
         description: "Update the working notes on this codebase for the next agent - add a line, change one that is no longer " +
             "true, remove one that is wrong - in its sections: where things are, how to build, run and test, " +
-            "assumptions made where the specification is silent, spec gaps the person should decide, and pitfalls. Never " +
+            "assumptions made where the specification is silent, and pitfalls. Never " +
             "requirements: the specification is never an assumption.",
         promptSnippet: "leave the next agent what you learned and assumed about this codebase",
         parameters: Type.Object({
@@ -283,7 +288,7 @@ export function sectionNamed(name) {
 /** How many times an agent that finishes without update_notes is asked to call it. */
 export const NOTES_ASKS = 3;
 /** The turn that asks for the notes: update_notes is the only tool it may use - the work it follows is done. */
-export const NOTES_TURN = { onlyTools: ["update_notes"] };
+export const NOTES_TURN = { onlyTools: ["update_notes", "report_spec_gap"] };
 /** What the notes turn says first, once the harness's own run of `script` has passed on the work. */
 export function passedOutcome(script) {
     return (`The harness ran the project's ${script} on your work itself, and it passed: your work is done and accepted. ` +
@@ -327,10 +332,53 @@ export function recordPulse(buildDir, text, source) {
         // The notes are a help, not the work.
     }
 }
-/** The lines of a section added since `before` - a pulse's new spec gaps, say - without when and where they came from. */
-export function linesAddedSince(before, buildDir, section) {
-    const known = new Set(before[section]);
-    return readNotes(buildDir)[section].filter((line) => !known.has(line)).map((line) => line.replace(/^\[[^\]]*\]\s*/, ""));
+/** Every spec gap reported in this process, with the codebase it was met in: a pulse reads those since it started. */
+const reportedGaps = [];
+/** Where the spec gaps stand now: what `gapsSince` reads from. */
+export function gapMark() {
+    return reportedGaps.length;
+}
+/** The spec gaps reported in these codebases since `mark`. */
+export function gapsSince(mark, dirs) {
+    const wanted = new Set(dirs.map((dir) => resolve(dir)));
+    return reportedGaps.slice(mark).filter((entry) => wanted.has(entry.dir)).map((entry) => entry.gap);
+}
+/**
+ * `report_spec_gap`: a behaviour the specification leaves open that the person would want to decide, put to them as
+ * the pulse ends - never into the notes, which are the next agent's. What the agent decided meanwhile goes into the
+ * notes' assumptions, so the code built on it is known for what it is until the specification settles it.
+ */
+export function createSpecGapTool(buildDir, source) {
+    return defineTool({
+        name: "report_spec_gap",
+        label: "Report a spec gap",
+        description: "Report a spec gap: a behaviour the specification leaves open that the person would want to decide - not a detail " +
+            "of how. Decide it meanwhile and carry on: the person is asked once the work ends, and what they decide is " +
+            "written into the specification. The assumption you made is added to the notes' assumptions for you.",
+        promptSnippet: "tell the person about a behaviour the specification leaves open, and what you decided meanwhile",
+        parameters: Type.Object({
+            question: Type.String({ description: 'The question it leaves the person, one line: "What happens to a contact archived in HubSpot after it was synced?"' }),
+            assumption: Type.String({
+                description: "What you decided meanwhile, as its line in the notes' assumptions - with the tests that assert it, when any do: " +
+                    '"An archived contact is left as synced - asserted in sync.test.ts, archived contacts".',
+            }),
+        }),
+        async execute(_id, params) {
+            const question = params.question.replace(/\s+/g, " ").trim();
+            const assumption = params.assumption.replace(/\s+/g, " ").trim();
+            if (question === "" || assumption === "")
+                throw new Error("Nothing reported - a spec gap needs both the question it leaves and the assumption you made meanwhile.");
+            // However many there are, spec gaps are put to the person - never a reason to stop the pulse.
+            reportedGaps.push({ dir: resolve(buildDir), gap: { question, assumption } });
+            const known = readNotes(buildDir).assumptions.some((line) => body(line) === assumption);
+            if (!known)
+                recordNote(buildDir, "assumptions", assumption, source ?? "spec gap");
+            return {
+                content: [{ type: "text", text: `Reported. The assumption is in the notes' assumptions${known ? " already" : " now"} - do not add it again.` }],
+                details: { question, assumption },
+            };
+        },
+    });
 }
 /** The notes, for an agent that reads them but leaves none - a judge. Empty when there are none. */
 export function notesToRead(buildDir) {
@@ -367,6 +415,7 @@ export function notesForSession(buildDir, source) {
         return true;
     };
     return {
+        gapTool: createSpecGapTool(buildDir, source),
         tool: createNotesTool(buildDir, (text) => {
             written = true;
             knownNotes.set(file, text);

package/dist/regenerate/panel-dock.js

@@ -9,9 +9,9 @@ import { HStack } from "@earendil-works/pi-tui";
  */
 /** 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 - 0 when the terminal is too narrow to share. */
+/** 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.max(48, Math.floor(columns * 0.45));
+    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
@@ -55,3 +55,32 @@ export function clickToFocus(tui, chatWidth, side) {
         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

@@ -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

@@ -14,13 +14,13 @@ import { buildSpecDiffPrompt, describeSpecChange, reviewedSpec, sectionModules }
 import { abandonWork, recordHistory, startWork } from "./lineage.js";
 import { createWorkLedger, SUBMIT_WORK_NOTE } from "./submit-work.js";
 import { CODER_COMPACTION } from "./compaction.js";
-import { linesAddedSince, NOTES_TURN, notesForSession, passedOutcome, readNotes, recordNote, withNotes } from "./notes.js";
+import { gapMark, gapsSince, NOTES_TURN, notesForSession, passedOutcome, recordNote, withNotes } from "./notes.js";
 import { createLoopWatch, createScriptTool, failureSignature, findTestScripts, projectRootFor, requireTestScripts, runUnitScript, STUCK_ROUNDS, withoutConformance, withTestingScripts, } from "./test-scripts.js";
 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";
@@ -268,8 +268,8 @@ export async function renderSpecDiff(options) {
         ...(options.cases !== undefined ? { cases: options.cases } : {}),
     });
     const digestsBefore = digestFiles(buildDir);
-    // The notes as the agent finds them: what it adds - a spec gap above all - is told with the result.
-    const notesBefore = readNotes(buildDir);
+    // The spec gaps its agents report from here on are told with the result.
+    const gapsFrom = gapMark();
     /** What the debugger found, each time it was asked: the pulse's line in the notes says it. */
     const diagnosed = [];
     const runs = [];
@@ -305,6 +305,7 @@ export async function renderSpecDiff(options) {
         cwd: buildDir,
         customTools: [
             notes.tool,
+            notes.gapTool,
             work.tool,
             ...createWebTools(),
             createScriptTool({ kind: "unit", script: scripts.unit, run: () => runUnitScript(buildDir, scripts.unit), runs, watch: loop }),
@@ -313,7 +314,7 @@ export async function renderSpecDiff(options) {
             ...fence.tools,
             createCopyResourceTool({ resources: linkedResources, dir: buildDir }),
         ],
-        tools: [...fence.names, "run_unit_tests", ...selfChecks.map((tool) => tool.name), ...services.names, "update_notes", "submit_work", "copy_resource", ...WEB_TOOLS],
+        tools: [...fence.names, "run_unit_tests", ...selfChecks.map((tool) => tool.name), ...services.names, "update_notes", "report_spec_gap", "submit_work", "copy_resource", ...WEB_TOOLS],
         model: options.model,
         label: `${moduleName} spec change coding agent`,
         role: "coding",
@@ -333,6 +334,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 +426,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 +500,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);
@@ -528,8 +543,8 @@ export async function renderSpecDiff(options) {
         testRemovals,
         files,
         ...(steering !== undefined && steering.steers > 0 ? { steered: [...steering.notes] } : {}),
-        // Read before a rollback takes the notes back: a gap the agent met is the person's to decide, whether it landed or not.
-        specGaps: linesAddedSince(notesBefore, buildDir, "gaps"),
+        // A gap the agent met is the person's to decide, whether it landed or not.
+        specGaps: gapsSince(gapsFrom, [buildDir]),
         diagnosed,
     };
     /** The change landed: what the code is built from is now the spec with the change in, committed with it. */
@@ -543,13 +558,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");
@@ -562,8 +581,10 @@ export function specGapsText(gaps) {
         return [];
     return [
         "",
-        "Spec gaps its agents met - the spec does not say, so they decided. Put each to the user, and write the ones they decide into the spec:",
-        ...gaps.map((gap) => `- ${gap}`),
+        "Spec gaps its agents met - the spec does not say, so they decided, each as an assumption in the codebase's notes. Put " +
+            "each to the user, and write the ones they decide into the spec - the pulse that builds it is told the assumption " +
+            "it replaces:",
+        ...gaps.map((gap) => `- ${gap.question} Meanwhile: ${gap.assumption}`),
     ];
 }
 /** What a rendered spec change did, for the agent and the person. */

package/dist/regenerate/regression.js

@@ -21,7 +21,7 @@ import { keepingTestsUnchanged, listFiles } from "./testing.js";
  * job ends on it: tests that pass on their own are not done until the whole suite passes with them.
  */
 /** On top of the file tools, which are fenced to the build directory by `confine.ts`. */
-const FIX_TOOLS = ["run_unit_tests", "run_conformance_tests", "update_notes"];
+const FIX_TOOLS = ["run_unit_tests", "run_conformance_tests", "update_notes", "report_spec_gap"];
 const DEFAULT_MAX_REGRESSION_ROUNDS = ATTEMPTS.regression;
 /** The module's conformance tests, when there are any: the chain's, copied up, and its own. */
 function conformanceDirs(conformanceRoot, moduleName) {
@@ -39,6 +39,7 @@ async function repairRegression(input) {
         cwd: input.buildDir,
         customTools: [
             notes.tool,
+            notes.gapTool,
             ...createWebTools(),
             ...fence.tools,
             createScriptTool({ kind: "unit", script: input.scripts.unit, run: () => runUnitScript(input.buildDir, input.scripts.unit), runs }),

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/side-panel.js

@@ -16,7 +16,7 @@ export function createSidePanel(options) {
     const backKeys = () => {
         if (options.dock === undefined)
             return [`esc or ${options.key} back to the chat`];
-        return options.dock.docked() ? ["s full screen", "esc to the chat", `${options.key} close`] : ["s beside the chat", `esc or ${options.key} back to the chat`];
+        return options.dock.docked() ? ["s full screen", "esc or ⌥⌘← to the chat", `${options.key} close`] : ["s beside the chat", `esc or ${options.key} back to the chat`];
     };
     const waitingNote = () => 
     // A question asked while it showed waits in the chat, unanswered: the person is told it is there.

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:"]),

package/dist/regenerate-cli.js

@@ -19,7 +19,7 @@ its conformance tests too when they are on.
   --start-over             start over, without asking, a codebase regenerated without a module it now requires -
                            with no terminal to ask and without it, the run stops there
   --from-scratch           delete the module's code and conformance tests (its lineage keeps them) and regenerate all of it
-  --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner, the conformance chooser, a diagnosis
+  --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner and the conformance chooser
   --coding-model <p/id>    its coding-model, --model too: the agents that build; p/id:level for how hard a model thinks
   --judge-model <p/id>     its judge-model: the judge and the test review
   --review <true|false>    its review: whether the code and its tests are reviewed once they pass

package/dist/resume-line.js

@@ -0,0 +1,4 @@
+/** pi's line on the way out that says how to resume the session, with turri in place of pi as the command to run. */
+export function resumeLine(text) {
+    return text.replace(/^((?:\x1b\[[0-9;]*m)*To resume this session:(?:\x1b\[[0-9;]*m)*\s+)pi(?= )/m, "$1turri");
+}

package/dist/spec-tools.js

@@ -1,8 +1,8 @@
-import { readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, relative, resolve } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { IMPORT_DIRECTIVE, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata } from "./plain/parser.js";
+import { plainFileParser } from "./plain/parser.js";
+import { importingModules, isImportModule } from "./regenerate/requires.js";
 import { resolveTemplateDirs } from "./regenerate/paths.js";
 import { applySpecDiff, plainFilesOf, revertSpecDiff } from "./regenerate/regenerate.js";
 import { MissingFunctionalitiesError } from "./plain/errors.js";
@@ -62,24 +62,12 @@ export function createSpecDiffTools(options) {
             // file that cannot be parsed. A module with no functional specs yet is not broken. An import
             // module - definitions only, say - is not a module of its own: it is parsed as the modules
             // that import it read it, the one the change is built for among them.
-            const importers = (file) => {
-                const name = basename(file, ".plain");
-                const dir = dirname(resolve(cwd, file));
-                return readdirSync(dir)
-                    .filter((entry) => entry.endsWith(".plain"))
-                    .map((entry) => join(dir, entry))
-                    .filter((path) => {
-                    try {
-                        return (readPlainSourceMetadata(readFileSync(path, "utf8")).metadata[IMPORT_DIRECTIVE] ?? []).includes(name);
-                    }
-                    catch {
-                        return false;
-                    }
-                });
-            };
-            const imported = importedNames(resolveTemplateDirs(resolve(cwd, params.plain_file)));
             const toParse = [
-                ...new Set([params.plain_file, ...touched].flatMap((file) => imported.has(basename(file, ".plain")) ? importers(file).filter((path) => !imported.has(basename(path, ".plain"))) : [resolve(cwd, file)])),
+                ...new Set([params.plain_file, ...touched].flatMap((file) => {
+                    const path = resolve(cwd, file);
+                    const importing = isImportModule(path) ? importingModules(path) : [];
+                    return importing.length > 0 ? importing : [path];
+                })),
             ];
             for (const path of toParse) {
                 const file = relative(cwd, path);
@@ -129,27 +117,3 @@ export function createSpecDiffTools(options) {
         },
     };
 }
-/** The module names some .plain file in these folders imports: import modules, not codebases. */
-export function importedNames(dirs) {
-    const names = new Set();
-    for (const dir of dirs) {
-        let entries;
-        try {
-            entries = readdirSync(dir).filter((name) => name.endsWith(PLAIN_SOURCE_FILE_EXTENSION));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            try {
-                const imports = readPlainSourceMetadata(readFileSync(join(dir, entry), "utf8")).metadata[IMPORT_DIRECTIVE];
-                for (const name of imports ?? [])
-                    names.add(name);
-            }
-            catch {
-                // A file that does not read imports nothing.
-            }
-        }
-    }
-    return names;
-}