@turri-dev/cli 0.1.7 → 0.1.8-next.91b957c

package/dist/regenerate/chunk-plan.d.ts

@@ -79,6 +79,11 @@ export declare function stepsOf(input: PlanInput, draft: DraftJob[]): Array<Draf
     step: SpecStep;
 }>;
 export declare const MAX_SPECS_PER_JOB = 3;
+/** The most a pulse's title is - in words, and in characters - however it was made: a host shows it as its heading. */
+export declare const TITLE_WORDS = 10;
+export declare const TITLE_CHARS = 70;
+/** A title held to `TITLE_WORDS` and `TITLE_CHARS` - or less, for room beside it - cut at a word, with an ellipsis. */
+export declare function shortTitle(text: string, chars?: number, words?: number): string;
 export declare const MAX_LINES_PER_JOB = 120;
 /**
  * A functional spec to build, for the grouping: the number the agent answers with, its text, and whether it is built
@@ -147,12 +152,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";
@@ -70,6 +71,19 @@ export function stepsOf(input, draft) {
     });
 }
 export const MAX_SPECS_PER_JOB = 3;
+/** The most a pulse's title is - in words, and in characters - however it was made: a host shows it as its heading. */
+export const TITLE_WORDS = 10;
+export const TITLE_CHARS = 70;
+/** A title held to `TITLE_WORDS` and `TITLE_CHARS` - or less, for room beside it - cut at a word, with an ellipsis. */
+export function shortTitle(text, chars = TITLE_CHARS, words = TITLE_WORDS) {
+    const all = text.trim().split(/\s+/).filter((word) => word !== "");
+    let cut = all.slice(0, words).join(" ");
+    if (all.length <= words && cut.length <= chars)
+        return cut;
+    if (cut.length > chars - 1)
+        cut = cut.slice(0, chars - 1).replace(/\s+\S*$/, "") || cut.slice(0, chars - 1);
+    return `${cut.replace(/[\s,.;:-]+$/, "")}…`;
+}
 export const MAX_LINES_PER_JOB = 120;
 /** How often an answer that does not hold goes back to its agent before the plan falls back. */
 const RETRIES = 2;
@@ -123,6 +137,9 @@ export function groupProblems(specs, answer, maxSpecs = MAX_SPECS_PER_JOB) {
         }
         if (group.title.trim() === "")
             problems.push("Every group needs a title.");
+        else if (group.title.trim().split(/\s+/).length > TITLE_WORDS || group.title.trim().length > TITLE_CHARS) {
+            problems.push(`"${group.title}" is too long for a title: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.`);
+        }
     }
     return problems;
 }
