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

package/README.md

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

package/dist/btw.d.ts

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

package/dist/btw.js

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

package/dist/cli.js

@@ -81,6 +81,7 @@ const COMMANDS = {
     "spec-diff": { module: "./spec-diff-cli.ts", blurb: "apply a change to the specs, given as a git diff, and regenerate it" },
     validate: { module: "./validate-cli.ts", blurb: "validate a ***plain spec, regenerating nothing" },
     lineage: { module: "./lineage-cli.ts", blurb: "a module's lineage: what was regenerated into it, and when" },
+    ledger: { module: "./ledger-cli.ts", blurb: "what turri did here: the last runs and their pulses, or one pulse, from the ledger" },
     release: { module: "./release-cli.ts", blurb: "release what is regenerated to dist/<module> and activate it on this machine" },
     cultivate: { module: "./cultivate-cli.ts", blurb: "run a gated skill" },
 };
@@ -96,6 +97,7 @@ const USAGE = [
     "",
     `  ${"options".padEnd(12)} --harness-model <m>  the model you chat with   --coding-model <m>  the model renders run on`,
     `  ${"".padEnd(12)} --stack <name>  build with config.turri.<name>.yaml over config.turri.yaml - here and in every command`,
+    `  ${"".padEnd(12)} --debug  keep what turri writes for debugging it - agents' logs and sessions - as debug: true does`,
     `  ${"".padEnd(12)} --use-theme <t>  another theme than turri-dark - and every option of pi's own`,
     "",
     ...Object.entries(COMMANDS).map(([name, { blurb }]) => `  ${name.padEnd(12)} ${blurb}`),
@@ -109,7 +111,7 @@ const USAGE = [
 ].join("\n");
 dropNoise();
 // --stack <name>, for any command and for the conversation: the stack everything is built with (stacks.ts), taken out
-// before the rest is read - a command never sees it.
+// before the rest is read - a command never sees it. --debug too: TURRI_DEBUG for this run, and the pi it starts.
 const argv = await withoutStack(process.argv.slice(2));
 const [command, ...rest] = argv;
 async function withoutStack(args) {
@@ -121,6 +123,8 @@ async function withoutStack(args) {
             stack = args[++at] ?? "";
         else if (arg.startsWith("--stack="))
             stack = arg.slice("--stack=".length);
+        else if (arg === "--debug")
+            process.env.TURRI_DEBUG = "1";
         else
             kept.push(arg);
     }
@@ -173,7 +177,7 @@ process.argv = [
 // A headless run is stopped by a signal - SIGTERM, SIGHUP, Ctrl-C - whatever else listens for it: it exits, and what
 // its agents left running goes with it (shell.ts kills every process group on exit). Left to the libraries' own
 // handlers, one ran on for minutes after it was told to stop, building in the same codebase as the run after it.
-if (!["validate", "check", "drift", "lineage"].includes(command)) {
+if (!["validate", "check", "drift", "lineage", "ledger"].includes(command)) {
     for (const [signal, code] of [["SIGTERM", 143], ["SIGHUP", 129], ["SIGINT", 130]]) {
         process.on(signal, () => {
             console.error(`\nstopped (${signal})`);

package/dist/config-edit.d.ts

@@ -5,7 +5,7 @@
  * kept; `models:` and `agent-env:`, which nest, are written again whole, their own comments lost.
  */
 /** When a change takes effect. Nothing turri reads needs a restart: what is fixed at its start is changed live. */
-export type Effect = "now" | "next-message" | "next-pulse" | "next-plan" | "next-test-run" | "next-landing" | "next-regenerate";
+export type Effect = "now" | "next-message" | "next-pulse" | "next-plan" | "next-test-run" | "next-landing" | "next-regenerate" | "next-start";
 export type SettingKind = "boolean" | "choice" | "number" | "model" | "list" | "path" | "budget";
 export interface Setting {
     /** As written in the file - a nested one by its path: `models.coding`, `models.coding.turn-limit`, `agent-env.files`. */

package/dist/config-edit.js

@@ -11,6 +11,7 @@ export const EFFECT_TEXT = {
     "next-test-run": "in effect from the next test run - the running pulse's too",
     "next-landing": "in effect from the next pulse that lands - the running one too",
     "next-regenerate": "in effect for the next regeneration that names no .plain file",
+    "next-start": "in effect the next time turri starts here",
 };
 const SECONDS = ["0", "60", "120", "180", "300"];
 /** A role's line: which agents it is, for the list. */
@@ -75,6 +76,9 @@ export function settings(rules = []) {
         { key: "agent-env.files", about: "dotenv files whose variables the agents' commands get", kind: "list", unset: "none", effect: "next-pulse", projectOnly: true },
         { key: "agent-env.vars", about: "variables from turri's environment the agents' commands get, by name", kind: "list", unset: "none", effect: "next-pulse", projectOnly: true },
         { key: "toolchains", about: "folders of this machine an agent's commands may read beside the usual ones", kind: "list", unset: "none", effect: "next-pulse", projectOnly: true },
+        { key: "debug", about: "whether turri keeps what it writes for debugging it - agents' logs and sessions, pulse logs, outputs", kind: "boolean", unset: "false", effect: "next-pulse", projectOnly: true },
+        { key: "cache-keep", about: "megabytes of package caches the project keeps; 0 keeps none", kind: "number", options: ["0", "1024", "4096", "16384"], min: 0, unset: "4096", effect: "next-start", projectOnly: true },
+        { key: "ledger-keep", about: "megabytes of the ledger - what turri did, as facts - the project keeps; 0 keeps none", kind: "number", options: ["0", "50", "100", "500"], min: 0, unset: "100", effect: "next-start", projectOnly: true },
         ...roles,
     ];
 }

package/dist/config.d.ts

@@ -260,6 +260,23 @@ export interface ProjectConfig {
      * toolchain installed somewhere unusual. A module's own are added to the project's.
      */
     toolchains?: string[];
+    /**
+     * 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. Unset: 100.
+     */
+    ledgerKeep?: number;
+    /**
+     * Whether turri keeps what it writes for a person debugging it: every agent's whole log and saved session, each
+     * pulse's log, the testing scripts' and services' outputs, the agents' temporary files, and the dependencies installed
+     * in the modules a chain has left behind. Off, only what turri reads to work is kept. The project's alone. Unset: false.
+     */
+    debug?: boolean;
+    /**
+     * Megabytes of package caches - plain_modules/.turri/cache, and the caches in the agents' home folders - the project
+     * keeps: past it, the least recently written are removed when a run first starts an agent's command. 0 keeps none.
+     * The project's alone. Unset: 4096.
+     */
+    cacheKeep?: number;
     /** Each agent role's own model, thinking and turn limit; `default` for every role not named. */
     models?: Partial<Record<AgentRole | "default", RoleChoice>>;
     /** Seconds each turn of an agent a render starts has, for every role without its own. Unset: 120. 0: none. */
@@ -288,6 +305,9 @@ export declare const CONFIG_KEYS: {
     readonly maxLinesPerPulse: "max-lines-per-pulse";
     readonly agentEnv: "agent-env";
     readonly toolchains: "toolchains";
+    readonly ledgerKeep: "ledger-keep";
+    readonly debug: "debug";
+    readonly cacheKeep: "cache-keep";
     readonly models: "models";
     readonly turnLimit: "turn-limit";
 };
@@ -310,6 +330,13 @@ export declare function readProjectConfig(root: string, stack?: string): Project
  * edited. Never set in the conversation.
  */
 type RunOverrides = Partial<Pick<ProjectConfig, "harnessModel" | "codingModel" | "judgeModel" | "conformanceTests" | "review" | "mutationTesting">>;
+/** Megabytes of package caches a project keeps when `cache-keep:` does not say. */
+export declare const DEFAULT_CACHE_KEEP_MB = 4096;
+/**
+ * Whether turri keeps what it writes for a person debugging it, in this project: TURRI_DEBUG - `--debug` sets it, and
+ * `0` or `false` turns it off - else the project's `debug:`. Off by default.
+ */
+export declare function debugMode(project: string): boolean;
 /** Read a command's options as the config's keys for the rest of this process. */
 export declare function overrideConfig(overrides: RunOverrides): void;
 /** `--conformance-tests <value>`: the config's own values - all (or true), chosen, module, false. Undefined for anything else. */

package/dist/config.js

@@ -379,6 +379,9 @@ export const CONFIG_KEYS = {
     maxLinesPerPulse: "max-lines-per-pulse",
     agentEnv: "agent-env",
     toolchains: "toolchains",
+    ledgerKeep: "ledger-keep",
+    debug: "debug",
+    cacheKeep: "cache-keep",
     models: "models",
     turnLimit: "turn-limit",
 };
@@ -431,7 +434,7 @@ function readStackedConfig(root, stack) {
     // The project's alone: one conversation, one module built when none is named.
     const merged = { ...project };
     for (const key of Object.keys(CONFIG_KEYS)) {
-        if (key === "module" || key === "harnessModel" || key === "parallelJobs" || key === "rulesOff" || key === "compactAt" || key === "toolchains" || key === "agentEnv" || own[key] === undefined)
+        if (key === "module" || key === "harnessModel" || key === "parallelJobs" || key === "rulesOff" || key === "compactAt" || key === "ledgerKeep" || key === "debug" || key === "cacheKeep" || key === "toolchains" || key === "agentEnv" || own[key] === undefined)
             continue;
         merged[key] = own[key];
     }
@@ -443,6 +446,23 @@ function readStackedConfig(root, stack) {
     return withoutUndefined(merged);
 }
 let runOverrides = {};
+/** Megabytes of package caches a project keeps when `cache-keep:` does not say. */
+export const DEFAULT_CACHE_KEEP_MB = 4096;
+/**
+ * Whether turri keeps what it writes for a person debugging it, in this project: TURRI_DEBUG - `--debug` sets it, and
+ * `0` or `false` turns it off - else the project's `debug:`. Off by default.
+ */
+export function debugMode(project) {
+    const said = process.env.TURRI_DEBUG?.trim().toLowerCase();
+    if (said !== undefined && said !== "")
+        return said !== "0" && said !== "false";
+    try {
+        return readProjectConfig(project).debug === true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Read a command's options as the config's keys for the rest of this process. */
 export function overrideConfig(overrides) {
     runOverrides = { ...overrides };
@@ -542,6 +562,13 @@ function readConfigFile(path) {
             : undefined,
         maxSpecsPerPulse: positiveInteger(raw[CONFIG_KEYS.maxSpecsPerPulse]),
         maxLinesPerPulse: positiveInteger(raw[CONFIG_KEYS.maxLinesPerPulse]),
+        ledgerKeep: typeof raw[CONFIG_KEYS.ledgerKeep] === "number" && Number.isInteger(raw[CONFIG_KEYS.ledgerKeep]) && raw[CONFIG_KEYS.ledgerKeep] >= 0
+            ? raw[CONFIG_KEYS.ledgerKeep]
+            : undefined,
+        debug: typeof raw[CONFIG_KEYS.debug] === "boolean" ? raw[CONFIG_KEYS.debug] : undefined,
+        cacheKeep: typeof raw[CONFIG_KEYS.cacheKeep] === "number" && Number.isInteger(raw[CONFIG_KEYS.cacheKeep]) && raw[CONFIG_KEYS.cacheKeep] >= 0
+            ? raw[CONFIG_KEYS.cacheKeep]
+            : undefined,
         models: modelsSetting(raw[CONFIG_KEYS.models]),
         turnLimit: turnLimitSetting(raw[CONFIG_KEYS.turnLimit]),
     };

package/dist/extension.d.ts

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

package/dist/extension.js

@@ -44,6 +44,9 @@ import { describeDiagnosis, diagnoseFailure } from "./regenerate/diagnose.js";
 import { HISTORY_DIR, historyLog, historyShow } from "./regenerate/lineage.js";
 import { defaultBuildDir } from "./regenerate/paths.js";
 import { describeTurnIncident, describeUsage, onModelEvent } from "./regenerate/activity.js";
+import { ledgerWanted, startLedger } from "./regenerate/ledger.js";
+import { describePastPulse, describeRuns, earlierPulses, ledgerProjects } from "./regenerate/ledger-view.js";
+import { ledgerTool } from "./ledger-tools.js";
 import { describeSpecConflict } from "./regenerate/stop-report.js";
 import { inheritProviders, inheritThinkingLevel } from "./pi.js";
 import { beginCapture, captureConsole, describeCaptured, dropNoise } from "./quiet.js";
@@ -53,13 +56,14 @@ import { describeStdlib } from "./stdlib.js";
 import { peekKeyListener, runAsk } from "./ask.js";
 import { QuestionDialog } from "./question-dialog.js";
 import { registerStacks } from "./stacks.js";
-import { catalogueLine, discoverSkills, leftOutNote } from "./skills.js";
+import { catalogueLine, createCommandGate, discoverSkills, leftOutNote, startedByCommandOnly } from "./skills.js";
 import { supersededByTurri } from "./chat-skills.js";
-import { TURRI_IDENTITY } from "./identity.js";
+import { conversationIdentity } from "./identity.js";
+import { setSurface, surfaceOf } from "./surface.js";
 import { turriIdentity } from "./environment.js";
 import { conformanceChooser } from "./regenerate/choose-conformance.js";
 import { answerSideQuestion, askWithAsides, BTW_HOW, runningSkill, skillRunStarted, skillSessionText, transcriptOf } from "./btw.js";
-import { createJobRegistry, defaultParallelJobs, describeJob, formatDuration, pulseName, shouldWait, STOPPED_ON_REQUEST, } from "./regenerate/jobs.js";
+import { createJobRegistry, defaultParallelJobs, describeJob, firstRegeneration, formatDuration, formatElapsed, pulseName, shouldWait, STOPPED_ON_REQUEST, } from "./regenerate/jobs.js";
 /**
  * Makes gated skills reachable from a conversation.
  *
@@ -180,6 +184,14 @@ export function chatAskUserTool(dialogs) {
         },
     };
 }
+/**
+ * The conversation's system prompt for a turn: pi's, turri's identity - with the host's surface in place of the
+ * terminal's, when it has one - and turri's blocks; then the host's last word on it.
+ */
+function conversationSystemPrompt(base, host, blocks) {
+    const prompt = [base, conversationIdentity(host.surface), ...blocks].filter((part) => part !== "").join("\n\n");
+    return host.systemPrompt !== undefined ? host.systemPrompt(prompt) : prompt;
+}
 /** The host each conversation's jobs report to, for the work loop made for them later. */
 const hosts = new WeakMap();
 /** turri's conversation as an extension of pi's, for a host that runs it itself: see TurriHost. */
@@ -260,6 +272,8 @@ function turriExtension(pi, host) {
         },
     });
     hosts.set(jobs, host);
+    // What the model is told of where the person watches the work, deep in the tools too: the host's surface, or the terminal.
+    setSurface(jobs, host.surface);
     host.onJobs?.(jobs);
     // The ***plain rules go into the system prompt in full, every turn. The block is
     // identical each time, so it sits inside the cached prefix rather than invalidating it.
@@ -298,7 +312,7 @@ function turriExtension(pi, host) {
             }
         }
         return {
-            systemPrompt: [event.systemPrompt, TURRI_IDENTITY, TOOLS_NOT_CLI, projectConfigBlock(cwd), machineBlock(cwd, machine.now()), rulesBlock()].filter((part) => part !== "").join("\n\n"),
+            systemPrompt: conversationSystemPrompt(event.systemPrompt, host, [TOOLS_NOT_CLI, projectConfigBlock(cwd), machineBlock(cwd, machine.now()), rulesBlock()]),
         };
     });
     // The conversation's agent does not run turri again through its shell, unless the person
@@ -314,7 +328,7 @@ function turriExtension(pi, host) {
         if (event.toolName === "bash" && typeof command === "string") {
             const what = selfInvocation(command);
             if (what !== undefined && !askedForCommandLine(lastUserMessage))
-                return { block: true, reason: refusal(what) };
+                return { block: true, reason: refusal(what, surfaceOf(jobs)) };
         }
         markConversationWrite(event.toolCallId, event.toolName, event.input);
         return undefined;
@@ -368,6 +382,24 @@ function turriExtension(pi, host) {
                 ctx.ui.notify(event.job !== undefined ? `${event.job}: ${line}` : line, "warning");
         });
     });
+    // What this session does, as facts, in the project's .turri/ledger - a pulse's own in its project. Said once, in the
+    // chat, when it cannot be written.
+    const ledgerTrouble = [];
+    let tellLedgerTrouble;
+    if (ledgerWanted()) {
+        startLedger({
+            mode: Object.keys(host).length > 0 ? "host" : "chat",
+            project: cwd,
+            warn: (message) => (tellLedgerTrouble !== undefined ? tellLedgerTrouble(message) : ledgerTrouble.push(message)),
+        });
+    }
+    pi.on("session_start", (_event, ctx) => {
+        if (!ctx.hasUI)
+            return;
+        tellLedgerTrouble = (message) => ctx.ui.notify(message, "warning");
+        for (const message of ledgerTrouble.splice(0))
+            tellLedgerTrouble(message);
+    });
     // What a turri that was killed left running - its commands' process groups - stopped as this one starts.
     const orphans = sweepOrphanedGroups();
     let orphansSaid = orphans === 0;
@@ -416,6 +448,19 @@ function turriExtension(pi, host) {
         return;
     const catalogue = skills.map(catalogueLine).join("\n");
     const pendingNote = leftOutNote(discoveredSkills);
+    // The skills the person starts themselves - brood, spawn, bud: each has its command, and cultivate starts it only
+    // once its command is typed. The command puts what was typed in the chat, as the person's message, for the model to
+    // run it with what follows as its context.
+    const gate = createCommandGate();
+    for (const skill of skills.filter((s) => s.commandOnly)) {
+        pi.registerCommand(skill.name, {
+            description: `Start ${skill.name}${skill.steps.length > 1 ? ` - ${skill.steps.map((step) => step.name).join(" → ")}` : ""}: /${skill.name} [what you want]`,
+            handler: async (args) => {
+                gate.typed(skill.name);
+                pi.sendUserMessage(`/${skill.name}${args.trim() !== "" ? ` ${args.trim()}` : ""}`, { deliverAs: "followUp" });
+            },
+        });
+    }
     pi.registerTool({
         name: "cultivate",
         label: "Cultivate",
@@ -426,6 +471,7 @@ function turriExtension(pi, host) {
         promptSnippet: "cultivate: run a gated skill - its steps and review gates enforced by turri",
         promptGuidelines: [
             "When a request matches a skill listed in cultivate's description, call cultivate instead of doing the work yourself. Doing it by hand skips the review gates.",
+            "A skill marked as started only by the person runs only from its command: a message that is its command - /spawn a small server - is the person starting it, so call cultivate for it at once, with what follows the command as context. Never call cultivate for one otherwise; tell them to type its command.",
             // pi lists .agents/skills among its own skills too: read and followed by hand, a skill's gates would be skipped.
             "A skill cultivate lists may also be among your own skills, from the project's .agents/skills: run it with cultivate all the same, never by reading its SKILL.md and following it.",
             "cultivate returns the reviewed artifact and a trace of every gate decision. Report the artifact to the user; do not rewrite it.",
@@ -458,6 +504,8 @@ function turriExtension(pi, host) {
                     details: {},
                 };
             }
+            if (!gate.mayStart(skill))
+                return { content: [{ type: "text", text: startedByCommandOnly(skill.name) }], details: { notStarted: true } };
             // A new run clears the run folder. An interrupted one is not thrown away by accident:
             // whether to pick it up or start over is the user's call.
             const runDir = skillRunDir(cwd, skill.name);
@@ -475,6 +523,8 @@ function turriExtension(pi, host) {
                     details: { interrupted },
                 };
             }
+            // Its command is used up: started again later, it is typed again.
+            gate.started(skill.name);
             const trace = [`skill: ${skill.name}`, ...describeGates(skill).map((l) => `  ${l}`)];
             // While it runs, what its agent is doing leads: pi shows a running tool's first lines, and the trace's first
             // lines are the gates, which say nothing about now. The result keeps the trace alone.
@@ -560,6 +610,8 @@ function turriExtension(pi, host) {
             const filesBefore = projectFiles(cwd);
             // A side question asked while it runs is told what it has done so far.
             const ended = skillRunStarted({ skill: skill.name, dir: skill.dir, step: () => live.step, trace: () => [...trace], runDir });
+            // From here the time to first regeneration is counted, for a skill that writes spec diffs: its first pulse started.
+            const began = Date.now();
             const { result, output: captured } = await captureConsole(() => runSkill({
                 skillDir: skill.dir,
                 cwd,
@@ -620,11 +672,17 @@ function turriExtension(pi, host) {
                 ? `${specsChanged.join(", ")} changed, and nothing is regenerated from that yet: call regenerate for it, and the code is brought up to the spec.`
                 : "";
             const gated = skill.steps.some((step) => step.gate !== undefined);
+            const first = skill.allowedTools.includes("write_spec_diff") ? firstRegeneration(jobs.list(), began) : {};
+            const ttfr = first.started === undefined
+                ? ""
+                : `Time to first regeneration: ${formatElapsed(first.started)} - its first pulse started that long after ${skill.name} began` +
+                    (first.landed !== undefined ? `, and landed after ${formatElapsed(first.landed)}.` : ".");
             const text = result.ok
                 ? [
                     gated ? `${skill.name}: passed all gates.` : `${skill.name}: finished. It has no review gates, so nothing checked its work: read what it changed before you report it.`,
                     changed,
                     ...(unrendered !== "" ? [unrendered] : []),
+                    ...(ttfr !== "" ? [ttfr] : []),
                     "",
                     "<artifact>",
                     result.output,
@@ -1411,28 +1469,40 @@ async function deliver(jobs, input) {
 const panelOpeners = new WeakMap();
 /** By registry: the last pulse that failed, stopped or did not pass, not yet looked at - ctrl+h opens on it. */
 const needsLooking = new WeakMap();
+/** What heads a pulse told from the ledger: it is not this session's, and the facts are all there is of it. */
+const pastPulseNote = "A pulse of an earlier session, as the ledger recorded it - facts, not its transcript. Its whole log is the file it names, " +
+    "for the read tool.";
 function registerJobTools(pi, jobs, cwd) {
     pi.registerTool({
         name: "diagnose",
         label: "Diagnose a pulse",
         description: "Why a pulse did not land, from its whole transcript: how it ended and its diagnosis, the stages that went wrong, the " +
             "last failing test run with its output, the last review that sent the work back, and the tool calls that failed - " +
-            "and where the whole log is.",
+            "and where the whole log is. A pulse of an earlier session is told from the ledger - what it recorded of it, as facts.",
         promptSnippet: "diagnose: why a pulse did not land, from its transcript",
         promptGuidelines: ["When a pulse failed or did not land, call diagnose before you explain it or change the spec: go by what happened, not by the report alone."],
         parameters: Type.Object({ job_id: Type.String({ description: "The pulse's id" }) }),
         async execute(_id, params) {
             const job = jobs.get(params.job_id);
-            if (job === undefined)
-                return { content: [{ type: "text", text: `No pulse ${params.job_id} has run in this session.` }], details: { status: "unknown" } };
-            return { content: [{ type: "text", text: whyFailed(job) }], details: { status: job.status } };
+            if (job === undefined) {
+                const past = describePastPulse(ledgerProjects(cwd), params.job_id);
+                if (past !== undefined)
+                    return { content: [{ type: "text", text: `${pastPulseNote}\n\n${past}` }], details: { status: "earlier" } };
+                return { content: [{ type: "text", text: `No pulse ${params.job_id} has run in this session, and the ledger has none by that id.` }], details: { status: "unknown" } };
+            }
+            // What the ledger recorded of it besides: its rounds, test runs, healers and commits, as facts.
+            const facts = describePastPulse(ledgerProjects(cwd), job.id);
+            const text = facts !== undefined ? `${whyFailed(job)}\n\nWhat the ledger recorded of it:\n${facts}` : whyFailed(job);
+            return { content: [{ type: "text", text }], details: { status: job.status } };
         },
     });
+    pi.registerTool(ledgerTool({ cwd }));
     pi.registerTool({
         name: "pulses",
         label: "Pulses",
         description: "What is regenerating: with no pulse, every pulse of this session - running, planned and finished - and what deploy started; " +
-            "with a pulse's id, that pulse - whether it is still running, its latest output, and its report once it has finished.",
+            "with a pulse's id, that pulse - whether it is still running, its latest output, and its report once it has finished. " +
+            "A pulse of an earlier session is told from the ledger.",
         promptSnippet: "pulses: every pulse, or one - what is regenerating and how it is going",
         parameters: Type.Object({
             job_id: Type.Optional(Type.String({ description: "The id returned when the pulse started. Omitted: every pulse" })),
@@ -1440,7 +1510,7 @@ function registerJobTools(pi, jobs, cwd) {
         }),
         async execute(_id, params) {
             if (params.job_id === undefined) {
-                return { content: [{ type: "text", text: listJobs(jobs) }], details: { status: "all" } };
+                return { content: [{ type: "text", text: listJobs(jobs, cwd) }], details: { status: "all" } };
             }
             const existing = jobs.get(params.job_id);
             const planned = shownJobs(jobs).find((job) => job.id === params.job_id && jobs.get(job.id) === undefined);
@@ -1451,6 +1521,9 @@ function registerJobTools(pi, jobs, cwd) {
                 };
             }
             if (existing === undefined) {
+                const past = describePastPulse(ledgerProjects(cwd), params.job_id);
+                if (past !== undefined)
+                    return { content: [{ type: "text", text: `${pastPulseNote}\n\n${past}` }], details: { status: "earlier" } };
                 const known = shownJobs(jobs).map((job) => job.id);
                 return {
                     content: [
@@ -1564,6 +1637,21 @@ function registerJobTools(pi, jobs, cwd) {
     const panelBeside = () => (panelDocked && panelTerminal !== undefined ? dockedWidth(paddedColumns(panelTerminal.columns)) : 0);
     // What is open in the pulse list and the map, and where their cursors are: the conversation's, as left each time it opens.
     const jobsTree = createJobsTreeState();
+    // Earlier sessions' pulses, from the ledger: read as the panel first shows them - they do not change while this one runs.
+    let earlier;
+    const earlierJobs = () => {
+        if (earlier !== undefined)
+            return earlier;
+        try {
+            const found = earlierPulses(ledgerProjects(cwd), new Set(jobs.list().map((job) => job.id)));
+            earlier = found.jobs;
+            jobsTree.earlierMore = found.more;
+        }
+        catch {
+            earlier = [];
+        }
+        return earlier;
+    };
     const mapState = createSpecMapState();
     // The map from the files - the .plain files asked for, else the project's - with the work loop's plan laid over them.
     const specMap = createSpecMapSource({
@@ -1657,6 +1745,7 @@ function registerJobTools(pi, jobs, cwd) {
             specMap.refresh();
             const view = createSidePanel({
                 jobs: () => shownJobs(jobs),
+                earlier: earlierJobs,
                 tree: jobsTree,
                 map: () => specMap.read(),
                 mapState,
@@ -1930,13 +2019,27 @@ function deployedLabel(name, what) {
 function shownJobs(jobs) {
     return [...(workLoops.get(jobs)?.loop.planned() ?? []), ...jobs.list()];
 }
-function listJobs(jobs) {
+function listJobs(jobs, cwd) {
     const all = [...shownJobs(jobs)].reverse().filter((job) => job.replacedBy === undefined);
     const deployed = runningDeployed().map((item) => `deploy ${item.name}  running  ${item.moduleName}: ${item.url ?? item.command}  (pid ${item.pid}, output in ${relative(process.cwd(), item.log) || item.log})`);
     const listed = deployed.length > 0 ? `\n\nActivated from dist - /halt activated <name> halts one:\n${deployed.join("\n")}` : "";
+    const before = earlierRuns(jobs, cwd);
     if (all.length === 0)
-        return `No pulses have been started.${listed}`;
-    return `${jobLines(all)}${listed}`;
+        return `No pulses have been started in this session.${listed}${before}`;
+    return `${jobLines(all)}${listed}${before}`;
+}
+/** Earlier sessions' last runs and their pulses, from the ledger - nothing when it has none. */
+function earlierRuns(jobs, cwd) {
+    try {
+        const found = earlierPulses(ledgerProjects(cwd), new Set(jobs.list().map((job) => job.id)));
+        if (found.runs.length === 0)
+            return "";
+        const more = found.more > 0 ? `\n\n${found.more} earlier run${found.more === 1 ? "" : "s"} beyond these are in the ledger.` : "";
+        return `\n\nEarlier sessions, from the ledger - pulses or diagnose with a pulse's id tells one:\n${describeRuns(found.runs)}${more}`;
+    }
+    catch {
+        return "";
+    }
 }
 function jobLines(all) {
     return all
@@ -2083,6 +2186,7 @@ async function askOnTheSide(pi, ctx, cwd, jobs, question) {
         pulses: jobs.list().map((job) => `${job.id} ${job.status}: ${pulseName(job)}`),
         projectDir: cwd,
         harnessDir: PACKAGE_ROOT,
+        ...(surfaceOf(jobs) !== undefined ? { surface: surfaceOf(jobs) } : {}),
     }, chatModelOf(ctx));
     try {
         pi.appendEntry(SIDE_ENTRY, { question, answer });

package/dist/genome.js

@@ -136,6 +136,8 @@ export async function runSkill(opts) {
         rules: true,
         system: toolchainsBlock(),
         resumeFrom: resumed?.sessionFile,
+        // Its run picks it back up (resume) and the side questions read it (btw): saved whatever the mode.
+        saveSession: true,
     });
     const manifest = resumed ?? {
         skill: skill.name,

package/dist/host.d.ts

@@ -8,7 +8,7 @@ export { createTurriExtension, type TurriHost } from "./extension.ts";
 export type { AskUserIO } from "./ask.ts";
 /** pi itself, as turri's extension is built against it: a host makes its session with this one, not another copy. */
 export * as pi from "@earendil-works/pi-coding-agent";
-export { configForSpec, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf, type ProjectConfig } from "./config.ts";
+export { configForSpec, debugMode, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf, type ProjectConfig } from "./config.ts";
 export { MODULES_DIR, projectDirOf, resolveTemplateDirs } from "./regenerate/paths.ts";
 export { BEDROCK_DEFAULT, BEDROCK_REGIONS, bedrockModels, initConfig, VENDORS, type BedrockChoice, type Vendor } from "./init-config.ts";
 export { checkPlainFile, type CheckResult } from "./plain/check.ts";
@@ -19,3 +19,5 @@ export { createWorkLoop, describeModules, functionalityCompletion, promptOf, typ
 export { createJobRegistry, defaultParallelJobs, type Job, type JobRegistry } from "./regenerate/jobs.ts";
 export { describeTurnIncident, onModelEvent, type TranscriptEntry } from "./regenerate/activity.ts";
 export { sweepOrphanedGroups } from "./regenerate/shell.ts";
+export { ledgerDir, onLedgerEvent, readLedger, type AgentRef, type LedgerEntry, type LedgerEvent, type LedgerKind, type LedgerQuery } from "./regenerate/ledger.ts";
+export { asJob, describePulseView, describeRuns, earlierPulses, ledgerProjects, pulseView, runViews, type PulseView, type RunView } from "./regenerate/ledger-view.ts";

package/dist/host.js

@@ -9,7 +9,7 @@ export { createTurriExtension } from "./extension.js";
 /** pi itself, as turri's extension is built against it: a host makes its session with this one, not another copy. */
 export * as pi from "@earendil-works/pi-coding-agent";
 // The project and its settings.
-export { configForSpec, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf } from "./config.js";
+export { configForSpec, debugMode, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf } from "./config.js";
 export { MODULES_DIR, projectDirOf, resolveTemplateDirs } from "./regenerate/paths.js";
 // A project's first config.turri.yaml, as `turri init-config` writes it - the vendor whose models it takes chosen by the host.
 export { BEDROCK_DEFAULT, BEDROCK_REGIONS, bedrockModels, initConfig, VENDORS } from "./init-config.js";
@@ -23,3 +23,6 @@ export { createWorkLoop, describeModules, functionalityCompletion, promptOf } fr
 export { createJobRegistry, defaultParallelJobs } from "./regenerate/jobs.js";
 export { describeTurnIncident, onModelEvent } from "./regenerate/activity.js";
 export { sweepOrphanedGroups } from "./regenerate/shell.js";
+// What turri did, as facts: the ledger, heard live and read back - this session's pulses and every earlier one's.
+export { ledgerDir, onLedgerEvent, readLedger } from "./regenerate/ledger.js";
+export { asJob, describePulseView, describeRuns, earlierPulses, ledgerProjects, pulseView, runViews } from "./regenerate/ledger-view.js";

package/dist/identity.d.ts

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