@turri-dev/cli 0.1.8-next.e553476 → 0.1.8

package/dist/regenerate/regenerate.js

@@ -11,7 +11,8 @@ import { debugFailure, diagnosisText } from "./debugger.js";
 import { codebaseMap, diffFiles, digestFiles, wroteNothing } from "./codebase.js";
 import { confinedTools } from "./confine.js";
 import { buildSpecDiffPrompt, describeSpecChange, reviewedSpec, sectionModules } from "./prompt.js";
-import { abandonWork, recordHistory, startWork } from "./lineage.js";
+import { abandonWork, landWork, startWork } from "./lineage.js";
+import { healing, record, signatureHash } from "./ledger.js";
 import { createWorkLedger, SUBMIT_WORK_NOTE } from "./submit-work.js";
 import { CODER_COMPACTION } from "./compaction.js";
 import { gapMark, gapsSince, NOTES_TURN, notesForSession, passedOutcome, recordNote, withNotes } from "./notes.js";
@@ -193,7 +194,7 @@ export async function renderSpecDiff(options) {
     if (builtBefore !== null && sameSpec(builtBefore, tree) && !dryRun) {
         stage("the specs were only restructured - nothing to render; recording the spec as it is now laid out");
         writeCodeRecord(tip.buildDir, tree);
-        recordHistory(tip.buildDir, `spec restructured: ${summarizeDiff(options.diff)}`, options.diff);
+        landWork(tip.buildDir, `spec restructured: ${summarizeDiff(options.diff)}`, options.diff);
         return {
             moduleName,
             buildDir: tip.buildDir,
@@ -440,7 +441,7 @@ export async function renderSpecDiff(options) {
                             : timedOut && seen < STUCK_ROUNDS
                                 ? `the unit testing script did not finish in ${Math.round(verdict.run.timeoutMs / 1000)}s - a debugger works out whether something hangs`
                                 : `the same failure ${seen} times - a debugger looks at it with fresh eyes`);
-                        const found = await debugFailure({
+                        const found = await healing("debugger", () => debugFailure({
                             buildDir,
                             failure: verdict.run.output,
                             times,
@@ -450,7 +451,7 @@ export async function renderSpecDiff(options) {
                             label: `${moduleName} spec change`,
                             ...(debuggerModel !== undefined ? { model: debuggerModel } : {}),
                             onDelta: options.onDelta,
-                        }).catch(() => undefined);
+                        }), (finding) => finding?.rootCause);
                         // Nothing hangs: the suite needs more time than a test run may take, and no agent can give it that.
                         if (found?.tooSlow === true) {
                             stage(`the unit testing script needs more than the ${Math.round(verdict.run.timeoutMs / 1000)}s a test run may take - stopping`);
@@ -477,6 +478,7 @@ export async function renderSpecDiff(options) {
                             ].join("\n");
                         }
                     }
+                    record({ kind: "gate.round", gate: "unit tests", round: followUp + 1, of: MAX_FOLLOW_UPS, ...(key !== undefined ? { signature: signatureHash(key) } : {}) });
                     stage(`${verdict.staticOnly ? "static checks" : "unit tests"} not passing - fixing (round ${followUp + 1} of ${MAX_FOLLOW_UPS})`);
                     response = await ask(executor, prompt, options.onDelta);
                     continue;
@@ -554,7 +556,7 @@ export async function renderSpecDiff(options) {
         stage("recording what the code is built from, and committing it");
         // Steered, it is built from the spec as it was steered to - the record the loop moved with it.
         writeCodeRecord(buildDir, steering?.target ?? tree);
-        recordHistory(buildDir, `spec diff: ${summarizeDiff(options.diff)}`, options.diff);
+        landWork(buildDir, `spec diff: ${summarizeDiff(options.diff)}`, options.diff);
     };
     if (!unitPassed) {
         stage(unitReviewStopped ? "the unit tests pass but still leave the change untested - undoing the change" : "unit tests NOT passing - undoing the change");

package/dist/regenerate/regression.js

@@ -6,7 +6,8 @@ import { reportActivity, reportStage, unitOf } from "./activity.js";
 import { confinedTools } from "./confine.js";
 import { projectRootOf } from "./paths.js";
 import { buildRegressionFixPrompt, sectionModules } from "./prompt.js";
-import { abandonWork, markWork, recordHistory } from "./lineage.js";
+import { abandonWork, landWork, markWork } from "./lineage.js";
+import { record } from "./ledger.js";
 import { missingToolchainError } from "./environment-error.js";
 import { workspaceBlock } from "./workspace.js";
 import { CODER_COMPACTION } from "./compaction.js";
@@ -154,13 +155,14 @@ export async function ensureRegressionPasses(input) {
         if (passing) {
             reportStage(`${unitOf(input.moduleName)}: the whole conformance suite passes, and the unit tests with it${repairs.length > 0 ? ` after ${repairs.length} repair${repairs.length === 1 ? "" : "s"}` : ""}`);
             if (repairs.length > 0) {
-                recordHistory(input.buildDir, `regression ${input.moduleName} (pass after ${repairs.length} repair(s))`);
+                landWork(input.buildDir, `regression ${input.moduleName} (pass after ${repairs.length} repair(s))`);
             }
             return { passed: true, runs, repairs, command };
         }
         if (round === maxRounds)
             break;
         input.onEvent?.({ type: "repair", frids: input.frids });
+        record({ kind: "gate.round", gate: "regression", round: round + 1, of: maxRounds });
         reportStage(`${unitOf(input.moduleName)}: an earlier functionality broke - repairing (round ${round + 1} of ${maxRounds})`);
         repairs.push(await repairRegression({
             testsDirs: dirs,

package/dist/regenerate/services.js

@@ -8,6 +8,7 @@ import { agentShell } from "./agent-shell.js";
 import { maskSecrets } from "./masking.js";
 import { modulesScratchDir } from "./paths.js";
 import { isRunning, startInBackground, stopGroup } from "./shell.js";
+import { pulseWrote } from "./pulse-files.js";
 /**
  * What an agent starts and keeps running while it works - a server, a worker - to try the software as someone would,
  * from outside: with curl, or what the stack's own client is. Whatever the stack: the agent gives the command that
@@ -83,6 +84,8 @@ export function createServiceTools(options) {
                 return say(`Not started: ${checked.reason}`);
             mkdirSync(logsDir, { recursive: true });
             const log = join(logsDir, `${name.replace(/[^\w.-]+/g, "_")}-${randomUUID().slice(0, 8)}.log`);
+            // Read through service_logs while the pulse runs, and by no one after it (pulse-files.ts).
+            pulseWrote(log);
             const limit = Math.min(Math.max(seconds ?? DEFAULT_READY_SECONDS, 1), MAX_READY_SECONDS);
             // Started and waited on under the audit: what it writes while it comes up, outside its role, is put back.
             const { value: outcome, note } = await fenced.audited(async () => {

package/dist/regenerate/side-panel.d.ts

@@ -17,6 +17,8 @@ import type { TranscriptStyle } from "./transcript-view.ts";
 export interface SidePanelOptions {
     /** Every job, oldest first. */
     jobs: () => Job[];
+    /** Earlier sessions' pulses, from the ledger: listed under this session's, in a section of their own. */
+    earlier?: () => Job[];
     /** The regeneration's pages. Not given: the pulse list alone. */
     map?: () => MarkedPage[];
     /** Rows the panel may use. */

package/dist/regenerate/side-panel.js

@@ -1,5 +1,5 @@
 import { Key, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import { createJobsTreeState, jobsTreeLines, jobsTreeRows, keepCursorInView, scrollTree, treeKey } from "./jobs-tree.js";
+import { createJobsTreeState, jobsTreeLines, jobsTreeRows, keepCursorInView, scrollTree, sectionOf, treeKey } from "./jobs-tree.js";
 import { columnHeadings, createSpecMapState, DISCUSS_KEY, legendLines, minimap, shownPage, specMapHeader, specMapLines, switchTab, tabBar } from "./spec-map-view.js";
 export function createSidePanel(options) {
     const style = options.style;
@@ -71,7 +71,8 @@ export function createSidePanel(options) {
         const bodyHeight = Math.max(3, rows - top.length - 2);
         lastBodyHeight = bodyHeight;
         // The tree scrolls to keep the cursor in sight, and only that far.
-        const tree_ = jobsTreeLines(options.jobs(), tree, width, style);
+        // This session's pulses, and under them the earlier sessions' the ledger has.
+        const tree_ = jobsTreeLines([...options.jobs(), ...(options.earlier?.() ?? [])], tree, width, style);
         drawnTree = { rows: tree_.rows, rowStarts: tree_.rowStarts, lineCount: tree_.lines.length };
         keepCursorInView(tree, tree_.rowStarts, tree_.lines.length, bodyHeight);
         const visible = tree_.lines.slice(tree.top, tree.top + bodyHeight);
@@ -132,7 +133,7 @@ export function createSidePanel(options) {
         const job = jobs.find((entry) => entry.id === id);
         if (job === undefined)
             return;
-        const section = job.status === "running" ? "running" : job.status === "queued" ? "queued" : "finished";
+        const section = sectionOf(job);
         tree.open[section] = true;
         const at = jobsTreeRows(jobs, tree).findIndex((entry) => entry.kind === "job" && entry.job.id === id);
         if (at !== -1)

package/dist/regenerate/test-scripts.js

@@ -4,6 +4,7 @@ import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readdirSync
 import { basename, delimiter, dirname, join, resolve, sep } from "node:path";
 import { CONFIG_FILE, CONFIG_KEYS, projectConfigFile, readProjectConfig, stackConfigFile, stackConfigFileIn, stackOf, stacksOf } from "../config.js";
 import { reportActivity, reportLogNote, reportNote } from "./activity.js";
+import { record, signatureHash } from "./ledger.js";
 import { ensureInModulesScratch, modulesScratchDir } from "./paths.js";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -361,7 +362,7 @@ async function runScript(cwd, script, args, logDir, options = {}) {
     const noted = withScriptLineNote(text, script);
     // Its failures, counts and end are what the agent is shown; the whole is kept, a read_output away.
     const log = keepTestOutput(logDir, basename(script), noted);
-    return {
+    const run = {
         command: shown(script),
         exitCode: timedOut === true ? 124 : exitCode,
         output: shownTestOutput(noted, log),
@@ -370,6 +371,18 @@ async function runScript(cwd, script, args, logDir, options = {}) {
         elapsedMs: Date.now() - started,
         ...(log !== undefined ? { log } : {}),
     };
+    record({
+        kind: "script.run",
+        script: basename(script),
+        exit: run.exitCode,
+        ms: run.elapsedMs,
+        timedOut: run.timedOut === true,
+        inPlace: options.named === undefined,
+        // On code changed for the run - can_it_fail's bug: failing is what it is for.
+        ...(options.mutated === true ? { mutated: true } : {}),
+        ...(run.exitCode !== 0 ? { signature: signatureHash(failureSignature(run)) } : {}),
+    });
+    return run;
 }
 /** What bash says when a line of the script itself cannot run: a command or file that is not there, or not runnable. */
 const OWN_LINE_FAILURE = /: (No such file or directory|command not found|Permission denied)$/;
@@ -406,10 +419,10 @@ function quote(path) {
     return `'${path.replace(/'/g, "'\\''")}'`;
 }
 /** A testing script run on a fresh copy of the code: the project's script copied fresh into the staging folder, beside it. */
-async function runOnCopy(stagingRoot, script, args, logDir, limitMs) {
+async function runOnCopy(stagingRoot, script, args, logDir, limitMs, mutated) {
     const copy = join(stagingRoot, basename(script));
     writeFileSync(copy, readFileSync(script));
-    return runScript(stagingRoot, script, args, logDir, { named: copy, ...(limitMs !== undefined ? { limitMs } : {}) });
+    return runScript(stagingRoot, script, args, logDir, { named: copy, ...(limitMs !== undefined ? { limitMs } : {}), ...(mutated === true ? { mutated } : {}) });
 }
 /**
  * The harness's run of the unit testing script on the code as it is now - and run_unit_tests'.
@@ -475,7 +488,7 @@ limitMs) {
         return run;
     };
     if (project.inPlace) {
-        const inPlace = () => runScript(project.root, script, [resolve(buildDir)], buildDir, limitMs !== undefined ? { limitMs } : {});
+        const inPlace = () => runScript(project.root, script, [resolve(buildDir)], buildDir, { ...(limitMs !== undefined ? { limitMs } : {}), ...(change !== undefined ? { mutated: true } : {}) });
         const started = Date.now();
         if (change === undefined)
             return passed(await inPlace(), started);
@@ -490,7 +503,7 @@ limitMs) {
         if (change !== undefined)
             writeFileSync(join(staging.build, change.file), change.text);
         const started = Date.now();
-        return passed(await runOnCopy(staging.root, script, [staging.build], buildDir, limitMs), started);
+        return passed(await runOnCopy(staging.root, script, [staging.build], buildDir, limitMs, change !== undefined), started);
     }
     finally {
         rmSync(staging.root, { recursive: true, force: true });

package/dist/regenerate/testing.js

@@ -9,6 +9,7 @@ import { modulesScratchDir } from "./paths.js";
 import { RECORD_FILE } from "./records.js";
 import { missingToolchain, runUnitScript, scriptFailure } from "./test-scripts.js";
 import { COMMAND_TIMEOUT_MS } from "./shell.js";
+import { pulseWrote } from "./pulse-files.js";
 /** Up to this much of a run's output is shown: all of it when it fits, otherwise its end. */
 const MAX_OUTPUT_CHARS = 60_000;
 /** A test run has the same time limit as any command: see COMMAND_TIMEOUT_MS. */
@@ -92,6 +93,8 @@ export function keepOutput(dir, label, output) {
         const name = label.replace(/[^\w.-]+/g, "_").slice(0, 60);
         const file = join(logs, `${stamp}-${name}.log`);
         writeFileSync(file, typeof output === "string" ? maskSecrets(output) : maskSecrets(output.toString("utf8")));
+        // Read through read_output while the pulse runs, and by no one after it (pulse-files.ts).
+        pulseWrote(file);
         const all = readdirSync(logs).sort();
         for (const old of all.slice(0, Math.max(0, all.length - MAX_LOGS)))
             rmSync(join(logs, old), { force: true });

package/dist/regenerate/unit-review.js

@@ -3,6 +3,7 @@ import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { ask, createExecutor } from "../pi.js";
 import { reportActivity } from "./activity.js";
+import { record } from "./ledger.js";
 import { diffFiles, digestFiles } from "./codebase.js";
 import { confinedTools } from "./confine.js";
 import { REVIEWER_CALLS, reviewKind } from "./conformance-agents.js";
@@ -288,6 +289,7 @@ async function reviewLoop(options, reviewer) {
         letGo = [];
         options.stage(`reviewing the code and its unit tests (review ${reviews + 1}): does the code do what the spec says, and does each test fail when that breaks`);
         const review = await reviewer.review(request);
+        record({ kind: "review.verdict", reviewer: "unit", review: reviews + 1, pass: review.pass, problems: review.pass ? 0 : review.problems.length });
         if (review.pass) {
             options.stage("the review has nothing left to improve in the code or its unit tests");
             return waived.length > 0 ? { passed: true, waived, reviews: reviews + 1 } : { passed: true, reviews: reviews + 1 };
@@ -316,6 +318,7 @@ async function reviewLoop(options, reviewer) {
             });
             // No ruling: the review stands, as it did before there was an arbiter.
             if (ruling !== undefined) {
+                record({ kind: "arbiter.ruling", upheld: ruling.upheld.length, dismissed: ruling.dismissed.length });
                 waived.push(...ruling.dismissed.map((entry) => entry.problem));
                 if (ruling.dismissed.length > 0)
                     recordNote(options.buildDir, "pitfalls", dismissedNote(ruling, "unit test"), `${options.label} unit tests`);

package/dist/run-report.js

@@ -1,5 +1,6 @@
 import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
+import { debugMode } from "./config.js";
 import { turriIdentity } from "./environment.js";
 import { onModelEvent } from "./regenerate/activity.js";
 import { firstRegeneration } from "./regenerate/jobs.js";
@@ -290,11 +291,14 @@ export function startRunReport(options) {
             spec_gaps: specGapsOf(jobs),
             turn_incidents: turnIncidentsOf(),
             ...(exitParts ?? {}),
-            logs: {
-                jobs_dir: fromProject(join(projectRoot, ".turri", "jobs")),
-                debug_dir: fromProject(join(projectRoot, ".turri", "debug")),
-                sessions_dir: fromProject(join(projectRoot, ".turri", "sessions")),
-            },
+            // Kept only in debug mode: otherwise each pulse's go as it ends, and the sessions are never written.
+            logs: debugMode(projectRoot)
+                ? {
+                    jobs_dir: fromProject(join(projectRoot, ".turri", "jobs")),
+                    debug_dir: fromProject(join(projectRoot, ".turri", "debug")),
+                    sessions_dir: fromProject(join(projectRoot, ".turri", "sessions")),
+                }
+                : null,
         };
     };
     const write = (exitCode) => {

package/docs/config.md

@@ -42,11 +42,12 @@ Each change says when it takes effect. None needs turri started again - what tur
 | --- | --- |
 | now | `harness-model` and `models.chat` - the conversation switches to it; `parallel-jobs` - a pulse waiting for a slot starts if there is one now; `allow-to-stop-jobs` |
 | your next message | `rules-off` - for the conversation; a skill's agents from the next skill run |
-| the next pulse - one running keeps what it started with | `coding-model`, `judge-model`, every other `models.<role>`, `review`, `mutation-testing`, `turn-limit`, `compact-at`, `agent-env`, `toolchains` |
+| the next pulse - one running keeps what it started with | `coding-model`, `judge-model`, every other `models.<role>`, `review`, `mutation-testing`, `turn-limit`, `compact-at`, `agent-env`, `toolchains`, `debug` |
 | the next time the work is planned | `conformance-tests`, `conformance-budget`, `max-specs-per-pulse`, `max-lines-per-pulse` |
 | the next test run - the running pulse's too | the testing scripts, `testing-scripts-run-on` |
 | the next pulse that lands - the running one too | `release-after-pulse` |
 | the next regeneration that names no `.plain` file | `module` |
+| the next time turri starts here | `ledger-keep`, `cache-keep` |
 
 A coding model chosen this session - `--coding-model`, or `engine` - gives way to one set here: the last word wins. It says, too, what wins over the change: `models.chat` over `harness-model` (and so on), and a stack's `config.turri.<stack>.yaml`, which is not changed here, while that stack is chosen. In a project still read from `config.yaml`, the first change copies it to `config.turri.yaml` first - see [the old config.yaml](#the-old-configyaml).
 
@@ -91,6 +92,9 @@ models:                              # each agent role's model, thinking and tur
 | `conformance-tests-script` | the conformance testing script, by path from the project root | looked for - see below |
 | `prepare-environment-script` | optional: run as `<script> <build>` before every run of the conformance testing script, which runs only once it passes - see [the testing scripts](regenerating.md#the-testing-scripts). turri never writes one | the one `prepare_environment*.sh` at the root or in `test_scripts/`, else none |
 | `compact-at` | how many tokens of work - past its instructions - an agent kept through a job holds before the harness compacts it between turns; at least 1000; the project's alone | 100,000 - see [agent sessions](regenerating.md#agent-sessions) |
+| `ledger-keep` | how many megabytes of the ledger - what turri did, as facts, in `.turri/ledger` - the project keeps: past it, the oldest runs' are pruned when a run first writes; `0` keeps none, and writes none; the project's alone. See [the ledger](using.md#the-ledger) | 100 |
+| `debug` | `true` or `false`: whether turri keeps what it writes only for a person debugging it - every agent's whole log and saved session, each pulse's log, the whole outputs of its test runs and services, its agents' temporary files, and the dependencies installed in the modules a chain has left behind. `false`: only what turri reads to work is kept. `TURRI_DEBUG=1` - or `turri --debug` - turns it on for one run, and `TURRI_DEBUG=0` off; the project's alone. See [debug mode](#debug-mode) | `false` |
+| `cache-keep` | how many megabytes of package caches the project keeps - `plain_modules/.turri/cache`, and the caches in the agents' home folders: past it, the least recently written - by the newest file in each - are removed when a run starts its first agent command, each downloaded again when it is wanted; `0` keeps none; the project's alone | 4096 |
 | `max-specs-per-pulse` | the most functional specs the planner groups into one pulse - what builds one feature goes together, up to this many; a stack's file wins | 3 |
 | `max-lines-per-pulse` | the most lines of spec in one pulse - its functional specs with the definitions they bring; a group past it is split again, a functional spec a pulse; a stack's file wins | 120 |
 | `parallel-jobs` | how many jobs the chat runs at once - modules that share nothing build side by side up to it; read when the chat starts, from the folder it starts in | half this machine's cores, between one and four - see [how many jobs at once](#how-many-jobs-at-once) |
@@ -178,6 +182,23 @@ The optional prepare script - `prepare-environment-script:`, else the one `prepa
 
 A folder holding two of a kind is not guessed between: name the one to use. A script named inside `plain_modules/` is refused - agents write there, so it could be changed by the work it judges. The scripts are never linked from the specs. What they are and how they run is in [regenerating the code](regenerating.md#the-testing-scripts).
 
+## Debug mode
+
+turri writes much more than it needs to work, for a person working out why it did what it did - each agent's whole conversation, each pulse's whole transcript, every test run's whole output. Most of it nothing of turri ever reads again. So by default it is not kept:
+
+| | outside debug mode | in debug mode |
+| --- | --- | --- |
+| each pulse's log (`.turri/jobs/`) and its agents' (`.turri/debug/`) | written while the pulse runs - the diagnosis of a failure reads them - and removed as it ends | kept |
+| the logs of agents outside a pulse - the release agent, a side question | not written | kept |
+| the agents' saved sessions (`.turri/sessions/`) | not written - each is kept in memory while it works; a gated skill's alone is saved, as its run resumes from it | kept |
+| whole outputs of test runs and services (`plain_modules/.turri/logs/`, `services/`) | read by the pulse's agents while it runs, removed as it ends | kept, the last 100 outputs |
+| a module's `TMPDIR` (`plain_modules/.turri/tmp/<module>`) | emptied as each of its pulses ends | kept |
+| dependencies installed in the modules below a pulse's own in its chain (`node_modules`, `.venv`) | removed as the pulse ends: the chain is built in its tip, and a module built on again installs them again, from the cache | kept |
+
+Kept either way: the ledger - what each pulse did, how it ended, what it cost (see [the ledger](using.md#the-ledger)) - the code, its tests and their history, a gated skill's run, what a conformance explorer found, what `deploy` started, and the package caches, held to `cache-keep:`. The testing scripts install what they run with themselves, so nothing removed is ever missed by a test run.
+
+Turn it on in `config.turri.yaml` (`debug: true`, or `/turri-config debug true`), or for one run with `TURRI_DEBUG=1` or `turri --debug`.
+
 ## Credentials for the agents
 
 An agent's commands do not get the environment turri was started in: it holds your providers' API keys, cloud credentials and tokens. They get only the path, the locale, the terminal and the user, the variables that locate your toolchains (`JAVA_HOME`, `NVM_DIR`, `RUSTUP_HOME`, ... - the ones in your home found even when your shell sets none), and turri's own: a home folder of the module's own (`plain_modules/.turri/home/<module>`, kept between pulses, with a git identity of its own), a `TMPDIR`, the package caches in `plain_modules/.turri/cache`, and git stopped at the module folder, so a project that is itself a repository is never found from the code.
@@ -229,7 +250,7 @@ How a stack's config is made:
 - **Laid over `config.turri.yaml`, key by key.** What the stack's file gives wins; what it leaves out is the project's. A model it names takes what it leaves out from the project's same model - above, with the stack frontend chosen, everything renders on the project's coding model, thinking `high`.
 - **Pinned to a module when it is asked for.** A module is built with the stack it was asked for with, from its first pulse to its last: the pulses planned after it, its test runs, the scripts found, its plans and its conformance tests, whatever stack is chosen meanwhile. A pulse waiting for a free slot keeps the stack it was queued with. A change to its spec keeps its stack - unless it was built with none and has a stack of its own now; asked for again, its stack is worked out again. What `regenerate` says back names each module's stack, and so does a pulse's report.
 - **Refused with none, when that cannot build.** In a project of stacks, a module asked for with no stack - none named, none named after it, none chosen - is refused before anything is planned when `config.turri.yaml` alone names no unit testing script: every pulse would stop for want of one. The refusal names the stacks and the script each names. A spec change `write_spec_diff` writes is never refused: it is written, and said not to be built yet - passed the stack, everything written is built. `stack: none` builds with `config.turri.yaml` alone all the same.
-- **The project's alone.** `module:`, `harness-model:`, `parallel-jobs:`, `rules-off:` and `compact-at:` are read only from `config.turri.yaml` - there is one conversation, one module built when none is named, one machine. `agent-env:` and `toolchains:` in a stack's file add to the project's.
+- **The project's alone.** `module:`, `harness-model:`, `parallel-jobs:`, `rules-off:`, `compact-at:`, `ledger-keep:`, `debug:` and `cache-keep:` are read only from `config.turri.yaml` - there is one conversation, one module built when none is named, one machine. `agent-env:` and `toolchains:` in a stack's file add to the project's.
 
 The chat is told each stack's config and the one chosen. The skills that write testing scripts put each stack's in its own file once a project has two stacks, each stack named after the module it builds.
 

package/docs/development.md

@@ -56,7 +56,9 @@ The workflow signs in to npm with npm's trusted publishing (OIDC), not a token:
 | `src/regenerate/side-panel.ts`, `src/regenerate/panel-dock.ts` | the side panel, and the chat narrowed beside it when it is docked |
 | `src/screen-padding.ts` | the blank row above and below the whole screen and the two columns either side, in both of pi's ways of drawing it |
 | `src/regenerate/spec-map.ts`, `src/regenerate/spec-map-view.ts` | regen: each item's mark, from the records, the `.plain` files and the work loop's plan (`mapPlan`), and the map drawn |
-| `src/regenerate/debug-log.ts` | each render agent's whole conversation, always streamed to `.turri/debug/` |
+| `src/regenerate/debug-log.ts` | each render agent's whole conversation, streamed to `.turri/debug/` - while its pulse runs, and kept in debug mode |
+| `src/regenerate/pulse-files.ts` | what a pulse writes only for a person - its logs, outputs, temporary files, its chain's installed dependencies - removed as it ends outside debug mode |
+| `src/regenerate/ledger.ts`, `src/regenerate/ledger-view.ts`, `src/ledger-tools.ts`, `src/ledger-cli.ts` | the ledger: what turri did, as typed facts, in `.turri/ledger/` - `record()`, read back for the `ledger` tool, `pulses`, `diagnose` and `turri ledger` - see [the ledger](using.md#the-ledger) |
 | `genome/` | what turri knows and can do: `genome/skills/`, the skill library, and `genome/rules/`, the \*\*\*plain authoring rules |
 
 ## Known edges

package/docs/headless.md

@@ -84,8 +84,9 @@ The command exits `0` only when every module is complete: its code regenerated f
 | `plain_modules/<module>/code/` | the code and unit tests |
 | `plain_modules/<module>/tests/` | the conformance tests |
 | `plain_modules/<module>/code/.turri.json` | the marshalled plain tree the code is built from |
-| `.turri/jobs/` | each pulse's log: its agents, its test runs, how it ended |
-| `.turri/debug/` | each agent's whole conversation |
+| `.turri/ledger/` | what each pulse did, how it ended and what it cost - `turri ledger` |
+| `.turri/jobs/` | each pulse's log: its agents, its test runs, how it ended - with `--debug` (or `debug: true`) only |
+| `.turri/debug/` | each agent's whole conversation - with `--debug` only |
 
 And what happened, step by step, in the module's history:
 
@@ -142,7 +143,7 @@ A module that `requires` others is built in its own codebase on top of theirs: t
       "status": "succeeded", "landed": true, "failed_for_good": false,
       "started_at": "…", "duration_seconds": 512.3, "usage": { },
       "agents": [{ "label": "app 1 coding agent", "model": "…", "turns": 14, "compactions": 0, "input_tokens": 0, "…": 0 }],
-      "log_file": ".turri/jobs/….log", "error": null
+      "log_file": ".turri/jobs/….log", "error": null    // log_file null outside debug mode
     }]
   },
   "functionalities": {
@@ -164,7 +165,7 @@ A module that `requires` others is built in its own codebase on top of theirs: t
     { "kind": "stopped", "pulse_id": "5c1e0b2f", "role": "conformance explorer", "model": "…", "reason": "10 submit_exploration calls failed in a row" }
   ],
   "build_dir_export": { "exported": true, "dir": "/work/out", "module": "app", "commit": "8036b3b", "files": 23 },
-  "logs": { "jobs_dir": ".turri/jobs", "debug_dir": ".turri/debug", "sessions_dir": ".turri/sessions" }
+  "logs": { "jobs_dir": ".turri/jobs", "debug_dir": ".turri/debug", "sessions_dir": ".turri/sessions" }  // null outside debug mode
 }
 ```
 

package/docs/hosting.md

@@ -11,11 +11,13 @@
 | `createTurriExtension(host)` | turri's conversation as an extension of pi's: every tool, slash command, rule and skill the terminal has. The host is told of its jobs and asks its questions - see below. |
 | `pi` | pi itself, as turri's extension is built against it. Make the session with this one - `pi.createAgentSession`, `pi.DefaultResourceLoader` - not another copy. |
 | `readProjectConfig`, `projectModels`, `modelSpec`, `configForSpec`, `hasProjectConfig`, `stacksOf` | the project's settings, as [config.turri.yaml](config.md) has them. |
+| `debugMode` | whether turri keeps, in a project, what it writes only for debugging it - `debug:`, or `TURRI_DEBUG` over it (see [debug mode](config.md#debug-mode)). |
 | `initConfig(dir, { vendor, bedrock, force })`, `VENDORS`, `BEDROCK_REGIONS`, `BEDROCK_DEFAULT`, `bedrockModels` | a project's first config.turri.yaml, as `turri init-config` writes it: the host asks which vendor's models - `VENDORS` has each one's label and its two models, `BEDROCK_REGIONS` where Bedrock serves each maker's - and `initConfig` writes it, saying what it did. One already there keeps everything but its two models. |
 | `checkPlainFile`, `plainFileParser`, `resolveTemplateDirs`, `iterateFunctionalSpecs`, `FUNCTIONAL_REQUIREMENTS` | a spec checked and parsed, its functional specs one by one - as `turri validate` reads it. |
 | `highlightLines`, `roleOf` | a spec's lines coloured by turri's own \*\*\*plain grammar. |
 | `functionalityCompletion`, `createWorkLoop`, `createJobRegistry`, `promptOf`, `describeModules` | how far each functional spec is built, and - on a loop of the host's own with `dryRun` - the work a spec change would plan, as `turri glimpse` does. |
 | `onModelEvent`, `describeTurnIncident` | a provider failing and waited out, a turn turri ended itself. |
+| `onLedgerEvent`, `readLedger`, `ledgerDir`, `runViews`, `pulseView`, `describePulseView`, `describeRuns`, `ledgerProjects`, `earlierPulses`, `asJob` | what turri did, as facts - the [ledger](using.md#the-ledger): each event heard as it is recorded, and every run and pulse read back, earlier sessions' too - see [the ledger in a host](#the-ledger-in-a-host). |
 | `sweepOrphanedGroups` | stop what a turri killed outright left running, before anything starts. |
 
 It is turri's own code, as the terminal runs it: a 0.x release may change any of it.
@@ -64,6 +66,33 @@ the chat, and the toolbar's buttons send them too.
 - The Run button releases what is built and opens it.`;
 ```
 
+## The ledger in a host
+
+The conversation's extension starts the ledger itself, in the folder the host made the session in - so a host that runs it there, the project's, needs nothing to have one: its pulses are recorded as `host` runs, and the conversation's `pulses` and `diagnose` already tell the model of earlier sessions' pulses. What the host can do with it is show it.
+
+```js
+import { onLedgerEvent, pulseView, readLedger, runViews } from "@turri-dev/cli/host";
+
+// Each event as it is recorded - written or not, so a project with ledger-keep: 0 is heard too.
+const stop = onLedgerEvent((entry, project) => {
+  if (entry.kind === "healer.failed") notify(`the ${entry.healer} failed: ${entry.error}`);
+  if (entry.kind === "provider.error" && !entry.transient) notify(`the model provider: ${entry.error}`);
+});
+
+// The project's runs, the most recent first, each with its pulses - how each ended, how long, what it cost.
+const runs = runViews(projectDir);
+
+// One pulse, from this session or an earlier one: its rounds, test runs, verdicts, healers, refusals, history.
+const view = pulseView("646d", readLedger(projectDir, { job: "646d" }));
+
+// Earlier sessions' pulses as jobs, to list beside this session's - none this session's registry knows.
+const { jobs, more } = earlierPulses(ledgerProjects(projectDir), new Set(registry.list().map((job) => job.id)));
+```
+
+- **Live.** `onLedgerEvent(listener)` is told every event as turri records it, with the project it is about, until what it returns is called; a listener that throws misses that event and nothing else. It is the pulse's own detail - its stages, test runs, verdicts, refusals - where `onJobChange` is the job as a whole.
+- **Read back.** `readLedger(project, { job, run, kinds, since })` is the project's events, oldest first, the gzipped runs too; `runViews` and `pulseView` gather them into runs and pulses, and `describePulseView` and `describeRuns` say them in lines, as `turri ledger` prints them. `ledgerProjects(dir)` finds the ledgers of a folder and the projects under it. `earlierPulses(projects, known, runs = 3)` gives the last runs before this one as `Job`s - the shape a host already draws for this session's - each marked `earlier: { run, runMode, lines }`, `lines` what the ledger says of it; `more` is how many runs are beyond them. They are read only: never started, halted or waited for. turri's own side panel lists them so, as **earlier sessions**.
+- **What it is for.** Looking up, never deciding: what is built and what is left come from the records and the work loop, as before. Its events and their fields are `LedgerEvent`'s - a kind is added, never changed, and every event carries `v: 1`.
+
 ## Running it
 
 The host entry is compiled JavaScript, so any Node from 22.19 runs it - Electron's own included; nothing strips types. It finds turri's own folders - `genome/`, `stdlib/`, `.pi/` - beside `dist/` in the package, wherever npm installed it.

package/docs/installation.md

@@ -93,3 +93,4 @@ For Gemini, `GEMINI_API_KEY` is what makes pi *offer* the google provider, but w
 | --- | --- |
 | `PLAIN_TEMPLATE_DIRS` | colon-separated template directories, e.g. the standard library |
 | `TURRI_COMMAND_TIMEOUT` | seconds a command may run before it is stopped - an agent's own, its tests (default `120`) |
+| `TURRI_LEDGER` | `off`: write no [ledger](using.md#the-ledger) at all, whatever `ledger-keep:` says - the test suite sets it |

package/docs/regenerating.md

@@ -33,12 +33,12 @@ The harness's scratch - each ignores itself, and is never part of a module's his
 | | |
 | --- | --- |
 | `plain_modules/.turri/` | what turri keeps beside the code - see [sandbox](sandbox.md#what-turri-keeps-beside-the-code) |
-| `plain_modules/.turri/cache/` | the package caches, so a dependency is fetched once |
+| `plain_modules/.turri/cache/` | the package caches, so a dependency is fetched once - held to `cache-keep:` |
 | `plain_modules/.turri/scripts/` | the copies each testing script run happens in, one folder a run |
-| `plain_modules/.turri/logs/` | the whole output of each run or command an agent was shown cut short, by time and what ran - read by agents only through `read_output` |
-| `.turri/jobs/` | each job's log: its diff, its stages, its agents and what they cost, and which walls were up under its agents' commands |
-| `.turri/debug/` | each agent's log: its prompt, every tool call and every answer |
-| `.turri/sessions/` | the agents' saved sessions |
+| `plain_modules/.turri/logs/` | the whole output of each run or command an agent was shown cut short, by time and what ran - read by agents only through `read_output`; removed as the pulse ends, outside [debug mode](config.md#debug-mode) |
+| `.turri/jobs/` | each job's log: its diff, its stages, its agents and what they cost, and which walls were up under its agents' commands - kept in debug mode only |
+| `.turri/debug/` | each agent's log: its prompt, every tool call and every answer - kept in debug mode only |
+| `.turri/sessions/` | the agents' saved sessions - in debug mode, and a gated skill's run's |
 | `.turri/runs/<skill>/` | a gated skill's run: what an interrupted one resumes from, and its gates' evidence |
 | `.turri/deploy/` | the output of what `deploy` started |
 | `dist/<module>/` | what `deploy` puts out: the module's code as its last commit has it, replaced whole each time - see [deploy](deploy.md) |
@@ -411,7 +411,7 @@ The agents that work through a job keep **one session for it**: the coding agent
 
 An agent kept through a job re-reads everything it has done on every call. So between turns, once its conversation - what it has done, past its instructions - passes `compact-at` tokens (100,000 unless [the project config](config.md) says otherwise), the harness compacts it, with instructions for its role: the coding agent and the fixer keep what is done, what still fails and why, the decisions and every review problem's fate; a reviewer keeps every problem it raised and where each stands, and what it has already checked. pi's own compaction, when the context window is nearly full, stays on beneath it.
 
-What each agent of a job did - its turns, its compactions, its tokens and cost - is at the end of the job's log in `.turri/jobs/`, and in `pulses`.
+What each agent of a job did - its turns, its compactions, its tokens and cost - is at the end of the job's log in `.turri/jobs/` (kept in [debug mode](config.md#debug-mode)), and in `pulses`.
 
 ## Working notes
 
@@ -462,7 +462,7 @@ Two records per module, each committed with what it describes in the module's `.
 | `code/.turri.json` | the code record: the spec the code is built from - its whole requires chain's: the definitions and implementation reqs of the modules below, each tagged with its module, their functional specs among the ones it inherits, and its own - without the test reqs and the acceptance tests, which are for conformance only |
 | `tests/.turri.json` | the tests record: the functional specs the conformance tests are written for - of the code record's, with their acceptance tests - the definitions and implementation reqs they were written against, and the test reqs they follow |
 
-Nothing about how a build went: whether tests passed and which files a job touched are in the history. And nothing else is stored: what is left to build is worked out from the records whenever a job ends or the spec changes - the code work from the code record to the spec now (`src/regenerate/drift.ts`), the conformance work from the tests record to what the tests are to be written for. Only the running job is kept; what the panel shows as planned is worked out again. The tests record never goes ahead of the code's: a conformance test exercises functionality, and only what is in the code can be tested.
+Nothing about how a build went: whether tests passed and which files a job touched are in the history, and how each pulse went is in the [ledger](using.md#the-ledger), which nothing reads to decide what to build. And nothing else is stored: what is left to build is worked out from the records whenever a job ends or the spec changes - the code work from the code record to the spec now (`src/regenerate/drift.ts`), the conformance work from the tests record to what the tests are to be written for. Only the running job is kept; what the panel shows as planned is worked out again. The tests record never goes ahead of the code's: a conformance test exercises functionality, and only what is in the code can be tested.
 
 What goes into them:
 

package/docs/sandbox.md

@@ -107,12 +107,12 @@ It lives in `plain_modules/.turri`, which ignores itself in git:
 
 | | |
 | --- | --- |
-| `cache/` | package caches - pip, npm, cargo, Maven, Gradle, Go - so a dependency downloads once per project |
-| `home/<module>` | each module's home folder for its agents' commands, kept between pulses |
-| `tmp/<module>` | each module's `TMPDIR` |
+| `cache/` | package caches - pip, npm, cargo, Maven, Gradle, Go, node-gyp's headers, the browsers Playwright, Puppeteer and Cypress download - so a dependency downloads once per project; held to `cache-keep:` megabytes, the least recently written going first |
+| `home/<module>` | each module's home folder for its agents' commands, kept between pulses; the caches its tools keep there count towards `cache-keep:` |
+| `tmp/<module>` | each module's `TMPDIR`, emptied as each of its pulses ends outside [debug mode](config.md#debug-mode) |
 | `scripts/` | the throwaway copies test runs happen in, emptied after each run |
-| `logs/` | whole outputs cut short for an agent, read through `read_output` |
-| `services/` | what the services agents started printed |
+| `logs/` | whole outputs cut short for an agent, read through `read_output` - removed as the pulse ends, outside debug mode |
+| `services/` | what the services agents started printed - removed as the pulse ends, outside debug mode |
 
 ## What the machine lacks
 

package/docs/using.md

@@ -36,7 +36,8 @@ While a skill runs, a line above the input shows its phases, every one by name -
 | `engine` | show or choose the model the code is regenerated on - see [below](#choosing-a-model) |
 | `pulses` | the pulses - running, planned and finished - or one of them |
 | `halt` | halt a pulse, a module's planned pulses, or what `activate` started |
-| `diagnose` | why a pulse did not land, from its transcript: how it ended, the stages that went wrong, the last failing test run, the last review, the tool calls that failed |
+| `diagnose` | why a pulse did not land, from its transcript: how it ended, the stages that went wrong, the last failing test run, the last review, the tool calls that failed - and what the [ledger](#the-ledger) recorded of it |
+| `ledger` | what turri did, from the [ledger](#the-ledger), this session's and every earlier one's: a pulse as facts, by its id - its rounds, test runs, verdicts, healers, refusals and commits; events of some kinds counted and listed, for a module or since a time - `healer.failed`, or `healer` for the group; or the last runs, a line a pulse |
 | `lineage` | a module's lineage: what each regeneration and conformance run changed in it, and what it was regenerated from |
 | `cultivate` | run a gated skill, its steps and review gates enforced |
 | `release`, `activate` | try what is regenerated: release it to `dist/<module>` and activate it on this machine, installing what it needs - see [deploy](deploy.md) |
@@ -80,7 +81,7 @@ A render takes minutes, so in the TUI every render tool starts the work as a pul
 
   One module is shown at a time, with a tab for each module of the chain on the line under the top line, in the chain's order - the module it is built on to the left: `d365_version_api  [d365_http_client]  d365_utils 12 ›`. A tab regenerating spins, one stuck says `!`; what does not fit is counted at either end. `←` `→` go from one tab to the next. The module shown is the one in focus - the one regenerating now, else the one asked for, else the first - until you pick another tab; it goes back to following once another module is in focus, or the one in focus starts regenerating. Under the module's own text is what it imports, under **imported**, a folded block a file, `▸ from stdlib/backend/python-fastapi · 7 reqs · all built`, closed until opened. The modules it requires are tabs of their own: a chain of many modules is never drawn nested, one in the next. A map longer than the screen has a minimap down its right edge, a cell a slice in the colour of its most pressing mark, the slice shown solid. The map is read from the files - the code record, the `.plain` files, the tests record - so it is right the moment turri opens a project, before anything runs; the work loop's plan adds the pulses on top. It maps the files asked to build this conversation, else `module:` in `config.turri.yaml`, else the `.plain` files of the folder that no other one there imports or requires - the folder's files looked at again only once one of them, or its config, changes. `↑` `↓` move row by row, `enter` or `space` open and close an item or an import block - a functional spec opens to its sub-bullets and its `***acceptance tests***`, nested under it as the spec has them - `←` `→` go to the next module's tab, `o` and `c` open or close everything shown, `pgup` `pgdn` and the wheel scroll, `g`/`G` go to the top and the bottom.
 
-  `p` goes to the **pulses** - and back - onto the pulse that regenerates the item under the cursor, and back onto the first item the pulse under the cursor regenerates. The pulses are every pulse as three sections - running, queued, finished - each opened and closed on its own (running and queued start open). A pulse is one line: its module, kind and number (`hubspot · regenerate pulse 1`, `hubspot · conformance pulse 2`) - so it is named wherever a pulse is named in a line (the job panel, the `pulses` tool, `/halt`, the command line), never by what it regenerates, which is in it, opened - its time (none while it is queued: it has not started) and its cost - a finished one's mark green when it passed, red when it failed or did not pass, amber when it was stopped. Opened, a running one shows what it is doing; a queued one, what it waits for; a finished one, its agents and what each spent, and whether it did not pass. Under it is a row for each file its spec diff changes - the file of the module being rendered first and open, the rest by name and closed - each opening onto that file's lines. A file with nothing added or taken out is not listed. `↑` `↓` move, `enter` or `space` open and close what is under the cursor, `→` `←` open and close (`←` on a closed pulse goes to its section, on a closed file to its pulse), `o` and `c` open or close every pulse of the section - or, on a file, every file of its pulse - `pgup` `pgdn` and the wheel scroll, `g`/`G` go to the top and the bottom. The cursor stays on its row when the pulse under it moves on; a pulse opened closes when it moves to another section. What is open is kept while the panel is closed. What the agents said and did is not shown - it is in each pulse's log (see [Agent logs](#agent-logs)).
+  `p` goes to the **pulses** - and back - onto the pulse that regenerates the item under the cursor, and back onto the first item the pulse under the cursor regenerates. The pulses are every pulse as three sections - running, queued, finished - each opened and closed on its own (running and queued start open) - and a fourth, **earlier sessions**, closed, when the [ledger](#the-ledger) has pulses of sessions before this one: its last three runs', each pulse read only - opened, what the ledger says of it (how it ended, its rounds and test runs, the healers, what turri refused and committed, its last stages and its log) - and a line for how many more runs it has. A pulse is one line: its module, kind and number (`hubspot · regenerate pulse 1`, `hubspot · conformance pulse 2`) - so it is named wherever a pulse is named in a line (the job panel, the `pulses` tool, `/halt`, the command line), never by what it regenerates, which is in it, opened - its time (none while it is queued: it has not started) and its cost - a finished one's mark green when it passed, red when it failed or did not pass, amber when it was stopped. Opened, a running one shows what it is doing; a queued one, what it waits for; a finished one, its agents and what each spent, and whether it did not pass. Under it is a row for each file its spec diff changes - the file of the module being rendered first and open, the rest by name and closed - each opening onto that file's lines. A file with nothing added or taken out is not listed. `↑` `↓` move, `enter` or `space` open and close what is under the cursor, `→` `←` open and close (`←` on a closed pulse goes to its section, on a closed file to its pulse), `o` and `c` open or close every pulse of the section - or, on a file, every file of its pulse - `pgup` `pgdn` and the wheel scroll, `g`/`G` go to the top and the bottom. The cursor stays on its row when the pulse under it moves on; a pulse opened closes when it moves to another section. What is open is kept while the panel is closed. What the agents said and did is not shown - it is in each pulse's log (see [Agent logs](#agent-logs)).
 
   `ctrl+h` again, or `esc`, closes it and goes back to the chat. Beside the chat, one side has the keys and the other is drawn faint: `ctrl+h` switches sides - from the chat to the panel, from the panel to the chat, the panel staying and following the pulses - `esc` gives the chat the keys too, and a click gives them to the side clicked. `ctrl+c` closes the panel; so do `s`, over the whole screen, then `esc`. (pi's regular screen, `--tui-mode regular`, reads no mouse: there it is the keys alone.) While the panel has the keys, every key is the panel's, whatever else happens: a question the chat model asks in the background (`ask_user`) waits in the chat, unanswered - an `enter` in the panel never answers it - and the panel's top line says "the chat is waiting for your answer". Back in the chat, the question is there, with the keys.
 - `turri` runs pi in fullscreen mode, so the conversation stays where you scroll it while the pulses redraw (PgUp/PgDn, the wheel); `--tui-mode regular` goes back to the terminal's own scrollback.
@@ -151,7 +152,9 @@ A provider failure - no credits, bad key, rate limit - is raised with the provid
 
 Each `plain_modules/<module>` is a git repository whose git directory is `.plaingit` rather than `.git`, so it stays plain files to your own repository. A commit is made after every step that changes the module - a render, a functionality regenerated, a conformance run, a regression repair, a spec change. `/lineage [module]` and `lineage` show it.
 
-The last commit is also the last known good state. Every render, functionality regenerated, spec change and conformance run starts by putting the codebase it works in back to it, so if turri was stopped or restarted mid-pulse, whatever that pulse left half-written is undone first - and one that does not pass is undone the same way when it ends, commits and all. Only work that passed is committed. Installed dependencies and caches are not in the history and stay. With git directly:
+The last commit is also the last known good state. Every render, functionality regenerated, spec change and conformance run starts by putting the codebase it works in back to it, so if turri was stopped or restarted mid-pulse, whatever that pulse left half-written is undone first - and one that does not pass is undone the same way when it ends, commits and all. Only work that passed is committed. Installed dependencies and caches are not in the history and stay.
+
+The history is turri's own: the hooks your git config names (`core.hooksPath` - gitleaks, husky) do not run on its commits. When work that passed cannot be committed all the same - a `.plaingit/index.lock` a git stopped mid-commit left, a full disk - the pulse does not land: the next start would undo it while turri took it as built. It is rolled back, and the stop says what git said and how to fix it. Any other step's commit failing leaves only a gap in the history. With git directly:
 
 ```bash
 git --git-dir=plain_modules/<module>/.plaingit --work-tree=plain_modules/<module> log
@@ -159,14 +162,41 @@ git --git-dir=plain_modules/<module>/.plaingit --work-tree=plain_modules/<module
 
 ## Agent logs
 
-When an agent does something you cannot explain, its logs are where to look: the chat shows what its pulse is doing, not what its agents said. Every agent a render starts - the coding agent, the conformance agent, the repair agent, the spec-steps planner - also streams its whole conversation to a file of its own, always.
+When an agent does something you cannot explain, its logs are where to look: the chat shows what its pulse is doing, not what its agents said. Every agent a render starts - the coding agent, the conformance agent, the repair agent, the spec-steps planner - also streams its whole conversation to a file of its own.
 
 The logs are in `.turri/debug/` in the project, beside `plain_modules`, one per agent, named by when it started and what it is: `2026-09-26T13-45-02-123Z-app-3-coding-agent.log`. Each starts with the pulse it runs for, its model and thinking level, its folder, its saved pi session, its tools and its system prompt, and then has, in order and stamped with the time: every prompt it is sent, whole; its thinking and replies as they stream; every tool call with its arguments, numbered
 - `→ #3 bash` - and its whole result under the same number, `← #3 bash done`, since calls made together run at once and finish in any order; a tool call a response was cut off in, marked as never run; each response's stop reason, tokens and cost; the provider's retries and errors; and how each turn ended. Every line is on disk as it happens, so `tail -f` follows an agent live and a run that crashed leaves its log up to that moment. The pulse's own log names each agent's log as it starts.
 
 Beside them, each pulse has a log of its own in `.turri/jobs/` - `<time>-<pulse id>-<kind>.log`: its whole transcript, written as it happens. The harness's stages, the functional spec or the diff it builds, and every one of its agents in turn - each prompt, its thinking and replies, every tool call and its result, whole where the screen clips them - and how the pulse ended. A finished pulse, opened in the side panel, names it. It is the one to read for a pulse as a whole; an agent's own log has its system prompt, tokens and retries besides.
 
-No agent can read the logs: they are outside `plain_modules` - or, for a `--build-dir` outside it, beside that folder rather than in it. Nothing prunes them either - delete the folder when you are done with it. A log that cannot be written is given up on without failing the render.
+They are kept only in [debug mode](config.md#debug-mode) - `debug: true` in `config.turri.yaml`, or `TURRI_DEBUG=1`, or `turri --debug` for one run. Otherwise a pulse's logs are written while it runs - the diagnosis of a pulse that fails twice reads them, and quotes what it needs, never sending you to a file that is about to go - and removed as it ends, and an agent outside a pulse writes none; the [ledger](#the-ledger) still says what each pulse did, how it ended and what it cost. To read why an agent did something, turn debug mode on and run it again.
+
+The coding and conformance agents cannot read the logs: they are outside `plain_modules` - or, for a `--build-dir` outside it, beside that folder rather than in it. The diagnosis of a failed pulse reads them. In debug mode nothing prunes them - delete the folder when you are done with it. A log that cannot be written is given up on without failing the render.
+
+## The ledger
+
+The logs keep everything a pulse's agents said, for reading one pulse closely. The ledger keeps what turri did, as facts, across pulses, sessions and runs - to answer *why did last night's run fail*, *how often does the debugger fail*, *what did this module cost*, long after the session that ran it is gone (`src/regenerate/ledger.ts`).
+
+It is in `.turri/ledger/` in the project, a JSON line an event, one file a run - a conversation, a headless run, a host's session: `<time>-<run>-p<pid>.jsonl`. Each line has the time with its date, its order in the run, the run, and - where they apply - the pulse, the module and the agent. What it records:
+
+| | |
+| --- | --- |
+| runs | `run.started` (how it was started, turri's version and commit, the machine), `run.ended` |
+| pulses | `job.queued`, `job.started`, every `job.stage`, `job.retried`, `job.finished` - its status, whether it landed, how long it ran, what it cost, how it ended |
+| the work loop | `loop.halted`, `loop.stopped` (a pulse the spec moved on from), `planner.failed`, `planner.fellBack` |
+| the model | `model.call` (time and tokens), `model.turn`, `model.compaction`, `provider.retry`, `provider.stall`, `provider.error`, `turn.stopped` (a turn turri ended itself, and why) |
+| tools and tests | `tool.call` (the tool, how long, whether it failed - never its arguments or result), `script.run` (the testing script, its exit, how long, whether the time limit stopped it, the failure's fingerprint, and `mutated` for a `can_it_fail` run on code broken on purpose) |
+| the gates | `gate.round`, `review.verdict`, `arbiter.ruling`, `judge.verdict` |
+| what turri refused | `guard.refused` (a repeated call, a call past its budget, a tool the turn does not have), `command.refused`, `audit.putBack` |
+| the healers | `healer.started`, `healer.ended` with what it found, `healer.failed` and why - the debugger, the diagnosis of a failed pulse |
+| the history | `history.committed`, `history.failed`, `history.reset`, `history.rolledBack` |
+| the environment | `environment.error` |
+
+Never in it: prompts, replies, thinking, tool arguments and results, file contents. What an event does carry - a stage, an error's first line - is masked as the logs are.
+
+`turri ledger` prints the last runs, a line a pulse; `turri ledger <pulse>` one pulse - its rounds, its test runs and how many failed the same way, the verdicts, the healers, what turri refused, what its history recorded, its log; `--json` the events themselves, for `jq`. In the chat, `ledger` is the way in - a pulse of this session or an earlier one, the events of some kinds counted (how often the debugger failed this week: `kinds: [healer.failed], since: 7d`), the last runs - and `pulses` lists the last three earlier runs under this session's pulses, `pulses` and `diagnose` tell one of them by its id, and `diagnose` adds the ledger's facts to a pulse of this session; the side panel's pulses list has them as **earlier sessions** (see [the side panel](#in-a-conversation)).
+
+It is for looking up, never for deciding: what to build comes from the records alone (see [what the code is built from](regenerating.md#what-the-code-is-built-from)), so deleting `.turri/ledger/` loses nothing but what can be looked up. When a run first writes to the project, the files of runs that have ended are gzipped and the oldest pruned past `ledger-keep:` megabytes - 100 unset, `0` for none at all; a run still going is never touched. `.turri` ignores itself, so the ledger is never committed, and nothing of it is sent anywhere. A ledger that cannot be written is said once and given up on, never failing the work.
 
 ## From the command line
 
@@ -183,6 +213,7 @@ turri regenerate <file.plain> --from-scratch-chain   # the same for every module
 turri spec-diff <file.plain> <diff>    # apply a spec diff, and regenerate it
 turri conform <file.plain> 1           # black-box tests for functionality 1
 turri lineage <module>                 # what each regeneration changed in a module, and when
+turri ledger [pulse]                   # what turri did here: the last runs and their pulses, or one pulse
 turri cultivate brood                  # run a skill directly - by name, the project's too, or by its folder
 turri release <file.plain>             # release what is regenerated to dist/<module>, and activate it here
 ```