@turri-dev/cli 0.1.6 → 0.1.7-next.9aec40e

package/dist/regenerate/loop.d.ts

@@ -0,0 +1,392 @@
+import { type ChunkAgents } from "./chunk-plan.ts";
+import { type SpecGap } from "./notes.ts";
+import { type Job, type JobRegistry } from "./jobs.ts";
+import type { Steering } from "./steer.ts";
+import { type ChainEntry } from "./requires.ts";
+import { type SpecSnapshot } from "./regenerate.ts";
+import { type JobSteering } from "./steering.ts";
+import { type SpecStep } from "./spec-steps.ts";
+import { type JobCases, type TouchedSpec } from "./drift.ts";
+/**
+ * The work loop - see docs/regenerating.md.
+ *
+ * Nothing is queued. For every codebase it has been asked to bring up to its spec, the loop works out
+ * what is left to build - from the code record to the spec of the codebase's requires chain, as the
+ * .plain files have it now - has the planner cut it into jobs, and runs the first. When a job ends, or
+ * the spec changes, it works it out again. A plan is kept only while the spec and the record it was cut
+ * from stay as they were.
+ *
+ * Code accumulates up a requires chain: a module is built on a copy of the code of the one it requires.
+ * So the codebase of a chain is its furthest-built module - its tip - and a change to a module below is
+ * made there. The codebases below it are left as they were, their records saying what they are built
+ * from; one is brought up to its own spec again only when a module not built yet is to start from it.
+ *
+ * - A module waits while one it is built on has work left, or a job running.
+ * - A running job the spec no longer wants - one of its changes is no longer part of the work - is
+ *   stopped, and what it did rolled back. Otherwise it finishes, and the next plan starts from what it
+ *   landed.
+ * - A job that does not land halts its codebase: nothing more runs there until the spec changes or it is
+ *   asked for again.
+ */
+/** A planned job: its title, why, its cases, and its step - its diff and the spec it leaves. */
+export interface PlannedJob {
+    title: string;
+    reason: string;
+    cases: JobCases;
+    step: SpecStep;
+    /** What it builds: the code, or the conformance tests of what the code is built from. */
+    track: Track;
+}
+/** The two things a codebase is brought up in: its code, and - on the code as built - its conformance tests. */
+export type Track = "code" | "conformance";
+/** What renders a job. Injectable, so the loop can be tested without a model. */
+export type JobRunner = (job: {
+    plainFile: string;
+    moduleName: string;
+    buildDir: string;
+    spec: SpecSnapshot;
+    planned: PlannedJob;
+    model?: string;
+    cwd: string;
+    /** A code job's: how the loop steers it when the spec changes inside what it regenerates - and the record it lands. */
+    steering?: JobSteering;
+}, onDelta: (delta: string) => void) => Promise<{
+    landed: boolean;
+    report: string;
+    story?: string;
+    specGaps?: SpecGap[];
+}>;
+/** A codebase as the loop sees it, for the person. */
+export interface ModuleStatus {
+    module: string;
+    plainFile: string;
+    /** The job running now, if one is. */
+    running?: {
+        jobId: string;
+        title: string;
+        steered?: string[];
+    };
+    /**
+     * The jobs planned after it, in order: the module's code jobs, then its conformance jobs. A conformance job scheduled
+     * for functional specs not all built yet - `waitsFor`, those that are not - comes after the module's last code job.
+     * The module's conformance tests, wanted for all of it while its code is still to build - `afterCode` - come last:
+     * they are planned into pulses only once the code is built, but are shown, so asking for them is seen to have worked.
+     */
+    planned: Array<{
+        title: string;
+        cases: JobCases;
+        track: Track;
+        waitsFor?: string[];
+        planning?: true;
+        afterCode?: true;
+    }>;
+    /**
+     * What the plan of its code did not do as asked: the person's wishes its planner did not follow and why, an answer
+     * that did not hold, a group split for its size.
+     */
+    planNotes?: string[];
+    /** Why nothing runs there, when nothing does. */
+    why?: string;
+    /** What asking for conformance tests changed there, when it changed nothing: they were on for the whole module already. */
+    conformanceNote?: string;
+    /**
+     * It now requires modules its code was not built on - `requires` - and is built only once its code is started
+     * over on them: these codebases' code and tests taken out, kept in their history, and built again from the
+     * bottom of the chain. Never done unasked: `startOver` does it.
+     */
+    startOver?: {
+        requires: string[];
+        codebases: string[];
+    };
+    /** The stack it is built with - its config.turri.<stack>.yaml over config.turri.yaml - when one is. */
+    stack?: string;
+}
+/** What is left to regenerate in a codebase - see `WorkLoop.drift`. */
+export interface DriftReport {
+    module: string;
+    plainFile: string;
+    /** The code's work, from its record to the spec now: null, none - built from the spec as it is. */
+    code: JobCases | null | undefined;
+    /** The conformance tests' work: null, none; undefined, none are written here. */
+    conformance: JobCases | null | undefined;
+    /** Conformance tests scheduled ahead of their code, and which of their functional specs are not built yet. */
+    scheduled: Array<{
+        frids: string[];
+        unbuilt: string[];
+    }>;
+    running?: {
+        jobId: string;
+        title: string;
+    };
+    /** Why nothing is regenerated there: halted, or its spec does not parse. */
+    why?: string;
+    startOver?: ModuleStatus["startOver"];
+}
+/** What is left to regenerate, as the conversation and the command line read it. */
+export declare function describeDrift(reports: DriftReport[]): string;
+export interface WorkLoop {
+    /**
+     * Bring a spec's module up to the spec as the .plain files have it now - in the codebases where its
+     * code lives, and every module it is built on that has to be built first - planning and starting the
+     * first jobs. Asked again, it clears a halt. Also what a spec change is: the loop works out the work
+     * again. `specChange`: brought up because its spec was changed, not asked for - a module the person halted stays
+     * halted. Says what it planned.
+     */
+    bringUp(plainFile: string, options?: {
+        model?: string;
+        guidance?: string;
+        specChange?: boolean;
+    }): Promise<ModuleStatus[]>;
+    /**
+     * Regenerate functional specs of a module again, their spec changed or not: each is marked to regenerate again in
+     * the record of every codebase it is built in - committed - and they are brought up to their spec, the marked ones
+     * planned as any change is. Their code is there: the jobs that regenerate them are told to regenerate it again, not
+     * to build it anew.
+     */
+    regenerateAgain(plainFile: string, frids: string | string[], options?: {
+        model?: string;
+        guidance?: string;
+    }): Promise<ModuleStatus[]>;
+    /**
+     * What is left to regenerate, for a spec's module, in each codebase where its code lives: the code's work from its
+     * record to the spec now, and the conformance tests' - planning nothing, starting nothing.
+     */
+    drift(plainFile: string): DriftReport[];
+    /**
+     * Write and run the conformance tests of a spec's module - of the functional specs named, or of every one - on the
+     * code as it is built, in the codebases where its code lives: for this session, whatever the config says. Asked
+     * again, it clears a halt. Says what it planned.
+     */
+    conformance(plainFile: string, options?: {
+        frids?: string[];
+        model?: string;
+        separately?: boolean;
+        groups?: string[][];
+    }): Promise<ModuleStatus[]>;
+    /**
+     * Start over the codebases of a spec's module that now require a module their code was not built on (see
+     * `ModuleStatus.startOver`): their code and conformance tests taken out - committed, so their history keeps
+     * them - and the module brought up, from the bottom of its chain. Destructive: asked for only once the person
+     * agreed. Says what it planned.
+     */
+    startOver(plainFile: string, options?: {
+        model?: string;
+    }): Promise<ModuleStatus[]>;
+    /**
+     * Regenerate a spec's module from scratch: every codebase where its code lives taken back to nothing - its code and
+     * conformance tests taken out, committed so its history keeps them - and the module brought up from its spec, planned
+     * into pulses as any work is. With `chain`, every codebase of its requires chains too, the base's included: nothing
+     * below is copied up, and the whole chain is built again from the bottom - after modules were split or moved, when
+     * the code below was laid out for modules that are no more. Destructive: asked for only when the person asked for
+     * it. Says what it planned.
+     */
+    fromScratch(plainFile: string, options?: {
+        model?: string;
+        guidance?: string;
+        chain?: boolean;
+    }): Promise<ModuleStatus[]>;
+    /**
+     * Halt a module's planned work, as the person asked: `target` is a planned row's id (`planned-<module>-...`) or the
+     * module's name. A module's pulses are planned again from its spec each look, so it is the module that is halted, not
+     * one row: its pulse running is stopped and rolled back, nothing is planned or started there - nor in the modules built
+     * on it, which wait for it - until it is asked for again; a spec change does not start it. A module whose .plain file is
+     * gone is forgotten. Says what it did - undefined when the target names no module the loop looks after.
+     */
+    halt(target: string, reason?: string): string | undefined;
+    /** Every codebase the loop looks after, bottom of each chain first. */
+    status(): ModuleStatus[];
+    /**
+     * The jobs planned after the running ones, as jobs are listed - queued, each after the one before it -
+     * for the job panel and pulses. Not started, they are not the registry's: planned again, they change.
+     */
+    planned(): Job[];
+    /**
+     * What the regeneration draws on top of the files: the .plain files asked for, and each codebase's pulses - running and
+     * planned, numbered, with the trees each goes between - and why nothing moves there, when nothing does.
+     */
+    mapPlan(): MapPlan;
+    /** Resolves once nothing runs and nothing more can start. */
+    drain(): Promise<void>;
+    /** In a dry run: the job each codebase would start, with the spec it would be given. */
+    firsts(): Array<{
+        module: string;
+        plainFile: string;
+        buildDir: string;
+        spec: SpecSnapshot;
+        planned: PlannedJob;
+    }>;
+}
+/** A pulse as the regeneration places it: by the items its trees differ in. */
+export interface MapPulse {
+    /** Its number among the module's pulses this session - planned ones' provisional. */
+    number: number;
+    title: string;
+    track: Track;
+    running: boolean;
+    /** Its id in the jobs listed - the running job's, or the planned row's - for the pulse list to go to. */
+    rowId: string;
+    /** The trees it goes between, serialized. */
+    before: string;
+    after: string;
+    /**
+     * A conformance pulse scheduled ahead of its code - not planned, so with no trees: the texts of the functional specs
+     * it writes tests for.
+     */
+    specs?: string[];
+}
+/** A codebase as the regeneration reads the loop. */
+export interface MapCodebase {
+    module: string;
+    plainFile: string;
+    buildDir: string;
+    /** The pulses running and planned, in order. */
+    pulses: MapPulse[];
+    /** The track the planner is cutting now. */
+    planning?: Track;
+    /** The module below it that it waits for. */
+    waitsFor?: string;
+    /** Its conformance tests are on: by the config, or asked for this session. */
+    conformance: boolean;
+    /** Why nothing runs there, when nothing does. */
+    why?: string;
+    /** What asking for conformance tests changed there, when it changed nothing: they were on for the whole module already. */
+    conformanceNote?: string;
+    /**
+     * Halted, or the planner found no plan: it needs the person. `pulse`, the pulse that did not land; `cause`, what went
+     * wrong in it, in a few words - its tests never passed, the machine lacks a toolchain.
+     */
+    stuck?: {
+        why: string;
+        pulse?: {
+            number: number;
+            before: string;
+            after: string;
+        };
+        cause?: string;
+    };
+}
+export interface MapPlan {
+    /** The .plain files asked for, in the order they were. */
+    files: string[];
+    codebases: MapCodebase[];
+}
+/** The spec a codebase is built from, as the .plain files have it now: its whole requires chain's. */
+export declare function chainSpec(chain: ChainEntry[]): SpecSnapshot;
+/** How many of a module's functional specs are completed in the codebase a run delivers - see `functionalityCompletion`. */
+export interface ModuleCompletion {
+    module: string;
+    /** Its own functional specs, as its spec has them now. */
+    specified: number;
+    /** Of those, the ones the delivered codebase's code record has as the spec has them now. */
+    completed: number;
+    /** Of the completed ones, those its conformance tests are recorded as written for, as the spec has them now. */
+    conformanceTested: number;
+    /** Its functional specs not completed, by number. */
+    incomplete: string[];
+}
+/**
+ * The functional specs of a spec's whole requires chain, completed or not, in the codebase each chain delivers: its
+ * furthest-built module's code - which holds the code of every module below it. A functional spec is completed when that
+ * codebase's code record, as last committed, holds it as the spec has it now - the same text, the linked files it uses
+ * holding the same, no definition it uses changed, not marked to regenerate again. A record moves only when a pulse
+ * lands, its unit tests passing (and its conformance tests, when they are on), so completed is landed and passing.
+ * The modules above the delivered codebase have nothing completed. One entry per chain; planning nothing, calling no model.
+ */
+export declare function functionalityCompletion(plainFile: string): Array<{
+    codebase: string;
+    modules: ModuleCompletion[];
+}>;
+export declare function createWorkLoop(options: {
+    registry: JobRegistry;
+    cwd: string;
+    /** The model a job renders on, asked when a module is brought up. */
+    modelFor?: (plainFile: string) => string | undefined;
+    /** The planner's agents. false: none - a functional spec a job. Default: the LLM ones, on `plannerModel`. */
+    planner?: ChunkAgents | false;
+    /** The planner's model, read afresh each plan - the chat's, in a conversation. */
+    plannerModel?: string | (() => string | undefined);
+    /** How the person wants the work cut and ordered, for every plan of a spec's module. */
+    steering?: (plainFile: string) => Steering[];
+    /** Renders a job. Default: a spec diff render that lands on its unit tests. */
+    run?: JobRunner;
+    /** Writes and runs a conformance job's tests. Default: a spec diff's conformance run, the whole suite with it. */
+    runConformance?: JobRunner;
+    /** Whether the config has a module's conformance tests on. Default: its `conformance-tests:`, off unless it turns them on. */
+    conformanceOn?: (plainFile: string) => boolean;
+    /**
+     * Whether a module's conformance tests are for the functional specs chosen, not every one: those with acceptance
+     * tests, those the conversation asked for, and those tested already. Default: `conformance-tests: chosen`.
+     */
+    conformanceChosen?: (plainFile: string) => boolean;
+    /**
+     * Under `conformance-tests: chosen`, asked what a code job that landed built or changed that no conformance test is
+     * for - by whoever chooses without a conversation (`turri regenerate`) - before the job ends: the functional specs it
+     * names are scheduled as conform schedules them. The conversation is told in the job's report instead.
+     */
+    onChoose?: (plainFile: string, specs: TouchedSpec[], budget: number | undefined, when: "pulse" | "module") => Promise<{
+        frids: string[];
+        groups?: string[][];
+        why?: string;
+    } | undefined>;
+    /** When the chooser is asked: after each code pulse, once the module is regenerated, or never. Default: `conformance-tests:`. */
+    conformanceChoosing?: (plainFile: string) => "pulse" | "module" | undefined;
+    /**
+     * Under `release-after-pulse: true`, what releases a pulse that landed, as its last stage - before the pulse ends, so
+     * the module's next pulse starts on what is released. Its last reply goes in the pulse's report. Not given: nothing is.
+     */
+    release?: (input: {
+        plainFile: string;
+        moduleName: string;
+        title: string;
+        onDelta: (delta: string) => void;
+    }) => Promise<string>;
+    /** Plan, and keep the job each codebase would start (`firsts`) - but start none. */
+    dryRun?: boolean;
+}): WorkLoop;
+/** Why nothing runs in a codebase whose code - and conformance tests, where they are wanted - is built from its spec as it is. */
+export declare const UP_TO_DATE = "built from the spec as it is";
+/** The codebases the loop looks after, as the person reads them: what runs, what is planned after it, and why nothing does. */
+/**
+ * The coding agent's task for a dry run's first job, built as the render builds it - and all it did rolled back. Not for
+ * a conformance job: its prompt is built from what the code holds once it is built.
+ */
+export declare function promptOf(first: ReturnType<WorkLoop["firsts"]>[number]): Promise<string | undefined>;
+/** The first job a codebase would start, and the prompt its coding agent would get. */
+export interface JobPreview {
+    module: string;
+    title: string;
+    track: Track;
+    cases: JobCases;
+    /** The coding agent's task, whole. Not for a conformance job: it is built from what the code holds once it is built. */
+    task?: string;
+}
+/**
+ * What bringing a spec's module up would start, in each codebase, and the prompt of each - planned on a loop of its own
+ * that starts nothing. A codebase `busy` says is running a job is left out: a dry run starts from its last commit, and
+ * what the next job there is given depends on what the running one lands.
+ */
+export declare function previewJobs(options: {
+    plainFile: string;
+    cwd: string;
+    model?: string;
+    plannerModel?: string;
+    steering?: (plainFile: string) => Steering[];
+    /** Whether a codebase, by its module, has a job running. */
+    busy?: (module: string) => boolean;
+}): Promise<{
+    statuses: ModuleStatus[];
+    previews: JobPreview[];
+    busy: string[];
+}>;
+/** Nothing runs, is planned or is waiting there, as its code is built from its spec as it is. */
+export declare function isUpToDate(status: ModuleStatus): boolean;
+export declare function describeModules(statuses: ModuleStatus[], options?: {
+    for?: "chat" | "command line";
+}): string;
+/** How a code pulse went, for its line in the notes: the rounds it took, its test runs, what the debugger found. */
+export declare function codeStory(result: {
+    attempts?: number;
+    runs?: unknown[];
+    diagnosed?: string[];
+    restructured?: boolean;
+}): string | undefined;

