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

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.d.ts

@@ -1,4 +1,4 @@
-import type { Job } from "./regenerate/jobs.ts";
+import { type Job } from "./regenerate/jobs.ts";
 /**
  * A headless run's report: one JSON file, `turri regenerate --report <file>`, saying what the run did - how it ended,
  * what it spent, which pulses landed, how many functional specs are completed - for a benchmark or CI to read rather

package/dist/run-report.js

@@ -1,7 +1,9 @@
 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";
 /**
  * A headless run's report: one JSON file, `turri regenerate --report <file>`, saying what the run did - how it ended,
  * what it spent, which pulses landed, how many functional specs are completed - for a benchmark or CI to read rather
@@ -177,7 +179,12 @@ export function startRunReport(options) {
             };
         });
         const ran = list.filter((pulse) => pulse.status !== "queued");
+        const first = firstRegeneration(jobs, startedAt);
+        const seconds = (ms) => (ms !== undefined ? Math.round(ms / 100) / 10 : null);
         return {
+            // The time to first regeneration - the first code pulse started - and to the first one landed, from the run's start.
+            first_started_seconds: seconds(first.started),
+            first_landed_seconds: seconds(first.landed),
             counts: {
                 total: ran.length,
                 landed: ran.filter((pulse) => pulse.landed).length,
@@ -284,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/dist/self-invocation.d.ts

@@ -20,6 +20,6 @@ export declare function selfInvocation(command: string): string | undefined;
  */
 export declare function askedForCommandLine(message: string): boolean;
 /** What the agent is told when the call is refused. */
-export declare function refusal(what: string): string;
+export declare function refusal(what: string, surface?: string): string;
 /** The instruction that goes into the conversation's system prompt. */
 export declare const TOOLS_NOT_CLI: string;

package/dist/self-invocation.js

@@ -88,12 +88,13 @@ export function askedForCommandLine(message) {
         /(^|\s)pi\s+-p\b/.test(text));
 }
 /** What the agent is told when the call is refused. */
