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

package/dist/plain/liquid.js

@@ -7,7 +7,7 @@ function currentScope() {
 }
 /**
  * Leading indentation of the line the tag sits on, and whether that line is a
- * comment. Ported from Plain2CodeIncludeNode.render_to_output, which walks
+ * comment. Ported from the reference implementation's include node, which walks
  * backwards from the tag to the start of its line.
  */
 function scanLine(source, start) {
@@ -70,7 +70,7 @@ export function createEnvironment(options) {
                     "    2. The directory specified by --template-dir (if provided)\n" +
                     "    3. The built-in 'standard_template_library' directory\n");
             }
-            // Plain2CodeLoaderMixin.load: rstrip, then re-indent every line to match the
+            // The reference implementation's loader: rstrip, then re-indent every line to match the
             // include site. The rstrip is what stops a block-level include from ending
             // the surrounding list.
             const indented = templateSource.replace(/\s+$/, "").split("\n").join("\n" + " ".repeat(whitespaces));

package/dist/regenerate/activity.js

@@ -84,6 +84,25 @@ export function describeUsage(usage) {
     return usage.cost > 0 ? `${size} tok · $${usage.cost.toFixed(2)}` : `${size} tok`;
 }
 const store = new AsyncLocalStorage();
+const modelListeners = new Set();
+/** Hear of every model call, turn and compaction from now on. Returns what stops it. */
+export function onModelEvent(listener) {
+    modelListeners.add(listener);
+    return () => modelListeners.delete(listener);
+}
+export function reportModelEvent(event) {
+    if (modelListeners.size === 0)
+        return;
+    const job = store.getStore()?.job?.id;
+    for (const listener of modelListeners) {
+        try {
+            listener(job !== undefined ? { ...event, job } : event);
+        }
+        catch {
+            /* a listener that fails does not take the agent down */
+        }
+    }
+}
 export function withActivity(sink, run) {
     return store.run(sink, run);
 }

package/dist/regenerate/loop.js

