@turri-dev/cli 0.1.2 → 0.1.3-next.26f08c5

package/dist/chat-skills.js

@@ -11,7 +11,7 @@
  * message, a deploy - is offered as pi offers it.
  */
 /** What a skill says it is about, that turri covers: ***plain specs and their testing scripts. */
-const ABOUT_PLAIN = /\*\*\*plain|\\\*\\\*\\\*plain|\.plain\b|\bcodeplain\b|functional specs?\b|testing scripts?\b|run_unittests|run_conformance_tests/i;
+const ABOUT_PLAIN = /\*\*\*plain|\\\*\\\*\\\*plain|\.plain\b|functional specs?\b|testing scripts?\b|run_unittests|run_conformance_tests/i;
 /** Whether turri has what a pi skill offers: it runs a skill of that name itself, or the skill is about ***plain. */
 export function supersededByTurri(skill, turriRuns) {
     return turriRuns.has(skill.name) || ABOUT_PLAIN.test(`${skill.name} ${skill.description}`);

package/dist/cli-options.js

@@ -0,0 +1,82 @@
+import { conformanceOption, overrideConfig, reviewOption, splitModelSpec } from "./config.js";
+/**
+ * The command line of turri's commands: their words, and the options that stand for the config's own keys - kept apart
+ * from the commands that use them, so a light one (doctor) reads them as a regenerate does without loading it.
+ */
+/**
+ * A command's arguments: the positional ones, `--flag`s and `--name value` options (`--name=value` too) -
+ * `--coding-model` is `--model`. An option it does not take is refused, rather than taking the word after it, and so is an
+ * option with no value - the end of the words, or another option where its value should be.
+ */
+export function parseArgs(argv, flags, usage, valued = []) {
+    const positional = [];
+    const options = {};
+    const takes = new Set(["--model", ...valued]);
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const [name, inline] = arg.startsWith("--") && arg.includes("=") ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)] : [arg, undefined];
+        const option = name === "--coding-model" ? "--model" : name;
+        if (arg === "-h" || arg === "--help") {
+            console.log(usage);
+            process.exit(0);
+        }
+        else if (flags.includes(option) && inline === undefined)
+            options[option.slice(2)] = "yes";
+        else if (takes.has(option)) {
+            // Its value is the next word - never another option, which would be taken as the value and lost.
+            const value = inline ?? argv[i + 1];
+            if (value === undefined || (inline === undefined && value.startsWith("--"))) {
+                console.error(`${usage}\n\n${name} needs a value${value !== undefined ? `, not the option ${value}` : ""} - ${name}=<value> gives one that starts with --.`);
+                process.exit(1);
+            }
+            if (inline === undefined)
+                i += 1;
+            options[option.slice(2)] = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`${usage}\n\nNo such option: ${name}.`);
+            process.exit(1);
+        }
+        else
+            positional.push(arg);
+    }
+    return { positional, options };
+}
+/** An option's value, as parseArgs left it: refused when it was given with none. */
+export function optionValue(options, name) {
+    const value = options[name];
+    if (name in options && (value === undefined || value.trim() === ""))
+        failOption(`--${name} needs a value`);
+    return value;
+}
+/**
+ * The options that stand for the config's own keys - `--harness-model`, `--coding-model` (`--model`), `--judge-model`
+ * and, as asked, `--review` and `--conformance-tests` - read as if config.turri.yaml had them, in their place in the
+ * order the config resolves them in (overrideConfig): a run, or doctor, with them is the same as one with them in the
+ * file. Exits on a value it cannot read.
+ */
+export function configKeyOptions(options, take = {}) {
+    const tests = take.conformance === true ? optionValue(options, "conformance-tests") : undefined;
+    const setting = tests !== undefined ? conformanceOption(tests) : undefined;
+    if (tests !== undefined && setting === undefined)
+        failOption(`--conformance-tests takes all, chosen, module or false, not ${tests}`);
+    const reviewed = take.review === true ? optionValue(options, "review") : undefined;
+    const review = reviewed !== undefined ? reviewOption(reviewed) : undefined;
+    if (reviewed !== undefined && review === undefined)
+        failOption(`--review takes true or false, not ${reviewed}`);
+    const model = (name, key) => {
+        const spec = optionValue(options, name);
+        return spec !== undefined ? { [key]: splitModelSpec(spec) } : {};
+    };
+    overrideConfig({
+        ...model("harness-model", "harnessModel"),
+        ...model("model", "codingModel"),
+        ...model("judge-model", "judgeModel"),
+        ...(setting !== undefined ? { conformanceTests: setting } : {}),
+        ...(review !== undefined ? { review } : {}),
+    });
+}
+function failOption(message) {
+    console.error(message);
+    process.exit(1);
+}

