@turri-dev/cli 0.1.2 → 0.1.3-next.04c4f71

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/loop-tools.js

@@ -73,7 +73,7 @@ export async function loopReply(loop, statuses, wait) {
 export function stopJob(jobs, named, reason) {
     const matches = jobs.list().filter((job) => job.id.startsWith(named.trim()));
     if (matches.length === 0)
-        return `No pulse ${named}. /regen shows them.`;
+        return `No pulse ${named}. /pulses shows them.`;
     if (matches.length > 1)
         return `'${named}' matches ${matches.map((job) => job.id).join(", ")}. Give more of the id.`;
     const target = matches[0];

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/picture-row.js

@@ -0,0 +1,21 @@
+import { compositeTuiLine } from "@earendil-works/pi-tui";
+/** What the banner puts between a row's text and the picture after it: back to the jellyfish's column. */
+export const PICTURE_AT = "\x1b[2G";
+/** The picture's escape sequence, as the banner writes it after PICTURE_AT: Kitty's, in chunks, or iTerm2's - climbing first on iTerm2. */
+const PICTURE = /^(?:\x1b\[\d+A)?(?:(?:\x1b_G[^\x1b]*\x1b\\)+|\x1b\]1337;File=[^\x07]*\x07)/;
+/**
+ * The banner's picture row with an overlay drawn over its text, the picture after it - left out while the overlay
+ * reaches over the picture, `pictureRight` columns from the left edge. Undefined for a row that holds no picture.
+ *
+ * What follows the picture - the padding a row narrower than the screen is given, the chat's beside the docked panel -
+ * is the row's text: written after the picture, from the picture's column, it would blank the row.
+ */
+export function overPictureRow(base, overlay, col, width, total, pictureRight) {
+    const at = base.lastIndexOf(PICTURE_AT);
+    const picture = at === -1 ? null : PICTURE.exec(base.slice(at + PICTURE_AT.length));
+    if (picture === null)
+        return undefined;
+    const after = base.slice(at + PICTURE_AT.length + picture[0].length);
+    const drawn = compositeTuiLine(`${base.slice(0, at)}${after}`, overlay, col, width, total);
+    return col >= pictureRight ? `${drawn}${PICTURE_AT}${picture[0]}` : drawn;
+}

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);

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/confine.js

@@ -188,6 +188,7 @@ export function sandboxNote(fence) {
         const report = fence.environmentTool !== undefined
             ? `report it as an environment error with ${fence.environmentTool}`
             : "say so plainly - what is missing and what needs it - and end your turn";
+        lines.push("- A command refused a file outside your folder - `Operation not permitted`, `Permission denied`, a lock it could not", `  take - is these walls, not the code, and nothing you change gets past them: ${report} at once, naming the file`, "  and the command that wanted it.");
         lines.push(fence.write.length > 0
             ? "- The project's dependencies are yours: declare them in the build manifest, and let the build tools fetch them."
             : "- You install nothing.", `${fence.write.length > 0 ? "  Installing anything else is not" : "  Nor is installing anything on the machine yours"}: no toolchains, system packages, drivers, global packages or \`sudo\`. If the`, `  machine lacks something the code needs, ${report}, name what is missing, and go no further with what depends on it.`, "  The person decides.", "- Ports and processes: you may stop only what you started. If a port is taken by something else, use another port.", "  `ps` may show nothing but what you started: check a server you started with `kill -0 $!`, its log, or a request to it.", "- Temporary files go in `$TMPDIR`: `/tmp` is outside your walls.");

package/dist/regenerate/environment-error.js

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, sep } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -35,7 +36,7 @@ export class EnvironmentError extends Error {
     sandbox;
     constructor(details) {
         super(details.sandbox !== undefined
-            ? `${details.moduleName} stopped: turri's sandbox kept its agents from ${details.sandbox.paths[0]}, which is on this machine.`
+            ? `${details.moduleName} stopped: turri's sandbox kept its agents from ${details.sandbox.access === "write" ? "writing" : "reading"} ${details.sandbox.paths[0]}, which is on this machine.`
             : `${details.moduleName} stopped: the environment lacks ${details.missing}.`);
         this.name = "EnvironmentError";
         this.moduleName = details.moduleName;
@@ -50,6 +51,10 @@ export class EnvironmentError extends Error {
             this.sandbox = details.sandbox;
     }
 }
+/** A file's name that says it is a lock: `lockfile`, `x.lock`, `x.lck`, `.lock-x`, `x.lock.y`. */
+const LOCK_FILE = /(?:^|[._-])(?:lock|lck|lockfile)(?:$|[._-])/i;
+/** What says the sandbox refused a write, not a read: writing, creating, a lock not taken - not a name with "lock" in it. */
+const WRITE_REFUSED = /\b(?:writ(?:e|es|ing|able)|creat(?:e|es|ing)|acquir(?:e|ing)|(?:take|obtain|get) (?:a |the )?lock|locking|read-only file system)\b/i;
 /** A folder named for a version - `24.16.0`, `v22.3.0`, `3.12.4` - the root of a version manager's install. */
 const VERSION = /^v?\d+\.\d+/;
 /** The parts of an install below its root, where the root ends: `…/24.16.0/lib/node_modules/…` ends before `lib`. */
@@ -74,27 +79,59 @@ export function sandboxGapOf(text, options = {}) {
     const system = (options.platform ?? process.platform) === "darwin" ? MACOS_MACHINE : LINUX_MACHINE;
     const within = (path, root) => path === root || path.startsWith(`${root}/`);
     const named = [...text.matchAll(/(?:^|[\s'"`(=:])(\/[^\s'"`()<>,;]+)/g)].map((match) => match[1].replace(/[.:]+$/, ""));
-    const paths = [...new Set(named)].filter((path) => path.split("/").length > 3 && exists(path) && !system.some((root) => within(path, root)) && (options.project === undefined || !within(path, options.project)));
-    return paths.length > 0 ? { paths, folder: toolchainFolder(paths[0]) } : undefined;
+    const isLock = (path) => LOCK_FILE.test(basename(path));
+    // A lock file the tool could not create is not there: its folder is.
+    const found = [...new Set(named)].filter((path) => path.split("/").length > 3 &&
+        (exists(path) || (isLock(path) && exists(dirname(path)))) &&
+        !system.some((root) => within(path, root)) &&
+        (options.project === undefined || !within(path, options.project)));
+    if (found.length === 0)
+        return undefined;
+    // The lock first: it is what the build could not take.
+    const paths = [...found.filter(isLock), ...found.filter((path) => !isLock(path))];
+    const lock = isLock(paths[0]);
+    return { paths, folder: toolchainFolder(paths[0]), access: lock || WRITE_REFUSED.test(text) ? "write" : "read", ...(lock ? { lock } : {}) };
 }
 /**
  * What the person is told, in the chat, at the end of `turri regenerate`, and in the job's log. `rerun`: the command that runs
  * the work again, as the pulse knows it - the spec the person ran; without it, the module's own spec by its name.
  */
 export function describeEnvironmentError(error, rerun) {
-    if (error.sandbox !== undefined) {
+    const again = `Then re-run: \`${rerun ?? `turri regenerate ${error.moduleName}.plain`}\`, or say "resume" in the chat.`;
+    const needed = `Needed by: ${error.neededBy}${error.shownBy !== undefined ? ` (${error.shownBy})` : ""}.`;
+    const gap = error.sandbox;
+    if (gap?.access === "write") {
+        const what = gap.lock === true ? `the lock file \`${gap.paths[0]}\`, which the build takes as it runs` : `\`${gap.paths[0]}\``;
+        const home = homedir();
+        const inHome = gap.paths[0] === home || gap.paths[0].startsWith(`${home}/`);
+        return [
+            `**${error.moduleName} stopped: turri's sandbox kept its agents from writing ${what} - it is on this machine; nothing is missing, and nothing needs installing.**`,
+            needed,
+            "An agent's commands write only their module's folders, their own home and temporary folder, and the package caches turri " +
+                "points the build tools at - no setting lets them write anywhere else, and `toolchains:` lets them read a folder, not write it.",
+            inHome
+                ? "To fix: it is in your home, not the agents' own - the tool found your home without `$HOME`, as a JVM does for `user.home`, " +
+                    "or a setting of yours points it there. Have it use `$HOME` instead - for a JVM tool, `-Duser.home=$HOME` where the build " +
+                    "starts its JVM - and the agents' own home takes it."
+                : `To fix: it is in a toolchain's own install, \`${gap.folder}\`, which the build writes into as it runs - and the agents may ` +
+                    "not change a toolchain. Have the build keep it elsewhere if the tool has a setting for it, or install a copy of the " +
+                    "toolchain that keeps its writes in its cache.",
+            again,
+        ].join("\n");
+    }
+    if (gap !== undefined) {
         return [
-            `**${error.moduleName} stopped: turri's sandbox kept its agents from reading \`${error.sandbox.paths[0]}\` - it is on this machine; nothing is missing.**`,
-            `Needed by: ${error.neededBy}${error.shownBy !== undefined ? ` (${error.shownBy})` : ""}.`,
-            `To fix: let the agents read that toolchain - add its folder to \`toolchains:\` in config.yaml, keeping what is there: \`toolchains: [${error.sandbox.folder}]\`. Nothing needs installing.`,
-            `Then re-run: \`${rerun ?? `turri regenerate ${error.moduleName}.plain`}\`, or say "resume" in the chat.`,
+            `**${error.moduleName} stopped: turri's sandbox kept its agents from reading \`${gap.paths[0]}\` - it is on this machine; nothing is missing.**`,
+            needed,
+            `To fix: let the agents read that toolchain - add its folder to \`toolchains:\` in config.turri.yaml, keeping what is there: \`toolchains: [${gap.folder}]\`. Nothing needs installing.`,
+            again,
         ].join("\n");
     }
     return [
         `**${error.moduleName} stopped: the environment lacks ${error.missing}.**`,
         `Needed by: ${error.neededBy}${error.shownBy !== undefined ? ` (${error.shownBy})` : ""}.`,
         `To fix: ${error.fix ?? "provide it on this machine, then run it again."}`,
-        `Then re-run: \`${rerun ?? `turri regenerate ${error.moduleName}.plain`}\`, or say "resume" in the chat.`,
+        again,
     ].join("\n");
 }
 /** The name agents know the tool by - their wall text names it. */

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 } : {}),