@turri-dev/cli 0.1.4-next.318a98a → 0.1.4-next.4342332

package/dist/loop-tools.js

@@ -110,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) {
@@ -131,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" })),
@@ -139,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,
@@ -151,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);

package/dist/module-report.js

@@ -1,9 +1,10 @@
+import { brand } from "./brand.js";
 /** Colours for what the command line prints. */
 export const c = {
     dim: (s) => `\x1b[2m${s}\x1b[0m`,
     bold: (s) => `\x1b[1m${s}\x1b[0m`,
-    green: (s) => `\x1b[32m${s}\x1b[0m`,
-    red: (s) => `\x1b[31m${s}\x1b[0m`,
-    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
-    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    success: brand.success,
+    error: brand.error,
+    warning: brand.warning,
+    accent: brand.accent,
 };

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,32 @@ 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()));
+}
+/** How long a request to the model may go without anything coming back before the provider is said to be stalling; 0 never. */
+export const PROVIDER_STALL_MS = Number(process.env.TURRI_PROVIDER_STALL ?? 120) * 1000;
 /** 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 +280,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);
@@ -263,7 +292,30 @@ async function askOnce(session, text, onDelta) {
     if (agent !== undefined)
         reportAgent({ label: agent.label, ...(agent.model !== undefined ? { model: agent.model } : {}), turns: 1 });
     reportModelEvent({ kind: "turn", ...modelEventOf(session) });
+    // The provider stalling: a request to the model that nothing has come back on - not a token, not an error - for
+    // long. Said once for each silence; the turn goes on waiting, its own time limit ending it if it must.
+    let toolsRunning = 0;
+    let stall;
+    const watchForStall = (afterMs = PROVIDER_STALL_MS) => {
+        if (stall !== undefined)
+            clearTimeout(stall);
+        stall = toolsRunning > 0 || PROVIDER_STALL_MS <= 0 ? undefined : setTimeout(() => {
+            reportModelEvent({ kind: "provider_stall", ...modelEventOf(session), waitMs: PROVIDER_STALL_MS });
+            debugLogOf(session)?.note(`the provider has sent nothing back for ${seconds(PROVIDER_STALL_MS)}`);
+        }, afterMs);
+    };
     const unsubscribe = session.subscribe((event) => {
+        if (event.type === "tool_execution_start")
+            toolsRunning += 1;
+        if (event.type === "tool_execution_end")
+            toolsRunning = Math.max(0, toolsRunning - 1);
+        // pi tries a failed request again itself first: the provider failing is said then, not only once pi gives up.
+        if (event.type === "auto_retry_start") {
+            reportModelEvent({ kind: "provider_retry", ...modelEventOf(session), error: event.errorMessage, attempt: event.attempt, of: event.maxAttempts, waitMs: event.delayMs });
+            watchForStall(event.delayMs + PROVIDER_STALL_MS);
+        }
+        else
+            watchForStall();
         if (event.type === "message_update") {
             const update = event.assistantMessageEvent;
             if (update.type === "text_delta") {
@@ -308,14 +360,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 +427,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) => {
@@ -392,6 +443,7 @@ async function askOnce(session, text, onDelta) {
     }
     // What the model is sent, and only that: its task is its system prompt, which the log already holds whole.
     debug?.prompt(text);
+    watchForStall();
     try {
         // Its images, when its conversation does not hold them: the first turn, and the first after a compaction.
         const images = sessionImages.get(session);
@@ -412,19 +464,24 @@ async function askOnce(session, text, onDelta) {
             clearTimeout(timer);
         if (backstop !== undefined)
             clearTimeout(backstop);
+        if (stall !== undefined)
+            clearTimeout(stall);
         atNextRequest?.();
         unsubscribe();
         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 +671,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 +681,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 +709,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 +752,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 +871,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() {

package/dist/regenerate/activity.js

@@ -90,6 +90,27 @@ export function onModelEvent(listener) {
     modelListeners.add(listener);
     return () => modelListeners.delete(listener);
 }
+/**
+ * The model provider failing or stalling, in a line for the person: the chat's notification, a headless run's console.
+ * A turn turri stopped itself is the work going its normal course - kept in the activity, the pulse's log and the run
+ * report, not said.
+ */
+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 request again in ${wait}s (${event.attempt} of ${event.of}).`;
+    }
+    if (event.kind === "provider_stall") {
+        return `The model provider has sent nothing back to ${who}${model} for ${formatSilence(event.waitMs ?? 0)} - still waiting.`;
+    }
+    return undefined;
+}
+function formatSilence(ms) {
+    const seconds = Math.round(ms / 1000);
+    return seconds >= 60 && seconds % 60 === 0 ? `${seconds / 60}m` : seconds >= 60 ? `${Math.floor(seconds / 60)}m ${seconds % 60}s` : `${seconds}s`;
+}
 export function reportModelEvent(event) {
     if (modelListeners.size === 0)
         return;

package/dist/regenerate/list-arguments.js

@@ -0,0 +1,121 @@
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** The tool's arguments that take a list of objects. */
+function listArguments(schema) {
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties ?? {})
+        .filter(([, property]) => property.type === "array" && property.items?.type === "object")
+        .map(([name, property]) => ({ name, required: required.has(name), item: property.items }));
+}
+/** JSON text, fenced or not, as what it holds; anything else as it is. */
+function parsed(value) {
+    if (typeof value !== "string")
+        return value;
+    const text = value
+        .trim()
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```$/, "");
+    if (!/^[[{]/.test(text))
+        return value;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return value;
+    }
+}
+const escaped = (name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Arguments the model wrote inside another argument's text - `answer</a>\n<b>[...]</b>\n<c>...` - taken out of it and
+ * given as their own, where they were not given already. Which argument each was found in, for the refusal.
+ */
+function untucked(args, names) {
+    const out = { ...args };
+    const foundIn = new Map();
+    const anyTag = names.map(escaped).join("|");
+    for (const [key, value] of Object.entries(args)) {
+        if (typeof value !== "string")
+            continue;
+        let cut = value.search(new RegExp(`</${escaped(key)}>`));
+        for (const name of names) {
+            if (name === key || (out[name] !== undefined && out[name] !== ""))
+                continue;
+            const match = new RegExp(`<${escaped(name)}>([\\s\\S]*?)(?:</${escaped(name)}>|(?=<(?:${anyTag})>)|$)`).exec(value);
+            if (match === null)
+                continue;
+            out[name] = match[1].trim();
+            foundIn.set(name, key);
+            cut = cut === -1 ? match.index : Math.min(cut, match.index);
+        }
+        if (cut !== -1)
+            out[key] = value.slice(0, cut).trim();
+    }
+    return { args: out, foundIn };
+}
+/** What an entry of the list looks like, as JSON: its fields, the optional ones marked. */
+function shapeOf(item) {
+    const required = new Set(item.required ?? []);
+    const entries = Object.entries(item.properties ?? {});
+    const fields = entries.map(([name, field]) => `"${name}"${required.has(name) ? "" : "?"}: ${field.type ?? "value"}`).join(", ");
+    const sample = (field) => (field.type === "number" || field.type === "integer" ? "1" : field.type === "boolean" ? "true" : field.type === "string" ? '"..."' : "...");
+    const example = entries
+        .filter(([name]) => required.has(name))
+        .map(([name, field]) => `"${name}": ${sample(field)}`)
+        .join(", ");
+    return { fields: `{${fields}}`, example: `{${example}}` };
+}
+/** Why a list argument is not one, said so a model can make the call right next time - or undefined when it is. */
+function problemOf(list, value, foundIn) {
+    if (value === undefined)
+        return list.required ? "you left it out" : undefined;
+    if (!Array.isArray(value)) {
+        if (foundIn !== undefined)
+            return `you wrote it inside \`${foundIn}\``;
+        return typeof value === "string" ? "you sent it as text, not a list" : `you sent ${isObject(value) ? "an object" : `a ${typeof value}`}, not a list`;
+    }
+    const bad = value.findIndex((entry) => !isObject(entry));
+    if (bad === -1)
+        return undefined;
+    return `entry ${bad + 1} is ${typeof value[bad] === "string" ? "text" : `a ${typeof value[bad]}`}, not an object`;
+}
+/** The arguments with their lists made lists where they plainly are; refused, saying what is wanted, where they are not. */
+export function prepareListArguments(toolName, schema, raw) {
+    const lists = listArguments(schema);
+    if (lists.length === 0 || !isObject(raw))
+        return raw;
+    const { args, foundIn } = untucked(raw, Object.keys(schema.properties ?? {}));
+    const problems = [];
+    for (const list of lists) {
+        let value = parsed(args[list.name]);
+        if (isObject(value))
+            value = [value];
+        if (Array.isArray(value))
+            value = value.map(parsed);
+        if (value !== undefined)
+            args[list.name] = value;
+        const problem = problemOf(list, value, foundIn.get(list.name));
+        if (problem === undefined)
+            continue;
+        const { fields, example } = shapeOf(list.item);
+        problems.push(`- \`${list.name}\`: ${problem}. It is a list of objects, each ${fields} - e.g. "${list.name}": [${example}].`);
+    }
+    if (problems.length === 0)
+        return args;
+    throw new Error([
+        `${toolName} was not run - its arguments are not in the shape it takes:`,
+        ...problems,
+        "Each argument is a field of its own in the call, at the top level: a list is a JSON array of objects, never text, and never written inside another argument's text.",
+    ].join("\n"));
+}
+/** The tools, each that takes a list of objects preparing its arguments so before they are checked. */
+export function withListArguments(tools) {
+    return tools.map((tool) => {
+        const schema = tool.parameters;
+        if (listArguments(schema).length === 0)
+            return tool;
+        const before = tool.prepareArguments;
+        return {
+            ...tool,
+            prepareArguments: (args) => prepareListArguments(tool.name, schema, before !== undefined ? before(args) : args),
+        };
+    });
+}

package/dist/regenerate/loop.js

@@ -597,7 +597,14 @@ export function createWorkLoop(options) {
                 }
                 return {
                     report: released !== undefined ? `${report}\n\n${released}` : report,
-                    details: { passed: result.landed, landed: result.landed, ...(released !== undefined ? { released: true } : {}), ...(result.story !== undefined ? { story: result.story } : {}) },
+                    details: {
+                        passed: result.landed,
+                        landed: result.landed,
+                        ...(released !== undefined ? { released: true } : {}),
+                        ...(result.story !== undefined ? { story: result.story } : {}),
+                        // The spec gaps its agents met, for a headless run to say - in the chat the report puts them to the person.
+                        ...(result.specGaps !== undefined && result.specGaps.length > 0 ? { specGaps: result.specGaps } : {}),
+                    },
                 };
             },
         });
