@turri-dev/cli 0.1.3 → 0.1.4-next.01530aa

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

@@ -378,6 +378,8 @@ export function createWorkLoop(options) {
             const waiting = (why) => ({ module: entry.moduleName, why: `waiting for ${entry.moduleName}: ${why}` });
             if (below.running !== undefined)
                 return waiting(below.running.planned.track === "conformance" ? "its conformance tests are being written" : "the code it is built on is not built yet");
+            if (below.held !== undefined)
+                return waiting("you halted it - nothing is built on it until it is asked for again");
             const spec = chainSpec(below.chain);
             if (codeWork(builtOf(below), spec.tree).length > 0)
                 return waiting("the code it is built on is not built yet");
@@ -486,6 +488,11 @@ export function createWorkLoop(options) {
     /** A dry run's first jobs, by codebase: what each would start. */
     const firsts = new Map();
     const startJob = (state, spec, from, planned) => {
+        // Halted while it was being planned: the plan is made, nothing starts.
+        if (state.held !== undefined) {
+            state.why = state.held.why;
+            return;
+        }
         const tip = tipEntry(state);
         if (options.dryRun === true) {
             firsts.set(tip.buildDir, { spec: planned.track === "conformance" ? spec : { ...spec, tree: planned.step.tree }, planned });
@@ -590,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 } : {}),
+                    },
                 };
             },
         });
@@ -773,16 +787,37 @@ export function createWorkLoop(options) {
         }
         return states;
     };