package/dist/regenerate/masking.d.ts

@@ -0,0 +1,19 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+/** Mask these values, by name, from now on. */
+export declare function registerSecrets(values: Record<string, string>): void;
+/** For tests: mask nothing. */
+export declare function forgetSecretsForTests(): void;
+/** `text` with every registered value replaced by its name. */
+export declare function maskSecrets(text: string): string;
+/**
+ * A stream that masks what passes through it before `onData` sees it: the end of each chunk is held back - as long as
+ * the longest value, less one - until the next shows whether a value runs across them. `end` lets the rest out.
+ */
+export declare function maskingStream(onData: (data: Buffer) => void): {
+    write(data: Buffer): void;
+    end(): void;
+};
+type AnyTool = ToolDefinition<any, any, any>;
+/** The tools, each result they return - and each error they throw, a refusal - masked before the agent sees it. */
+export declare function maskToolResults<T extends AnyTool>(tools: T[]): T[];
+export {};

package/dist/regenerate/notes.d.ts

@@ -0,0 +1,159 @@
+import { Type } from "typebox";
+/**
+ * Working notes: what one agent on a codebase leaves the next.
+ *
+ * Every agent the harness starts is a fresh session. Without notes, each one spends its first
+ * turns finding its bearings - where the entry point is, how the tests run, what was installed,
+ * which approach already failed. The notes carry that forward: each agent on a codebase gets
+ * them the moment it starts, and updates them - a line added, changed or removed - before it
+ * finishes, so they get longer with the codebase instead of being rewritten by whoever came last.
+ *
+ * Stubborn on the specs, flexible on the assumptions. What the software must do is in the spec,
+ * and the notes never repeat or override it. Where the spec is silent, an agent has to assume
+ * something, and the assumptions it made are written down - so the next agent builds on the
+ * same ones instead of guessing afresh, and changes one the moment the code or the spec shows
+ * it to be wrong.
+ *
+ * Every line says when and where it came from - `[2026-09-24 16:49 · backend 3]` for
+ * functionality 3 of backend, `backend 3 conformance`, `backend spec change` - stamped by the
+ * harness, not written by the agent, so a line read two modules later can still be traced to the
+ * step that wrote it. A line that is changed is stamped again: an assumption one agent revised
+ * shows as newer than the ones around it, and where two lines disagree the later one is right. And every line
+ * has to say something: "none", "N/A", "nothing new" are refused - a section with nothing to add
+ * is left alone.
+ *
+ * Leaving them is not optional, and neither is how: only update_notes writes the file. The file
+ * tools refuse it, a change made any other way - a shell, a script - is undone, and an agent
+ * that finishes without calling update_notes is asked again until it does.
+ *
+ * The notes are disposable: delete the file and nothing breaks, the next agent just explores a
+ * little more. They live beside the code, so they travel with it - copied up with it to a module
+ * that requires this one, committed with it, and reset with it when a run is interrupted.
+ */
+export declare const NOTES_FILE = ".turri-notes.md";
+/** The sections, in order, and what each is for - shown to the agent as the heading. */
+export declare const SECTIONS: {
+    readonly where: "Where things are";
+    readonly run: "How to build, run and test";
+    readonly assumptions: "Assumptions";
+    readonly pitfalls: "Pitfalls";
+    readonly pulses: "Pulses";
+};
+/** How many pulses the notes keep: the last ones - the module's history has every one. */
+export declare const PULSES_KEPT = 10;
+export type Section = keyof typeof SECTIONS;
+export type Notes = Record<Section, string[]>;
+export declare function notesPath(buildDir: string): string;
+/** The notes, as lines per section. Lines under no known heading go to pitfalls, not lost. */
+export declare function parseNotes(text: string): Notes;
+export declare function formatNotes(notes: Notes): string;
+export declare function readNotes(buildDir: string): Notes;
+/** A prompt, led by the notes earlier agents left - and told to update them for the next. */
+export declare function withNotes(prompt: string, buildDir: string): string;
+/**
+ * What an agent a review sent tests back to is asked to leave: the lesson, not the fix - the kind of
+ * test the review found weak or missing, and how to write it instead - so every later agent on the
+ * codebase writes it right from its first test, and the first reviews have less to send back.
+ */
+export declare const REVIEW_LESSON: string[];
+/**
+ * After an agent worked on what a review found: when it left no new pitfall - no lesson - it is asked
+ * once more, so the next agent does not make the same tests the review has to send back again.
+ */
+export declare function reflectOnReview(buildDir: string, pitfallsBefore: string[], send: (prompt: string) => Promise<unknown>): Promise<void>;
+export interface NotesChange {
+    section: Section;
+    action: "add" | "change" | "remove";
+    /** The line to add, or for a change the new line. For a remove, the line to remove. */
+    text: string;
+    /** For a change: the line it replaces, as it reads now. */
+    replaces?: string;
+}
+export declare function isFiller(text: string): boolean;
+/**
+ * Apply the changes; the notes that result, or what could not be applied. A line added or
+ * changed is stamped with `stamp` - when, and which step wrote it.
+ */
+export declare function applyNotesChanges(notes: Notes, changes: NotesChange[], stamp?: string): {
+    notes: Notes;
+    problems: string[];
+};
+/** `update_notes`: lines added, changed or removed, never the notes rewritten. */
+export declare function createNotesTool(buildDir: string, onWrite: (text: string) => void, before?: () => void, source?: string): import("@earendil-works/pi-coding-agent").ToolDefinition<Type.TObject<{
+    changes: Type.TArray<Type.TObject<{
+        section: Type.TString;
+        action: Type.TUnion<[Type.TLiteral<"add">, Type.TLiteral<"change">, Type.TLiteral<"remove">]>;
+        text: Type.TString;
+        replaces: Type.TOptional<Type.TString>;
+    }>>;
+}>, {
+    characters: number;
+}, any> & import("@earendil-works/pi-coding-agent").ToolDefinition<any, any, any>;
+/** The section a name means - its key or its heading, in any case, or the heading's first words. */
+export declare function sectionNamed(name: string): Section | undefined;
+/** How many times an agent that finishes without update_notes is asked to call it. */
+export declare const NOTES_ASKS = 3;
+/** The turn that asks for the notes: update_notes is the only tool it may use - the work it follows is done. */
+export declare const NOTES_TURN: {
+    onlyTools: string[];
+};
+/** What the notes turn says first, once the harness's own run of `script` has passed on the work. */
+export declare function passedOutcome(script: string): string;
+/**
+ * A line the harness itself writes into the notes - an attempt at a failing conformance run, what
+ * was judged wrong and what was done about it - stamped like an agent's, and kept as update_notes
+ * would keep it, so no session takes it for a direct write. Never fails the work it records.
+ */
+export declare function recordNote(buildDir: string, section: Section, text: string, source: string): void;
+/**
+ * A pulse's line, written by the harness as the pulse ends - landed or not: what it regenerated, how it went, where its
+ * log is. The last PULSES_KEPT stay; the module's history has every pulse.
+ */
+export declare function recordPulse(buildDir: string, text: string, source: string): void;
+/** A spec gap an agent met: the question it leaves the person, and what the agent decided meanwhile. */
+export interface SpecGap {
+    question: string;
+    assumption: string;
+}
+/** Where the spec gaps stand now: what `gapsSince` reads from. */
+export declare function gapMark(): number;
+/** The spec gaps reported in these codebases since `mark`. */
+export declare function gapsSince(mark: number, dirs: string[]): SpecGap[];
+/**
+ * `report_spec_gap`: a behaviour the specification leaves open that the person would want to decide, put to them as
+ * the pulse ends - never into the notes, which are the next agent's. What the agent decided meanwhile goes into the
+ * notes' assumptions, so the code built on it is known for what it is until the specification settles it.
+ */
+export declare function createSpecGapTool(buildDir: string, source?: string): import("@earendil-works/pi-coding-agent").ToolDefinition<Type.TObject<{
+    question: Type.TString;
+    assumption: Type.TString;
+}>, {
+    question: string;
+    assumption: string;
+}, any> & import("@earendil-works/pi-coding-agent").ToolDefinition<any, any, any>;
+/** The notes, for an agent that reads them but leaves none - a judge. Empty when there are none. */
+export declare function notesToRead(buildDir: string): string;
+export declare function notesForSession(buildDir: string, source?: string): {
+    gapTool: import("@earendil-works/pi-coding-agent").ToolDefinition<Type.TObject<{
+        question: Type.TString;
+        assumption: Type.TString;
+    }>, {
+        question: string;
+        assumption: string;
+    }, any> & import("@earendil-works/pi-coding-agent").ToolDefinition<any, any, any>;
+    tool: import("@earendil-works/pi-coding-agent").ToolDefinition<Type.TObject<{
+        changes: Type.TArray<Type.TObject<{
+            section: Type.TString;
+            action: Type.TUnion<[Type.TLiteral<"add">, Type.TLiteral<"change">, Type.TLiteral<"remove">]>;
+            text: Type.TString;
+            replaces: Type.TOptional<Type.TString>;
+        }>>;
+    }>, {
+        characters: number;
+    }, any> & import("@earendil-works/pi-coding-agent").ToolDefinition<any, any, any>;
+    /**
+     * Ask for the notes until this agent has updated them; whether it has. `outcome`: how the harness's own check of the
+     * work went, said first - so the notes tell the next agent the work passed, never that it could not be made to.
+     */
+    ensureWritten(ask: (prompt: string) => Promise<unknown>, outcome?: string): Promise<boolean>;
+};

