@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/loop-cli.js

@@ -0,0 +1,132 @@
+import { sweepOrphanedGroups } from "./regenerate/shell.js";
+import { createInterface } from "node:readline/promises";
+import { resolve } from "node:path";
+import { configForSpec, modelSpec, projectModels, readProjectConfig } from "./config.js";
+import { PACKAGE_ROOT } from "./environment.js";
+import { c } from "./module-report.js";
+import { tryItCommand } from "./regenerate/delivery.js";
+import { describeDiagnosis, diagnoseFailure } from "./regenerate/diagnose.js";
+import { createJobRegistry, pulseName } from "./regenerate/jobs.js";
+import { conformanceChooser } from "./regenerate/choose-conformance.js";
+import { createWorkLoop, describeModules, promptOf } from "./regenerate/loop.js";
+import { projectDirOf } from "./regenerate/paths.js";
+/**
+ * What every command that builds - `turri regenerate`, `conform`, `spec-diff` - does around its own
+ * request of the work loop, as the chat does it: the project's models, a job that fails run once more and, failing again,
+ * diagnosed, a line as each job starts and ends; then the loop run until nothing more can start, how each job ended,
+ * and exit 1 when any failed. With `dryRun`, the work is planned and the prompt of the first job each codebase would
+ * start printed, and nothing runs.
+ */
+export async function runLoop(options) {
+    const plainFile = resolve(options.plainFile);
+    // What a turri that was killed left running - commands' process groups - stopped before anything starts.
+    const orphans = sweepOrphanedGroups();
+    if (orphans > 0)
+        console.log(`Stopped ${orphans} process group${orphans === 1 ? "" : "s"} a turri that was killed left running.`);
+    const project = { ...readProjectConfig(process.cwd()), ...Object.fromEntries(Object.entries(configForSpec(plainFile)).filter(([, value]) => value !== undefined)) };
+    const model = options.model ?? modelSpec(projectModels(project).coding);
+    const projectDir = projectDirOf(plainFile);
+    // Each job as it starts and as it ends - the transcript of each is in .turri/jobs/.
+    const seen = new Map();
+    const registry = createJobRegistry({
+        retries: 1,
+        diagnose: async (job, failures, jobLog) => {
+            const diagnosis = await diagnoseFailure({ job, failures, projectDir, harnessDir: PACKAGE_ROOT, jobLog, model: modelSpec(projectModels(project).harness) ?? model });
+            return diagnosis !== undefined ? describeDiagnosis(diagnosis) : undefined;
+        },
+        onChange: (job) => {
+            const line = job.status === "running" ? `${job.stage ?? "started"}` : job.status;
+            if (seen.get(job.id) === line)
+                return;
+            seen.set(job.id, line);
+            if (job.status === "running")
+                console.log(`${c.cyan(`▶ ${job.id}`)} ${pulseName(job)}${job.stage !== undefined ? c.dim(` - ${job.stage}`) : ""}`);
+        },
+        onFinish: (job) => {
+            const mark = job.status === "succeeded" ? c.green("✓") : job.status === "stopped" ? c.dim("■") : c.red("✗");
+            console.log(`${mark} ${job.id} ${pulseName(job)} - ${job.status}`);
+            if (job.status !== "succeeded")
+                console.log(c.dim((job.announce ?? job.report ?? job.error ?? "").trim()));
+        },
+    });
+    const planner = modelSpec(projectModels(project).harness);
+    const loop = createWorkLoop({
+        registry,
+        cwd: process.cwd(),
+        ...(options.buildDir !== undefined ? { buildDir: resolve(options.buildDir) } : {}),
+        ...(model !== undefined ? { modelFor: () => model } : {}),
+        ...(planner !== undefined ? { plannerModel: planner } : {}),
+        ...(options.dryRun === true ? { dryRun: true } : {}),
+        // Under conformance-tests: chosen or module, the chooser decides as a pulse ends, as in the chat.
+        onChoose: conformanceChooser({ model: () => planner, ...(options.dryRun === true ? { dryRun: true } : {}) }),
+    });
+    let planned = await options.ask(loop);
+    console.log(describeModules(planned, { for: "command line" }));
+    // A codebase built without a module it now requires is started over only when the person says so.
+    const toStartOver = planned.filter((status) => status.startOver !== undefined);
+    if (toStartOver.length > 0 && options.dryRun !== true) {
+        const why = toStartOver
+            .map(({ startOver }) => `${startOver.codebases.join(", ")} was built without ${startOver.requires.join(", ")}, which it now requires: no change to its code can bring it in.`)
+            .join("\n");
+        const agreed = options.startOver === true ||
+            (await askAtTerminal("Start over?", `${why}\nStarting over takes its code and conformance tests out - they stay in its history - and builds it again from the bottom of the chain.`));
+        if (agreed === true) {
+            planned = await loop.startOver(plainFile, model !== undefined ? { model } : {});
+            console.log(describeModules(planned, { for: "command line" }));
+        }
+    }
+    if (options.dryRun === true) {
+        for (const first of loop.firsts()) {
+            console.log(`\n${c.bold(`${first.module}: ${first.planned.title}`)}${first.planned.track === "conformance" ? c.dim(" (conformance)") : ""}`);
+            if (first.planned.track === "conformance") {
+                console.log(c.dim("A conformance job's prompt is built from what the code it tests holds once it is built: not shown before."));
+                continue;
+            }
+            console.log((await promptOf(first)) ?? "(no task)");
+        }
+        process.exit(0);
+    }
+    // Until nothing more starts: a choice is made inside the pulse it follows, so draining waits for it.
+    await loop.drain();
+    console.log(`\n${describeModules(loop.status(), { for: "command line" })}`);
+    const ended = registry.list();
+    const failed = ended.filter((job) => job.status === "failed");
+    console.log(`\n${failed.length === 0 ? c.green(c.bold("all jobs done")) : c.red(c.bold(`${failed.length} job${failed.length === 1 ? "" : "s"} failed`))}`);
+    for (const job of [...ended].reverse())
+        console.log(`  ${job.id} ${pulseName(job)}: ${job.status}`);
+    if (ended.some((job) => job.status === "succeeded"))
+        console.log(`\n${tryItCommand(plainFile)}`);
+    process.exit(failed.length === 0 ? 0 : 1);
+}
+/** A command's arguments: the positional ones, and `--name value` / `--flag` options - `--coding-model` is `--model`. */
+export function parseArgs(argv, flags, usage) {
+    const positional = [];
+    const options = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "-h" || arg === "--help") {
+            console.log(usage);
+            process.exit(0);
+        }
+        else if (flags.includes(arg))
+            options[arg.slice(2)] = "yes";
+        else if (arg.startsWith("--"))
+            options[arg === "--coding-model" ? "model" : arg.slice(2)] = argv[++i];
+        else
+            positional.push(arg);
+    }
+    return { positional, options };
+}
+/** Yes or no at the terminal - or undefined when there is none, and so no one to ask. */
+async function askAtTerminal(title, body) {
+    if (process.stdin.isTTY !== true)
+        return undefined;
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await prompt.question(`\n${c.bold(title)}\n${body}\n\n${c.bold("Go ahead? [y/N] ")}`);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        prompt.close();
+    }
+}

