@turri-dev/cli 0.1.7 → 0.1.8-next.01c7342

package/README.md

@@ -1,7 +1,5 @@
 <p align="center"><img src="docs/images/turri-banner.gif" alt="turri, beside its mark - the first coding agent with the power of regenerative software: npm install -g @turri-dev/cli - and a pixel jellyfish regenerating, from a polyp on the sea floor"></p>
 
-<h1 align="center">turri<br>the first coding agent with the power of<br>regenerative software<br>&nbsp;</h1>
-
 <p align="center">
   <a href="https://www.npmjs.com/package/@turri-dev/cli"><img src="https://img.shields.io/npm/v/@turri-dev/cli?label=npm" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/@turri-dev/cli" alt="MIT licence"></a>
@@ -49,7 +47,7 @@ turri init-config --vendor anthropic
 
 It then tells you which API key to set - or to type `/login` once **turri** is running instead. **turri** loads the `config.turri.yaml` in the folder you start it from. Below the two models, the file sets every other setting to its default - change any of them in the file, or from the chat with `/turri-config`. Any other model works too: [models](#models).
 
-Once `turri` is running, say: *Let's start a new project: a small API where people can register and sign in.*
+Once `turri` is running, type: `/spawn a small API where people can register and sign in` - or `/brood` for an interview that settles each feature with you first.
 
 No project of your own yet? Build one of [**the examples**](examples/README.md) with turri, step by step.
 
@@ -146,11 +144,11 @@ cd ~/my-project
 turri
 ```
 
-Then talk to it:
+Then start the interview:
 
-> Let's start a new project: a small API where people can register and sign in.
+> /brood a small API where people can register and sign in
 
-It runs the interview skill, asks you about the problem, the stack and the product, writes \*\*\*plain, and builds each functionality as it is written. While it works:
+It asks you about the problem, the stack and the product, writes \*\*\*plain, and builds each functionality as it is written. While it works:
 
 - the **panel** above the input shows every build - its stage, what its agents are doing, its model and cost - and the queue behind it;
 - ask to try it at any time - "let me try it" - and **`release`** puts what is built so far in `dist/<module>` and **`activate`** starts it, installing what it needs - nothing to approve;
@@ -188,7 +186,7 @@ Start at the [documentation index](docs/README.md), or go straight to a page:
 | | |
 | --- | --- |
 | [Installation](docs/installation.md) | doctor, what turri needs of this machine, **turri** and `pi`, environment variables |
-| [Examples](examples/README.md) | projects to build with turri step by step: cognio from an empty folder, guestbook - a backend and a frontend in minutes - a CLI, a backend service with conformance tests, a REST API integration |
+| [Examples](examples/README.md) | projects to build with turri step by step: guestbook - a backend and a frontend in minutes - a CLI, and a backend service with conformance tests |
 | [Using **turri**](docs/using.md) | the conversation, skills, tools, pulses and regen, choosing models, the command line |
 | [The project config](docs/config.md) | `config.turri.yaml` and each stack's `config.turri.<stack>.yaml`: every key, models and their inheritance, conformance, the testing scripts, stacks and choosing one, the old `config.yaml` |
 | [Deploy](docs/deploy.md) | trying what is built: the last commit in `dist/<module>`, started on your machine, nothing installed without asking |

package/dist/btw.d.ts

@@ -53,6 +53,8 @@ export interface SideQuestion {
     projectDir: string;
     /** turri's own folder: its source, skills, rules and docs. */
     harnessDir: string;
+    /** A host's surface, in its own words (TurriHost.surface): where the person watches the work instead of the terminal. */
+    surface?: string;
 }
 export declare function sideQuestionPrompt(side: SideQuestion): string;
 /** Answers a side question with an agent of its own, read only, on `model`. */

package/dist/btw.js

@@ -12,7 +12,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { confinedTools } from "./regenerate/confine.js";
-import { TURRI_IDENTITY } from "./identity.js";
+import { conversationIdentity } from "./identity.js";
 import { ask, BEGIN, createExecutor } from "./pi.js";
 /** How many tool calls the side agent may make before it is told to answer. */
 export const SIDE_CALLS = 20;
@@ -85,7 +85,7 @@ export function skillSessionText(runDir, maxChars = SKILL_SESSION_CHARS) {
 }
 export function sideQuestionPrompt(side) {
     return [
-        TURRI_IDENTITY,
+        conversationIdentity(side.surface),
         "",
         "The person is in the middle of something with you - a skill, a pulse - and has asked you a question on the side",
         "with /btw. Answer it as turri: in the first person, to them, in whole sentences - briefly and plainly, from what is",

package/dist/extension.d.ts

@@ -41,6 +41,17 @@ export interface TurriHost {
     onPlanChange?(): void;
     /** The dialogs ask_user puts its questions in - the conversation's and a skill's interview - instead of the terminal's. */
     dialogs?: AskUserIO;
+    /**
+     * The host's own UI, in its own words: the views it has in place of the terminal's, what its marks and buttons mean,
+     * where questions appear. Given, turri tells the model none of the terminal's - its keys, the side panel, regen,
+     * /pulses - and gives it this instead, as a `<surface>` block in turri's identity. Absent, the terminal is the surface.
+     */
+    surface?: string;
+    /**
+     * The last word on the whole system prompt, as turri has built it for this turn - after its own before_agent_start
+     * work: what it returns is what is sent. For a host that needs to change anything else.
+     */
+    systemPrompt?(prompt: string): string;
 }
 /** turri's conversation as an extension of pi's, for a host that runs it itself: see TurriHost. */
 export declare function createTurriExtension(host?: TurriHost): (pi: ExtensionAPI) => void;

package/dist/extension.js

@@ -53,13 +53,14 @@ import { describeStdlib } from "./stdlib.js";
 import { peekKeyListener, runAsk } from "./ask.js";
 import { QuestionDialog } from "./question-dialog.js";
 import { registerStacks } from "./stacks.js";
-import { catalogueLine, discoverSkills, leftOutNote } from "./skills.js";
+import { catalogueLine, createCommandGate, discoverSkills, leftOutNote, startedByCommandOnly } from "./skills.js";
 import { supersededByTurri } from "./chat-skills.js";
-import { TURRI_IDENTITY } from "./identity.js";
+import { conversationIdentity } from "./identity.js";
+import { setSurface, surfaceOf } from "./surface.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";
+import { createJobRegistry, defaultParallelJobs, describeJob, firstRegeneration, formatDuration, formatElapsed, pulseName, shouldWait, STOPPED_ON_REQUEST, } from "./regenerate/jobs.js";
 /**
  * Makes gated skills reachable from a conversation.
  *
@@ -180,6 +181,14 @@ export function chatAskUserTool(dialogs) {
         },
     };
 }
+/**
+ * The conversation's system prompt for a turn: pi's, turri's identity - with the host's surface in place of the
+ * terminal's, when it has one - and turri's blocks; then the host's last word on it.
+ */
+function conversationSystemPrompt(base, host, blocks) {
+    const prompt = [base, conversationIdentity(host.surface), ...blocks].filter((part) => part !== "").join("\n\n");
+    return host.systemPrompt !== undefined ? host.systemPrompt(prompt) : prompt;
+}
 /** The host each conversation's jobs report to, for the work loop made for them later. */
 const hosts = new WeakMap();
 /** turri's conversation as an extension of pi's, for a host that runs it itself: see TurriHost. */
@@ -260,6 +269,8 @@ function turriExtension(pi, host) {
         },
     });
     hosts.set(jobs, host);
+    // What the model is told of where the person watches the work, deep in the tools too: the host's surface, or the terminal.
+    setSurface(jobs, host.surface);
     host.onJobs?.(jobs);
     // The ***plain rules go into the system prompt in full, every turn. The block is
     // identical each time, so it sits inside the cached prefix rather than invalidating it.
@@ -298,7 +309,7 @@ function turriExtension(pi, host) {
             }
         }
         return {
-            systemPrompt: [event.systemPrompt, TURRI_IDENTITY, TOOLS_NOT_CLI, projectConfigBlock(cwd), machineBlock(cwd, machine.now()), rulesBlock()].filter((part) => part !== "").join("\n\n"),
+            systemPrompt: conversationSystemPrompt(event.systemPrompt, host, [TOOLS_NOT_CLI, projectConfigBlock(cwd), machineBlock(cwd, machine.now()), rulesBlock()]),
         };
     });
     // The conversation's agent does not run turri again through its shell, unless the person
@@ -314,7 +325,7 @@ function turriExtension(pi, host) {
         if (event.toolName === "bash" && typeof command === "string") {
             const what = selfInvocation(command);
             if (what !== undefined && !askedForCommandLine(lastUserMessage))
-                return { block: true, reason: refusal(what) };
+                return { block: true, reason: refusal(what, surfaceOf(jobs)) };
         }
         markConversationWrite(event.toolCallId, event.toolName, event.input);
         return undefined;
@@ -416,6 +427,19 @@ function turriExtension(pi, host) {
         return;
     const catalogue = skills.map(catalogueLine).join("\n");
     const pendingNote = leftOutNote(discoveredSkills);
+    // The skills the person starts themselves - brood, spawn, bud: each has its command, and cultivate starts it only
+    // once its command is typed. The command puts what was typed in the chat, as the person's message, for the model to
+    // run it with what follows as its context.
+    const gate = createCommandGate();
+    for (const skill of skills.filter((s) => s.commandOnly)) {
+        pi.registerCommand(skill.name, {
+            description: `Start ${skill.name}${skill.steps.length > 1 ? ` - ${skill.steps.map((step) => step.name).join(" → ")}` : ""}: /${skill.name} [what you want]`,
+            handler: async (args) => {
+                gate.typed(skill.name);
+                pi.sendUserMessage(`/${skill.name}${args.trim() !== "" ? ` ${args.trim()}` : ""}`, { deliverAs: "followUp" });
+            },
+        });
+    }
     pi.registerTool({
         name: "cultivate",
         label: "Cultivate",
@@ -426,6 +450,7 @@ function turriExtension(pi, host) {
         promptSnippet: "cultivate: run a gated skill - its steps and review gates enforced by turri",
         promptGuidelines: [
             "When a request matches a skill listed in cultivate's description, call cultivate instead of doing the work yourself. Doing it by hand skips the review gates.",
+            "A skill marked as started only by the person runs only from its command: a message that is its command - /spawn a small server - is the person starting it, so call cultivate for it at once, with what follows the command as context. Never call cultivate for one otherwise; tell them to type its command.",
             // pi lists .agents/skills among its own skills too: read and followed by hand, a skill's gates would be skipped.
             "A skill cultivate lists may also be among your own skills, from the project's .agents/skills: run it with cultivate all the same, never by reading its SKILL.md and following it.",
             "cultivate returns the reviewed artifact and a trace of every gate decision. Report the artifact to the user; do not rewrite it.",
@@ -458,6 +483,8 @@ function turriExtension(pi, host) {
                     details: {},
                 };
             }
+            if (!gate.mayStart(skill))
+                return { content: [{ type: "text", text: startedByCommandOnly(skill.name) }], details: { notStarted: true } };
             // A new run clears the run folder. An interrupted one is not thrown away by accident:
             // whether to pick it up or start over is the user's call.
             const runDir = skillRunDir(cwd, skill.name);
@@ -475,6 +502,8 @@ function turriExtension(pi, host) {
                     details: { interrupted },
                 };
             }
+            // Its command is used up: started again later, it is typed again.
+            gate.started(skill.name);
             const trace = [`skill: ${skill.name}`, ...describeGates(skill).map((l) => `  ${l}`)];
             // While it runs, what its agent is doing leads: pi shows a running tool's first lines, and the trace's first
             // lines are the gates, which say nothing about now. The result keeps the trace alone.
@@ -560,6 +589,8 @@ function turriExtension(pi, host) {
             const filesBefore = projectFiles(cwd);
             // A side question asked while it runs is told what it has done so far.
             const ended = skillRunStarted({ skill: skill.name, dir: skill.dir, step: () => live.step, trace: () => [...trace], runDir });
+            // From here the time to first regeneration is counted, for a skill that writes spec diffs: its first pulse started.
+            const began = Date.now();
             const { result, output: captured } = await captureConsole(() => runSkill({
                 skillDir: skill.dir,
                 cwd,
@@ -620,11 +651,17 @@ function turriExtension(pi, host) {
                 ? `${specsChanged.join(", ")} changed, and nothing is regenerated from that yet: call regenerate for it, and the code is brought up to the spec.`
                 : "";
             const gated = skill.steps.some((step) => step.gate !== undefined);
+            const first = skill.allowedTools.includes("write_spec_diff") ? firstRegeneration(jobs.list(), began) : {};
+            const ttfr = first.started === undefined
+                ? ""
+                : `Time to first regeneration: ${formatElapsed(first.started)} - its first pulse started that long after ${skill.name} began` +
+                    (first.landed !== undefined ? `, and landed after ${formatElapsed(first.landed)}.` : ".");
             const text = result.ok
                 ? [
                     gated ? `${skill.name}: passed all gates.` : `${skill.name}: finished. It has no review gates, so nothing checked its work: read what it changed before you report it.`,
                     changed,
                     ...(unrendered !== "" ? [unrendered] : []),
+                    ...(ttfr !== "" ? [ttfr] : []),
                     "",
                     "<artifact>",
                     result.output,
@@ -2083,6 +2120,7 @@ async function askOnTheSide(pi, ctx, cwd, jobs, question) {
         pulses: jobs.list().map((job) => `${job.id} ${job.status}: ${pulseName(job)}`),
         projectDir: cwd,
         harnessDir: PACKAGE_ROOT,
+        ...(surfaceOf(jobs) !== undefined ? { surface: surfaceOf(jobs) } : {}),
     }, chatModelOf(ctx));
     try {
         pi.appendEntry(SIDE_ENTRY, { question, answer });

package/dist/identity.d.ts

@@ -1,2 +1,7 @@
-/** Who the conversation's agent is: turri, and what it does - first, so it speaks as turri, in the first person. */
+/**
+ * Who the conversation's agent is: turri, and what it does - first, so it speaks as turri, in the first person. Where
+ * the person watches the work is the terminal's regen; given a host's surface, that is said in its place.
+ */
+export declare function conversationIdentity(surface?: string): string;
+/** turri as the terminal runs it. */
 export declare const TURRI_IDENTITY: string;

package/dist/identity.js

@@ -1,5 +1,31 @@
-/** Who the conversation's agent is: turri, and what it does - first, so it speaks as turri, in the first person. */
-export const TURRI_IDENTITY = [
+/** In the terminal: regen, where the person watches the work - the side panel, its key, and the pulses behind it. */
+const REGEN = [
+    "- regen is the side panel (ctrl+h): the spec with each functionality and item marked built, regenerating,",
+    "  planned or waiting - and behind it the pulses (/pulses), every pulse regenerating, planned and finished. Say regen,",
+    "  lowercase. It was the regeneration, the job queue, or the job panel.",
+];
+/** In a host: where the person watches the work is the host's to say - its surface, below. */
+const HOST_SURFACE = [
+    "- What the person sees of your work - where they watch it, and what they press - is the app's you run in, and",
+    "  <surface> below says it in its own words. Say only what it says, and speak of no key, panel or view it does not",
+    "  name.",
+];
+/**
+ * Who the conversation's agent is: turri, and what it does - first, so it speaks as turri, in the first person. Where
+ * the person watches the work is the terminal's regen; given a host's surface, that is said in its place.
+ */
+export function conversationIdentity(surface) {
+    const text = surface?.trim() ?? "";
+    const hosted = text !== "";
+    return [
+        ...IDENTITY_BEFORE,
+        ...(hosted ? HOST_SURFACE : REGEN),
+        ...IDENTITY_AFTER,
+        ...(hosted ? ["", "<surface>", text, "</surface>"] : []),
+        "</turri>",
+    ].join("\n");
+}
+const IDENTITY_BEFORE = [
     "<turri>",
     "You are turri - always lowercase - a coding agent with the power of regenerative software. The software is its",
     "***plain; the code is regenerated from it. You help the person write ***plain, and you regenerate the code from it a",
@@ -25,11 +51,11 @@ export const TURRI_IDENTITY = [
     "- A pulse is one unit of work regenerating the code - a spec diff regenerated in a codebase, or its conformance",
     "  tests. It was called a job, and still is in places: the job_id a tool takes is a pulse's id, and parallel-jobs and",
     "  allow-to-stop-jobs in config.turri.yaml are about pulses. \"Job\" in what you read is a pulse; say pulse.",
-    "- regen is the side panel (ctrl+h): the spec with each functionality and item marked built, regenerating,",
-    "  planned or waiting - and behind it the pulses (/pulses), every pulse regenerating, planned and finished. Say regen,",
-    "  lowercase. It was the regeneration, the job queue, or the job panel.",
+];
+const IDENTITY_AFTER = [
     "- mutate, in a skill's activity, is write_spec_diff: a spec change written and regenerated in one step.",
     "- Regenerate is the word for what you do to the code: never grow, grew or grown - older text, a tool's description",
     "  or a report may still say it, and means regenerate.",
-    "</turri>",
-].join("\n");
+];
+/** turri as the terminal runs it. */
+export const TURRI_IDENTITY = conversationIdentity();

package/dist/loop-tools.js

@@ -9,6 +9,7 @@ import { pulseName } from "./regenerate/jobs.js";
 import { stopDeployed } from "./regenerate/release.js";
 import { projectDirOf } from "./regenerate/paths.js";
 import { findTestScripts } from "./regenerate/test-scripts.js";
+import { surfaceOf } from "./surface.js";
 /** How the queue is to be planned, for the work this call queues - see regenerate/steer.ts. */
 export const GUIDANCE_PARAM = Type.Optional(Type.String({
     description: "How to plan the queue for this work, in a sentence or two - which functional specs go together, what first - as " +
@@ -114,8 +115,9 @@ export function stopJob(jobs, named, reason, loop) {
     if (module !== undefined)
         return module;
     const matches = jobs.list().filter((job) => job.id.startsWith(named.trim()));
+    // /pulses is the terminal's: in a host, the pulses tool lists them.
     if (matches.length === 0)
-        return `No pulse ${named}. /pulses shows them.`;
+        return `No pulse ${named}. ${surfaceOf(jobs) !== undefined ? "The pulses tool lists them." : "/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/regenerate/cases.js

@@ -64,6 +64,9 @@ export function conformanceCasesBlock(cases) {
     if (cases.patch.length > 0) {
         lines.push(`- Changed - its text, its acceptance tests, or a concept it uses: ${named(cases.patch)}.`, "  Its conformance tests exist: rewrite them to what it says now. The tests of everything else stay as they are.");
     }
+    if (cases.again.length > 0) {
+        lines.push(`- Regenerated again - its code was built anew, and its conformance tests were written against the code it replaced: ${named(cases.again)}.`, "  Its text did not change, but the code did. Run its tests against the new code. What they check that the", "  specification says stays checked: rewrite such a test only as the new code needs it reached. What they check", "  that the specification leaves open - a path, a field, a message, a format the old code chose and the", "  specification never names - is the new code's choice now: rewrite those checks to what the new code does,", "  or take them out. No test may hold the new code to what only the old code did. The tests of everything else", "  stay as they are.");
+    }
     if (cases.delete.length > 0)
         lines.push(`- Taken out - remove its conformance tests: ${named(cases.delete)}.`);
     if (cases.mechanical) {

package/dist/regenerate/conformance-agents.js

@@ -316,9 +316,9 @@ export function createAskExplorerTool(options) {
     return defineTool({
         name: "ask_explorer",
         label: "Ask the explorer",
-        description: "Ask the explorer - who read and ran the code, and wrote the account of it you were given - something the account " +
+        description: "Ask the explorer - who read the code, and wrote the account of it you were given - something the account " +
             "does not say: how a functionality is reached, what a field is called, what the software needs around it. It reads " +
-            `and runs the code to answer. ${options.questions ?? EXPLORER_QUESTIONS} questions a run: ask what reading the code yourself would take long to find.`,
+            `the code to answer - it runs nothing, so what only running the software shows is yours to try. ${options.questions ?? EXPLORER_QUESTIONS} questions a run: ask what reading the code yourself would take long to find.`,
         promptSnippet: "ask_explorer: a question about how the software is reached, answered by the explorer from the code",
         parameters: Type.Object({ question: Type.String({ description: "What you need to know, exactly" }) }),
         async execute(_id, params) {

package/dist/regenerate/conformance.js

@@ -5,7 +5,7 @@ import { PLAIN_SOURCE_FILE_EXTENSION, plainFileParser } from "../plain/parser.js
 import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, getFrids, getInheritedFunctionalSpecs, getSpecificationsForFrid, TEST_REQUIREMENTS, } from "../plain/spec.js";
 import { reportActivity, reportLogNote, reportSpec, reportStage, unitOf } from "./activity.js";
 import { confinedTools } from "./confine.js";
-import { abandonWork, diffSinceSnapshot, moduleDirOf, recordHistory, startWork, workDiff, workSnapshot } from "./lineage.js";
+import { abandonWork, diffSinceSnapshot, landWork, moduleDirOf, startWork, workDiff, workSnapshot } from "./lineage.js";
 import { createWorkLedger, describeAccounts, SUBMIT_WORK_NOTE, unanswered, unansweredPrompt } from "./submit-work.js";
 import { CONFORMANCE_COMPACTION } from "./compaction.js";
 import { NOTES_TURN, notesForSession, passedOutcome, readNotes, reflectOnReview, withNotes } from "./notes.js";
@@ -797,9 +797,9 @@ export async function renderConformanceTests(options) {
             // The tests, and the code when it changed: one commit if they share a module folder.
             const subject = `conformance ${moduleName} ${options.diff !== undefined ? "for a spec change" : `fs ${frid}`}${changed ? " (code changed)" : ""}`;
             stage(`committing the conformance tests${changed ? " and the code changes" : ""}`);
-            recordHistory(conformanceDir, subject);
+            landWork(conformanceDir, subject);
             if (moduleDirOf(buildDir) !== moduleDirOf(conformanceDir))
-                recordHistory(buildDir, subject);
+                landWork(buildDir, subject);
         }
         else if (start !== undefined) {
             const why = notLandedWhy(options.diff !== undefined ? "for the spec change" : `of functionality ${frid}`, unlabelled);

package/dist/regenerate/environment-error.d.ts

@@ -128,6 +128,12 @@ export declare function missingToolchainError(run: {
     script: string;
     kind: "unit" | "conformance";
 }): EnvironmentError | undefined;
+/**
+ * Work that passed could not be committed into the module's history: the next pulse, putting the module back to its last
+ * commit, would undo it while turri took it as built - so the pulse does not land, and is rolled back like any other that
+ * did not, and the person is told why. `said` is what git said.
+ */
+export declare function historyError(moduleDir: string, said: string): EnvironmentError;
 /**
  * Before a pulse in `moduleDir` starts any agent: a credential `agent-env:` names that is not there stops it - every
  * command that needs it would fail, and no agent may make one up. Nothing when all are there, or the folder is no

package/dist/regenerate/environment-error.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, sep } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { passedCredentials } from "./agent-env.js";
@@ -246,6 +246,24 @@ export function missingToolchainError(run, details) {
     const missing = missingToolchain(run);
     return missing !== undefined ? toolchainError(missing, details) : undefined;
 }
+/**
+ * Work that passed could not be committed into the module's history: the next pulse, putting the module back to its last
+ * commit, would undo it while turri took it as built - so the pulse does not land, and is rolled back like any other that
+ * did not, and the person is told why. `said` is what git said.
+ */
+export function historyError(moduleDir, said) {
+    const lock = /index\.lock/.test(said);
+    return new EnvironmentError({
+        moduleName: moduleNameOf(moduleDir),
+        missing: `a commit into the module's history, \`${join(moduleDir, ".plaingit")}\``,
+        neededBy: "the work that passed - without the commit, the next pulse would undo it",
+        shownBy: `git said: ${said.replace(/\s+/g, " ").trim().slice(0, 600)}`,
+        fix: lock
+            ? `if no git is still running on it, remove \`${join(moduleDir, ".plaingit", "index.lock")}\`, which a git stopped mid-commit left behind.`
+            : "fix what git said - a full disk, files it cannot read - so a commit can be made there.",
+        source: "harness",
+    });
+}
 /** The module a folder is part of, by name: `plain_modules/<module>/...`. */
 function moduleNameOf(moduleDir) {
     return basename(moduleDir);

package/dist/regenerate/jobs.d.ts

@@ -163,6 +163,15 @@ export declare function createJobRegistry(options?: {
 export declare function formatDuration(job: Job): string;
 /** "42s", "3m 12s", "1h 5m": how long something has run. */
 export declare function formatElapsed(ms: number): string;
+/**
+ * How soon after `since` the first code pulse queued since then started - the time to first regeneration - and how soon
+ * the first of them landed, when one has: from then on there is something to try. In milliseconds; either is undefined
+ * until it has happened.
+ */
+export declare function firstRegeneration(jobs: Job[], since: number): {
+    started?: number;
+    landed?: number;
+};
 /**
  * What a pulse is called wherever it is shown in a line: its module, kind and number - `shorty · regenerate pulse 3`,
  * `shorty · conformance pulse 6` - never what it regenerates, which is the agents' words and long. A job of no module,

package/dist/regenerate/jobs.js

@@ -377,6 +377,17 @@ export function formatElapsed(ms) {
         return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
     return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
 }
+/**
+ * How soon after `since` the first code pulse queued since then started - the time to first regeneration - and how soon
+ * the first of them landed, when one has: from then on there is something to try. In milliseconds; either is undefined
+ * until it has happened.
+ */
+export function firstRegeneration(jobs, since) {
+    const pulses = jobs.filter((job) => job.kind === "regenerate" && job.queuedAt >= since && job.status !== "queued");
+    const started = Math.min(...pulses.map((job) => job.startedAt));
+    const landed = Math.min(...pulses.filter((job) => job.status === "succeeded" && job.details?.landed === true && job.finishedAt !== undefined).map((job) => job.finishedAt));
+    return { ...(Number.isFinite(started) ? { started: started - since } : {}), ...(Number.isFinite(landed) ? { landed: landed - since } : {}) };
+}
 /**
  * What a pulse is called wherever it is shown in a line: its module, kind and number - `shorty · regenerate pulse 3`,
  * `shorty · conformance pulse 6` - never what it regenerates, which is the agents' words and long. A job of no module,

package/dist/regenerate/lineage.d.ts

@@ -10,7 +10,8 @@
  * A commit is made after every step that changes the module - a render, a regeneration, a
  * conformance run, a regression repair, a spec change, a start from the module below - with
  * a message saying what it was. History is a record of the work, never a gate on it: a git
- * failure is swallowed, not raised.
+ * failure is swallowed, not raised - except landing work (`landWork`), whose commit the next
+ * start would otherwise undo.
  */
 export declare const HISTORY_DIR = ".plaingit";
 /** The module folder a build or tests directory belongs to. */
@@ -20,6 +21,13 @@ export declare function moduleDirOf(dir: string): string;
  * directory - belongs to. Nothing changed, nothing is committed. Returns the commit, if any.
  */
 export declare function recordHistory(dir: string, subject: string, body?: string): string | undefined;
+/**
+ * Commit work that landed - the code or tests a pulse passed, with the record of what they are built from. Unlike any
+ * other step's, this commit is not only a record: the next unit of work puts the module back to its last commit, and
+ * would undo what landed with it. So a commit that cannot be made is raised, as the environment's, with what git said -
+ * the work left in place, uncommitted. Nothing changed, nothing is committed. Returns the commit, if any.
+ */
+export declare function landWork(dir: string, subject: string, body?: string): string | undefined;
 /**
  * The notes the harness writes once a pulse has ended, committed - or the next pulse, putting the module back to its last
  * commit, would take them away. Into the pulse's own commit when it landed one - `landedSince` (ms), when it started - so

package/dist/regenerate/lineage.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { reportActivity } from "./activity.js";
+import { historyError } from "./environment-error.js";
 import { projectRootOf } from "./paths.js";
 /**
  * Version history for each module's generated code and tests.
@@ -15,7 +16,8 @@ import { projectRootOf } from "./paths.js";
  * A commit is made after every step that changes the module - a render, a regeneration, a
  * conformance run, a regression repair, a spec change, a start from the module below - with
  * a message saying what it was. History is a record of the work, never a gate on it: a git
- * failure is swallowed, not raised.
+ * failure is swallowed, not raised - except landing work (`landWork`), whose commit the next
+ * start would otherwise undo.
  */
 export const HISTORY_DIR = ".plaingit";
 const AUTHOR = ["-c", "user.name=turri", "-c", "user.email=turri@localhost", "-c", "commit.gpgsign=false"];
@@ -39,7 +41,10 @@ const EXCLUDED = [
     ".DS_Store",
 ];
 function git(moduleDir, args, input) {
-    return spawnSync("git", [...AUTHOR, "--git-dir", join(moduleDir, HISTORY_DIR), "--work-tree", moduleDir, ...args], {
+    const gitDir = join(moduleDir, HISTORY_DIR);
+    // The history is turri's, not the person's: hooks their git config names - gitleaks, husky - would refuse some of its
+    // commits, and the next start would put back what landed. Its own hooks folder holds only git's samples.
+    return spawnSync("git", [...AUTHOR, "-c", `core.hooksPath=${join(gitDir, "hooks")}`, "--git-dir", gitDir, "--work-tree", moduleDir, ...args], {
         cwd: moduleDir,
         encoding: "utf8",
         input,
@@ -79,21 +84,51 @@ function ensureHistory(moduleDir) {
  */
 export function recordHistory(dir, subject, body) {
     try {
-        const moduleDir = moduleDirOf(dir);
-        if (!existsSync(moduleDir) || !ensureHistory(moduleDir))
-            return undefined;
-        git(moduleDir, ["add", "-A"]);
-        if (git(moduleDir, ["diff", "--cached", "--quiet"]).status === 0)
-            return undefined;
-        const message = body ? `${subject}\n\n${body.trim()}\n` : subject;
-        if (git(moduleDir, ["commit", "-q", "-F", "-"], message).status !== 0)
-            return undefined;
-        return head(dir);
+        return commitAll(dir, subject, body).commit;
     }
     catch {
         return undefined;
     }
 }
+/**
+ * Commit work that landed - the code or tests a pulse passed, with the record of what they are built from. Unlike any
+ * other step's, this commit is not only a record: the next unit of work puts the module back to its last commit, and
+ * would undo what landed with it. So a commit that cannot be made is raised, as the environment's, with what git said -
+ * the work left in place, uncommitted. Nothing changed, nothing is committed. Returns the commit, if any.
+ */
+export function landWork(dir, subject, body) {
+    const moduleDir = moduleDirOf(dir);
+    let made;
+    try {
+        made = commitAll(dir, subject, body);
+    }
+    catch (error) {
+        made = { failed: error instanceof Error ? error.message : String(error) };
+    }
+    if (made.failed !== undefined)
+        throw historyError(moduleDir, made.failed);
+    return made.commit;
+}
+/** Commit everything the step changed in the module `dir` belongs to: the commit, nothing when nothing changed, or why git failed. */
+function commitAll(dir, subject, body) {
+    const moduleDir = moduleDirOf(dir);
+    if (!existsSync(moduleDir))
+        return {};
+    if (!ensureHistory(moduleDir))
+        return { failed: `git could not make the module's history in ${join(moduleDir, HISTORY_DIR)}` };
+    const failed = (result) => (result.error?.message ?? `${result.stderr}${result.stdout}`.trim()) || `git exited ${result.status}`;
+    const added = git(moduleDir, ["add", "-A"]);
+    if (added.status !== 0)
+        return { failed: failed(added) };
+    if (git(moduleDir, ["diff", "--cached", "--quiet"]).status === 0)
+        return {};
+    const message = body ? `${subject}\n\n${body.trim()}\n` : subject;
+    const committed = git(moduleDir, ["commit", "-q", "-F", "-"], message);
+    if (committed.status !== 0)
+        return { failed: failed(committed) };
+    const commit = head(dir);
+    return commit !== undefined ? { commit } : {};
+}
 /**
  * The notes the harness writes once a pulse has ended, committed - or the next pulse, putting the module back to its last
  * commit, would take them away. Into the pulse's own commit when it landed one - `landedSince` (ms), when it started - so

package/dist/regenerate/loop.d.ts

@@ -385,6 +385,12 @@ export declare function isUpToDate(status: ModuleStatus): boolean;
 export declare function describeModules(statuses: ModuleStatus[], options?: {
     for?: "chat" | "command line";
 }): string;
+/**
+ * A module's first pulse when it builds one functional spec - the project set up and the smallest thing that runs: it lands on its
+ * unit tests alone, with no review. A reviewer, and an arbiter after it, on a scaffold is time spent before anything can
+ * be tried.
+ */
+export declare function skipsReview(cases: JobCases): boolean;
 /** How a code pulse went, for its line in the notes: the rounds it took, its test runs, what the debugger found. */
 export declare function codeStory(result: {
     attempts?: number;