package/dist/config.js

@@ -49,7 +49,7 @@ import { projectDirOf } from "./regenerate/paths.js";
  * as `coding-model`, which it was before there were two.
  *
  * Keys are written with dashes; underscores are read the same (`conformance_tests`). Keys it
- * does not know - a codeplain `config.yaml`, read while it is the old file, carries several - are ignored, and so is a value of
+ * does not know - another tool's `config.yaml`, read while it is the old file, may carry several - are ignored, and so is a value of
  * the wrong type. Everything is optional, and what is given on the command line wins.
  *
  * A project whose parts do not share a stack - a Python backend and a React frontend beside each other - keeps a
@@ -385,6 +385,9 @@ function text(value) {
  * not parse.
  */
 export function readProjectConfig(root, stack) {
+    return withRunOverrides(readStackedConfig(root, stack));
+}
+function readStackedConfig(root, stack) {
     const project = readConfigFile(join(root, projectConfigFile(root)));
     if (stack === undefined)
         return project;
@@ -403,6 +406,25 @@ export function readProjectConfig(root, stack) {
     merged.models = joinModels(project.models, own.models);
     return withoutUndefined(merged);
 }
+let runOverrides = {};
+/** Read a command's options as the config's keys for the rest of this process. */
+export function overrideConfig(overrides) {
+    runOverrides = { ...overrides };
+}
+/** `--conformance-tests <value>`: the config's own values - all (or true), chosen, module, false. Undefined for anything else. */
+export function conformanceOption(value) {
+    return conformanceSetting(value);
+}
+/** `--review <value>`: the config's own, true or false. Undefined for anything else. */
+export function reviewOption(value) {
+    const word = value.trim().toLowerCase();
+    return word === "true" ? true : word === "false" ? false : undefined;
+}
+/** The config with the command's options in place of the keys they name. */
+function withRunOverrides(config) {
+    const given = Object.entries(runOverrides).filter(([, value]) => value !== undefined);
+    return given.length === 0 ? config : { ...config, ...Object.fromEntries(given) };
+}
 /** A module's `models:` over the project's, role by role - each entry taking what it leaves out from the project's; the chat's the project's alone. */
 function joinModels(project, own) {
     if (own === undefined)

package/dist/conform-cli.js

@@ -1,4 +1,5 @@
-import { parseArgs, runLoop } from "./loop-cli.js";
+import { parseArgs } from "./cli-options.js";
+import { headlessOptions, runLoop } from "./loop-cli.js";
 const USAGE = `usage: turri conform <file.plain> [frid ...] [options]
 
 Writes and runs the black-box conformance tests of a module's functional specs - those named, or
@@ -8,8 +9,14 @@ module inherits, a failure fixed in the test or the code, whichever is wrong. Ev
 tested goes in one pulse, as far as the size guardrail lets.
 
   --one-by-one             a pulse a functional spec instead
-  --model <provider/id>    model for the agents (default: config.turri.yaml's coding-model)`;
-const { positional, options } = parseArgs(process.argv.slice(2), ["--one-by-one"], 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
+  --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
+  --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), ["--one-by-one"], USAGE, ["--build-dir", "--report", "--harness-model", "--judge-model", "--review"]);
+const { report, buildDir } = headlessOptions(options, false);
 const [plainFile, ...frids] = positional;
 if (plainFile === undefined) {
     console.error(USAGE);
@@ -17,10 +24,11 @@ if (plainFile === undefined) {
 }
 runLoop({
     plainFile,
-    ...(options.model !== undefined ? { model: options.model } : {}),
+    ...(buildDir !== undefined ? { buildDir } : {}),
+    ...(report !== undefined ? { report } : {}),
+    command: ["conform", ...process.argv.slice(2)],
     ask: (loop) => loop.conformance(plainFile, {
         ...(frids.length > 0 ? { frids } : {}),
-        ...(options.model !== undefined ? { model: options.model } : {}),
         ...(options["one-by-one"] !== undefined ? { separately: true } : {}),
     }),
 }).catch((error) => {

package/dist/environment.js

@@ -68,3 +68,22 @@ export function turriOnPath() {
     const found = which.status === 0 ? which.stdout.trim().split("\n")[0] : undefined;
     return found === "" ? undefined : found;
 }
+/** turri's version, and the commit when it runs from a clone. */
+export 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,
+    };
+}

package/dist/extension.js

@@ -52,6 +52,7 @@ import { registerStacks } from "./stacks.js";
 import { catalogueLine, discoverSkills, leftOutNote } from "./skills.js";
 import { supersededByTurri } from "./chat-skills.js";
 import { TURRI_IDENTITY } from "./identity.js";
+import { turriIdentity } from "./environment.js";
 import { conformanceChooser } from "./regenerate/choose-conformance.js";
 import { answerSideQuestion, askWithAsides, BTW_HOW, runningSkill, skillRunStarted, skillSessionText, transcriptOf } from "./btw.js";
 import { createJobRegistry, defaultParallelJobs, describeJob, formatDuration, pulseName, shouldWait, STOPPED_ON_REQUEST, } from "./regenerate/jobs.js";
@@ -2158,7 +2159,8 @@ function registerBranding(pi, ruleCount, skills) {
         if (data === undefined)
             return undefined;
         const lines = [
-            `${theme.fg("accent", "turri")}  ${theme.fg("muted", `v${data.version}`)}`,
+            `${theme.fg("accent", "turri")}  ${theme.fg("muted", `v${data.version}`)}` +
+                (data.commit !== undefined ? theme.fg("dim", `  from a clone, ${data.commit}${data.changed ? " with changes" : ""}`) : ""),
             theme.fg("text", "regenerative software - the code is regenerated from the spec"),
             theme.fg("muted", `${data.rules} rules · ${data.skills} skill${data.skills === 1 ? "" : "s"}` +
                 (data.projectSkills !== undefined && data.projectSkills > 0 ? ` (${data.projectSkills} the project's)` : "") +
@@ -2180,8 +2182,11 @@ function registerBranding(pi, ruleCount, skills) {
         if (ctx.hasUI)
             animateJellyfish(ctx);
         try {
+            const identity = turriIdentity();
             pi.appendEntry(BANNER_ENTRY, {
-                version: packageVersion(),
+                version: identity.version ?? "0.0.0",
+                commit: identity.git_commit?.slice(0, 7),
+                changed: identity.git_dirty === true,
                 rules: ruleCount,
                 skills: skills.skills.length,
                 projectSkills: skills.skills.filter((skill) => skill.origin !== "turri").length,
@@ -2361,12 +2366,3 @@ function jellyfishArt(appearance, ink) {
         return undefined;
     }
 }
-function packageVersion() {
-    try {
-        const raw = readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8");
-        return JSON.parse(raw).version ?? "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-}

package/dist/init-config.js

@@ -292,7 +292,7 @@ function whose(vendor, bedrock) {
     return `${VENDORS[choice.maker].label}'s on Amazon Bedrock (${choice.region})`;
 }
 /**
- * What a config.yaml in `folder` says that turri reads too - codeplain's testing scripts, say - by turri's names
+ * What a config.yaml in `folder` says that turri reads too - another tool's testing scripts, say - by turri's names
  * (`template_dir` read as `template-dir`), in the file's order; and the keys it leaves, turri reading none of them. The
  * two models are the vendor's, so they are not taken.
  */
@@ -338,7 +338,7 @@ export function initConfig(dir, options = {}) {
     const existing = existsSync(path) && options.force !== true;
     const { harness, coding } = modelsOf(vendor, options.bedrock);
     const lines = modelLines(harness, coding);
-    // A new file takes what a config.yaml beside it - codeplain's - says that turri reads too: its testing scripts, say.
+    // A new file takes what a config.yaml beside it - another tool's, say - says that turri reads too: its testing scripts, say.
     const shared = existing ? { carried: [], left: [] } : sharedWithLegacy(folder);
     const config = existing
         ? withModels(readFileSync(path, "utf8"), lines)
@@ -384,7 +384,7 @@ const USAGE = [
     "a mix of Anthropic and Google, the starting point for any provider pi supports. On amazon-bedrock, --maker and",
     "--region say whose models and where (anthropic: global, us, eu, jp, au; openai: global, us) - asked when not given.",
     "A config.turri.yaml already there keeps everything but its two models; --force writes the whole of it again. A new",
-    "one takes from a config.yaml beside it - codeplain's - the keys turri reads too, its testing scripts say, and leaves",
+    "one takes from a config.yaml beside it - another tool's, say - the keys turri reads too, its testing scripts say, and leaves",
     "config.yaml as it is.",
 ].join("\n");
 /** Ask until the answer is one `read` takes. */

package/dist/loop-cli.js

@@ -1,20 +1,24 @@
 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 { resolve, sep } from "node:path";
+import { configForSpec, inheritModel, modelOnly, modelSpec, projectModels, readProjectConfig, roleModel, ROLE_THINKING, splitModelSpec, } 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";
+import { createWorkLoop, describeModules, functionalityCompletion, promptOf } from "./regenerate/loop.js";
+import { MODULES_DIR, projectDirOf } from "./regenerate/paths.js";
+import { exportModule } from "./regenerate/release.js";
+import { listFiles } from "./regenerate/testing.js";
+import { startRunReport } from "./run-report.js";
+import { configKeyOptions, optionValue } from "./cli-options.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
+ * and exit 1 when any failed or a module is not complete. 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) {
@@ -24,8 +28,42 @@ export async function runLoop(options) {
     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);
+    // The models as the config has them - with a command's own options read as its keys (headlessOptions), as the chat reads them.
+    const model = modelSpec(projectModels(project).coding);
     const projectDir = projectDirOf(plainFile);
+    const buildDir = options.buildDir !== undefined && options.dryRun !== true ? resolve(options.buildDir) : undefined;
+    if (buildDir !== undefined)
+        refuseBuildDir(buildDir, projectDir);
+    // The code, exported into --build-dir as the process exits - however it exits - before the report's last write.
+    let exported;
+    if (buildDir !== undefined) {
+        process.once("exit", () => {
+            exported = exportCode(plainFile, buildDir);
+            console.error(exported.exported === true ? `The code is in ${buildDir} (${String(exported.module)} at ${String(exported.commit)}).` : `Nothing exported to ${buildDir}: ${String(exported.why)}`);
+        });
+    }
+    const report = options.report !== undefined && options.dryRun !== true
+        ? startRunReport({
+            file: options.report,
+            command: options.command ?? process.argv.slice(2),
+            specFile: plainFile,
+            projectDir,
+            ...(buildDir !== undefined ? { buildDir } : {}),
+            conformanceTests: conformanceLabel(project.conformanceTests),
+            review: project.review === true,
+            models: reportModels(project, model),
+        })
+        : undefined;
+    try {
+        return await runLoopReporting({ ...options, plainFile, project, model, projectDir, reporter: report, exported: () => exported });
+    }
+    catch (error) {
+        report?.crashed(error);
+        throw error;
+    }
+}
+async function runLoopReporting(options) {
+    const { plainFile, project, model, projectDir, reporter: report } = options;
     // Each job as it starts and as it ends - the transcript of each is in .turri/jobs/.
     const seen = new Map();
     const registry = createJobRegistry({
@@ -47,18 +85,28 @@ export async function runLoop(options) {
             console.log(`${mark} ${job.id} ${pulseName(job)} - ${job.status}`);
             if (job.status !== "succeeded")
                 console.log(c.dim((job.announce ?? job.report ?? job.error ?? "").trim()));
+            report?.write();
         },
     });
     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 } : {}) }),
+        // Under conformance-tests: chosen or module, the chooser decides as a pulse ends, as in the chat - on the harness
+        // model, else the coding model: never pi's own default, which may be one this account cannot reach.
+        onChoose: conformanceChooser({ model: () => planner ?? model, ...(options.dryRun === true ? { dryRun: true } : {}) }),
+    });
+    report?.attach({
+        jobs: () => registry.list(),
+        modules: () => moduleStates(loop.drift(plainFile)),
+        completion: () => functionalityCompletion(plainFile),
+        atExit: () => {
+            const exported = options.exported();
+            return exported !== undefined ? { build_dir_export: exported } : undefined;
+        },
     });
     let planned = await options.ask(loop);
     console.log(describeModules(planned, { for: "command line" }));
@@ -68,6 +116,13 @@ export async function runLoop(options) {
         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");
+        // No terminal and no --start-over: no one to ask, so the run stops here rather than build nothing and say it is done.
+        if (options.startOver !== true && process.stdin.isTTY !== true) {
+            const message = `${why}\nThere is no terminal to ask whether to start over: run it again with --start-over to start over without asking.`;
+            console.error(c.red(message));
+            report?.end("incomplete", message);
+            process.exit(1);
+        }
         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) {
@@ -91,31 +146,104 @@ export async function runLoop(options) {
     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`))}`);
+    // Complete: every codebase regenerated from the spec as it is, its conformance tests too - nothing halted, nothing
+    // waiting for a start over, nothing the planner left out.
+    const unfinished = moduleStates(loop.drift(plainFile)).filter((module) => module.state !== "complete");
+    const verdict = failed.length > 0
+        ? c.red(c.bold(`${failed.length} job${failed.length === 1 ? "" : "s"} failed`))
+        : unfinished.length > 0
+            ? c.red(c.bold(`not complete: ${unfinished.map((module) => `${module.module}${module.why !== undefined ? ` - ${module.why}` : ""}`).join("; ")}`))
+            : c.green(c.bold("all jobs done"));
+    console.log(`\n${verdict}`);
     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);
+    report?.end(failed.length > 0 ? "failed" : unfinished.length > 0 ? "incomplete" : "completed");
+    process.exit(failed.length === 0 && unfinished.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);
+/** How each codebase stands, from what is left to regenerate there. */
+export function moduleStates(reports) {
+    return reports.map((report) => {
+        const state = report.running !== undefined
+            ? "running"
+            : report.startOver !== undefined
+                ? "start_over_needed"
+                : report.why !== undefined
+                    ? "halted"
+                    : report.code === null && (report.conformance === null || report.conformance === undefined) && report.scheduled.length === 0
+                        ? "complete"
+                        : "incomplete";
+        const why = state === "start_over_needed"
+            ? `built without ${report.startOver.requires.join(", ")}, which it now requires: run with --start-over`
+            : state === "incomplete"
+                ? report.code !== null && report.code !== undefined
+                    ? "its code is not regenerated from the spec as it is"
+                    : "its conformance tests are not written for what is built"
+                : report.why;
+        return { module: report.module, state, ...(why !== undefined ? { why } : {}) };
+    });
+}
+/**
+ * A --build-dir the export would wipe something in: the project, a folder holding it, or one inside plain_modules.
+ * Anything else is the export's own, its contents replaced as the run ends.
+ */
+function refuseBuildDir(buildDir, projectDir) {
+    const within = (dir, of) => dir === of || dir.startsWith(`${of}${sep}`);
+    const why = within(projectDir, buildDir)
+        ? "it holds the project, and the export replaces what is in it"
+        : within(buildDir, resolve(projectDir, MODULES_DIR))
+            ? `it is inside ${MODULES_DIR}, which turri regenerates in`
+            : undefined;
+    if (why === undefined)
+        return;
+    console.error(`--build-dir ${buildDir} cannot be used: ${why}. Name a folder of its own - the code is exported there as the run ends.`);
+    process.exit(1);
+}
+/** The furthest-built codebase's last commit, exported into `dir` - or why nothing was. */
+function exportCode(plainFile, dir) {
+    try {
+        const deployment = exportModule(plainFile, undefined, dir);
+        const files = listFiles(dir).length;
+        // Its history began, and nothing landed in it yet: only the harness's own files, which are left out.
+        if (files === 0)
+            return { exported: false, dir, why: `nothing has landed in ${deployment.moduleName} yet: its codebase holds no code` };
+        return { exported: true, dir, module: deployment.moduleName, commit: deployment.commit, files };
+    }
+    catch (error) {
+        return { exported: false, dir, why: error instanceof Error ? error.message : String(error) };
     }
-    return { positional, options };
+}
+/** `conformance-tests:` as the report says it - not set is false. */
+function conformanceLabel(setting) {
+    return setting === true ? "all" : setting === "chosen" || setting === "module" ? setting : "false";
+}
+/** The models of the three roles as this run uses them: the coding model given, the others as they fall back - each with the level it thinks at. */
+function reportModels(project, model) {
+    const coding = splitModelSpec(model);
+    const harness = projectModels(project).harness ?? modelOnly(model);
+    // As the judge's agent finds it: its models: entry over judge-model over models.default, else the coding model's.
+    const judge = inheritModel(roleModel(project, "judge"), modelOnly(model)) ?? {};
+    const choice = (given, fallback) => ({
+        ...(given.model !== undefined ? { model: given.model } : {}),
+        ...((given.thinking ?? fallback) !== undefined ? { thinking: given.thinking ?? fallback } : {}),
+    });
+    return {
+        harness: choice(harness, ROLE_THINKING.planner),
+        coding: choice(coding, ROLE_THINKING.coding),
+        judge: choice(judge, ROLE_THINKING.judge),
+    };
+}
+/**
+ * The options every command that regenerates takes for a headless run: `--report` and `--build-dir`, and the config's
+ * own keys (configKeyOptions) - `--harness-model`, `--coding-model` (`--model`), `--judge-model`, `--review` and, where
+ * `conformance` is true, `--conformance-tests` - read as if config.turri.yaml had them. Exits on a value it cannot read.
+ */
+export function headlessOptions(options, conformance) {
+    configKeyOptions(options, { conformance, review: true });
+    const report = optionValue(options, "report");
+    const buildDir = optionValue(options, "build-dir");
+    return { ...(report !== undefined ? { report } : {}), ...(buildDir !== undefined ? { buildDir } : {}) };
 }
 /** Yes or no at the terminal - or undefined when there is none, and so no one to ask. */
 async function askAtTerminal(title, body) {

package/dist/pi-launch.js

@@ -9,19 +9,28 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { main, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { ProcessTerminal } from "@earendil-works/pi-tui";
 import "./terminal-images.js";
 /**
  * pi, started the way its own CLI starts it, for `turri`.
  *
- * The one difference: pi's startup header - its version, key hints and the list of every
- * loaded skill, extension and theme - is left out, because turri shows its own. pi only
- * takes that from the `quietStartup` setting, and a setting would quiet every `pi` on the
- * machine, so it is answered for this run instead. `--verbose` still shows it.
+ * What differs is pi's own branding, because turri shows its own: its startup header - its
+ * version, key hints and the list of every loaded skill, extension and theme - its update notice
+ * and its tab title. pi only takes the header from the `quietStartup` setting, and a setting would
+ * quiet every `pi` on the machine, so it is answered for this run instead. `--verbose` still shows it.
  */
 const args = process.argv.slice(2);
 if (!args.includes("--verbose")) {
     SettingsManager.prototype.getQuietStartup = () => true;
 }
+// pi's "Update Available" notice is left out: the pi turri runs is its pinned dependency, which `pi update`
+// does not touch - it moves when turri does.
+process.env.PI_SKIP_VERSION_CHECK = "1";
+// The terminal's tab title: pi writes `π - <folder>` (its APP_TITLE, a constant), turri a jellyfish and its name.
+const setTitle = ProcessTerminal.prototype.setTitle;
+ProcessTerminal.prototype.setTitle = function (title) {
+    setTitle.call(this, title.replace(/^π(?= |$)/, "🪼 turri"));
+};
 // pi's own keys stand: a new line is shift+enter or ctrl+j. turri's side panel is on ctrl+h (job-panel.ts PANEL_KEY).
 // What pi's CLI does before main: the process title, pi's environment markers, the HTTP
 // dispatcher. Not exported, so loaded from the file - beside pi's entry point, wherever npm put it.

package/dist/pi.js

@@ -6,7 +6,7 @@ import { inheritModel, stackOf, readProjectConfig, ROLE_THINKING, roleModel, rol
 import { maskToolResults } from "./regenerate/masking.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, reportUsage, } from "./regenerate/activity.js";
+import { currentStopSignal, describeToolCall, describeToolResult, JobStoppedError, shownName, reportActivity, reportNow, reportAgent, reportTranscript, reportModelEvent, reportUsage, } from "./regenerate/activity.js";
 import { debugLogOf, startDebugLog } from "./regenerate/debug-log.js";
 let thinkingSource;
 /**
@@ -262,6 +262,7 @@ async function askOnce(session, text, onDelta) {
     transcript({ kind: "prompt", text: task !== undefined ? `${task}\n\n${text}` : text });
     if (agent !== undefined)
         reportAgent({ label: agent.label, ...(agent.model !== undefined ? { model: agent.model } : {}), turns: 1 });
+    reportModelEvent({ kind: "turn", ...modelEventOf(session) });
     const unsubscribe = session.subscribe((event) => {
         if (event.type === "message_update") {
             const update = event.assistantMessageEvent;
@@ -332,6 +333,7 @@ async function askOnce(session, text, onDelta) {
                 reportUsage(spent);
                 if (agent !== undefined)
                     reportAgent({ label: agent.label, usage: spent });
+                reportModelEvent({ kind: "call", ...modelEventOf(session), usage: spent, ms: Date.now() - stepStarted });
             }
             // A provider error counts only if the turn ends on it: a later message that ends well - pi's own retry, the
             // stream picked up again - means it recovered, and the turn's work stands.
@@ -514,6 +516,7 @@ export async function compactIfDue(session) {
     const who = agent?.label ?? "the agent";
     reportActivity(`  compacting ${who}'s work: ${thousands(conversation)} tokens of it, past ${thousands(settings.atTokens)}`);
     try {
+        const compactStarted = Date.now();
         const result = await session.compact(settings.instructions);
         const usage = result.usage;
         if (usage !== undefined) {
@@ -521,7 +524,9 @@ export async function compactIfDue(session) {
             reportUsage(spent);
             if (agent !== undefined)
                 reportAgent({ label: agent.label, usage: spent });
+            reportModelEvent({ kind: "call", ...modelEventOf(session), usage: spent, ms: Date.now() - compactStarted });
         }
+        reportModelEvent({ kind: "compaction", ...modelEventOf(session) });
         if (agent !== undefined)
             reportAgent({ label: agent.label, compactions: 1 });
         reportActivity(`  compacted ${who}'s work${result.estimatedTokensAfter !== undefined ? ` to about ${thousands(result.estimatedTokensAfter)} tokens` : ""}`);
@@ -542,6 +547,13 @@ const agentRoles = new WeakMap();
 function agentOf(session) {
     return agentLabels.get(session);
 }
+/** Who a model event is from: the agent's model as it runs now, its role and its label - an agent with no label too. */
+function modelEventOf(session) {
+    const agent = agentOf(session);
+    const role = agentRoles.get(session);
+    const model = session.model !== undefined ? `${session.model.provider}/${session.model.id}${session.thinkingLevel ? `:${session.thinkingLevel}` : ""}` : agent?.model;
+    return { ...(model !== undefined ? { model } : {}), ...(role !== undefined ? { role } : {}), ...(agent !== undefined ? { label: agent.label } : {}) };
+}
 /**
  * Have this session's turns timed, as an agent a render starts has: `limitMs` each - its role's in the config - or
  * the default.
@@ -700,7 +712,7 @@ export async function createExecutor(opts) {
     if (chosen.model !== undefined) {
         const model = findModel(session, chosen.model);
         if (model === undefined) {
-            throw new Error(`Model '${chosen.model}' is not configured. Check the provider's API key.`);
+            throw new Error(`Model '${chosen.model}' is not a model pi knows: no such id for that provider. \`turri --list-models <search>\` lists the ones it does; one of your own goes in ~/.pi/agent/models.json.`);
         }
         await session.setModel(model);
     }

package/dist/plain/errors.js

@@ -1,4 +1,4 @@
-/** Ports of the exception classes in plain2code_exceptions.py that this parser raises. */
+/** Ports of the exception classes of the Python reference implementation that this parser raises. */
 export class PlainSyntaxError extends Error {
     constructor(message) {
         super(message);

package/dist/plain/files.js

@@ -1,7 +1,7 @@
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { createEnvironment } from "./liquid.js";
-/** Ports of the file_utils.py and plain2code_utils.py helpers this parser needs. */
+/** Ports of the Python reference implementation's file helpers this parser needs. */
 export function openFrom(dirs, fileName) {
     for (const dir of dirs) {
         const fullPath = join(dir, fileName);