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

package/README.md

@@ -152,7 +152,7 @@ It asks you about the problem, the stack and the product, writes \*\*\*plain, an
 
 - 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;

package/dist/cli.js

@@ -97,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}`),
@@ -110,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) {
@@ -122,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);
     }

package/dist/config-edit.js

@@ -76,6 +76,8 @@ 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

@@ -265,6 +265,18 @@ export interface ProjectConfig {
      * 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. */
@@ -294,6 +306,8 @@ export declare const CONFIG_KEYS: {
     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";
 };
@@ -316,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

@@ -380,6 +380,8 @@ export const CONFIG_KEYS = {
     agentEnv: "agent-env",
     toolchains: "toolchains",
     ledgerKeep: "ledger-keep",
+    debug: "debug",
+    cacheKeep: "cache-keep",
     models: "models",
     turnLimit: "turn-limit",
 };
@@ -432,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 === "ledgerKeep" || 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];
     }
@@ -444,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 };
@@ -546,6 +565,10 @@ function readConfigFile(path) {
         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/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";

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";

package/dist/init-config.d.ts

@@ -67,6 +67,8 @@ export declare const DEFAULTS: {
     readonly maxSpecsPerPulse: 3;
     readonly maxLinesPerPulse: 120;
     readonly ledgerKeep: 100;
+    readonly debug: false;
+    readonly cacheKeep: 4096;
 };
 /** 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

@@ -119,6 +119,8 @@ export const DEFAULTS = {
     maxSpecsPerPulse: 3,
     maxLinesPerPulse: 120,
     ledgerKeep: 100,
+    debug: false,
+    cacheKeep: 4096,
 };
 /** 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()) {
@@ -188,6 +190,14 @@ export function quickStartConfig(vendor = "other", bedrock) {
         "# the oldest runs' are pruned. 0 keeps none.",
         `ledger-keep: ${DEFAULTS.ledgerKeep}`,
         "",
+        "# Megabytes of package caches - npm's, pip's, Maven's... in plain_modules/.turri/cache - the project keeps; past it,",
+        "# the least recently written are removed. 0 keeps none.",
+        `cache-keep: ${DEFAULTS.cacheKeep}`,
+        "",
+        "# Whether turri keeps what it writes for debugging it: every agent's whole log and session, each pulse's log, the",
+        "# test runs' outputs, the agents' temporary files. Off, only what turri reads to work is kept. TURRI_DEBUG=1 for one run.",
+        `debug: ${DEFAULTS.debug}`,
+        "",
         "# 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-tools.js

@@ -21,7 +21,7 @@ export function ledgerTool(options) {
             "how each ended, how long, what it cost. Starts nothing and calls no model.",
         promptSnippet: "ledger: what turri did - a pulse as facts, the last runs, or events counted by kind - this session and earlier ones",
         promptGuidelines: [
-            "Use ledger for what turri recorded of the work - a pulse's rounds, test runs, verdicts, healers and commits, this session's or an earlier one's; how often something happened; what earlier runs did and cost - rather than reading .turri/ledger with the shell. pulses is what is running and planned now; a pulse's whole transcript is its log, which ledger names.",
+            "Use ledger for what turri recorded of the work - a pulse's rounds, test runs, verdicts, healers and commits, this session's or an earlier one's; how often something happened; what earlier runs did and cost - rather than reading .turri/ledger with the shell. pulses is what is running and planned now; a pulse's whole transcript is its log, which ledger names when it is kept (debug mode).",
         ],
         parameters: Type.Object({
             pulse: Type.Optional(Type.String({ description: "A pulse's id, or the start of it: that pulse, as the ledger has it" })),

package/dist/pi.d.ts

@@ -184,6 +184,8 @@ export declare function createExecutor(opts: {
     rules?: boolean;
     /** Continue the session saved in this file, instead of starting a new one. */
     resumeFrom?: string;
+    /** Save its session to disk, debug mode or not: it is picked back up later (a skill's run, resumed). */
+    saveSession?: boolean;
     /** Added to its system prompt: its sandbox, above all - what it can reach (see confine.ts sandboxNote). */
     system?: string;
     /**

package/dist/pi.js

@@ -2,7 +2,7 @@ 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";
@@ -753,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/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/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

package/dist/regenerate/chunk-plan.js

@@ -71,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;
@@ -124,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;
 }
@@ -227,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)
@@ -238,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
@@ -470,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.
@@ -520,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.",
@@ -600,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/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)}`);

