@turri-dev/cli 0.1.7 → 0.1.8-next.b03162b

package/dist/ledger-cli.js

@@ -0,0 +1,50 @@
+import { resolve } from "node:path";
+import { readLedger } from "./regenerate/ledger.js";
+import { describePastPulse, describeRuns, ledgerProjects, runViews } from "./regenerate/ledger-view.js";
+const USAGE = `usage: turri ledger [pulse] [--runs <n>] [--json]
+
+What turri did here, from the project's ledger (.turri/ledger): the last runs, a line a pulse - how each ended, how
+long it took and what it cost. With a pulse's id, or the start of it, that pulse: its rounds, test runs, verdicts,
+healers, what turri refused and what its history recorded. --json prints the events themselves, a JSON line each.
+
+  --runs <n>   how many runs to show, the most recent first (default 5)
+  --json       the events, as the ledger has them - the pulse's alone with a pulse`;
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+    console.log(USAGE);
+    process.exit(0);
+}
+const runsAt = args.indexOf("--runs");
+const runs = runsAt >= 0 ? Number(args[runsAt + 1]) : 5;
+if (runsAt >= 0 && (!Number.isInteger(runs) || runs < 1)) {
+    console.error(`--runs takes a number of runs, at least 1\n\n${USAGE}`);
+    process.exit(1);
+}
+const [pulse] = args.filter((arg, at) => !arg.startsWith("-") && (runsAt < 0 || at !== runsAt + 1));
+const projects = ledgerProjects(process.cwd());
+if (projects.length === 0) {
+    console.log("No ledger here: turri has not run in this folder, or in a project under it, since the ledger began.");
+    process.exit(0);
+}
+if (args.includes("--json")) {
+    for (const project of projects)
+        for (const entry of readLedger(project, pulse !== undefined ? { job: pulse } : {}))
+            console.log(JSON.stringify(entry));
+    process.exit(0);
+}
+if (pulse !== undefined) {
+    const described = describePastPulse(projects, pulse);
+    if (described === undefined) {
+        console.error(`The ledger has no pulse ${pulse}.`);
+        process.exit(1);
+    }
+    console.log(described);
+    process.exit(0);
+}
+for (const project of projects) {
+    if (projects.length > 1)
+        console.log(`── ${resolve(project)}\n`);
+    console.log(describeRuns(runViews(project).slice(0, runs)));
+    if (projects.length > 1)
+        console.log("");
+}

package/dist/loop-cli.js