package/dist/loop-tools.js

@@ -0,0 +1,225 @@
+import { existsSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { CONFIG_FILE, readProjectConfig } from "./config.js";
+import { checkPlainFile } from "./plain/check.js";
+import { describeDrift, describeModules } from "./regenerate/loop.js";
+import { pulseName } from "./regenerate/jobs.js";
+import { stopDeployed } from "./regenerate/release.js";
+/** How the queue is to be planned, for the work this call queues - see regenerate/steer.ts. */
+export const GUIDANCE_PARAM = Type.Optional(Type.String({
+    description: "How to plan the queue for this work, in a sentence or two - which functional specs go together, what first - as " +
+        "the user said it, or as you understood it. A strong preference for the planner, within its limits. Omit when there is none.",
+}));
+export const WORKING_DIR_PARAM = Type.Optional(Type.String({
+    description: "The folder to render from, relative to where turri was started - as if it had been started there " +
+        "(e.g. \"plain\"). plain_file, build_dir and a spec diff's paths are then relative to it - hubspot.plain, not " +
+        "plain/hubspot.plain. Default: where " +
+        "turri was started.",
+}));
+export const MODEL_PARAM = Type.Optional(Type.String({
+    description: "The model for the agents of this one call: a provider/model-id, or its name as the user said it. " +
+        "Omitted: the model chosen for this kind of work with engine, else the conversation's. " +
+        "To change it for every later render, use engine instead.",
+}));
+export const WAIT_PARAM = Type.Optional(Type.Boolean({
+    description: "Block until the work finishes instead of returning a pulse id. Defaults to false in the " +
+        "interactive TUI and true elsewhere, where a pulse would not outlive the turn.",
+}));
+/**
+ * A render tool's arguments as if turri had been started in `working_dir`: the .plain file
+ * and the build folder made absolute from there, and that folder as `base`.
+ */
+export function fromWorkingDir(cwd, params) {
+    const base = params.working_dir !== undefined && params.working_dir.trim() !== "" ? resolve(cwd, params.working_dir) : cwd;
+    let plainFile = params.plain_file !== undefined ? resolve(base, params.plain_file) : undefined;
+    if (params.plain_file !== undefined && plainFile !== undefined && !existsSync(plainFile)) {
+        // plain/hubspot.plain with working_dir plain: the folder named twice. Taken from where it is.
+        const fromSession = resolve(cwd, params.plain_file);
+        if (existsSync(fromSession))
+            plainFile = fromSession;
+        else {
+            throw new Error(`There is no .plain file at ${plainFile}` +
+                (base !== cwd ? ` - plain_file is relative to working_dir (${relative(cwd, base) || "."}), so do not repeat the folder in it.` : "."));
+        }
+    }
+    return {
+        ...params,
+        base,
+        ...(plainFile !== undefined ? { plain_file: plainFile } : {}),
+        ...(params.build_dir !== undefined ? { build_dir: resolve(base, params.build_dir) } : {}),
+    };
+}
+/** What the loop is doing for a spec's modules, for the conversation - and, waiting, how each module ended. */
+export async function loopReply(loop, statuses, wait) {
+    if (wait)
+        await loop.drain();
+    const now = wait ? loop.status().filter((status) => statuses.some((asked) => asked.plainFile === status.plainFile)) : statuses;
+    const jobIds = now.flatMap((status) => (status.running !== undefined ? [status.running.jobId] : []));
+    const text = [
+        describeModules(now),
+        "",
+        wait
+            ? "Tell the user how it went."
+            : "It regenerates in the background. " +
+                "Nothing to wait for: if what you are doing has a next step - a question to ask, a file to edit, functional specs to conform - take it now, " +
+                "in this same turn, and tell the user what runs and what is planned alongside it, never as a reply that ends your turn. " +
+                "Use pulses with a pulse's id if they ask how it is going.",
+    ].join("\n");
+    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) {
+    const matches = jobs.list().filter((job) => job.id.startsWith(named.trim()));
+    if (matches.length === 0)
+        return `No pulse ${named}. /regen shows them.`;
+    if (matches.length > 1)
+        return `'${named}' matches ${matches.map((job) => job.id).join(", ")}. Give more of the id.`;
+    const target = matches[0];
+    const behind = jobs.list().filter((job) => job.status === "queued" && job.waitingOn.includes(target.id));
+    const stopped = jobs.stop(target.id);
+    if (stopped === undefined)
+        return `${pulseName(target)} is already ${target.status}.`;
+    if (reason !== undefined && reason.trim() !== "")
+        stopped.note = `Halted: ${reason.trim()}`;
+    const queued = behind.length > 0 ? ` Queued behind it, now moving up: ${behind.map((job) => `${pulseName(job)} (${job.id})`).join(", ")}.` : "";
+    // A spec diff's change is in the .plain files: stopping its render does not take it out of the spec.
+    const inSpec = target.kind === "regenerate"
+        ? " Its change is still in the .plain files: nothing more is regenerated in that codebase until the spec changes or it is asked " +
+            "for again with regenerate - then it is regenerated with the rest. To drop the change, take it out of the spec and regenerate; to change " +
+            "how the work is cut or ordered, use steer."
+        : "";
+    return stopped.status === "stopped"
+        ? `Stopped ${pulseName(target)} (${target.id}) before it started.${queued}${inSpec}`
+        : `Stopping ${pulseName(target)} (${target.id}): its agent is being stopped now.${queued}${inSpec}`;
+}
+/** The module to act on: the .plain file named, or the one the project's config.turri.yaml names. */
+function plainFileOf(cwd, given, what) {
+    const located = fromWorkingDir(cwd, given);
+    const named = located.plain_file ?? readProjectConfig(located.base).module;
+    if (named === undefined)
+        throw new Error(`Name the .plain file to ${what}, or set module: in ${CONFIG_FILE}.`);
+    return resolve(located.base, named);
+}
+/** Whether a /regenerate's words ask for the module from scratch: its code deleted, and all of it regenerated again. */
+export function asksFromScratch(words) {
+    return FROM_SCRATCH.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) {
+    return defineTool({
+        name: "regenerate",
+        label: "Regenerate",
+        description: "Regenerate a .plain module's code from its spec as the files have it now - and every module it requires, bottom of the " +
+            "requires chain first. Call it after any change to the spec, by any means: the file tools, a skill, the user in an " +
+            "editor. It takes no diff: what is left to regenerate - from what each module's code was regenerated from to its spec now - is " +
+            "worked out and planned into pulses, and a pulse running that regenerates something the spec no longer wants is stopped and " +
+            "rolled back. Nothing to do where the code is regenerated from the spec as it is. With functionalities named, those are " +
+            "regenerated though their spec did not change - rewritten or started over, better made, what they replace taken out - " +
+            "planned into pulses as any change is, the ones next to each other together; their conformance tests stay as they are.",
+        promptSnippet: "regenerate a module's code from its spec as it is now - after any change to the spec",
+        promptGuidelines: [
+            "Call regenerate after editing a .plain file with the file tools - or when the user says they changed one - instead of working out a diff: turri compares what is regenerated with the spec now.",
+            "regenerate returns at once with what runs and what is planned. Report it, keep talking, and use pulses when the user asks; the pulses report when they finish.",
+            "When the user wants a functionality to come out differently, change its spec - the spec is what persists - then regenerate. When they want ones already built regenerated as their spec stands - better made, on another model, after many patches - name them in functionalities, all in one call.",
+            "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.",
+        ],
+        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" })),
+            working_dir: WORKING_DIR_PARAM,
+            guidance: GUIDANCE_PARAM,
+            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",
+            })),
+            model: MODEL_PARAM,
+            wait: WAIT_PARAM,
+        }),
+        async execute(_id, given, _signal, _onUpdate, ctx) {
+            const plainFile = plainFileOf(options.cwd, given, "regenerate");
+            const check = checkPlainFile(plainFile);
+            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)
+                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)
+                : again.length > 0
+                    ? await loop.regenerateAgain(plainFile, again, request)
+                    : await loop.bringUp(plainFile, request);
+            return loopReply(loop, statuses, options.wait !== undefined ? options.wait(ctx, given.wait) : given.wait === true);
+        },
+    });
+}
+/** drift: what is left to regenerate - planning nothing, starting nothing. */
+export function driftTool(options) {
+    return defineTool({
+        name: "drift",
+        label: "Drift",
+        description: "How far a module's code has drifted from its spec: in each codebase where it lives, what is left to regenerate - the " +
+            "functional specs to add, change, regenerate again or take out, and reqs or definitions alone - and the conformance tests " +
+            "left to write, those scheduled ahead of their code, what is regenerating now, and why nothing is regenerated where nothing is; " +
+            "with nothing left, it says the module is fully regenerated. It plans nothing and starts nothing, and calls no model.",
+        promptSnippet: "drift: what is left to regenerate in a module, code and conformance tests - starting nothing",
+        promptGuidelines: [
+            "Use drift when the user asks what is left to build, whether a module is up to date with its spec, or what changed since it was last regenerated. To see the next pulse's prompt as well, use glimpse.",
+        ],
+        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" })),
+            working_dir: WORKING_DIR_PARAM,
+        }),
+        async execute(_id, given, _signal, _onUpdate, ctx) {
+            const reports = options.loop(ctx).drift(plainFileOf(options.cwd, given, "look at"));
+            return { content: [{ type: "text", text: describeDrift(reports) }], details: { modules: reports.length } };
+        },
+    });
+}
+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" })),
+    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,
+});
+/** With no pulses - the release agent's halt - only what activate started. */
+const HALT_ACTIVATED_PARAMS = Type.Object({ activated: ACTIVATED_PARAM });
+/** halt: stop a pulse, or what activate started. */
+export function haltTool(options) {
+    const { jobs } = options;
+    return defineTool({
+        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."
+            : "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."] : [],
+        parameters: (jobs !== undefined ? HALT_PULSE_PARAMS : HALT_ACTIVATED_PARAMS),
+        async execute(_id, params) {
+            if (params.job_id === undefined && params.activated === undefined) {
+                throw new Error(jobs !== undefined ? "Say what to halt: a job_id, or what activate started (activated)." : 'Say what to stop: its name, or "all" (activated).');
+            }
+            const lines = [];
+            if (params.job_id !== undefined && jobs !== undefined)
+                lines.push(stopJob(jobs, params.job_id, params.reason));
+            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}`}.`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }], details: {} };
+        },
+    });
+}