@@ -1240,17 +1247,21 @@ export function createWorkLoop(options) {
                 startAgain(entry, `it now requires ${requires.join(", ")}, which its code was not built on`);
             return loop.bringUp(plainFile, request);
         },
-        async fromScratch(plainFile, request = {}) {
+        async fromScratch(plainFile, { chain, ...request } = {}) {
             const file = resolve(options.cwd, plainFile);
-            // Where its code lives: the tips its module is built in, or - none built yet - its own codebase.
-            const codebases = chainsFor(file).map(tipOf);
+            // Where its code lives: the tips its module is built in, or - none built yet - its own codebase. The whole chain:
+            // every codebase in those chains, bottom first - a tip taken back to nothing is otherwise started from a copy of
+            // the code below it.
+            const chains = chainsFor(file);
+            const codebases = [...new Map((chain === true ? chains.flat() : chains.map(tipOf)).map((entry) => [entry.buildDir, entry])).values()];
             for (const entry of codebases) {
                 if (modules.get(entry.buildDir)?.running !== undefined)
                     throw new Error(`${entry.moduleName} has a pulse running: halt it, or ask again once it is done.`);
             }
+            const why = chain === true ? "asked to be regenerated from scratch, with its whole chain" : "asked to be regenerated from scratch";
             for (const entry of codebases)
                 if (started(entry))
-                    startAgain(entry, "asked to be regenerated from scratch");
+                    startAgain(entry, why);
             return loop.bringUp(plainFile, request);
         },
         halt(target, reason) {
@@ -1511,7 +1522,7 @@ export function describeModules(statuses, options = {}) {
                 `  Ask the user whether to start ${codebases.join(", ")} over, and say why: ${codebases.join(", ")} was built without ` +
                     `${requires.join(", ")}, so no change to its code can bring ${requires.join(", ")} in - its code and conformance ` +
                     "tests are taken out, kept in its history, and built again from the bottom of the chain. Only if they agree, " +
-                    `call regenerate with ${basename(status.plainFile)} and from_scratch.`,
+                    `call regenerate with ${basename(status.plainFile)} and from_scratch: "module".`,
             ];
     };
     return statuses
@@ -1565,7 +1576,7 @@ const defaultConformanceRunner = async (job, onDelta) => {
         writeTestsRecord(result.conformanceDir, job.planned.step.tree);
         recordHistory(job.buildDir, `conformance tests: ${job.planned.title}`);
     }
-    return { landed: result.passed, report: describeSpecDiffConformance(result) };
+    return { landed: result.passed, report: describeSpecDiffConformance(result), ...(result.specGaps !== undefined ? { specGaps: result.specGaps } : {}) };
 };
 /** A job as a spec diff render, landed on its unit tests: conformance is a track of its own. */
 const defaultRunner = async (job, onDelta) => {
@@ -1581,7 +1592,9 @@ const defaultRunner = async (job, onDelta) => {
         onDelta,
     });
     // Landed code can be tried.
