@turri-dev/cli 0.1.6 → 0.1.7-next.eb57c34

package/dist/plain/spec.d.ts

@@ -0,0 +1,90 @@
+import type { LinkedResource } from "./markdown.ts";
+/** Port of plain_spec.py. */
+export declare const DEFINITIONS = "definitions";
+export declare const NON_FUNCTIONAL_REQUIREMENTS = "implementation reqs";
+export declare const TEST_REQUIREMENTS = "test reqs";
+export declare const FUNCTIONAL_REQUIREMENTS = "functional specs";
+export declare const ACCEPTANCE_TESTS = "acceptance_tests";
+export declare const ACCEPTANCE_TEST_HEADING = "acceptance tests";
+/**
+ * Where a module's tree carries the functional specs it inherits through `requires`: every
+ * functional spec of every module it requires, transitively, bottom of the chain first.
+ * Kept apart from its own, which are numbered 1, 2, 3 on their own.
+ */
+export declare const REQUIRED_FUNCTIONAL_SPECS = "required functional specs";
+export declare const ALLOWED_SPECIFICATION_HEADINGS: string[];
+export declare const ALLOWED_IMPORT_SPECIFICATION_HEADINGS: string[];
+export interface CodeVariable {
+    name: string;
+    value: string;
+}
+export interface SpecificationItem {
+    markdown: string;
+    linked_resources?: LinkedResource[];
+    code_variables?: CodeVariable[];
+    [ACCEPTANCE_TESTS]?: SpecificationItem[];
+}
+/** A functional spec inherited through `requires`, with the module it belongs to and its id there. */
+export interface InheritedSpecificationItem extends SpecificationItem {
+    module: string;
+    frid: string;
+}
+/**
+ * The functional specs a module inherits through `requires`, rendered: each with its
+ * module, its id there, and its acceptance tests.
+ */
+export declare function getInheritedFunctionalSpecs(tree: MarshalledPlainSource, replaceCodeVariables?: boolean): Array<{
+    module: string;
+    frid: string;
+    spec: string;
+    acceptanceTests?: string[];
+}>;
+/**
+ * The marshalled tree: heading -> list of items. Flat: functionalities are numbered 1, 2, 3
+ * in the order they appear. Nested sections with dotted ids ("2.3") are not supported.
+ */
+export interface MarshalledPlainSource {
+    [heading: string]: unknown;
+}
+export declare function getSpecificationItems(tree: MarshalledPlainSource, heading: string): SpecificationItem[] | undefined;
+export declare function hasAcceptanceTests(tree: MarshalledPlainSource): boolean;
+export interface CollectedLinkedResource extends LinkedResource {
+    sections: string[];
+}
+export declare function collectSpecificationLinkedResources(specification: SpecificationItem, specificationHeading: string, linkedResourcesList: CollectedLinkedResource[]): void;
+export declare function collectLinkedResourcesInSection(section: MarshalledPlainSource, linkedResourcesList: CollectedLinkedResource[], specificationsList: string[] | null, includeAcceptanceTests: boolean, frid: string | null): boolean;
+export declare function collectLinkedResources(tree: MarshalledPlainSource, linkedResourcesList: CollectedLinkedResource[], specificationsList: string[] | null, includeAcceptanceTests: boolean, frid?: string | null): boolean;
+/**
+ * The FRID iterator: one functionality ID per functional spec, 1, 2, 3 in order.
+ * Everything that walks the spec one functionality at a time - rendering, ranges, context
+ * building - is driven by this.
+ */
+export declare function getFrids(tree: MarshalledPlainSource): Generator<string>;
+export declare function getFirstFrid(tree: MarshalledPlainSource): string | null;
+export declare function getNextFrid(tree: MarshalledPlainSource, frid: string): string | null;
+export declare function getPreviousFrid(tree: MarshalledPlainSource, frid: string): string | null;
+export declare function getFridsBefore(tree: MarshalledPlainSource, targetFrid: string): string[];
+export declare function getSpecificationItemMarkdown(specificationItem: SpecificationItem, codeVariables: Record<string, string>, replaceCodeVariables: boolean): string;
+export interface Specifications {
+    [DEFINITIONS]: string[];
+    [NON_FUNCTIONAL_REQUIREMENTS]: string[];
+    [TEST_REQUIREMENTS]: string[];
+    [FUNCTIONAL_REQUIREMENTS]: string[];
+    [ACCEPTANCE_TESTS]?: string[];
+}
+/**
+ * Build the rendering context for one functionality: every definition and
+ * implementation/test req in scope, the functionalities up to and including this one,
+ * and this one's acceptance tests.
+ */
+export declare function getSpecificationsForFrid(tree: MarshalledPlainSource, frid: string, replaceCodeVariables?: boolean): [Specifications, Record<string, string> | null];
+/** Iterate every functionality with the context that should be rendered for it. */
+export declare function iterateFunctionalSpecs(tree: MarshalledPlainSource, replaceCodeVariables?: boolean): Generator<{
+    frid: string;
+    specifications: Specifications;
+    codeVariables: Record<string, string> | null;
+}>;
+export declare function hashText(text: string): string;
+export declare function getHashValue(specifications: unknown): string;
+export declare function getRenderRange(renderRange: string, tree: MarshalledPlainSource): string[];
+export declare function getRenderRangeFrom(start: string, tree: MarshalledPlainSource): string[];

