@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/core/retry-budget/budget.js

@@ -0,0 +1,284 @@
+/**
+ * — Per-command tool retry budget (the upstream tool parity).
+ *
+ * the upstream tool limits the number of times the model may retry the SAME
+ * tool with the SAME arguments inside a single operator-input cycle.
+ * Once the cap is hit, the dispatcher hard-refuses and surfaces a
+ * sentinel string telling the model that this exact call has exhausted
+ * its retry budget. The model is expected (via system-prompt rule) to
+ * either change approach or ask the operator for guidance instead of
+ * looping forever on a transient failure.
+ *
+ * Why per-cycle, not per-session: a retry budget that persists across
+ * operator turns would surprise the operator. After the operator says
+ * "try again" the model rightly retries; the budget must reset when a
+ * fresh brief arrives. The simplest reset boundary is the executor
+ * lifetime — `buildExecutor` is called once per `runEngineLoop` and
+ * the loop drives exactly one operator-input cycle. Constructing the
+ * budget inside `buildExecutor` therefore gives us per-cycle scoping
+ * "for free" via closure lifetime; no external clear() call is needed
+ * from production callsites. The exported `clear()` exists so tests
+ * and a future hook surface (PreToolUse) can introspect the state.
+ *
+ * Hash design: same tool + same canonical args = same bucket. We
+ * canonicalise the args record by sorting object keys (stable across
+ * model output ordering) and then sha256 the JSON. The model emits
+ * `arguments` as a raw JSON string; we parse, canonicalise, hash. If
+ * parse fails we hash the raw string verbatim — that way an
+ * unparseable repeat still counts toward the cap (otherwise the model
+ * could loop on syntactic noise variants forever).
+ *
+ * Env overrides:
+ *  PUGI_RETRY_BUDGET_<TOOLNAME>=<N>  — override a single tool's cap.
+ *                                       Toolname matches DEFAULT_CAPS
+ *                                       keys verbatim, uppercased
+ *                                       (PUGI_RETRY_BUDGET_BASH=8).
+ *  PUGI_RETRY_BUDGET_DEFAULT=<N>     — override the fallback cap for
+ *                                       any tool not in DEFAULT_CAPS.
+ *  PUGI_RETRY_BUDGET_DISABLED=1      — warn-only mode. `shouldAllow`
+ *                                       still records but always
+ *                                       returns `allowed: true`. The
+ *                                       count is preserved so
+ *                                       diagnostics can still surface
+ *                                       the pattern.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Default per-tool retry caps. Tuned per the upstream behavior :
+ *
+ *  bash      — 5 (most volatile; transient flakes common)
+ *  edit      — 3 (deterministic; repeat = real bug)
+ *  write     — 3 (same)
+ *  read      — 10 (cheap; legitimate re-reads after edits)
+ *  search/grep/glob — 10 (cheap; exploration loop)
+ *  web_fetch — 5 (transient network; not infinite)
+ *  default   — 5 (any tool not in the table)
+ *
+ * Operators override per-tool via `PUGI_RETRY_BUDGET_<NAME>` env vars.
+ * Caps are bounded `[1, 1000]` after override to defend against typo
+ * runaway (e.g. `PUGI_RETRY_BUDGET_BASH=5000000`).
+ */
+export const DEFAULT_CAPS = Object.freeze({
+    bash: 5,
+    edit: 3,
+    write: 3,
+    read: 10,
+    search: 10,
+    grep: 10,
+    glob: 10,
+    web_fetch: 5,
+    default: 5,
+});
+/**
+ * Lower / upper bound for any resolved cap. Defends against:
+ *  - PUGI_RETRY_BUDGET_BASH=0    -> first call instantly denied
+ *  - PUGI_RETRY_BUDGET_BASH=99999 -> effectively unbounded loop
+ */
+export const MIN_CAP = 1;
+export const MAX_CAP = 1000;
+/**
+ * Per-cycle retry budget. One instance per `buildExecutor` call.
+ *
+ * Not thread-safe: the executor is single-threaded by construction
+ * (Node event loop + sequential await in dispatcher). If a future
+ * executor parallelises tool dispatch it must serialise the budget
+ * mutation explicitly.
+ */
+export class RetryBudget {
+    counts = new Map();
+    capCache = new Map();
+    env;
+    programmaticCaps;
+    constructor(options = {}) {
+        this.env = options.env ?? process.env;
+        this.programmaticCaps = options.caps ?? {};
+    }
+    /**
+     * Returns true when PUGI_RETRY_BUDGET_DISABLED=1. In disabled mode
+     * `shouldAllow` still records attempts but always allows the
+     * dispatch — useful for operators triaging a false-positive without
+     * a code change.
+     */
+    isDisabled() {
+        return this.env.PUGI_RETRY_BUDGET_DISABLED === '1';
+    }
+    /**
+     * Record one dispatch attempt. Idempotent on the bucket key (tool
+     * + argHash). Call this BEFORE the dispatch (or after `shouldAllow`
+     * but before `dispatch()` resolves) so a thrown dispatch counts.
+     */
+    recordAttempt(toolName, argHash) {
+        const key = `${toolName}::${argHash}`;
+        const next = (this.counts.get(key) ?? 0) + 1;
+        this.counts.set(key, next);
+        return next;
+    }
+    /**
+     * Returns the current count for (tool, argHash) WITHOUT mutating.
+     */
+    peek(toolName, argHash) {
+        return this.counts.get(`${toolName}::${argHash}`) ?? 0;
+    }
+    /**
+     * Resolve the effective cap for a tool.
+     *
+     * Precedence:
+     *  1. PUGI_RETRY_BUDGET_<TOOL_UPPER>=<N> (env)
+     *  2. programmaticCaps[toolName]         (constructor)
+     *  3. DEFAULT_CAPS[toolName]             (this module)
+     *  4. PUGI_RETRY_BUDGET_DEFAULT=<N>      (env fallback)
+     *  5. DEFAULT_CAPS.default               (final fallback)
+     *
+     * Bounded by [MIN_CAP, MAX_CAP] post-resolution. Invalid (NaN, ≤0,
+     * non-integer) env values are ignored and the next layer wins.
+     */
+    capFor(toolName) {
+        const cached = this.capCache.get(toolName);
+        if (cached !== undefined)
+            return cached;
+        const envKey = `PUGI_RETRY_BUDGET_${toolName.toUpperCase()}`;
+        const envCap = parseCapEnv(this.env[envKey]);
+        const programmaticCap = this.programmaticCaps[toolName];
+        const defaultCap = DEFAULT_CAPS[toolName];
+        const fallbackEnvCap = parseCapEnv(this.env.PUGI_RETRY_BUDGET_DEFAULT);
+        // DEFAULT_CAPS.default is hard-coded above; cast keeps the type-
+        // narrower happy without leaking `| undefined` through the index
+        // access (tsc cannot prove the literal key exists).
+        const finalFallback = DEFAULT_CAPS.default;
+        let resolved;
+        if (envCap !== undefined) {
+            resolved = envCap;
+        }
+        else if (programmaticCap !== undefined) {
+            resolved = programmaticCap;
+        }
+        else if (defaultCap !== undefined) {
+            resolved = defaultCap;
+        }
+        else {
+            resolved = fallbackEnvCap ?? finalFallback;
+        }
+        const bounded = Math.min(MAX_CAP, Math.max(MIN_CAP, resolved));
+        this.capCache.set(toolName, bounded);
+        return bounded;
+    }
+    /**
+     * Should this dispatch be allowed? Caller passes the current count
+     * BEFORE recording — i.e. shouldAllow returns true when count < cap,
+     * then recordAttempt fires, bringing count up to cap. The next
+     * identical call sees count === cap and is refused.
+     *
+     * In disabled mode `allowed` is forced to true; `count` and `cap`
+     * still reflect reality so logs / diagnostics can spot the pattern.
+     */
+    shouldAllow(toolName, argHash) {
+        const cap = this.capFor(toolName);
+        const count = this.peek(toolName, argHash);
+        const disabled = this.isDisabled();
+        const allowed = disabled ? true : count < cap;
+        return { allowed, count, cap, argHash, disabled };
+    }
+    /** Reset all state. Used between operator-input cycles when the
+     * budget instance is reused (most callers throw the instance away
+     * per cycle, so clear() is mostly for tests and hook surfaces). */
+    clear() {
+        this.counts.clear();
+        this.capCache.clear();
+    }
+    /**
+     * Snapshot the current state for diagnostics. Returns a plain
+     * object so it round-trips through JSON.stringify cleanly.
+     */
+    snapshot() {
+        const out = [];
+        for (const [key, count] of this.counts) {
+            const sep = key.indexOf('::');
+            if (sep < 0)
+                continue;
+            out.push({ tool: key.slice(0, sep), argHash: key.slice(sep + 2), count });
+        }
+        return out;
+    }
+}
+/**
+ * Hash the model's tool-call arguments into a stable key. Same
+ * canonical args = same hash regardless of JSON whitespace / key
+ * order. Unparseable JSON is hashed verbatim so the budget still
+ * catches syntactically degenerate retry loops.
+ */
+export function hashArgs(argsRaw) {
+    const canonical = canonicalise(argsRaw);
+    return createHash('sha256').update(canonical).digest('hex');
+}
+/**
+ * Canonicalise a raw JSON arg string. Object keys are sorted
+ * recursively. Arrays preserve order (semantic). Primitives untouched.
+ * On parse failure, returns the original string prefixed with `raw:`
+ * so a malformed-args repeat still hashes to the same bucket.
+ */
+function canonicalise(argsRaw) {
+    try {
+        const parsed = JSON.parse(argsRaw);
+        return JSON.stringify(sortKeys(parsed));
+    }
+    catch {
+        return `raw:${argsRaw}`;
+    }
+}
+function sortKeys(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    const obj = value;
+    const sorted = {};
+    for (const k of Object.keys(obj).sort()) {
+        sorted[k] = sortKeys(obj[k]);
+    }
+    return sorted;
+}
+/**
+ * Parse and bound a `PUGI_RETRY_BUDGET_*` env var. Returns `undefined`
+ * for any non-positive-integer string so the resolver can fall
+ * through to the next precedence layer. Bounded by [MIN_CAP, MAX_CAP]
+ * is NOT applied here — `capFor` clamps after the final layer wins,
+ * matching the "operator typo defends against runaway" requirement
+ * without silently swallowing a meaningful low value (e.g.
+ * `PUGI_RETRY_BUDGET_BASH=1` should clamp to MIN_CAP=1, which it
+ * does naturally since 1 >= MIN_CAP).
+ */
+function parseCapEnv(raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0)
+        return undefined;
+    return n;
+}
+/**
+ * Sentinel emitted to the model when the budget is exhausted. The
+ * format is stable so the engine adapter, spec layer, and operator
+ * dashboards can pattern-match on it.
+ */
+export function retryBudgetExhaustedSentinel(toolName, cap) {
+    return `RETRY_BUDGET_EXHAUSTED: ${toolName} exceeded ${cap} attempts with these args. Operator must intervene.`;
+}
+/**
+ * Typed error thrown by the tool-bridge when the cap is hit. Carries
+ * the sentinel string so the engine loop can pattern-match without
+ * re-parsing. `instanceof RetryBudgetExhausted` is the canonical
+ * downstream test.
+ */
+export class RetryBudgetExhausted extends Error {
+    toolName;
+    cap;
+    argHash;
+    constructor(toolName, cap, argHash) {
+        super(retryBudgetExhaustedSentinel(toolName, cap));
+        this.name = 'RetryBudgetExhausted';
+        this.toolName = toolName;
+        this.cap = cap;
+        this.argHash = argHash;
+    }
+}
+//# sourceMappingURL=budget.js.map