package/dist/mature-tools.js

@@ -0,0 +1,193 @@
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { formatDuration } from "./regenerate/jobs.js";
+import { readNotes } from "./regenerate/notes.js";
+import { modulesRoot, projectDirOf } from "./regenerate/paths.js";
+/** A time as the notes stamp their lines: "2026-09-28 17:40". */
+export function noteStamp(date) {
+    const two = (n) => String(n).padStart(2, "0");
+    return `${date.getFullYear()}-${two(date.getMonth() + 1)}-${two(date.getDate())} ${two(date.getHours())}:${two(date.getMinutes())}`;
+}
+/** Every module codebase of a project that has working notes. */
+function codebasesOf(project) {
+    const root = modulesRoot(project);
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+        .map((entry) => ({ module: entry.name, buildDir: join(root, entry.name, "code") }))
+        .filter((codebase) => existsSync(codebase.buildDir));
+}
+/** A notes line's stamp, and what it says: "[2026-09-28 17:40 · app 3] text". */
+function stamped(line) {
+    const match = /^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}) · ([^\]]*)\]\s*(.*)$/.exec(line);
+    return match === null ? undefined : { stamp: match[1], source: match[2], text: match[3] };
+}
+/**
+ * What the agents and the harness recorded since `since`: the assumptions and pitfalls in every
+ * codebase's working notes, the diagnosis of every job that failed for good, and every spec that
+ * contradicts itself.
+ */
+export function collectFindings(options) {
+    const since = noteStamp(options.since);
+    const found = [];
+    for (const { module, buildDir } of codebasesOf(options.project)) {
+        // The code's notes, and its conformance tests' beside them.
+        for (const notes of [readNotes(buildDir), readNotes(join(dirname(buildDir), "tests"))]) {
+            for (const [section, kind] of [["assumptions", "assumption"], ["pitfalls", "pitfall"]]) {
+                for (const line of notes[section]) {
+                    const item = stamped(line);
+                    if (item === undefined || item.stamp < since)
+                        continue;
+                    found.push({ kind, where: `${module} (${item.source})`, text: item.text });
+                }
+            }
+        }
+    }
+    for (const job of options.jobs) {
+        if (job.queuedAt < options.since.getTime())
+            continue;
+        if (job.specConflict !== undefined) {
+            const specs = job.specConflict.specs.map((spec) => `${spec.module} ${spec.frid}: ${spec.text.trim()}`).join("\n");
+            found.push({ kind: "conflict", where: `job ${job.id} (${job.summary})`, text: `${job.specConflict.reasons.at(-1) ?? ""}\n${specs}`.trim() });
+        }
+        if (job.diagnosis !== undefined)
+            found.push({ kind: "diagnosis", where: `job ${job.id} (${job.summary})`, text: job.diagnosis.trim() });
+    }
+    return found;
+}
+/** How a job stands, in a line: what it is, how it ended, and the first line of what it said. */
+function jobLine(job) {
+    const said = (job.status === "succeeded" ? job.report : job.error ?? job.report)?.trim().split("\n")[0] ?? "";
+    const flags = [job.diagnosis !== undefined ? "diagnosed" : "", job.specConflict !== undefined ? "spec conflict" : ""].filter(Boolean).join(", ");
+    return `- job ${job.id} · ${job.summary} · ${job.status}${job.status === "running" || job.status === "queued" ? "" : ` after ${formatDuration(job)}`}${flags ? ` · ${flags}` : ""}${said ? ` - ${said.slice(0, 200)}` : ""}`;
+}
+/** Setbacks a build reports as it goes: its stages that say a run failed, a review sent tests back, a judge found something wrong. */
+const SETBACK = /not passing|NOT passing|the review found|is wrong|found the|failed|a spec conflict|contradicts|stuck|cannot|still leave|trying it once more/;
+/** How long a build may run before it counts as struggling on its length alone. */
+export const LONG_BUILD_MS = 30 * 60_000;
+/**
+ * Whether a running build is struggling, and how: sent back four times or more in one loop, five
+ * setbacks or more, a spec conflict raised, a failure being run again, or running far longer than a
+ * build should. Each kind comes once per build - a round count again only every four rounds more.
+ */
+export function struggling(job, now = Date.now()) {
+    if (job.status !== "running")
+        return undefined;
+    const stages = job.transcript.filter((entry) => entry.kind === "stage").map((entry) => entry.text);
+    if (stages.some((stage) => /a spec conflict|contradicts itself/.test(stage)))
+        return { key: "conflict", why: "a spec conflict was raised: two functional specs that may not both hold" };
+    if (stages.some((stage) => /trying it once more/.test(stage)))
+        return { key: "retry", why: "it failed once and is being run again" };
+    const round = /round (\d+) of (\d+)/.exec(job.stage ?? "");
+    if (round !== null && Number(round[1]) >= 4) {
+        const bucket = Math.floor((Number(round[1]) - 4) / 4);
+        return { key: `rounds-${bucket}`, why: `sent back ${round[1]} times of at most ${round[2]}: ${job.stage}` };
+    }
+    const setbacks = stages.filter((stage) => SETBACK.test(stage));
+    if (setbacks.length >= 5)
+        return { key: `setbacks-${Math.floor(setbacks.length / 5)}`, why: `${setbacks.length} setbacks so far - the last: ${setbacks.at(-1)}` };
+    if (now - job.startedAt > LONG_BUILD_MS)
+        return { key: `long-${Math.floor((now - job.startedAt) / LONG_BUILD_MS)}`, why: `running for ${formatDuration(job)}` };
+    return undefined;
+}
+/** A struggling build, for the skill to judge: why, its last stages, and the end of what it printed. */
+function describeStruggle(job, struggle) {
+    const stages = job.transcript.filter((entry) => entry.kind === "stage").map((entry) => entry.text).slice(-12);
+    return [
+        `job ${job.id} · ${job.summary} · ${struggle.why}`,
+        job.diff !== undefined ? `<its change>\n${job.diff.trim().slice(0, 3000)}\n</its change>` : "",
+        `<its last stages>\n${stages.map((stage) => `- ${stage}`).join("\n")}\n</its last stages>`,
+        job.tail.trim() !== "" ? `<the end of its output>\n${job.tail.trim().slice(-2500)}\n</the end of its output>` : "",
+    ]
+        .filter((part) => part !== "")
+        .join("\n");
+}
+export function createMatureTools(options) {
+    const startedAt = options.startedAt ?? new Date();
+    const mine = () => options.jobs.list().filter((job) => job.queuedAt >= startedAt.getTime());
+    /** Findings already handed out, by what they say: each is reported once. */
+    const reported = new Set();
+    let counter = 0;
+    /** The struggles already handed out, by job and what they were - each reported once, again only when it gets longer. */
+    const flagged = new Set();
+    const watchJobs = defineTool({
+        name: "watch_jobs",
+        label: "Watch the builds",
+        description: "Watch the builds queued since this run started, and come back as soon as one is struggling - sent back again and " +
+            "again, setback after setback, a spec conflict raised, a failure being run again, running far too long - or when " +
+            "every one has finished, or when `minutes` have passed. For a struggling build it gives what it has been through: its " +
+            "last stages and the end of its output. Says how every build stands.",
+        promptSnippet: "watch the builds, and come back when one struggles or all are done",
+        parameters: Type.Object({
+            minutes: Type.Optional(Type.Number({ description: "The longest to watch, in minutes. Default 20" })),
+        }),
+        async execute(_id, params, signal) {
+            const limit = Math.max(1, Math.min(120, params.minutes ?? 20)) * 60_000;
+            const deadline = Date.now() + limit;
+            const pending = () => mine().filter((job) => job.status === "running" || job.status === "queued");
+            const newStruggles = () => mine()
+                .map((job) => ({ job, struggle: struggling(job) }))
+                .filter((item) => item.struggle !== undefined && !flagged.has(`${item.job.id}|${item.struggle.key}`));
+            let found = newStruggles();
+            while (found.length === 0 && pending().length > 0 && Date.now() < deadline && signal?.aborted !== true) {
+                await new Promise((resolve) => setTimeout(resolve, 2000));
+                found = newStruggles();
+            }
+            for (const item of found)
+                flagged.add(`${item.job.id}|${item.struggle.key}`);
+            const all = mine().sort((a, b) => a.sequence - b.sequence);
+            const left = pending();
+            const text = [
+                found.length > 0
+                    ? `${found.length} build${found.length === 1 ? " is" : "s are"} struggling:`
+                    : left.length === 0
+                        ? `Every build queued since this run started has finished (${all.length}).`
+                        : `No build is struggling; ${left.length} of ${all.length} are still running or queued - call watch_jobs again.`,
+                ...found.flatMap(({ job, struggle }) => ["", describeStruggle(job, struggle)]),
+                "",
+                "Every build:",
+                ...all.map(jobLine),
+                "",
+                "Read what the builds had to decide themselves with spec_findings; see how far the spec is regenerated with drift.",
+            ].join("\n");
+            return { content: [{ type: "text", text }], details: { pending: left.length, struggling: found.map((item) => item.job.id) } };
+        },
+    });
+    const specFindings = defineTool({
+        name: "spec_findings",
+        label: "What the spec left open",
+        description: "What the builds since this run started recorded where the spec left them to decide or went wrong: every " +
+            "assumption and pitfall in the codebases' working notes, the diagnosis of every job that failed for good, and every " +
+            "spec that contradicts itself - each numbered, and each given once: a finding already handed out is not repeated.",
+        promptSnippet: "where the builds had to guess, or failed on the spec",
+        parameters: Type.Object({
+            plain_file: Type.Optional(Type.String({ description: "A .plain file of the project to read; default the session's folder" })),
+            all: Type.Optional(Type.Boolean({ description: "Every finding since the run started, not only the new ones" })),
+        }),
+        async execute(_id, params) {
+            // The project a spec is built in; with none named, the one the session's folder is.
+            const project = projectDirOf(params.plain_file !== undefined ? resolve(options.cwd, params.plain_file) : join(options.cwd, "session.plain"));
+            const found = collectFindings({ project, jobs: mine(), since: startedAt });
+            const fresh = found.filter((finding) => params.all === true || !reported.has(`${finding.kind}|${finding.where}|${finding.text}`));
+            const numbered = fresh.map((finding) => {
+                reported.add(`${finding.kind}|${finding.where}|${finding.text}`);
+                counter += 1;
+                return { ...finding, id: `f${counter}` };
+            });
+            const text = numbered.length === 0
+                ? "No new findings: the builds since the last look recorded no assumption, no pitfall, no diagnosis and no spec conflict."
+                : [
+                    `${numbered.length} finding${numbered.length === 1 ? "" : "s"}:`,
+                    "",
+                    ...numbered.map((finding) => `${finding.id} · ${finding.kind} · ${finding.where}\n${finding.text}`),
+                ].join("\n\n");
+            return { content: [{ type: "text", text }], details: { findings: numbered } };
+        },
+    });
+    return [watchJobs, specFindings];
+}
+/** The names of the maturing tools, as a skill's allowed-tools names them: its own - it regenerates, halts and reads drift with the conversation's (loop-tools.ts). */
+export const MATURE_TOOLS = ["watch_jobs", "spec_findings"];