@turri-dev/cli 0.1.8-next.01c7342 → 0.1.8-next.b03162b

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" },
 };
@@ -173,7 +174,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,7 @@ 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: "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,11 @@ 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;
     /** 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 +293,7 @@ export declare const CONFIG_KEYS: {
     readonly maxLinesPerPulse: "max-lines-per-pulse";
     readonly agentEnv: "agent-env";
     readonly toolchains: "toolchains";
+    readonly ledgerKeep: "ledger-keep";
     readonly models: "models";
     readonly turnLimit: "turn-limit";
 };

package/dist/config.js

@@ -379,6 +379,7 @@ export const CONFIG_KEYS = {
     maxLinesPerPulse: "max-lines-per-pulse",
     agentEnv: "agent-env",
     toolchains: "toolchains",
+    ledgerKeep: "ledger-keep",
     models: "models",
     turnLimit: "turn-limit",
 };
@@ -431,7 +432,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 === "toolchains" || key === "agentEnv" || own[key] === undefined)
             continue;
         merged[key] = own[key];
     }
@@ -542,6 +543,9 @@ 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,
         models: modelsSetting(raw[CONFIG_KEYS.models]),
         turnLimit: turnLimitSetting(raw[CONFIG_KEYS.turnLimit]),
     };

package/dist/extension.js

@@ -44,6 +44,8 @@ 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 { describeSpecConflict } from "./regenerate/stop-report.js";
 import { inheritProviders, inheritThinkingLevel } from "./pi.js";
 import { beginCapture, captureConsole, describeCaptured, dropNoise } from "./quiet.js";
@@ -379,6 +381,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;
@@ -1448,20 +1468,27 @@ 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" } };
+            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" } };
+            }
             return { content: [{ type: "text", text: whyFailed(job) }], details: { status: job.status } };
         },
     });
@@ -1469,7 +1496,8 @@ function registerJobTools(pi, jobs, cwd) {
         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" })),
@@ -1477,7 +1505,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);
@@ -1488,6 +1516,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: [
@@ -1601,6 +1632,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({
@@ -1694,6 +1740,7 @@ function registerJobTools(pi, jobs, cwd) {
             specMap.refresh();
             const view = createSidePanel({
                 jobs: () => shownJobs(jobs),
+                earlier: earlierJobs,
                 tree: jobsTree,
                 map: () => specMap.read(),
                 mapState,
@@ -1967,13 +2014,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

package/dist/host.d.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

@@ -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/init-config.d.ts

@@ -66,6 +66,7 @@ export declare const DEFAULTS: {
     readonly compactAt: 100000;
     readonly maxSpecsPerPulse: 3;
     readonly maxLinesPerPulse: 120;
+    readonly ledgerKeep: 100;
 };
 /** How many pulses run at once without a setting: half this machine's cores, one to four - as regenerate/jobs.ts has it. */
 export declare function defaultParallel(cores?: number): number;

package/dist/init-config.js