-export function refusal(what) {
+export function refusal(what, surface) {
     const instead = what === "pi"
         ? "Do not start another agent: do the work here, with this conversation's tools."
         : `Use ${TOOL_FOR[what] ?? "the matching turri tool"} instead.`;
     return (`Not run: that starts turri${what === "pi" ? "'s agent" : ` ${what}`} again from the shell - a separate, headless ` +
-        "run outside this conversation, its jobs, the panel and /halt. " +
+        // In a host there is no panel: the person watches the pulses where its surface says.
+        (surface !== undefined ? "run outside this conversation and its pulses, where the person can neither watch it nor halt it. " : "run outside this conversation, its jobs, the panel and /halt. ") +
         `${instead} Run turri from the command line only when the user asks for that.`);
 }
 /** The instruction that goes into the conversation's system prompt. */

package/dist/skill-progress.d.ts

@@ -6,7 +6,7 @@
  *   brood       ✓ intent ━━━━ ⠋ stack ──── ○ testing ──── ○ product       phase 2 of 4
  *                 stack - the language, frameworks, storage and architecture
  *
- * The second line says what the phase it is in does: a phase's name alone - `groundwork` - says little to someone
+ * The second line says what the phase it is in does: a phase's name alone - `skeleton` - says little to someone
  * who has not read the skill.
  *
  * A skill of one phase, or none, has nothing to be partway through: its line is the spinner and its name alone.

package/dist/skill.d.ts

@@ -85,6 +85,11 @@ export interface Skill {
      * last answer is written with `write_spec_diff`, and changes the agent decides itself need no answer before them.
      */
     diffPerAnswer: string[];
+    /**
+     * Started only by the person, with its slash command - `/brood` - never by the model on its own
+     * (`metadata.command-only: true`): cultivate runs it only when the person has just typed its command.
+     */
+    commandOnly: boolean;
 }
 export declare function loadSkill(skillDir: string): Skill;
 export declare function readRubric(skill: Skill, review: {

package/dist/skill.js

@@ -131,6 +131,7 @@ export function loadSkill(skillDir) {
         paced: data.metadata?.paced !== false,
         questioning: capped,
         diffPerAnswer,
+        commandOnly: data.metadata?.["command-only"] === true,
     };
 }
 export function readRubric(skill, review) {

package/dist/skills.d.ts

@@ -28,3 +28,17 @@ export declare function discoverSkills(packageRoot: string, projectDir: string |
 export declare function catalogueLine(skill: FoundSkill): string;
 /** What is said under the list about the skills it leaves out. */
 export declare function leftOutNote(catalogue: SkillCatalogue): string;
+/**
+ * Which skills cultivate may start now. A skill marked command-only (`/brood`) waits for the person to type its command:
+ * the command lets it start once, and the run starting uses that up - the model cannot start it again later on its own.
+ */
+export declare function createCommandGate(): {
+    /** The person typed the skill's command. */
+    typed(name: string): void;
+    /** Whether cultivate may start it now. */
+    mayStart(skill: Pick<FoundSkill, "name" | "commandOnly">): boolean;
+    /** Its run started: the command is used up. */
+    started(name: string): void;
+};
+/** What cultivate says of a command-only skill the person did not start. */
+export declare function startedByCommandOnly(name: string): string;

package/dist/skills.js

@@ -61,7 +61,9 @@ export function discoverSkills(packageRoot, projectDir) {
 /** A skill's line in cultivate's list: a project's says so, and where it is. */
 export function catalogueLine(skill) {
     const whose = skill.origin === "turri" ? "" : ` (this project's, ${skill.origin.project})`;
-    return `- ${skill.name}${whose}: ${skill.description}`;
+    // One the person starts themselves: the model points them to its command rather than running it.
+    const byCommand = skill.commandOnly ? ` Started only by the person, with /${skill.name}: never run it unasked - when it fits, tell them to type /${skill.name}.` : "";
+    return `- ${skill.name}${whose}: ${skill.description}${byCommand}`;
 }
 /** What is said under the list about the skills it leaves out. */
 export function leftOutNote(catalogue) {
@@ -72,3 +74,19 @@ export function leftOutNote(catalogue) {
         .map((line) => `\n\n${line}`)
         .join("");
 }
+/**
+ * Which skills cultivate may start now. A skill marked command-only (`/brood`) waits for the person to type its command:
+ * the command lets it start once, and the run starting uses that up - the model cannot start it again later on its own.
+ */
+export function createCommandGate() {
+    const typed = new Set();
+    return {
+        typed: (name) => void typed.add(name),
+        mayStart: (skill) => !skill.commandOnly || typed.has(skill.name),
+        started: (name) => void typed.delete(name),
+    };
+}
+/** What cultivate says of a command-only skill the person did not start. */
+export function startedByCommandOnly(name) {
+    return `Not started: ${name} is started only by the person, with /${name}. If it fits what they want, tell them to type /${name} - with what they want after it, if they like.`;
+}

package/dist/surface.d.ts

@@ -0,0 +1,5 @@
+import type { JobRegistry } from "./regenerate/jobs.ts";
+/** The host's surface for the conversation these jobs are: blank or undefined is the terminal. */
+export declare function setSurface(jobs: JobRegistry, surface: string | undefined): void;
+/** The host's surface, in its own words - undefined in the terminal. */
+export declare function surfaceOf(jobs: JobRegistry | undefined): string | undefined;

package/dist/surface.js

@@ -0,0 +1,18 @@
+/**
+ * Where the person sees turri's work: the terminal - regen, its keys, /pulses - unless a host that runs the conversation
+ * itself describes its own (TurriHost.surface). Kept with the conversation's job registry, so what is told the model
+ * deep in a tool - a pulse not found - says the host's words and not the terminal's.
+ */
+const surfaces = new WeakMap();
+/** The host's surface for the conversation these jobs are: blank or undefined is the terminal. */
+export function setSurface(jobs, surface) {
+    const text = surface?.trim() ?? "";
+    if (text !== "")
+        surfaces.set(jobs, text);
+    else
+        surfaces.delete(jobs);
+}
+/** The host's surface, in its own words - undefined in the terminal. */
+export function surfaceOf(jobs) {
+    return jobs !== undefined ? surfaces.get(jobs) : undefined;
+}

package/docs/authoring-plain.md

@@ -122,12 +122,12 @@ The ones that shape a spec most:
 
 ## Writing specs with turri
 
-In a conversation (`turri`), say what you want and the matching skill runs. Two build a project from scratch, and write each spec change as a git diff that is built in the background the moment it is written. `brood` interviews you one question at a time and writes the specs as you answer; `spawn`, its quick twin, asks only what you want to build and which stack - or leaves the stack to it - and writes the rest on its own:
+In a conversation (`turri`), say what you want and the matching skill runs - but the three that start a project or a feature you start yourself, by their commands: `/brood`, `/spawn` or `/bud`, with what you want after it. Two build a project from scratch, and write each spec change as a git diff that is built in the background the moment it is written. `brood` interviews you one question at a time and writes the specs as you answer; `spawn`, its quick twin, gets something running as soon as it can - the smallest thing that runs first, then the product a slice at a time - asking only what your message leaves open:
 
 | skill | phases | how a spec change is written |
 | --- | --- | --- |
 | `brood` | intent → stack → testing → product, feature by feature | first, how many questions the stack and product phases may ask - light 3, medium 5, thorough 10 or best judgement, broader with fewer, covering the same ground - and what they leave open turri decides itself, each decision a spec change of its own; every product answer is still a spec change, built before the next question; in testing, whether there are conformance tests, their `***test reqs***` and script - written as files, building nothing; then one spec change per answer, across whatever sections it needs, as a git diff with `write_spec_diff`, rendered as a render spec diff job and conformance tested as it is built |
-| `spawn` | intent → groundwork → product | only the intent and the stack are asked - the stack one question, `You choose` first, skipped when the user named one; the stack and the unit tests are written as files, with conformance tests off unless the user asks for them; then one spec change per feature, in build order, as a git diff with `write_spec_diff`, one after another with no answer between them. Changes after it are asked for in the conversation, as spec diffs, and what is left to build is worked out again from the spec |
+| `spawn` | start → skeleton → regenerate | built for the time to first regeneration: what to build is asked only when the message does not say, and the stack only when the user named one this machine cannot build - otherwise turri chooses one; the stack and the unit tests are written as files, with conformance tests off unless the user asks for them; then a spec change for the smallest thing that runs starts the first build - a module's first pulse of one functional spec is not reviewed - and the main slice of what the user described and at most one more follow - none when they described no feature, and never one of turri's own - each a functional spec on its happy path, as git diffs with `write_spec_diff`, one after another with no answer between them. The rest - the next slices, then validation and edge cases as changes to those specs - is asked for in the conversation once the user has tried what landed: `go on` for the next slice it proposed |
 
 `mature` starts from a spec you already have, rough or hand-written, and runs on its own until it is fully rendered - every functionality built from the spec as it stands, its tests passing. It renders what is not built and watches the agents building it; when one struggles on something the spec leaves open or unclear - sent back again and again, the judge going back and forth, a spec conflict - it writes what the spec should say as a spec diff, stops that build, and renders it again. What the builds had to decide themselves - their assumptions, pitfalls, a failed build's diagnosis - goes into the spec the same way, when a user, a caller or a test can see it. It never asks: it takes the reading that fits the rest of the spec, and marks each such decision in its report. It leaves code, environment and turri problems to the builds, and stops when a functionality keeps struggling after the spec was clarified, when two cycles change nothing, or after twenty.
 

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).
 
@@ -82,7 +83,7 @@ models:                              # each agent role's model, thinking and tur
 | `judge-model` | the judge and the test review of a conformance run | `coding-model` |
 | `conformance-tests` | `all` (or `true`): conformance tests for every functional spec of every module with test reqs, written once each module's code is built, before anything is built on it. `chosen`: for the functional specs chosen - every one with acceptance tests, and those the chooser picks as each code pulse ends, from what that pulse regenerated. `module`: the same, but the chooser is asked once, when the whole module is regenerated, and plans the conformance pulses too. Under both, the choice is made inside the pulse, before anything is built on the module, and the pulse's report says what was chosen and why; those the person asks for with `conform` are written too; once chosen, a functional spec keeps them, and they are rewritten when it changes - see [who chooses, and when](regenerating.md#conformance-tests-in-the-work-loop). `false`: none written, and none of the existing ones run - until the conversation asks with `conform` | `false` |
 | `conformance-budget` | under `conformance-tests: chosen` or `module`: how many of a module's functional specs may be chosen for conformance tests, beside those with acceptance tests - a count (`2`) or a share of its functional specs (`30%`, rounded up, at least one). Every choice for the module counts, whenever it was made; the chooser is told what is left, and can choose no more. Your own `conform` is not limited. A stack's `config.turri.<stack>.yaml` can set its own | no limit |
-| `review` | `true` or `false`: whether the code and its unit tests - and the conformance tests - are reviewed once they pass: two reviews at most, the second weighed by the arbiter; off, a job lands once its tests pass - see [regenerating the code](regenerating.md#the-code-and-its-unit-tests-are-reviewed) | `false` |
+| `review` | `true` or `false`: whether the code and its unit tests - and the conformance tests - are reviewed once they pass: two reviews at most, the second weighed by the arbiter; off, a job lands once its tests pass. A module's first pulse of one functional spec - the project set up and the smallest thing that runs - lands on its unit tests with no review - see [regenerating the code](regenerating.md#the-code-and-its-unit-tests-are-reviewed) | `false` |
 | `mutation-testing` | `true` or `false`: whether the coding agent and the reviewer have `can_it_fail` - one change put in the code for one run of the unit testing script, to see that a test catches it; on a copy of the code, or in place and put back after the run (see [regenerating the code](regenerating.md#checking-its-own-work)). `turri regenerate --mutation-testing false` for one run | `true` |
 | `rules-off` | a list of rule names - `integrations`, `concise-specs`, the files of `genome/rules/` without `.md` - left out of the conversation's prompt and every spec-writing agent's: a rule this project's own skills or AGENTS.md replace, such as one that says to probe a live API before any spec is written. The project's alone | none |
 | `allow-to-stop-jobs` | `true` or `false`: whether turri stops a running job the spec has moved on from - a functional spec it regenerates changed, or a file one links was edited - rolls it back and regenerates the spec as it now is. `false`: the job runs to its end and lands, and what changed since is regenerated on top of it by the next job - see [regenerating the code](regenerating.md). Your own `halt` stops a job either way | `true` |
@@ -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:
 
@@ -134,13 +135,15 @@ A module that `requires` others is built in its own codebase on top of theirs: t
     "by_pulse_kind": { "code": { }, "conformance": { } }
   },
   "pulses": {
+    "first_started_seconds": 41.2,   // the time to first regeneration: the first code pulse started - null before
+    "first_landed_seconds": 233.9,   // the first code pulse landed: something to try - null before
     "counts": { "total": 7, "landed": 5, "failed": 1, "stopped": 0, "rolled_back": 2, "running": 0, "not_started": 0 },
     "list": [{
       "id": "2a058729", "module": "app", "number": 1, "kind": "code", "title": "…",
       "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": {
@@ -162,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
 }
 ```
 
@@ -170,6 +173,8 @@ A module that `requires` others is built in its own codebase on top of theirs: t
 
 **Pulses.** `landed`: its work is committed. `rolled_back`: it ended without landing - failed, stopped, or did not pass - and everything it wrote was undone. A pulse that failed is tried once more before it counts as failed; both tries are the one pulse.
 
+**Time to first regeneration.** `pulses.first_started_seconds` is how long after the run started its first code pulse started - planning the work, and any wait for a free slot, before it - and `first_landed_seconds` how long until the first one landed, when there is first something to try. Both are `null` until it happens. In the chat, `spawn` and the other skills that write spec diffs say the same in their result, counted from when the skill began.
+
 **Spec gaps.** A behaviour the spec leaves open that an agent met and decided on its own - reported with `report_spec_gap` (see [regenerating](regenerating.md)). In the chat they are put to you as the pulse ends; a headless run has no one to ask, so they are listed here, in the order the pulses started, and printed under the pulse that met them. `assumption` is what the agent decided meanwhile, also in the codebase's notes' assumptions while its pulse is `landed`; a pulse rolled back takes it out of the notes, but the question still stands. Settle the ones you care about in the spec and run again.
 
 **Turn incidents.** Each time the model provider failed for a moment and pi or turri waited it out before trying the request again, each time the provider sent nothing back on a request for two minutes, and each turn turri stopped itself - an agent going round in a circle, its calls failing again and again, its time up - after which the run carried on. The provider failing or stalling is printed as it happens, in orange, under the pulse; a stop is the work's normal course and is only listed. They are counted in the usage as `provider_retries`, `provider_stalls` and `turns_stopped`. Many of any point at the model, not the spec: a provider at its limits, or a model too small for the role it was given.

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.
@@ -35,6 +37,8 @@ const loader = new pi.DefaultResourceLoader({
       onJobChange: (job) => {},    // a job started, moved on, did something, or ended
       onPlanChange: () => {},      // what is planned changed with no job
       dialogs: { select, input },  // ask_user's questions, put in the host's own dialogs
+      surface: SURFACE,            // the host's UI, in its own words, told to the model in place of the terminal's
+      systemPrompt: (prompt) => prompt, // the last word on the whole system prompt, each turn
     }),
   ],
 });
@@ -45,8 +49,50 @@ await session.bindExtensions({ uiContext, mode: "tui" });
 
 - **The jobs.** The pulses the conversation starts - its tools, `/regenerate`, a spec change - run in its own job registry and work loop, the project's one. The host is handed both as they are made, and told of each job as it changes, so it shows the very jobs the conversation runs. Its buttons are best the conversation's commands - `session.prompt("/regenerate app.plain")` - so there is never a second loop on the same project.
 - **The questions.** `dialogs` is `ask_user`'s two dialogs: `select(title, options, context, at)` and `input(title, context)`, each resolving with the answer, or undefined when the person dismissed it. Given, the conversation's questions and a skill's interview are put in them; without it, in the terminal's own dialog.
+- **The surface.** What turri tells the model of where the person watches the work is the terminal's by default: regen, the side panel on `ctrl+h`, `/pulses`. In a host none of that is there, and the model would send the person to keys and panels that do not exist. `surface` is the host's own description of its UI - the views it has in place of the terminal's, what its marks and buttons mean, where questions appear - in its own words. Given, turri leaves every terminal instruction out of what the model is told and puts the surface in turri's identity, as a `<surface>` block, where the identity speaks of regen. It reaches the side questions and the tools' own words too: a pulse not found says the `pulses` tool lists them, not `/pulses`. Text only the person sees in the terminal - the job panel, the side panel - is the terminal's and stays as it is. Without `surface`, the prompt is the terminal's, byte for byte.
+- **The system prompt.** `systemPrompt(prompt)` gets the whole system prompt for the turn - pi's, turri's identity and blocks, the rules - after turri's own `before_agent_start` work, and returns what is sent. It is for what `surface` does not cover; to describe the UI, use `surface`, rather than words appended after turri's that contradict them.
 - **The mode.** `mode: "tui"` runs the work in the background and keeps the conversation free, as the terminal does; `rpc`, `json` and `print` wait for each job. The extension's other UI calls - its notices, its working line, a confirm - come to the host's `uiContext`, as pi's [SDK](https://github.com/earendil-works/pi) describes it.
 
+A surface for a desktop app might read:
+
+```js
+const SURFACE = `The person uses turri's desktop app, not a terminal: there are no keys to press. Slash commands are typed in
+the chat, and the toolbar's buttons send them too.
+- The Specs view shows each .plain file, every functional spec marked: a green dot is built, a pulsing ring regenerating,
+  a hollow ring planned, grey waiting.
+- The Pulses view lists every pulse - running, planned and finished. A row opens what its agents did and its log; its
+  Halt button stops it.
+- Your questions appear as cards above the message box: the person picks an option or types an answer there.
+- 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) |
@@ -123,7 +123,7 @@ The reviewer has `can_it_fail` too, three runs a review session: a test it doubt
 
 ### The code and its unit tests are reviewed
 
-Passing unit tests prove only what they check, and a coding agent is quick to write tests that check next to nothing - that a function exists, that a result is not empty, that a status is 200 - or code that no test reaches. So, with `review: true` in the [config](config.md), once the unit testing script passes a reviewer on the judge model reads what the work wrote, beside the spec, and changes nothing. It reviews both halves, with the unit testing script word for word in its prompt: a test the script never reaches is not run, and checks nothing. The review is off by default - `review: false`, or the key left out - and so is the conformance tests' review: the work goes on once its tests pass.
+Passing unit tests prove only what they check, and a coding agent is quick to write tests that check next to nothing - that a function exists, that a result is not empty, that a status is 200 - or code that no test reaches. So, with `review: true` in the [config](config.md), once the unit testing script passes a reviewer on the judge model reads what the work wrote, beside the spec, and changes nothing. It reviews both halves, with the unit testing script word for word in its prompt: a test the script never reaches is not run, and checks nothing. The review is off by default - `review: false`, or the key left out - and so is the conformance tests' review: the work goes on once its tests pass. Even on, a module's first pulse is not reviewed when it builds one functional spec - the project set up and the smallest thing that runs, as `spawn` starts one: a review of a scaffold is time spent before anything can be tried.
 
 - **The code.** Every behaviour, edge case, validation rule and error the spec states for this work is implemented as the spec says it, with nothing left as a stub, a placeholder or a hard-coded answer. The code keeps to the implementation reqs and does not break what was already built. A behaviour with no code for it is raised as not implemented. Such a problem is of kind `wrong`.
 - **The unit tests.** Every behaviour, edge case and error the spec states for this work has a test asserting the exact outcome the spec says, that fails when it breaks; that no test only checks something exists, asserts nothing, is skipped or swallows a failure; that the unit under test is never mocked - only what is outside it; and that the tests are deterministic. A test that is not there is `missing`, a weak one is `bad`.
@@ -281,11 +281,11 @@ It is told, too, what to do with each functional spec the job touches, by its ca
 | fresh | the module requires none and nothing is built | set up the project and its unit tests where the unit testing script runs them, then build | set up `tests/` so the conformance testing script, which brings the tests together with `code/`, runs them, then write |
 | add | a functional spec is new | build it and write its unit tests | write its tests |
 | patch | its text changed, or a concept it uses did | change the existing code and tests to match - never build it again from scratch | rewrite its existing tests to match |
-| again | `regenerate` named it: it is built, and marked in the code record to be regenerated again | replace its implementation - rewrite it or start it over, doing what the spec says now; no second implementation beside the old, nothing of it left unused; its unit tests may be rewritten | none: its tests stay as they are |
+| again | `regenerate` named it: it is built, and marked in the code record to be regenerated again | replace its implementation - rewrite it or start it over, doing what the spec says now; no second implementation beside the old, nothing of it left unused; its unit tests may be rewritten | its tests were written against the code it replaced: run against the new code, what they check that the spec says stays checked, and what they check that the spec leaves open - a path, a field, a message the old code chose - is rewritten to what the new code does, or taken out |
 | delete | a functional spec is gone | take out its code and the tests only it had | take out its tests |
 | mechanical | no functional spec is touched - only reqs, or definitions none uses | adapt the code; write no new test; an existing one may change only mechanically - an import, a fixture, its setup - never what it asserts | the same, for test reqs, definitions or implementation reqs alone |
 
-**Regenerating again.** `regenerate` with functionalities named regenerates them again though their spec did not change - made better, on another model, after many patches. Each is marked in the code record of every codebase it is built in (`regenerate_again`, committed), and nothing else changes: the record now differs from the spec at that item, so the work loop plans it as it plans any change. A functional spec of a module below is regenerated again where its code lives - the codebase at the tip of each chain built on it, never the module's own codebase left behind - marked among that codebase's required functional specs. The planner groups the ones regenerated again as it groups new ones - up to three a job, only those next to each other in one module together - and the job is given the definitions and implementation reqs as every job is; `<spec change>` lists each under "To regenerate again", with its text as it is now. The job that regenerates it records it as the spec has it, without the mark. Its conformance tests compare its text, which did not change: they stay as they are, and are not rewritten.
+**Regenerating again.** `regenerate` with functionalities named regenerates them again though their spec did not change - made better, on another model, after many patches. Each is marked in the code record of every codebase it is built in (`regenerate_again`, committed), and nothing else changes: the record now differs from the spec at that item, so the work loop plans it as it plans any change. A functional spec of a module below is regenerated again where its code lives - the codebase at the tip of each chain built on it, never the module's own codebase left behind - marked among that codebase's required functional specs. The planner groups the ones regenerated again as it groups new ones - up to three a job, only those next to each other in one module together - and the job is given the definitions and implementation reqs as every job is; `<spec change>` lists each under "To regenerate again", with its text as it is now. The job that regenerates it records it as the spec has it, without the mark. Its conformance tests are marked with it, in the tests record of the codebase whose own functional spec it is: they were written against the code being replaced, and may hold the new code to what only the old code chose - `/healthcheck` where the spec says only that there is a health check, and the new code answers `/health`. While the code regenerates they stay as they are; once it lands, the mark is conformance work like any change, and a conformance job writes them again, in the again case above, and runs the whole suite. Until it lands, regen shows its tests as written for an earlier build, and they are not counted as conformance tested.
 
 A functional spec is patched when a concept it uses changed as well as when its own text did: the harness follows each functional spec's concepts through the definitions. Fresh is only where nothing exists: a module that requires another starts from what it inherits, and its first job adds or patches.
 
@@ -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,14 +462,14 @@ 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:
 
 - **A code job landed:** the code record becomes the spec the job ends on.
 - **A conformance job landed:** the tests record becomes what its tests are written for.
 - **A module started from another's code:** that code's record, as a lower module's - see [where things go](#where-things-go) - and an empty tests record: the tests it inherits are the module below's.
-- **A functional spec named to `regenerate`:** it is marked to be regenerated again in the code record, so the next job regenerates it again; that job's record drops the mark.
+- **A functional spec named to `regenerate`:** it is marked to be regenerated again in the code record, so the next job regenerates it again; that job's record drops the mark. Its conformance tests, when it has them, are marked in the tests record too, and the conformance job that writes them again for the new code drops that mark.
 
 A unit of work - a code job, a conformance job - lands whole or is undone whole. It starts from the module's last commit, putting back whatever an interrupted run left; a module with no commit yet is given one first. When it does not pass, the module goes back to that commit: its changes, the files it added and any commit it made on the way are gone, with the record they came with. Installed dependencies and caches stay. So the code, its tests and the records of what they were built from never disagree.
 

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/skills-and-gates.md

@@ -37,6 +37,8 @@ metadata:
 
 A skill declares its steps with a `## Steps` section whose `###` headings are the steps; without it the whole skill is one step, which is what most skills are. Steps are never inferred from `###` headings elsewhere in the body - prose skills are full of those. Each gate becomes a conditional edge after its step; a single-step skill is gated by naming the skill itself. None of the skills turri ships declares a gate today - `brood`'s phases end on the person's confirmation alone - but a project's own skill can.
 
+`command-only: true` under `metadata:` keeps a skill from the model: it is started only by the person, with its slash command - `/brood`, `/spawn` and `/bud` are. turri registers the command for every such skill, the project's own too. Typed, the command puts what was typed in the chat as the person's message, and lets `cultivate` start the skill once; the run starting uses that up, so the model cannot start it again later on its own. Without the command, `cultivate` refuses it and the model is told to name the command to the person instead - the skill's line in `cultivate`'s list says so too.
+
 `paced: false` under `metadata:` lets a skill write spec changes one after another on its own: `write_spec_diff` otherwise refuses a new change until the user has answered a question since the last one - one answer, one change, as an interview writes them. `spawn` is unpaced: the tool tells it so, and after each change to write the next at once, not to carry on with an interview it does not have.
 
 `questioning:` under `metadata:` names the steps the questioning level caps (`src/questioning.ts`) - `brood`'s `[stack, product]`, `bud`'s `[product]`. When there are any and someone to ask, the harness itself asks the first question of the first step: how many questions those steps may ask - light (3), medium (5), thorough (10) or best judgement - and tells the agent the answer beside each step's instructions, with how broad each question is to be: broad at light, a whole area at once, narrow at thorough, an edge case at a time. Every level covers the same ground, in less or more depth. In a capped step `ask_user` refuses a question past the cap; the step's closing confirmation, asked with `confirms_phase: true`, is never counted. `end_questions` ends the step's questions sooner - best judgement's only end. What the questions leave open, the agent decides itself and says what it chose. The level, and how many questions each step has asked, are kept in the run's `run.json`, so a resumed run keeps them. A step it does not name, or a run with nobody to ask, is not capped.
@@ -45,7 +47,7 @@ A skill declares its steps with a `## Steps` section whose `###` headings are th
 
 A step ends when its agent's turn does. A turn that ends on a question in the reply would end the step there, half done, on a question no one reads - the person sees only what `ask_user` asks. So such a step is sent back, twice at most: to ask with `ask_user` if the question is truly the person's, or, in an unpaced skill, to decide it itself - then to carry on until the step is done.
 
-`phases:` under `metadata:` says what each step does, in a short line a step by its name - for the person, not the agent: while the skill runs, the line above the input shows its phases, and under them the one it is in with its line (`groundwork - the language, frameworks, storage and architecture`). A phase's name alone says little to someone who has not read the skill. Every skill with more than one step describes each; a line for a step the skill does not have is an error, as a gate after one is.
+`phases:` under `metadata:` says what each step does, in a short line a step by its name - for the person, not the agent: while the skill runs, the line above the input shows its phases, and under them the one it is in with its line (`skeleton - sets up the project and writes the smallest spec that runs, so the first build can start`). A phase's name alone says little to someone who has not read the skill. Every skill with more than one step describes each; a line for a step the skill does not have is an error, as a gate after one is.
 
 A skill gets the tools its `allowed-tools` names, and nothing else: one that names none has none. So every skill here names its own - the file tools (`read`, `write`, `edit`, `bash`, `ls`, `grep`, `find`) for the ones that write specs, resources or scripts, only the reading ones for those that analyse and report, and turri's own (`write_spec_diff` and the ones below) where a skill uses them.