package/dist/plain/stdlib.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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
+ * project that has a module at such a path gets an error, not a quiet choice between the two: which one
+ * a spec builds on must never depend on what happens to be on disk beside it.
+ *
+ * This is turri's, not the reference parser's: the Python parser has no standard library.
+ */
+export declare const STDLIB_PREFIX = "stdlib/";
+/** The folder `stdlib/` is in: turri's own. */
+export declare const STDLIB_ROOT: string;
+export declare function isStdlibModule(moduleName: string): boolean;
+/** A standard library module's text - refused when a folder the spec is resolved from has a module of that name too. */
+export declare function readStdlibModule(moduleName: string, templateDirs: string[]): string;

package/dist/question-dialog.d.ts

@@ -0,0 +1,51 @@
+import { type Component, type Focusable, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+/**
+ * The dialog a question is put to the person in, in the TUI: what they must read to answer - a brief to confirm, a plan
+ * to approve - above the question, and the options, or a line to type the answer on.
+ *
+ * pi's own select puts all of it in its title, so a long brief pushes the options off the screen: the person answers a
+ * question they cannot see the choices of. Here the brief scrolls in a window of its own, sized to the terminal, and
+ * the question and its options always show below it - PgUp/PgDn or Shift+Up/Down scroll it, and the mouse wheel.
+ */
+export interface DialogStyle {
+    accent(text: string): string;
+    muted(text: string): string;
+    bold(text: string): string;
+}
+export interface QuestionDialogOptions {
+    /** What to read to answer: shown above the question, scrolling when it is long. Markdown's **bold** and `code` shown as such. */
+    context?: string;
+    question: string;
+    /** The choices. Without them, a line to type the answer on. */
+    options?: string[];
+    /** The choice the cursor starts on. */
+    selected?: number;
+    /** The terminal's height, for the window the brief scrolls in. */
+    rows: () => number;
+    style: DialogStyle;
+    /** The answer - an option, or what was typed - or undefined, dismissed. */
+    done: (answer: string | undefined) => void;
+    /** Draw again: a key changed what shows. */
+    requestRender: () => void;
+}
+export declare class QuestionDialog implements Component, Focusable {
+    private readonly options;
+    private readonly input;
+    private selected;
+    /** The brief's first line in its window. */
+    private scroll;
+    /** How far the brief scrolls, and its window's height - as last drawn. */
+    private maxScroll;
+    private window;
+    private answered;
+    private focusedNow;
+    constructor(options: QuestionDialogOptions);
+    get focused(): boolean;
+    set focused(value: boolean);
+    private finish;
+    private scrollBy;
+    render(width: number): string[];
+    handleInput(data: string): void;
+    handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+    invalidate(): void;
+}

package/dist/questioning.d.ts

@@ -0,0 +1,55 @@
+/**
+ * How many questions an interview may put to the person in each phase it caps, and how broad each is - the
+ * questioning level, the first thing a skill with `metadata.questioning` asks. Light, medium and thorough cap each such
+ * phase at 3, 5 and 10 questions; best judgement leaves it to the agent, which says when it has asked enough. Every
+ * level covers the same ground: fewer questions are broader ones, and what they leave open the agent decides itself.
+ * The level limits the questions, never the spec changes. The phase's closing confirmation, asked with
+ * `confirms_phase`, is never counted.
+ */
+export interface QuestioningLevel {
+    name: string;
+    /** Questions a capped phase may ask; none for best judgement. */
+    cap?: number;
+    /** As the person is offered it. */
+    option: string;
+    /** How broad each question is, as the agent is told. */
+    breadth: string;
+}
+export declare const QUESTIONING_LEVELS: QuestioningLevel[];
+/** The level an answer picks: by its name, wherever it is in the answer; anything else is best judgement. */
+export declare function levelOf(answer: string): QuestioningLevel;
+/** The question the harness puts first, and what the person reads above it. */
+export declare function questioningQuestion(phases: string[]): {
+    question: string;
+    options: string[];
+    context: string;
+};
+/** What a resumed run picks up: the level, and how far each phase's questions went. */
+export interface QuestioningState {
+    level: string;
+    asked: Record<string, number>;
+    /** Phases whose questions are over. */
+    over: string[];
+}
+export interface Questioning {
+    level: QuestioningLevel;
+    /** The phase now running. */
+    enter(phase: string): void;
+    /** Why a question may not be asked now, or undefined when it may. */
+    refusal(confirmsPhase: boolean): string | undefined;
+    /** A question was answered. */
+    answered(confirmsPhase: boolean): void;
+    /** The agent ends this phase's questions itself; what to tell it. */
+    end(): string;
+    /** What the agent is told of the level as a phase starts. */
+    note(phase: string, first: boolean): string | undefined;
+    state(): QuestioningState;
+}
+export declare function createQuestioning(options: {
+    level: QuestioningLevel;
+    /** The phases the level caps. */
+    phases: string[];
+    from?: QuestioningState;
+    /** Called whenever the state changes, to keep it for a resume. */
+    onChange?: (state: QuestioningState) => void;
+}): Questioning;

package/dist/quiet.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Keeps library chatter out of the terminal while a tool runs.
+ *
+ * A skill run spawns many nested agent sessions - an executor, two judges per gate, a fix
+ * agent, each queued render - and libraries underneath them write to the console. In the
+ * TUI every one of those writes interrupts the differential renderer, which abandons the
+ * current frame and leaves it stranded in scrollback. Dozens of "Working" lines pile up.
+ *
+ * Only the `console` methods are intercepted, never `process.stdout.write` itself: that is
+ * how pi draws the TUI, and silencing it would blank the screen. Library noise goes
+ * through `console`; pi's rendering does not.
+ */
+/** Drop the NOISE warnings for good, from here on - captured or not. Safe to call more than once. */
+export declare function dropNoise(): void;
+export interface Captured<T> {
+    result: T;
+    /** Whatever the libraries tried to print, in order. */
+    output: string[];
+}
+/** Run `fn` with console output collected instead of printed. */
+export declare function captureConsole<T>(fn: () => Promise<T>): Promise<Captured<T>>;
+/**
+ * Capture that spans something other than one promise - a whole agent turn, say.
+ *
+ * `captureConsole` covers work it can wrap. A conversation's own model calls happen inside
+ * pi's agent loop, where there is nothing to wrap, so those are bracketed by hand instead.
+ * `end` is safe to call twice and safe to skip: an unbalanced `begin` leaves the console
+ * patched, so callers must end it from a handler that always runs.
+ */
+export declare function beginCapture(): {
+    end: () => string[];
+};
+/** One line noting what was swallowed, or nothing when it was quiet. */
+export declare function describeCaptured(output: string[]): string | null;

package/dist/regenerate/activity.d.ts

@@ -0,0 +1,207 @@
+/**
+ * What a background job is doing right now.
+ *
+ * A render is minutes of agents working with nothing on screen. The work is several layers
+ * deep - a chain, a module, a functionality, an agent session, its tool calls - and
+ * threading a callback through all of them would touch every signature on the way. Instead
+ * each job runs inside its own async context, and anything underneath it reports into
+ * whichever job it is running for: the render steps say which stage they are at, and every
+ * agent session reports its tool calls. Outside a job, reporting is a no-op.
+ */
+export interface ActivitySink {
+    /** Which stage of the work this is, e.g. "writing code and unit tests". */
+    stage(label: string): void;
+    /** One thing that just happened, e.g. "✎ write greeter.py". */
+    activity(line: string): void;
+    /** A line about the machinery under the work - which walls are up, what a command changed that was put back - kept in the job's log too. */
+    note?(line: string): void;
+    /**
+     * What is happening at this moment, e.g. "thinking", or undefined when nothing is.
+     * `keepSince` updates the words without restarting the clock on it.
+     */
+    now(label: string | undefined, options?: {
+        keepSince?: boolean;
+    }): void;
+    /** What one model response cost. */
+    usage(usage: UsageReport): void;
+    /** One agent's share of the work: a turn it took, a compaction, what a model call of it cost. */
+    agent?(tally: AgentReport): void;
+    /** One piece of the full conversation, for reading it back while it happens. */
+    transcript(entry: TranscriptEntry): void;
+    /** Aborted when the job is asked to stop. */
+    signal?: AbortSignal;
+    /** Which job this is, for what records it - a debug log's header. */
+    job?: {
+        id: string;
+        kind: string;
+        summary: string;
+    };
+    /** The spec was found to contradict itself - for the person to decide. */
+    specConflict?(conflict: SpecConflict): void;
+    /** The functional spec being built now, or nothing when none is. */
+    spec?(spec: BuildingSpec | undefined): void;
+}
+/** A functional spec as it is being built: where it sits, and its text as the spec has it. */
+export interface BuildingSpec {
+    /** E.g. "rt_tuples functionality 2 of 5". */
+    label: string;
+    text: string;
+    /**
+     * When work on it began - set by the job, and kept while the same one goes on to its next stage
+     * (its conformance tests, the whole suite), so its time is the whole of it.
+     */
+    since?: number;
+}
+/** Say which functional spec is being built now - shown with the job, and in its transcript. */
+export declare function reportSpec(spec: BuildingSpec | undefined): void;
+/**
+ * Two functional specs that cannot both hold, as a conformance run's judge found them - the times
+ * it takes to count. Nothing in the code or the tests can fix it: the person decides which is meant.
+ */
+export interface SpecConflict {
+    /** The module whose conformance run found it, and its .plain file. */
+    moduleName: string;
+    plainFile: string;
+    /**
+     * The two functionalities - in that module, or in one it requires - each with its module, its
+     * id there, the .plain file it is in, and its functional spec as that file has it.
+     */
+    specs: Array<{
+        module: string;
+        frid: string;
+        plainFile: string;
+        text: string;
+    }>;
+    /** What the judge said each time it raised it, oldest first. */
+    reasons: string[];
+}
+/** Say the spec contradicts itself, to the job this runs for. */
+export declare function reportSpecConflict(conflict: SpecConflict): void;
+/** Raised inside a job that was asked to stop, so the work unwinds instead of carrying on. */
+export declare class JobStoppedError extends Error {
+    constructor();
+}
+/** The stop signal of the job this code is running for, if it is running for one. */
+export declare function currentStopSignal(): AbortSignal | undefined;
+/** The job this code is running for, if it is running for one. */
+export declare function currentJob(): {
+    id: string;
+    kind: string;
+    summary: string;
+} | undefined;
+/**
+ * The conversation an agent is having, as it happens: what it was asked, what it wrote and
+ * thought, what it called and what came back. Text and thinking arrive as deltas and are
+ * joined to the entry before them of the same kind.
+ */
+export interface TranscriptEntry {
+    /** `diff`: a spec change the job is about to render, as a git diff. */
+    kind: "stage" | "spec" | "diff" | "prompt" | "text" | "thinking" | "tool" | "result";
+    text: string;
+    /** For a result: whether the tool failed. */
+    error?: boolean;
+    /** The whole of it, where `text` is clipped for the screen - a tool call's arguments, its result. */
+    full?: string;
+    /** Which agent it is from, e.g. "app 1 judge", and what it runs on - for a prompt, a reply, a thought, a tool call, a result. */
+    agent?: {
+        label: string;
+        model?: string;
+    };
+}
+export declare function reportTranscript(entry: TranscriptEntry): void;
+/** The part of a model response's usage a job adds up. */
+export interface UsageReport {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+}
+/**
+ * What a stage is about, said so the person knows what the name is: "module backend", or "module
+ * backend, functionality 2". A stage leads with it: `${unitOf(moduleName, frid)}: running the tests`.
+ */
+export declare function unitOf(moduleName: string, frid?: string): string;
+export declare function reportUsage(usage: UsageReport): void;
+/** What one agent of a job did, added to what it did before: counted by its label. */
+export interface AgentReport {
+    label: string;
+    model?: string;
+    turns?: number;
+    compactions?: number;
+    usage?: UsageReport;
+}
+/** Each agent of a job, as the job adds it up: how many turns it took, how often its work was compacted, what it cost. */
+export interface AgentTally {
+    label: string;
+    model?: string;
+    turns: number;
+    compactions: number;
+    usage: UsageReport;
+}
+export declare function reportAgent(report: AgentReport): void;
+/** Add one agent report to a job's tally, by label - its first report starts its row. */
+export declare function addAgentReport(tallies: AgentTally[], report: AgentReport): void;
+/** A job's agents, a line each: "app 1 reviewer · 3 turns · 1 compaction · 210.4k tok · $0.41". */
+export declare function describeAgents(tallies: AgentTally[]): string[];
+/** "1.2k tok · $0.03", or "" when nothing has been spent yet. */
+export declare function describeUsage(usage: UsageReport | undefined): string;
+/**
+ * Something an agent did with its model, wherever it ran - in a pulse or not, the planner and the chooser too: what a
+ * headless run's report adds up (run-report.ts). A call is one model response; a turn, one request of the harness's
+ * to an agent, as many calls as it takes; a compaction, its work summed up - a call of its own. A provider retry is a
+ * request the provider failed for a moment, waited out and tried again - by pi, or by turri after pi gave up; a provider
+ * stall, a request the provider has sent nothing back on for a long while; a stop, a turn turri itself ended - the
+ * agent going round in a circle, or its time up - after which the harness carries on as after any turn.
+ */
+export interface ModelEvent {
+    kind: "call" | "turn" | "compaction" | "provider_retry" | "provider_stall" | "stopped";
+    /** For a provider retry: what the provider said, the try this is and how many there may be, and the wait before it. For a stall, waitMs is how long it has been silent. */
+    error?: string;
+    attempt?: number;
+    of?: number;
+    waitMs?: number;
+    /** For a stop: why turri ended the turn. */
+    reason?: string;
+    /** "provider/model-id:thinking", when known. */
+    model?: string;
+    role?: string;
+    label?: string;
+    /** The job it was made for: none outside a pulse. */
+    job?: string;
+    usage?: UsageReport;
+    /** For a call: how long the model took to answer it, in milliseconds. */
+    ms?: number;
+}
+/** Hear of every model call, turn and compaction from now on. Returns what stops it. */
+export declare function onModelEvent(listener: (event: ModelEvent) => void): () => void;
+/**
+ * The model provider failing or stalling, in a line for the person: the chat's notification, a headless run's console.
+ * A turn turri stopped itself is the work going its normal course - kept in the activity, the pulse's log and the run
+ * report, not said.
+ */
+export declare function describeTurnIncident(event: ModelEvent): string | undefined;
+export declare function reportModelEvent(event: Omit<ModelEvent, "job">): void;
+export declare function withActivity<T>(sink: ActivitySink, run: () => Promise<T>): Promise<T>;
+export declare function reportStage(label: string): void;
+export declare function reportActivity(line: string): void;
+/** Say something about the machinery under the work: shown as activity, and kept in the job's log, which the activity is not. */
+export declare function reportNote(line: string): void;
+/** Say something for the job's log alone: the machinery, not what its agents are doing. */
+export declare function reportLogNote(line: string): void;
+export declare function reportNow(label: string | undefined, options?: {
+    keepSince?: boolean;
+}): void;
+/**
+ * Paths as they are inside `plain_modules`: everything up to and including it left out, wherever
+ * a path to it appears - `/Users/…/project/plain_modules/app/code/main.py` is `app/code/main.py`.
+ * The rest of the path is the same for every line, and is what pushes the part that differs off
+ * the end of it.
+ */
+export declare function withinModules(text: string): string;
+/** A tool's name as the person is shown it. */
+export declare function shownName(name: string): string;
+/** A tool call as one short line. Unknown tools still show up, by name. */
+export declare function describeToolCall(name: string, args: Record<string, unknown> | undefined): string;
+/** The outcome of a test run, or nothing for tools whose outcome is not worth a line. */
+export declare function describeToolResult(name: string, result: unknown, isError: boolean): string | undefined;

package/dist/regenerate/agent-env.d.ts

@@ -0,0 +1,44 @@
+/** The variables that locate a toolchain - their folders are what the OS sandbox lets a command read of the person's. */
+export declare const TOOLCHAIN_VARIABLES: string[];
+/** Where package managers keep their caches: in the project's scratch area, so a dependency downloads once. */
+export declare function packageCacheDir(dir: string): string;
+/** Every package manager's cache, pointed into `cache`. */
+export declare function cacheEnv(cache: string): Record<string, string>;
+/** A credential `agent-env:` names that is not there. */
+export interface MissingCredential {
+    /** The file or the variable. */
+    name: string;
+    why: string;
+}
+export interface AgentEnvironment {
+    /** The whole environment of an agent's command. */
+    env: Record<string, string>;
+    /** The names of what `agent-env:` passed, sorted - for the prompt, never the values. */
+    passed: string[];
+    /** The values `agent-env:` passed, by name - what is masked wherever turri shows or writes output. */
+    values: Record<string, string>;
+    /** What `agent-env:` names that is not there. */
+    missing: MissingCredential[];
+}
+/**
+ * The environment of a command an agent runs in `moduleDir` - `plain_modules/<module>`. `hostEnv`: the environment
+ * turri was started in; `home`: the person's home folder.
+ */
+export declare function agentEnvironment(moduleDir: string, options?: {
+    hostEnv?: NodeJS.ProcessEnv;
+    home?: string;
+}): AgentEnvironment;
+/**
+ * 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
+ * Mockito's inline mocks, jcmd and jstack attach through; the sandbox reaches this folder alone, never the person's
+ * JVMs' sockets beside it.
+ */
+export declare const DARWIN_TEMP_SUFFIX = "DIRHELPER_USER_DIR_SUFFIX";
+/** What `agent-env:` - the project's, with the chosen stack's added - passes, and what of it is not there. Reads only. */
+export declare function passedCredentials(module: string, hostEnv: NodeJS.ProcessEnv): {
+    values: Record<string, string>;
+    missing: MissingCredential[];
+};
+/** A dotenv file's variables: `KEY=value`, `export KEY=value`, quoted or not; comments and blank lines skipped. */
+export declare function parseDotenv(text: string): Record<string, string>;

package/dist/regenerate/agent-shell.d.ts

@@ -0,0 +1,49 @@
+import { type CheckResult } from "./command-check.ts";
+import { type Wall } from "./os-sandbox.ts";
+import { type RunResult } from "./shell.ts";
+/**
+ * An agent's command on this machine, behind every wall at once: the command check before it, the module's scrubbed
+ * environment and the OS sandbox around it - where one is up - and the audit after it. Built once per agent from its
+ * role's fence, the same as its file tools': what it may read and write.
+ */
+export interface ShellRole {
+    /** Where its commands start - the agent's folder. */
+    workdir: string;
+    /** The folders it may read; its workdir when not given. */
+    read?: string[];
+    /** The folders it may write; its workdir when not given, none for a role that only reads. */
+    write?: string[];
+}
+export interface AgentShell {
+    /** The wall under the check and the audit. */
+    readonly wall: Wall;
+    /** The environment its commands get. */
+    readonly env: Record<string, string>;
+    /** One line for the job log: which walls are up. */
+    readonly description: string;
+    /** The check alone: whether a command would be run. */
+    check(command: string): CheckResult;
+    /** How a command is run behind the wall. */
+    wrap(argv: string[]): string[];
+    /** Run a command behind every wall; refused, it is not run and says why (exit 126). */
+    run(command: string, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        onData?: (data: Buffer) => void;
+        timeoutNote?: (ms: number) => string;
+    }): Promise<RunResult>;
+    /** Run `work` - something that starts a command another way - under the audit; what it puts back, for the agent. */
+    audited<T>(work: () => Promise<T>): Promise<{
+        value: T;
+        note?: string;
+    }>;
+}
+/**
+ * What a module's shell writes beside its roots: its home, its TMPDIR, the package caches - and on macOS its own folder
+ * in the per-user temporary folder, where its JVMs keep the attach sockets Mockito's inline mocks and jcmd go through.
+ */
+export declare function writableFor(env: Record<string, string>, moduleDir: string): string[];
+export declare function agentShell(role: ShellRole, options?: {
+    wall?: Wall;
+    busy?: (moduleDir: string) => boolean;
+}): AgentShell;

