crewhaus 0.1.8 → 0.2.1

package/dist/fleet.js

@@ -0,0 +1,488 @@
+/**
+ * Item 58 — `crewhaus fleet`: the cross-harness view every other single-cwd
+ * command lacks. A team runs many harnesses (the Slack bot, the CLI
+ * concierge, the nightly optimizer) each in its own directory per the
+ * standalone-harness convention; `fleet` discovers them under a root and
+ * rolls their state up into one inventory / health table, and runs a safe
+ * read-only subcommand across the filtered set.
+ *
+ * Factored out of the entry file `index.ts` (which runs a top-level argv
+ * switch and so cannot be imported by a test without executing the CLI).
+ * Side-effect-free on import and directly unit-testable, mirroring
+ * `retention.ts` / `state-backup.ts` / `datasets.ts`:
+ *   - discovery + inventory aggregation are pure reads over seeded harness
+ *     dirs (no network, no subprocess);
+ *   - the bulk-run path launches per-harness `crewhaus` invocations through an
+ *     INJECTED runner seam (`FleetRunner`), so tests drive it without a real
+ *     CLI.
+ *
+ * DISCOVERY MODEL — a "harness" is any directory that carries a
+ * `crewhaus.yaml` (the spec file the standalone-harness convention roots a
+ * harness on). `discoverHarnesses(root)` walks `root` up to a bounded depth,
+ * records every dir with a `crewhaus.yaml`, and does NOT descend into a
+ * harness's own `.crewhaus/` state dir or into `node_modules` (a bundled
+ * template spec under `node_modules` is not a fleet member). The root itself
+ * counts when it carries a spec, so `fleet list` run from inside a single
+ * harness reports just that one.
+ *
+ * INVENTORY — per harness, aggregated purely from on-disk state the other
+ * commands already write:
+ *   - name / target / model: a lenient scan of `crewhaus.yaml` (a full
+ *     `parseSpec` can fail on schema drift, and a fleet scan must not die on
+ *     one stale spec — so name/target/model are read best-effort);
+ *   - registry version + env pins: `@crewhaus/spec-registry` manifest for the
+ *     spec name under `.crewhaus/specs`;
+ *   - last eval pass-rate: newest entry in `.crewhaus/evals/index.jsonl`
+ *     (`@crewhaus/eval-report`'s `readRunIndex`);
+ *   - session count: `sess_*.json` files under `.crewhaus/sessions`;
+ *   - feedback count: distinct records via `extractFeedbackRecords` over the
+ *     same sinks `crewhaus distill` reads (sessions + feedback jsonl).
+ *
+ * BULK OPS SAFETY — `fleet run <sub>` only accepts commands off an explicit
+ * READ-ONLY allow-list (`eval`, `doctor`, `security digest`, `audit verify`).
+ * A mutating command is refused unless `--allow-mutating` is passed AND a
+ * per-harness confirm callback approves each one — the CLI wires that to an
+ * interactive prompt, tests to a predicate. The bulk runner never itself
+ * mutates: it launches one `crewhaus <sub>` invocation per harness (cwd = the
+ * harness dir, the convention every subcommand resolves state from) and
+ * aggregates exit codes.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { extractFeedbackRecords, mergeFeedback } from "./feedback";
+/** The spec file that roots a standalone harness. */
+export const HARNESS_SPEC_FILENAME = "crewhaus.yaml";
+/** Depth cap for the discovery walk (root is depth 0). Deep monorepos still
+ *  resolve; a pathological tree can't hang the scan. */
+const MAX_DISCOVERY_DEPTH = 6;
+/** Directory names never descended into during discovery. */
+const DISCOVERY_SKIP_DIRS = new Set([
+    ".crewhaus",
+    "node_modules",
+    ".git",
+    "dist",
+    ".worktrees",
+]);
+/** Thrown for operational failures (missing root, empty filter, disallowed
+ *  bulk subcommand). The CLI entry file catches it and routes the message
+ *  through `die()`; tests assert on `.message` without the process exiting. */
+export class FleetError extends Error {
+    name = "FleetError";
+}
+/**
+ * Walk `root` for directories carrying a `crewhaus.yaml`, bounded to
+ * {@link MAX_DISCOVERY_DEPTH}. Never descends into `.crewhaus`, `node_modules`,
+ * `.git`, `dist`, or `.worktrees`. A directory that IS a harness is still
+ * descended into (a harness may nest sub-harnesses in a demo tree), just not
+ * through its state dir. Results are sorted by directory for stable output.
+ */
+export function discoverHarnesses(root) {
+    const absRoot = resolve(root);
+    if (!existsSync(absRoot) || !statSync(absRoot).isDirectory()) {
+        throw new FleetError(`no directory at ${absRoot} — nothing to scan for harnesses`);
+    }
+    const found = [];
+    const visit = (dir, depth) => {
+        const specPath = join(dir, HARNESS_SPEC_FILENAME);
+        if (existsSync(specPath) && statSync(specPath).isFile()) {
+            found.push({ dir, specPath });
+        }
+        if (depth >= MAX_DISCOVERY_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable dir — skip, don't abort the whole scan
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (DISCOVERY_SKIP_DIRS.has(entry.name))
+                continue;
+            visit(join(dir, entry.name), depth + 1);
+        }
+    };
+    visit(absRoot, 0);
+    found.sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));
+    return found;
+}
+/**
+ * Read `name`, `target`, and `model` from a `crewhaus.yaml` WITHOUT a full
+ * schema parse. A fleet scan must survive a stale/invalid spec (schema drift,
+ * a half-edited file), so this is a tolerant top-level-key scrape rather than
+ * `parseSpec`. `name`/`target` are top-level on every target shape; `model`
+ * lives at `agent.model` (cli/channel/voice) OR top-level `model`
+ * (workflow/graph/pipeline/crew) depending on the shape — the first
+ * `model:` at any indentation is taken. Values are unquoted and trimmed.
+ */
+export function readSpecHeader(yamlText) {
+    const topLevel = (key) => {
+        // `key:` at column 0 (top-level YAML mapping key).
+        const re = new RegExp(`^${key}:[ \\t]*(.*)$`, "m");
+        const m = re.exec(yamlText);
+        if (m === null)
+            return undefined;
+        return cleanScalar(m[1] ?? "");
+    };
+    const anyLevel = (key) => {
+        // `key:` at any indentation — for `model` under `agent:`.
+        const re = new RegExp(`^[ \\t]*${key}:[ \\t]*(.*)$`, "m");
+        const m = re.exec(yamlText);
+        if (m === null)
+            return undefined;
+        return cleanScalar(m[1] ?? "");
+    };
+    const name = topLevel("name");
+    const target = topLevel("target");
+    const model = topLevel("model") ?? anyLevel("model");
+    return {
+        ...(name !== undefined ? { name } : {}),
+        ...(target !== undefined ? { target } : {}),
+        ...(model !== undefined ? { model } : {}),
+    };
+}
+/** Strip surrounding quotes, an inline `# comment`, and whitespace from a
+ *  scalar. Returns undefined for an empty/block-scalar-only value. */
+function cleanScalar(raw) {
+    let s = raw.trim();
+    if (s === "" || s === "|" || s === ">" || s === "|-" || s === ">-")
+        return undefined;
+    const quote = s.startsWith('"') ? '"' : s.startsWith("'") ? "'" : undefined;
+    if (quote !== undefined) {
+        // Quoted value: take everything up to the closing quote (a `#` inside is
+        // data); anything after the close (e.g. ` # comment`) is dropped.
+        const close = s.indexOf(quote, 1);
+        if (close !== -1)
+            return s.slice(1, close);
+        // Unterminated quote — fall through to the unquoted handling.
+    }
+    const hash = s.indexOf(" #");
+    if (hash !== -1)
+        s = s.slice(0, hash).trim();
+    return s === "" ? undefined : s;
+}
+const SESSION_JSON_REGEX = /^sess_[0-9a-f]{16}\.json$/;
+/** Count `sess_<16hex>.json` files under `.crewhaus/sessions`. */
+export function countSessions(harnessDir) {
+    const dir = join(harnessDir, ".crewhaus", "sessions");
+    if (!existsSync(dir))
+        return 0;
+    let n = 0;
+    for (const f of readdirSync(dir)) {
+        if (SESSION_JSON_REGEX.test(f))
+            n += 1;
+    }
+    return n;
+}
+/** Parse a JSONL blob into objects, skipping blank/malformed lines. */
+function parseJsonlObjects(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // tolerated — one torn line must not hide the rest
+        }
+    }
+    return out;
+}
+/**
+ * Distinct feedback a harness carries, counted the way `crewhaus distill`
+ * folds it: `user_feedback` events in `sessions/*.jsonl` PLUS bare records in
+ * `feedback/*.jsonl` (`extractFeedbackRecords` accepts both encodings), then
+ * `mergeFeedback` collapses to one per (sessionId, turnNumber). The row shows
+ * distinct rated turns, not raw line count, so a re-rated turn counts once.
+ */
+export function countFeedback(harnessDir) {
+    const objects = [];
+    for (const sub of ["sessions", "feedback"]) {
+        const dir = join(harnessDir, ".crewhaus", sub);
+        if (!existsSync(dir))
+            continue;
+        for (const f of readdirSync(dir)) {
+            if (!f.endsWith(".jsonl"))
+                continue;
+            objects.push(...parseJsonlObjects(readFileSync(join(dir, f), "utf-8")));
+        }
+    }
+    return mergeFeedback(extractFeedbackRecords(objects)).length;
+}
+/** The newest run in an eval index, or undefined. Newest by `ts` (ISO-8601
+ *  lexical order is chronological). */
+export function lastEvalFor(evalEntries) {
+    let best;
+    for (const e of evalEntries) {
+        if (best === undefined || e.ts > best.ts)
+            best = e;
+    }
+    if (best === undefined)
+        return undefined;
+    return { datasetName: best.datasetName, passRate: best.passRate, ts: best.ts };
+}
+/**
+ * Aggregate one harness directory into an inventory row. All reads are
+ * tolerant: a missing state dir, an unregistered spec, or an unreadable spec
+ * file each degrade to an empty/absent field rather than throwing, so one
+ * broken harness never aborts a `fleet list`.
+ */
+export async function buildHarnessInventory(harness, deps) {
+    let header = {};
+    let specUnreadable = false;
+    try {
+        header = readSpecHeader(readFileSync(harness.specPath, "utf-8"));
+    }
+    catch {
+        specUnreadable = true;
+    }
+    const specName = header.name ?? basenameOf(harness.dir);
+    let registry = { pins: {} };
+    const manifest = await deps.readManifest(specName, join(harness.dir, ".crewhaus", "specs"));
+    if (manifest !== undefined) {
+        const latest = manifest.versions[manifest.versions.length - 1];
+        registry = {
+            ...(latest !== undefined ? { latestVersion: latest } : {}),
+            pins: manifest.pins,
+        };
+    }
+    const lastEval = lastEvalFor(deps.readEvalIndex(join(harness.dir, ".crewhaus", "evals")));
+    return {
+        dir: harness.dir,
+        header,
+        specName,
+        registry,
+        ...(lastEval !== undefined ? { lastEval } : {}),
+        sessionCount: countSessions(harness.dir),
+        feedbackCount: countFeedback(harness.dir),
+        specUnreadable,
+    };
+}
+function basenameOf(dir) {
+    const parts = dir.split(/[\\/]/).filter((p) => p !== "");
+    return parts[parts.length - 1] ?? dir;
+}
+/** Build the full fleet inventory for a root. */
+export async function buildFleetInventory(root, deps) {
+    const harnesses = discoverHarnesses(root);
+    const rows = [];
+    for (const h of harnesses) {
+        rows.push(await buildHarnessInventory(h, deps));
+    }
+    return rows;
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+/** Render the inventory as aligned columns for `fleet list`. */
+export function formatInventory(rows, root) {
+    if (rows.length === 0) {
+        return [`no harnesses (no ${HARNESS_SPEC_FILENAME}) found under ${resolve(root)}`];
+    }
+    const lines = [`${rows.length} harness(es) under ${resolve(root)}:`, ""];
+    for (const r of rows) {
+        const rel = relTo(root, r.dir);
+        lines.push(`• ${r.specName}${rel !== "" ? `  (${rel})` : ""}`);
+        const shape = r.header.target ?? "?";
+        const model = r.header.model ?? "?";
+        lines.push(`    shape=${shape} model=${model}`);
+        const ver = r.registry.latestVersion ?? "unregistered";
+        const pins = Object.entries(r.registry.pins);
+        const pinStr = pins.length === 0 ? "no pins" : pins.map(([e, v]) => `${e}→${v}`).join(", ");
+        lines.push(`    registry=${ver}  pins: ${pinStr}`);
+        if (r.lastEval !== undefined) {
+            lines.push(`    last eval: ${(r.lastEval.passRate * 100).toFixed(1)}% pass (${r.lastEval.datasetName}, ${r.lastEval.ts})`);
+        }
+        else {
+            lines.push("    last eval: none recorded");
+        }
+        lines.push(`    sessions=${r.sessionCount}  feedback=${r.feedbackCount}`);
+        if (r.specUnreadable)
+            lines.push("    ⚠ spec file unreadable");
+    }
+    return lines;
+}
+function relTo(root, dir) {
+    const absRoot = resolve(root);
+    const absDir = resolve(dir);
+    if (absDir === absRoot)
+        return ".";
+    if (absDir.startsWith(`${absRoot}/`))
+        return absDir.slice(absRoot.length + 1);
+    return absDir;
+}
+/** Count open incidents under `.crewhaus/incidents` (files not ending
+ *  `.resolved.json`). Absent dir → 0. The ops batch writes one JSON per
+ *  incident; a resolved one is renamed `<id>.resolved.json`. */
+export function countOpenIncidents(harnessDir) {
+    const dir = join(harnessDir, ".crewhaus", "incidents");
+    if (!existsSync(dir))
+        return 0;
+    let n = 0;
+    for (const f of readdirSync(dir)) {
+        if (f.endsWith(".json") && !f.endsWith(".resolved.json"))
+            n += 1;
+    }
+    return n;
+}
+export async function buildHarnessHealth(inv, readEvalHealth) {
+    const evalHealth = readEvalHealth(join(inv.dir, ".crewhaus", "evals"), inv.specName);
+    return {
+        dir: inv.dir,
+        specName: inv.specName,
+        registered: inv.registry.latestVersion !== undefined,
+        pinnedEnvs: Object.keys(inv.registry.pins).sort(),
+        evalHealthy: evalHealth.healthy,
+        evalNote: evalHealth.note,
+        openIncidents: countOpenIncidents(inv.dir),
+        hasAudit: existsSync(join(inv.dir, ".crewhaus", "audit")),
+    };
+}
+/** Render the health rollup as status lines for `fleet status`. */
+export function formatHealth(rows, root) {
+    if (rows.length === 0) {
+        return [`no harnesses found under ${resolve(root)}`];
+    }
+    const lines = [`fleet health — ${rows.length} harness(es) under ${resolve(root)}:`, ""];
+    for (const r of rows) {
+        const flags = [];
+        flags.push(r.registered ? "registered" : "unregistered");
+        flags.push(r.evalHealthy ? "eval:ok" : "eval:attention");
+        if (r.openIncidents > 0)
+            flags.push(`incidents:${r.openIncidents}`);
+        if (r.hasAudit)
+            flags.push("audit");
+        const mark = healthMark(r);
+        lines.push(`${mark} ${r.specName}`);
+        lines.push(`    ${flags.join("  ")}`);
+        lines.push(`    eval: ${r.evalNote}`);
+        if (r.pinnedEnvs.length > 0)
+            lines.push(`    pinned envs: ${r.pinnedEnvs.join(", ")}`);
+    }
+    const attention = rows.filter((r) => healthMark(r) !== "✓").length;
+    lines.push("");
+    lines.push(attention === 0
+        ? "summary: all harnesses healthy"
+        : `summary: ${attention} harness(es) need attention`);
+    return lines;
+}
+/** ✓ healthy / ✗ needs attention. Attention = an open incident, an eval
+ *  regression, or an unregistered harness that nonetheless has env pins
+ *  (a pin pointing at nothing registered). */
+export function healthMark(r) {
+    if (r.openIncidents > 0)
+        return "✗";
+    if (!r.evalHealthy)
+        return "✗";
+    if (!r.registered && r.pinnedEnvs.length > 0)
+        return "✗";
+    return "✓";
+}
+// ---------------------------------------------------------------------------
+// Bulk run (fleet run <sub> --filter <glob>)
+// ---------------------------------------------------------------------------
+/** Read-only / idempotent subcommands the bulk runner accepts without an
+ *  explicit opt-in. Each maps to a `crewhaus <argv...>` invocation. */
+export const READ_ONLY_BULK_COMMANDS = {
+    eval: ["eval"],
+    doctor: ["doctor"],
+    "security digest": ["security", "digest"],
+    "audit verify": ["audit", "verify"],
+};
+/**
+ * Resolve a `fleet run` subcommand + trailing args into a plan. Refuses
+ * anything off the read-only allow-list unless `allowMutating` is set. The
+ * longest allow-listed prefix wins, so `security digest` resolves ahead of a
+ * bare `security`.
+ */
+export function resolveBulkCommand(subcommandTokens, allowMutating) {
+    if (subcommandTokens.length === 0) {
+        throw new FleetError("missing subcommand — usage: crewhaus fleet run <eval|doctor|security digest|audit verify> [--filter <glob>]");
+    }
+    const joined2 = subcommandTokens.slice(0, 2).join(" ");
+    const joined1 = subcommandTokens[0];
+    const two = READ_ONLY_BULK_COMMANDS[joined2];
+    if (two !== undefined) {
+        return { argv: [...two, ...subcommandTokens.slice(2)], mutating: false };
+    }
+    const one = READ_ONLY_BULK_COMMANDS[joined1];
+    if (one !== undefined) {
+        return { argv: [...one, ...subcommandTokens.slice(1)], mutating: false };
+    }
+    if (!allowMutating) {
+        const allowed = Object.keys(READ_ONLY_BULK_COMMANDS).join(", ");
+        throw new FleetError(`"${joined1}" is not a read-only fleet subcommand (allowed: ${allowed}). Pass --allow-mutating to run a mutating command across the fleet (each harness will require confirmation).`);
+    }
+    return { argv: [...subcommandTokens], mutating: true };
+}
+/** Match a harness against a `--filter` glob, tested against BOTH the spec
+ *  name and the directory basename, so `--filter '*bot*'` catches either. */
+export function matchesFilter(inv, filter) {
+    if (filter === undefined)
+        return true;
+    const glob = new Bun.Glob(filter);
+    return glob.match(inv.specName) || glob.match(basenameOf(inv.dir));
+}
+/**
+ * Run one subcommand across the filtered fleet. Read-only commands run
+ * unconditionally on every matched harness; a mutating command (only reachable
+ * with `allowMutating`) runs a harness only when `confirm` approves it. The
+ * runner is the sole side-effect surface, injected for testability.
+ */
+export async function runFleetBulk(opts) {
+    const plan = resolveBulkCommand(opts.subcommandTokens, opts.allowMutating);
+    const inventory = await buildFleetInventory(opts.root, opts.deps);
+    const results = [];
+    let failed = 0;
+    let passed = 0;
+    let skipped = 0;
+    for (const inv of inventory) {
+        if (!matchesFilter(inv, opts.filter)) {
+            results.push({ inv, ran: false, skipReason: "filtered out" });
+            skipped += 1;
+            continue;
+        }
+        if (plan.mutating) {
+            const ok = await opts.confirm(inv, plan.argv);
+            if (!ok) {
+                results.push({ inv, ran: false, skipReason: "declined at confirm" });
+                skipped += 1;
+                continue;
+            }
+        }
+        const { exitCode, tail } = await opts.runner({ cwd: inv.dir, argv: plan.argv });
+        results.push({ inv, ran: true, exitCode, tail });
+        if (exitCode === 0)
+            passed += 1;
+        else
+            failed += 1;
+    }
+    return { plan, results, failed, passed, skipped };
+}
+/** Render a bulk-run report as summary lines for `fleet run`. */
+export function formatBulkReport(report) {
+    const cmd = report.plan.argv.join(" ");
+    const lines = [
+        `fleet run: crewhaus ${cmd}${report.plan.mutating ? " (mutating — confirmed per harness)" : ""}`,
+        "",
+    ];
+    for (const r of report.results) {
+        if (!r.ran) {
+            lines.push(`~ ${r.inv.specName} — skipped (${r.skipReason})`);
+            continue;
+        }
+        const mark = r.exitCode === 0 ? "✓" : "✗";
+        lines.push(`${mark} ${r.inv.specName} — exit ${r.exitCode}`);
+        const tail = (r.tail ?? "").trim();
+        if (tail !== "") {
+            for (const line of tail.split("\n").slice(-3))
+                lines.push(`    ${line}`);
+        }
+    }
+    lines.push("");
+    lines.push(`summary: ${report.passed} passed, ${report.failed} failed, ${report.skipped} skipped`);
+    return lines;
+}

package/dist/flywheel.d.ts

@@ -0,0 +1,193 @@
+import type { EvalRunSummary } from "@crewhaus/eval-runner";
+/** Thrown on invalid knobs/defaults and scaffold refusals. The CLI entry
+ *  file catches it and routes the message through `die()`; tests assert on
+ *  `.message` without the process exiting (mirrors DatasetRefError). */
+export declare class FlywheelConfigError extends Error {
+    readonly name = "FlywheelConfigError";
+}
+/**
+ * The demo's env knob names, kept verbatim for continuity — a repo that ran
+ * the EP01 `nightly-flywheel.sh` can point its existing workflow env at
+ * `crewhaus flywheel run` without renaming a secret or a variable.
+ */
+export declare const FLYWHEEL_ENV_KNOBS: {
+    readonly budgetUsd: "FLYWHEEL_BUDGET_USD";
+    readonly iterations: "FLYWHEEL_ITERATIONS";
+    readonly seed: "FLYWHEEL_SEED";
+    readonly concurrency: "FLYWHEEL_CONCURRENCY";
+};
+export type FlywheelKnobs = {
+    /** Hard USD ceiling for the optimizer's model-driven mutation calls. */
+    readonly budgetUsd: number;
+    readonly iterations: number;
+    readonly seed: number;
+    /** Eval fan-out. Default 1 keeps the loop under a low provider TPM tier
+     *  (the 30k-TPM default tier) — unattended jobs favour reliability. */
+    readonly concurrency: number;
+};
+/** Demo defaults: $2 cap, 3 iterations, seed 1 (reproducible PRs),
+ *  concurrency 1 (rate-limit-tier safe). */
+export declare const FLYWHEEL_DEFAULT_KNOBS: FlywheelKnobs;
+/**
+ * Resolve the run knobs with flag > FLYWHEEL_* env > default precedence.
+ * The env layer exists so the scaffolded workflow (and the EP01 demo's)
+ * can steer a run purely through repository variables/dispatch inputs.
+ */
+export declare function resolveFlywheelKnobs(opts: {
+    readonly flags: Readonly<Record<string, string | boolean>>;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}): FlywheelKnobs;
+export type FlywheelDataResolution = {
+    /** `--dataset` value to use (file path or `registry:` ref). */
+    readonly dataset: string;
+    /** `--graders` file path to use. */
+    readonly graders: string;
+    readonly datasetSource: "flag" | "convention" | "ratings-registry";
+    readonly gradersSource: "flag" | "convention";
+};
+/** The standalone-harness convention paths the flywheel defaults to. */
+export declare const CONVENTIONAL_DATASET: string;
+export declare const CONVENTIONAL_GRADERS: string;
+/**
+ * Resolve where the flywheel's dataset + graders come from when the flags
+ * are omitted: the standalone-harness convention (`eval/dataset.jsonl` /
+ * `eval/graders.yaml` beside the SPEC — resolved from the spec's directory,
+ * matching the dirty-check's spec-dir behavior, so `flywheel run
+ * path/to/crewhaus.yaml` from a sibling dir still finds the harness's own
+ * files; flag paths stay cwd-relative), and — when the spec declares a
+ * `feedback:` block and ratings have been distilled into the registry —
+ * the `registry:<spec>-ratings` dataset the autoDistill flywheel feeds.
+ */
+export declare function resolveFlywheelData(opts: {
+    readonly datasetFlag?: string;
+    readonly gradersFlag?: string;
+    readonly specName: string;
+    /** Directory the spec lives in — the base for the conventional paths. */
+    readonly specDir: string;
+    readonly hasConventionalDataset: boolean;
+    readonly hasConventionalGraders: boolean;
+    /** `registry:<specName>-ratings` has at least one version. */
+    readonly ratingsRegistered: boolean;
+}): FlywheelDataResolution;
+/** True when `git status --porcelain -- <spec>` reported any change. */
+export declare function specIsDirty(porcelain: string): boolean;
+export type FlywheelVerdict = {
+    readonly accepted: boolean;
+    readonly reason: string;
+    readonly passRateBefore: number;
+    readonly passRateAfter: number;
+    /** Sample-level pass→fail flips between the before and after runs. */
+    readonly regressions: number;
+    /** Sample-level fail→pass flips (what the accepted patch bought). */
+    readonly recoveries: number;
+};
+/**
+ * The flywheel's acceptance bar: BOTH conditions must hold —
+ *   (a) the strict run-history gate passes (`gateRuns`: any pass-rate drop
+ *       or sample-level pass→fail flip fails, even when recoveries cancel
+ *       it out in the aggregates), and
+ *   (b) pass_rate STRICTLY improved (a flat run passes the gate but is not
+ *       worth a write-back/PR — taste over averages, per the demo).
+ */
+export declare function evaluateFlywheelAcceptance(before: EvalRunSummary, after: EvalRunSummary): FlywheelVerdict;
+export declare function formatPassRate(rate: number): string;
+/** What the optimize step reports back (the orchestrator's result, narrowed
+ *  to what the flywheel needs). `applied` mirrors OptimizeSpecResult.applied:
+ *  improvement ≥ threshold — NOT the flywheel acceptance verdict. */
+export type FlywheelOptimizeOutcome = {
+    readonly applied: boolean;
+    /** The patched YAML, NOT yet written anywhere (accept-then-write). */
+    readonly patchedYaml: string;
+    readonly runId: string;
+    /** The optimize artifacts dir (patch.json / report.json / evals/). */
+    readonly outDir: string;
+    readonly scoreBefore: number;
+    readonly scoreAfter: number;
+    readonly mutatorName: string;
+    readonly iterations: number;
+    /** Formatted `$0.0000` spend total from the budget meter. */
+    readonly spendUsd: string;
+};
+export type FlywheelHooks = {
+    /** Offline parse→lower gate. Throws to fail the phase. */
+    readonly compileCheck: (yaml: string, phase: "pre-optimize" | "post-optimize") => void;
+    /** One full eval pass of `yaml` over the flywheel's dataset. */
+    readonly evalRun: (label: "before" | "after", yaml: string) => Promise<EvalRunSummary>;
+    /** The optimize search, run WITHOUT write-back. */
+    readonly optimize: () => Promise<FlywheelOptimizeOutcome>;
+    /** Apply the accepted patch: write-back + auto-register + regression pin. */
+    readonly applyAccepted: (outcome: FlywheelOptimizeOutcome) => Promise<void>;
+};
+export type FlywheelOutcome = "accepted" | "accepted-dry-run" | "rejected" | "no-improvement" | "patch-compile-failed";
+export type FlywheelRunResult = {
+    readonly outcome: FlywheelOutcome;
+    readonly reason: string;
+    readonly verdict?: FlywheelVerdict;
+    readonly before?: EvalRunSummary;
+    readonly after?: EvalRunSummary;
+    readonly optimize?: FlywheelOptimizeOutcome;
+};
+/**
+ * The complete loop with accept-then-write semantics. The source spec is
+ * only ever touched by `hooks.applyAccepted`, which runs exactly when the
+ * acceptance gate passed AND `dryRun` is false — every other path leaves
+ * the working tree byte-identical, so there is nothing to revert. A
+ * pre-optimize compile failure propagates (nothing was spent yet); a
+ * post-optimize compile failure maps to `"patch-compile-failed"` (the
+ * optimizer produced YAML the compiler rejects — an error, but the source
+ * is untouched).
+ */
+export declare function runFlywheelLoop(opts: {
+    readonly sourceYaml: string;
+    readonly dryRun: boolean;
+    readonly hooks: FlywheelHooks;
+}): Promise<FlywheelRunResult>;
+/** One-screen flywheel report, printed after every run. */
+export declare function formatFlywheelReport(result: FlywheelRunResult, extras: {
+    readonly specPath: string;
+    readonly datasetName: string;
+    readonly sampleCount: number;
+    readonly budgetUsd: number;
+    readonly artifactsDir: string;
+}): string[];
+export declare const FLYWHEEL_WORKFLOW_RELPATH: string;
+export type ScaffoldResult = {
+    readonly path: string;
+    readonly action: "wrote";
+};
+/**
+ * Write a workflow scaffold, refusing to overwrite an existing file unless
+ * `force` (shared by `flywheel init` and `init --ci`). Throws
+ * FlywheelConfigError on refusal so the CLI maps it to a clean `die()`.
+ */
+export declare function scaffoldWorkflowFile(opts: {
+    readonly rootDir: string;
+    readonly relPath: string;
+    readonly content: string;
+    readonly force: boolean;
+}): ScaffoldResult;
+/**
+ * Normalize a repo-root-relative harness dir for embedding in a scaffolded
+ * workflow: POSIX separators, no leading `./`, no trailing slash; "" means
+ * the harness IS the repo root. Shared by both workflow builders.
+ */
+export declare function normalizeHarnessDir(dir: string | undefined): string;
+/**
+ * The GitHub Actions schedule, adapted from the EP01 demo's
+ * `concierge-flywheel.yml`: nightly cron + manual dispatch, budget knobs as
+ * FLYWHEEL_* env, PR creation via `gh` for HUMAN review. It never merges on
+ * its own, and `crewhaus flywheel run` never writes an unaccepted patch, so
+ * every change that reaches the default branch passed both the acceptance
+ * gate and a human.
+ *
+ * `harnessDir` (repo-root-relative, "" = root) points the job's
+ * working-directory at a nested harness AND prefixes the artifact upload
+ * `path:` — actions paths resolve from the repo root and do NOT honor
+ * `defaults.run.working-directory` (finding 7).
+ */
+export declare function buildFlywheelWorkflowYaml(opts?: {
+    readonly harnessDir?: string;
+}): string;
+/** Printed after `flywheel init` (and folded into `flywheel --help`): the
+ *  env knobs the scaffolded workflow steers the run with. */
+export declare function formatFlywheelKnobsGuide(): string[];