package/dist/core/retry-budget/index.js

@@ -0,0 +1,5 @@
+/**
+ * — Tool retry budget. Public surface.
+ */
+export { DEFAULT_CAPS, MIN_CAP, MAX_CAP, RetryBudget, RetryBudgetExhausted, hashArgs, retryBudgetExhaustedSentinel, } from './budget.js';
+//# sourceMappingURL=index.js.map

package/dist/core/retry-budget/retry-cap.js

@@ -0,0 +1,74 @@
+const DEFAULT_CAP = 3;
+const DEFAULT_RESET_AFTER_MS = 300_000;
+export function createRetryBudget(options = {}) {
+    const cap = normalizePositiveInteger(options.cap, DEFAULT_CAP);
+    const resetAfterMs = normalizeNonNegativeInteger(options.resetAfterMs, DEFAULT_RESET_AFTER_MS);
+    const states = new Map();
+    function clone(state) {
+        return { ...state };
+    }
+    function getFreshState(operationKey, now = Date.now()) {
+        const state = states.get(operationKey);
+        if (!state)
+            return null;
+        if (now - state.lastAttemptAt >= resetAfterMs) {
+            states.delete(operationKey);
+            return null;
+        }
+        return state;
+    }
+    return {
+        record(operationKey) {
+            const now = Date.now();
+            const existing = getFreshState(operationKey, now);
+            const attempts = (existing?.attempts ?? 0) + 1;
+            const next = {
+                operationKey,
+                attempts,
+                firstAttemptAt: existing?.firstAttemptAt ?? now,
+                lastAttemptAt: now,
+                exhausted: attempts >= cap,
+            };
+            states.set(operationKey, next);
+            return clone(next);
+        },
+        reset(operationKey) {
+            states.delete(operationKey);
+        },
+        isExhausted(operationKey) {
+            return getFreshState(operationKey)?.exhausted ?? false;
+        },
+        getState(operationKey) {
+            const state = getFreshState(operationKey);
+            return state ? clone(state) : null;
+        },
+    };
+}
+export function validatePromptWordCount(text, opts) {
+    const words = countWords(text);
+    const chars = text.length;
+    if (opts.min !== undefined && words < opts.min) {
+        return { valid: false, words, chars, reason: 'too-short' };
+    }
+    if (opts.max !== undefined && words > opts.max) {
+        return { valid: false, words, chars, reason: 'too-long' };
+    }
+    return { valid: true, words, chars };
+}
+function countWords(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return 0;
+    return trimmed.split(/\s+/).length;
+}
+function normalizePositiveInteger(value, fallback) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.max(1, Math.floor(value));
+}
+function normalizeNonNegativeInteger(value, fallback) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.max(0, Math.floor(value));
+}
+//# sourceMappingURL=retry-cap.js.map