package/dist/regenerate/diagnose.js

@@ -1,6 +1,7 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { ask, BEGIN, createExecutor } from "../pi.js";
+import { debugMode } from "../config.js";
 import { confinedTools } from "./confine.js";
 /** How many tool calls the diagnosis may make before it is told to decide. */
 export const DIAGNOSIS_CALLS = 40;
@@ -77,6 +78,13 @@ export function diagnosisPrompt(options) {
         "Find the root cause, not the last symptom: read the failing run's output and the agents' logs around where it",
         "failed, and follow it to the spec line, the code, the test, the environment or the harness it comes from. Then",
         "call submit_diagnosis: what happened, why, whose it is to fix, and exactly what to do.",
+        ...(debugMode(options.projectDir)
+            ? []
+            : [
+                "",
+                "The logs and the full outputs are removed as the job ends - the project is not in debug mode - so never send",
+                "the person to one of them: quote what in them shows the cause.",
+            ]),
         "",
         ...options.failures.flatMap((failure, index) => [`<attempt ${index + 1}>`, failure.trim().slice(-12_000), `</attempt ${index + 1}>`, ""]),
     ].join("\n");

package/dist/regenerate/jobs.js

@@ -5,7 +5,8 @@ import { describeEnvironmentError, EnvironmentError, missingCredentials } from "
 import { addAgentReport, describeAgents, JobStoppedError, withActivity } from "./activity.js";
 import { projectOfLanes, startJobLog } from "./job-log.js";
 import { firstLine, healing, record } from "./ledger.js";
-import { chosenStack, withStack } from "../config.js";
+import { chosenStack, debugMode, withStack } from "../config.js";
+import { pulseEnded, pulseWrote } from "./pulse-files.js";
 const DEFAULT_TAIL_CHARS = 4000;
 const ACTIVITY_LINES = 10;
 /** A long render's full transcript is kept, up to about this much text. */
@@ -261,6 +262,8 @@ export function createJobRegistry(options) {
             };
             /** It holds one of the run slots, to give back when it ends. */
             let holding = false;
