@turri-dev/cli 0.2.0 → 0.2.1-next.47b578c

package/dist/model-check.d.ts

@@ -10,6 +10,8 @@ import { type ProjectConfig } from "./config.ts";
 export interface UsedModel {
     spec: string;
     usedBy: string[];
+    /** How hard it thinks, as the first setting naming it says - none written, as the agents run it: low at least. */
+    thinking?: string;
 }
 /** Every model the config uses, each once, with the settings that name it - the two models first. */
 export declare function modelsInUse(config: Pick<ProjectConfig, "harnessModel" | "codingModel" | "judgeModel" | "models">): UsedModel[];
@@ -31,8 +33,8 @@ export interface ModelAccess {
     find(provider: string, id: string): unknown;
     /** Other models of the provider pi knows, to suggest from. */
     known(provider: string): string[];
-    /** One short request: the error the provider gave, or nothing when it answered. */
-    ask(model: unknown): Promise<string | undefined>;
+    /** One short request, thinking as hard as `thinking` says: the error the provider gave, or nothing when it answered. */
+    ask(model: unknown, thinking?: string): Promise<string | undefined>;
 }
 /** A model in pi's catalogue: what turri chooses among, and checks a model it is given against. */
 export interface CatalogueModel {

package/dist/model-check.js

@@ -1,31 +1,37 @@
-import { join } from "node:path";
-import { getAgentDir, ModelRegistry, ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { EXTENSION_PROVIDERS, installedProviders, runtimeWithProviders } from "./installed-providers.js";
 import { AGENT_ROLES, projectModels, roleModel } from "./config.js";
 /** Every model the config uses, each once, with the settings that name it - the two models first. */
 export function modelsInUse(config) {
     const used = new Map();
-    const add = (spec, by) => {
+    const thinking = new Map();
+    const add = (choice, by) => {
+        const spec = choice?.model;
         if (spec === undefined)
             return;
         used.set(spec, [...(used.get(spec) ?? []), by]);
+        if (!thinking.has(spec) && choice?.thinking !== undefined)
+            thinking.set(spec, choice.thinking);
     };
     const { harness, coding } = projectModels(config);
-    add(harness?.model, "harness-model");
-    add(coding?.model, "coding-model");
-    add(config.judgeModel?.model, "judge-model");
+    add(harness, "harness-model");
+    add(coding, "coding-model");
+    add(config.judgeModel, "judge-model");
     // A role named under models: runs on its own model - or what it inherits, when its entry names only how it thinks.
     for (const role of AGENT_ROLES) {
         if (config.models?.[role] === undefined || role === "chat" || role === "coding")
             continue;
-        add(roleModel(config, role)?.model, `models.${role}`);
+        add(roleModel(config, role), `models.${role}`);
     }
-    add(config.models?.default?.model, "models.default");
-    return [...used].map(([spec, usedBy]) => ({ spec, usedBy: [...new Set(usedBy)] }));
+    add(config.models?.default, "models.default");
+    return [...used].map(([spec, usedBy]) => ({ spec, usedBy: [...new Set(usedBy)], ...(thinking.has(spec) ? { thinking: thinking.get(spec) } : {}) }));
 }
-/** pi's own model runtime: its catalogue with models.json's, and pi's credentials - auth.json and the environment. */
+/**
+ * pi's own model runtime: its catalogue with models.json's, pi's credentials - auth.json and the environment - and the
+ * providers the person's installed pi extensions register (installed-providers.ts), as turri's agents have them.
+ */
 async function piRuntime() {
-    const agentDir = getAgentDir();
-    return ModelRuntime.create({ authPath: join(agentDir, "auth.json"), modelsPath: join(agentDir, "models.json") });
+    return runtimeWithProviders(await installedProviders());
 }
 /** pi's catalogue, read once: no request, no model asked. */
 export async function piModelCatalogue() {
@@ -67,9 +73,12 @@ export async function piModelAccess() {
     return {
         find: (provider, id) => registry.find(provider, id),
         known: (provider) => runtime.getModels(provider).map((model) => model.id),
-        async ask(model) {
+        async ask(model, thinking) {
+            // As the agents ask it: thinking as the config says - some models refuse a request with none, Claude Code's among
+            // them - with room for the thinking before the word.
+            const reasoning = thinking !== undefined && thinking !== "off" && model.reasoning === true ? thinking : undefined;
             try {
-                const reply = await runtime.completeSimple(model, { messages: [{ role: "user", content: "Reply with the one word: ok", timestamp: Date.now() }] }, { maxTokens: 64, signal: AbortSignal.timeout(60_000) });
+                const reply = await runtime.completeSimple(model, { messages: [{ role: "user", content: "Reply with the one word: ok", timestamp: Date.now() }] }, { maxTokens: reasoning !== undefined ? 2048 : 64, ...(reasoning !== undefined ? { reasoning: reasoning } : {}), signal: AbortSignal.timeout(60_000) });
                 return reply.stopReason === "error" || reply.stopReason === "aborted" ? (reply.errorMessage ?? `the request ended: ${reply.stopReason}`) : undefined;
             }
             catch (error) {
@@ -85,6 +94,7 @@ function signIn(provider) {
         openai: "OPENAI_API_KEY, or /login in turri",
         google: "GEMINI_API_KEY",
         "amazon-bedrock": "AWS_PROFILE (aws configure, or aws sso login) or AWS_BEARER_TOKEN_BEDROCK",
+        ...Object.fromEntries(Object.entries(EXTENSION_PROVIDERS).map(([id, provider]) => [id, provider.signIn])),
     };
     return keys[provider] ?? `the key pi reads for ${provider}, or /login in turri - https://pi.dev lists them`;
 }
@@ -123,7 +133,7 @@ function commonPrefix(a, b) {
 }
 /** Each model the config uses, tried: answered, or what is wrong and what to do. One request a model. */
 export async function checkModels(models, access, options = {}) {
-    return Promise.all(models.map(async ({ spec, usedBy }) => {
+    return Promise.all(models.map(async ({ spec, usedBy, thinking }) => {
         const slash = spec.indexOf("/");
         if (slash === -1)
             return { ok: false, spec, usedBy, problem: "not provider/model-id", fix: "write it as provider/model-id - amazon-bedrock/global.openai.gpt-6-astra" };
@@ -131,13 +141,19 @@ export async function checkModels(models, access, options = {}) {
         const model = access.find(provider, id);
         if (model === undefined) {
             const known = access.known(provider);
-            if (known.length === 0)
+            if (known.length === 0) {
+                // A provider an extension brings: its extension is not installed - or, installed, not ready.
+                const extension = EXTENSION_PROVIDERS[provider];
+                if (extension !== undefined)
+                    return { ok: false, spec, usedBy, problem: `${provider} - ${extension.label} - is not there`, fix: `install its pi extension: ${extension.install} - with ${extension.signIn}` };
                 return { ok: false, spec, usedBy, problem: `pi knows no provider ${provider}`, fix: "use a provider pi supports - https://pi.dev" };
+            }
             const close = closestModels(id, known);
             return { ok: false, spec, usedBy, problem: `pi knows no model ${id} at ${provider}`, fix: close.length > 0 ? `did you mean ${close.map((other) => `${provider}/${other}`).join(", ")}?` : `change it in config.turri.yaml to a model pi knows at ${provider}` };
         }
         const started = Date.now();
-        const problem = await access.ask(model);
+        // How the agents run it: as the config says, else low - a role's own default is at least that.
+        const problem = await access.ask(model, thinking ?? "low");
         if (problem === undefined)
             return { ok: true, spec, usedBy, ms: Date.now() - started };
         const said = problem.split("\n").find((line) => line.trim() !== "")?.trim().slice(0, 300) ?? problem;

package/dist/notice.d.ts

@@ -15,9 +15,11 @@ export interface NoticeAction {
 export interface NoticeInput {
     /**
      * `sentinel-start`: not something wrong but a question turri puts before the sentinel first opens in a session - its
-     * actions start it, or not, and are turri's to carry out, not the chat's agent's (SENTINEL_START). None: the sentinel's.
+     * actions start it, or not, and are turri's to carry out, not the chat's agent's (SENTINEL_START). `fixed`: the
+     * sentinel says what it fixed itself in the project's tooling - a testing script, its config - with nothing to answer:
+     * a note, never put as a question, and never superseding a notice about its module. None: the sentinel's.
      */
-    kind?: "sentinel-start";
+    kind?: "sentinel-start" | "fixed";
     severity: NoticeSeverity;
     /** What is wrong, in a line. */
     summary: string;
@@ -29,6 +31,8 @@ export interface NoticeInput {
     job?: string;
     /** Its number among its module's pulses. */
     pulse?: number;
+    /** The check it is about, when a host asked the sentinel to check functional specs (`SentinelCheck`): its id. */
+    check?: string;
     /**
      * The person may leave it as the build has it, for good (`{ ignore: true }`): a gap in the ***plain the build settled
      * with an assumption - never something broken, a pulse that went wrong, a release that did not come up, nor the
@@ -79,12 +83,32 @@ export declare function ignoredGuidance(notice: Notice): string;
 export declare function describeNotice(notice: NoticeInput): string;
 /** Whether a pulse went wrong: failed, stopped, or ran to its end with what it built not passing. */
 export declare function wentWrong(job: Job): boolean;
-/** The sentinel done with a pulse: whether what it checked holds, and what it checked and found, in a line or two. */
+/**
+ * The sentinel done with a pulse - or a check a host asked for: whether what it checked holds, and what it checked and
+ * found, in a line or two. `unchecked`: a check that never ran - the person did not start the sentinel, or it could not
+ * be opened - turri's own word, never the sentinel's.
+ */
 export interface Conclusion {
-    /** The pulse: its job id. */
-    job: string;
-    verdict: "holds" | "wrong";
+    /** The pulse: its job id. Undefined for a check. */
+    job?: string;
+    /** The check: its id (`SentinelCheck`). Undefined for a pulse. */
+    check?: string;
+    verdict: "holds" | "wrong" | "unchecked";
     summary: string;
     module?: string;
     pulse?: number;
 }
+/**
+ * Functional specs of a module a host asked the sentinel to check, in the module's release: its last commit, released,
+ * and every module its requires chain builds on with it. Queued with the pulses, in a conversation of its own.
+ */
+export interface SentinelCheck {
+    id: string;
+    /** The module released and tested, by name. */
+    module: string;
+    plainFile: string;
+    /** The functional specs to test, each `module:func-id` - of the module, or of a module its requires chain builds on. */
+    funcIds: string[];
+    /** When it was asked for. */
+    at: string;
+}

package/dist/pi.js

@@ -1,6 +1,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 { createAgentSession, DefaultResourceLoader, getAgentDir, ModelRegistry, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { installedProviders, runtimeWithProviders } from "./installed-providers.js";
 import { loadRules, renderRulesBlock } from "./rules.js";
 import { debugMode, inheritModel, stackOf, readProjectConfig, ROLE_THINKING, roleModel, roleTurnLimitMs, splitModelSpec } from "./config.js";
 import { maskToolResults } from "./regenerate/masking.js";
@@ -53,36 +54,19 @@ let providerSource;
 export function inheritProviders(source) {
     providerSource = source;
 }
-/** A model runtime for a sub-agent: pi's configuration, with the providers the conversation's extensions registered. */
+/**
+ * A model runtime for a sub-agent: pi's configuration, with the providers the conversation's extensions registered - or,
+ * with no conversation to take them from (a command run headless), those the person's installed pi extensions register.
+ */
 async function subAgentModelRuntime() {
-    const agentDir = getAgentDir();
-    const runtime = await ModelRuntime.create({ authPath: join(agentDir, "auth.json"), modelsPath: join(agentDir, "models.json") });
     let source;
     try {
         source = providerSource?.();
     }
     catch {
-        // The conversation it came from is gone: pi's own configuration is what there is.
-    }
-    if (source === undefined)
-        return runtime;
-    const registry = new ModelRegistry(runtime);
-    for (const id of source.getRegisteredProviderIds()) {
-        const native = source.getRegisteredNativeProvider(id);
-        const config = source.getRegisteredProviderConfig(id);
-        try {
-            if (native !== undefined)
-                registry.registerProvider(native);
-            else if (config !== undefined)
-                registry.registerProvider(id, config);
-        }
-        catch {
-            // One provider that will not register leaves the others, and pi's own, usable.
-        }
+        // The conversation it came from is gone: the installed ones, then.
     }
-    // Its models are listed as the registrations land; the agent's model is looked up right after.
-    await runtime.refresh({ allowNetwork: false });
-    return runtime;
+    return runtimeWithProviders(source ?? (await installedProviders()));
 }
 const RULES_DIR = join(dirname(dirname(fileURLToPath(import.meta.url))), "genome", "rules");
 /**

package/dist/plain/files.d.ts

@@ -2,6 +2,21 @@
 export declare function openFrom(dirs: string[], fileName: string): string | null;
 /** The file `openFrom` reads: the first of the folders that has it. */
 export declare function findIn(dirs: string[], fileName: string): string | null;
+/** Whether there is a file at `path` - looked for as `findIn` looks, and noted as it is. */
+export declare function isFile(path: string): boolean;
+declare const FOUND: unique symbol;
+declare const MISSING: unique symbol;
+/** What a parse read, while `noteReads` runs: each file it looked for - its text, there, or not there. */
+export type Reads = Map<string, string | typeof FOUND | typeof MISSING>;
+/** `run`, with every file it looked for and read through these helpers noted - an inner run's in the outer's too. */
+export declare function noteReads<T>(run: () => T): {
+    value: T;
+    reads: Reads;
+};
+/** Reads made before - a kept result's - counted in the run noting now, as if made again. */
+export declare function addReads(into: Reads | undefined, reads: Reads): void;
+/** Whether each file noted is still as it was: the same text, still there, still not there. */
+export declare function readsHold(reads: Reads): boolean;
 /**
  * Port of loaders.relative_resource_path: the path of `target` in `resourceDir`, relative to `baseDir`, with `/` as
  * separator. The folder part is computed lexically and the target is appended as written (`..` kept), so joining
@@ -29,3 +44,4 @@ export declare function liquidErrorMessage(error: Error & {
         input?: string;
     };
 }, templateName?: string): string;
+export {};

package/dist/plain/files.js

@@ -6,21 +6,84 @@ import { createEnvironment } from "./liquid.js";
 /** Ports of the Python reference implementation's file helpers this parser needs. */
 export function openFrom(dirs, fileName) {
     const path = findIn(dirs, fileName);
-    return path === null ? null : readFileSync(path, "utf8");
+    if (path === null)
+        return null;
+    const text = readFileSync(path, "utf8");
+    noted?.set(resolve(path), text);
+    return text;
 }
 /** The file `openFrom` reads: the first of the folders that has it. */
 export function findIn(dirs, fileName) {
     for (const dir of dirs) {
         const fullPath = join(dir, fileName);
+        if (isFile(fullPath))
+            return fullPath;
+    }
+    return null;
+}
+/** Whether there is a file at `path` - looked for as `findIn` looks, and noted as it is. */
+export function isFile(path) {
+    let found;
+    try {
+        found = statSync(path).isFile();
+    }
+    catch {
+        found = false;
+    }
+    const at = resolve(path);
+    if (noted !== undefined && !noted.has(at))
+        noted.set(at, found ? FOUND : MISSING);
+    return found;
+}
+const FOUND = Symbol("found");
+const MISSING = Symbol("missing");
+let noted;
+/** `run`, with every file it looked for and read through these helpers noted - an inner run's in the outer's too. */
+export function noteReads(run) {
+    const outer = noted;
+    const mine = new Map();
+    noted = mine;
+    try {
+        return { value: run(), reads: mine };
+    }
+    finally {
+        noted = outer;
+        if (outer !== undefined)
+            addReads(outer, mine);
+    }
+}
+/** Reads made before - a kept result's - counted in the run noting now, as if made again. */
+export function addReads(into = noted, reads) {
+    if (into === undefined)
+        return;
+    for (const [path, what] of reads)
+        if (!into.has(path) || typeof what === "string")
+            into.set(path, what);
+}
+/** Whether each file noted is still as it was: the same text, still there, still not there. */
+export function readsHold(reads) {
+    for (const [path, was] of reads) {
+        if (typeof was === "string") {
+            try {
+                if (readFileSync(path, "utf8") !== was)
+                    return false;
+            }
+            catch {
+                return false;
+            }
+            continue;
+        }
+        let there;
         try {
-            if (statSync(fullPath).isFile())
-                return fullPath;
+            there = statSync(path).isFile();
         }
         catch {
-            continue;
+            there = false;
         }
+        if (there !== (was === FOUND))
+            return false;
     }
-    return null;
+    return true;
 }
 /**
  * Port of loaders.relative_resource_path: the path of `target` in `resourceDir`, relative to `baseDir`, with `/` as

package/dist/plain/graph.js

@@ -6,7 +6,7 @@ import { resourceFile } from "../regenerate/resources.js";
 import { DEFAULT_CONCEPT_DEFINITIONS, DEFAULT_CONCEPTS, definitionText, extractConceptsFromDefinition, findConcepts } from "./concepts.js";
 import { lineNumber, renderToMarkdown, renderTokens } from "./markdown.js";
 import { attempt, namesIn, readModule } from "./module-concepts.js";
-import { IMPORT_DIRECTIVE, linksIn, modulePlainFile, parsePlainFile, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata, REQUIRES_DIRECTIVE, functionalitiesOf, sectionOf, withParseCache, } from "./parser.js";
+import { IMPORT_DIRECTIVE, linksIn, modulePlainFile, sharedPlainFileParse, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata, REQUIRES_DIRECTIVE, functionalitiesOf, sectionOf, withParseCache, } from "./parser.js";
 import { DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS } from "./spec.js";
 import { isStdlibModule } from "./stdlib.js";
 import { discoverTestPlainFiles, readTestPlainFileText } from "./project.js";
@@ -161,7 +161,7 @@ function parseError(node, dirs) {
     const imported = node.importedBy.length > 0 || isStdlibModule(node.module) || basename(dirname(node.file)) === "template";
     try {
         if (imported)
-            parsePlainFile(node.module, {}, dirs, [], []);
+            sharedPlainFileParse(node.module, dirs);
         else
             plainFileParser(`${node.module}${PLAIN_SOURCE_FILE_EXTENSION}`, dirs, { allowNoFunctionalities: true });
         return undefined;

package/dist/plain/module-concepts.js

@@ -3,7 +3,7 @@ import { basename } from "node:path";
 import { resolveTemplateDirs } from "../regenerate/paths.js";
 import { DEFAULT_CONCEPT_DEFINITIONS, definitionText, extractConceptsFromDefinition } from "./concepts.js";
 import { renderToMarkdown } from "./markdown.js";
-import { exportedDefinitionsOf, IMPORT_DIRECTIVE, parsePlainFile, parsePlainSource, PLAIN_SOURCE_FILE_EXTENSION, readPlainSourceMetadata, REQUIRES_DIRECTIVE, restoreStrippedLines, sectionOf, } from "./parser.js";
+import { exportedDefinitionsOf, IMPORT_DIRECTIVE, sharedPlainFileParse, parsePlainSource, PLAIN_SOURCE_FILE_EXTENSION, readPlainSourceMetadata, REQUIRES_DIRECTIVE, restoreStrippedLines, sectionOf, } from "./parser.js";
 import { DEFINITIONS } from "./spec.js";
 /**
  * A module read for what it can name, as the parser builds its definitions: its own, its imports' (`import`), and its
@@ -11,7 +11,8 @@ import { DEFINITIONS } from "./spec.js";
  * gives its own definitions read without its imports, and what of those it names is there.
  */
 export function readModule(moduleName, plainFile, templateDirs) {
-    const parse = (name) => attempt(() => parsePlainFile(name, {}, templateDirs, [], []));
+    // Read, never changed: the parse kept for the file, not a copy of it.
+    const parse = (name) => attempt(() => sharedPlainFileParse(name, templateDirs));
     const definitions = [];
     const add = (result, nodes, module) => {
         for (const node of nodes)

package/dist/plain/parser.d.ts

@@ -100,6 +100,11 @@ export declare function parsePlainSource(plainSourceText: string, codeVariables:
 export declare function modulePlainFile(moduleName: string, templateDirs: string[]): string | null;
 export declare function readModulePlainSource(moduleName: string, templateDirs: string[]): string;
 export declare function parsePlainFile(moduleName: string, codeVariables: Record<string, Record<string, string>>, templateDirs: string[], importedModules: string[], modulesTrace: string[]): PlainFileParseResult;
+/**
+ * A module's file parsed on its own - as `parsePlainFile(moduleName, {}, templateDirs, [], [])` parses it - shared with
+ * every caller, not a copy: for what only reads it. What builds on a parse asks `parsePlainFile` for its own copy.
+ */
+export declare function sharedPlainFileParse(moduleName: string, templateDirs: string[]): PlainFileParseResult;
 /**
  * Parse every required module, deepest first, without validating it - each with code variables of its own - and
  * return the definitions the directly required modules export. A module listed again right after it was walked is
@@ -151,8 +156,8 @@ export declare function parseModuleChain(plainSourceFileName: string, templateDi
  *
  * Walking a requires chain parses each module in it, and each parse gathers what it inherits
  * by parsing the modules below - so looking across a project of long chains asks for the
- * same files thousands of times. Inside `run` they are parsed once. Outside it nothing is
- * kept, so an edit made between two calls is always seen: the cache is for one question
- * about the specs, not for the life of the process.
+ * same files thousands of times. Inside `run` they are parsed once. Between calls only
+ * parses that still hold are kept - a top-level parse by its fingerprint, a file parsed on
+ * its own by every file it read - so an edit made between two calls is always seen.
  */
 export declare function withParseCache<T>(run: () => T): T;

package/dist/plain/parser.js

@@ -4,7 +4,7 @@ import { extname, isAbsolute, basename, join, resolve } from "node:path";
 import { load as loadYaml } from "js-yaml";
 import { extractConceptsFromDefinition, findConceptDefinitionsInPlainSource, sortDefinitions, validateConcepts, DEFAULT_CONCEPTS, } from "./concepts.js";
 import { ImportedModuleWithFunctionalitiesError, MissingFunctionalitiesError, ModuleDoesNotExistError, PlainSyntaxError, UnsupportedBase64Content, } from "./errors.js";
-import { findIn, findLargeBase64Blob, getLoadedTemplates, openFrom } from "./files.js";
+import { addReads, findIn, findLargeBase64Blob, getLoadedTemplates, noteReads, openFrom, readsHold } from "./files.js";
 import { renderPlainSource } from "./liquid.js";
 import { isStdlibModule, readStdlibModule, stdlibModuleFile } from "./stdlib.js";
 import { getRawText, lineNumber, parseMarkdown, removeQuotes, renderToMarkdown, renderTokens, traverse, } from "./markdown.js";
@@ -547,6 +547,45 @@ export function readModulePlainSource(moduleName, templateDirs) {
     return plainSourceText;
 }
 export function parsePlainFile(moduleName, codeVariables, templateDirs, importedModules, modulesTrace) {
+    // A file parsed on its own - not an import inside another's parse, whose result hangs on what was imported before it -
+    // is parsed once while nothing it read has changed: every module below a module in its chain parses each of them
+    // again, and a project of long chains asked the same files thousands of times.
+    const own = importedModules.length === 0 && modulesTrace.length === 0 && Object.keys(codeVariables).length === 0;
+    if (!own)
+        return parsePlainFileNow(moduleName, codeVariables, templateDirs, importedModules, modulesTrace);
+    // A copy: the caller builds on what it is given.
+    const copy = structuredClone(keptParse(moduleName, templateDirs));
+    Object.assign(codeVariables, copy.codeVariables);
+    return copy.result;
+}
+/** Files parsed on their own, with what each read - by working folder, template folders and module. Oldest out first. */
+const keptFiles = new Map();
+const KEPT_FILES = 500;
+/**
+ * A module's file parsed on its own - as `parsePlainFile(moduleName, {}, templateDirs, [], [])` parses it - shared with
+ * every caller, not a copy: for what only reads it. What builds on a parse asks `parsePlainFile` for its own copy.
+ */
+export function sharedPlainFileParse(moduleName, templateDirs) {
+    return keptParse(moduleName, templateDirs).result;
+}
+/** A file parsed on its own, as kept while what it read holds - not to be changed: copy what is built on. */
+function keptParse(moduleName, templateDirs) {
+    const key = `${process.cwd()}\0${templateDirs.join("\0")}\0${moduleName}`;
+    const kept = keptFiles.get(key);
+    if (kept !== undefined && readsHold(kept.reads)) {
+        addReads(undefined, kept.reads);
+        return kept.parsed;
+    }
+    const codeVariables = {};
+    const { value: result, reads } = noteReads(() => parsePlainFileNow(moduleName, codeVariables, templateDirs, [], []));
+    const parsed = { result, codeVariables };
+    keptFiles.delete(key);
+    keptFiles.set(key, { reads, parsed });
+    while (keptFiles.size > KEPT_FILES)
+        keptFiles.delete(keptFiles.keys().next().value);
+    return parsed;
+}
+function parsePlainFileNow(moduleName, codeVariables, templateDirs, importedModules, modulesTrace) {
     const plainSourceText = readModulePlainSource(moduleName, templateDirs);
     return parsePlainSource(plainSourceText, codeVariables, templateDirs, importedModules, [...modulesTrace, moduleName], moduleName);
 }
@@ -567,7 +606,9 @@ export function processRequiredModules(requiredModules, templateDirs, allRequire
             exportedDefinitions.push(...(exports.get(moduleName) ?? []));
             continue;
         }
-        const result = parsePlainFile(moduleName, {}, templateDirs, [], []);
+        // Only what it requires and what it exports are read: the kept parse, not a copy - but for what it exports, which the
+        // module requiring it takes into its own definitions.
+        const { result } = keptParse(moduleName, templateDirs);
         if (result.requiredModules.length === 0) {
             if (allRequiredModules.length > 0) {
                 // Required modules must form one chain; independent modules cannot yet be merged.
@@ -577,7 +618,7 @@ export function processRequiredModules(requiredModules, templateDirs, allRequire
         else {
             processRequiredModules(result.requiredModules, templateDirs, allRequiredModules, [...modulesTrace, moduleName], exports);
         }
-        const own = exportedDefinitionsOf(result);
+        const own = structuredClone(exportedDefinitionsOf(result));
         exports.set(moduleName, own);
         exportedDefinitions.push(...own);
         allRequiredModules.push(moduleName);
@@ -687,9 +728,9 @@ export function parseModuleChain(plainSourceFileName, templateDirs, options = {}
  *
  * Walking a requires chain parses each module in it, and each parse gathers what it inherits
  * by parsing the modules below - so looking across a project of long chains asks for the
- * same files thousands of times. Inside `run` they are parsed once. Outside it nothing is
- * kept, so an edit made between two calls is always seen: the cache is for one question
- * about the specs, not for the life of the process.
+ * same files thousands of times. Inside `run` they are parsed once. Between calls only
+ * parses that still hold are kept - a top-level parse by its fingerprint, a file parsed on
+ * its own by every file it read - so an edit made between two calls is always seen.
  */
 export function withParseCache(run) {
     if (activeCache !== undefined)

package/dist/plain/stdlib.js

@@ -1,8 +1,8 @@
-import { existsSync, realpathSync } from "node:fs";
+import { realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ModuleDoesNotExistError, PlainSyntaxError } from "./errors.js";
-import { findIn, openFrom } from "./files.js";
+import { findIn, isFile, openFrom } from "./files.js";
 /**
  * The ***plain standard library's names. `stdlib/` is a reserved prefix: `stdlib/backend/python-fastapi`
  * is always turri's own template, in its `stdlib/` folder - never a module of the project's. A
@@ -36,7 +36,7 @@ export function readStdlibModule(moduleName, templateDirs) {
     const own = join(STDLIB_ROOT, file);
     for (const dir of templateDirs) {
         const local = join(dir, file);
-        if (existsSync(local) && !sameFile(local, own)) {
+        if (isFile(local) && !sameFile(local, own)) {
             throw new PlainSyntaxError(`Plain syntax error: '${name}' is a reserved name - modules under ${STDLIB_PREFIX} are turri's standard library - ` +
                 `but ${local} is a module of that name. Rename it, or the folder it is in.`);
         }

package/dist/regenerate/base-folder.d.ts

@@ -31,6 +31,8 @@ export declare function baseFolderOf(plainFile: string): {
  * does not ignore - so no dependencies or build output; otherwise every file but those of the folders never copied.
  */
 export declare function baseFiles(folder: string): string[];
+/** `baseFiles`, its git runs not holding the thread up - for doctor, on a host's thread. */
+export declare function baseFilesAsync(folder: string): Promise<string[]>;
 /** What a base folder holds now, as one hash: each file's path and bytes. */
 export declare function hashBase(folder: string, files?: string[]): string;
 /** What a codebase started from, when it started from a base folder. */

package/dist/regenerate/base-folder.js

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { spawnAsync } from "../spawn-async.js";
 import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
@@ -34,14 +35,31 @@ const NOT_COPIED = new Set([".git", "node_modules", ".venv", "venv", "__pycache_
  * does not ignore - so no dependencies or build output; otherwise every file but those of the folders never copied.
  */
 export function baseFiles(folder) {
-    const inGit = spawnSync("git", ["-C", folder, "rev-parse", "--is-inside-work-tree"], { encoding: "utf8" });
+    const inGit = spawnSync("git", ["-C", folder, ...IN_WORK_TREE], { encoding: "utf8" });
     if (inGit.status === 0 && inGit.stdout.trim() === "true") {
-        const listed = spawnSync("git", ["-C", folder, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "."], { encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
-        if (listed.status === 0) {
-            // A tracked file deleted in the work tree is listed, and not there to copy.
-            return [...new Set(listed.stdout.split("\0").filter((path) => path !== ""))].filter((path) => isFile(join(folder, path))).sort();
-        }
+        const listed = spawnSync("git", ["-C", folder, ...LISTED], { encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+        if (listed.status === 0)
+            return gitListed(folder, listed.stdout);
+    }
+    return walkedFiles(folder);
+}
+/** `baseFiles`, its git runs not holding the thread up - for doctor, on a host's thread. */
+export async function baseFilesAsync(folder) {
+    const inGit = await spawnAsync("git", ["-C", folder, ...IN_WORK_TREE]);
+    if (inGit.status === 0 && inGit.stdout.trim() === "true") {
+        const listed = await spawnAsync("git", ["-C", folder, ...LISTED]);
+        if (listed.status === 0)
+            return gitListed(folder, listed.stdout);
     }
+    return walkedFiles(folder);
+}
+const IN_WORK_TREE = ["rev-parse", "--is-inside-work-tree"];
+const LISTED = ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "."];
+/** What git listed, as files there: a tracked file deleted in the work tree is listed, and not there to copy. */
+function gitListed(folder, listed) {
+    return [...new Set(listed.split("\0").filter((path) => path !== ""))].filter((path) => isFile(join(folder, path))).sort();
+}
+function walkedFiles(folder) {
     const found = [];
     const walk = (dir) => {
         for (const entry of readdirSync(dir)) {

package/dist/regenerate/command-check.d.ts

@@ -26,7 +26,7 @@ export interface CommandFence {
     /** Whose paths these are: drive letters, backslashes and any case on Windows. */
     platform?: "posix" | "win32";
 }
-export type CheckRule = "path" | "record" | "credential" | "install" | "kill";
+export type CheckRule = "path" | "record" | "credential" | "install" | "system" | "kill";
 export type CheckResult = {
     ok: true;
 } | {
@@ -36,5 +36,16 @@ export type CheckResult = {
 };
 /** What of the machine an agent's command may read, beside its roots and its toolchains: the system's own folders. */
 export declare function machineReadable(platform?: NodeJS.Platform): string[];
+/**
+ * Why a command line changes the machine - installs software outside the project, or changes a setting of the
+ * machine's or the person's environment - or nothing when it does not. The project's own dependencies, installed into
+ * the project (npm install, a venv, mvn, cargo), change nothing of the machine's. turri changes the machine nowhere: not
+ * an agent, not the chat, not a release - what the machine lacks is the person's to install, in their own words.
+ */
+export declare function machineChange(command: string): string | undefined;
+/** The .plain file a command line writes - a ***plain module or a test plain file - or nothing when it writes none. */
+export declare function writesPlain(command: string): string | undefined;
+/** What turri says when a command would change the machine: what it does instead. */
+export declare function machineChangeReason(why: string): string;
 /** Check one command line against a role's fence: `{ ok: true }`, or which rule it breaks and what to do instead. */
 export declare function checkCommand(command: string, fence: CommandFence): CheckResult;