-    return { landed: result.passed, report: withTryItLine(describeSpecDiff(result), result.passed && result.restructured !== true), story: codeStory(result) };
+    return { landed: result.passed, report: withTryItLine(describeSpecDiff(result), result.passed && result.restructured !== true), story: codeStory(result),
+        ...(result.specGaps !== undefined ? { specGaps: result.specGaps } : {}),
+    };
 };
 /** How a code pulse went, for its line in the notes: the rounds it took, its test runs, what the debugger found. */
 export function codeStory(result) {

package/dist/regenerate/plain-palette.js

@@ -1,38 +1,46 @@
-/** On a dark surface - turri-dark's #0f0f0f, pi's dark ones. Every colour at least 7:1 on it, and 4.5:1 on the fills. */
+/**
+ * On a dark surface - turri-dark's abyss, #0a0f1a, pi's dark ones - in the design system's colours alone: a section's
+ * header in pink, a concept in neon, text in quotes or backticks in siesta tan. Every colour at least 7:1 on abyss and 4.8:1 on the blue whale fill
+ * of an added line; on the eggplant of a removed one, the design system's only fill of that warmth, its pinks and
+ * grauzone drop to 3.7:1.
+ */
 const DARK = {
     roles: {
-        section: { colour: "#fcd34d", bold: true },
-        concept: { colour: "#7dd3fc" },
-        link: { colour: "#c4b5fd", underline: true },
-        literal: { colour: "#fdba74" },
-        keyword: { colour: "#f9a8d4", bold: true },
-        module: { colour: "#5eead4" },
-        comment: { colour: "#b4bfcf", italic: true },
-        bullet: { colour: "#b4bfcf" },
+        section: { colour: "#ff7fa6", bold: true },
+        concept: { colour: "#5ce1e6" },
+        link: { colour: "#f4f7f9", underline: true },
+        literal: { colour: "#e9d8c8" },
+        keyword: { colour: "#f4f7f9", bold: true },
+        module: { colour: "#f4f7f9" },
+        comment: { colour: "#85a3b2", italic: true },
+        bullet: { colour: "#85a3b2" },
     },
-    added: "#86efac",
-    removed: "#fca5a5",
-    addedFill: "#1f4d2e",
-    removedFill: "#5c2323",
-    muted: "#808080",
+    added: "#5ce1e6",
+    removed: "#ff7fa6",
+    addedFill: "#1e3442",
+    removedFill: "#732553",
+    muted: "#85a3b2",
 };
-/** On a light surface - turri-light's white, pi's light ones. Every colour at least 7:1 on it, and 5:1 on the fills. */
+/**
+ * On a light surface - turri-light's white, pi's light ones - in the design system's deep colours, the only ones it has
+ * that read on white. Every colour at least 7:1 on white, and 5:1 on the neon hover and siesta tan fills.
+ */
 const LIGHT = {
     roles: {
-        section: { colour: "#0a1fd4", bold: true },
-        concept: { colour: "#155e75" },
-        link: { colour: "#6d28d9", underline: true },
-        literal: { colour: "#92400e" },
-        keyword: { colour: "#9d174d", bold: true },
-        module: { colour: "#065f46" },
-        comment: { colour: "#475569", italic: true },
-        bullet: { colour: "#475569" },
+        section: { colour: "#3e5a6b", bold: true },
+        concept: { colour: "#732553" },
+        link: { colour: "#1e3442", underline: true },
+        literal: { colour: "#1e3442" },
+        keyword: { colour: "#0a0f1a", bold: true },
+        module: { colour: "#1e3442" },
+        comment: { colour: "#3e5a6b", italic: true },
+        bullet: { colour: "#3e5a6b" },
     },
-    added: "#166534",
-    removed: "#991b1b",
-    addedFill: "#d3f5dc",
-    removedFill: "#fcd9d9",
-    muted: "#6b7280",
+    added: "#1e3442",
+    removed: "#732553",
+    addedFill: "#8eebee",
+    removedFill: "#e9d8c8",
+    muted: "#3e5a6b",
 };
 const rgb = (hex) => {
     const value = Number.parseInt(hex.slice(1), 16);
@@ -57,17 +65,24 @@ const fillWith = (hex, text, truecolor) => {
     return `${on}${text.replace(/\x1b\[(?:0|49)?m/g, (reset) => `${reset}${on}`)}\x1b[49m`;
 };
 /**
- * Brand blue, for what is shown to do what its spec says - regen's ◆. Brand blue itself on a light surface, 9.72:1
- * on white; on a dark one, where it is illegible (1.97:1 on brand black - see docs/theming.md), its tint 55% of the way
- * to white, 7.34:1 on brand black.
+ * Neon, for what is shown to do what its spec says - regen's ◆: the design system's colour for what can be followed,
+ * 12.2:1 on abyss. On a light surface, where neon is illegible (1.6:1 on white), blue whale, 12.9:1 on white.
  */
-export const BRAND_BLUE = { light: "#0a1fd4", dark: "#919aec" };
-/** Text in brand blue on a theme - its tint on a dark one - in as many colours as the terminal has. */
-export function brandBlue(theme) {
-    const colour = theme.appearance === "light" ? BRAND_BLUE.light : BRAND_BLUE.dark;
+export const BRAND_NEON = { light: "#1e3442", dark: "#5ce1e6" };
+/**
+ * Pink, the one pink thing in a view - the banner's wordmark: 6.54:1 on abyss. On a light surface, where pink is
+ * too pale (2.9:1 on white), eggplant, 9.9:1 on white.
+ */
+export const BRAND_PINK = { light: "#732553", dark: "#ff5c8d" };
+const brandInk = (colours) => (theme) => {
+    const colour = theme.appearance === "light" ? colours.light : colours.dark;
     const truecolor = (theme.getColorMode?.() ?? "truecolor") === "truecolor";
     return (text) => paintWith({ colour, bold: true }, text, truecolor);
-}
+};
+/** Text in neon on a theme - blue whale on a light one - in as many colours as the terminal has. */
+export const brandNeon = brandInk(BRAND_NEON);
+/** Text in pink on a theme - eggplant on a light one - in as many colours as the terminal has. */
+export const brandPink = brandInk(BRAND_PINK);
 /** How a spec diff is painted on a theme: its palette by whether the theme is dark or light, in as many colours as the terminal has. */
 export function plainPaint(theme) {
     const palette = theme.appearance === "light" ? LIGHT : DARK;

package/dist/regenerate/regenerate.js

@@ -281,9 +281,11 @@ export async function renderSpecDiff(options) {
     const work = createWorkLedger();
     // What it checks its own work with: the diff its reviewer is shown, and whether a test catches a bug - neither decides anything.
     const gate = createUnitGate(buildDir, scripts.unit);
+    // can_it_fail, for the coding agent and its reviewer: on unless mutation-testing says otherwise.
+    const mutationTesting = scripts.unit !== undefined && configForSpec(tip.plainFile).mutationTesting !== false;
     const selfChecks = [
         createMyDiffTool({ dir: buildDir, what: "code" }),
-        ...(scripts.runOn === "copy" ? [createCanItFailTool({ buildDir, script: scripts.unit })] : []),
+        ...(mutationTesting ? [createCanItFailTool({ buildDir, script: scripts.unit })] : []),
     ];
     // A server it built, it can start and try from outside - stopped when it is done.
     const services = createServiceTools({ dir: buildDir });
@@ -499,7 +501,7 @@ export async function renderSpecDiff(options) {
                 forChange: true,
                 ...(options.cases !== undefined ? { cases: options.cases } : {}),
                 label: `${moduleName} spec change`,
-                ...(scripts.runOn === "copy" ? { unitScript: scripts.unit } : {}),
+                ...(mutationTesting ? { 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) => {