@@ -5,6 +5,7 @@ import { configForSpec, inheritModel, modelOnly, modelSpec, projectModels, readP
 import { PACKAGE_ROOT } from "./environment.js";
 import { c } from "./module-report.js";
 import { describeTurnIncident, onModelEvent } from "./regenerate/activity.js";
+import { ledgerWanted, startLedger } from "./regenerate/ledger.js";
 import { tryItCommand } from "./regenerate/delivery.js";
 import { describeDiagnosis, diagnoseFailure } from "./regenerate/diagnose.js";
 import { createJobRegistry, pulseName } from "./regenerate/jobs.js";
@@ -32,6 +33,9 @@ export async function runLoop(options) {
     // 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);
+    // What the run does, as facts, in the project's .turri/ledger.
+    if (ledgerWanted() && options.dryRun !== true)
+        startLedger({ mode: options.command?.[0] ?? "headless", project: projectDir, warn: (message) => console.error(message) });
     const buildDir = options.buildDir !== undefined && options.dryRun !== true ? resolve(options.buildDir) : undefined;
     if (buildDir !== undefined)
         refuseBuildDir(buildDir, projectDir);

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

@@ -9,6 +9,7 @@ import { checkAgainstScript, ENVIRONMENT_ERROR_TOOL, EnvironmentError, environme
 import { MODULES_DIR, projectRootOf, sessionsDir } from "./regenerate/paths.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";
+import { firstLine, record } from "./regenerate/ledger.js";
 let thinkingSource;
 /**
  * Where sub-agents take their thinking level from: the conversation that started them.
@@ -280,6 +281,8 @@ async function askOnce(session, text, onDelta) {
     // Calls to one tool failing one after another - arguments it refuses, or errors - with nothing going through.
     let failing = 0;
     let failingTool;
+    /** When each tool call under way started, by its id: how long it took is recorded as it ends. */
+    const toolStarted = new Map();
     harnessStops.delete(session);
     reportNow("waiting for the model");
     // Every entry says which agent it is from, and what it runs on - for reading one agent at a time.
@@ -348,6 +351,7 @@ async function askOnce(session, text, onDelta) {
             }
         }
         if (event.type === "tool_execution_start") {
+            toolStarted.set(event.toolCallId, Date.now());
             const args = JSON.stringify(event.args ?? {});
             transcript({ kind: "tool", text: `${shownName(event.toolName)} ${clipText(args, MAX_TOOL_ARGS)}`, full: `${shownName(event.toolName)} ${args}` });
             const took = Date.now() - stepStarted;
@@ -369,6 +373,9 @@ async function askOnce(session, text, onDelta) {
                 stopTurn(session, `${failing} ${shownName(event.toolName)} calls failed in a row`);
             }
             const output = resultText(event.result);
+            const started = toolStarted.get(event.toolCallId);
+            toolStarted.delete(event.toolCallId);
+            record({ kind: "tool.call", tool: event.toolName, ms: started !== undefined ? Date.now() - started : 0, ok: !event.isError, resultChars: output.length }, { agent: modelEventOf(session) });
             transcript({ kind: "result", text: clipText(output, MAX_TOOL_RESULT), error: event.isError, full: output });
             const line = describeToolResult(event.toolName, event.result, event.isError);
             if (line !== undefined)
@@ -483,6 +490,7 @@ async function askOnce(session, text, onDelta) {
     // A turn turri ended is ended, whatever the provider was doing then: what comes back of the abort is not the provider failing.
     if (providerError !== undefined && stoppedFor === undefined) {
         debug?.note(`turn ended with a provider error after ${seconds(Date.now() - turnStarted)}: ${providerError}`);
+        record({ kind: "provider.error", error: firstLine(providerError, 300), transient: TRANSIENT_PROVIDER_ERROR.test(providerError) }, { agent: modelEventOf(session) });
         throw new ProviderError(`${session.model?.id ?? "model"}: ${providerError}`);
     }
     debug?.note(`turn finished after ${seconds(Date.now() - turnStarted)}`);
@@ -659,6 +667,11 @@ export function guardRepeats(tools, session, budget) {
     // Calls refused in the restricted turn under way, and which turn's set that was.
     let refused = 0;
     let refusedIn;
+    /** The agent a refusal is of, for the ledger. */
+    const guardPlace = () => {
+        const current = session();
+        return current !== undefined ? { agent: modelEventOf(current) } : {};
+    };
     return tools.map((tool) => ({
         ...tool,
         execute: async (...args) => {
@@ -669,6 +682,7 @@ export function guardRepeats(tools, session, budget) {
                 if (refusedIn !== only)
                     (refused = 0), (refusedIn = only);
                 refused += 1;
+                record({ kind: "guard.refused", rule: "restricted", tool: tool.name, times: refused }, guardPlace());
                 if (refused > REFUSED_BEFORE_STOP) {
                     reportActivity(`  stopped the agent's turn: ${refused} calls to tools this turn does not have`);
                     stopTurn(current, `${refused} calls to tools this turn does not have`);
@@ -679,6 +693,7 @@ export function guardRepeats(tools, session, budget) {
             }
             calls += 1;
             if (budget !== undefined && !budget.finish.includes(tool.name) && calls > budget.calls) {
+                record({ kind: "guard.refused", rule: "budget", tool: tool.name, times: calls - budget.calls }, guardPlace());
                 if (calls > budget.calls * 2) {
                     reportActivity(`  stopped the agent's turn: ${calls} tool calls, past its budget of ${budget.calls}`);
                     stopTurn(session(), `${calls} tool calls, past its budget of ${budget.calls}`);
@@ -707,6 +722,8 @@ export function guardRepeats(tools, session, budget) {
                 // Anything else may have changed what a look would find.
                 looks.clear();
             }
+            if (repeats > REPEATS_ALLOWED)
+                record({ kind: "guard.refused", rule: "repeat", tool: tool.name, times: repeats }, guardPlace());
             if (repeats > REPEATS_BEFORE_STOP) {
                 reportActivity(`  stopped the agent's turn: it made the same ${tool.name} call ${repeats} times with nothing changed`);
                 stopTurn(session(), `the same ${tool.name} call ${repeats} times with nothing changed`);

package/dist/regenerate/activity.d.ts

@@ -36,6 +36,9 @@ export interface ActivitySink {
         kind: string;
         summary: string;
     };
+    /** The project the job works in, and its module: where what it does is recorded (ledger.ts). */
+    project?: string;
+    module?: string;
     /** The spec was found to contradict itself - for the person to decide. */
     specConflict?(conflict: SpecConflict): void;
     /** The functional spec being built now, or nothing when none is. */
@@ -89,6 +92,12 @@ export declare function currentJob(): {
     kind: string;
     summary: string;
 } | undefined;
+/** Where this code runs: the job it runs for, its project and its module - each when it runs for one. */
+export declare function currentPlace(): {
+    job?: string;
+    project?: string;
+    module?: string;
+};
 /**
  * The conversation an agent is having, as it happens: what it was asked, what it wrote and
  * thought, what it called and what came back. Text and thinking arrive as deltas and are

package/dist/regenerate/activity.js

@@ -22,6 +22,17 @@ export function currentStopSignal() {
 export function currentJob() {
     return store.getStore()?.job;
 }
+/** Where this code runs: the job it runs for, its project and its module - each when it runs for one. */
+export function currentPlace() {
+    const sink = store.getStore();
+    if (sink === undefined)
+        return {};
+    return {
+        ...(sink.job !== undefined ? { job: sink.job.id } : {}),
+        ...(sink.project !== undefined ? { project: sink.project } : {}),
+        ...(sink.module !== undefined ? { module: sink.module } : {}),
+    };
+}
 export function reportTranscript(entry) {
     store.getStore()?.transcript(entry);
 }

package/dist/regenerate/agent-shell.js

@@ -1,6 +1,7 @@
 import { dirname, join, resolve, sep } from "node:path";
 import { readProjectConfig, stackOf } from "../config.js";
 import { reportNote } from "./activity.js";
+import { record } from "./ledger.js";
 import { agentEnvironment, DARWIN_TEMP_SUFFIX, packageCacheDir, TOOLCHAIN_VARIABLES } from "./agent-env.js";
 import { afterCommand, auditMessage, beforeCommand } from "./audit.js";
 import { checkCommand, machineReadable } from "./command-check.js";
@@ -67,6 +68,9 @@ export function agentShell(role, options = {}) {
             throw error;
         }
         const result = afterCommand(before);
+        if (result.putBack.length + result.left.length + result.lost.length + result.conversation.length > 0) {
+            record({ kind: "audit.putBack", putBack: result.putBack.length, left: result.left.length, lost: result.lost.length, conversation: result.conversation.length });
+        }
         if (result.putBack.length > 0)
             reportNote(`  an agent's command changed ${result.putBack.join(", ")} - put back`);
         if (result.left.length > 0)
@@ -90,6 +94,7 @@ export function agentShell(role, options = {}) {
         async run(command, runOptions = {}) {
             const checked = checkCommand(command, commandFence);
             if (!checked.ok) {
+                record({ kind: "command.refused", rule: checked.rule });
                 reportNote(`  refused an agent's command (${checked.rule}): ${command.length > 120 ? `${command.slice(0, 120)}...` : command}`);
                 const output = `Not run: ${checked.reason}`;
                 runOptions.onData?.(Buffer.from(output));

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/chunk-plan.d.ts

@@ -147,12 +147,6 @@ export interface ChunkAgents {
 export declare function groupProblems(specs: NewSpec[], answer: GroupAnswer, maxSpecs?: number): string[];
 /** What is wrong with a placement: every new req once, each where there is such a job. */
 export declare function placeProblems(input: PlaceInput, answer: PlaceAnswer): string[];
-/**
- * Cut the queue's work - from `input.base` to `input.current` - into jobs, as the three steps say. Returns the draft
- * the work loop runs: checked (checkDraft), or, when nothing holds, the whole work as one job. `notes` is given what
- * the plan did not do as asked - the person's wishes an agent did not follow and why, an answer that did not hold, a
- * group split for its size - for the conversation to say, rather than guess.
- */
 export declare function planChunks(input: PlanInput, agents?: ChunkAgents, notes?: string[]): Promise<DraftJob[]>;
 export declare function groupPrompt(specs: NewSpec[], steering?: Steering[], maxSpecs?: number): string;
 export declare function placePrompt(input: PlaceInput): string;

package/dist/regenerate/chunk-plan.js

@@ -4,6 +4,7 @@ import { DEFAULT_CONCEPTS, extractConceptsFromDefinition, extractConceptsFromSpe
 import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS, TEST_REQUIREMENTS } from "../plain/spec.js";
 import { ask, BEGIN, createExecutor } from "../pi.js";
 import { reportActivity, reportStage } from "./activity.js";
+import { firstLine, record } from "./ledger.js";
 import { steeringBlock } from "./steer.js";
 import { marksRegenerateAgain } from "./records.js";
 import { validateConcepts } from "../plain/concepts.js";
@@ -245,6 +246,11 @@ function titleOf(change) {
  * the plan did not do as asked - the person's wishes an agent did not follow and why, an answer that did not hold, a
  * group split for its size - for the conversation to say, rather than guess.
  */
+/** A planner agent that failed: the plan falls back, and the ledger says why. */
+function plannerFailed(step, error) {
+    record({ kind: "planner.failed", step, error: firstLine(error instanceof Error ? error.message : String(error), 300) });
+    return undefined;
+}
 export async function planChunks(input, agents, notes) {
     if (input.track !== "conformance")
         return cut(input, agents, notes);
@@ -370,7 +376,7 @@ async function cut(input, agents, notes) {
         ...list.map((group) => ({ title: group.title, specs: group.specs.map((number) => bySpec.get(number)), definitions: [], reqs: [] })),
     ];
     const conformance = input.track === "conformance";
-    const grouped = conformance ? undefined : ((await agents?.group(numbered, (answer) => groupProblems(numbered, answer, maxSpecs), input.steering, maxSpecs).catch(() => undefined)) ?? undefined);
+    const grouped = conformance ? undefined : ((await agents?.group(numbered, (answer) => groupProblems(numbered, answer, maxSpecs), input.steering, maxSpecs).catch((error) => plannerFailed("group", error))) ?? undefined);
     const groups = conformance
         ? conformanceGroups(numbered, input.separately === true, maxLines, (list) => {
             const trial = chunksFor(list);
@@ -386,10 +392,14 @@ async function cut(input, agents, notes) {
     if (grouped?.notes !== undefined && grouped.notes.trim() !== "")
         say(`the grouping: ${grouped.notes.trim()}`);
     if (!conformance && agents !== undefined) {
-        if (grouped === undefined)
+        if (grouped === undefined) {
+            record({ kind: "planner.fellBack", step: "group", why: "no grouping was given" });
             say("the grouping was not given - a functional spec a pulse");
-        else if (groupProblems(numbered, grouped, maxSpecs).length > 0)
+        }
+        else if (groupProblems(numbered, grouped, maxSpecs).length > 0) {
+            record({ kind: "planner.fellBack", step: "group", why: firstLine(groupProblems(numbered, grouped, maxSpecs).join(" "), 300) });
             say(`the grouping did not hold (${groupProblems(numbered, grouped, maxSpecs).join(" ")}) - a functional spec a pulse`);
+        }
     }
     let chunks = chunksFor(groups);
     // 2. The definitions each group uses.
@@ -407,10 +417,12 @@ async function cut(input, agents, notes) {
             implementationReqs: implementationReqs.map((change, index) => ({ number: index + 1, text: textOf(change) })),
             testReqs: testReqs.map((change, index) => ({ number: index + 1, text: textOf(change) })),
         };
-        const answer = (await agents?.place(placeInput, (given) => placeProblems(placeInput, given)).catch(() => undefined)) ?? undefined;
+        const answer = (await agents?.place(placeInput, (given) => placeProblems(placeInput, given)).catch((error) => plannerFailed("place", error))) ?? undefined;
         if (answer?.notes !== undefined && answer.notes.trim() !== "")
             say(`the placement: ${answer.notes.trim()}`);
         placement = answer !== undefined && placeProblems(placeInput, answer).length === 0 ? answer : undefined;
+        if (placement === undefined && agents !== undefined)
+            record({ kind: "planner.fellBack", step: "place", why: answer === undefined ? "no placement was given" : firstLine(placeProblems(placeInput, answer).join(" "), 300) });
         if (placement === undefined && agents !== undefined)
             say("the placement did not hold - every implementation req with the first pulse, every test req with the first conformance pulse");
     }

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,8 @@ 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 { firstLine, record } from "./ledger.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";
@@ -417,6 +418,7 @@ export async function renderConformanceTests(options) {
             // every functionality's tests - and the code's unit testing script.
             stage(`running the conformance testing script on the whole suite (attempt ${rounds + 1} of ${maxRounds})`);
             rounds += 1;
+            record({ kind: "gate.round", gate: "conformance", round: rounds, of: maxRounds });
             let recheck = await runConformanceScript(buildDir, [conformanceDir], scripts);
             runs.push({ command: recheck.command, exitCode: recheck.exitCode });
             options.onRun?.(recheck.command, recheck.exitCode);
@@ -537,6 +539,7 @@ export async function renderConformanceTests(options) {
                     onDelta: options.onDelta,
                 });
                 const reason = verdict.reason.split("\n")[0].slice(0, 160);
+                record({ kind: "judge.verdict", culprit: verdict.culprit, round: rounds, reason: firstLine(verdict.reason, 300) });
                 // Stopped by the time limit while it was still getting on: no agent can give it more time. The pulse stops now -
                 // rolled back, no retry - and the person is told how to raise the limit.
                 if (verdict.culprit === "environment" && recheck.timedOut === true) {
@@ -797,9 +800,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/diagnose.js

@@ -49,8 +49,10 @@ export async function diagnoseFailure(options) {
         if (diagnosis === undefined)
             await ask(session, "You have not called submit_diagnosis. Call it now, with what you know.");
     }
-    catch {
-        // Without a diagnosis the person still gets both failures, as they were.
+    catch (error) {
+        // Without a diagnosis the person still gets both failures, as they were - and the ledger why there is none.
+        if (diagnosis === undefined)
+            throw error;
     }
     finally {
         session.dispose();

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/job-log.d.ts

@@ -17,7 +17,9 @@ export interface JobLog {
     /** `agents`: a line per agent - its turns, compactions and cost. */
     end(status: string, report: string | undefined, agents?: string[]): void;
 }
-/** The folder a job's log goes in: the project of the first module it writes, from its lanes. */
+/** The project a job works in: the one of the first module it writes, from its lanes. */
+export declare function projectOfLanes(lanes: string[]): string | undefined;
+/** The folder a job's log goes in: `.turri/jobs` in its project. */
 export declare function jobLogDir(lanes: string[]): string | undefined;
 export declare function startJobLog(job: {
     id: string;

package/dist/regenerate/job-log.js

@@ -2,12 +2,15 @@ import { appendFileSync, existsSync } from "node:fs";
 import { maskSecrets } from "./masking.js";
 import { dirname, isAbsolute, join, sep } from "node:path";
 import { ensureInScratch, MODULES_DIR, projectRootOf, scratchDir } from "./paths.js";
-/** The folder a job's log goes in: the project of the first module it writes, from its lanes. */
-export function jobLogDir(lanes) {
+/** The project a job works in: the one of the first module it writes, from its lanes. */
+export function projectOfLanes(lanes) {
     const lane = lanes.find((candidate) => isAbsolute(candidate) && candidate.split(sep).includes(MODULES_DIR));
-    if (lane === undefined)
-        return undefined;
-    return join(scratchDir(join(projectRootOf(lane), MODULES_DIR)), "jobs");
+    return lane !== undefined ? projectRootOf(lane) : undefined;
+}
+/** The folder a job's log goes in: `.turri/jobs` in its project. */
+export function jobLogDir(lanes) {
+    const project = projectOfLanes(lanes);
+    return project !== undefined ? join(scratchDir(join(project, MODULES_DIR)), "jobs") : undefined;
 }
 export function startJobLog(job, lanes) {
     const dir = jobLogDir(lanes);

package/dist/regenerate/jobs-tree.d.ts

@@ -3,15 +3,17 @@ import type { TranscriptStyle } from "./transcript-view.ts";
 /**
  * The side panel's Jobs view: the queue as a tree, read one job at a time.
  *
- * Three sections - running, queued, finished - each opened and closed on its own, and under them one line per job:
+ * Four sections - running, queued, finished, and earlier sessions' from the ledger - each opened and closed on its own,
+ * and under them one line per job:
  * its module, its time and its cost. A job opened shows all of what it builds - the diff, or the spec - and, running,
- * what it is doing; finished, what went on in it. So what is planned can be read without every diff on the screen at once.
+ * what it is doing; finished, what went on in it; earlier, what the ledger says of it. So what is planned can be read
+ * without every diff on the screen at once.
  *
  * A cursor moves over the sections and the jobs; it stays on its row, whatever moves under it - a job that finishes
  * leaves its row to the one after it. A job opened stays open while it stays where it is: moving to another section
  * it closes, and turns up there collapsed. The state is the conversation's, kept while the panel is closed.
  */
-export type JobSection = "running" | "queued" | "finished";
+export type JobSection = "running" | "queued" | "finished" | "earlier";
 export declare const SECTIONS: JobSection[];
 export interface JobsTreeState {
     /** Which sections are open. */
@@ -24,6 +26,8 @@ export interface JobsTreeState {
     cursor: number;
     /** The first line shown. */
     top: number;
+    /** How many runs the ledger has beyond the earlier sessions shown: said under them. */
+    earlierMore?: number;
 }
 export declare function createJobsTreeState(): JobsTreeState;
 export declare function sectionOf(job: Job): JobSection;

package/dist/regenerate/jobs-tree.js

@@ -3,11 +3,15 @@ import { describeAgents } from "./activity.js";
 import { didNotPass, finishedMark, pulseCost, spinner } from "./job-panel.js";
 import { formatDuration, pulseName } from "./jobs.js";
 import { diffFiles, fileHeader, PLAIN_PAINT } from "./diff-view.js";
-export const SECTIONS = ["running", "queued", "finished"];
+export const SECTIONS = ["running", "queued", "finished", "earlier"];
+/** A section as its header says it. */
+const SECTION_NAMES = { running: "running", queued: "queued", finished: "finished", earlier: "earlier sessions" };
 export function createJobsTreeState() {
-    return { open: { running: true, queued: true, finished: false }, openJobs: new Map(), openFiles: new Map(), cursor: 0, top: 0 };
+    return { open: { running: true, queued: true, finished: false, earlier: false }, openJobs: new Map(), openFiles: new Map(), cursor: 0, top: 0 };
 }
 export function sectionOf(job) {
+    if (job.earlier !== undefined)
+        return "earlier";
     return job.status === "running" ? "running" : job.status === "queued" ? "queued" : "finished";
 }
 /** The files of a job's diff, in the order they are shown - read once for each diff, not on every frame. */
@@ -47,7 +51,7 @@ export function selectJob(jobs, state, id) {
     const job = jobs.find((entry) => entry.id === id);
     if (job === undefined)
         return false;
-    const section = job.status === "running" ? "running" : job.status === "queued" ? "queued" : "finished";
+    const section = sectionOf(job);
     state.open[section] = true;
     state.openJobs.set(id, section);
     const at = jobsTreeRows(jobs, state).findIndex((row) => row.kind === "job" && row.job.id === id);
@@ -60,13 +64,16 @@ export function jobsTreeRows(jobs, state) {
     const bySequence = jobs.filter((job) => job.replacedBy === undefined).sort((a, b) => a.sequence - b.sequence);
     const of = (section) => {
         const inSection = bySequence.filter((job) => sectionOf(job) === section);
-        return section === "finished" ? inSection.sort((a, b) => (b.finishedAt ?? b.sequence) - (a.finishedAt ?? a.sequence) || b.sequence - a.sequence) : inSection;
+        return section === "finished" || section === "earlier" ? inSection.sort((a, b) => (b.finishedAt ?? b.sequence) - (a.finishedAt ?? a.sequence) || b.sequence - a.sequence) : inSection;
     };
     // Forget what is open for jobs that moved on - they close as they leave.
     for (const job of jobs)
         isOpen(state, job);
     return SECTIONS.flatMap((section) => {
         const inSection = of(section);
+        // Earlier sessions are there only when the ledger has some.
+        if (section === "earlier" && inSection.length === 0)
+            return [];
         const jobRows = (job) => [
             { kind: "job", section, job },
             // An open job's diff, a row a file: each opens and closes on its own.
@@ -82,7 +89,8 @@ export function jobsTreeRows(jobs, state) {
 const MARK = { running: spinner, queued: () => "·", succeeded: () => "✓", failed: () => "✗", stopped: () => "■" };
 /** A pulse's mark: running or queued as it is; finished, in the colour of how it ended - green it passed, red it failed or did not pass, stopped amber. */
 function markOf(job, style) {
-    if (sectionOf(job) !== "finished")
+    const section = sectionOf(job);
+    if (section !== "finished" && section !== "earlier")
         return MARK[job.status]?.(Date.now()) ?? "·";
     return finishedMark(job, { success: style.success ?? style.added, error: style.error, warning: style.warning ?? style.accent });
 }
@@ -106,6 +114,9 @@ function named(jobs, id) {
 /** All of a job, opened: what it builds, and - running - what it is doing; waiting, what it waits on; done, how it ended. */
 function detailLines(job, jobs, width, style) {
     const indent = "        ";
+    // An earlier session's: what the ledger says of it - its transcript is its log's alone.
+    if (job.earlier !== undefined)
+        return job.earlier.lines.flatMap((line) => wrap(line, width, indent, /FAILED|ended with/.test(line) ? style.error : style.muted));
     const lines = [];
     // A diff is shown a file at a time, in rows of their own after these.
     if ((job.diff === undefined || job.diff.trim() === "") && job.building !== undefined) {
@@ -170,7 +181,7 @@ export function jobsTreeLines(jobs, state, width, style) {
                 lines.push("");
                 rowStarts[index] = lines.length;
             }
-            const header = `${pointer} ${state.open[row.section] ? "▾" : "▸"} ${row.section} (${row.count})`;
+            const header = `${pointer} ${state.open[row.section] ? "▾" : "▸"} ${SECTION_NAMES[row.section]} (${row.count})`;
             lines.push(here ? style.heading(header) : style.muted(header));
             return;
         }
@@ -197,6 +208,10 @@ export function jobsTreeLines(jobs, state, width, style) {
         if (open)
             lines.push(...detailLines(job, jobs, width, style));
     });
+    // The ledger has more than the runs shown: where to find them.
+    if (state.open.earlier && (state.earlierMore ?? 0) > 0) {
+        lines.push(style.muted(`      ${state.earlierMore} earlier run${state.earlierMore === 1 ? "" : "s"} in the ledger - turri ledger lists them`));
+    }
     return { lines, rowStarts, rows };
 }
 /** How far a job's files, and their lines, are indented under it. */

package/dist/regenerate/jobs.d.ts

@@ -84,6 +84,15 @@ export interface Job {
     announce?: string;
     error?: string;
     details?: unknown;
+    /**
+     * A pulse of an earlier session, as the ledger recorded it - not this session's registry's: shown, never run, halted or
+     * waited for. Its run, how and when that run was started, and what the ledger says of it, a line each.
+     */
+    earlier?: {
+        run: string;
+        runMode?: string;
+        lines: string[];
+    };
 }
 export interface JobOutcome {
     report: string;
@@ -163,6 +172,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,