@@ -226,7 +243,8 @@ function draftOf(chunks, net) {
     })
         .filter((entry) => entry.changes.length > 0)
         .map((entry) => ({
-        title: entry.chunk.title,
+        // However the title was made - an agent's, a spec's first line, several joined - it is held to the limit.
+        title: shortTitle(entry.chunk.title),
         reason: entry.chunk.built !== undefined
             ? "what is built already, changed"
             : entry.chunk.specs.length > 0 && entry.chunk.specs.every(regeneratesAgain)
@@ -237,7 +255,7 @@ function draftOf(chunks, net) {
 }
 /** A spec's first line, as a group's title when no agent gave one. */
 function titleOf(change) {
-    return textOf(change).split("\n")[0].replace(/^-\s*/, "").slice(0, 80);
+    return shortTitle(textOf(change).split("\n")[0].replace(/^-\s*/, ""));
 }
 /**
  * Cut the queue's work - from `input.base` to `input.current` - into jobs, as the three steps say. Returns the draft
@@ -245,6 +263,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 +393,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 +409,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 +434,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");
     }
@@ -458,7 +487,10 @@ async function cut(input, agents, notes) {
             }
             runs.push(run);
             say(`"${group.title}" is past ${maxLines} lines with its definitions and reqs - split into ${runs.length} pulses`);
-            runs.forEach((specs, index) => split.push({ specs, title: specs.length === 1 ? titleOf(bySpec.get(specs[0])) : `${group.title} (${index + 1} of ${runs.length})` }));
+            runs.forEach((specs, index) => split.push({
+                specs,
+                title: specs.length === 1 ? titleOf(bySpec.get(specs[0])) : `${shortTitle(group.title, TITLE_CHARS - 9, TITLE_WORDS - 3)} (${index + 1} of ${runs.length})`,
+            }));
         });
         const before = placement;
         // A req placed with a group that split goes with the first functional spec of it.
@@ -508,7 +540,8 @@ export function groupPrompt(specs, steering, maxSpecs = MAX_SPECS_PER_JOB) {
         "Never group specs only because they are of the same kind.",
         "",
         "Only functional specs next to each other in the same module go together, and they stay in the order given: the",
-        "order is what each is built on. Give each group a short title that says what it builds.",
+        `order is what each is built on. Give each group a title that says what it builds - at most ${TITLE_WORDS} words and ${TITLE_CHARS}`,
+        "characters: it heads the group's pulse where the person watches the work, and a longer one is cut short there.",
         "",
         "The specification is split into modules - a ***plain matter, not how the code is laid out. Each numbers its",
         "functional specs from 1: each below is given with its module and its id there, and a number of its own to answer with.",
@@ -588,9 +621,9 @@ export function llmChunkAgents(options) {
             tool: (take) => defineTool({
                 name: "submit_groups",
                 label: "Submit the groups",
-                description: "The new functional specs in groups, in order: each group's spec numbers and a short title.",
+                description: `The new functional specs in groups, in order: each group's spec numbers and a title of at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.`,
                 parameters: Type.Object({
-                    groups: Type.Array(Type.Object({ specs: Type.Array(Type.Number()), title: Type.String() })),
+                    groups: Type.Array(Type.Object({ specs: Type.Array(Type.Number()), title: Type.String({ description: `What the group builds: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.` }) })),
                     notes: Type.Optional(Type.String({ description: NOTES })),
                 }),
                 async execute(_id, params) {

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

@@ -1,6 +1,8 @@
 import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
 /**
- * Every render agent's whole conversation, streamed to a file of its own as it happens - always.
+ * Every render agent's whole conversation, streamed to a file of its own as it happens: an agent of a pulse's for as
+ * long as the pulse runs - what the diagnosis of a failure reads - and kept after it in debug mode alone (`debug:`,
+ * pulse-files.ts); an agent outside a pulse only in debug mode.
  *
  * A job's transcript keeps a tool call's arguments to 600 characters and its result to 2000, and only while pi is
  * running. When an agent goes wrong, what it was actually

package/dist/regenerate/debug-log.js

@@ -2,9 +2,13 @@ import { appendFileSync, existsSync } from "node:fs";
 import { maskSecrets } from "./masking.js";
 import { dirname, join, resolve, sep } from "node:path";
 import { currentJob, reportActivity, reportTranscript } from "./activity.js";
+import { debugMode } from "../config.js";
+import { pulseWrote } from "./pulse-files.js";
 import { ensureInScratch, MODULES_DIR, projectRootOf, scratchDir } from "./paths.js";
 /**
- * Every render agent's whole conversation, streamed to a file of its own as it happens - always.
+ * Every render agent's whole conversation, streamed to a file of its own as it happens: an agent of a pulse's for as
+ * long as the pulse runs - what the diagnosis of a failure reads - and kept after it in debug mode alone (`debug:`,
+ * pulse-files.ts); an agent outside a pulse only in debug mode.
  *
  * A job's transcript keeps a tool call's arguments to 600 characters and its result to 2000, and only while pi is
  * running. When an agent goes wrong, what it was actually
@@ -47,8 +51,11 @@ export function debugLogOf(session) {
  */
 export function startDebugLog(session, options) {
     let file;
+    const dir = debugDirFor(options.cwd);
+    // Outside a pulse nothing reads it - no diagnosis, no person but one debugging turri.
+    if (currentJob() === undefined && !debugMode(dirname(dirname(dir))))
+        return undefined;
     try {
-        const dir = debugDirFor(options.cwd);
         ensureInScratch(dirname(dir), dir);
         const stamp = new Date().toISOString().replace(/[:.]/g, "-");
         const name = options.label.replace(/[^\w.-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "agent";
@@ -56,6 +63,7 @@ export function startDebugLog(session, options) {
         for (let n = 2; existsSync(file); n += 1)
             file = join(dir, `${stamp}-${name}-${n}.log`);
         appendFileSync(file, maskSecrets(header(session, options)), { flag: "wx" });
+        pulseWrote(file);
     }
     catch (error) {
         reportActivity(`debug log not started: ${error instanceof Error ? error.message : String(error)}`);

package/dist/regenerate/diagnose.js

@@ -1,6 +1,7 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { ask, BEGIN, createExecutor } from "../pi.js";
+import { debugMode } from "../config.js";
 import { confinedTools } from "./confine.js";
 /** How many tool calls the diagnosis may make before it is told to decide. */
 export const DIAGNOSIS_CALLS = 40;
@@ -49,8 +50,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();
@@ -75,6 +78,13 @@ export function diagnosisPrompt(options) {
         "Find the root cause, not the last symptom: read the failing run's output and the agents' logs around where it",
         "failed, and follow it to the spec line, the code, the test, the environment or the harness it comes from. Then",
         "call submit_diagnosis: what happened, why, whose it is to fix, and exactly what to do.",
+        ...(debugMode(options.projectDir)
+            ? []
+            : [
+                "",
+                "The logs and the full outputs are removed as the job ends - the project is not in debug mode - so never send",
+                "the person to one of them: quote what in them shows the cause.",
+            ]),
         "",
         ...options.failures.flatMap((failure, index) => [`<attempt ${index + 1}>`, failure.trim().slice(-12_000), `</attempt ${index + 1}>`, ""]),
     ].join("\n");

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,