+    /** A codebase the loop no longer looks after: nothing of it is shown, planned or waited for. */
+    const forget = (state) => {
+        const key = tipEntry(state).buildDir;
+        modules.delete(key);
+        order.splice(order.indexOf(key), 1);
+    };
     const lookAll = async () => {
+        // A .plain file taken out of the project is asked for no more, and a codebase whose module's file is gone is
+        // forgotten - nothing running there - rather than shown waiting for a plan it will never have.
+        for (const file of [...asked.keys()])
+            if (!existsSync(file))
+                asked.delete(file);
+        for (const key of [...order]) {
+            const state = modules.get(key);
+            if (state.running === undefined && !existsSync(tipEntry(state).plainFile))
+                forget(state);
+        }
         const now = active();
         looking = now;
         for (const key of order) {
             const state = modules.get(key);
-            // A codebase left behind - built on since - is not looked at, unless a job of it is still running.
+            // A codebase left behind - built on since - is not looked at, unless a job of it is still running; what it had
+            // planned, or waited for, is no longer shown.
             if (now.has(state) || state.running !== undefined)
                 await look(state);
-            else
+            else {
                 state.why = "left behind: the code is built on further up the chain, where changes to it are made";
+                state.waitsFor = undefined;
+                state.plan = undefined;
+                state.conformancePlan = undefined;
+            }
         }
     };
     const look = async (state) => {
@@ -793,6 +828,12 @@ export function createWorkLoop(options) {
         }
         catch (error) {
             state.why = `its spec does not parse: ${error instanceof Error ? error.message : String(error)}`;
+            // Not planned from a spec that does not parse: what it waited for, and the plan, were the spec's before.
+            state.waitsFor = undefined;
+            if (state.running === undefined) {
+                state.plan = undefined;
+                state.conformancePlan = undefined;
+            }
             return;
         }
         const specKey = keyOf(spec);
@@ -845,6 +886,11 @@ export function createWorkLoop(options) {
             return;
         }
         hashResources(state, spec);
+        if (state.held !== undefined) {
+            state.why = state.held.why;
+            state.waitsFor = undefined;
+            return;
+        }
         if (state.halted !== undefined) {
             if (state.halted.specKey === specKey) {
                 state.why = state.halted.why;
@@ -1005,14 +1051,18 @@ export function createWorkLoop(options) {
         return state;
     };
     const loop = {
-        async bringUp(plainFile, request = {}) {
+        async bringUp(plainFile, given = {}) {
+            const { specChange, ...request } = given;
             const files = codebasesOf(resolve(options.cwd, plainFile));
             for (const file of files)
                 asked.set(file, { ...asked.get(file), ...request });
             const states = withParseCache(() => files.flatMap((file) => chainsFor(file).flatMap((chain) => toBuild(chain).map((entry) => track(chain.slice(0, chain.indexOf(entry) + 1), file, request)))));
-            // Asked again, a halted codebase is tried again.
-            for (const state of states)
+            // Asked again, a halted codebase is tried again - one the person halted too, unless only its spec changed.
+            for (const state of states) {
                 state.halted = undefined;
+                if (specChange !== true)
+                    state.held = undefined;
+            }
             await tick();
             return [...new Set(states)].map(statusOf);
         },
@@ -1080,7 +1130,7 @@ export function createWorkLoop(options) {
                 report.scheduled = (state.scheduled ?? []).map((group) => ({ frids: group.specs.map((touched) => touched.frid), unbuilt: group.unbuilt }));
                 if (state.running !== undefined)
                     report.running = { jobId: state.running.jobId, title: state.running.planned.title };
-                const halted = state.halted?.why ?? state.conformanceHalted?.why;
+                const halted = state.held?.why ?? state.halted?.why ?? state.conformanceHalted?.why;
                 if (halted !== undefined)
                     report.why = halted;
                 if (state.startOver !== undefined)
@@ -1167,6 +1217,7 @@ export function createWorkLoop(options) {
                 }
                 state.conformanceHalted = undefined;
                 state.halted = undefined;
+                state.held = undefined;
             }
             await tick();
             return [...new Set(states)].map((state) => {
@@ -1196,19 +1247,67 @@ 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) {
+            const named = target.trim();
+            // A planned row's module - the longest name its id starts with, as a name may hold a hyphen - or a module by its name.
+            const state = order
+                .map((key) => modules.get(key))
+                .filter((candidate) => {
+                const name = tipEntry(candidate).moduleName;
+                return named === name || named.startsWith(`planned-${name}-`);
+            })
+                .sort((a, b) => tipEntry(b).moduleName.length - tipEntry(a).moduleName.length)[0];
+            if (state === undefined)
+                return undefined;
+            const tip = tipEntry(state);
+            if (state.running === undefined && !existsSync(tip.plainFile)) {
+                forget(state);
+                asked.delete(tip.plainFile);
+                return `${tip.moduleName} is no longer in the project - ${basename(tip.plainFile)} is gone - so nothing was to be built there: it is dropped from the regeneration.`;
+            }
+            const planned = statusOf(state).planned.length;
+            const said = reason !== undefined && reason.trim() !== "" ? ` (${reason.trim()})` : "";
+            state.held = { why: `you halted it${said} - nothing runs here until it is asked for again` };
+            state.why = state.held.why;
+            state.waitsFor = undefined;
+            state.plan = undefined;
+            state.conformancePlan = undefined;
+            const running = state.running;
+            if (running !== undefined && running.stopping !== true) {
+                running.stopping = true;
+                options.registry.stop(running.jobId, `Halted by you${said}: what it had done is rolled back, and nothing more runs in ${tip.moduleName} until it is asked for again.`);
+            }
+            const above = order
+                .map((key) => modules.get(key))
+                .filter((other) => other !== state && looking.has(other) && other.chain.some((entry) => entry.buildDir === tip.buildDir))
+                .map((other) => tipEntry(other).moduleName);
+            void tick();
+            return [
+                `Halted ${tip.moduleName}${said}:`,
+                running !== undefined ? ` its running pulse ${running.jobId} is being stopped, and what it had done rolled back;` : "",
+                planned > 0 ? ` its ${planned} planned pulse${planned === 1 ? "" : "s"} will not start.` : " nothing more is planned there.",
+                " Pulses that landed stay.",
+                above.length > 0 ? ` ${above.join(", ")} ${above.length === 1 ? "waits" : "wait"} for it.` : "",
+                ` It runs again only when asked for - regenerate ${basename(tip.plainFile)} - a spec change does not start it.`,
+            ].join("");
+        },
         status() {
             return order.map((key) => statusOf(modules.get(key)));
         },
@@ -1423,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
@@ -1477,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) => {
@@ -1493,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/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) => {