package/dist/core/routing/lead-worker.js

@@ -0,0 +1,43 @@
+export function assignRoles(opts) {
+    let hasAssignedWriteLead = false;
+    return opts.steps.map((step) => {
+        const role = assignRole(step, hasAssignedWriteLead);
+        if (step.intent === 'write' && role.role === 'lead') {
+            hasAssignedWriteLead = true;
+        }
+        return {
+            step: step.id,
+            role: role.role,
+            model: role.role === 'lead' ? opts.leadModel : opts.workerModel,
+            reason: role.reason,
+        };
+    });
+}
+function assignRole(step, hasAssignedWriteLead) {
+    if (step.intent === 'plan') {
+        return { role: 'lead', reason: 'planning step requires lead orchestration' };
+    }
+    if (hasLeadHeuristic(step.id)) {
+        return { role: 'lead', reason: 'step id indicates planning or orchestration' };
+    }
+    if (step.intent === 'write' && !hasAssignedWriteLead) {
+        return { role: 'lead', reason: 'first write step needs lead architecture' };
+    }
+    if (step.intent === 'write') {
+        return { role: 'worker', reason: 'subsequent write step is bulk execution' };
+    }
+    if (step.intent === 'read' || step.intent === 'verify') {
+        return { role: 'worker', reason: 'read and verify steps are worker execution' };
+    }
+    if (step.intent === 'explain') {
+        return { role: 'worker', reason: 'explanation step can run on worker model' };
+    }
+    return { role: 'lead', reason: 'unknown intent defaults to lead defensively' };
+}
+function hasLeadHeuristic(stepId) {
+    const normalized = stepId.toLowerCase();
+    return (normalized.includes('plan') ||
+        normalized.includes('design') ||
+        normalized.includes('orchestrate'));
+}
+//# sourceMappingURL=lead-worker.js.map