@@ -89,6 +89,61 @@ function chainsFor(plainFile) {
 function ownBuilt(entry) {
     return (readRecord(entry.buildDir)?.[FUNCTIONAL_REQUIREMENTS] ?? []).length;
 }
+/**
+ * The functional specs of a spec's whole requires chain, completed or not, in the codebase each chain delivers: its
+ * furthest-built module's code - which holds the code of every module below it. A functional spec is completed when that
+ * codebase's code record, as last committed, holds it as the spec has it now - the same text, the linked files it uses
+ * holding the same, no definition it uses changed, not marked to regenerate again. A record moves only when a pulse
+ * lands, its unit tests passing (and its conformance tests, when they are on), so completed is landed and passing.
+ * The modules above the delivered codebase have nothing completed. One entry per chain; planning nothing, calling no model.
+ */
+export function functionalityCompletion(plainFile) {
+    return withParseCache(() => chainsFor(resolve(plainFile)).map((chain) => {
+        let delivered = -1;
+        chain.forEach((entry, index) => {
+            if (readRecord(entry.buildDir) !== null)
+                delivered = index;
+        });
+        const counts = chain.map((entry) => ({ module: entry.moduleName, specified: entry.frids.length, completed: 0, conformanceTested: 0, incomplete: [...entry.frids] }));
+        if (delivered === -1)
+            return { codebase: tipOf(chain).buildDir, modules: counts };
+        const codebase = chain.slice(0, delivered + 1);
+        const tip = tipOf(codebase);
+        const spec = chainSpec(codebase).tree;
+        const record = readRecord(tip.buildDir);
+        const changes = codeWork(record, spec);
+        // Its own: what the work loop would regenerate - new, changed, a concept it uses changed, or marked again.
+        const cases = casesOf(codeTree(record ?? {}), changes, { module: tip.moduleName });
+        const touched = new Set([...cases.add, ...cases.patch, ...cases.again].map((spec) => `${spec.module ?? tip.moduleName}:${spec.frid}`));
+        // The modules' below it: an item the record does not have as the spec has it.
+        for (const change of changes) {
+            if (change.section !== REQUIRED_FUNCTIONAL_SPECS || change.after === undefined)
+                continue;
+            try {
+                const item = JSON.parse(change.after);
+                if (item.module !== undefined && item.frid !== undefined)
+                    touched.add(`${item.module}:${item.frid}`);
+            }
+            catch {
+                /* not an item */
+            }
+        }
+        const specText = (module, frid) => {
+            const own = module === tip.moduleName;
+            const items = spec[own ? FUNCTIONAL_REQUIREMENTS : REQUIRED_FUNCTIONAL_SPECS] ?? [];
+            return (own ? items[Number(frid) - 1] : items.find((item) => item.module === module && item.frid === frid))?.markdown.trim();
+        };
+        codebase.forEach((entry, index) => {
+            const count = counts[index];
+            const completed = entry.frids.filter((frid) => !touched.has(`${entry.moduleName}:${frid}`));
+            const tested = (readRecord(conformanceDirFor(entry.moduleName, modulesRoot(projectDirOf(entry.plainFile))))?.[FUNCTIONAL_REQUIREMENTS] ?? []).filter((item) => item.frid !== undefined && item.markdown.trim() === specText(entry.moduleName, item.frid));
+            count.completed = completed.length;
+            count.conformanceTested = completed.filter((frid) => tested.some((item) => item.frid === frid)).length;
+            count.incomplete = entry.frids.filter((frid) => !completed.includes(frid));
+        });
+        return { codebase: tip.buildDir, modules: counts };
+    }));
+}
 /** The modules of a chain to build: its furthest-built one, and those above it - or, none built, all of it. */
 function toBuild(chain) {
     let from = 0;
@@ -434,7 +489,7 @@ export function createWorkLoop(options) {
             title: planned.title,
             diff: shown.diff,
             ...(state.model !== undefined ? { model: state.model } : {}),
-            lanes: [...moduleLanes(tip.plainFile, options.buildDir)],
+            lanes: [...moduleLanes(tip.plainFile)],
             rerun: `turri regenerate ${relative(options.cwd, tip.plainFile) || basename(tip.plainFile)}`,
             run: async (onDelta) => {
                 // The guardrail: a conformance job tests only code that is built - the code record, read as the job starts, has every functional spec it tests as it tests it.
@@ -1313,7 +1368,6 @@ export async function previewJobs(options) {
         registry: createJobRegistry(),
         cwd: options.cwd,
         dryRun: true,
-        ...(options.buildDir !== undefined ? { buildDir: options.buildDir } : {}),
         ...(options.model !== undefined ? { modelFor: () => options.model } : {}),
         ...(options.plannerModel !== undefined ? { plannerModel: options.plannerModel } : {}),
         ...(options.steering !== undefined ? { steering: options.steering } : {}),

package/dist/regenerate/prompt.js

@@ -24,7 +24,7 @@ function alreadyImplemented(moduleName, own, required) {
  * one another, the current module marked - and each tagged with its module and its id there. A codebase holds the
  * functionalities of every module it is built on, and each module numbers its own from 1, so
  * "functionality 1" alone is ambiguous: the first listed may be base's 1 and the next top's 3.
- * (plain2code's _get_implemented_functional_requirements_prompt_section, as tags.)
+ * (the reference implementation's implemented functional requirements prompt section, as tags.)
  */
 export function functionalitiesByModule(entries, currentModule, status) {
     // In the order given: the bottom of the chain first. A regeneration in a later module's

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,6 @@
 import { CONFIG_FILE, readProjectConfig } from "./config.js";
-import { c } from "./module-report.js";
-import { parseArgs, runLoop } from "./loop-cli.js";
+import { parseArgs } from "./cli-options.js";
+import { headlessOptions, 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 +12,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 +47,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,289 @@
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { turriIdentity } 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 };
+}
+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

@@ -6,6 +6,7 @@ import { ModelRegistry, ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { globalExtensionFile, MIN_NODE, nodeVersionOk, PACKAGE_ROOT, turriOnPath } from "./environment.js";
 import { sandboxAvailable } from "./regenerate/os-sandbox.js";
 import { findTestScripts } from "./regenerate/test-scripts.js";
+import { configKeyOptions, parseArgs } from "./cli-options.js";
 import { hasProjectConfig, readProjectConfig, stackOf } from "./config.js";
 import { checkModels, modelsInUse, piModelAccess } from "./model-check.js";
 import { brand } from "./brand.js";
@@ -33,6 +34,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")
@@ -140,7 +152,7 @@ function checkGlobal() {
 export async function checkProjectModels(project, access) {
     const used = modelsInUse(readProjectConfig(project, stackOf(project)));
     if (used.length === 0) {
-        return [{ level: "missing", name: "Models", detail: "config.turri.yaml names none", fix: "turri init-config writes the two models" }];
+        return [{ level: "missing", name: "Models", detail: "config.turri.yaml names none", fix: "turri init-config writes the two models - or name them here: --harness-model, --coding-model" }];
     }
     let verdicts;
     try {
@@ -156,16 +168,17 @@ export async function checkProjectModels(project, access) {
             : { level: "missing", name, detail: verdict.spec, more: [verdict.problem], fix: verdict.fix };
     });
 }
+/** `modelsGiven`: models named on the command line - checked wherever doctor runs, a project or not. */
 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"))) {
+    const inProject = hasProjectConfig(project) || existsSync(join(project, "plain_modules"));
+    if (inProject)
         checks.push(...checkProject(project));
-        if (options.models !== false && hasProjectConfig(project)) {
-            console.log(brand.muted("Asking each model the config names for a word..."));
-            checks.push(...(await checkProjectModels(project)));
-        }
+    if (options.models !== false && (hasProjectConfig(project) || options.modelsGiven === true)) {
+        console.log(brand.muted("Asking each model the config names for a word..."));
+        checks.push(...(await checkProjectModels(project)));
     }
     return checks;
 }
@@ -224,21 +237,27 @@ function removeGlobalExtension() {
     rmSync(file, { force: true });
     console.log(`  removed ${file}`);
 }
+const USAGE = [
+    "usage: turri doctor [--harness-model <m>] [--coding-model <m>] [--judge-model <m>] [--no-models] [--yes]",
+    "",
+    "Check everything turri needs - in a project, what its modules need of this machine too, and that",
+    "each model its config names answers with this machine's credentials (one short request a model;",
+    "--no-models skips it). The model options are read as the config's keys, as turri regenerate reads them:",
+    "a headless run's models can be checked before it starts, with no config.turri.yaml.",
+    "It changes nothing but this, asked first: a plain pi that an older turri made load turri too is put back to",
+    "plain pi. --yes answers yes.",
+].join("\n");
 export async function main(args) {
-    if (args.includes("--help") || args.includes("-h")) {
-        console.log("usage: turri doctor [--no-models] [--yes]\n\nCheck everything turri needs - in a project, what its modules need of this machine too, and that\n" +
-            "each model its config names answers with this machine's credentials (one short request a model;\n--no-models skips it).\n" +
-            "It changes nothing but this, asked first: a plain pi that an older turri made load turri too is put back to\n" +
-            "plain pi. --yes answers yes.");
-        return 0;
-    }
+    const { options } = parseArgs(args, ["--no-models", "--yes", "-y"], USAGE, ["--harness-model", "--judge-model"]);
+    configKeyOptions(options);
     console.log(brand.bold(brand.accent("Checking what turri needs.")));
     if (!nodeVersionOk())
         return report([checkNode()]);
-    const code = report(await allChecks({ models: !args.includes("--no-models") }));
+    const modelsGiven = ["harness-model", "model", "judge-model"].some((name) => options[name] !== undefined);
+    const code = report(await allChecks({ models: options["no-models"] === undefined, modelsGiven }));
     // turri and pi are kept apart: a plain pi does not start turri. An older turri's file that made it do so goes, asked.
     const global = globalExtensionFile();
-    if (global !== undefined && (await confirm(`\nA plain \`pi\` loads turri too, through ${global}. Remove it, so pi stays pi?`, true, args.includes("--yes") || args.includes("-y")))) {
+    if (global !== undefined && (await confirm(`\nA plain \`pi\` loads turri too, through ${global}. Remove it, so pi stays pi?`, true, options.yes !== undefined || args.includes("-y")))) {
         removeGlobalExtension();
     }
     return code;