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

package/dist/pi.js

@@ -2,13 +2,14 @@ import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, ModelRegistry, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { loadRules, renderRulesBlock } from "./rules.js";
-import { inheritModel, stackOf, readProjectConfig, ROLE_THINKING, roleModel, roleTurnLimitMs, splitModelSpec } from "./config.js";
+import { debugMode, inheritModel, stackOf, readProjectConfig, ROLE_THINKING, roleModel, roleTurnLimitMs, splitModelSpec } from "./config.js";
 import { maskToolResults } from "./regenerate/masking.js";
 import { withListArguments } from "./regenerate/list-arguments.js";
 import { checkAgainstScript, ENVIRONMENT_ERROR_TOOL, EnvironmentError, environmentErrorTool, sandboxGapOf } from "./regenerate/environment-error.js";
 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`);
@@ -736,11 +753,14 @@ export function guardRepeats(tools, session, budget) {
  * start that has forgotten what it just wrote.
  */
 export async function createExecutor(opts) {
-    // Saved to disk, in the project: an agent's session is the record of what it did, and the
-    // only way to pick a long run back up after the process that ran it is gone.
+    // Saved to disk, in the project, for an agent picked back up after the process that ran it is gone - a skill's run -
+    // and in debug mode, as the record of what each did. Nothing else reads one back: the rest are kept in memory.
+    const project = projectRootOf(opts.cwd);
     const sessionManager = opts.resumeFrom !== undefined
         ? SessionManager.open(opts.resumeFrom)
-        : SessionManager.create(opts.cwd, sessionsDir(projectRootOf(opts.cwd)));
+        : opts.saveSession === true || debugMode(project)
+            ? SessionManager.create(opts.cwd, sessionsDir(project))
+            : SessionManager.inMemory(opts.cwd);
     // An agent that writes and runs code - given the harness's run its reports are checked against - can say the machine
     // lacks what the work needs: its turn ends, and the pulse stops with it. Observers, explorers and judges cannot.
     const hasShell = opts.customTools.some((tool) => tool.name === "bash") && opts.checkEnvironment !== undefined;

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

@@ -28,6 +28,13 @@ export declare function agentEnvironment(moduleDir: string, options?: {
     hostEnv?: NodeJS.ProcessEnv;
     home?: string;
 }): AgentEnvironment;
+/**
+ * Hold the package caches of a scratch area to `keepMb` megabytes: past it, the caches least recently written go whole -
+ * a package manager's folder in `cache`, or a tool's in an agent's home - until it is under. A cache is as recent as the
+ * newest thing written anywhere in it: a package manager writes deep inside its folder, never beside it. What goes is
+ * downloaded again when it is wanted. Never a reason for the work to fail.
+ */
+export declare function tidyCaches(scratch: string, keepMb: number): void;
 /**
  * On macOS, what a program asks the system for as the per-user temporary folder - not TMPDIR - is that folder with this
  * suffix added: a folder of the module's own inside it. The JVM keeps its attach sockets there (`.java_pid<pid>`), which

package/dist/regenerate/agent-env.js

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
-import { readProjectConfig, stackOf } from "../config.js";
+import { DEFAULT_CACHE_KEEP_MB, readProjectConfig, stackOf } from "../config.js";
 import { registerSecrets } from "./masking.js";
 import { projectRootOf, modulesScratchDir } from "./paths.js";
 /**
@@ -12,9 +12,9 @@ import { projectRootOf, modulesScratchDir } from "./paths.js";
  * agent, and an agent's command - or the code it runs - could read any of them. So only an allow-list passes: the path,
  * the locale, the terminal, the user, and the variables that locate the host's toolchains. Then turri's own: a HOME of
  * the module's own, kept between pulses, so a tool's settings and an agent's dotfiles never land in the person's; a
- * TMPDIR; the package caches in the project, so a dependency downloads once; and git stopped at the module, so a
- * project that is itself a repository is not found from the code. Last, what the project passes on purpose -
- * `agent-env:` in its config - which never replaces turri's own.
+ * TMPDIR; the package caches in the project, so a dependency downloads once - held to `cache-keep:`; and git stopped
+ * at the module, so a project that is itself a repository is not found from the code. Last, what the project passes on
+ * purpose - `agent-env:` in its config - which never replaces turri's own.
  */
 /** Passed from the host as they are. */
 const ALLOWED = ["PATH", "LANG", "TERM", "TZ", "USER", "LOGNAME", "COLORTERM"];
@@ -62,11 +62,18 @@ export function cacheEnv(cache) {
         GRADLE_USER_HOME: join(cache, "gradle"),
         CARGO_HOME: join(cache, "cargo"),
         npm_config_cache: join(cache, "npm"),
+        // node-gyp's headers, which it keeps in the home folder - a copy each module's - once for the project.
+        npm_config_devdir: join(cache, "node-gyp"),
         YARN_CACHE_FOLDER: join(cache, "yarn"),
         PIP_CACHE_DIR: join(cache, "pip"),
         UV_CACHE_DIR: join(cache, "uv"),
         GOCACHE: join(cache, "go-build"),
         GOMODCACHE: join(cache, "go-mod"),
+        // The browsers the end-to-end test tools download - hundreds of megabytes each, kept in the home folder: once for
+        // the project, not once a module.
+        PLAYWRIGHT_BROWSERS_PATH: join(cache, "ms-playwright"),
+        PUPPETEER_CACHE_DIR: join(cache, "puppeteer"),
+        CYPRESS_CACHE_FOLDER: join(cache, "Cypress"),
     };
 }
 /** The git identity an agent's commits in a scratch repository get - never the person's. */
@@ -101,9 +108,123 @@ export function agentEnvironment(moduleDir, options = {}) {
     Object.assign(env, turrisOwn(module, name));
     return { env, passed: Object.keys(values).sort(), values, missing };
 }
+/** The scratch areas whose caches this process has held to `cache-keep:`: once a run, before its first command. */
+const tidied = new Set();
+/** Where in an agent's home folder its tools keep caches of their own. */
+const HOME_CACHES = [join("Library", "Caches"), ".cache"];
+/**
+ * Hold the package caches of a scratch area to `keepMb` megabytes: past it, the caches least recently written go whole -
+ * a package manager's folder in `cache`, or a tool's in an agent's home - until it is under. A cache is as recent as the
+ * newest thing written anywhere in it: a package manager writes deep inside its folder, never beside it. What goes is
+ * downloaded again when it is wanted. Never a reason for the work to fail.
+ */
+export function tidyCaches(scratch, keepMb) {
+    const caches = [];
+    const folders = [join(scratch, "cache")];
+    for (const home of entries(join(scratch, "home")))
+        for (const inHome of HOME_CACHES)
+            folders.push(join(scratch, "home", home, inHome));
+    for (const folder of folders) {
+        for (const name of entries(folder)) {
+            const path = join(folder, name);
+            try {
+                caches.push({ path, ...measure(path) });
+            }
+            catch {
+                /* gone meanwhile */
+            }
+        }
+    }
+    let total = caches.reduce((sum, cache) => sum + cache.bytes, 0);
+    for (const cache of caches.sort((a, b) => a.written - b.written)) {
+        if (total <= keepMb * 1024 * 1024)
+            break;
+        total -= cache.bytes;
+        // What could not be removed still counts: a cache half gone is not the room it took.
+        if (existsSync(cache.path))
+            total += remove(cache.path);
+    }
+}
+function entries(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** A file's or folder's bytes and when anything in it was last written, its links not followed. */
+function measure(path) {
+    const stat = lstatSync(path);
+    if (!stat.isDirectory())
+        return { bytes: stat.size, written: stat.mtimeMs };
+    let bytes = 0;
+    let written = stat.mtimeMs;
+    for (const name of entries(path)) {
+        try {
+            const inside = measure(join(path, name));
+            bytes += inside.bytes;
+            written = Math.max(written, inside.written);
+        }
+        catch {
+            /* gone meanwhile */
+        }
+    }
+    return { bytes, written };
+}
+/**
+ * Remove a cache whole, and say how many of its bytes are left. Some tools make what they cache read-only - Go's module
+ * cache, so it is never edited in place - and a folder that cannot be written cannot be emptied: each is made writable
+ * first, as `go clean -modcache` does.
+ */
+function remove(path) {
+    try {
+        rmSync(path, { recursive: true, force: true });
+    }
+    catch {
+        writable(path);
+        try {
+            rmSync(path, { recursive: true, force: true });
+        }
+        catch {
+            /* what cannot be removed stays */
+        }
+    }
+    try {
+        return existsSync(path) ? measure(path).bytes : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Every folder under `path` made writable by its owner, links not followed. */
+function writable(path) {
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isDirectory())
+            return;
+        chmodSync(path, stat.mode | 0o700);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries(path))
+        writable(join(path, name));
+}
 /** HOME, TMPDIR, the caches and git's ceiling: what no setting of the project's replaces. */
 function turrisOwn(module, name) {
     const scratch = modulesScratchDir(module);
+    if (!tidied.has(scratch)) {
+        tidied.add(scratch);
+        let keep = DEFAULT_CACHE_KEEP_MB;
+        try {
+            keep = readProjectConfig(projectRootOf(module)).cacheKeep ?? DEFAULT_CACHE_KEEP_MB;
+        }
+        catch {
+            /* a config that does not parse is said elsewhere: the default holds */
+        }
+        tidyCaches(scratch, keep);
+    }
     const fakeHome = join(scratch, "home", name);
     mkdirSync(fakeHome, { recursive: true });
     const gitconfig = join(fakeHome, ".gitconfig");

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

@@ -79,6 +79,11 @@ export declare function stepsOf(input: PlanInput, draft: DraftJob[]): Array<Draf
     step: SpecStep;
 }>;
 export declare const MAX_SPECS_PER_JOB = 3;
+/** The most a pulse's title is - in words, and in characters - however it was made: a host shows it as its heading. */
+export declare const TITLE_WORDS = 10;
+export declare const TITLE_CHARS = 70;
+/** A title held to `TITLE_WORDS` and `TITLE_CHARS` - or less, for room beside it - cut at a word, with an ellipsis. */
+export declare function shortTitle(text: string, chars?: number, words?: number): string;
 export declare const MAX_LINES_PER_JOB = 120;
 /**
  * A functional spec to build, for the grouping: the number the agent answers with, its text, and whether it is built
@@ -147,12 +152,6 @@ export interface ChunkAgents {
 export declare function groupProblems(specs: NewSpec[], answer: GroupAnswer, maxSpecs?: number): string[];
 /** What is wrong with a placement: every new req once, each where there is such a job. */
 export declare function placeProblems(input: PlaceInput, answer: PlaceAnswer): string[];
-/**
- * Cut the queue's work - from `input.base` to `input.current` - into jobs, as the three steps say. Returns the draft
- * the work loop runs: checked (checkDraft), or, when nothing holds, the whole work as one job. `notes` is given what
- * the plan did not do as asked - the person's wishes an agent did not follow and why, an answer that did not hold, a
- * group split for its size - for the conversation to say, rather than guess.
- */
 export declare function planChunks(input: PlanInput, agents?: ChunkAgents, notes?: string[]): Promise<DraftJob[]>;
 export declare function groupPrompt(specs: NewSpec[], steering?: Steering[], maxSpecs?: number): string;
 export declare function placePrompt(input: PlaceInput): string;

package/dist/regenerate/chunk-plan.js

@@ -4,6 +4,7 @@ import { DEFAULT_CONCEPTS, extractConceptsFromDefinition, extractConceptsFromSpe
 import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS, TEST_REQUIREMENTS } from "../plain/spec.js";
 import { ask, BEGIN, createExecutor } from "../pi.js";
 import { reportActivity, reportStage } from "./activity.js";
+import { firstLine, record } from "./ledger.js";
 import { steeringBlock } from "./steer.js";
 import { marksRegenerateAgain } from "./records.js";
 import { validateConcepts } from "../plain/concepts.js";
@@ -70,6 +71,19 @@ export function stepsOf(input, draft) {
     });
 }
 export const MAX_SPECS_PER_JOB = 3;
+/** The most a pulse's title is - in words, and in characters - however it was made: a host shows it as its heading. */
+export const TITLE_WORDS = 10;
+export const TITLE_CHARS = 70;
+/** A title held to `TITLE_WORDS` and `TITLE_CHARS` - or less, for room beside it - cut at a word, with an ellipsis. */
+export function shortTitle(text, chars = TITLE_CHARS, words = TITLE_WORDS) {
+    const all = text.trim().split(/\s+/).filter((word) => word !== "");
+    let cut = all.slice(0, words).join(" ");
+    if (all.length <= words && cut.length <= chars)
+        return cut;
+    if (cut.length > chars - 1)
+        cut = cut.slice(0, chars - 1).replace(/\s+\S*$/, "") || cut.slice(0, chars - 1);
+    return `${cut.replace(/[\s,.;:-]+$/, "")}…`;
+}
 export const MAX_LINES_PER_JOB = 120;
 /** How often an answer that does not hold goes back to its agent before the plan falls back. */
 const RETRIES = 2;
@@ -123,6 +137,9 @@ export function groupProblems(specs, answer, maxSpecs = MAX_SPECS_PER_JOB) {
         }
         if (group.title.trim() === "")
             problems.push("Every group needs a title.");
+        else if (group.title.trim().split(/\s+/).length > TITLE_WORDS || group.title.trim().length > TITLE_CHARS) {
+            problems.push(`"${group.title}" is too long for a title: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.`);
+        }
     }
     return problems;
 }
@@ -226,7 +243,8 @@ function draftOf(chunks, net) {
     })
         .filter((entry) => entry.changes.length > 0)
         .map((entry) => ({
-        title: entry.chunk.title,
+        // However the title was made - an agent's, a spec's first line, several joined - it is held to the limit.
+        title: shortTitle(entry.chunk.title),
         reason: entry.chunk.built !== undefined
             ? "what is built already, changed"
             : entry.chunk.specs.length > 0 && entry.chunk.specs.every(regeneratesAgain)
@@ -237,7 +255,7 @@ function draftOf(chunks, net) {
 }
 /** A spec's first line, as a group's title when no agent gave one. */
 function titleOf(change) {
-    return textOf(change).split("\n")[0].replace(/^-\s*/, "").slice(0, 80);
+    return shortTitle(textOf(change).split("\n")[0].replace(/^-\s*/, ""));
 }
 /**
  * Cut the queue's work - from `input.base` to `input.current` - into jobs, as the three steps say. Returns the draft
@@ -245,6 +263,11 @@ function titleOf(change) {
  * the plan did not do as asked - the person's wishes an agent did not follow and why, an answer that did not hold, a
  * group split for its size - for the conversation to say, rather than guess.
  */
+/** A planner agent that failed: the plan falls back, and the ledger says why. */
+function plannerFailed(step, error) {
+    record({ kind: "planner.failed", step, error: firstLine(error instanceof Error ? error.message : String(error), 300) });
+    return undefined;
+}
 export async function planChunks(input, agents, notes) {
     if (input.track !== "conformance")
         return cut(input, agents, notes);
@@ -370,7 +393,7 @@ async function cut(input, agents, notes) {
         ...list.map((group) => ({ title: group.title, specs: group.specs.map((number) => bySpec.get(number)), definitions: [], reqs: [] })),
     ];
     const conformance = input.track === "conformance";
-    const grouped = conformance ? undefined : ((await agents?.group(numbered, (answer) => groupProblems(numbered, answer, maxSpecs), input.steering, maxSpecs).catch(() => undefined)) ?? undefined);
+    const grouped = conformance ? undefined : ((await agents?.group(numbered, (answer) => groupProblems(numbered, answer, maxSpecs), input.steering, maxSpecs).catch((error) => plannerFailed("group", error))) ?? undefined);
     const groups = conformance
         ? conformanceGroups(numbered, input.separately === true, maxLines, (list) => {
             const trial = chunksFor(list);
@@ -386,10 +409,14 @@ async function cut(input, agents, notes) {
     if (grouped?.notes !== undefined && grouped.notes.trim() !== "")
         say(`the grouping: ${grouped.notes.trim()}`);
     if (!conformance && agents !== undefined) {
-        if (grouped === undefined)
+        if (grouped === undefined) {
+            record({ kind: "planner.fellBack", step: "group", why: "no grouping was given" });
             say("the grouping was not given - a functional spec a pulse");
-        else if (groupProblems(numbered, grouped, maxSpecs).length > 0)
+        }
+        else if (groupProblems(numbered, grouped, maxSpecs).length > 0) {
+            record({ kind: "planner.fellBack", step: "group", why: firstLine(groupProblems(numbered, grouped, maxSpecs).join(" "), 300) });
             say(`the grouping did not hold (${groupProblems(numbered, grouped, maxSpecs).join(" ")}) - a functional spec a pulse`);
+        }
     }
     let chunks = chunksFor(groups);
     // 2. The definitions each group uses.
@@ -407,10 +434,12 @@ async function cut(input, agents, notes) {
             implementationReqs: implementationReqs.map((change, index) => ({ number: index + 1, text: textOf(change) })),
             testReqs: testReqs.map((change, index) => ({ number: index + 1, text: textOf(change) })),
         };
-        const answer = (await agents?.place(placeInput, (given) => placeProblems(placeInput, given)).catch(() => undefined)) ?? undefined;
+        const answer = (await agents?.place(placeInput, (given) => placeProblems(placeInput, given)).catch((error) => plannerFailed("place", error))) ?? undefined;
         if (answer?.notes !== undefined && answer.notes.trim() !== "")
             say(`the placement: ${answer.notes.trim()}`);
         placement = answer !== undefined && placeProblems(placeInput, answer).length === 0 ? answer : undefined;
+        if (placement === undefined && agents !== undefined)
+            record({ kind: "planner.fellBack", step: "place", why: answer === undefined ? "no placement was given" : firstLine(placeProblems(placeInput, answer).join(" "), 300) });
         if (placement === undefined && agents !== undefined)
             say("the placement did not hold - every implementation req with the first pulse, every test req with the first conformance pulse");
     }
@@ -458,7 +487,10 @@ async function cut(input, agents, notes) {
             }
             runs.push(run);
             say(`"${group.title}" is past ${maxLines} lines with its definitions and reqs - split into ${runs.length} pulses`);
-            runs.forEach((specs, index) => split.push({ specs, title: specs.length === 1 ? titleOf(bySpec.get(specs[0])) : `${group.title} (${index + 1} of ${runs.length})` }));
+            runs.forEach((specs, index) => split.push({
+                specs,
+                title: specs.length === 1 ? titleOf(bySpec.get(specs[0])) : `${shortTitle(group.title, TITLE_CHARS - 9, TITLE_WORDS - 3)} (${index + 1} of ${runs.length})`,
+            }));
         });
         const before = placement;
         // A req placed with a group that split goes with the first functional spec of it.
@@ -508,7 +540,8 @@ export function groupPrompt(specs, steering, maxSpecs = MAX_SPECS_PER_JOB) {
         "Never group specs only because they are of the same kind.",
         "",
         "Only functional specs next to each other in the same module go together, and they stay in the order given: the",
-        "order is what each is built on. Give each group a short title that says what it builds.",
+        `order is what each is built on. Give each group a title that says what it builds - at most ${TITLE_WORDS} words and ${TITLE_CHARS}`,
+        "characters: it heads the group's pulse where the person watches the work, and a longer one is cut short there.",
         "",
         "The specification is split into modules - a ***plain matter, not how the code is laid out. Each numbers its",
         "functional specs from 1: each below is given with its module and its id there, and a number of its own to answer with.",
@@ -588,9 +621,9 @@ export function llmChunkAgents(options) {
             tool: (take) => defineTool({
                 name: "submit_groups",
                 label: "Submit the groups",
-                description: "The new functional specs in groups, in order: each group's spec numbers and a short title.",
+                description: `The new functional specs in groups, in order: each group's spec numbers and a title of at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.`,
                 parameters: Type.Object({
-                    groups: Type.Array(Type.Object({ specs: Type.Array(Type.Number()), title: Type.String() })),
+                    groups: Type.Array(Type.Object({ specs: Type.Array(Type.Number()), title: Type.String({ description: `What the group builds: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.` }) })),
                     notes: Type.Optional(Type.String({ description: NOTES })),
                 }),
                 async execute(_id, params) {

package/dist/regenerate/conformance-agents.js

@@ -316,9 +316,9 @@ export function createAskExplorerTool(options) {
     return defineTool({
         name: "ask_explorer",
         label: "Ask the explorer",
-        description: "Ask the explorer - who read and ran the code, and wrote the account of it you were given - something the account " +
+        description: "Ask the explorer - who read the code, and wrote the account of it you were given - something the account " +
             "does not say: how a functionality is reached, what a field is called, what the software needs around it. It reads " +
-            `and runs the code to answer. ${options.questions ?? EXPLORER_QUESTIONS} questions a run: ask what reading the code yourself would take long to find.`,
+            `the code to answer - it runs nothing, so what only running the software shows is yours to try. ${options.questions ?? EXPLORER_QUESTIONS} questions a run: ask what reading the code yourself would take long to find.`,
         promptSnippet: "ask_explorer: a question about how the software is reached, answered by the explorer from the code",
         parameters: Type.Object({ question: Type.String({ description: "What you need to know, exactly" }) }),
         async execute(_id, params) {

package/dist/regenerate/conformance.js

@@ -5,7 +5,8 @@ import { PLAIN_SOURCE_FILE_EXTENSION, plainFileParser } from "../plain/parser.js
 import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, getFrids, getInheritedFunctionalSpecs, getSpecificationsForFrid, TEST_REQUIREMENTS, } from "../plain/spec.js";
 import { reportActivity, reportLogNote, reportSpec, reportStage, unitOf } from "./activity.js";
 import { confinedTools } from "./confine.js";
-import { abandonWork, diffSinceSnapshot, moduleDirOf, recordHistory, startWork, workDiff, workSnapshot } from "./lineage.js";
+import { abandonWork, diffSinceSnapshot, landWork, moduleDirOf, startWork, workDiff, workSnapshot } from "./lineage.js";
+import { firstLine, record } from "./ledger.js";
 import { createWorkLedger, describeAccounts, SUBMIT_WORK_NOTE, unanswered, unansweredPrompt } from "./submit-work.js";
 import { CONFORMANCE_COMPACTION } from "./compaction.js";
 import { NOTES_TURN, notesForSession, passedOutcome, readNotes, reflectOnReview, withNotes } from "./notes.js";
@@ -417,6 +418,7 @@ export async function renderConformanceTests(options) {
             // every functionality's tests - and the code's unit testing script.
             stage(`running the conformance testing script on the whole suite (attempt ${rounds + 1} of ${maxRounds})`);
             rounds += 1;
+            record({ kind: "gate.round", gate: "conformance", round: rounds, of: maxRounds });
             let recheck = await runConformanceScript(buildDir, [conformanceDir], scripts);
             runs.push({ command: recheck.command, exitCode: recheck.exitCode });
             options.onRun?.(recheck.command, recheck.exitCode);
@@ -537,6 +539,7 @@ export async function renderConformanceTests(options) {
                     onDelta: options.onDelta,
                 });
                 const reason = verdict.reason.split("\n")[0].slice(0, 160);
+                record({ kind: "judge.verdict", culprit: verdict.culprit, round: rounds, reason: firstLine(verdict.reason, 300) });
                 // Stopped by the time limit while it was still getting on: no agent can give it more time. The pulse stops now -
                 // rolled back, no retry - and the person is told how to raise the limit.
                 if (verdict.culprit === "environment" && recheck.timedOut === true) {
@@ -797,9 +800,9 @@ export async function renderConformanceTests(options) {
             // The tests, and the code when it changed: one commit if they share a module folder.
             const subject = `conformance ${moduleName} ${options.diff !== undefined ? "for a spec change" : `fs ${frid}`}${changed ? " (code changed)" : ""}`;
             stage(`committing the conformance tests${changed ? " and the code changes" : ""}`);
-            recordHistory(conformanceDir, subject);
+            landWork(conformanceDir, subject);
             if (moduleDirOf(buildDir) !== moduleDirOf(conformanceDir))
-                recordHistory(buildDir, subject);
+                landWork(buildDir, subject);
         }
         else if (start !== undefined) {
             const why = notLandedWhy(options.diff !== undefined ? "for the spec change" : `of functionality ${frid}`, unlabelled);

package/dist/regenerate/debug-log.d.ts

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

package/dist/regenerate/debug-log.js

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