package/dist/core/routing/pre-flight-estimator.js

@@ -0,0 +1,108 @@
+/**
+ * Pre-flight token estimator — Nuekkis tokenEstimation port,
+ * adapted for Anvil's 3-tier routing.
+ *
+ * The auto-compact gate counts tokens AFTER a turn lands. This module
+ * runs BEFORE the request leaves the CLI so the router can pick the
+ * cheapest pool that still fits. Three pools exist:
+ *
+ *  cheap    → DeepSeek V4-Pro / Cerebras Qwen3-Coder (128k-256k window)
+ *  mid      → Anthropic Sonnet 4.6 / GPT-5 (200k window, 2-3× cheap-pool cost)
+ *  long     → Kimi K2.6 / Gemini 2.5 Pro (1M window, 5-10× cheap-pool cost)
+ *
+ * The estimator is intentionally synchronous, pure, and free of I/O so
+ * the call site can run it inside a render loop without yielding to
+ * the event loop. The token approximation reuses the existing
+ * char-per-token heuristic from `core/compact/token-counter.ts` (4 chars
+ * ≈ 1 token, biased high). No tiktoken dependency added.
+ */
+import { estimateTokens } from '../compact/token-counter.js';
+/**
+ * Default tier ceilings tuned для Anvil 2026-06 routing matrix.
+ * cheap-pool models (DeepSeek/Cerebras) hard-cap at 100k effective input.
+ * mid-pool (Sonnet/GPT-5) safe through 180k.
+ * long-pool (Kimi/Gemini-Pro) accepts к 900k.
+ *
+ * The numbers stay below the nominal context window к leave room for
+ * output tokens, тек streaming overhead, and tokenizer skew.
+ */
+const DEFAULT_CHEAP_MAX = 100_000;
+const DEFAULT_MID_MAX = 180_000;
+const DEFAULT_LONG_MAX = 900_000;
+const DEFAULT_OUTPUT_BUFFER = 4_096;
+export function estimatePreFlight(input, options = {}) {
+    const cheapMax = options.cheapTierMaxInput ?? DEFAULT_CHEAP_MAX;
+    const midMax = options.midTierMaxInput ?? DEFAULT_MID_MAX;
+    const longMax = options.longTierMaxInput ?? DEFAULT_LONG_MAX;
+    const outputBuffer = input.expectedOutputTokens
+        ?? options.outputBuffer
+        ?? DEFAULT_OUTPUT_BUFFER;
+    if (cheapMax <= 0 || midMax <= 0 || longMax <= 0) {
+        throw new RangeError('tier max values must be positive');
+    }
+    if (cheapMax > midMax || midMax > longMax) {
+        throw new RangeError('tier ceilings must be monotonic: cheap <= mid <= long');
+    }
+    if (outputBuffer < 0) {
+        throw new RangeError('outputBuffer must be >= 0');
+    }
+    const systemTokens = sumStrings(input.systemPrompt ? [input.systemPrompt] : []);
+    const dialogTokens = sumStrings(input.dialogHistory ?? []);
+    const ragTokens = sumStrings(input.ragContext ?? []);
+    const toolTokens = sumStrings(input.toolResults ?? []);
+    const userTokens = sumStrings(input.userMessage ? [input.userMessage] : []);
+    const inputTokens = systemTokens + dialogTokens + ragTokens + toolTokens + userTokens;
+    const totalTokens = inputTokens + outputBuffer;
+    const tier = pickTier(inputTokens, cheapMax, midMax);
+    const overLongTier = inputTokens > longMax;
+    return {
+        inputTokens,
+        outputBuffer,
+        totalTokens,
+        tier,
+        breakdown: {
+            systemPrompt: systemTokens,
+            dialogHistory: dialogTokens,
+            ragContext: ragTokens,
+            toolResults: toolTokens,
+            userMessage: userTokens,
+        },
+        overLongTier,
+    };
+}
+function sumStrings(parts) {
+    let total = 0;
+    for (const part of parts) {
+        total += estimateTokens(part);
+    }
+    return total;
+}
+function pickTier(inputTokens, cheapMax, midMax) {
+    if (inputTokens <= cheapMax)
+        return 'cheap';
+    if (inputTokens <= midMax)
+        return 'mid';
+    return 'long';
+}
+/**
+ * Human-readable explanation для CLI / TUI surfacing.
+ * The format is stable and may be parsed by the doctor command.
+ */
+export function explainEstimate(estimate) {
+    const lines = [];
+    lines.push(`Input tokens: ${estimate.inputTokens.toLocaleString('en-US')}`);
+    lines.push(`Output buffer: ${estimate.outputBuffer.toLocaleString('en-US')}`);
+    lines.push(`Total: ${estimate.totalTokens.toLocaleString('en-US')}`);
+    lines.push(`Routing tier: ${estimate.tier}`);
+    if (estimate.overLongTier) {
+        lines.push('WARNING: input exceeds long-tier ceiling — request will likely fail');
+    }
+    lines.push('Breakdown:');
+    lines.push(` system prompt: ${estimate.breakdown.systemPrompt.toLocaleString('en-US')}`);
+    lines.push(` dialog:        ${estimate.breakdown.dialogHistory.toLocaleString('en-US')}`);
+    lines.push(` rag:           ${estimate.breakdown.ragContext.toLocaleString('en-US')}`);
+    lines.push(` tool results:  ${estimate.breakdown.toolResults.toLocaleString('en-US')}`);
+    lines.push(` user message:  ${estimate.breakdown.userMessage.toLocaleString('en-US')}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=pre-flight-estimator.js.map

package/dist/core/runs/run-tree.js

@@ -0,0 +1,103 @@
+/**
+ * Canonical `.pugi/runs/<id>/` artifact tree .
+ *
+ * Karpathy hn-time-capsule pattern: every Pugi execution produces a
+ * deterministic directory structure where downstream tooling (eval
+ * harness, leaderboard, replay, debugging) can find
+ * artifacts at predictable paths.
+ *
+ * Layout per run:
+ *  .pugi/runs/<id>/
+ *    meta.json      — metadata: id, startedAt, finishedAt?, command, tier
+ *    stdout.log     — captured stdout (the engine writes it directly)
+ *    stderr.log     — captured stderr
+ *    events.jsonl   — structured event stream (NDJSON)
+ *    metrics.json   — final metrics summary (written at run end)
+ *    artifacts/     — арbitrary file outputs (plans, diffs, exports)
+ *
+ * The `<id>` is `<ISO-timestamp>-<short-rand>` so runs sort
+ * chronologically when listed by directory order.
+ *
+ * This module only handles the directory + metadata primitive. Actual
+ * stream writing (stdout.log, events.jsonl) is the engine's job —
+ * we return paths so the engine knows where к write.
+ */
+import { mkdir, writeFile, readFile, stat } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+export function generateRunId(now = new Date()) {
+    const iso = now.toISOString().replace(/[:.]/g, '-');
+    const rand = randomBytes(3).toString('hex');
+    return `${iso}-${rand}`;
+}
+export function resolveRunPaths(workspaceRoot, id) {
+    const root = path.join(workspaceRoot, '.pugi', 'runs', id);
+    return {
+        root,
+        meta: path.join(root, 'meta.json'),
+        stdout: path.join(root, 'stdout.log'),
+        stderr: path.join(root, 'stderr.log'),
+        events: path.join(root, 'events.jsonl'),
+        metrics: path.join(root, 'metrics.json'),
+        artifacts: path.join(root, 'artifacts'),
+    };
+}
+export async function createRun(options) {
+    if (!options.workspaceRoot) {
+        throw new TypeError('workspaceRoot is required');
+    }
+    const id = options.id ?? generateRunId();
+    if (!/^[A-Za-z0-9_.\-T:Z]+$/.test(id)) {
+        throw new RangeError(`invalid run id: ${id} (forbidden characters)`);
+    }
+    const paths = resolveRunPaths(options.workspaceRoot, id);
+    await mkdir(paths.artifacts, { recursive: true });
+    const meta = {
+        id,
+        startedAt: new Date().toISOString(),
+    };
+    if (options.command !== undefined)
+        meta.command = options.command;
+    if (options.tier !== undefined)
+        meta.tier = options.tier;
+    if (options.extra !== undefined)
+        meta.extra = options.extra;
+    await writeFile(paths.meta, JSON.stringify(meta, null, 2) + '\n');
+    return paths;
+}
+export async function readRunMetadata(paths) {
+    try {
+        const buf = await readFile(paths.meta, 'utf8');
+        return JSON.parse(buf);
+    }
+    catch {
+        return null;
+    }
+}
+export async function finalizeRun(paths, options = {}) {
+    const existing = await readRunMetadata(paths);
+    if (!existing) {
+        throw new Error(`run metadata missing at ${paths.meta}`);
+    }
+    const finished = {
+        ...existing,
+        finishedAt: new Date().toISOString(),
+    };
+    if (options.exitCode !== undefined) {
+        finished.exitCode = options.exitCode;
+    }
+    await writeFile(paths.meta, JSON.stringify(finished, null, 2) + '\n');
+    if (options.metrics !== undefined) {
+        await writeFile(paths.metrics, JSON.stringify(options.metrics, null, 2) + '\n');
+    }
+}
+export async function runExists(paths) {
+    try {
+        const stats = await stat(paths.root);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=run-tree.js.map