@turri-dev/cli 0.1.2-next.48dacfc → 0.1.3-next.17f0f7f

package/dist/regenerate/release.js

@@ -1,5 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { connect } from "node:net";
 import { dirname, join, relative } from "node:path";
 import { HISTORY_DIR } from "./lineage.js";
@@ -38,15 +38,17 @@ export function deployTarget(plainFile, inModule) {
     throw new Error(`Nothing is built yet for ${tip.moduleName}${candidates.length > 1 ? " or the modules it requires" : ""}: there is no code to deploy. Render it first.`);
 }
 /**
- * Export the module's code at its last commit into `dist/<module>`, replacing whatever was there - the
- * harness's own files (what the code is built from, the agents' notes) left out.
+ * Export the module's code at its last commit into `dist/<module>` - or `into`, `turri regenerate --build-dir` -
+ * replacing whatever was there, the harness's own files (what the code is built from, the agents' notes) left out.
  */
-export function exportModule(plainFile, inModule) {
+export function exportModule(plainFile, inModule, into) {
     const { entry, commit, instead } = deployTarget(plainFile, inModule);
     const moduleDir = dirname(entry.buildDir);
-    const dir = distDirFor(projectDirOf(entry.plainFile), entry.moduleName);
-    rmSync(dir, { recursive: true, force: true });
+    const dir = into ?? distDirFor(projectDirOf(entry.plainFile), entry.moduleName);
+    // Emptied, not removed: the folder may be a mount point - a container's volume - that cannot be removed.
     mkdirSync(dir, { recursive: true });
+    for (const entry of readdirSync(dir))
+        rmSync(join(dir, entry), { recursive: true, force: true });
     const exported = spawnSync("bash", ["-o", "pipefail", "-c", 'git --git-dir "$1" archive --format=tar "$2" | tar -x -f - -C "$3"', "export", join(moduleDir, HISTORY_DIR), `${commit}:code`, dir], { encoding: "utf8" });
     if (exported.status !== 0)
         throw new Error(`Could not export ${entry.moduleName}'s code at ${commit.slice(0, 8)}: ${(exported.stderr ?? "").trim()}`);

package/dist/regenerate-cli.js

@@ -1,6 +1,5 @@
 import { CONFIG_FILE, readProjectConfig } from "./config.js";
-import { c } from "./module-report.js";
-import { parseArgs, runLoop } from "./loop-cli.js";
+import { headlessOptions, parseArgs, runLoop } from "./loop-cli.js";
 const USAGE = `usage: turri regenerate [file.plain] [frid ...] [options]
 
 Regenerates the module's code from its spec as it is now, and everything it requires, bottom first, as
@@ -12,33 +11,27 @@ does in the chat with functionalities named: their code rewritten or started ove
 
 The project's config.turri.yaml, in the current directory, gives the defaults: module (the file to
 build when none is given), coding-model (the agents that build), harness-model (the planner), and
-conformance-tests.
+conformance-tests. It exits 0 only when every module is complete: regenerated from the spec as it is,
+its conformance tests too when they are on.
 
   --dry-run                plan the work and print the prompt of the first job, and run nothing (turri glimpse)
-  --start-over             start over, without asking, a codebase regenerated without a module it now requires
+  --start-over             start over, without asking, a codebase regenerated without a module it now requires -
+                           with no terminal to ask and without it, the run stops there
   --from-scratch           delete the module's code and conformance tests (its lineage keeps them) and regenerate all of it
-  --build-dir <dir>        default: plain_modules/<module>/code
-  --model <provider/id>    model for the agents
+  --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner, the conformance chooser, a diagnosis
+  --coding-model <p/id>    its coding-model, --model too: the agents that build; p/id:level for how hard a model thinks
+  --judge-model <p/id>     its judge-model: the judge and the test review
+  --review <true|false>    its review: whether the code and its tests are reviewed once they pass
+  --conformance-tests <all|chosen|module|false>
+                           its conformance-tests: which conformance tests are written and run
+  --build-dir <dir>        as the run ends, however it ends, export the code there: the furthest-built codebase's
+                           last commit, which holds every module it requires - the folder's contents are replaced
+  --report <file.json>     write a report of the run there - outcome, usage, pulses, functional specs completed -
+                           as it starts, as each pulse ends and as it exits (docs/headless.md)
 
   PLAIN_TEMPLATE_DIRS      colon-separated template directories`;
-/** Options of the build this replaced, and what to do instead. */
-const GONE = {
-    force: "to regenerate a functionality again, name it: turri regenerate <file.plain> <frid>",
-    only: "every module the spec requires is built, bottom first",
-    to: "the whole spec is built: stop the jobs to stop partway",
-    from: "every functionality not built is queued; built ones are skipped",
-    "conformance-root": "conformance tests are in plain_modules/<module>/tests",
-    "max-regression-rounds": "each conformance job runs the whole suite",
-    "try-it": "run turri release to try what is regenerated",
-    conformance: `set conformance-tests: in ${CONFIG_FILE}, or turri conform`,
-    "no-conformance": `set conformance-tests: false in ${CONFIG_FILE}`,
-    "template-dir": "set PLAIN_TEMPLATE_DIRS",
-};
-const { positional, options } = parseArgs(process.argv.slice(2), ["--only", "--force", "--conformance", "--no-conformance", "--try-it", "--dry-run", "--start-over", "--from-scratch"], USAGE);
-for (const [name, instead] of Object.entries(GONE)) {
-    if (options[name] !== undefined)
-        console.log(c.dim(`--${name} is no longer an option: ${instead}.`));
-}
+const { positional, options } = parseArgs(process.argv.slice(2), ["--dry-run", "--start-over", "--from-scratch"], USAGE, ["--build-dir", "--report", "--conformance-tests", "--harness-model", "--judge-model", "--review"]);
+const { report, buildDir } = headlessOptions(options, true);
 const named = positional[0] ?? readProjectConfig(process.cwd()).module;
 // Functional specs named after the file: regenerated again though their spec did not change.
 const again = positional.slice(1);
@@ -53,15 +46,16 @@ if (options["from-scratch"] !== undefined && options["dry-run"] !== undefined) {
 }
 runLoop({
     plainFile: named,
-    ...(options.model !== undefined ? { model: options.model } : {}),
-    ...(options["build-dir"] !== undefined ? { buildDir: options["build-dir"] } : {}),
+    ...(buildDir !== undefined ? { buildDir } : {}),
+    ...(report !== undefined ? { report } : {}),
+    command: ["regenerate", ...process.argv.slice(2)],
     dryRun: options["dry-run"] !== undefined,
     startOver: options["start-over"] !== undefined,
     ask: (loop) => again.length > 0
-        ? loop.regenerateAgain(named, again, options.model !== undefined ? { model: options.model } : {})
+        ? loop.regenerateAgain(named, again)
         : options["from-scratch"] !== undefined
-            ? loop.fromScratch(named, options.model !== undefined ? { model: options.model } : {})
-            : loop.bringUp(named, options.model !== undefined ? { model: options.model } : {}),
+            ? loop.fromScratch(named)
+            : loop.bringUp(named),
 }).catch((error) => {
     console.error(error instanceof Error ? error.message : error);
     process.exit(1);

package/dist/run-report.js

@@ -0,0 +1,309 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { PACKAGE_ROOT } from "./environment.js";
+import { onModelEvent } from "./regenerate/activity.js";
+/**
+ * A headless run's report: one JSON file, `turri regenerate --report <file>`, saying what the run did - how it ended,
+ * what it spent, which pulses landed, how many functional specs are completed - for a benchmark or CI to read rather
+ * than the log. See docs/headless.md for every field.
+ *
+ * Written when the run starts, again as each pulse ends, and last as the process exits - however it exits: done, a
+ * pulse failed, a crash, a signal. A process killed outright (SIGKILL) leaves the one written as the last pulse ended.
+ * Each write is atomic: the file is written beside it and renamed over it, so a reader never sees half of one.
+ */
+export const REPORT_SCHEMA_VERSION = 1;
+const SIGNALS = { 129: "SIGHUP", 130: "SIGINT", 143: "SIGTERM" };
+const emptyTotals = () => ({
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_read_tokens: 0,
+    cache_write_tokens: 0,
+    cost_usd: 0,
+    llm_calls: 0,
+    agent_turns: 0,
+    compactions: 0,
+    model_seconds: 0,
+});
+function addUsage(totals, usage) {
+    if (usage === undefined)
+        return;
+    totals.input_tokens += usage.input;
+    totals.output_tokens += usage.output;
+    totals.cache_read_tokens += usage.cacheRead;
+    totals.cache_write_tokens += usage.cacheWrite;
+    totals.cost_usd += usage.cost;
+}
+/** An event's counts - a call, a turn, a compaction, the model's time - and, with `tokens`, its usage too. */
+function addEvent(totals, event, tokens) {
+    if (event.kind === "call") {
+        totals.llm_calls += 1;
+        totals.model_seconds += (event.ms ?? 0) / 1000;
+        if (tokens)
+            addUsage(totals, event.usage);
+    }
+    else if (event.kind === "turn")
+        totals.agent_turns += 1;
+    else
+        totals.compactions += 1;
+}
+function sumTotals(a, b) {
+    const sum = emptyTotals();
+    for (const key of Object.keys(sum))
+        sum[key] = a[key] + b[key];
+    return sum;
+}
+/** Tidied for reading: the cost to a millionth of a dollar, the time to a tenth of a second - float sums otherwise show their noise. */
+function rounded(totals) {
+    return { ...totals, cost_usd: Math.round(totals.cost_usd * 1e6) / 1e6, model_seconds: Math.round(totals.model_seconds * 10) / 10 };
+}
+/** turri's version, and the commit when it runs from a clone. */
+function turriIdentity() {
+    let version = null;
+    try {
+        version = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version ?? null;
+    }
+    catch {
+        /* no package.json: left out */
+    }
+    if (!existsSync(join(PACKAGE_ROOT, ".git")))
+        return { version, git_commit: null, git_dirty: null };
+    const commit = spawnSync("git", ["-C", PACKAGE_ROOT, "rev-parse", "HEAD"], { encoding: "utf8" });
+    const status = spawnSync("git", ["-C", PACKAGE_ROOT, "status", "--porcelain", "--untracked-files=no"], { encoding: "utf8" });
+    return {
+        version,
+        git_commit: commit.status === 0 ? commit.stdout.trim() : null,
+        git_dirty: status.status === 0 ? status.stdout.trim() !== "" : null,
+    };
+}
+const pulseKind = (job) => (job.kind === "regenerate" ? "code" : job.kind);
+const firstLines = (text) => {
+    const trimmed = text?.trim();
+    return trimmed === undefined || trimmed === "" ? null : trimmed.length > 1000 ? `${trimmed.slice(0, 1000)}…` : trimmed;
+};
+/** Write a file whole or not at all: beside it first, then renamed over it. */
+export function writeAtomically(file, text) {
+    mkdirSync(dirname(file), { recursive: true });
+    const temporary = join(dirname(file), `.${basename(file)}.${process.pid}.tmp`);
+    try {
+        writeFileSync(temporary, text);
+        renameSync(temporary, file);
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
+export function startRunReport(options) {
+    const file = resolve(options.file);
+    const startedAt = Date.now();
+    const identity = turriIdentity();
+    const events = [];
+    const stopListening = onModelEvent((event) => events.push(event));
+    let sources = { jobs: () => [] };
+    let ended;
+    let crash;
+    let exitParts;
+    let finishedAt;
+    const fromProject = (path) => relative(options.projectDir, path) || ".";
+    const attempt = (read) => {
+        if (read === undefined)
+            return undefined;
+        try {
+            return read();
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const usageOf = (jobs) => {
+        const ids = new Set(jobs.map((job) => job.id));
+        const kindOf = new Map(jobs.map((job) => [job.id, pulseKind(job)]));
+        // In pulses: their tokens as each job adds them up - what its pulse line prints - and their calls from the events.
+        const inPulses = emptyTotals();
+        for (const job of jobs)
+            addUsage(inPulses, job.usage);
+        const outside = emptyTotals();
+        const byModel = {};
+        const byRole = {};
+        const byKind = {};
+        for (const job of jobs)
+            addUsage((byKind[pulseKind(job)] ??= emptyTotals()), job.usage);
+        for (const event of events) {
+            const inPulse = event.job !== undefined && ids.has(event.job);
+            addEvent(inPulse ? inPulses : outside, event, !inPulse);
+            addEvent((byModel[event.model ?? "unknown"] ??= emptyTotals()), event, true);
+            addEvent((byRole[event.role ?? "unknown"] ??= emptyTotals()), event, true);
+            if (inPulse)
+                addEvent((byKind[kindOf.get(event.job)] ??= emptyTotals()), event, false);
+        }
+        const each = (table) => Object.fromEntries(Object.entries(table).map(([key, totals]) => [key, rounded(totals)]));
+        return {
+            total: rounded(sumTotals(inPulses, outside)),
+            in_pulses: rounded(inPulses),
+            outside_pulses: rounded(outside),
+            by_model: each(byModel),
+            by_role: each(byRole),
+            by_pulse_kind: each(byKind),
+        };
+    };
+    const pulsesOf = (jobs, now) => {
+        const callsOf = new Map();
+        for (const event of events)
+            if (event.job !== undefined)
+                addEvent(callsOf.get(event.job) ?? callsOf.set(event.job, emptyTotals()).get(event.job), event, false);
+        const list = jobs.map((job) => {
+            const landed = job.status === "succeeded" && job.details?.landed === true;
+            const ran = job.status !== "queued";
+            const usage = sumTotals(callsOf.get(job.id) ?? emptyTotals(), (() => {
+                const tokens = emptyTotals();
+                addUsage(tokens, job.usage);
+                return tokens;
+            })());
+            return {
+                id: job.id,
+                module: job.module ?? null,
+                number: job.pulse ?? null,
+                kind: pulseKind(job),
+                title: job.title ?? job.summary,
+                status: job.status,
+                landed,
+                failed_for_good: job.failedForGood === true,
+                started_at: ran ? new Date(job.startedAt).toISOString() : null,
+                duration_seconds: ran ? Math.round(((job.finishedAt ?? now) - job.startedAt) / 100) / 10 : null,
+                usage: rounded(usage),
+                agents: job.agents.map((agent) => ({
+                    label: agent.label,
+                    model: agent.model ?? null,
+                    turns: agent.turns,
+                    compactions: agent.compactions,
+                    input_tokens: agent.usage.input,
+                    output_tokens: agent.usage.output,
+                    cache_read_tokens: agent.usage.cacheRead,
+                    cache_write_tokens: agent.usage.cacheWrite,
+                    cost_usd: Math.round(agent.usage.cost * 1e6) / 1e6,
+                })),
+                log_file: job.logFile !== undefined ? fromProject(job.logFile) : null,
+                error: job.status === "failed" || job.status === "stopped" ? firstLines(job.error) : null,
+            };
+        });
+        const ran = list.filter((pulse) => pulse.status !== "queued");
+        return {
+            counts: {
+                total: ran.length,
+                landed: ran.filter((pulse) => pulse.landed).length,
+                failed: ran.filter((pulse) => pulse.status === "failed").length,
+                stopped: ran.filter((pulse) => pulse.status === "stopped").length,
+                rolled_back: ran.filter((pulse) => !pulse.landed && pulse.status !== "running").length,
+                running: ran.filter((pulse) => pulse.status === "running").length,
+                not_started: list.length - ran.length,
+            },
+            list,
+        };
+    };
+    const functionalitiesOf = (counts) => {
+        if (counts === undefined)
+            return null;
+        const modules = counts.flatMap((chain) => chain.modules.map((module) => ({
+            module: module.module,
+            specified: module.specified,
+            completed: module.completed,
+            conformance_tested: module.conformanceTested,
+            incomplete_frids: module.incomplete,
+        })));
+        return {
+            total: {
+                specified: modules.reduce((sum, module) => sum + module.specified, 0),
+                completed: modules.reduce((sum, module) => sum + module.completed, 0),
+                conformance_tested: modules.reduce((sum, module) => sum + module.conformance_tested, 0),
+            },
+            modules,
+            codebases: counts.map((chain) => fromProject(chain.codebase)),
+        };
+    };
+    const statusAt = (exitCode) => {
+        const signal = exitCode !== undefined ? (SIGNALS[exitCode] ?? null) : null;
+        if (crash !== undefined)
+            return { status: "crashed", signal: null, error: crash };
+        if (ended !== undefined)
+            return { status: ended.status, signal: null, error: ended.error ?? null };
+        if (exitCode === undefined)
+            return { status: "running", signal: null, error: null };
+        if (signal !== null)
+            return { status: "interrupted", signal, error: null };
+        return { status: exitCode === 0 ? "completed" : "crashed", signal: null, error: exitCode === 0 ? null : `exited with ${exitCode} before the run ended` };
+    };
+    const build = (exitCode) => {
+        const now = finishedAt ?? Date.now();
+        // In the order they started; one queued again as another never ran, and is not a pulse of its own.
+        const jobs = (attempt(sources.jobs) ?? []).filter((job) => job.replacedBy === undefined).sort((a, b) => a.sequence - b.sequence);
+        const outcome = statusAt(exitCode);
+        const projectRoot = options.projectDir;
+        return {
+            schema_version: REPORT_SCHEMA_VERSION,
+            turri: identity,
+            command: options.command,
+            spec_file: resolve(options.specFile),
+            project_dir: projectRoot,
+            build_dir: options.buildDir !== undefined ? resolve(options.buildDir) : null,
+            conformance_tests: options.conformanceTests,
+            review: options.review ?? null,
+            models: {
+                ...Object.fromEntries(Object.entries(options.models).map(([role, choice]) => [role, { model: choice.model ?? null, thinking: choice.thinking ?? null }])),
+                observed: Object.fromEntries([...new Set(events.map((event) => event.role ?? "unknown"))].sort().map((role) => [role, [...new Set(events.filter((event) => (event.role ?? "unknown") === role).map((event) => event.model ?? "unknown"))].sort()])),
+            },
+            started_at: new Date(startedAt).toISOString(),
+            finished_at: finishedAt !== undefined ? new Date(finishedAt).toISOString() : null,
+            duration_seconds: Math.round((now - startedAt) / 100) / 10,
+            outcome: {
+                status: outcome.status,
+                exit_code: exitCode ?? null,
+                signal: outcome.signal,
+                error: outcome.error,
+                modules: attempt(sources.modules) ?? null,
+            },
+            usage: usageOf(jobs),
+            pulses: pulsesOf(jobs, now),
+            functionalities: functionalitiesOf(attempt(sources.completion)),
+            ...(exitParts ?? {}),
+            logs: {
+                jobs_dir: fromProject(join(projectRoot, ".turri", "jobs")),
+                debug_dir: fromProject(join(projectRoot, ".turri", "debug")),
+                sessions_dir: fromProject(join(projectRoot, ".turri", "sessions")),
+            },
+        };
+    };
+    const write = (exitCode) => {
+        try {
+            writeAtomically(file, `${JSON.stringify(build(exitCode), null, 2)}\n`);
+        }
+        catch (error) {
+            console.error(`Could not write the run report ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    if (options.onExit !== false) {
+        process.on("uncaughtExceptionMonitor", (error) => {
+            crash ??= error instanceof Error ? (error.stack ?? error.message) : String(error);
+        });
+        process.once("exit", (code) => {
+            finishedAt = Date.now();
+            exitParts = attempt(sources.atExit);
+            stopListening();
+            write(code);
+        });
+    }
+    write();
+    return {
+        attach(given) {
+            sources = given;
+        },
+        end(status, error) {
+            ended = { status, ...(error !== undefined ? { error } : {}) };
+        },
+        crashed(error) {
+            crash ??= error instanceof Error ? error.message : String(error);
+        },
+        write: () => write(),
+        build,
+    };
+}

package/dist/setup.js

@@ -33,6 +33,17 @@ export function checkShell(found = spawnSync("bash", ["--version"], { stdio: "ig
         fix: platform === "win32" ? "install Git for Windows (Git Bash), and put its bash on the PATH" : "install bash with your system's package manager",
     };
 }
+/** git: each module's history, which every pulse starts from and lands in, and the spec diffs the work is planned from. */
+export function checkGit(found = spawnSync("git", ["--version"], { stdio: "ignore", windowsHide: true }).status === 0) {
+    if (found)
+        return { level: "ok", name: "git", detail: "on the PATH - each module's history, and the spec diffs" };
+    return {
+        level: "missing",
+        name: "git",
+        detail: "not on the PATH - each module's history is a git repository, and the work is planned from git diffs",
+        fix: "install git with your system's package manager",
+    };
+}
 /** Which wall is up under the agents' commands, and - where none starts - why, and how to give it one. */
 export function checkSandbox(wall = sandboxAvailable(), platform = process.platform) {
     if (wall.kind === "seatbelt")
@@ -157,7 +168,7 @@ export async function checkProjectModels(project, access) {
     });
 }
 async function allChecks(options = {}) {
-    const checks = [checkNode(), checkShell(), checkSandbox(), await checkProvider(), checkPath(), ...checkGlobal()];
+    const checks = [checkNode(), checkShell(), checkGit(), checkSandbox(), await checkProvider(), checkPath(), ...checkGlobal()];
     // In a project: what it needs of this machine, and whether its models answer.
     const project = process.cwd();
     if (hasProjectConfig(project) || existsSync(join(project, "plain_modules"))) {

package/dist/spec-diff-cli.js

@@ -2,16 +2,24 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { checkPlainFile } from "./plain/check.js";
 import { applySpecDiff, revertSpecDiff } from "./regenerate/regenerate.js";
-import { parseArgs, runLoop } from "./loop-cli.js";
+import { headlessOptions, parseArgs, runLoop } from "./loop-cli.js";
 const USAGE = `usage: turri spec-diff <file.plain> <diff-file> [options]
 
 Applies a change to the specs, given as a git diff of the .plain files, and builds it: the headless
 counterpart of regenerate, given a diff. The diff is applied first, unless it is already in; then, as
 turri regenerate does, what is left to build is planned into jobs and built.
 
-  --model <provider/id>    model for the agents (default: config.turri.yaml's coding-model)
-  --start-over             start over, without asking, a codebase regenerated without a module it now requires`;
-const { positional, options } = parseArgs(process.argv.slice(2), ["--start-over"], USAGE);
+  --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner, the conformance chooser, a diagnosis
+  --coding-model <p/id>    its coding-model, --model too: the agents that build
+  --start-over             start over, without asking, a codebase regenerated without a module it now requires
+  --judge-model <p/id>     its judge-model: the judge and the test review
+  --review <true|false>    its review: whether the code and its tests are reviewed once they pass
+  --conformance-tests <all|chosen|module|false>
+                           its conformance-tests: which conformance tests are written and run
+  --build-dir <dir>        as the run ends, export the code there (see turri regenerate --help)
+  --report <file.json>     write a report of the run there (see turri regenerate --help)`;
+const { positional, options } = parseArgs(process.argv.slice(2), ["--start-over"], USAGE, ["--build-dir", "--report", "--conformance-tests", "--harness-model", "--judge-model", "--review"]);
+const { report, buildDir } = headlessOptions(options, true);
 const [plainFile, diffFile] = positional;
 if (plainFile === undefined || diffFile === undefined) {
     console.error(USAGE);
@@ -28,9 +36,11 @@ if (!check.ok) {
 }
 runLoop({
     plainFile,
-    ...(options.model !== undefined ? { model: options.model } : {}),
     startOver: options["start-over"] !== undefined,
-    ask: (loop) => loop.bringUp(plainFile, options.model !== undefined ? { model: options.model } : {}),
+    ...(buildDir !== undefined ? { buildDir } : {}),
+    ...(report !== undefined ? { report } : {}),
+    command: ["spec-diff", ...process.argv.slice(2)],
+    ask: (loop) => loop.bringUp(plainFile),
 }).catch((error) => {
     console.error(error instanceof Error ? error.message : error);
     process.exit(1);

package/docs/config.md

@@ -5,7 +5,7 @@ is optional: with no file at all, turri finds the testing scripts on its own, tu
 tests on wherever a module has test reqs, and runs on pi's configured model. A project whose
 parts are on different stacks - a backend and a frontend - adds a file per stack,
 `config.turri.<stack>.yaml`, beside it, and chooses the stack to build with (see
-[stacks](#stacks)). turri never writes a `config.yaml`: it may be another tool's - codeplain's - and
+[stacks](#stacks)). turri never writes a `config.yaml`: it may be another tool's, and
 is read only by a project that has no file of turri's yet (see [the old config.yaml](#the-old-configyaml)).
 
 `turri init-config` starts one: the two models, a strong one to talk to and a smaller one to write the code. It
@@ -42,7 +42,7 @@ change one by changing it. The optional ones, which have no value of their own -
 skill that writes them), `module`, `conformance-budget`, `judge-model`, `models` - are there commented out, each with an
 example: uncomment one to use it. A key taken out of the file is still read as the table below says.
 
-Beside a `config.yaml` - codeplain's - the new file takes from it the keys turri reads too, each in its place, its
+Beside a `config.yaml` - another tool's, say - the new file takes from it the keys turri reads too, each in its place, its
 testing scripts above all, and says which it left (see [the old config.yaml](#the-old-configyaml)); `config.yaml`
 is left as it is. A `config.turri.yaml` already there keeps everything but its two models, which it sets - `--force` writes the whole
 file again - and a `config.yaml` turri read until then is copied to it first. It takes a folder other than the current
@@ -133,7 +133,7 @@ models:                              # each agent role's model, thinking and tur
 | `release-after-pulse` | `true` or `false`: whether every pulse that lands code releases it, in the chat, as its last stage - before the module's next pulse starts, whatever the chat is doing: an agent on the coding model looks for the project's release guidance as the chat does (what was passed to `release` this conversation, AGENTS.md, the project's skills) and, when it says to release after a build, does what it says - see [deploy](deploy.md#after-every-pulse). One release a pulse that lands; a release that fails is said in the pulse's report, and what it landed stays | `false` |
 | `unittests-script` | the unit testing script, by path from the project root - it runs the code's static checks too, exiting 80 when only they fail (see [the static checks](regenerating.md#the-static-checks)) | looked for - see below |
 | `conformance-tests-script` | the conformance testing script, by path from the project root | looked for - see below |
-| `prepare-environment-script` | optional, as codeplain has it: run as `<script> <build>` before every run of the conformance testing script, which runs only once it passes - see [the testing scripts](regenerating.md#the-testing-scripts). turri never writes one | the one `prepare_environment*.sh` at the root or in `test_scripts/`, else none |
+| `prepare-environment-script` | optional: run as `<script> <build>` before every run of the conformance testing script, which runs only once it passes - see [the testing scripts](regenerating.md#the-testing-scripts). turri never writes one | the one `prepare_environment*.sh` at the root or in `test_scripts/`, else none |
 | `compact-at` | how many tokens of work - past its instructions - an agent kept through a job holds before the harness compacts it between turns; at least 1000; the project's alone | 100,000 - see [agent sessions](regenerating.md#agent-sessions) |
 | `max-specs-per-pulse` | the most functional specs the planner groups into one pulse - what builds one feature goes together, up to this many; a stack's file wins | 3 |
 | `max-lines-per-pulse` | the most lines of spec in one pulse - its functional specs with the definitions they bring; a group past it is split again, a functional spec a pulse; a stack's file wins | 120 |
@@ -145,7 +145,7 @@ models:                              # each agent role's model, thinking and tur
 | `testing-scripts-run-on` | what the testing scripts run on - always on this machine, in your environment. `in-place`: the real build and tests folders, the script at its own path, from the project - so a script that finds a host codebase from its own path finds it. `copy`: a fresh copy of the code, staged in `plain_modules/.turri/scripts/`, with the script copied beside it; it gives the coding agent `can_it_fail` (see [the testing scripts](regenerating.md#the-testing-scripts)) | `in-place` |
 
 Keys are written with dashes; underscores are read the same (`conformance_tests`). A key turri
-does not know is ignored - a codeplain `config.yaml`, read while it is the old file, carries several - and so is a value of the
+does not know is ignored - another tool's `config.yaml`, read while it is the old file, may carry several - and so is a value of the
 wrong type, as if it were not there. `model:`, from before there were separate models, is read as
 `coding-model`.
 
@@ -218,8 +218,13 @@ They are defaults. What is asked for wins over them:
 | model | wins over the config |
 | --- | --- |
 | harness | `turri --harness-model <m>` (or pi's own `--model`), and pi's `/model` in the conversation |
-| coding | `turri --coding-model <m>`, `engine` in the conversation, and `--model` / `--coding-model` on `turri regenerate`, `conform` and `spec-diff` |
-| judge | `--judge-model` on `turri conform` |
+| coding | `turri --coding-model <m>`, `engine` in the conversation |
+| judge | - |
+
+`turri regenerate`, `conform` and `spec-diff` read `--harness-model`, `--coding-model` (or `--model`),
+`--judge-model`, `--review` and `--conformance-tests` differently: as the keys themselves, as if the file had
+them. Each takes its key's value and its place in the order above - a `models:` entry still wins over it - so a
+headless run is the same as a chat with those keys in the file.
 
 A job keeps the model it was queued with: choosing another holds for what is queued after.
 
@@ -231,8 +236,8 @@ codebase are not run, and no agent is shown the conformance testing script. No k
 `false`: conformance tests are off by default. `all` (or `true`) means on wherever a module has
 `***test reqs***` - a module without them has nothing to write conformance tests from, so it writes
 none, but still keeps the codebase's existing ones passing. Asked in the
-conversation, or with `--conformance` / `--no-conformance` on the command line, a render does
-otherwise.
+conversation (`conform`), or with `--conformance-tests all|chosen|module|false` on `turri regenerate` and
+`spec-diff` - for that run, the file left as it is - a render does otherwise.
 
 `spawn` writes `conformance-tests: false` into a new project unless you ask for tests;
 `brood` asks, whatever the key says, offering what it says first.
@@ -346,8 +351,14 @@ The first time turri itself writes a setting there with `/turri-config`, it copi
 `config.turri.yaml` and each `config.<name>.yaml` to `config.turri.<name>.yaml` first, leaves the old
 files as they are, and from then on reads only the new ones. `turri init-config` copies the stacks'
 files the same way, but writes `config.turri.yaml` as its quick start, taking from `config.yaml` only
-the keys turri reads too - codeplain's `unittests-script`, `conformance-tests-script` and
+the keys turri reads too - `unittests-script`, `conformance-tests-script` and
 `prepare-environment-script`, say - each in its place in the file, and saying which keys it left:
-`template_dir`, `verbose`, `api`, codeplain's alone. The two models are the vendor's, never taken. To change a
+`template_dir`, `verbose`, `api`, the other tool's alone. The two models are the vendor's, never taken. To change a
 setting by hand in such a project, do the same: copy the files to their new names, and edit the
-copies - never `config.yaml`.
+copies - never `config.yaml`. Writing a `config.turri.yaml` of your own beside it is the same move: from then on
+`config.yaml` is not read, its testing scripts with it. For a headless run that only needs conformance tests or
+another judge, or review, those options leave the files alone: `--conformance-tests`, `--judge-model`, `--review true|false`, and the models' too.
+
+Keys turri does not read - another tool's `verbose`, `api-key`, `build-folder`, ... - are ignored without a word, and so
+is a value of the wrong type. A file that does not parse as YAML is read as empty, so its testing scripts are then
+looked for by name.