@quickchatai/pi-quickreview 0.0.0-stage → 1.2.0

package/dist/src/reviewconfig.d.ts

@@ -0,0 +1,753 @@
+import type { LensTuningMap } from "./lenstuning.js";
+import type { PostingPolicy } from "./postingpolicy.js";
+import { type PassTier } from "./types.js";
+/** `[github] auth`: whose credential the daemon runs on. `app` (the default)
+ * is a GitHub App's installation token; `user` is the person's own GitHub
+ * token, read from the `github_token` file in the secrets dir. `user` is
+ * polling-only: no webhooks, no App self-config, every review a COMMENT. */
+export type GithubAuthMode = "app" | "user";
+export declare const GITHUB_AUTH_MODES: readonly GithubAuthMode[];
+export interface GithubConfig {
+    repo: string;
+    /** Always set after parse; absent (a hand-built config) means "app". */
+    auth?: GithubAuthMode;
+    /** The App's slug. May be "" under `auth = "user"`, where no App exists. */
+    app_slug: string;
+    /** The login the system posts as: the App's `<slug>[bot]`, or under
+     * `auth = "user"` the person's own login (onboarding reads it from
+     * `GET /user`). */
+    bot_login: string;
+    review_team: string;
+    trigger_label: string;
+    in_progress_label: string;
+    reviewed_label: string;
+    improvement_label: string;
+    issue_label: string;
+    /** Always an absolute-or-given path after parse: an empty (or the legacy
+     * default `~/.config/quickreview-bot`) value is resolved by the install
+     * locator to `<config home>/secrets` (the legacy dir itself is never read).
+     * A value the operator set is taken as given. */
+    secrets_dir: string;
+    /** The reviewed repo's default branch: the base the improvement
+     * filer targets, the branch replay diffs against, and the fixture base for
+     * CLI ops. Default "main"; a repo whose default is "master" sets it. PR rounds do NOT
+     * read this — a round's base is always the PR's own `base_ref` from the
+     * GitHub API. */
+    base_branch: string;
+    /** Directory name of the base clone under the sandbox root.
+     * "" (the default) derives from the repo slug's basename via
+     * `githubCloneDir` — "owner/name" ⇒ "name". */
+    clone_dir: string;
+}
+/**
+ * [guards] — the posting-time guards. Every one but `no_checks_is_red` is on
+ * by default; a knob exists only so a guard can be taken out of the path
+ * deliberately, in one place, rather than by editing the gate.
+ */
+export interface GuardsConfig {
+    /** A non-author human APPROVED at the head ⇒ post COMMENT, not REQUEST_CHANGES. */
+    downgrade_on_human_approval: boolean;
+    /** Same head as the last review and no author reply since ⇒ post nothing. */
+    skip_unchanged_head: boolean;
+    /** Re-read the PR immediately before every posting mutation; merged/closed ⇒ refuse. */
+    recheck_pr_state_before_post: boolean;
+    /** No green CI at this head ⇒ APPROVE is unavailable; the review posts as a
+     * COMMENT with approval withheld. */
+    block_approve_on_red_ci: boolean;
+    /** A head with ZERO check-runs also withholds approval: in a CI-running
+     * repo that is a conflicted PR or CI that has not started — no execution
+     * evidence. Off by default so a repo with no CI at all is never wedged (the
+     * `none` exemption). */
+    no_checks_is_red: boolean;
+    /** The head the review is ABOUT must still be the PR's live head at posting
+     * time: a push landing between the round's validation and
+     * its posting step otherwise lands a stale review against the new head. */
+    refuse_on_head_drift: boolean;
+}
+export declare const GUARDS_DEFAULTS: GuardsConfig;
+/**
+ * [review.directives] — EXTENSIONS to the first-party directive-path
+ * vocabulary (`packages/pi-plugin/src/severity.ts DEFAULT_DIRECTIVE_VOCABULARY`). Extend-only by
+ * design: config ADDS names, nothing can remove a built-in — dropping, say,
+ * `CLAUDE.md` would silently re-enable auto-blocking on first-party directive
+ * edits by config typo. The shape mirrors
+ * `severity.ts DirectiveVocabularyExtras`.
+ */
+export interface ReviewDirectivesConfig {
+    /** Extra vendored/third-party path segments (matched case-insensitively). */
+    extra_vendored_segments: string[];
+    /** Extra directive-file basenames (any depth), e.g. "COPILOT.md". */
+    extra_basenames: string[];
+    /** Extra directory segments whose whole subtree is directive content. */
+    extra_dir_segments: string[];
+    /** Extra ROOT-level directory names (bind at the repo root only). */
+    extra_root_dirs: string[];
+    /** Extra exact repo-relative directive file paths. */
+    extra_files: string[];
+}
+export declare const REVIEW_DIRECTIVES_DEFAULTS: ReviewDirectivesConfig;
+/**
+ * [review] — review-content knobs. Distinct from [guards] (posting-time
+ * refusals) and [recheck] (post-approval triggers): these shape what a review
+ * says, not whether it posts.
+ */
+export interface ReviewConfig {
+    /**
+     * Fallback @-mention for the first-party-directive escalation comment when
+     * git history yields no attributable human author login for the touched
+     * directive files. "" ⇒ the comment renders without an @ (addressed to
+     * "a maintainer") — it still posts.
+     */
+    escalation_mention_default: string;
+    /**
+     * Repo profile: names a directory under `profiles/` — the install's config
+     * home first, then the checkout's generic examples
+     * (`src/install.ts locateProfile`; a non-plain name is refused) — whose
+     * house-rule addenda pack (`profiles/<name>/addenda/*.md`) is composed onto
+     * the built pass bodies AFTER the built-in generic registry and BEFORE the
+     * dynamic same-day feedback addendum — and whose optional
+     * `heuristics.toml` extends lens selection with repo-shaped predicates.
+     * "" ⇒ no profile: exactly the generic addenda set and the generic
+     * selection core. Loaded once at daemon assembly (src/wire.ts) — a
+     * malformed pack or heuristics file fails the boot loudly, never a silent
+     * skip.
+     */
+    profile: string;
+    /** Directive-path vocabulary extensions — see the type above. */
+    directives: ReviewDirectivesConfig;
+    /** The named review configuration (`REVIEW_PRESETS`): the reasoning level
+     * and every lever below in one word. A key set explicitly in `[review]` (or
+     * `[models] effort`) overrides what the preset would give it. */
+    preset: ReviewPreset;
+    /** Content-triggered sub-lenses (`SUBLENS_TRIGGERS` in packages/pi-plugin/src/heuristics.ts):
+     * narrow passes, each a fixed procedure, planned when the diff or the PR
+     * text shows the shape its procedure exists for. Off ⇒ the path-shaped
+     * plan alone. */
+    sublenses: boolean;
+    /** The per-file sweep (`agents/pass-sweep.md`): changed files are grouped
+     * into a few small batches and each batch gets its own line-by-line pass —
+     * the local slips a whole-PR reading skims past. */
+    sweep: boolean;
+    /** At most this many sweep passes per round; files beyond them are listed
+     * as not swept. */
+    sweep_max_groups: number;
+    /** Files and changed lines per sweep group (heuristics.ts sweepGroups). */
+    sweep_group_files: number;
+    sweep_group_lines: number;
+    /** Files per sweep group on a WIDE change — more files than
+     * `sweep_group_files × sweep_max_groups` — packed by `sweep_group_lines`
+     * instead (heuristics.ts SWEEP_WIDE_FILES_PER_GROUP). 0 = off. */
+    sweep_wide_files: number;
+    /** The behaviour-delta lens (`agents/pass-behaviour-delta.md`): base versus
+     * head on every modified or deleted line of non-test code, one row per group
+     * of modifying files packed by `sweep_group_lines` changed lines, at most
+     * `behaviour_delta_max_groups` rows (heuristics.ts behaviourDeltaGroups). */
+    behaviour_delta: boolean;
+    behaviour_delta_max_groups: number;
+    /** Over this many changed lines (heuristics.ts `baselineSplitLines` — the
+     * sweep's sizing: prose half, lockfiles, generated and vendored files
+     * nothing) pass-baseline is planned as 2–3 rows, each STARTING from one
+     * group of the change's files with the whole PR as its charter
+     * (heuristics.ts `baselineGroups`). 0 ⇒ never: one row. At 2000 only the
+     * largest PRs split — those where a lone baseline row sets the round's
+     * critical path; every PR under it plans as one row. */
+    baseline_split_lines: number;
+    /** The loosened-test hint (packages/pi-plugin/src/loosenedtests.ts): weakened assertions in
+     * the PR's test files are found deterministically and named in pass-tests'
+     * plan reason; their presence also plans pass-tests. Off ⇒ neither. */
+    loosened_test_hint: boolean;
+    /** Selection cost knobs (heuristics.ts SelectionTuning): pass-intent's
+     * substance bar in words, and when pass-placement runs — this many code
+     * files, or a new code file with this many added lines. */
+    intent_min_words: number;
+    placement_min_code_files: number;
+    placement_min_new_file_lines: number;
+    /** Unpack the sources of the third-party packages this PR touches, at
+     * their locked versions, so passes can read what a library actually does
+     * (packages/pi-plugin/src/depsources.ts). Download-and-unpack only — nothing is installed or
+     * run. */
+    dependency_sources: boolean;
+    /** The tests lens (`agents/pass-tests.md`) on every PR that
+     * changes code — which existing tests the change breaks, and whether the
+     * PR's own tests exercise the code or mock the failure point away. */
+    tests_lens: boolean;
+    /** The code-quality lenses (`agents/pass-maintainability.md`,
+     * `pass-duplication.md`, `pass-abstraction.md`; heuristics.ts
+     * QUALITY_PASSES) on every PR whose non-test code adds at least
+     * `quality_min_added_lines` lines. Style is none of them. */
+    quality_lenses: boolean;
+    quality_min_added_lines: number;
+    /** The style lens (`agents/pass-style.md`) — planned only when the repo has
+     * a written style guide (packages/pi-plugin/src/styleguide.ts), and judging only against it. */
+    style_lens: boolean;
+    /** The lint-conformance sub-lens (`agents/pass-lint-conformance.md`) —
+     * planned only when a CI job of the repo runs a linter or formatter whose
+     * rules cover a changed file (packages/pi-plugin/src/lintconfig.ts), reporting only changed
+     * lines that would fail that job. */
+    lint_conformance: boolean;
+    /** How many nits a review may post. `strict` (the default, production's
+     * behaviour): the validator drops true-but-trivial candidates (`below-bar`),
+     * a nit must name the change it asks for, and review volume comes
+     * out of nits. `open`: none of those limits — every true nit posts. Meant
+     * for benchmarks whose references reward nits; a repo that wants every nit
+     * can set it too. Style still needs the repo's written guide either way. */
+    nits: NitPolicy;
+    /** The validator demotes a confirmed, actionable observation instead of
+     * killing it for a small consequence (`validate-demote-not-kill`).
+     * On by default; off reproduces the earlier validator for a benchmark. */
+    validate_demote: boolean;
+    /** Passes never planned and never addable this round (cost tuning). `[]`
+     * (the default) plans every lens selection picks. Names must be known
+     * passes; `pass-validate` is refused here — switching the validator off is
+     * the profile's `enabled = false`. Not a preset lever. */
+    skip_lenses: string[];
+    /** The validator's consequence rules (`validate-consequence-rule`):
+     * intent/contract appeals, dead code, CI-enabled lint rules and
+     * merges judged by consequence. Off by default; opt-in for a benchmark arm. */
+    validate_consequence_rule: boolean;
+    /** Review latency levers (bench/aacr/PERF.md §6). None changes
+     * which lenses run or what they are asked; each removes serial time.
+     *
+     * `wide_lens_fanout`: a batched `tasks:[…]` lens launch runs as wide as
+     * `[engine] lens_max_concurrency`.
+     * Deprecated: it steered only the retired native glue, and is a no-op on an
+     * SDK session, where our lens tool sets its own width. */
+    wide_lens_fanout: boolean;
+    /** `task_files`: the daemon (or the bench) writes each plan row's complete
+     * lens task to a file (packages/pi-plugin/src/passtasks.ts), so the session launches a lens
+     * with a short pointer instead of generating its whole task string. */
+    task_files: boolean;
+    /** `render_outputs`: the posted review body and inline-comments JSON are
+     * rendered deterministically from the findings record (packages/pi-plugin/src/reviewrender.ts)
+     * instead of being written out by the session a second time. */
+    render_outputs: boolean;
+    /** `validator_shards`: how many `pass-validate` children split the
+     * candidates (by file); 1 = one validator. */
+    validator_shards: number;
+    /** `dedup_merge` (docs/duplicate-merge.md): candidates are grouped
+     * deterministically before the validator (the `cluster_findings` tool,
+     * packages/pi-plugin/src/dedup.ts), the validator judges each group as one root cause or
+     * splits it, and a post-check at render time merges two posted findings
+     * that are one root cause posted twice. Off ⇒ none of that: no grouping,
+     * no merge. */
+    dedup_merge: boolean;
+    /** `coverage_check` (packages/pi-plugin/src/coverage.ts): after the lenses return, every
+     * changed non-test source file no lens raised a finding on gets a targeted
+     * pass-sweep row (at most two, packed by line budget), each saying why. Off
+     * ⇒ no coverage rows. */
+    coverage_check: boolean;
+    /** `follow_up` (docs/follow-up-rounds.md): `"delta"` ⇒ every round after
+     * the first is a FOLLOW-UP round — prior findings verified, the PR-owned
+     * change since the last reviewed head reviewed, one pre-approval sweep when
+     * owed — falling back to a full re-review on any doubt. `"full"` ⇒ every
+     * later round is a full re-review. */
+    follow_up: "delta" | "full";
+    /** Above this share of the PR's diff lines (additions + deletions), the
+     * delta is too large to be worth a follow-up round: the round runs in full. */
+    follow_up_max_delta_ratio: number;
+    /** false ⇒ a follow-up round never plans the pre-approval sweep. */
+    follow_up_sweep: boolean;
+    /** After a POSTED approval the sweep is owed only when the PR-owned change
+     * since it reaches this many lines (additions + deletions); 0 ⇒ never.
+     * The default of 500 reflects measurement: post-approval blockers outside
+     * the change sat behind 600+-line pushes, while most post-approval rounds
+     * change fewer than 500 lines. */
+    follow_up_post_approval_sweep_lines: number;
+    /** A follow-up delta of at most this many lines (additions + deletions)
+     * gets a LEAN plan: no per-file pass-sweep rows (pass-baseline reads a small
+     * change whole) and the quality and style lenses offered as addable instead
+     * of planned (they judged the PR in round 1; on a fix push they mostly
+     * re-raise nits). 0 ⇒ never lean. A follow-up round's time tracks its
+     * agent count, and small deltas otherwise fan out to 15–20 agents. */
+    follow_up_small_delta_lines: number;
+    /** `context_pack` (packages/pi-plugin/src/contextpack.ts): `"pack-first"` ⇒ the
+     * daemon writes the round's CONTEXT PACK (the diff, the change since the
+     * last review, the most-changed files' full text) beside its task files, and
+     * every lens session carries it at the very start of its prompt, ahead of its
+     * lens instructions (packages/pi-plugin/src/engine/lens/leaf-cache.ts) — one shared, cached prefix
+     * instead of every lens re-reading the same text uncached. `"off"` ⇒ no
+     * pack. Takes effect only with `[engine] lens_cache_group` > 0 (an unshared
+     * pack would cost more, not less). On by default: measured ~40% cheaper,
+     * with verdicts and recall unchanged. */
+    context_pack: "off" | "pack-first";
+    /** The pack's size cap in tokens (≈4 characters each). */
+    context_pack_max_tokens: number;
+    /** A benchmark lever until measured: a pass-sweep row whose files are ALL
+     * tests, prose or config/data (heuristics.ts `isLightSweepFile`) runs at
+     * this tier instead of the sweep's own. `""` ⇒ off: every sweep row at the
+     * sweep's tier. A profile `min_tier`
+     * for pass-sweep still floors it, and a tier at or above the sweep's own
+     * changes nothing. */
+    sweep_light_tier: "" | PassTier;
+    /** The validator answers with a DECISION TABLE keyed by
+     * candidate id instead of restating every survivor — only a finding whose
+     * text it changed is written out in full (`validate-compact-output`
+     * addendum; the session's half is `{{validator_output_note}}`). What it
+     * decides is unchanged. `false` ⇒ the frozen output format. */
+    validate_compact: boolean;
+    /** Who sizes a FOLLOW-UP round.
+     * `"session"` ⇒ every follow-up round plans the lean core (pass-baseline,
+     * the risk lenses, behaviour-delta, the validator) and offers the full
+     * plan's per-file sweep rows and quality/style lenses as OPTIONAL rows the
+     * main session runs, partly runs or skips — and it decides whether an owed
+     * pre-approval sweep is needed — each with a stated reason, logged.
+     * `"rules"` ⇒ fixed rules: the lean plan only at or under
+     * `follow_up_small_delta_lines`, the pre-approval sweep always run when
+     * owed and the round would approve. */
+    follow_up_extent: "session" | "rules";
+}
+export type NitPolicy = "strict" | "open";
+/**
+ * `[review] preset` — three named review configurations, measured on the
+ * defect benchmark (bench/aacr/RESULTS.md):
+ *
+ *   - `default` — the measured best value. Every lever on with the lean plan:
+ *     on ten PRs no change was designed from it found 81% of the real defects
+ *     (weighted 86%) against 71% before the levers, for $1.02 vs $0.90 a PR and
+ *     the same ~6 minutes.
+ *   - `max` — every model at its highest reasoning level and the full lever
+ *     plan (every intent and placement pass, small sweep groups). Measured on
+ *     smoke10 with the pre-lever plan: 72% of defects vs 44-51%, at ~$2 and ~18
+ *     minutes a PR. For the PRs that warrant it.
+ *   - `low` — every model at low reasoning, the default plan. Half the cost
+ *     and time of `default` (~$0.52, ~3.5 min a PR on fresh10) for about the
+ *     recall the review had BEFORE the levers (69% vs 71% of real defects),
+ *     with fewer high-severity finds and less accurate comments (73%).
+ */
+export type ReviewPreset = "low" | "default" | "max";
+type PresetLevers = Pick<ReviewConfig, "sublenses" | "sweep" | "sweep_max_groups" | "sweep_group_files" | "sweep_group_lines" | "sweep_wide_files" | "behaviour_delta" | "behaviour_delta_max_groups" | "loosened_test_hint" | "intent_min_words" | "placement_min_code_files" | "placement_min_new_file_lines" | "dependency_sources" | "tests_lens" | "quality_lenses" | "quality_min_added_lines" | "style_lens" | "lint_conformance">;
+export declare const REVIEW_PRESETS: Readonly<Record<ReviewPreset, {
+    effort: ReviewEffort;
+    levers: PresetLevers;
+}>>;
+export declare function parsePreset(raw: unknown): ReviewPreset;
+export declare const REVIEW_DEFAULTS: ReviewConfig;
+/**
+ * [escalation] — the optional, OFF-BY-DEFAULT escalation feature (the never-hand-to-a-human
+ * rule).
+ *
+ * Two invariants bound everything this table can express, and neither is a
+ * knob:
+ *
+ *   1. The reviewer STILL DECIDES. An escalation is additive notification
+ *      posted BESIDE a finished verdict. Nothing here can withhold, defer or
+ *      replace one — `src/escalation.ts` has no verdict in its return type and
+ *      is called only after the verdict has been applied.
+ *   2. It escalates a QUESTION, never a review. Every escalation names one
+ *      thing to look at (a file and line range, a migration, a named
+ *      decision) and why that person. There is no way to configure "ask
+ *      someone to review this PR" — the comment body is rendered from the
+ *      scope, not written free-hand.
+ *
+ * With `enabled = false` (the default, and what every shipped config carries)
+ * nothing in this table is read and BEHAVIOUR is identical to a build without
+ * the feature. (Not byte-identical prompt text: the `{{escalation_note}}`
+ * placeholder renders empty and leaves a blank line, exactly as the sibling
+ * `{{directive_note}}` already does. `tests/escalation.test.ts` pins that
+ * whitespace is the ONLY difference.)
+ */
+export type EscalationShape = "comment" | "review_request";
+/** A severity threshold a rule may key on. Matches `packages/pi-plugin/src/severity.ts Severity`
+ * minus "nit", which is never worth a person's attention by definition. */
+export type EscalationSeverityFloor = "P0" | "P1" | "P2" | "P3";
+/**
+ * One operator-defined DETERMINISTIC trigger. No LLM judgement takes part in
+ * evaluating one: given the round's facts, `evaluateEscalationRules` is a pure
+ * function and `tests/escalation.test.ts` drives it directly.
+ *
+ * A rule fires when EVERY condition it declares is met (conditions AND
+ * together) — a rule that declares none never fires, and configuration
+ * validation refuses it rather than shipping a rule that silently does
+ * nothing.
+ */
+export interface EscalationRule {
+    /** Stable name — it appears in the event log and in the posted note. */
+    name: string;
+    /** The GitHub login to escalate to. MUST be one of `targets`. */
+    to: string;
+    /** Why this person, in the operator's own words — rendered verbatim. */
+    why: string;
+    /** Glob-ish path patterns; fires when the PR touches a matching file. */
+    paths: string[];
+    /** PR labels; fires when the PR carries one of them. */
+    labels: string[];
+    /** Fires when the round posted a finding at or above this severity. */
+    min_severity: EscalationSeverityFloor | "";
+    /** Check-run names; fires when the LATEST run of one is not green. */
+    failing_checks: string[];
+}
+export declare const ESCALATION_RULE_DEFAULTS: EscalationRule;
+export interface EscalationConfig {
+    /** OFF by default. False ⇒ no rule is evaluated, no note is rendered into
+     * any prompt, and no escalation mutation is ever built. */
+    enabled: boolean;
+    /**
+     * How an escalation is delivered. `comment` (the default) posts a gated
+     * COMMENT review @-mentioning the person with the narrow ask.
+     * `review_request` ALSO puts the PR in that person's review-requested queue
+     * (the `request_reviewer` gate kind) — GitHub's own UI frames that as
+     * "review this pull request", which is exactly the framing this feature
+     * rules out, so the accompanying comment is still posted and still carries
+     * the narrow ask. `comment` is the shape that matches the intent.
+     */
+    shape: EscalationShape;
+    /** The CLOSED set of logins any escalation may reach. A session-judgement
+     * escalation naming anyone else is dropped and logged; it is not an error
+     * the session can talk its way past. */
+    targets: string[];
+    /** May the PR's session ALSO escalate on its own judgement, bounded to
+     * `targets`? Off by default — the deterministic rules stand alone. */
+    session_judgement: boolean;
+    /** Hard cap on escalations delivered per PR, across all rounds. */
+    max_per_pr: number;
+    /** The deterministic triggers. */
+    rules: EscalationRule[];
+}
+export declare const ESCALATION_DEFAULTS: EscalationConfig;
+export declare const ESCALATION_SEVERITY_FLOORS: readonly string[];
+/** A GitHub login: letters, digits and single inner dashes, at most 39. */
+export declare const ESCALATION_LOGIN_RE: RegExp;
+/**
+ * Parse and VALIDATE `[escalation]`.
+ *
+ * A half-configured live state is made unrepresentable here
+ * rather than only in the wizard: a config with the feature on and no target,
+ * or with a rule pointing at a login that is not a target, or with a rule that
+ * declares no condition, fails to LOAD. A hand-edited config gets the same
+ * refusal the interview does.
+ *
+ * With `enabled = false` NOTHING below the early return is checked, so a
+ * half-filled table that is switched off really is a draft — it cannot wedge
+ * daemon startup. The whole validation set fires the moment the operator
+ * flips the switch.
+ */
+export declare function parseEscalation(raw: Record<string, any>): EscalationConfig;
+/**
+ * [owner] — the system's ONE accountable human, as a configured role. Every
+ * identity surface renders from here: Slack fallback prose,
+ * the companion day-open role label, the pinned-memory head framing, and the
+ * escalation-mention fallback. Empty values degrade to neutral wording
+ * ("the owner" / "the operator"), never to a hardcoded personal name.
+ */
+export interface OwnerConfig {
+    /** Display name for rendered prose. "" ⇒ neutral wording. */
+    name: string;
+    /**
+     * Slack member id (U…). When [slack] is enabled it must be non-empty and a
+     * key of [slack.users]. Legacy alias on INPUT only: a set
+     * `[slack] legacy_owner_slack_id` feeds this when it is empty; nothing reads the
+     * legacy key after load.
+     */
+    slack_id: string;
+    /** GitHub login; the fallback for [review] escalation_mention_default when
+     * that knob is unset. */
+    github_login: string;
+}
+export declare const OWNER_DEFAULTS: OwnerConfig;
+/** Per-model spend rates, keyed by bare model id (e.g. "gpt-6-sol"). */
+export interface ModelPricing {
+    input_per_mtok: number;
+    output_per_mtok: number;
+}
+/** [models] — role models plus the tiered pass-model scheme. */
+export interface ModelsConfig {
+    default: string;
+    conversation: string;
+    /** PassTier → full model spec ("provider/model:thinking"). */
+    tiers: Record<PassTier, string>;
+    /** Passes always run at sol-high, single variant, not raisable. */
+    risk_passes: string[];
+    /** The tier pass-validate runs at — never raised to the round's highest
+     * lens tier, because a validity veto is a `doubted` mark, not a deletion.
+     * Only the profile's `min_tier` for the validator moves it, and only
+     * upward. */
+    validate_tier: PassTier;
+    /** Diffs under this many changed lines start at terra-med (heuristics). */
+    small_diff_lines: number;
+    /** Spend rates keyed by bare model id; consumed by spend accounting. */
+    pricing: Record<string, ModelPricing>;
+    /** ONE reasoning-effort setting for the whole review (`""` = off: every
+     * role and tier keeps the level its own spec names). When set, the thinking
+     * suffix of EVERY model spec above — default, conversation and all
+     * three tiers — is replaced: `low` → `:low`, `medium` → `:medium`, `high` →
+     * the model's highest level (`effort_max`). Applied once, at parse time, so
+     * every consumer (sessions, the agents build, the bench) sees the same
+     * specs. */
+    effort: ReviewEffort;
+    /** The level `effort = "high"` means — the highest a model accepts. pi
+     * 0.87.1 (and 0.99.1, also for gpt-6.1-sol) lists `minimal…high, xhigh, max` for gpt-6-sol (model catalog,
+     * VERIFY-ON-PIN); a model that tops out lower needs this set to its own
+     * ceiling. */
+    effort_max: ThinkingLevel;
+    /** Per-lens tier pins (`[models.pass_tiers]`): pass name → tier.
+     * A pinned lens runs at that tier on every PR whatever the diff size — the
+     * plan names that tier, the lens is not raisable, and every built variant
+     * of it carries that tier's spec. The default is `DEFAULT_PASS_TIERS`
+     * (baseline, sweep, behaviour-delta at sol-high); a config entry replaces
+     * a lens's default pin. Not
+     * for pass-validate (its knob is `validate_tier`) nor for a risk pass
+     * (always sol-high). A profile `min_tier` still floors a pin, and the
+     * validator never follows a pinned lens's tier. */
+    pass_tiers: Record<string, PassTier>;
+    /** Per-lens MODEL overrides (`[models.pass_models]`): pass name →
+     * model spec. Every built variant of that lens runs on that model, at the
+     * thinking level it would otherwise have had (its tier, a pin, the
+     * profile's `effort`) unless the spec names its own. Empty by default — a
+     * benchmark lever (a smaller model for the quality lenses) until measured.
+     * Never for pass-validate nor a risk pass. */
+    pass_models: Record<string, string>;
+}
+/** pi's thinking levels, ascending (pi 0.87.1, unchanged at 0.99.1 and 1.0.0 — VERIFY-ON-PIN). */
+export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/** `[models] effort` — `""` leaves every spec as written. */
+export type ReviewEffort = "" | "low" | "medium" | "high";
+/** "provider/model:thinking" → its model and its pi thinking level, or a
+ * null level when the spec carries no suffix. */
+export declare function splitModelSpec(spec: string): {
+    model: string;
+    thinking: string | null;
+};
+/** Replace (or add) the `:thinking` suffix of one model spec. */
+export declare function withThinking(spec: string, level: ThinkingLevel): string;
+/** The thinking level an effort setting names: `high` is the model's
+ * ceiling (`[models] effort_max`) — the one reading of `[models] effort`, a
+ * lens's profile `effort` and `[scan] effort` alike. */
+export declare function effortLevel(effort: Exclude<ReviewEffort, "">, effortMax: ThinkingLevel): ThinkingLevel;
+/** Apply `[models] effort` to every spec the review runs on. Pure. */
+export declare function applyReviewEffort(models: ModelsConfig): ModelsConfig;
+export declare function parseEffort(raw: unknown): ReviewEffort;
+/** The nonempty effort vocabulary every effort knob shares — `low`,
+ * `medium` (alias `med`) and `high`, case- and space-insensitive — or null for
+ * anything else. What an empty value means is each knob's own call. */
+export declare function normalizeEffort(raw: unknown): "low" | "medium" | "high" | null;
+/**
+ * The shipped per-lens tier pins (measured: high effort on these lenses found
+ * more defects with no high-severity loss, for ~18% more cost per PR). The
+ * three lenses that read the whole diff line by line run at
+ * the `sol-high` tier — gpt-6.1-sol at high effort — on every PR; every other
+ * lens keeps its planned tier. A config's own `[models.pass_tiers]` entry for
+ * one of them replaces its pin (e.g. `"pass-baseline" = "sol-med"`), and a
+ * profile lowers its thinking with `[lenses.<pass>] effort = "medium"`.
+ */
+export declare const DEFAULT_PASS_TIERS: Readonly<Record<string, PassTier>>;
+/** `[engine] lens_pass_deadline_min` when the file does not set it: a
+ * healthy pass takes 20-100 s and the slowest about 4 min, so 8 min only
+ * ever cuts a stalled one. */
+export declare const DEFAULT_LENS_PASS_DEADLINE_MIN = 8;
+/** `[engine] lens_cache_stagger_ms`'s default — every reader's fallback too
+ * (`packages/pi-plugin/src/engine/lens/env.ts` keeps the env reader's copy, pinned equal by a
+ * test). */
+export declare const DEFAULT_LENS_CACHE_STAGGER_MS = 2500;
+/** `[engine] lens_max_concurrency` when the file does not set it: the
+ * companion's desktop number. */
+export declare const DEFAULT_LENS_MAX_CONCURRENCY = 4;
+/** `[engine] lens_cache_group` when the file does not set it. */
+export declare const DEFAULT_LENS_CACHE_GROUP = 5;
+/** What hosts a pi session (`[engine] runtime`): the pi SDK, in-process
+ * (packages/pi-plugin/src/engine/sdkruntime.ts), the one adapter. The `proc` runtime, pi as a
+ * child process, is retired and refused (`parseEngine`). A route that has no
+ * SDK host yet refuses `sdk` (packages/pi-plugin/src/engine/select.ts). */
+export type EngineRuntimeKind = "sdk";
+export declare const ENGINE_RUNTIME_KINDS: readonly EngineRuntimeKind[];
+/** Who launches the lenses (`[pi] lens_runtime`): `engine`, our lens tool and
+ * discovery wave, the only kind. pi's own subagent glue (`native`) is retired
+ * and refused (`parsePiLensRuntime`). */
+export type LensRuntimeKind = "engine";
+export declare const LENS_RUNTIME_KINDS: readonly LensRuntimeKind[];
+/** `[engine]`: which runtime hosts pi sessions, and how its lens tool runs the
+ * passes (the width, the shared prompt cache and the per-pass deadline that
+ * `[pi] subagent_*` used to carry). */
+export interface EngineConfig {
+    runtime: EngineRuntimeKind;
+    /** Process-wide cap on a round's concurrently running lens sessions
+     * (rides the lens tool's env as QCR_SUBAGENT_MAX_CONCURRENCY). */
+    lens_max_concurrency: number;
+    /** Lens sessions share a provider PROMPT CACHE in groups of this many (one
+     * pi session id, the provider's cache key, per group); 0 ⇒ a random id per
+     * session, which gets no cache hits. */
+    lens_cache_group: number;
+    /** How long a group's later sessions wait after its first one started, so
+     * the cache is written before they ask. */
+    lens_cache_stagger_ms: number;
+    /** Per-pass deadline in minutes: a pass still running at the deadline is
+     * aborted and retried ONCE with a fresh deadline, and a second timeout fails
+     * that pass alone. 0 ⇒ no deadline. */
+    lens_pass_deadline_min: number;
+}
+export declare const ENGINE_DEFAULTS: EngineConfig;
+export declare function parseEngine(raw: Record<string, unknown>): EngineConfig;
+/** Defaults for the tiered [models] knobs — older configs keep parsing. */
+export declare const MODELS_TIER_DEFAULTS: Pick<ModelsConfig, "tiers" | "risk_passes" | "validate_tier" | "small_diff_lines" | "pricing" | "effort" | "effort_max" | "pass_tiers" | "pass_models">;
+/** The values `[memory] delivery` takes. */
+export declare const MEMORY_DELIVERY_MODES: readonly ["off", "shadow", "on"];
+export type MemoryDelivery = (typeof MEMORY_DELIVERY_MODES)[number];
+/**
+ * `[scan]`: the companion's whole-repo scan. Read only by the scan
+ * engine inside the companion (src/setup/) — nothing on the VM reads it.
+ */
+export interface ScanConfig {
+    /** Stage 1's reasoning level for `pass-scan` (`high` = the model's
+     * ceiling, `[models] effort_max`). */
+    effort: Exclude<ReviewEffort, "">;
+    /** Stage 1's tier — whose model `pass-scan` runs on, at `effort`. */
+    tier: PassTier;
+    /** Run the scan's SKEPTIC — `pass-validate` in scan mode — over each
+     * case's candidates, at the tier of the lens that raised them. ON by
+     * default; a profile may switch it off. It sorts every finding into a
+     * validity tier — confirmed / likely / doubtful — and kills none: a
+     * refuted finding is kept, marked doubtful. Its cost is part of every
+     * case's measured price. */
+    validator: boolean;
+    /** Repo-relative globs never scanned (packages/pi-plugin/src/glob.ts), on top of tests,
+     * migrations and what no pass reads (lockfiles, binaries, prose). */
+    exclude: string[];
+    /** Units the first-scan calibration run reads (spread across the size
+     * range), before any stage-1 estimate is offered. */
+    calibration_units: number;
+    /** The calibration run's hard stop — it has no estimate to stop at. */
+    calibration_max_usd: number;
+    /** Stage-1 cases in flight at once (background subagents). */
+    concurrency: number;
+    /** One case reads at most this much; a bigger unit splits, name kept. */
+    case_max_files: number;
+    case_max_lines: number;
+    /** Stage 2: a deep lens never measured at a row's tier, effort
+     * and validator setting — no other lens measured there either, and no
+     * factor learnable from a stage-2 measurement with the validator the other
+     * way (stage2.ts `priceStage2Row`) — is priced at stage 1's measured rate
+     * times this. A conservative stand-in
+     * until the first stage-2 run measures the real one; the hard stop holds
+     * whatever it says. */
+    unmeasured_rate_factor: number;
+    /** How hard the scan looks. `standard`: stage 1 is a cheap first look and
+     * stage 2 runs only the rows the companion proposes. `deep`: stage 1 names a
+     * deep lens for every focus file, every deep lens is told to dig past its
+     * row's files, and a stage-2 proposal adds the deterministic FLOOR — every
+     * `deep_lenses` lens over every file stage 1 reads. A deep reading is its own
+     * coverage: a file read only at `standard` is read again. */
+    depth: ScanDepth;
+    /** The deep floor's lenses, each a lens a scan may run
+     * (`SCAN_DEEP_LENSES`); one the profile switched off is skipped. */
+    deep_lenses: string[];
+}
+/** How hard a scan looks — `[scan] depth`. */
+export declare const SCAN_DEPTHS: readonly ["standard", "deep"];
+export type ScanDepth = (typeof SCAN_DEPTHS)[number];
+export declare const SCAN_DEFAULTS: ScanConfig;
+/** The `[scan]` keys a repo profile may override — what is about THIS repo
+ * (how hard to look, whether to validate, what is not worth reading), never
+ * the install's operating limits. */
+export declare const SCAN_PROFILE_KEYS: readonly ["effort", "tier", "validator", "exclude", "depth", "deep_lenses"];
+/**
+ * Validate one `[scan]` table — config.toml's (every key) or a profile's
+ * (`SCAN_PROFILE_KEYS` only). Returns just the keys it set; an unknown key or
+ * a bad value throws naming `where`.
+ */
+export declare function parseScanTable(where: string, raw: unknown, allowed?: readonly string[]): Partial<ScanConfig>;
+/** The `[scan]` keys that say where a run is driven, not how it scans. */
+export declare const SCAN_SANDBOX_KEYS: readonly ["sandbox", "pihome_volume", "image"];
+/** `[scan]` from config.toml: the defaults, overlaid by what it sets. The
+ * sandbox keys are parsed apart (`parseScanSandbox`). */
+export declare function parseScan(raw: unknown): ScanConfig;
+/** A key the table must have: its value, or a throw naming it. */
+export declare function req(obj: Record<string, unknown>, key: string): unknown;
+/** The overseer session is gone: its two knobs are still ACCEPTED so a
+ * live config does not break, read by nothing, and named here once at parse. */
+export declare function configDeprecations(raw: Record<string, any>): string[];
+export declare function parseModels(raw: Record<string, any>, presetEffort?: ReviewEffort): ModelsConfig;
+/**
+ * Validate the per-lens knobs — `[review] skip_lenses`,
+ * `[review] validate_consequence_rule`, `[models.pass_tiers]` and
+ * `[models.pass_models]`. Called by
+ * `parseConfig` and again by the bench's `--config` overrides (which write
+ * past the parser), so both routes refuse the same things.
+ */
+export declare function validateLensKnobs(cfg: Pick<CoreConfig, "review" | "models">): void;
+/** Full model spec ("provider/model:thinking") for a pass tier. */
+export declare function tierModel(cfg: Pick<CoreConfig, "models">, tier: PassTier): string;
+/** `[pi]`: the pinned pi and where its sessions live, and who launches a
+ * round's lenses. */
+export interface PiConfig {
+    package: string;
+    version: string;
+    session_dir: string;
+    /** Who launches a round's lenses: `engine`, our lens tool and discovery
+     * wave on an SDK session, the only kind. */
+    lens_runtime: LensRuntimeKind;
+    /** `lens_runtime = engine` only: the round's engine starts the planned
+     * discovery wave itself at round start (rule 9) and the main session joins
+     * it through `lens_wave`. On by default with `lens_runtime = engine`; off:
+     * the main session launches the wave, with the same tools. */
+    engine_wave: boolean;
+}
+/**
+ * The review config: the sections of config.toml the review core reads. The
+ * app's `Config` (src/config.ts) extends it with every other surface's, so
+ * whatever takes a `CoreConfig` takes the daemon's config as it is.
+ */
+export interface CoreConfig {
+    dry_run: boolean;
+    /** The selected profile's resolved per-lens tuning
+     * (`[lenses.<pass>]` in profile.toml, packages/pi-plugin/src/lenstuning.ts). config.toml never
+     * sets it: `applyProfileTuning` overlays it after parsing, which is what
+     * makes the profile win over config.toml, the preset and the defaults.
+     * Absent or empty ⇒ untuned. */
+    lenses?: LensTuningMap;
+    /** The selected profile's posting policy (`[posting]` in profile.toml,
+     * packages/pi-plugin/src/postingpolicy.ts), overlaid by `applyProfilePosting`. Absent ⇒ the
+     * default posting behaviour; an all-default policy is never attached. */
+    posting?: PostingPolicy;
+    github: GithubConfig;
+    models: ModelsConfig;
+    engine: EngineConfig;
+    pi: PiConfig;
+    guards: GuardsConfig;
+    review: ReviewConfig;
+    escalation: EscalationConfig;
+    owner: OwnerConfig;
+    /** The whole-repo scan's defaults. The repo profile's `[scan]`
+     * table overrides the keys in `SCAN_PROFILE_KEYS` (`applyProfileScan`,
+     * packages/pi-plugin/src/profiles.ts) — the profile wins, as for per-lens tuning. */
+    scan: ScanConfig;
+}
+/** `[github]`: base_branch/clone_dir default so older configs keep parsing.
+ * `secrets_dir` is as written; the reader that needs the secrets locates
+ * them (src/homes.ts `locateSecrets`). */
+export declare function parseGithubSection(raw: Record<string, any>): GithubConfig;
+/** Refuse a `[github]` table that leaves out a key every config names. */
+export declare function requireGithubKeys(github: GithubConfig): void;
+/** `[review] preset`. It shapes both [models] (reasoning level) and [review]
+ * (the levers), so it is read before either is parsed. */
+export declare function presetOf(raw: Record<string, any>): ReviewPreset;
+/** `[pi]`, with the lens runtime defaulted and checked and the retired keys refused. */
+export declare function parsePiSection(raw: Record<string, any>): PiConfig;
+/** `[guards]` over its defaults. */
+export declare function parseGuardsSection(raw: Record<string, any>): GuardsConfig;
+/** `[owner]` over its defaults (the legacy Slack alias folds in later,
+ * `foldLegacyOwnerSlackId`). */
+export declare function parseOwnerSection(raw: Record<string, any>): OwnerConfig;
+/** `[review]`. [review.directives] merges under its own spread so a partial
+ * table extends the defaults instead of clobbering the sibling keys. The
+ * preset fills every lever the file does not set itself; an explicit key
+ * always wins, so `preset = "max"` + `sweep = false` means exactly that. */
+export declare function parseReviewSection(raw: Record<string, any>, preset: ReviewPreset): ReviewConfig;
+/** The checks on a parsed `[review]` (and the per-lens knobs), run once the
+ * whole config is built. */
+export declare function validateReviewSection(cfg: Pick<CoreConfig, "review" | "models">): void;
+/** Legacy alias: a set `[slack] legacy_owner_slack_id` feeds [owner] slack_id when
+ * that is empty; a conflicting pair is an error that names the NEW key. After
+ * this fold nothing reads the legacy key. */
+export declare function foldLegacyOwnerSlackId(raw: Record<string, any>, owner: OwnerConfig): void;
+/**
+ * The review sections of a config.toml, parsed and checked exactly as the
+ * whole-file parser (`parseConfig`, src/config.ts) parses them. The other
+ * sections are not read, so a file that only names the review's sections is
+ * a whole review config. `[github] secrets_dir` stays as written. `warn`
+ * hears each deprecated key once.
+ */
+export declare function parseCoreConfig(toml: string, opts?: {
+    warn?: (line: string) => void;
+}): CoreConfig;
+export {};
+//# sourceMappingURL=reviewconfig.d.ts.map