@turri-dev/cli 0.1.3-next.f74e98a → 0.1.4-next.172be6f

package/dist/loop-tools.js

@@ -70,7 +70,11 @@ export async function loopReply(loop, statuses, wait) {
     return { content: [{ type: "text", text }], details: { jobIds } };
 }
 /** Halt a pulse by its id, or the start of it: what it was, and what moves up behind it. `reason`: why, kept with it. */
-export function stopJob(jobs, named, reason) {
+export function stopJob(jobs, named, reason, loop) {
+    // A planned row, or a module by its name: the module is halted - its rows are planned again from the spec each look.
+    const module = /^planned-/.test(named.trim()) || !jobs.list().some((job) => job.id.startsWith(named.trim())) ? loop?.halt(named, reason) : undefined;
+    if (module !== undefined)
+        return module;
     const matches = jobs.list().filter((job) => job.id.startsWith(named.trim()));
     if (matches.length === 0)
         return `No pulse ${named}. /pulses shows them.`;
@@ -106,6 +110,10 @@ function plainFileOf(cwd, given, what) {
 export function asksFromScratch(words) {
     return FROM_SCRATCH.test(words);
 }
+/** Whether a /regenerate asking for its module from scratch asks for its whole requires chain with it. */
+export function asksWholeChain(words) {
+    return /\bchain\b|\bevery module\b|\ball (the )?modules\b/i.test(words);
+}
 const FROM_SCRATCH = /\b(from (scratch|nothing|zero|the (start|beginning|ground up))|start(ing)? (it )?(over|afresh)|afresh|anew|clean slate|(delete|wipe|remove|drop|throw away)\b.{0,30}\b(module|code|codebase|everything|all of it))/i;
 /** regenerate: regenerate a module's code up to its spec as it is now. */
 export function regenerateTool(options) {
@@ -127,6 +135,7 @@ export function regenerateTool(options) {
             "A change to a file the spec links - an API surface, a mapping document - is a change to the spec: regenerate sees it by itself, and regenerates every functional spec that uses what links it.",
             "Never stop pulses and start them again yourself to follow a spec change: regenerate does it.",
             "Set from_scratch only when the user asks for the module to be regenerated from scratch - started over, its code deleted - in this conversation, or agrees to it when a module's status says it has to start over: never to fix a pulse that did not land.",
+            'from_scratch "module" takes out the code where the module is built; the modules below keep theirs, and the module starts from a copy of the code below it. "chain" takes out every codebase of its requires chain, the base\'s too, and builds all of it again from the bottom: use it after modules were split, merged or moved (refactor-module), or when the user asks for the whole chain.',
         ],
         parameters: Type.Object({
             plain_file: Type.Optional(Type.String({ description: "Path to the .plain file. Omitted: the module the project's config.turri.yaml names" })),
@@ -135,8 +144,9 @@ export function regenerateTool(options) {
             functionalities: Type.Optional(Type.Array(Type.String(), {
                 description: "Functional specs already built, by id, to regenerate though their spec did not change. Omitted: what the spec now differs from the code in",
             })),
-            from_scratch: Type.Optional(Type.Boolean({
-                description: "Only when the user asks for it: the module's code and conformance tests deleted - committed first, so its lineage keeps them - and the whole module regenerated from its spec",
+            from_scratch: Type.Optional(Type.Union([Type.Literal("module"), Type.Literal("chain")], {
+                description: "Only when the user asks for it: the module's code and conformance tests deleted - committed first, so its lineage keeps them - and the whole module regenerated from its spec. " +
+                    '"chain": every module of its requires chain too, built again from the bottom',
             })),
             model: MODEL_PARAM,
             wait: WAIT_PARAM,
@@ -147,15 +157,15 @@ export function regenerateTool(options) {
             if (!check.ok)
                 throw new Error(`${relative(options.cwd, plainFile) || plainFile} does not parse, so nothing can be regenerated from it yet: ${check.error}`);
             const again = given.functionalities ?? [];
-            if (again.length > 0 && given.from_scratch === true)
+            if (again.length > 0 && given.from_scratch !== undefined)
                 throw new Error("Name functionalities or set from_scratch, not both: from scratch regenerates every one of them.");
             // Named functionalities are work on functionalities, as engine chooses a model for it; the rest, spec changes.
             const work = again.length > 0 ? "functionalities" : "spec_changes";
             const model = options.model !== undefined ? options.model(ctx, plainFile, given.model, work) : given.model;
             const loop = options.loop(ctx);
             const request = { ...(model !== undefined ? { model } : {}), ...(given.guidance !== undefined ? { guidance: given.guidance } : {}) };
-            const statuses = given.from_scratch === true
-                ? await loop.fromScratch(plainFile, request)
+            const statuses = given.from_scratch !== undefined
+                ? await loop.fromScratch(plainFile, { ...request, chain: given.from_scratch === "chain" })
                 : again.length > 0
                     ? await loop.regenerateAgain(plainFile, again, request)
                     : await loop.bringUp(plainFile, request);
@@ -188,7 +198,7 @@ export function driftTool(options) {
 }
 const ACTIVATED_PARAM = Type.Optional(Type.String({ description: 'What activate started, by name - or "all" for every one' }));
 const HALT_PULSE_PARAMS = Type.Object({
-    job_id: Type.Optional(Type.String({ description: "The pulse's id, or the start of it" })),
+    job_id: Type.Optional(Type.String({ description: "The pulse's id, or the start of it; a planned row's id (planned-<module>-...), or a module's name, halts the module" })),
     reason: Type.Optional(Type.String({ description: "Why it is halted, kept with it - what the spec now says that it did not, say" })),
     activated: ACTIVATED_PARAM,
 });
@@ -201,12 +211,21 @@ export function haltTool(options) {
         name: "halt",
         label: "Halt",
         description: jobs !== undefined
-            ? "Halt a pulse, or what activate started. A pulse: a queued one never starts, a running one has its agent stopped at once, " +
-                "and the pulses queued behind it move up - what a running pulse already changed is rolled back, and what it was regenerating " +
-                "counts as not regenerated. What activate started: the one named, or every one."
+            ? "Halt a pulse, a module's planned pulses, or what activate started. A pulse: a queued one never starts, a running one has its " +
+                "agent stopped at once, and the pulses queued behind it move up - what a running pulse already changed is rolled back, and what " +
+                "it was regenerating counts as not regenerated. A planned row (planned-<module>-...) or a module's name halts the module: its " +
+                "running pulse stopped, none of its planned pulses started, and the modules built on it waiting - until it is asked for again " +
+                "with regenerate; a spec change does not start it. A module whose .plain file is gone is dropped. What activate started: the " +
+                "one named, or every one."
             : "Stop what activate started: the one named, or every one.",
         promptSnippet: jobs !== undefined ? "halt a pulse, or what activate started" : "stop a deployed server, or all of them",
-        promptGuidelines: jobs !== undefined ? ["Halt a pulse only when the user asks, or your instructions say to. Name which one, and say which pulses were queued behind it - they will now run."] : [],
+        promptGuidelines: jobs !== undefined
+            ? [
+                "Halt a pulse only when the user asks, or your instructions say to. Name which one, and say which pulses were queued behind it - they will now run.",
+                "Halting a planned row halts its whole module - one planned pulse cannot be taken out alone, as the plan is made again from the spec. To build some of it later, or cut it differently, use steer; to drop work, change the spec.",
+                "A planned row for a module that is no longer in the project is halted the same way, and dropped.",
+            ]
+            : [],
         parameters: (jobs !== undefined ? HALT_PULSE_PARAMS : HALT_ACTIVATED_PARAMS),
         async execute(_id, params) {
             if (params.job_id === undefined && params.activated === undefined) {
@@ -214,7 +233,7 @@ export function haltTool(options) {
             }
             const lines = [];
             if (params.job_id !== undefined && jobs !== undefined)
-                lines.push(stopJob(jobs, params.job_id, params.reason));
+                lines.push(stopJob(jobs, params.job_id, params.reason, options.workLoop?.()));
             if (params.activated !== undefined) {
                 const stopped = await stopDeployed(params.activated === "all" ? {} : { name: params.activated });
                 lines.push(stopped.length > 0 ? `Halted ${stopped.join(", ")}.` : `Nothing activate started is running${params.activated === "all" ? "" : ` as ${params.activated}`}.`);

package/dist/pi-launch.js

@@ -11,6 +11,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { main, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { ProcessTerminal } from "@earendil-works/pi-tui";
 import "./terminal-images.js";
+import { resumeLine } from "./resume-line.js";
 /**
  * pi, started the way its own CLI starts it, for `turri`.
  *
@@ -31,6 +32,10 @@ const setTitle = ProcessTerminal.prototype.setTitle;
 ProcessTerminal.prototype.setTitle = function (title) {
     setTitle.call(this, title.replace(/^π(?= |$)/, "🪼 turri"));
 };
+// What pi prints on the way out to resume the session names pi - its APP_NAME, a constant - which may not be on the
+// PATH at all: turri takes the same flags, so it is turri the line names.
+const write = process.stdout.write.bind(process.stdout);
+process.stdout.write = ((chunk, ...rest) => write(typeof chunk === "string" ? resumeLine(chunk) : chunk, ...rest));
 // pi's own keys stand: a new line is shift+enter or ctrl+j. turri's side panel is on ctrl+h (job-panel.ts PANEL_KEY).
 // What pi's CLI does before main: the process title, pi's environment markers, the HTTP
 // dispatcher. Not exported, so loaded from the file - beside pi's entry point, wherever npm put it.

package/dist/pi.js

@@ -4,6 +4,7 @@ import { createAgentSession, DefaultResourceLoader, getAgentDir, ModelRegistry,
 import { loadRules, renderRulesBlock } from "./rules.js";
 import { inheritModel, stackOf, readProjectConfig, ROLE_THINKING, roleModel, roleTurnLimitMs, splitModelSpec } from "./config.js";
 import { maskToolResults } from "./regenerate/masking.js";
+import { withListArguments } from "./regenerate/list-arguments.js";
 import { checkAgainstScript, ENVIRONMENT_ERROR_TOOL, EnvironmentError, environmentErrorTool, sandboxGapOf } from "./regenerate/environment-error.js";
 import { MODULES_DIR, projectRootOf, sessionsDir } from "./regenerate/paths.js";
 import { currentStopSignal, describeToolCall, describeToolResult, JobStoppedError, shownName, reportActivity, reportNow, reportAgent, reportTranscript, reportModelEvent, reportUsage, } from "./regenerate/activity.js";
@@ -146,6 +147,19 @@ export class ProviderError extends Error {
         this.name = "ProviderError";
     }
 }
+/** Why turri itself ended a session's turn under way: the abort that comes back is its own, not the provider failing. */
+const harnessStops = new WeakMap();
+/**
+ * End the agent's turn, turri's own doing - it is going round in a circle, its time is up. The turn ends as any turn
+ * does: what the agent said stands, and the harness goes on from there. Never a provider error.
+ */
+export function stopTurn(session, reason) {
+    if (session === undefined || harnessStops.has(session))
+        return;
+    harnessStops.set(session, reason);
+    reportModelEvent({ kind: "stopped", ...modelEventOf(session), reason });
+    void session.abort();
+}
 /**
  * Run one turn and return the assistant's text, streaming deltas to `onDelta`.
  *
@@ -212,17 +226,30 @@ async function askUnrestricted(session, text, onDelta) {
         catch (error) {
             if (!(error instanceof ProviderError) || !TRANSIENT_PROVIDER_ERROR.test(error.message) || attempt >= PROVIDER_RETRIES)
                 throw error;
-            const wait = PROVIDER_RETRY_DELAY_MS * 2 ** attempt;
-            reportActivity(`  the model provider is failing for now - trying again in ${Math.round(wait / 1000)}s (${attempt + 1} of ${PROVIDER_RETRIES})`);
-            debugLogOf(session)?.note(`provider failing - trying again in ${Math.round(wait / 1000)}s: ${error.message.slice(0, 200)}`);
+            const wait = providerRetryDelay(attempt);
+            const shown = `${Math.round(wait / 1000)}s (${attempt + 1} of ${PROVIDER_RETRIES})`;
+            reportActivity(`  the model provider is failing for now - trying again in ${shown}`);
+            reportNow(`the model provider is failing - trying again in ${shown}`);
+            reportModelEvent({ kind: "provider_retry", ...modelEventOf(session), error: error.message, attempt: attempt + 1, of: PROVIDER_RETRIES, waitMs: wait });
+            debugLogOf(session)?.note(`provider failing - trying again in ${shown}: ${error.message.slice(0, 200)}`);
             await waitOrStop(wait);
+            reportNow(undefined);
             prompt = "Carry on where you were: the model provider failed part-way through your last turn.";
         }
     }
 }
-/** How many times, after pi's own retries, a turn whose provider failed for a moment is tried again - and the first wait, doubled each time. */
-export const PROVIDER_RETRIES = 3;
+/**
+ * How many times, after pi's own retries, a turn whose provider failed for a moment is tried again; the first wait,
+ * doubled each time up to the longest - 15s, 30s, 1m, 2m, 4m, 5m: an outage of about 13 minutes is waited out.
+ */
+export const PROVIDER_RETRIES = 6;
 export const PROVIDER_RETRY_DELAY_MS = Number(process.env.TURRI_PROVIDER_RETRY_DELAY ?? 15) * 1000;
+export const PROVIDER_RETRY_MAX_DELAY_MS = 20 * PROVIDER_RETRY_DELAY_MS;
+/** The wait before try `attempt + 1`: doubled each time, up to the longest, with a tenth either way so parallel jobs do not all come back at once. */
+export function providerRetryDelay(attempt, random = Math.random) {
+    const base = Math.min(PROVIDER_RETRY_DELAY_MS * 2 ** attempt, PROVIDER_RETRY_MAX_DELAY_MS);
+    return Math.round(base * (0.9 + 0.2 * random()));
+}
 /** A provider error that passes: overloaded, rate limited, unreachable, timed out. */
 const TRANSIENT_PROVIDER_ERROR = /\b(429|500|502|503|504|529)\b|overloaded|high demand|rate.?limit|too many requests|unavailable|fetch failed|network|connection|timed? ?out|ECONNRESET|socket|terminated/i;
 /** Wait, unless the job is stopped first. */
@@ -251,7 +278,7 @@ async function askOnce(session, text, onDelta) {
     // Calls to one tool failing one after another - arguments it refuses, or errors - with nothing going through.
     let failing = 0;
     let failingTool;
-    let stoppedFailing = false;
+    harnessStops.delete(session);
     reportNow("waiting for the model");
     // Every entry says which agent it is from, and what it runs on - for reading one agent at a time.
     const agent = agentOf(session);
@@ -308,14 +335,13 @@ async function askOnce(session, text, onDelta) {
         if (event.type === "tool_execution_end") {
             failing = event.isError ? (event.toolName === failingTool ? failing + 1 : 1) : 0;
             failingTool = event.isError ? event.toolName : undefined;
-            if (failing >= FAILURES_BEFORE_STOP && !stoppedFailing) {
+            if (failing >= FAILURES_BEFORE_STOP && !harnessStops.has(session)) {
                 // A call its tool refuses never reaches the tool, so no guard on the tools sees it: an agent can
                 // make the same bad call, worded a little differently, thousands of times. Its turn ends here, and
                 // the harness goes on from there, as after any turn.
-                stoppedFailing = true;
                 reportActivity(`  stopped the agent's turn: ${failing} ${shownName(event.toolName)} calls failed in a row`);
                 debugLogOf(session)?.note(`turn stopped: ${failing} ${event.toolName} calls failed in a row`);
-                void session.abort();
+                stopTurn(session, `${failing} ${shownName(event.toolName)} calls failed in a row`);
             }
             const output = resultText(event.result);
             transcript({ kind: "result", text: clipText(output, MAX_TOOL_RESULT), error: event.isError, full: output });
@@ -376,7 +402,7 @@ async function askOnce(session, text, onDelta) {
         stopped = true;
         reportActivity(`  stopped the agent's turn: its ${formatLimit(limitMs)} are up`);
         debug?.note(`turn stopped: its ${formatLimit(limitMs)} are up${how}`);
-        void session.abort();
+        stopTurn(session, `its ${formatLimit(limitMs)} were up`);
     };
     const atNextRequest = timed
         ? session.subscribe((event) => {
@@ -417,14 +443,17 @@ async function askOnce(session, text, onDelta) {
         stop?.removeEventListener("abort", onStop);
         reportNow(undefined);
     }
-    if (stopped)
-        out = `${out.trim()}\n\n[the turn was stopped: its ${formatLimit(limitMs)} were up]`.trim();
+    // turri ended the turn itself - its time was up, the agent went round in a circle: the abort that ended it is its own.
+    const stoppedFor = harnessStops.get(session);
+    harnessStops.delete(session);
+    if (stoppedFor !== undefined)
+        out = `${out.trim()}\n\n[the turn was stopped: ${stoppedFor}]`.trim();
     if (stop?.aborted) {
         debug?.note(`turn stopped on request after ${seconds(Date.now() - turnStarted)}`);
         throw new JobStoppedError();
     }
-    // A turn ended for its time is ended, whatever the provider was doing then.
-    if (providerError !== undefined && !stopped) {
+    // A turn turri ended is ended, whatever the provider was doing then: what comes back of the abort is not the provider failing.
+    if (providerError !== undefined && stoppedFor === undefined) {
         debug?.note(`turn ended with a provider error after ${seconds(Date.now() - turnStarted)}: ${providerError}`);
         throw new ProviderError(`${session.model?.id ?? "model"}: ${providerError}`);
     }
@@ -614,7 +643,7 @@ export function guardRepeats(tools, session, budget) {
                 refused += 1;
                 if (refused > REFUSED_BEFORE_STOP) {
                     reportActivity(`  stopped the agent's turn: ${refused} calls to tools this turn does not have`);
-                    void current?.abort();
+                    stopTurn(current, `${refused} calls to tools this turn does not have`);
                     throw new Error(`Stopped: ${refused} calls to tools this turn does not have.`);
                 }
                 throw new Error(`Not run: your work is done and checked - this turn is for ${[...only].join(" and ")} alone, and nothing else is ` +
@@ -624,7 +653,7 @@ export function guardRepeats(tools, session, budget) {
             if (budget !== undefined && !budget.finish.includes(tool.name) && calls > budget.calls) {
                 if (calls > budget.calls * 2) {
                     reportActivity(`  stopped the agent's turn: ${calls} tool calls, past its budget of ${budget.calls}`);
-                    void session()?.abort();
+                    stopTurn(session(), `${calls} tool calls, past its budget of ${budget.calls}`);
                     throw new Error(`Stopped: ${calls} tool calls, past the budget of ${budget.calls}.`);
                 }
                 throw new Error(`Not run: you have made ${budget.calls} tool calls, which is all you have. Decide now with what you know: call ` +
@@ -652,7 +681,7 @@ export function guardRepeats(tools, session, budget) {
             }
             if (repeats > REPEATS_BEFORE_STOP) {
                 reportActivity(`  stopped the agent's turn: it made the same ${tool.name} call ${repeats} times with nothing changed`);
-                void session()?.abort();
+                stopTurn(session(), `the same ${tool.name} call ${repeats} times with nothing changed`);
                 throw new Error(`Stopped: the same ${tool.name} call ${repeats} times with nothing changed.`);
             }
             if (repeats > REPEATS_ALLOWED) {
@@ -695,7 +724,7 @@ export async function createExecutor(opts) {
         modelRuntime: await subAgentModelRuntime(),
         tools: hasShell ? [...opts.tools, ENVIRONMENT_ERROR_TOOL] : opts.tools,
         // What an agent is shown never holds a credential the project passed: each value is its name (masking.ts).
-        customTools: guardRepeats(maskToolResults(withEnvironmentErrors), () => session, opts.budget),
+        customTools: guardRepeats(maskToolResults(withListArguments(withEnvironmentErrors)), () => session, opts.budget),
         sessionManager,
         resourceLoader: await subAgentResources(opts.cwd, opts.rules === true, [opts.system, opts.task].filter((part) => part !== undefined && part !== "").join("\n\n") || undefined),
     });
@@ -814,7 +843,7 @@ export async function createJudge(opts) {
         model,
         modelRuntime,
         tools: [...(opts.extraTools ?? []), "submit_verdict"],
-        customTools: [opts.verdictTool],
+        customTools: withListArguments([opts.verdictTool]),
         sessionManager: SessionManager.inMemory(opts.cwd),
         // Judges assess specs against the rules, so they have them too.
         resourceLoader: await subAgentResources(opts.cwd, true, opts.task),

package/dist/question-dialog.js

@@ -25,6 +25,7 @@ export class QuestionDialog {
         }
         else {
             this.input = undefined;
+            this.selected = Math.min(Math.max(0, options.selected ?? 0), options.options.length - 1);
         }
     }
     get focused() {
@@ -58,18 +59,23 @@ export class QuestionDialog {
         const choices = this.options.options ?? [];
         const body = this.input !== undefined
             ? this.input.render(inner)
-            : choices.map((choice, index) => (index === this.selected ? style.accent(`› ${choice}`) : `  ${choice}`));
+            : // A long option wraps, its lines under its first, rather than cut off where the person cannot read it.
+                choices.flatMap((choice, index) => wrapTextWithAnsi(choice, Math.max(1, inner - 2)).map((line, at) => {
+                    const shown = `${at === 0 && index === this.selected ? "›" : " "} ${line}`;
+                    return index === this.selected ? style.accent(shown) : shown;
+                }));
         const hint = this.input !== undefined
             ? "enter answers · esc dismisses"
             : "↑↓ choose · enter picks · esc dismisses";
         // The brief gets what the question, the options and the hints leave of the screen.
-        const fixed = question.length + body.length + 4;
+        const fixed = question.length + body.length + 5;
         const room = Math.max(3, this.options.rows() - KEPT_ABOVE - fixed);
         const scrolls = brief.length > room;
         this.window = scrolls ? room - 1 : brief.length;
         this.maxScroll = scrolls ? brief.length - this.window : 0;
         this.scroll = Math.min(this.scroll, this.maxScroll);
-        const lines = [];
+        // Set apart from what is drawn above it - the job panel's hints.
+        const lines = [""];
         if (brief.length > 0) {
             lines.push(...brief.slice(this.scroll, this.scroll + this.window).map(pad));
             if (scrolls) {

package/dist/questioning.js

@@ -43,7 +43,7 @@ export function questioningQuestion(phases) {
     return {
         question: `How many questions should I ask you in ${named}?`,
         options: QUESTIONING_LEVELS.map((level) => level.option),
-        context: `Light, medium and thorough cap each of ${named} at 3, 5 and 10 questions - broader with fewer, so every level ` +
+        context: `Light, medium and thorough cap ${phases.length === 1 ? named : `each of ${named}`} at 3, 5 and 10 questions - broader with fewer, so every level ` +
             "covers the same ground, only in less or more depth. What the questions leave open, turri decides itself and " +
             "says what it chose. With best judgement, turri asks as much as it judges each phase needs. Each phase still " +
             "ends with your confirmation of its summary.",

package/dist/regenerate/activity.js

@@ -90,6 +90,18 @@ export function onModelEvent(listener) {
     modelListeners.add(listener);
     return () => modelListeners.delete(listener);
 }
+/** A provider retry or a stop, in a line for the person: the chat's notification, a headless run's console. */
+export function describeTurnIncident(event) {
+    const who = event.role ?? event.label ?? "an agent";
+    const model = event.model !== undefined ? ` (${event.model})` : "";
+    if (event.kind === "provider_retry") {
+        const wait = Math.round((event.waitMs ?? 0) / 1000);
+        return `The model provider failed${model}: ${(event.error ?? "").slice(0, 160)} - trying ${who}'s turn again in ${wait}s (${event.attempt} of ${event.of}).`;
+    }
+    if (event.kind === "stopped")
+        return `turri stopped ${who}'s turn${model}: ${event.reason ?? "it was stopped"} - carrying on from there.`;
+    return undefined;
+}
 export function reportModelEvent(event) {
     if (modelListeners.size === 0)
         return;
@@ -183,6 +195,8 @@ export function describeToolCall(name, args) {
             return `± my_diff`;
         case "update_notes":
             return `✐ update_notes`;
+        case "report_spec_gap":
+            return `? spec gap: ${text("question") ?? ""}`.trimEnd();
         case "copy_resource":
             return `⎘ copy_resource ${path ?? text("to") ?? ""}`.trimEnd();
         case "can_it_fail":

package/dist/regenerate/conform.js

@@ -7,7 +7,7 @@ import { abandonWork, startWork } from "./lineage.js";
 import { ensureRegressionPasses } from "./regression.js";
 import { modulesRoot, projectDirOf } from "./paths.js";
 import { applySpecDiff, snapshotSpec, specGapsText } from "./regenerate.js";
-import { linesAddedSince, readNotes } from "./notes.js";
+import { gapMark, gapsSince } from "./notes.js";
 import { sectionsOf } from "./state.js";
 import { describeStop } from "./stop-report.js";
 import { missingTestLabels } from "./test-kinds.js";
@@ -41,8 +41,8 @@ export async function renderSpecDiffConformance(options) {
     // state, not to what an interrupted run left half-written. The tests and the whole suite are
     // one unit, landed whole or undone whole.
     const unit = startWork([buildDir, conformanceDir], moduleName);
-    // The notes as its agents find them: a spec gap they add is told with the result.
-    const notesBefore = { code: readNotes(buildDir), tests: readNotes(conformanceDir) };
+    // The spec gaps its agents report from here on are told with the result.
+    const gapsFrom = gapMark();
     const conformance = await renderConformanceTests({
         plainFile: tip.plainFile,
         frid: lastFrid,
@@ -58,8 +58,8 @@ export async function renderSpecDiffConformance(options) {
     });
     // What the codebase now has conformance tests for, as their labels say.
     const tested = () => frids.filter((frid) => missingTestLabels(conformanceDir, frid, []).length === 0);
-    // Read before a rollback takes the notes back: a gap is the person's to decide, whether the tests passed or not.
-    const base = { moduleName, buildDir, conformanceDir, diff: applied, conformance, specGaps: [...linesAddedSince(notesBefore.code, buildDir, "gaps"), ...linesAddedSince(notesBefore.tests, conformanceDir, "gaps")] };
+    // A gap is the person's to decide, whether the tests passed or not.
+    const base = { moduleName, buildDir, conformanceDir, diff: applied, conformance, specGaps: gapsSince(gapsFrom, [buildDir, conformanceDir]) };
     if (!conformance.passed) {
         abandonWork(unit, moduleName, notLandedWhy("for the spec change", conformance.unlabelled));
         return { ...base, tested: tested(), passed: false, stoppedAt: "conformance" };

package/dist/regenerate/conformance-agents.js

@@ -7,7 +7,7 @@ import { confinedTools } from "./confine.js";
 import { ensureInModulesScratch, modulesScratchDir } from "./paths.js";
 import { workspaceBlock } from "./workspace.js";
 import { reportActivity } from "./activity.js";
-import { runTiming } from "./test-scripts.js";
+import { runTiming, withTestingScripts } from "./test-scripts.js";
 import { createWebTools, WEB_TOOLS } from "./web.js";
 import { diffFiles, digestFiles } from "./codebase.js";
 import { ERROR_CAUSE_RULES, fixMethod, INTEGRITY_RULES, specPrimer } from "./prompt.js";
@@ -378,9 +378,17 @@ export function explorePrompt(buildDir, spec, scope, testingScripts, question, p
         ...(testingScripts !== undefined && testingScripts.length > 0
             ? [
                 "",
-                "This is the project's conformance testing script, which the harness runs to decide whether the",
-                "tests pass - read it for what it builds or installs before the tests run, and so what the tests can depend on:",
-                ...testingScripts.flatMap((script) => ["", `<script path="${script.path}" run-as="${script.runs}">`, script.content.trimEnd(), "</script>"]),
+                ...(testingScripts.some((script) => script.prepare === true)
+                    ? [
+                        "These are the project's prepare script, which the harness runs on the build first, and its conformance testing",
+                        "script, which runs only once the prepare script passes and decides whether the tests pass - read both for what",
+                        "they build or install before the tests run, and so what the tests can depend on:",
+                    ]
+                    : [
+                        "This is the project's conformance testing script, which the harness runs to decide whether the",
+                        "tests pass - read it for what it builds or installs before the tests run, and so what the tests can depend on:",
+                    ]),
+                ...testingScripts.flatMap((script) => ["", `<script${script.prepare === true ? ' kind="prepare environment"' : ""} path="${script.path}" run-as="${script.runs}">`, script.content.trimEnd(), "</script>"]),
             ]
             : []),
         ...(previous !== undefined && question === undefined
@@ -704,7 +712,7 @@ export function unfoundedEvidence(evidence, opened) {
             "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 inPrompt = (source) => /^(the )?(conformance )?testing script$|^(the )?prepare 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 ` +
@@ -735,7 +743,7 @@ export async function judgeFailure(options) {
                 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`" }),
+                source: Type.String({ description: "Where: the path of a file you opened, `testing script`, `prepare script` where there is one, 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({
@@ -900,6 +908,12 @@ export function judgePrompt(options) {
                 "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.",
+                ...(scripts.some((script) => script.prepare === true)
+                    ? [
+                        "The prepare script below it runs on the build before every run, and the conformance testing script only once it",
+                        "passes: it binds the same way - neither agent can change it, and what it needs of the code the code provides.",
+                    ]
+                    : []),
                 "",
             ]
             : []),
@@ -929,7 +943,10 @@ 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>", ""]),
+        ...scripts.flatMap((script) => {
+            const tag = script.prepare === true ? "prepare script" : "conformance testing script";
+            return [`<${tag} path="${script.path}" run-as="${script.runs}">`, script.content.trimEnd(), `</${tag}>`, ""];
+        }),
         ...(options.run.timedOut === true ? [...timedOutBlock(options.run), ""] : []),
         `<failing run exit="${options.run.exitCode}" command="${options.run.command}">`,
         runTiming(options.run),
@@ -1004,7 +1021,10 @@ export async function createCodeFixer(options) {
         model: options.model,
         label: `${options.label} coding agent`, role: "coding",
         system: `${fence.note}\n\n${workspaceBlock({ dir: options.buildDir, hasMyDiff: options.toolNames.includes("my_diff") })}`,
-        task: codeFixerTask(options),
+        // What the conformance testing script needs of the build, the code provides: the fixer reads it, not only a judge's quote of it.
+        task: options.testingScripts !== undefined
+            ? withTestingScripts(codeFixerTask(options), options.testingScripts.scripts, ["conformance", "unit"], options.testingScripts.root)
+            : codeFixerTask(options),
         compaction: { instructions: CODER_COMPACTION },
         ...(options.checkEnvironment !== undefined ? { checkEnvironment: options.checkEnvironment } : {}),
     });

package/dist/regenerate/conformance.js

@@ -9,7 +9,7 @@ import { abandonWork, diffSinceSnapshot, moduleDirOf, recordHistory, startWork,
 import { createWorkLedger, describeAccounts, SUBMIT_WORK_NOTE, unanswered, unansweredPrompt } from "./submit-work.js";
 import { CONFORMANCE_COMPACTION } from "./compaction.js";
 import { NOTES_TURN, notesForSession, passedOutcome, readNotes, reflectOnReview, withNotes } from "./notes.js";
-import { labelsPrompt, labelsPromptFor, misplacedConformanceTests, misplacedTestsPrompt, missingTestLabels } from "./test-kinds.js";
+import { acceptanceLabel, acceptanceText, labelsPrompt, labelsPromptFor, misplacedConformanceTests, misplacedTestsPrompt, missingTestLabels } from "./test-kinds.js";
 import { createScriptTool, findTestScripts, projectRootFor, requireTestScripts, runConformanceScript, runUnitScript, failureSignature, STUCK_ROUNDS, scriptFailure, staticChecksOnly, withTestingScripts, } from "./test-scripts.js";
 import { createWebTools, WEB_TOOLS } from "./web.js";
 import { createMyDiffTool } from "./self-check.js";
@@ -157,9 +157,11 @@ export async function renderConformanceTests(options) {
     // may read the code but writes only tests. An explorer reads the code first and writes down how the
     // software is invoked, which is what the tests are written against.
     const label = `${moduleName} ${options.diff !== undefined ? "spec change" : frid}`;
-    const specContext = { moduleName, text: specText(specifications, moduleName, frids, required, options.change ?? options.diff, sectionModules(tree, moduleName)) };
     // For a spec change: the functionalities it touches, whose acceptance tests are labelled, checked and reviewed.
     const touched = forChange ? touchedFunctionalities(tree, frids, options.diff) : [];
+    // The acceptance tests the run's tests carry out: every functionality the change touches, or the one under test.
+    const carriedOut = forChange ? touched : [{ frid: frid, acceptanceTests: specifications[ACCEPTANCE_TESTS] ?? [] }];
+    const specContext = { moduleName, text: specText(specifications, moduleName, frids, required, carriedOut, options.change ?? options.diff, sectionModules(tree, moduleName)) };
     // Any functionality of the codebase - this module's, and those of the modules it requires. A
     // functionality's run may raise a spec conflict only with that functionality; a spec diff's, between any two.
     const own = (forChange ? frids : frids.slice(0, frids.indexOf(frid) + 1)).map((id) => ({ module: moduleName, frid: id }));
@@ -223,11 +225,15 @@ export async function renderConformanceTests(options) {
     };
     stage(`exploring the code for how it is invoked${options.model ? ` (${options.model})` : ""}`);
     // The explorer reads the conformance testing script too: it is how the tests are built and run, and so how they reach the software.
+    // The prepare script, where there is one, runs on the build before it - and only once it passes does the suite run.
     const testingScripts = [
+        ...(scripts.prepare !== undefined
+            ? [{ path: relative(root, scripts.prepare), runs: "<script> <copy of the build>, before every run of the conformance testing script", content: readFileSync(scripts.prepare, "utf8"), prepare: true }]
+            : []),
         { path: relative(root, scripts.conformance), runs: "<script> <copy of the build> <copy of the whole conformance suite>", content: readFileSync(scripts.conformance, "utf8") },
     ];
     // The acceptance tests the explorer's plan has to carry out, step by step.
-    const toCarryOut = (forChange ? touched : [{ frid: frid, acceptanceTests: specifications[ACCEPTANCE_TESTS] ?? [] }])
+    const toCarryOut = carriedOut
         .map((item) => ({ module: moduleName, frid: item.frid, count: item.acceptanceTests.length }))
         .filter((item) => item.count > 0);
     let invocation = await exploreInvocation({ buildDir, spec: specContext, scope, testingScripts, acceptance: toCarryOut, label, model: options.model, onDelta: options.onDelta });
@@ -272,6 +278,7 @@ export async function renderConformanceTests(options) {
         cwd: conformanceDir,
         customTools: [
             notes.tool,
+            notes.gapTool,
             work.tool,
             ...createWebTools(),
             ...fence.tools,
@@ -285,7 +292,7 @@ export async function renderConformanceTests(options) {
             }),
             createCopyResourceTool({ resources: linkedResources, dir: conformanceDir }),
         ],
-        tools: [...fence.names, "run_conformance_tests", "my_diff", "ask_explorer", "update_notes", "submit_work", "copy_resource", ...WEB_TOOLS],
+        tools: [...fence.names, "run_conformance_tests", "my_diff", "ask_explorer", "update_notes", "report_spec_gap", "submit_work", "copy_resource", ...WEB_TOOLS],
         model: options.model,
         label: `${label} conformance agent`,
         role: "conformance",
@@ -313,12 +320,14 @@ export async function renderConformanceTests(options) {
             // The unit tests, and the conformance suite - to reproduce the failure and check the fix, seeing only its output.
             tools: [
                 fixerNotes.tool,
+                fixerNotes.gapTool,
                 createScriptTool({ kind: "unit", script: scripts.unit, run: () => runUnitScript(buildDir, scripts.unit), runs: unitRuns }),
                 fixerConformanceRuns.tool,
                 ...fixerServices.tools,
             ],
-            toolNames: ["run_unit_tests", "run_conformance_tests", ...fixerServices.names, "update_notes"],
+            toolNames: ["run_unit_tests", "run_conformance_tests", ...fixerServices.names, "update_notes", "report_spec_gap"],
             checkEnvironment: { run: () => runUnitScript(buildDir, scripts.unit), script: scripts.unit },
+            testingScripts: { scripts, root },
         });
         fixerConformanceRuns.newTurn();
         return ask(fixer, withNotes(text, buildDir), options.onDelta);
@@ -687,7 +696,7 @@ export async function renderConformanceTests(options) {
                     buildDir,
                     conformanceDir,
                     spec: specContext,
-                    functionalities: forChange ? touched : [{ frid: frid, acceptanceTests: specifications[ACCEPTANCE_TESTS] ?? [] }],
+                    functionalities: carriedOut,
                     forChange,
                     invocation,
                     label,
@@ -947,9 +956,10 @@ export function failureLine(run) {
 }
 /**
  * The spec as the explorer, the judge and the coding agent are shown it - its functional specs
- * numbered with their ids, so a spec conflict can name them.
+ * numbered with their ids, so a spec conflict can name them, and the acceptance tests the run carries
+ * out labelled as their tests are, so a verdict can quote them.
  */
-function specText(specifications, moduleName, frids, required, diff, modules) {
+function specText(specifications, moduleName, frids, required, acceptance, diff, modules) {
     // Every functionality in the codebase, each with its module: the required modules' first, then this one's.
     const numbered = (key, items) => key === FUNCTIONAL_REQUIREMENTS
         ? [
@@ -957,10 +967,14 @@ function specText(specifications, moduleName, frids, required, diff, modules) {
         ]
         : items;
     // Each section in its tag, as every agent is shown it (see specPrimer).
-    const sections = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, FUNCTIONAL_REQUIREMENTS, ACCEPTANCE_TESTS]
+    const sections = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, FUNCTIONAL_REQUIREMENTS]
         .map((key) => [key, specifications[key] ?? []])
         .filter(([, items]) => items.length > 0)
-        .map(([key, items]) => (key === FUNCTIONAL_REQUIREMENTS || key === ACCEPTANCE_TESTS ? section(key, numbered(key, items)) : moduleSection(key, items, moduleName, modules)));
+        .map(([key, items]) => (key === FUNCTIONAL_REQUIREMENTS ? section(key, numbered(key, items)) : moduleSection(key, items, moduleName, modules)));
+    // Not only the last functionality's: a spec change's run carries out the acceptance tests of every one it touches.
+    const tests = acceptance.flatMap((item) => item.acceptanceTests.map((test, index) => `${acceptanceLabel(item.frid, index + 1)}: ${acceptanceText(test)}`));
+    if (tests.length > 0)
+        sections.push(section(ACCEPTANCE_TESTS, tests));
     if (diff !== undefined)
         sections.push(specChangeBlock(diff));
     return sections.join("\n\n");