@pimmesz/afterburner 1.0.1

package/dist/core/index.d.ts

@@ -0,0 +1,781 @@
+import { z, ZodError } from 'zod';
+
+declare const configDir: string;
+declare const dataDir: string;
+declare function defaultRunStorePath(): string;
+/**
+ * Claude Code's config directory. CLAUDE_CONFIG_DIR relocates the whole tree
+ * (settings.json, skills/, projects/), so everything that reads or writes
+ * under ~/.claude must honor it or it targets a directory Claude Code ignores.
+ */
+declare function claudeConfigDir(): string;
+
+declare const TASK_CATEGORIES: readonly ["security", "tests", "types-lint", "dead-code", "perf", "infra", "docs"];
+type TaskCategory = (typeof TASK_CATEGORIES)[number];
+interface TaskCategoryInfo {
+    description: string;
+    /** How a human reviewer confirms the task is actually done. */
+    verifiabilityCheck: string;
+}
+declare const TASK_TAXONOMY: Record<TaskCategory, TaskCategoryInfo>;
+
+declare const DEFAULT_MODEL_BY_CATEGORY: Record<TaskCategory, string>;
+declare const repoConfigSchema: z.ZodObject<{
+    url: z.ZodString;
+    defaultBranch: z.ZodDefault<z.ZodString>;
+    branchPrefix: z.ZodDefault<z.ZodString>;
+    enabledTaskCategories: z.ZodArray<z.ZodEnum<{
+        security: "security";
+        tests: "tests";
+        "types-lint": "types-lint";
+        "dead-code": "dead-code";
+        perf: "perf";
+        infra: "infra";
+        docs: "docs";
+    }>>;
+}, z.core.$strip>;
+declare const budgetConfigSchema: z.ZodPrefault<z.ZodObject<{
+    provider: z.ZodDefault<z.ZodEnum<{
+        manual: "manual";
+        "claude-code-transcripts": "claude-code-transcripts";
+        "claude-usage": "claude-usage";
+    }>>;
+    weeklyAllowanceSonnetTokens: z.ZodDefault<z.ZodNumber>;
+    usageCacheMaxAgeHours: z.ZodDefault<z.ZodNumber>;
+    minWeeklyHeadroomPct: z.ZodDefault<z.ZodNumber>;
+    safetyMarginTokens: z.ZodDefault<z.ZodNumber>;
+    requireSessionAvailable: z.ZodDefault<z.ZodBoolean>;
+    manual: z.ZodDefault<z.ZodObject<{
+        sessionAvailable: z.ZodDefault<z.ZodBoolean>;
+        weeklyRemainingPct: z.ZodDefault<z.ZodNumber>;
+        weeklyRemainingTokensEst: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+declare const agentConfigSchema: z.ZodPrefault<z.ZodObject<{
+    backend: z.ZodDefault<z.ZodEnum<{
+        "dry-run": "dry-run";
+        "claude-code": "claude-code";
+        "api-key": "api-key";
+    }>>;
+    modelByCategory: z.ZodPipe<z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+        security: "security";
+        tests: "tests";
+        "types-lint": "types-lint";
+        "dead-code": "dead-code";
+        perf: "perf";
+        infra: "infra";
+        docs: "docs";
+    }> & z.core.$partial, z.ZodString>>, z.ZodTransform<{
+        security: string;
+        tests: string;
+        "types-lint": string;
+        "dead-code": string;
+        perf: string;
+        infra: string;
+        docs: string;
+    }, Partial<Record<"security" | "tests" | "types-lint" | "dead-code" | "perf" | "infra" | "docs", string>>>>;
+    maxTaskTokens: z.ZodDefault<z.ZodNumber>;
+    allowFable: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>>;
+declare const configSchema: z.ZodObject<{
+    repos: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        defaultBranch: z.ZodDefault<z.ZodString>;
+        branchPrefix: z.ZodDefault<z.ZodString>;
+        enabledTaskCategories: z.ZodArray<z.ZodEnum<{
+            security: "security";
+            tests: "tests";
+            "types-lint": "types-lint";
+            "dead-code": "dead-code";
+            perf: "perf";
+            infra: "infra";
+            docs: "docs";
+        }>>;
+    }, z.core.$strip>>>;
+    budget: z.ZodPrefault<z.ZodObject<{
+        provider: z.ZodDefault<z.ZodEnum<{
+            manual: "manual";
+            "claude-code-transcripts": "claude-code-transcripts";
+            "claude-usage": "claude-usage";
+        }>>;
+        weeklyAllowanceSonnetTokens: z.ZodDefault<z.ZodNumber>;
+        usageCacheMaxAgeHours: z.ZodDefault<z.ZodNumber>;
+        minWeeklyHeadroomPct: z.ZodDefault<z.ZodNumber>;
+        safetyMarginTokens: z.ZodDefault<z.ZodNumber>;
+        requireSessionAvailable: z.ZodDefault<z.ZodBoolean>;
+        manual: z.ZodDefault<z.ZodObject<{
+            sessionAvailable: z.ZodDefault<z.ZodBoolean>;
+            weeklyRemainingPct: z.ZodDefault<z.ZodNumber>;
+            weeklyRemainingTokensEst: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    schedule: z.ZodPrefault<z.ZodObject<{
+        cron: z.ZodDefault<z.ZodString>;
+        timezone: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    agent: z.ZodPrefault<z.ZodObject<{
+        backend: z.ZodDefault<z.ZodEnum<{
+            "dry-run": "dry-run";
+            "claude-code": "claude-code";
+            "api-key": "api-key";
+        }>>;
+        modelByCategory: z.ZodPipe<z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+            security: "security";
+            tests: "tests";
+            "types-lint": "types-lint";
+            "dead-code": "dead-code";
+            perf: "perf";
+            infra: "infra";
+            docs: "docs";
+        }> & z.core.$partial, z.ZodString>>, z.ZodTransform<{
+            security: string;
+            tests: string;
+            "types-lint": string;
+            "dead-code": string;
+            perf: string;
+            infra: string;
+            docs: string;
+        }, Partial<Record<"security" | "tests" | "types-lint" | "dead-code" | "perf" | "infra" | "docs", string>>>>;
+        maxTaskTokens: z.ZodDefault<z.ZodNumber>;
+        allowFable: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    taskCategories: z.ZodPipe<z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+        security: "security";
+        tests: "tests";
+        "types-lint": "types-lint";
+        "dead-code": "dead-code";
+        perf: "perf";
+        infra: "infra";
+        docs: "docs";
+    }> & z.core.$partial, z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        weight: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>>, z.ZodTransform<{
+        security: {
+            enabled: boolean;
+            weight: number;
+        };
+        tests: {
+            enabled: boolean;
+            weight: number;
+        };
+        "types-lint": {
+            enabled: boolean;
+            weight: number;
+        };
+        "dead-code": {
+            enabled: boolean;
+            weight: number;
+        };
+        perf: {
+            enabled: boolean;
+            weight: number;
+        };
+        infra: {
+            enabled: boolean;
+            weight: number;
+        };
+        docs: {
+            enabled: boolean;
+            weight: number;
+        };
+    }, Partial<Record<"security" | "tests" | "types-lint" | "dead-code" | "perf" | "infra" | "docs", {
+        enabled: boolean;
+        weight: number;
+    }>>>>;
+}, z.core.$strip>;
+type AfterburnerConfig = z.output<typeof configSchema>;
+type AfterburnerUserConfig = z.input<typeof configSchema>;
+type RepoConfig = z.output<typeof repoConfigSchema>;
+type BudgetConfig = z.output<typeof budgetConfigSchema>;
+type AgentConfig = z.output<typeof agentConfigSchema>;
+/** Identity helper so user configs get full type checking and completion. */
+declare function defineConfig(config: AfterburnerUserConfig): AfterburnerUserConfig;
+
+interface LoadedConfig {
+    config: AfterburnerConfig;
+    filepath: string;
+}
+/**
+ * Loads config via cosmiconfig: explicit path > search from cwd > the global
+ * config dir (env-paths). cosmiconfig v9 loads .ts configs natively, but only
+ * when the `typescript` package is importable at runtime, true in a project
+ * that has typescript installed, false after a bare global CLI install. We
+ * keep the defaults and rewrite that failure into an actionable error instead
+ * of adding a runtime TypeScript dependency.
+ */
+declare function loadConfig(explicitPath?: string): Promise<LoadedConfig>;
+/** Exported for unit tests: rewrites known loader failures into actionable errors. */
+declare function mapConfigLoadError(error: unknown): Error;
+declare function formatConfigError(error: ZodError, filepath: string): string;
+
+/**
+ * The single source of truth for budget math. ALL budget quantities in
+ * Afterburner are expressed in Sonnet-equivalent tokens, normalized through
+ * this table. Nothing outside this module may hardcode a model rate.
+ *
+ * Weights are relative cost factors with Sonnet = 1.0, derived from the
+ * published per-MTok API prices (verified 2026-06-11 at
+ * https://platform.claude.com/docs/en/about-claude/pricing):
+ * Haiku $1/$5, Sonnet $3/$15, Opus $5/$25, Fable $10/$50, input and output
+ * ratios are identical, so a single factor per model family suffices. The 1M
+ * context window is included at standard pricing, so there is no separate
+ * long-context weight. Anthropic publishes no numeric subscription-limit
+ * weighting between models (the docs are qualitative only), so these
+ * price-derived factors are the best documented proxy.
+ */
+interface ModelCostTable {
+    /** Relative cost weight for a model id (longest-prefix match). Throws on unknown models. */
+    weightFor(modelId: string): number;
+    /** Convert raw tokens spent on `modelId` into Sonnet-equivalent tokens. */
+    toSonnetTokens(tokens: number, modelId: string): number;
+}
+type ModelWeightEntry = readonly [prefix: string, weight: number];
+declare function createModelCostTable(weights?: readonly ModelWeightEntry[]): ModelCostTable;
+declare const defaultCostTable: ModelCostTable;
+
+/**
+ * Premium-model gate (still named the "Fable gate" / `allowFable` for the
+ * config key). Matches by model-family prefix (not exact id) so new releases in
+ * a gated family stay gated without a code change. It covers every top-tier,
+ * real-money family the cost table prices at ~2x Opus, currently Fable and
+ * Mythos, by reading PREMIUM_MODEL_PREFIXES from the cost table, so the gate
+ * and the cost weights can never drift apart. An autonomous run must never
+ * reach one of these models without the explicit `agent.allowFable` opt-in,
+ * since outside promotional windows they bill usage credits at API rates and
+ * would let an unattended scheduler silently spend real money.
+ */
+declare function isFableModel(modelId: string): boolean;
+declare function assertModelAllowed(modelId: string, allowFable: boolean): void;
+
+/**
+ * Budget snapshot of the user's Claude subscription headroom.
+ *
+ * There is no official API that exposes remaining subscription quota, so every
+ * provider is estimate-driven. The fields model the two caps a subscription
+ * has: the rolling 5-hour session cap and the weekly cap (what `/usage` shows
+ * inside Claude Code). Token amounts are Sonnet-equivalent (see ModelCostTable).
+ *
+ * Billing nuance (verified 2026-06-11): from June 15, 2026 headless
+ * `claude -p` / Agent SDK usage on subscription plans draws from a separate
+ * monthly "Agent SDK credit" rather than the interactive weekly limits.
+ * Afterburner still models the interactive limits the user actually watches;
+ * see README "The economics" for what that means per backend.
+ */
+interface Budget {
+    /** Is a 5-hour session window currently available? */
+    sessionAvailable: boolean;
+    /** Remaining share of the weekly cap, 0–100. */
+    weeklyRemainingPct: number;
+    /** Estimated remaining weekly budget in Sonnet-equivalent tokens. */
+    weeklyRemainingTokensEst: number;
+}
+interface BudgetProvider {
+    getBudget(): Promise<Budget>;
+}
+
+/**
+ * Budget values supplied by the user (config `budget.manual` or CLI flags).
+ * The reference provider for testing and the default until a reliable
+ * automated source for subscription usage exists.
+ */
+declare class ManualBudgetProvider implements BudgetProvider {
+    private readonly budget;
+    constructor(budget: Budget);
+    getBudget(): Promise<Budget>;
+}
+
+/**
+ * Automatic budget provider: derives weekly SPENT tokens from the local
+ * Claude Code session transcripts (~/.claude/projects/<project>/<session>.jsonl)
+ * and subtracts them from a configured weekly allowance.
+ *
+ * Why transcripts: there is no documented headless command that exposes the
+ * `/usage` panel data, and ~/.claude/stats-cache.json can be months stale.
+ * Transcripts are written live by every Claude Code session, so they are the
+ * one local source that is always current. The same approach is used by
+ * community tools like ccusage.
+ *
+ * TODO(unverified): the transcript JSONL format is undocumented. Verified
+ * empirically against Claude Code 2.1.173 (2026-06-11): assistant entries
+ * carry `timestamp` (ISO 8601), `message.model`, `message.id`, and
+ * `message.usage` with `input_tokens` / `output_tokens` /
+ * `cache_creation_input_tokens` / `cache_read_input_tokens`. Parsing is
+ * defensive, unknown shapes are skipped, never fatal.
+ *
+ * Counting convention: input_tokens + output_tokens per assistant message
+ * (cache reads/writes excluded). This matches Claude Code's own
+ * stats aggregation and avoids cache traffic dwarfing the numbers. The weekly
+ * cap itself is not exposed anywhere locally, so `weeklyAllowanceSonnetTokens`
+ * stays a one-time calibration against what /usage shows for your plan.
+ */
+interface TranscriptUsageSummary {
+    /** Sonnet-equivalent tokens spent inside the window. */
+    spentSonnetTokens: number;
+    /** Raw tokens per model id, for diagnostics. */
+    tokensByModel: Record<string, number>;
+    /** Number of assistant messages counted (after dedup). */
+    messagesCounted: number;
+}
+declare function defaultClaudeProjectsDir(): string;
+interface ClaudeCodeTranscriptsOptions {
+    /** Estimated total weekly capacity in Sonnet-equivalent tokens (calibrate against /usage). */
+    weeklyAllowanceSonnetTokens: number;
+    costTable: ModelCostTable;
+    /**
+     * The 5-hour session cap cannot be derived from local data (the limit value
+     * is not exposed), so session availability stays a manual input.
+     */
+    sessionAvailable: boolean;
+    /** Rolling window; the weekly reset anchor is unknown, so 7 rolling days is the conservative read. */
+    windowDays?: number;
+    projectsDir?: string;
+}
+declare class ClaudeCodeTranscriptsBudgetProvider implements BudgetProvider {
+    private readonly opts;
+    constructor(opts: ClaudeCodeTranscriptsOptions);
+    getBudget(): Promise<Budget>;
+}
+/** Exported separately so the scan/dedup/conversion logic is unit-testable. */
+declare function summarizeTranscriptUsage(projectsDir: string, since: Date, costTable: ModelCostTable): Promise<TranscriptUsageSummary>;
+
+/**
+ * Local mirror of the `rate_limits` object Claude Code pipes to a statusLine
+ * command on stdin (verified against the Claude Code statusline docs,
+ * 2026-06-11): each window is optional and present only for Pro/Max
+ * subscribers after the first API response in a session.
+ *   rate_limits.five_hour.used_percentage  (0–100)
+ *   rate_limits.five_hour.resets_at        (unix epoch SECONDS)
+ *   rate_limits.seven_day.{used_percentage,resets_at}
+ */
+interface RateLimitWindow {
+    used_percentage?: number;
+    resets_at?: number;
+}
+interface RateLimits {
+    five_hour?: RateLimitWindow;
+    seven_day?: RateLimitWindow;
+}
+interface UsageCache {
+    /** ISO 8601 timestamp of when the statusLine hook captured this. */
+    capturedAt: string;
+    rateLimits: RateLimits;
+    /** model.display_name at capture time, for diagnostics. */
+    model?: string;
+}
+declare function defaultUsageCachePath(): string;
+declare function readUsageCache(path?: string): Promise<UsageCache | null>;
+declare function writeUsageCache(path: string, cache: UsageCache): Promise<void>;
+interface UsageCacheBudgetOptions {
+    /** Total weekly capacity in Sonnet-equivalent tokens, maps the authoritative % to a token figure. */
+    weeklyAllowanceSonnetTokens: number;
+    /** Cache older than this is treated as unusable (fall back). */
+    maxAgeMs: number;
+}
+interface UsageCacheBudgetResult {
+    budget?: Budget;
+    /** Present when the cache can't yield a usable budget and the caller should fall back. */
+    fallbackReason?: string;
+}
+/**
+ * Maps a usage cache to a Budget, using the `resets_at` timestamps to reason
+ * about staleness so an old cache is self-correcting:
+ *
+ * - Weekly cap gates spend, so be conservative: if the cache is older than
+ *   maxAge, or its weekly window has already reset since capture (so the
+ *   cached % no longer reflects the current window), fall back to the
+ *   transcript estimate rather than trust a possibly-optimistic number.
+ * - The 5-hour session cap is a boolean: if its window has reset
+ *   (now ≥ resets_at) the session is available again regardless of the old %;
+ *   otherwise it's available unless that window is maxed.
+ *
+ * Pure and deterministic (nowMs injected) so the freshness logic is testable.
+ */
+declare function budgetFromUsageCache(cache: UsageCache, opts: UsageCacheBudgetOptions, nowMs: number): UsageCacheBudgetResult;
+
+interface ClaudeUsageBudgetOptions {
+    weeklyAllowanceSonnetTokens: number;
+    maxAgeMs: number;
+    /** Used when the usage cache is missing, stale, or incomplete. */
+    fallback: BudgetProvider;
+    cachePath?: string;
+    /** Called with a human-readable reason whenever it falls back. */
+    onFallback?: (reason: string) => void;
+}
+/**
+ * Reads the authoritative subscription usage figures (5h/7d % + reset times)
+ * that Claude Code captures into the usage cache via the statusLine hook
+ * (`afterburner statusline install`). Falls back to the supplied provider
+ * (normally the transcript estimate) whenever the cache can't be used, so an
+ * autonomous run never blocks on a missing or stale cache.
+ */
+declare class ClaudeUsageBudgetProvider implements BudgetProvider {
+    private readonly opts;
+    private readonly cachePath;
+    constructor(opts: ClaudeUsageBudgetOptions);
+    getBudget(): Promise<Budget>;
+    private fallBack;
+}
+
+interface BudgetProviderOptions {
+    /** Optional sink for diagnostic notes (e.g. "usage cache stale; falling back"). */
+    onNote?: (message: string) => void;
+}
+/**
+ * Picks the budget source from config:
+ * - 'manual': the values in budget.manual (and/or run-once flags).
+ * - 'claude-code-transcripts': spend computed from local Claude Code transcripts.
+ * - 'claude-usage': the authoritative subscription limits Claude Code captures
+ *   via the statusLine hook, with the transcript estimate as fallback.
+ * Session availability is a manual input for the non-statusLine providers (the
+ * 5-hour cap can't be derived from local data).
+ */
+declare function createBudgetProvider(config: AfterburnerConfig, opts?: BudgetProviderOptions): {
+    provider: BudgetProvider;
+    source: string;
+};
+
+interface TaskIdentity {
+    repoUrl: string;
+    category: TaskCategory;
+    /** Target path or finding identifier, whatever makes the task unique. */
+    target: string;
+}
+/**
+ * Deterministic task identity: a stable hash of (repo, category, target).
+ * Branch names and PR titles derive from it, the run store records it, and
+ * idempotency is enforced by refusing to re-run a fingerprint that already
+ * has an open or merged PR. The repo url is normalized first so the identity
+ * survives a config rewrite from a relative path to the absolute one (and two
+ * different repos reached via the same relative url can't collide).
+ */
+declare function taskFingerprint(id: TaskIdentity): string;
+declare function deriveBranchName(task: {
+    category: TaskCategory;
+    fingerprint: string;
+}, branchPrefix: string): string;
+declare function derivePrTitle(task: {
+    title: string;
+    fingerprint: string;
+}): string;
+
+interface CandidateTask {
+    repoUrl: string;
+    category: TaskCategory;
+    title: string;
+    /** Target path or finding identifier, the unique subject of the task. */
+    target: string;
+    /** Estimated cost in Sonnet-equivalent tokens (via ModelCostTable). */
+    estCostSonnetTokens: number;
+    fingerprint: string;
+}
+/**
+ * The replacement seam for a future Claude-powered ranker: exactly what the
+ * orchestrator consumes. (DeterministicTaskSelector also exposes a public
+ * rank() for inspection and tests, but implementations only owe select().)
+ */
+interface TaskSelector {
+    /** Highest-value candidate that fits within the budget minus the safety margin. */
+    select(repo: RepoConfig, budget: Budget): Promise<CandidateTask | null>;
+}
+interface DeterministicSelectorOptions {
+    costTable: ModelCostTable;
+    modelByCategory: Record<TaskCategory, string>;
+    taskCategories: Record<TaskCategory, {
+        enabled: boolean;
+        weight: number;
+    }>;
+    safetyMarginTokens: number;
+    maxTaskTokens: number;
+}
+/**
+ * Rough per-task spend in the routed model's own tokens; converted to
+ * Sonnet-equivalent through the ModelCostTable at estimation time. These are
+ * deliberately coarse, the selector's judgment is the part designed to be
+ * replaced by a Claude-powered ranker later.
+ */
+declare const BASE_TASK_TOKENS: Record<TaskCategory, number>;
+/**
+ * The one way run-once, watch, and tests derive selector options from config,
+ * so they can never drift (mirrors createBudgetProvider / createRunner).
+ */
+declare function createSelector(config: {
+    agent: {
+        modelByCategory: Record<TaskCategory, string>;
+        maxTaskTokens: number;
+    };
+    budget: {
+        safetyMarginTokens: number;
+    };
+    taskCategories: Record<TaskCategory, {
+        enabled: boolean;
+        weight: number;
+    }>;
+}): DeterministicTaskSelector;
+/**
+ * Deterministic, no-LLM selector: cheap static heuristics over a local
+ * checkout. Designed so a Claude-powered ranker can drop in behind the same
+ * TaskSelector interface later.
+ */
+declare class DeterministicTaskSelector implements TaskSelector {
+    private readonly opts;
+    constructor(opts: DeterministicSelectorOptions);
+    rank(repo: RepoConfig, _budget: Budget): Promise<CandidateTask[]>;
+    select(repo: RepoConfig, budget: Budget): Promise<CandidateTask | null>;
+    private isCategoryEnabled;
+    /** Estimate flows through the ModelCostTable using the category's ROUTED model. */
+    private estimate;
+    private makeTask;
+    private docsCandidates;
+    private testGapCandidates;
+    private deadCodeCandidates;
+}
+
+type RunnerBackend = 'dry-run' | 'claude-code' | 'api-key';
+type RunOutcome = 'dry-run' | 'pr-opened' | 'abandoned' | 'failed';
+interface RunResult {
+    outcome: RunOutcome;
+    /** Always claude/-prefixed; never the default branch. */
+    branch: string;
+    prTitle: string;
+    prUrl?: string;
+    summary: string;
+}
+/**
+ * Executes ONE bounded task against a repo. Live backends commit only to a
+ * claude/-prefixed branch and open a PR, never push to the default branch,
+ * never merge. A killed run must leave a resumable claude/ branch, never a
+ * broken state.
+ */
+interface AgentRunner {
+    readonly backend: RunnerBackend;
+    run(task: CandidateTask, repo: RepoConfig): Promise<RunResult>;
+}
+
+/** The default backend: reports exactly what a live run WOULD do. No side effects. */
+declare class DryRunRunner implements AgentRunner {
+    readonly backend: "dry-run";
+    run(task: CandidateTask, repo: RepoConfig): Promise<RunResult>;
+}
+
+/**
+ * Recommended live backend (stub): wraps Claude Code headless using the
+ * user's locally authenticated subscription, preserving the leftover-quota
+ * economics.
+ *
+ * Verified invocation surface (https://code.claude.com/docs/en/headless.md and
+ * /en/cli-reference.md, 2026-06-11):
+ *   claude -p --output-format json --permission-mode acceptEdits \
+ *          --allowedTools "…" --max-turns N --model <routed-model>
+ *   - JSON output carries `result`, `session_id`, and `total_cost_usd`.
+ *   - Subscription OAuth credentials (from `claude /login`, or a
+ *     `claude setup-token` → CLAUDE_CODE_OAUTH_TOKEN in CI) are the default
+ *     auth for `-p`.
+ *   - NEVER pass --bare: it skips OAuth/keychain reads, breaking subscription
+ *     auth. Docs say --bare will become the `-p` default in a future release,
+ *     revisit this invocation when that lands.
+ *
+ * TODO(unverified): exact prompt template, tool allowlist, and the PR-creation
+ * step (gh/glab vs API) are not implemented yet, live execution is out of
+ * scope for the scaffold.
+ */
+declare class ClaudeCodeRunner implements AgentRunner {
+    readonly backend: "claude-code";
+    run(_task: CandidateTask, _repo: RepoConfig): Promise<RunResult>;
+}
+interface ClaudeCodeInvocation {
+    command: 'claude';
+    /** Fixed flags only, untrusted text never lands in argv. */
+    args: string[];
+    /** Sanitized child environment. */
+    env: Record<string, string | undefined>;
+    /** The task prompt, delivered via stdin. */
+    stdinPrompt: string;
+}
+/**
+ * Pure builder for the headless invocation, kept separate from the stub so the
+ * injection-safety properties are unit-testable today.
+ *
+ * Injection class defended against: repo contents, issue titles, PR bodies and
+ * comments are UNTRUSTED input. Interpolating them into a shell command string
+ * (or a CI `run:` block) lets `$(…)`, backticks or quote-breaking text execute
+ * arbitrary commands. Defense: spawn with an argv array (no shell), keep argv
+ * limited to fixed flags, and deliver all untrusted text via stdin and
+ * environment variables that the child reads through process.env.
+ */
+declare function buildClaudeCodeInvocation(task: CandidateTask, repo: RepoConfig, opts: {
+    model: string;
+    maxTurns: number;
+    allowedTools: readonly string[];
+}): ClaudeCodeInvocation;
+/**
+ * Strip API-key auth from the child environment. Verified behavior
+ * (code.claude.com/docs/en/authentication.md, 2026-06-11): in `-p` mode a
+ * present ANTHROPIC_API_KEY is ALWAYS used and outranks the subscription
+ * login, a leftover exported key would silently bill the API instead of
+ * spending subscription quota. CLAUDE_CODE_OAUTH_TOKEN is kept: it IS
+ * subscription auth (the documented CI path).
+ */
+declare function sanitizeSpawnEnv(env: Record<string, string | undefined>): Record<string, string | undefined>;
+
+/**
+ * Universal fallback backend (interface stub only): drives the task through
+ * the Anthropic API with an API key. Unlike the claude-code backend this is
+ * BILLED PER TOKEN at API rates, every run costs real money instead of
+ * spending subscription quota you already paid for.
+ *
+ * TODO(unverified): implementation is out of scope for the scaffold.
+ */
+declare class ApiKeyRunner implements AgentRunner {
+    readonly backend: "api-key";
+    run(_task: CandidateTask, _repo: RepoConfig): Promise<RunResult>;
+}
+
+/**
+ * Dry-run is the DEFAULT. Live execution requires BOTH opt-ins:
+ *   1. the --live flag on the invocation, AND
+ *   2. a live backend in the config (agent.backend !== 'dry-run').
+ * Either one missing → dry-run. This is a non-negotiable safety rule; do not
+ * collapse it into a single switch.
+ */
+declare function createRunner(config: AfterburnerConfig, liveFlag: boolean): AgentRunner;
+
+interface RunRecord {
+    timestamp: string;
+    repoUrl: string;
+    fingerprint: string;
+    category: TaskCategory;
+    title: string;
+    estCostSonnetTokens: number;
+    branch: string;
+    prUrl?: string;
+    outcome: RunOutcome;
+}
+/**
+ * Append-only run records, the canonical "what happened" surface (exposed via
+ * `afterburner log`) and the source for idempotency checks.
+ */
+interface RunStore {
+    append(record: RunRecord): Promise<void>;
+    list(): Promise<RunRecord[]>;
+    /** Duplicate-PR guard: has this fingerprint already produced an open or merged PR? */
+    hasOpenOrMergedPr(fingerprint: string): Promise<boolean>;
+}
+declare class JsonlRunStore implements RunStore {
+    private readonly filePath;
+    constructor(filePath?: string);
+    append(record: RunRecord): Promise<void>;
+    list(): Promise<RunRecord[]>;
+    hasOpenOrMergedPr(fingerprint: string): Promise<boolean>;
+}
+
+/**
+ * Notification seam. Core ships ONLY ConsoleNotifier: the pull request is the
+ * real notification and the run store is the audit trail. This interface is
+ * the documented extension point for a future opt-in generic webhook, vendor
+ * SDKs are never bundled into core.
+ */
+interface Notifier {
+    notify(record: RunRecord): Promise<void>;
+}
+
+declare class ConsoleNotifier implements Notifier {
+    notify(record: RunRecord): Promise<void>;
+}
+
+interface GateConfig {
+    minWeeklyHeadroomPct: number;
+    safetyMarginTokens: number;
+    requireSessionAvailable: boolean;
+}
+interface GateDecision {
+    go: boolean;
+    reason: string;
+}
+/**
+ * Both-caps gate, a non-negotiable rule encoded as a pure function: only fire
+ * when a session window is available AND the estimated cost plus the safety
+ * margin fits inside the remaining weekly budget (with the configured
+ * headroom). Reasons are returned, not just booleans, so every skipped run is
+ * explainable in the log.
+ */
+declare function shouldIgnite(budget: Budget, estCostSonnetTokens: number, config: GateConfig): GateDecision;
+
+interface WatchHandle {
+    stop(): void;
+}
+/**
+ * Foreground scheduler daemon (`afterburner watch`). Useful for development,
+ * temporary runs, and cron expressions native schedulers cannot express. For
+ * normal unattended use, prefer `afterburner schedule install`.
+ */
+declare function startWatch(opts: {
+    cron: string;
+    timezone: string;
+    onTick: () => Promise<void>;
+    onError?: (error: unknown) => void;
+}): WatchHandle;
+
+type SupportedPlatform = 'darwin' | 'linux' | 'win32';
+interface ScheduleArtifacts {
+    kind: 'launchd' | 'systemd-user' | 'schtasks';
+    /** Files to write (empty for schtasks, which is command-driven). */
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** Commands the user runs to activate the schedule. */
+    activationHint: string;
+    /** Commands/steps to undo the installation. */
+    removalHint: string;
+}
+interface SimpleCronSchedule {
+    minute: number;
+    /** Explicit list of hours the job fires at. */
+    hours: number[];
+}
+/**
+ * Native schedulers don't speak cron uniformly (launchd wants calendar
+ * intervals, schtasks wants /SC switches), so we support the simple cron
+ * shapes Afterburner actually defaults to and fail loudly on anything fancier;
+ * `afterburner watch` handles full cron expressions.
+ *
+ * Supported: hourly ("M * * * *"), daily ("M H * * *"), every N hours
+ * (step syntax on the hour field), and specific hours ("M H1,H2 * * *").
+ */
+declare function parseSimpleCron(cron: string): SimpleCronSchedule;
+interface NativeScheduleOptions {
+    cron: string;
+    timezone: string;
+    /** Absolute path to the node binary. */
+    nodePath: string;
+    /** Absolute path to the afterburner CLI entry script. */
+    cliPath: string;
+    configPath?: string;
+}
+declare function generateScheduleArtifacts(platform: SupportedPlatform, opts: NativeScheduleOptions): ScheduleArtifacts;
+
+interface RunOnceDeps {
+    config: AfterburnerConfig;
+    budgetProvider: BudgetProvider;
+    selector: TaskSelector;
+    runner: AgentRunner;
+    store: RunStore;
+    notifier: Notifier;
+}
+interface RepoRunOutcome {
+    repoUrl: string;
+    status: 'completed' | 'skipped';
+    reason: string;
+    task?: CandidateTask;
+    result?: RunResult;
+    record?: RunRecord;
+}
+/**
+ * One ignition cycle: budget → selection → gates → run → record. Encodes the
+ * non-negotiables, one bounded task per run, both-caps gating, fingerprint
+ * idempotency, and the Fable gate re-checked at run time.
+ */
+declare function runOnce(deps: RunOnceDeps): Promise<RepoRunOutcome[]>;
+
+export { type AfterburnerConfig, type AfterburnerUserConfig, type AgentConfig, type AgentRunner, ApiKeyRunner, BASE_TASK_TOKENS, type Budget, type BudgetConfig, type BudgetProvider, type BudgetProviderOptions, type CandidateTask, type ClaudeCodeInvocation, ClaudeCodeRunner, ClaudeCodeTranscriptsBudgetProvider, type ClaudeCodeTranscriptsOptions, type ClaudeUsageBudgetOptions, ClaudeUsageBudgetProvider, ConsoleNotifier, DEFAULT_MODEL_BY_CATEGORY, type DeterministicSelectorOptions, DeterministicTaskSelector, DryRunRunner, type GateConfig, type GateDecision, JsonlRunStore, type LoadedConfig, ManualBudgetProvider, type ModelCostTable, type ModelWeightEntry, type NativeScheduleOptions, type Notifier, type RateLimitWindow, type RateLimits, type RepoConfig, type RepoRunOutcome, type RunOnceDeps, type RunOutcome, type RunRecord, type RunResult, type RunStore, type RunnerBackend, type ScheduleArtifacts, type SupportedPlatform, TASK_CATEGORIES, TASK_TAXONOMY, type TaskCategory, type TaskCategoryInfo, type TaskIdentity, type TaskSelector, type TranscriptUsageSummary, type UsageCache, type UsageCacheBudgetOptions, type UsageCacheBudgetResult, type WatchHandle, assertModelAllowed, budgetFromUsageCache, buildClaudeCodeInvocation, claudeConfigDir, configDir, configSchema, createBudgetProvider, createModelCostTable, createRunner, createSelector, dataDir, defaultClaudeProjectsDir, defaultCostTable, defaultRunStorePath, defaultUsageCachePath, defineConfig, deriveBranchName, derivePrTitle, formatConfigError, generateScheduleArtifacts, isFableModel, loadConfig, mapConfigLoadError, parseSimpleCron, readUsageCache, repoConfigSchema, runOnce, sanitizeSpawnEnv, shouldIgnite, startWatch, summarizeTranscriptUsage, taskFingerprint, writeUsageCache };