package/dist/regenerate/os-sandbox.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The OS sandbox: the wall under an agent's command where the OS offers one - Seatbelt on macOS, bubblewrap on Linux
+ * and WSL2 - driven directly, from the role's fence. It is an extra wall, never where a rule lives: every rule is in the
+ * command check and the audit, which run on every platform, and where no sandbox starts they hold alone.
+ *
+ * What the command can reach, on both: the role's roots - its own read only where the role only reads - the module's
+ * home, TMPDIR and the package caches to write, and of the machine only an allow-list to read: the system's folders and
+ * the toolchains. The code record is denied. The network is open, as on this machine. Signals and process listings
+ * reach only what runs in the same sandbox: bubblewrap's own PID namespace, Seatbelt's same-sandbox target. A cap on
+ * processes and on file size is set inside, beside the time limit.
+ */
+export interface SandboxFence {
+    /** Where the command starts. */
+    cwd: string;
+    /** The role's roots it reads and may not write. */
+    read: string[];
+    /** The role's roots it writes - none for a role that only reads. */
+    write: string[];
+    /** What else the shell writes: the module's home, its TMPDIR, the package caches. */
+    writable: string[];
+    /** What of the machine it reads: the system's folders, the toolchains. */
+    machine: string[];
+    /** What it may not touch at all, inside its roots: the code record. */
+    deny: string[];
+}
+export type Wall = {
+    kind: "seatbelt";
+} | {
+    kind: "bubblewrap";
+    proc: "mount" | "bind";
+} | {
+    kind: "none";
+    why: string;
+    fix?: string;
+};
+/** The caps set inside the sandbox before the command runs: processes, and file size in 1024-byte blocks (8 GiB). */
+export declare const PROCESS_CAP = 4096;
+export declare const FILE_SIZE_CAP_BLOCKS: number;
+/** What of macOS a command needs to read beyond the toolchains, besides `/usr`, `/bin`, `/System`: the loader's caches, the time zone, the developer tools. */
+export declare const MACOS_MACHINE: string[];
+/** What of Linux a command needs to read beyond the toolchains. */
+export declare const LINUX_MACHINE: string[];
+/**
+ * What of the machine a command reads, from the environment it runs in: the system's folders, every folder on its PATH,
+ * the folders its toolchain variables point at, and the project's `toolchains:`. Only the PATH folders themselves, not
+ * their parents - `~/.cargo/bin`, not `~/.cargo`, which holds a registry's credentials - but for a version manager's
+ * install: a `bin` whose parent is a version, `…/installs/node/24.16.0/bin`, links its tools into the install beside it
+ * (`npm` into `lib/node_modules`), and an install holds the toolchain, never a credential.
+ */
+export declare function machineFor(env: Record<string, string | undefined>, toolchainVariables: string[], extra?: string[], platform?: NodeJS.Platform): string[];
+/**
+ * The Seatbelt profile for a fence. Everything is allowed but what it names - reading file contents outside the
+ * allow-list, writing outside the writable folders, the code record, Unix sockets outside the folders, signals and
+ * process information beyond the sandbox - later rules winning over earlier ones. File metadata stays readable, as
+ * resolving a path needs.
+ */
+export declare function seatbeltProfile(fence: SandboxFence, userDirs?: {
+    temp?: string;
+    cache?: string;
+}): string;
+export declare function darwinUserDirs(): {
+    temp?: string;
+    cache?: string;
+};
+/** The bubblewrap arguments for a fence, up to the command. `proc: "bind"` binds the host's /proc where mounting one is refused. */
+export declare function bubblewrapArgs(fence: SandboxFence, options?: {
+    proc: "mount" | "bind";
+}): string[];
+/** How a command is run behind the wall that is up: for the host runner's `wrap`. Where none is, it runs as it is. */
+export declare function sandboxWrap(wall: Wall, fence: SandboxFence): (argv: string[]) => string[];
+/** What bubblewrap's refusal to start says is missing, and how to give it - each failure has a message of its own. */
+export declare function whyBubblewrapFailed(output: string): {
+    why: string;
+    fix?: string;
+};
+/** For tests: forget what was found, or say what to find. */
+export declare function setSandboxForTests(wall: Wall | undefined): void;
+/**
+ * Which wall is up on this machine - tried once, by starting a sandbox that runs `true` - and, when none starts, why
+ * and how to give it one.
+ */
+export declare function sandboxAvailable(): Wall;
+/** Whether `path` is one of the fence's roots or under one - for the tests and the audit. */
+export declare function underAny(path: string, roots: string[]): boolean;
+/** Where the agents' commands run, in one line for the person: which walls are up, or that only the shared ones are. */
+export declare function sandboxSummary(wall?: Wall): {
+    level: "ok" | "limited";
+    text: string;
+};