@@ -118,6 +118,7 @@ export const DEFAULTS = {
     compactAt: 100000,
     maxSpecsPerPulse: 3,
     maxLinesPerPulse: 120,
+    ledgerKeep: 100,
 };
 /** How many pulses run at once without a setting: half this machine's cores, one to four - as regenerate/jobs.ts has it. */
 export function defaultParallel(cores = availableParallelism()) {
@@ -183,6 +184,10 @@ export function quickStartConfig(vendor = "other", bedrock) {
         "# Folders of this machine an agent's commands may read beside the usual ones - a toolchain somewhere unusual: [/srv/zig].",
         "toolchains: []",
         "",
+        "# Megabytes of the ledger - what turri did, as facts, in .turri/ledger, never committed - the project keeps; past it,",
+        "# the oldest runs' are pruned. 0 keeps none.",
+        `ledger-keep: ${DEFAULTS.ledgerKeep}`,
+        "",
         "# The testing scripts, by path from the project root - written here by the skill that writes them. One not named is",
         "# looked for at the root, then in test_scripts/. Each runs the static checks of what it tests - the formatter, the",
         "# linter, the type checker - with the tests, exiting 80 when the tests pass and only the checks do not. The prepare",

package/dist/ledger-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ledger-cli.js

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

package/dist/loop-cli.js

@@ -5,6 +5,7 @@ import { configForSpec, inheritModel, modelOnly, modelSpec, projectModels, readP
 import { PACKAGE_ROOT } from "./environment.js";
 import { c } from "./module-report.js";
 import { describeTurnIncident, onModelEvent } from "./regenerate/activity.js";
+import { ledgerWanted, startLedger } from "./regenerate/ledger.js";
 import { tryItCommand } from "./regenerate/delivery.js";
 import { describeDiagnosis, diagnoseFailure } from "./regenerate/diagnose.js";
 import { createJobRegistry, pulseName } from "./regenerate/jobs.js";
@@ -32,6 +33,9 @@ export async function runLoop(options) {
     // The models as the config has them - with a command's own options read as its keys (headlessOptions), as the chat reads them.
     const model = modelSpec(projectModels(project).coding);
     const projectDir = projectDirOf(plainFile);
+    // What the run does, as facts, in the project's .turri/ledger.
+    if (ledgerWanted() && options.dryRun !== true)
+        startLedger({ mode: options.command?.[0] ?? "headless", project: projectDir, warn: (message) => console.error(message) });
     const buildDir = options.buildDir !== undefined && options.dryRun !== true ? resolve(options.buildDir) : undefined;
     if (buildDir !== undefined)
         refuseBuildDir(buildDir, projectDir);

package/dist/pi.js

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

package/dist/regenerate/activity.d.ts

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

package/dist/regenerate/activity.js

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

package/dist/regenerate/agent-shell.js

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

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

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

package/dist/regenerate/chunk-plan.js

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

package/dist/regenerate/conformance.js

@@ -6,6 +6,7 @@ import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_
 import { reportActivity, reportLogNote, reportSpec, reportStage, unitOf } from "./activity.js";
 import { confinedTools } from "./confine.js";
 import { abandonWork, diffSinceSnapshot, landWork, moduleDirOf, startWork, workDiff, workSnapshot } from "./lineage.js";
+import { firstLine, record } from "./ledger.js";
 import { createWorkLedger, describeAccounts, SUBMIT_WORK_NOTE, unanswered, unansweredPrompt } from "./submit-work.js";
 import { CONFORMANCE_COMPACTION } from "./compaction.js";
 import { NOTES_TURN, notesForSession, passedOutcome, readNotes, reflectOnReview, withNotes } from "./notes.js";
@@ -417,6 +418,7 @@ export async function renderConformanceTests(options) {
             // every functionality's tests - and the code's unit testing script.
             stage(`running the conformance testing script on the whole suite (attempt ${rounds + 1} of ${maxRounds})`);
             rounds += 1;
+            record({ kind: "gate.round", gate: "conformance", round: rounds, of: maxRounds });
             let recheck = await runConformanceScript(buildDir, [conformanceDir], scripts);
             runs.push({ command: recheck.command, exitCode: recheck.exitCode });
             options.onRun?.(recheck.command, recheck.exitCode);
@@ -537,6 +539,7 @@ export async function renderConformanceTests(options) {
                     onDelta: options.onDelta,
                 });
                 const reason = verdict.reason.split("\n")[0].slice(0, 160);
+                record({ kind: "judge.verdict", culprit: verdict.culprit, round: rounds, reason: firstLine(verdict.reason, 300) });
                 // Stopped by the time limit while it was still getting on: no agent can give it more time. The pulse stops now -
                 // rolled back, no retry - and the person is told how to raise the limit.
                 if (verdict.culprit === "environment" && recheck.timedOut === true) {

package/dist/regenerate/diagnose.js

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