package/dist/regenerate/arbiter.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The arbiter: the third voice in a review. The coding agent writes the tests; the reviewer - exacting,
+ * opinionated, hard to satisfy - sends them back with everything it finds; after the first review that sends
+ * them back, the arbiter weighs what each one found before any of it goes back. It is the distinguished engineer
+ * who balances the trade-offs: the tests have to be good, and time lost chasing perfect ones is lost too. It
+ * upholds a problem when the reviewer is right - a behaviour the spec states is untested, or a test cannot
+ * fail - and dismisses it when it is out of scope or a nitpick. Only what it upholds goes back; when it upholds
+ * nothing, the tests are approved as they are. Read-only, like the reviewer.
+ */
+/**
+ * How many reviews that send the work back go to the agent as they are: every one after them the arbiter weighs
+ * first, and only what it upholds goes back.
+ */
+export declare const ARBITER_AFTER = 1;
+/**
+ * How many reviews at most. What the last one sends back - weighed by the arbiter - goes to the agent once more, and
+ * then the work goes on without another review, once its tests pass.
+ */
+export declare const REVIEW_LIMIT = 2;
+/** A problem a review raised: in the unit tests or the conformance tests alike. */
+export interface ReviewedProblem {
+    file: string;
+    test?: string;
+    /** "wrong" is the code's: it does not do what the spec says. The unit review raises it; the conformance review does not. */
+    kind: "missing" | "bad" | "wrong";
+    what: string;
+    blocking?: boolean;
+}
+/** What the arbiter ruled: the problems it upholds, and those it lets go, each with why. */
+export interface ArbiterRuling<P extends ReviewedProblem = ReviewedProblem> {
+    upheld: Array<{
+        problem: P;
+        why: string;
+    }>;
+    dismissed: Array<{
+        problem: P;
+        why: string;
+    }>;
+}
+export interface ArbiterOptions<P extends ReviewedProblem> {
+    /** "the unit tests of functionality 3", "the conformance tests of the spec change". */
+    subject: string;
+    /** Where it works, and what it may read: the tests and the code. */
+    workdir: string;
+    read: string[];
+    /** When a problem is upheld: what the tests must do for this kind of review. */
+    uphold: string[];
+    /** The test files the work added or changed. */
+    changed: string[];
+    /** The specification the work built, as the reviewer had it - shown as it is given. */
+    spec: string;
+    /** What the work wrote: the diff of its folder from where it started (`workDiff`). */
+    code?: string;
+    /** The problems the latest review raised. */
+    problems: P[];
+    /** What each review before sent back, oldest first. */
+    history: P[][];
+    label: string;
+    model?: string;
+    onDelta?: (delta: string) => void;
+}
+export declare function problemLine(problem: ReviewedProblem): string;
+/** The arbiter's prompt: the spec, the reviews so far, and the latest one's problems, numbered. */
+export declare function arbiterPrompt<P extends ReviewedProblem>(options: Omit<ArbiterOptions<P>, "label" | "model" | "onDelta">): string;
+/** The arbiter's ruling on the latest review - or nothing, when it gave none: the review then stands. */
+export declare function arbitrateReview<P extends ReviewedProblem>(options: ArbiterOptions<P>): Promise<ArbiterRuling<P> | undefined>;
+/** What the arbiter let go, for the working notes' pitfalls. */
+export declare function dismissedNote(ruling: ArbiterRuling, what: string): string;