+            /** It started, holding its lanes: what it wrote, and what its chain installed, are its to clear as it ends. */
+            let ran = false;
             const promise = turn
                 .then(async () => {
                 // Stopped while it waited: it never starts.
@@ -295,9 +298,14 @@ export function createJobRegistry(options) {
                     changed();
                 }
                 log = startJobLog(job, claimed);
-                if (log !== undefined)
+                ran = true;
+                if (log !== undefined) {
                     job.logFile = log.file;
-                record({ kind: "job.started", waitedMs: job.startedAt - job.queuedAt, ...(log !== undefined ? { logFile: log.file } : {}) }, place);
+                    pulseWrote(log.file, id);
+                }
+                // Its log is named only where it is kept: otherwise it goes as the pulse ends.
+                const named = log !== undefined && project !== undefined && debugMode(project);
+                record({ kind: "job.started", waitedMs: job.startedAt - job.queuedAt, ...(named ? { logFile: log.file } : {}) }, place);
                 // What the job's agents start runs until it ends, and no longer (withPulse) - with the stack it was queued
                 // with, whatever is chosen while it waits or runs.
                 return withStack(stack, () => (guarded ? runGuarded() : runOnce()));
@@ -323,6 +331,10 @@ export function createJobRegistry(options) {
                     giveSlot();
                 }
                 finished.finishedAt = Date.now();
+                log?.end(finished.status === "succeeded" ? "finished" : finished.status === "stopped" ? "stopped" : "finished - failed", finished.announce ?? finished.report ?? finished.error, describeAgents(finished.agents));
+                // What it wrote for a person goes now, outside debug mode - its log too, which nothing names from then on.
+                if (ran && project !== undefined && !pulseEnded({ job: id, project, ...(input.module !== undefined ? { module: input.module } : {}), lanes: claimed }))
+                    delete finished.logFile;
                 const outcome = finished.details;
                 const stopReason = stopReasons.get(id);
                 record({
@@ -337,7 +349,6 @@ export function createJobRegistry(options) {
                     ...(finished.error !== undefined ? { error: firstLine(finished.error, 300) } : {}),
                     ...(finished.logFile !== undefined ? { logFile: finished.logFile } : {}),
                 }, place);
-                log?.end(finished.status === "succeeded" ? "finished" : finished.status === "stopped" ? "stopped" : "finished - failed", finished.announce ?? finished.report ?? finished.error, describeAgents(finished.agents));
                 // A failing listener must not take the job down with it; the result is
                 // already recorded and can still be collected by asking.
                 try {

package/dist/regenerate/pulse-files.d.ts

@@ -0,0 +1,14 @@
+/** A file the running pulse wrote for a person to read - removed as it ends, unless in debug mode. Outside a pulse, nothing. */
+export declare function pulseWrote(file: string, job?: string | undefined): void;
+/**
+ * A pulse has ended. Unless the project is in debug mode, what it wrote for a person goes - its files, and its module's
+ * temporary folder - and so do the dependencies installed in the modules below its own in its chain. `lanes` are the
+ * pulse's (`plain_modules/<module>` of its whole chain), still held: no other pulse works in them. Returns whether
+ * everything was kept.
+ */
+export declare function pulseEnded(options: {
+    job: string;
+    project: string;
+    module?: string;
+    lanes: string[];
+}): boolean;

package/dist/regenerate/pulse-files.js

@@ -0,0 +1,63 @@
+import { existsSync, rmSync } from "node:fs";
+import { basename, join } from "node:path";
+import { debugMode } from "../config.js";
+import { currentJob } from "./activity.js";
+import { modulesScratchDir } from "./paths.js";
+/**
+ * What a pulse writes only for a person debugging turri, and when it goes.
+ *
+ * A pulse writes its own log, every one of its agents' whole logs, the testing scripts' and services' full outputs and
+ * its agents' temporary files. Nothing of turri reads them once the pulse is over: while it runs, its agents read their
+ * outputs (`read_output`, `service_logs`) and the diagnosis of a failure reads the logs - so they are written as before,
+ * and removed as it ends. In debug mode (`debug: true`, TURRI_DEBUG, `--debug`) they are kept, as they always were.
+ *
+ * So are the dependencies installed in the modules below a pulse's own in its chain: the chain is built in its tip, and
+ * what was installed in the codebases it left behind is only installed again - from the package cache - if one of them
+ * is ever built on again. The testing scripts install what they run with themselves.
+ */
+/** The files each pulse wrote for a person to read, by its id. */
+const written = new Map();
+/** A file the running pulse wrote for a person to read - removed as it ends, unless in debug mode. Outside a pulse, nothing. */
+export function pulseWrote(file, job = currentJob()?.id) {
+    if (job === undefined)
+        return;
+    const files = written.get(job) ?? new Set();
+    files.add(file);
+    written.set(job, files);
+}
+/** Where a codebase's dependencies are installed: what a module its chain has left behind keeps no longer. */
+const INSTALLED = ["node_modules", ".venv", "venv"];
+/**
+ * A pulse has ended. Unless the project is in debug mode, what it wrote for a person goes - its files, and its module's
+ * temporary folder - and so do the dependencies installed in the modules below its own in its chain. `lanes` are the
+ * pulse's (`plain_modules/<module>` of its whole chain), still held: no other pulse works in them. Returns whether
+ * everything was kept.
+ */
+export function pulseEnded(options) {
+    const files = written.get(options.job) ?? new Set();
+    written.delete(options.job);
+    if (debugMode(options.project))
+        return true;
+    const gone = (path) => {
+        try {
+            rmSync(path, { recursive: true, force: true });
+        }
+        catch {
+            /* what cannot be removed stays: never a reason for the pulse to fail */
+        }
+    };
+    for (const file of files)
+        gone(file);
+    for (const lane of options.lanes) {
+        // A codebase of the chain: its folder holds `code` - a lane may also be a spec file, or a build folder.
+        if (!existsSync(join(lane, "code")))
+            continue;
+        const name = basename(lane);
+        if (name === options.module)
+            gone(join(modulesScratchDir(lane), "tmp", name));
+        else
+            for (const installed of INSTALLED)
+                gone(join(lane, "code", installed));
+    }
+    return false;
+}

package/dist/regenerate/services.js

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

package/dist/regenerate/testing.js

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

package/dist/run-report.js

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

package/docs/config.md

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

package/docs/development.md

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

package/docs/headless.md

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

package/docs/hosting.md

@@ -11,6 +11,7 @@
 | `createTurriExtension(host)` | turri's conversation as an extension of pi's: every tool, slash command, rule and skill the terminal has. The host is told of its jobs and asks its questions - see below. |
 | `pi` | pi itself, as turri's extension is built against it. Make the session with this one - `pi.createAgentSession`, `pi.DefaultResourceLoader` - not another copy. |
 | `readProjectConfig`, `projectModels`, `modelSpec`, `configForSpec`, `hasProjectConfig`, `stacksOf` | the project's settings, as [config.turri.yaml](config.md) has them. |
+| `debugMode` | whether turri keeps, in a project, what it writes only for debugging it - `debug:`, or `TURRI_DEBUG` over it (see [debug mode](config.md#debug-mode)). |
 | `initConfig(dir, { vendor, bedrock, force })`, `VENDORS`, `BEDROCK_REGIONS`, `BEDROCK_DEFAULT`, `bedrockModels` | a project's first config.turri.yaml, as `turri init-config` writes it: the host asks which vendor's models - `VENDORS` has each one's label and its two models, `BEDROCK_REGIONS` where Bedrock serves each maker's - and `initConfig` writes it, saying what it did. One already there keeps everything but its two models. |
 | `checkPlainFile`, `plainFileParser`, `resolveTemplateDirs`, `iterateFunctionalSpecs`, `FUNCTIONAL_REQUIREMENTS` | a spec checked and parsed, its functional specs one by one - as `turri validate` reads it. |
 | `highlightLines`, `roleOf` | a spec's lines coloured by turri's own \*\*\*plain grammar. |

package/docs/regenerating.md

@@ -33,12 +33,12 @@ The harness's scratch - each ignores itself, and is never part of a module's his
 | | |
 | --- | --- |
 | `plain_modules/.turri/` | what turri keeps beside the code - see [sandbox](sandbox.md#what-turri-keeps-beside-the-code) |
-| `plain_modules/.turri/cache/` | the package caches, so a dependency is fetched once |
+| `plain_modules/.turri/cache/` | the package caches, so a dependency is fetched once - held to `cache-keep:` |
 | `plain_modules/.turri/scripts/` | the copies each testing script run happens in, one folder a run |
-| `plain_modules/.turri/logs/` | the whole output of each run or command an agent was shown cut short, by time and what ran - read by agents only through `read_output` |
-| `.turri/jobs/` | each job's log: its diff, its stages, its agents and what they cost, and which walls were up under its agents' commands |
-| `.turri/debug/` | each agent's log: its prompt, every tool call and every answer |
-| `.turri/sessions/` | the agents' saved sessions |
+| `plain_modules/.turri/logs/` | the whole output of each run or command an agent was shown cut short, by time and what ran - read by agents only through `read_output`; removed as the pulse ends, outside [debug mode](config.md#debug-mode) |
+| `.turri/jobs/` | each job's log: its diff, its stages, its agents and what they cost, and which walls were up under its agents' commands - kept in debug mode only |
+| `.turri/debug/` | each agent's log: its prompt, every tool call and every answer - kept in debug mode only |
+| `.turri/sessions/` | the agents' saved sessions - in debug mode, and a gated skill's run's |
 | `.turri/runs/<skill>/` | a gated skill's run: what an interrupted one resumes from, and its gates' evidence |
 | `.turri/deploy/` | the output of what `deploy` started |
 | `dist/<module>/` | what `deploy` puts out: the module's code as its last commit has it, replaced whole each time - see [deploy](deploy.md) |
@@ -411,7 +411,7 @@ The agents that work through a job keep **one session for it**: the coding agent
 
 An agent kept through a job re-reads everything it has done on every call. So between turns, once its conversation - what it has done, past its instructions - passes `compact-at` tokens (100,000 unless [the project config](config.md) says otherwise), the harness compacts it, with instructions for its role: the coding agent and the fixer keep what is done, what still fails and why, the decisions and every review problem's fate; a reviewer keeps every problem it raised and where each stands, and what it has already checked. pi's own compaction, when the context window is nearly full, stays on beneath it.
 
-What each agent of a job did - its turns, its compactions, its tokens and cost - is at the end of the job's log in `.turri/jobs/`, and in `pulses`.
+What each agent of a job did - its turns, its compactions, its tokens and cost - is at the end of the job's log in `.turri/jobs/` (kept in [debug mode](config.md#debug-mode)), and in `pulses`.
 
 ## Working notes
 

package/docs/sandbox.md

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

package/docs/using.md

@@ -162,14 +162,16 @@ git --git-dir=plain_modules/<module>/.plaingit --work-tree=plain_modules/<module
 
 ## Agent logs
 
-When an agent does something you cannot explain, its logs are where to look: the chat shows what its pulse is doing, not what its agents said. Every agent a render starts - the coding agent, the conformance agent, the repair agent, the spec-steps planner - also streams its whole conversation to a file of its own, always.
+When an agent does something you cannot explain, its logs are where to look: the chat shows what its pulse is doing, not what its agents said. Every agent a render starts - the coding agent, the conformance agent, the repair agent, the spec-steps planner - also streams its whole conversation to a file of its own.
 
 The logs are in `.turri/debug/` in the project, beside `plain_modules`, one per agent, named by when it started and what it is: `2026-09-26T13-45-02-123Z-app-3-coding-agent.log`. Each starts with the pulse it runs for, its model and thinking level, its folder, its saved pi session, its tools and its system prompt, and then has, in order and stamped with the time: every prompt it is sent, whole; its thinking and replies as they stream; every tool call with its arguments, numbered
 - `→ #3 bash` - and its whole result under the same number, `← #3 bash done`, since calls made together run at once and finish in any order; a tool call a response was cut off in, marked as never run; each response's stop reason, tokens and cost; the provider's retries and errors; and how each turn ended. Every line is on disk as it happens, so `tail -f` follows an agent live and a run that crashed leaves its log up to that moment. The pulse's own log names each agent's log as it starts.
 
 Beside them, each pulse has a log of its own in `.turri/jobs/` - `<time>-<pulse id>-<kind>.log`: its whole transcript, written as it happens. The harness's stages, the functional spec or the diff it builds, and every one of its agents in turn - each prompt, its thinking and replies, every tool call and its result, whole where the screen clips them - and how the pulse ended. A finished pulse, opened in the side panel, names it. It is the one to read for a pulse as a whole; an agent's own log has its system prompt, tokens and retries besides.
 
-No agent can read the logs: they are outside `plain_modules` - or, for a `--build-dir` outside it, beside that folder rather than in it. Nothing prunes them either - delete the folder when you are done with it. A log that cannot be written is given up on without failing the render.
+They are kept only in [debug mode](config.md#debug-mode) - `debug: true` in `config.turri.yaml`, or `TURRI_DEBUG=1`, or `turri --debug` for one run. Otherwise a pulse's logs are written while it runs - the diagnosis of a pulse that fails twice reads them, and quotes what it needs, never sending you to a file that is about to go - and removed as it ends, and an agent outside a pulse writes none; the [ledger](#the-ledger) still says what each pulse did, how it ended and what it cost. To read why an agent did something, turn debug mode on and run it again.
+
+The coding and conformance agents cannot read the logs: they are outside `plain_modules` - or, for a `--build-dir` outside it, beside that folder rather than in it. The diagnosis of a failed pulse reads them. In debug mode nothing prunes them - delete the folder when you are done with it. A log that cannot be written is given up on without failing the render.
 
 ## The ledger
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.8-next.bfcb24e",
+  "version": "0.1.8",
   "license": "MIT",
   "type": "module",
   "repository": {