promigence 0.1.0-beta.12

package/dist/init.js

@@ -0,0 +1,352 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const LOCKFILES = [
+    ["bun.lock", "bun"], ["bun.lockb", "bun"],
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["package-lock.json", "npm"],
+    ["uv.lock", "uv"],
+    ["poetry.lock", "poetry"],
+    ["Pipfile.lock", "pipenv"],
+    ["requirements.txt", "pip"],
+    ["pyproject.toml", "pyproject"],
+    ["Cargo.lock", "cargo"],
+    ["go.sum", "go"], ["go.mod", "go"],
+    ["Gemfile.lock", "bundler"],
+    ["composer.lock", "composer"],
+];
+const SCRIPT_PRIORITY = ["typecheck", "type-check", "tsc", "check", "test", "lint", "build"];
+const NODE_INSTALL = {
+    bun: "bun install --frozen-lockfile",
+    pnpm: "pnpm install --frozen-lockfile",
+    yarn: "yarn install --immutable",
+    npm: "npm ci",
+};
+const NODE_RUN = {
+    bun: "bun run", pnpm: "pnpm run", yarn: "yarn run", npm: "npm run",
+};
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function pythonVerify(dir, run) {
+    const has = (f) => existsSync(join(dir, f));
+    if (has("mypy.ini") || (has("pyproject.toml") && /\[tool\.mypy\]/.test(readFileSync(join(dir, "pyproject.toml"), "utf8"))))
+        return { verify: `${run} mypy .`, why: "mypy is configured" };
+    if (has("tests") || has("test") || has("pytest.ini") || has("conftest.py"))
+        return { verify: `${run} pytest -q`, why: "a pytest suite is present" };
+    return { verify: `${run} python -c 'import sys; print(sys.version)'`, why: "no test suite found — replace this with the command that must pass" };
+}
+export function detect(dir) {
+    const hit = LOCKFILES.find(([f]) => existsSync(join(dir, f)));
+    const ecosystem = hit?.[1] ?? "unknown";
+    const lockfile = ecosystem === "pyproject" ? undefined : hit?.[0];
+    if (ecosystem === "bun" || ecosystem === "pnpm" || ecosystem === "yarn" || ecosystem === "npm") {
+        const pkg = readJson(join(dir, "package.json"));
+        const scripts = (pkg?.scripts ?? {});
+        const picked = SCRIPT_PRIORITY.find((s) => typeof scripts[s] === "string");
+        const run = NODE_RUN[ecosystem];
+        const toolchain = ecosystem === "bun" ? ["bun"] : ["node", ecosystem === "npm" ? "npm" : ecosystem];
+        return {
+            ecosystem,
+            ...(lockfile ? { lockfile } : {}),
+            setup: [NODE_INSTALL[ecosystem]],
+            verify: picked ? `${run} ${picked}` : `${run} test`,
+            toolchain,
+            why: picked
+                ? `package.json has a "${picked}" script`
+                : 'package.json declares no typecheck/check/test script — "test" is a guess; override with --verify',
+        };
+    }
+    switch (ecosystem) {
+        case "uv": {
+            const v = pythonVerify(dir, "uv run");
+            return { ecosystem, ...(lockfile ? { lockfile } : {}), setup: ["uv sync --frozen"], verify: v.verify, toolchain: ["uv", "python3"], why: v.why };
+        }
+        case "poetry": {
+            const v = pythonVerify(dir, "poetry run");
+            return { ecosystem, ...(lockfile ? { lockfile } : {}), setup: ["poetry install --no-interaction --no-ansi"], verify: v.verify, toolchain: ["poetry", "python3"], why: v.why };
+        }
+        case "pipenv": {
+            const v = pythonVerify(dir, "pipenv run");
+            return { ecosystem, ...(lockfile ? { lockfile } : {}), setup: ["pipenv sync"], verify: v.verify, toolchain: ["pipenv", "python3"], why: v.why };
+        }
+        case "pip": {
+            const v = pythonVerify(dir, ".venv/bin/python -m");
+            return {
+                ecosystem, ...(lockfile ? { lockfile } : {}),
+                setup: ["python3 -m venv .venv", ".venv/bin/pip install --no-input -r requirements.txt"],
+                verify: v.verify.replace(".venv/bin/python -m python -c", ".venv/bin/python -c"),
+                toolchain: ["python3"], why: v.why,
+            };
+        }
+        case "pyproject": {
+            const v = pythonVerify(dir, ".venv/bin/python -m");
+            const pytest = v.verify.includes("pytest") ? " pytest" : "";
+            return {
+                ecosystem,
+                setup: ["python3 -m venv .venv", `.venv/bin/pip install --no-input -e '.[test]'${pytest}`],
+                verify: v.verify.replace(".venv/bin/python -m python -c", ".venv/bin/python -c"),
+                toolchain: ["python3"],
+                why: `pyproject.toml with no lockfile: installed with pip, editable; ${v.why}`,
+            };
+        }
+        case "cargo":
+            return {
+                ecosystem, ...(lockfile ? { lockfile } : {}),
+                setup: ["cargo fetch --locked"],
+                verify: "cargo check --locked --all-targets",
+                toolchain: ["cargo", "rustc"],
+                why: "cargo check is the cheapest command that proves the tree builds",
+            };
+        case "go":
+            return {
+                ecosystem, ...(lockfile ? { lockfile } : {}),
+                setup: ["go mod download"],
+                verify: "go build ./...",
+                toolchain: ["go"],
+                why: "go build ./... is the cheapest command that proves the tree builds",
+            };
+        case "bundler":
+            return {
+                ecosystem, ...(lockfile ? { lockfile } : {}),
+                setup: ["bundle install --jobs 4"],
+                verify: existsSync(join(dir, "spec")) ? "bundle exec rspec" : "bundle exec rake test",
+                toolchain: ["ruby", "bundle"], why: existsSync(join(dir, "spec")) ? "a spec/ directory is present" : "no spec/ — rake test is a guess; override with --verify",
+            };
+        case "composer":
+            return {
+                ecosystem, ...(lockfile ? { lockfile } : {}),
+                setup: ["composer install --no-interaction --no-progress"],
+                verify: "composer run-script test",
+                toolchain: ["php", "composer"], why: "composer's declared test script",
+            };
+        default:
+            return {
+                ecosystem: "unknown",
+                setup: [],
+                verify: "",
+                toolchain: [],
+                why: "no lockfile found (bun/pnpm/yarn/npm, uv/poetry/pipenv/pip/pyproject.toml, cargo, go, bundler, composer)",
+            };
+    }
+}
+function git(dir, args) {
+    try {
+        return execFileSync("git", ["-C", dir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function stripRemoteCredentials(url) {
+    const bare = url.replace(/[?#].*$/, "");
+    const m = /^([a-z][a-z0-9+.-]*:\/\/)([^/?#]*)@([^/?#]*)(.*)$/i.exec(bare);
+    if (!m)
+        return bare;
+    const [, scheme, userinfo, host, rest] = m;
+    const user = /ssh:\/\/$/i.test(scheme) ? userinfo.split(":")[0] ?? "" : "";
+    return `${scheme}${user ? `${user}@` : ""}${host}${rest}`;
+}
+export function normalizeRemote(url) {
+    const ssh = /^ssh:\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/(.+?)(?:\.git)?\/?$/i.exec(url);
+    if (ssh)
+        return `https://${ssh[1]}/${ssh[2]}`;
+    const scp = /^(?:ssh:\/\/)?(?:[\w.-]+)@([\w.-]+):(.+?)(?:\.git)?\/?$/.exec(url);
+    if (scp)
+        return `https://${scp[1]}/${scp[2]}`;
+    return stripRemoteCredentials(url).replace(/\.git$/, "").replace(/\/$/, "");
+}
+export function gitFacts(dir) {
+    const out = {};
+    const remote = git(dir, ["config", "--get", "remote.origin.url"]);
+    if (remote) {
+        out.repo = normalizeRemote(remote);
+        if (stripRemoteCredentials(remote) !== remote)
+            out.credentialsRemoved = true;
+    }
+    const commit = git(dir, ["rev-parse", "HEAD"]);
+    if (commit && /^[0-9a-f]{40}$/.test(commit))
+        out.commit = commit;
+    const branch = git(dir, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (branch)
+        out.branch = branch;
+    const status = git(dir, ["status", "--porcelain"]);
+    if (status !== undefined)
+        out.dirty = status.length > 0;
+    else if (commit)
+        out.dirty = false;
+    if (out.commit) {
+        const remotes = git(dir, ["for-each-ref", "--count=1", "--format=%(refname)", "refs/remotes"]);
+        if (remotes) {
+            const containing = git(dir, ["branch", "-r", "--contains", out.commit]);
+            out.onRemote = containing !== undefined && containing.trim().length > 0;
+        }
+        else if (remote) {
+            out.onRemote = false;
+            out.noRemoteRefs = true;
+        }
+    }
+    return out;
+}
+export const INIT_IMAGES = {
+    bun: "node:22", pnpm: "node:22", yarn: "node:22", npm: "node:22",
+    uv: "python:3.12", poetry: "python:3.12", pipenv: "python:3.12", pip: "python:3.12", pyproject: "python:3.12",
+    cargo: "rust:1", go: "golang:1.23", bundler: "ruby:3.3", composer: "composer:2",
+};
+const PREP_STEP = {
+    bun: "npm install -g bun", pnpm: "corepack enable", yarn: "corepack enable",
+    uv: "pip install uv", poetry: "pip install poetry", pipenv: "pip install pipenv",
+};
+const COMMAND_TOOLS = [
+    [/^bunx?$/, "bun"], [/^pnpm$/, "pnpm"], [/^yarn$/, "yarn"], [/^(npm|npx|node)$/, "npm"],
+    [/^uv$/, "uv"], [/^poetry$/, "poetry"], [/^pipenv$/, "pipenv"],
+    [/^(pip|python)(3(\.\d+)?)?$|^pytest$/, "pip"],
+    [/^cargo$/, "cargo"], [/^go$/, "go"], [/^(bundle|ruby|rake)$/, "bundler"], [/^(composer|php)$/, "composer"],
+];
+export function ecosystemOfCommands(commands) {
+    for (const c of commands) {
+        for (const part of c.split(/&&|\|\||[;|]/)) {
+            const words = part.trim().split(/\s+/).filter((w) => w && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(w));
+            while (words[0] === "sudo" || words[0] === "env" || words[0] === "exec")
+                words.shift();
+            const prog = words[0]?.split("/").at(-1);
+            if (!prog || prog === "cd")
+                continue;
+            const hit = COMMAND_TOOLS.find(([re]) => re.test(prog));
+            if (hit)
+                return hit[1];
+        }
+    }
+    return undefined;
+}
+export function imageCreateCommand(c, ecosystem) {
+    const image = INIT_IMAGES[ecosystem] ?? "buildpack-deps:bookworm";
+    const prep = PREP_STEP[ecosystem];
+    return [
+        "promigence snapshot create",
+        `--image ${image}`,
+        `--setup ${JSON.stringify(`git clone ${c.repo} /work/repo && git -C /work/repo checkout ${c.commit}`)}`,
+        ...(prep ? [`--setup ${JSON.stringify(prep)}`] : []),
+        ...c.setup.map((s) => `--setup ${JSON.stringify(`cd /work/repo && ${s}`)}`),
+        `--verify ${JSON.stringify(`cd /work/repo && ${c.verify}`)}`,
+        ...(c.tier ? [`--tier ${c.tier}`] : []),
+        "--wait",
+    ].join(" ");
+}
+const tomlString = (s) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+const tomlArray = (a) => `[${a.map(tomlString).join(", ")}]`;
+export function readConfig(text) {
+    const out = {};
+    const lines = text.split(/\r?\n/);
+    for (let n = 0; n < lines.length; n++) {
+        const line = lines[n].trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        if (line.startsWith("["))
+            break;
+        const bad = (why) => new Error(`line ${n + 1}: ${why}`);
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            throw bad("not `key = value`");
+        const key = line.slice(0, eq).trim();
+        let at = eq + 1;
+        const rest = line;
+        const skipWs = () => { while (at < rest.length && (rest[at] === " " || rest[at] === "\t"))
+            at++; };
+        const readString = () => {
+            if (rest[at] !== '"')
+                throw bad(`\`${key}\` is not a quoted string`);
+            let v = "";
+            for (at++; at < rest.length; at++) {
+                const c = rest[at];
+                if (c === '"') {
+                    at++;
+                    return v;
+                }
+                if (c === "\\") {
+                    const e = rest[++at];
+                    if (e === "\\" || e === '"')
+                        v += e;
+                    else if (e === "n")
+                        v += "\n";
+                    else if (e === "t")
+                        v += "\t";
+                    else
+                        throw bad(`unsupported escape \\${e ?? ""} in \`${key}\``);
+                }
+                else
+                    v += c;
+            }
+            throw bad(`unterminated string in \`${key}\``);
+        };
+        skipWs();
+        let value;
+        if (rest[at] === "[") {
+            const items = [];
+            at++;
+            for (;;) {
+                skipWs();
+                if (rest[at] === "]") {
+                    at++;
+                    break;
+                }
+                items.push(readString());
+                skipWs();
+                if (rest[at] === ",") {
+                    at++;
+                    continue;
+                }
+                if (rest[at] === "]") {
+                    at++;
+                    break;
+                }
+                throw bad(`\`${key}\` is not a one-line array of strings`);
+            }
+            value = items;
+        }
+        else {
+            value = readString();
+        }
+        skipWs();
+        if (at < rest.length && rest[at] !== "#")
+            throw bad(`unexpected text after \`${key}\``);
+        if (key === "setup") {
+            if (!Array.isArray(value))
+                throw bad("`setup` is an array of commands");
+            out.setup = value;
+        }
+        else if (key === "repo" || key === "commit" || key === "tier" || key === "alias" || key === "verify") {
+            if (typeof value !== "string")
+                throw bad(`\`${key}\` is a string`);
+            out[key] = value;
+        }
+    }
+    return out;
+}
+export function renderConfig(c, notes = [], build) {
+    const lines = [
+        "# promigence.toml — the environment this repo forks from.",
+        "# Written by `promigence init`. Build it with the image form init printed (building straight",
+        "# from a repository is not open in this beta):",
+        `#   ${build ?? "promigence snapshot create --image IMAGE --setup 'git clone REPO /work/repo && git -C /work/repo checkout COMMIT' --verify 'cd /work/repo && VERIFY' --wait"}`,
+        ...notes.map((n) => `# ${n}`),
+        "",
+        `repo = ${tomlString(c.repo)}`,
+        "# A branch is not a pin: this is the 40-character sha the snapshot is built at.",
+        `commit = ${tomlString(c.commit)}`,
+        `tier = ${tomlString(c.tier)}`,
+    ];
+    if (c.alias)
+        lines.push(`alias = ${tomlString(c.alias)}`);
+    lines.push("", "# Ordered; each must exit 0.", `setup = ${tomlArray(c.setup)}`, "", "# The command that decides whether the snapshot exists at all. If it does not exit 0,", "# nothing is stored (the build's time is billed).", `verify = ${tomlString(c.verify)}`, "", "[guards]", "# Checked by the builder before anything is stored. A failed guard names itself.", `toolchain_present = ${tomlArray(c.toolchain)}`);
+    if (c.lockfile)
+        lines.push(`lockfile_unchanged = ${tomlString(c.lockfile)}`);
+    lines.push("install_sane = true", "verify_warm_ratio = true", "");
+    return lines.join("\n");
+}

package/dist/install.d.ts

@@ -0,0 +1,23 @@
+export declare const FENCE_BEGIN = "<!-- promigence:begin -->";
+export declare const FENCE_END = "<!-- promigence:end -->";
+export declare const FENCE_MAX_LINES = 8;
+export declare function fenceBody(): string;
+export interface Artifact {
+    path: string;
+    kind: "fence" | "file";
+    action: "created" | "updated" | "unchanged" | "would-create" | "would-update" | "skipped";
+    reason?: string;
+    diff: string[];
+}
+export interface InstallResult {
+    dir: string;
+    artifacts: Artifact[];
+    changed: boolean;
+    memoryFile?: string;
+}
+export declare function spliceFence(text: string, fence: string): string;
+export declare function install(dir: string, { write, create }: {
+    write: boolean;
+    create: boolean;
+}): InstallResult;
+export declare function installLines(res: InstallResult, checking: boolean): string[];

package/dist/install.js

@@ -0,0 +1,127 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { renderGuide } from "./guide.js";
+import { DOCS_URL, GOLDEN_PATH, LIVE_SUMMARY, VERSION, WAIT_TIMEOUT_DEFAULT } from "./surface.js";
+export const FENCE_BEGIN = "<!-- promigence:begin -->";
+export const FENCE_END = "<!-- promigence:end -->";
+export const FENCE_MAX_LINES = 8;
+export function fenceBody() {
+    return [
+        FENCE_BEGIN,
+        `## Promigence (promigence@${VERSION}) — run \`promigence agent-guide\` before using this tool`,
+        "Environment runtime: `verify → snapshot → fork(N) → exec → validity report`, billed per second.",
+        `Golden path: \`${GOLDEN_PATH}\``,
+        "Always `--json` (one envelope: `ok`, `error{code,message,fix}`, `next[]`) and always `--cap USD`.",
+        `Exits: 3 = env (ours, replayable) · 4 = task (yours) · 5 = over --cap · 11 = wait expired (${WAIT_TIMEOUT_DEFAULT}, nothing killed).`,
+        "Never put a key on argv: `auth login` takes `--from-env VAR` or stdin; `secrets set` also `--from-file P`.",
+        FENCE_END,
+    ].join("\n");
+}
+const MEMORY_CANDIDATES = ["AGENTS.md", "CLAUDE.md"];
+function skillMd() {
+    return [
+        "---",
+        "name: promigence",
+        `description: >-`,
+        `  Run verified, reproducible, forkable execution environments with the promigence CLI: fork N`,
+        `  sandboxes from a verified snapshot, exec a command in each, and read the validity report`,
+        `  that separates environment failures from task failures. Use whenever a task needs many`,
+        `  identical, disposable, pre-built repo environments (evals, RL rollouts, batch verification).`,
+        "---",
+        "",
+        renderGuide(),
+    ].join("\n");
+}
+function cursorMdc() {
+    return [
+        "---",
+        "description: promigence — verified, forkable execution environments (environment runtime)",
+        "alwaysApply: true",
+        "---",
+        "",
+        renderGuide(),
+    ].join("\n");
+}
+export function spliceFence(text, fence) {
+    const begin = text.indexOf(FENCE_BEGIN);
+    const end = text.indexOf(FENCE_END);
+    if (begin >= 0 && end > begin) {
+        return text.slice(0, begin) + fence + text.slice(end + FENCE_END.length);
+    }
+    if (text === "")
+        return fence + "\n";
+    const sep = text.endsWith("\n\n") ? "" : text.endsWith("\n") ? "\n" : "\n\n";
+    return text + sep + fence + "\n";
+}
+function diffLines(before, after, cap = 40) {
+    if (before === after)
+        return [];
+    const a = before === "" ? [] : before.split("\n");
+    const b = after.split("\n");
+    let head = 0;
+    while (head < a.length && head < b.length && a[head] === b[head])
+        head++;
+    let tail = 0;
+    while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail])
+        tail++;
+    const removed = a.slice(head, a.length - tail).map((l) => `-${l}`);
+    const added = b.slice(head, b.length - tail).map((l) => `+${l}`);
+    const out = [`@@ line ${head + 1} @@`, ...removed, ...added];
+    return out.length <= cap ? out : [...out.slice(0, cap), `… ${out.length - cap} more lines`];
+}
+function plan(dir, rel, kind, want, write, create) {
+    const full = join(dir, rel);
+    const exists = existsSync(full);
+    const before = exists ? readFileSync(full, "utf8") : "";
+    const after = kind === "fence" ? spliceFence(before, want) : want;
+    const diff = diffLines(before, after, kind === "fence" ? 40 : 4);
+    if (!diff.length)
+        return { path: rel, kind, action: "unchanged", diff };
+    if (!write)
+        return { path: rel, kind, action: exists ? "would-update" : "would-create", diff };
+    if (!exists && !create && kind === "file")
+        mkdirSync(dirname(full), { recursive: true });
+    else if (!exists)
+        mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, after);
+    return { path: rel, kind, action: exists ? "updated" : "created", diff };
+}
+export function install(dir, { write, create }) {
+    const artifacts = [];
+    const fence = fenceBody();
+    const found = MEMORY_CANDIDATES.filter((f) => existsSync(join(dir, f)));
+    const targets = found.length ? found : create ? ["AGENTS.md"] : [];
+    if (!targets.length) {
+        artifacts.push({
+            path: MEMORY_CANDIDATES.join(" / "),
+            kind: "fence",
+            action: "skipped",
+            reason: "neither AGENTS.md nor CLAUDE.md exists; pass --create to write AGENTS.md",
+            diff: [],
+        });
+    }
+    for (const f of targets)
+        artifacts.push(plan(dir, f, "fence", fence, write, create));
+    artifacts.push(plan(dir, join(".claude", "skills", "promigence", "SKILL.md"), "file", skillMd(), write, create));
+    artifacts.push(plan(dir, join(".cursor", "rules", "promigence.mdc"), "file", cursorMdc(), write, create));
+    const memory = targets[0];
+    return {
+        dir,
+        artifacts,
+        changed: artifacts.some((a) => a.action !== "unchanged" && a.action !== "skipped"),
+        ...(memory ? { memoryFile: memory } : {}),
+    };
+}
+export function installLines(res, checking) {
+    const lines = [`${checking ? "promigence agent-guide --check" : "promigence agent-guide --install"}: ${relative(process.cwd(), res.dir) || "."}`];
+    for (const a of res.artifacts) {
+        lines.push(`  ${a.action.padEnd(12)} ${a.path}${a.reason ? ` (${a.reason})` : ""}`);
+        for (const d of a.diff)
+            lines.push(`    ${d}`);
+    }
+    if (!res.changed)
+        lines.push("  already current — nothing written");
+    lines.push(`  guide: promigence agent-guide · ${DOCS_URL}`);
+    lines.push(`  live: ${LIVE_SUMMARY}`);
+    return lines;
+}

package/dist/io.d.ts

@@ -0,0 +1,37 @@
+import { PromigenceError, type AccountNotice, type ForkStats, type GradeStats, type ReportSandbox, type RunReport, type Totals } from "./sdk/index.js";
+import { type Envelope, type NextHint } from "./surface.js";
+export type Mode = "json" | "text";
+export declare const seenGuide: () => boolean;
+export declare function markGuideSeen(): void;
+export declare function isGoneReader(code: string | undefined): boolean;
+export declare function writeBytes(stream: NodeJS.WriteStream, data: Uint8Array): Promise<void>;
+export declare function write(stream: NodeJS.WriteStream, text: string): Promise<void>;
+export declare function setBeforeExit(fn: (() => Promise<unknown>) | undefined): void;
+export declare function exitWith(code: number): Promise<never>;
+export declare function recordNotice(n: AccountNotice): void;
+export declare function noticeLine(n: AccountNotice): string;
+export declare const PLACEHOLDER: RegExp;
+export declare function emit(mode: Mode, env: Envelope, textLines: string[], exit: number, pointer: boolean, textTo?: "payload" | "stderr"): Promise<never>;
+export declare function okEnvelope(command: string, fields: Record<string, unknown>, next: NextHint[]): Envelope;
+export declare function noCommandFix(example: string, platform?: NodeJS.Platform): string;
+export declare function usageError(message: string, fix: string): PromigenceError;
+export declare const USAGE_DOCS = "https://www.promigence.ai/docs/errors#usage";
+export declare function overMost(flag: string, given: string, most: number, mostText: string, page?: boolean): number;
+export declare function toPromigenceError(err: unknown): PromigenceError;
+export declare function errorEnvelope(command: string, err: PromigenceError, next: NextHint[]): Envelope;
+export declare function errorTextLines(command: string, err: PromigenceError, exit: number, next: NextHint[]): string[];
+export declare function pickExit(codes: readonly number[]): number;
+export declare function parseDuration(value: string, flag: string): number;
+export declare function parseCommandTimeout(value: string, flag: string): number;
+export declare function parseCount(value: string, flag: string): number;
+export declare function parseUsd(value: string, flag: string): number;
+export declare const MAX_OUTPUT_CEILING: number;
+export declare function parseMaxOutput(value: string, flag?: string): number;
+export declare function parseBytes(value: string, flag: string): number;
+export declare const ms: (n: number | undefined) => string;
+export declare function forkLine(fork: ForkStats | undefined): string;
+export declare function totalsLine(t: Totals | undefined): string;
+export declare function forkSummary(fork: ForkStats | undefined): Record<string, unknown>;
+export declare function reportSummaryLines(report: RunReport): string[];
+export declare function sandboxGrade(s: Pick<ReportSandbox, "passed" | "score" | "holdout_passed" | "holdout_score">): string;
+export declare function gradeLine(g: GradeStats | undefined): string | undefined;