@turri-dev/cli 0.1.3-next.79e2ad0 → 0.1.3-next.e5599c1

package/dist/regenerate/conformance-agents.js

@@ -659,15 +659,28 @@ function words(text) {
  * in the specification - or when it hides why the software failed. A test asserting what the
  * specification leaves open is the test's mistake, however plausible the assertion.
  */
-export function unfoundedCodeVerdict(verdict, specText) {
+export function unfoundedCodeVerdict(verdict, specText, scriptText) {
     if (verdict.causeHidden === true)
         return undefined;
+    // What the conformance testing script needs of the build - a file, an entry point, a module - binds the code as the
+    // specification does: neither agent can change the script. Its own words, as they are in it.
+    const needs = verdict.scriptNeeds?.trim() ?? "";
+    if (needs !== "" && scriptText !== undefined) {
+        const flat = (text) => text.replace(/\s+/g, " ");
+        if (flat(needs).length >= 4 && flat(scriptText).includes(flat(needs)))
+            return undefined;
+        if (verdict.specSays === undefined) {
+            return (`Your verdict blames the code for what the conformance testing script needs, but "${needs}" is not in the script. ` +
+                "Call submit_verdict again: copy into script_needs the script's own words for what it needs of the build, exactly as they are in it.");
+        }
+    }
     const quote = verdict.specSays?.trim() ?? "";
     if (quote === "") {
         return ("Your verdict blames the code, but quotes no words of the specification it does not meet. Call submit_verdict " +
             "again: for code, put the specification's own words the code does not meet in spec_says, copied exactly from " +
-            "<specification>; or set cause_hidden when the output does not show why the software failed. If the specification " +
-            "does not say what the failing test asserts, the test is what is wrong: culprit tests.");
+            "<specification>; or, when the run fails on something the conformance testing script needs the build to have, " +
+            "its own words in script_needs; or set cause_hidden when the output does not show why the software failed. If " +
+            "the specification does not say what the failing test asserts, the test is what is wrong: culprit tests.");
     }
     const quoted = words(quote);
     if (quoted.trim().split(" ").length < 4 || !words(specText).includes(quoted)) {
@@ -677,6 +690,31 @@ export function unfoundedCodeVerdict(verdict, specText) {
     }
     return undefined;
 }
+/**
+ * Why a verdict's evidence cannot be taken as it is, or nothing when it can. Asked to weigh an escalation, the judge has
+ * to rest its verdict on what it found itself: each piece of evidence from a file it opened, the testing script or the
+ * failing run - and at least one not the run alone, which every judge before it read too. What the explorer's account
+ * says is not evidence: it was written before the run, and may be wrong.
+ */
+export function unfoundedEvidence(evidence, opened) {
+    const given = (evidence ?? []).filter((item) => item.source.trim() !== "" && item.shows.trim() !== "");
+    if (given.length === 0) {
+        return ("Your verdict gives no evidence. Call submit_verdict again with `evidence`: what you found yourself - in a file you " +
+            "opened, the testing script, or the failing run - each with where. What <how to invoke it> says is not evidence: it " +
+            "may be wrong, so check it against the testing script and the files.");
+    }
+    const inPrompt = (source) => /^(the )?(conformance )?testing script$|^(the )?failing run$/i.test(source.trim());
+    const unread = given.filter((item) => !inPrompt(item.source) && !opened(item.source.trim()));
+    if (unread.length > 0) {
+        return (`Your evidence cites ${unread.map((item) => item.source.trim()).join(", ")}, which you did not open. Open each file you cite ` +
+            "and call submit_verdict again - evidence is what you found yourself, never what <how to invoke it> says.");
+    }
+    if (given.every((item) => /failing run$/i.test(item.source.trim()))) {
+        return ("Your evidence is only the failing run, which the judges before you read too. Check what it points at - the testing " +
+            "script, the code, the tests - and call submit_verdict again with what you found there.");
+    }
+    return undefined;
+}
 export async function judgeFailure(options) {
     let verdict;
     const submit = defineTool({
@@ -692,6 +730,13 @@ export async function judgeFailure(options) {
                 description: "For code: the specification's own words the code does not meet, copied exactly from <specification> - the sentence, or the part of it that says what the test checks",
             })),
             cause_hidden: Type.Optional(Type.Boolean({ description: "For code: true when it is wrong because the output does not show why the software failed - it hides the cause" })),
+            script_needs: Type.Optional(Type.String({
+                description: "For code: the conformance testing script's own words for what it needs the build to have - the file, entry point or module the run failed on - copied exactly from the script",
+            })),
+            evidence: Type.Optional(Type.Array(Type.Object({
+                source: Type.String({ description: "Where: the path of a file you opened, `testing script`, or `failing run`" }),
+                shows: Type.String({ description: "What it shows, e.g. `the script runs node dist/cli.js` or `tsconfig.json emits src/cli.ts as dist/src/cli.js`" }),
+            }), { description: "What you found yourself, each with where - never what <how to invoke it> claims unchecked" })),
             functionalities: Type.Optional(Type.Array(Type.Object({
                 module: Type.String({ description: "The module the functionality is in" }),
                 id: Type.String({ description: "Its id in that module" }),
@@ -704,6 +749,8 @@ export async function judgeFailure(options) {
                 reason: given.reason,
                 ...(given.spec_says?.trim() ? { specSays: given.spec_says.trim() } : {}),
                 ...(given.cause_hidden === true ? { causeHidden: true } : {}),
+                ...(given.script_needs?.trim() ? { scriptNeeds: given.script_needs.trim() } : {}),
+                ...(given.evidence !== undefined && given.evidence.length > 0 ? { evidence: given.evidence } : {}),
                 ...(given.functionalities ? { functionalities: conflictRefs(given.functionalities) } : {}),
             };
             return { content: [{ type: "text", text: "Recorded." }], details: {}, terminate: true };
@@ -712,10 +759,27 @@ export async function judgeFailure(options) {
     // It reads both, and changes neither: the file tools and the web - to look up what a service it calls answers -
     // and no shell. It judges from the code, the tests, the spec and the failing run's output, which it is given.
     const fence = confinedTools({ workdir: options.conformanceDir, read: [options.buildDir, options.conformanceDir], write: [], noBash: true });
+    // What it opens - read, listed, searched - is what its evidence can cite.
+    const openedPaths = new Set();
+    const tools = fence.tools.map((tool) => ({
+        ...tool,
+        execute: (async (...args) => {
+            const path = args[1]?.path;
+            if (typeof path === "string" && path !== "")
+                openedPaths.add(resolve(options.conformanceDir, path));
+            return tool.execute(...args);
+        }),
+    }));
+    const opened = (cited) => {
+        // A file it opened, or one in a folder it listed or searched; cited as it was opened, or relative to the code or the tests.
+        const candidates = [resolve(options.conformanceDir, cited), resolve(options.buildDir, cited)];
+        return candidates.some((path) => [...openedPaths].some((seen) => path === seen || path.startsWith(`${seen}/`)));
+    };
+    const scriptText = options.testingScripts?.map((script) => script.content).join("\n");
     const before = { code: digestFiles(options.buildDir), tests: digestFiles(options.conformanceDir) };
     const session = await createExecutor({
         cwd: options.conformanceDir,
-        customTools: [submit, ...createWebTools(), ...fence.tools],
+        customTools: [submit, ...createWebTools(), ...tools],
         tools: [...fence.names, ...WEB_TOOLS, "submit_verdict"],
         model: options.model,
         label: `${options.label} judge`, role: "judge",
@@ -730,8 +794,15 @@ export async function judgeFailure(options) {
                 await ask(session, "You have not called submit_verdict. Call it now: code, tests, spec or environment, and why.", options.onDelta);
                 continue;
             }
+            // Asked to weigh an escalation, a verdict of code or tests rests on what it found itself.
+            const unproven = options.escalation !== undefined && (verdict.culprit === "code" || verdict.culprit === "tests") ? unfoundedEvidence(verdict.evidence, opened) : undefined;
+            if (unproven !== undefined) {
+                verdict = undefined;
+                await ask(session, unproven, options.onDelta);
+                continue;
+            }
             if (verdict.culprit === "code") {
-                const unfounded = unfoundedCodeVerdict(verdict, options.spec.text);
+                const unfounded = unfoundedCodeVerdict(verdict, options.spec.text, scriptText);
                 if (unfounded === undefined)
                     break;
                 verdict = undefined;
@@ -759,18 +830,26 @@ export async function judgeFailure(options) {
     }
     if (verdict?.culprit === "spec" && specConflictProblem(verdict.functionalities, options.scope) !== undefined)
         verdict = undefined;
-    if (verdict?.culprit === "code" && unfoundedCodeVerdict(verdict, options.spec.text) !== undefined) {
+    // An escalation weighed without evidence escalates nothing: the tests stay the conformance agent's, as before it.
+    if (options.escalation !== undefined && verdict?.culprit === "code" && unfoundedEvidence(verdict.evidence, opened) !== undefined) {
+        return { culprit: "tests", reason: `${verdict.reason}\n\nBut the judge gave no evidence it found itself that the code is what is wrong, so the tests are looked at again.` };
+    }
+    if (verdict?.culprit === "code" && unfoundedCodeVerdict(verdict, options.spec.text, scriptText) !== undefined) {
         // Blaming the code takes the specification's own words; without them, the test asserts what the spec does not say.
         return { culprit: "tests", reason: `${verdict.reason}\n\nBut no words of the specification say so: a test that asserts what the specification does not say is what is wrong. Check each failing assertion against the specification, and assert only what it says.` };
     }
     if (verdict?.culprit === "code" && verdict.specSays !== undefined) {
         verdict = { ...verdict, reason: `${verdict.reason}\n\nThe specification says: "${verdict.specSays}"` };
     }
+    if (verdict?.culprit === "code" && verdict.scriptNeeds !== undefined) {
+        verdict = { ...verdict, reason: `${verdict.reason}\n\nThe conformance testing script needs: "${verdict.scriptNeeds}"` };
+    }
     // No verdict is no evidence the code is wrong: the tests are the newer work, and looked at first.
     return verdict ?? { culprit: "tests", reason: "The judge gave no verdict that could be used; check the failing tests against the specification first." };
 }
 export function judgePrompt(options) {
     const tested = options.scope.tested;
+    const scripts = options.testingScripts ?? [];
     return [
         specPrimer({ testReqs: true }),
         `The conformance tests of the \`${options.spec.moduleName}\` specification failed. Decide what is wrong: the code, the tests, the specification itself, or the run's environment.`,
@@ -780,7 +859,9 @@ export function judgePrompt(options) {
         "The specification is the judge, never either of them:",
         "- tests: a test asserts something the specification does not say, misreads it, or reaches the software the",
         "  wrong way - a wrong command, route or setup (see <how to invoke it>).",
-        "- code: the code does not do what the specification says, and the test checks exactly that.",
+        "- code: the code does not do what the specification says, and the test checks exactly that. Or the run fails",
+        "  on something the conformance testing script needs the code to provide - a build output, an entry point, a",
+        "  module - and the code does not provide it: quote the script's own words for it in script_needs.",
         "  Only what the specification says counts: anything it leaves open - a name, coordinates, a version, a path,",
         "  a package, a port, a file layout - is what the code already has. The tests follow it, and it is never",
         "  code - changing the code to fit a test's guess moves what every other test points at.",
@@ -810,6 +891,19 @@ export function judgePrompt(options) {
         "verdict of code without them is not taken. What the specification leaves open is never the code's fault: a test",
         "that asserts it - a status code, a message, a format the specification does not name - is what is wrong.",
         "",
+        ...(scripts.length > 0
+            ? [
+                "The conformance testing script below is how every run is made, and neither agent can change it: it is never",
+                "what is wrong. What it does with the tests, the tests have to fit; what it needs of the code - a file it runs or",
+                "checks for, a command it builds with - the code has to provide. A verdict that the script is wrong is neither",
+                "code nor tests: say which of the two has to change to get past it.",
+                "",
+            ]
+            : []),
+        "<how to invoke it> is the explorer's account, written before the run, and it can be wrong - a folder, a path, a",
+        "command. Never rest a verdict on it: check each claim you use against the testing script and the files, and give",
+        "in `evidence` what you found yourself, each with where.",
+        "",
         `You have ${JUDGE_CALLS} tool calls to decide in: read what the failure points at, not the whole codebase.`,
         "",
         "When the code and the tests could both be what is wrong, choose tests. When both are wrong, say which to fix",
@@ -832,11 +926,35 @@ export function judgePrompt(options) {
         "",
         `<how to invoke it>\n${options.invocation.trim()}\n</how to invoke it>`,
         "",
+        ...scripts.flatMap((script) => [`<conformance testing script path="${script.path}" run-as="${script.runs}">`, script.content.trimEnd(), "</conformance testing script>", ""]),
         `<failing run exit="${options.run.exitCode}" command="${options.run.command}">`,
         options.run.output.trimEnd(),
         "</failing run>",
+        ...(options.escalation !== undefined ? ["", ...escalationBlock(options.escalation)] : []),
     ].join("\n");
 }
+/** For the judge: the tests were fixed for this failure, and it did not go away - is it the code's? */
+function escalationBlock(escalation) {
+    const changed = escalation.changed.length === 0 ? "changed no file" : `changed ${escalation.changed.slice(0, 8).join(", ")}${escalation.changed.length > 8 ? ` and ${escalation.changed.length - 8} more` : ""}`;
+    return [
+        "<escalation>",
+        "This failure was judged the tests' before, and the conformance agent - who can change only the tests - was sent to",
+        `fix it. It ${changed}, and the run fails the same way. What it was told:`,
+        "",
+        escalation.reason.trim(),
+        "",
+        "Decide again, now whether the failure belongs to the code rather than the tests. It is the code's when the run",
+        "fails on something the code is meant to produce - a build output, an entry point, a module the testing script needs",
+        "- or when the tests ran and what the software does is not what the specification says. It stays the tests' when a",
+        "test is still wrong and the code is right: say exactly what in the tests, so the next fix is not the last one again.",
+        "",
+        "Gather the evidence yourself: open the files the failure points at - the code's build configuration and what it",
+        "emits, the tests - and read the testing script. Give it in `evidence`: a verdict of code or tests without evidence",
+        "you found is not taken. The coding agent is handed your reason and evidence: say what the code has to provide, and",
+        "where it now falls short (e.g. `the script runs dist/cli.js; the build emits dist/src/cli.js`).",
+        "</escalation>",
+    ];
+}
 /**
  * The coding agent a conformance run sends the code to, when the judge says the code is wrong: it
  * works in the code folder, may read the tests but never changes them, and keeps the unit
@@ -917,6 +1035,43 @@ export function codeFixPrompt(options) {
         "Fix the code, run the conformance tests and the unit tests, and finish.",
     ].join("\n");
 }
+/** How much of the conformance tests an escalation hands the coding agent, whole: the rest it reads itself. */
+const ESCALATED_TESTS_CHARS = 24_000;
+/**
+ * An escalated failure for the code fixer: the tests were fixed for it and it did not go away, and the judge found it
+ * the code's. It is handed the conformance testing script's error, the tests as they stand and the judge's evidence.
+ */
+export function escalatedFixPrompt(options) {
+    let room = ESCALATED_TESTS_CHARS;
+    const shown = options.tests.flatMap((test) => {
+        if (room <= 0)
+            return [`<conformance test path="${test.path}" shown="no - read it yourself" />`];
+        const content = test.content.length > room ? `${test.content.slice(0, room)}\n... (cut short - read the rest yourself)` : test.content;
+        room -= content.length;
+        return [`<conformance test path="${test.path}">`, content.trimEnd(), "</conformance test>"];
+    });
+    return [
+        `The conformance tests failed (exit ${options.run.exitCode}). The conformance agent was sent to fix the tests for it, and`,
+        "the run failed the same way. A judge then looked again, gathered the evidence below itself, and found that the",
+        "failure belongs to the code:",
+        "",
+        `<why the code>\n${options.reason.trim()}\n</why the code>`,
+        "",
+        "<evidence>",
+        ...options.evidence.map((item) => `- ${item.source.trim()}: ${item.shows.trim()}`),
+        "</evidence>",
+        "",
+        `<failing run command="${options.run.command}">`,
+        options.run.output.trimEnd(),
+        "</failing run>",
+        "",
+        "The conformance tests as they stand - not yours to change:",
+        ...shown,
+        "",
+        "Fix the code, run the conformance tests and the unit tests, and finish. This is the last attempt at this failure:",
+        "if the run still fails the same way after your fix, the work stops.",
+    ].join("\n");
+}
 /** The run's environment judged what is wrong: the conformance agent checks the tests do not cause it, and changes nothing when they do not. */
 export function environmentCheckPrompt(options) {
     return [

package/dist/regenerate/conformance.js

@@ -16,7 +16,7 @@ import { createMyDiffTool } from "./self-check.js";
 import { createServiceTools } from "./services.js";
 import { missingToolchainError, 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";
@@ -194,6 +194,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
@@ -414,6 +419,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.
@@ -504,6 +518,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,6 +533,9 @@ 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,
@@ -585,15 +608,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 +655,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;
@@ -772,6 +818,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 } : {}),

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 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 \`${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 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. */

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;
+    };
+}