@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/config.example.toml

@@ -0,0 +1,1067 @@
+# quickreviewd — EXAMPLE config. Copy to config.toml and fill in.
+#
+# Every runtime knob lives here (spec §2). The values below are safe defaults:
+# dry_run is ON (every GitHub mutation is recorded to state/dryrun/ instead of
+# executed) and every identity is empty. The ~10 values a new operator must
+# supply are marked "← FILL (n)" — grep for FILL. Flip dry_run to false only
+# as a deliberate cutover act, never as part of setup.
+#
+# YOU DO NOT HAVE TO FILL THIS BY HAND: `scripts/qcr onboard` interviews you
+# for the few values only you can answer, derives the rest, and patches this
+# file in place — every comment survives, and a re-run edits only what changed.
+# It never writes dry_run in either direction; going live is its own explicit
+# step. See docs/onboarding.md.
+# ONE mutation class is exempt and executes for real even here: the App
+# re-pointing its OWN webhook URL (see [ingress] below) — it can never touch
+# the reviewed repo, and every execution is logged loudly.
+
+dry_run = true
+
+# The operations timezone: whose calendar day the system runs on.
+# Every day-scoped feature (the [feedback] same-day addendum + its daily
+# expiry, metrics day buckets, TUI alert memory, companion day rollover)
+# derives its day from this one knob; [eod] and [slack.policy] `timezone`
+# default from it and may still be overridden in their own sections.
+[ops]
+timezone = "UTC"                             # ← FILL: your IANA timezone, e.g. "Europe/Warsaw"
+
+[github]
+repo = ""                                    # ← FILL (1): the repo to review, "owner/name"
+app_slug = ""                                # ← FILL (2): your GitHub App slug
+bot_login = ""                               # ← FILL (3): the App bot login, "<app_slug>[bot]"
+review_team = ""                            # ← FILL (4): "org/team" whose review request triggers
+# There is no reviewer knob here. The reviewer never hands a PR back: it always
+# decides on the merits and posts a verdict. If you want a named person told
+# about a particular KIND of change, that is the optional [escalation] section
+# further down — off by default.
+trigger_label = "AI review requested"
+in_progress_label = "AI review in progress"
+reviewed_label = "Automatic Review"
+improvement_label = "Bot improvement"
+issue_label = "bot-filed"
+# secrets dir: app_id, app.pem, webhook_secret, tunnel_token; optional openai_api_key (pi, API-key
+# route) and openai_embeddings_api_key (only with embedding_provider = "openai" in the openviking table)
+# "" (recommended) = the install's config home, $XDG_CONFIG_HOME/qcr/<install>/secrets (the old
+# ~/.config/quickreview-bot is never read — `qcr install migrate` moves it). A path here wins.
+secrets_dir = ""
+# The repo's default branch: the improvement filer's PR base, the
+# replay diff base, the CLI-ops fixture base. PR review rounds always use each
+# PR's own base_ref from the GitHub API, never this.
+base_branch = "main"                         # ← FILL: your default branch ("main"/"master")
+# Base-clone directory name under the sandbox root. "" (recommended) derives
+# it from the repo slug's basename — "owner/name" ⇒ "name".
+clone_dir = ""
+
+[owner]
+# The system's ONE accountable human, as a configured role. Every
+# identity surface renders from here: Slack prose, the companion day-open
+# labels, the pinned-memory head framing, the escalation-mention fallback.
+# Empty values degrade to neutral wording ("the owner" / "the operator").
+name = ""                         # ← FILL: the operator's display name for rendered prose
+slack_id = ""                     # ← FILL (if enabling Slack): U…; required then, and a [slack.users] key
+                                  # (legacy alias on input: [slack] legacy_owner_slack_id)
+github_login = ""                 # ← FILL: operator GitHub login; escalation-mention fallback
+
+[server]
+hostname = ""                                # ← FILL (6): the public webhook hostname.
+                                             #   Leave empty when your ingress assigns
+                                             #   its own (the quick tunnel does) — then
+                                             #   [ingress] below carries the shape.
+port = 8787                                  # loopback only; your HTTPS ingress fronts it
+                                             #   (a tunnel sidecar, cloudflared on the
+                                             #   host, or any reverse proxy)
+
+# [ingress] — webhook-URL self-heal, for tunnels whose hostname
+# ROTATES (the laptop quick-tunnel route). The tunnel sidecar writes
+# its assigned bare hostname (e.g. "abc.trycloudflare.com") to `hostname_file`;
+# the daemon watches it and re-points the GitHub App's own webhook URL on
+# change (JWT-authed PATCH /app/hook/config, read-back verified). This is the
+# ONE mutation class that executes even in dry_run (AGENTS.md invariant 6) — loudly
+# logged, structurally closed to this one kind; it
+# touches only the App's own configuration, never the reviewed repo. Off by
+# default: with the section absent (or shape = "none") no watcher ever starts —
+# a stable hostname (named tunnel, VM route) needs none of this.
+#[ingress]
+#shape = "tunnel-file"                       # "none" (default) | "tunnel-file"
+#hostname_file = ""                          # "" ⇒ <root>/state/ingress/hostname
+#debounce_ms = 3000                          # settle time after a file change
+#sweep_interval_s = 300                      # polling backstop behind fs.watch
+
+[daemon]
+poll_interval_s = 300
+# Rounds are network-IO-bound (model calls), not CPU-bound; the container's
+# 2 CPU / 8 GB Docker cap is the hard resource guard.
+max_concurrent_rounds = 12
+round_deadline_min = 75
+# A round overdue with no verdict whose session is dead is
+# self-requeued by the daemon (fresh dispatch to the PR's own session) at most
+# this many times per PR head. Past the cap the round is abandoned as an
+# anomaly and the PR RETURNS TO ITS STANDING-VERDICT STATE — never an approval,
+# and never a park: there is no "awaiting human" state.
+max_self_requeues = 2
+# Lost-prompt net: a running round whose inject file was consumed but whose
+# session shows NO activity since the round started is re-queued (once per
+# head, inside the max_self_requeues cap) after this many minutes — well before
+# the deadline, so a dropped round prompt does not cost a full deadline window.
+round_stall_grace_min = 10
+# Durable daemon→Pi stage leases. Start is short because no model
+# work exists yet; running is a fixed hard cap above the measured 23.4m live
+# maximum and below the 75m defense-in-depth round deadline. Unknown evidence
+# gets one minute once, never an open-ended extension.
+session_command_start_lease_s = 120
+session_command_running_max_min = 45
+# Command-correlated execution milestones: no first pass, incomplete pass plan,
+# and all-passes-done/no-verdict. Absolute start-derived bounds; activity cannot
+# renew them.
+round_first_pass_max_min = 5
+round_passes_max_min = 35
+round_finalize_grace_min = 5
+# Once a round's review is CONFIRMED posted, a stage limit does not cancel
+# it — the session's tail (ledger, findings record, verdict
+# file) gets this long after the posting, and a round still without a verdict
+# then is settled from the posting receipt. Never a requeue, never a second
+# posting.
+round_posted_tail_grace_min = 15
+# A follow-up round whose pre-approval sweep is owed (a whole
+# round-1-style plan after the delta's) gets this many extra minutes for its
+# passes and its hard cap.
+# follow_up_sweep_extra_min = 20
+posting_receipt_grace_s = 120
+# A review POST GitHub answers 5xx (or not at all) is handed to the daemon
+# (receipt `deferred`) and retried at these minutes after the first failure,
+# each attempt through the gate after a marker read; past the window the PR
+# goes FAILED_LOUD (u to recover).
+# posting_retry_offsets_min = [4, 12, 36]
+# posting_retry_window_min = 60
+session_command_unknown_grace_s = 60
+session_command_unknown_max_checks = 1
+session_command_max_start_retries = 2
+# pi refuses every prompt while it compacts, so a command queued
+# behind a compaction the session's inject bridge reports running is late, not
+# lost — its start lease is held open for up to this long. Past it, the
+# bounded same-session redelivery (max_prompt_redeliveries), and only then the
+# kill-and-replay recovery, take over.
+session_compaction_max_s = 600
+# The central lens permit broker (bot workers): the most lens sessions alive at
+# once across EVERY worker, granted first-in first-out. 20 is the VM's ruling
+# (the CPU gate measured 20 sessions fine on 2 cores). Grants are spaced at
+# least lens_grant_stagger_ms apart so a full wave never creates its sessions
+# in one burst (the gate measured a 0.7-2.5 s loop stall for 8-20 at once);
+# 0 turns the spacing off. status.json `permits` shows the use and the queue.
+lens_permits = 20
+lens_grant_stagger_ms = 250
+# The idle-PR answer worker: an operator's message to a PR with no running
+# worker is answered at once by a short worker that resumes the PR's session,
+# replies and exits. It is ended at answer_timeout_s of wall clock and stops at
+# answer_cap_usd of its own spend. It posts only when the message carried
+# may_post (the viewer's Alt-p, `qcr message --may-post`), through the one gate.
+answer_timeout_s = 600
+answer_cap_usd = 2
+round_stage_supervisor_stale_s = 180
+# The daemon watches its own event loop (status.json
+# `daemon.event_loop`, `qcr status`, the TUI board). One delay of
+# event_loop_stall_max_s or more, or a p99 of event_loop_stall_p99_s or more
+# over a window its samples cover, is a stall: it wakes the overseer
+# (`daemon_event_loop_stalled`) at most once per cooldown, naming the cause —
+# "the loop itself blocked" when the daemon itself was on CPU for most of the
+# stall (the stall's own evidence wins; any throttling is named beside it);
+# else "CPU starved" when the container (/sys/fs/cgroup/cpu.stat, over the
+# same window) was throttled in event_loop_starved_throttle_ratio of its CFS
+# periods or more; else "cause unknown" (host contention or a blocking wait).
+event_loop_window_s = 300
+event_loop_stall_max_s = 10
+event_loop_stall_p99_s = 2
+event_loop_wake_cooldown_min = 60
+event_loop_starved_throttle_ratio = 0.2
+# Zombie-round expiry: a round stuck 'overdue' longer than this whose
+# PR has since verdicted/closed (i.e. a rerun would never touch it) is expired.
+# 0 disables the sweep.
+expire_overdue_after_h = 24
+
+[eod]
+time = "18:00"
+# timezone defaults from [ops]; uncomment to run the EOD sweep on another clock.
+#timezone = "Europe/Warsaw"
+# Daily overseer heartbeat: anomaly-table + digest review pass.
+heartbeat_time = "09:00"
+# Watch the owner's pinned entries across the sweep. Curation must never
+# touch them; this makes the invariant detectable rather than merely
+# instructed. The window closes early when the day's digest appears.
+pinned_watchdog = true
+pinned_watchdog_window_min = 90
+
+[caps]
+improvement_pr_max_lines = 50
+improvement_pr_max_files = 3
+improvement_pr_per_day = 1
+improvement_pr_per_week = 3
+issues_per_day = 3
+# Paths a bot improvement PR may never touch. This value REPLACES
+# the shipped default shown here — adjust to your repo's shape — but files
+# named .env* are refused unconditionally regardless of this list.
+improvement_pr_deny_prefixes = ["migrations/", "infra/", "ansible/", ".github/workflows/"]
+
+[models]
+# default for every role; tiered pass models below
+# Provider prefix is `openai-codex/` — the ChatGPT-OAuth route's provider key
+# in pi's auth.json (direct `openai/` needs an API key we don't ship).
+default = "openai-codex/gpt-6.1-sol"
+conversation = "openai-codex/gpt-6.1-sol"
+# Passes always run at sol-high — single variant, not raisable (already top).
+risk_passes = ["pass-security", "pass-prod-risk", "pass-data-safety"]
+# pass-validate's tier — its own configured tier (floored by a repo profile's
+# min_tier for it), never raised to match a lens (src/dispatch.ts
+# validatorTier). Shipped at sol-high: the validator is the adversarial gate
+# over every finding. One validator call per round — not a hot-path multiplier.
+validate_tier = "sol-high"
+# Diffs under this many changed lines (additions+deletions) start at terra-med.
+small_diff_lines = 150
+# [models.pass_tiers] — per-lens tier pins: pass name → tier
+# name (a key of [models.tiers]). SHIPPED DEFAULT (src/config.ts
+# DEFAULT_PASS_TIERS): pass-baseline, pass-sweep and
+# pass-behaviour-delta at "sol-high" (gpt-6.1-sol at high effort) — measured
+# +6 defects on 18 AACR PRs for +18% cost per PR. An entry here replaces that
+# lens's default pin (e.g. "pass-baseline" = "sol-med"); a repo profile lowers
+# one lens's thinking with [lenses.<pass>] effort = "medium". A pinned lens
+# runs at that tier on every PR whatever the diff size — the plan names it, it
+# is not raisable, and every built variant of it carries that tier's spec. The
+# validator never follows a pinned lens (it runs at validate_tier).
+# Not for pass-validate (use validate_tier) nor for a risk pass (always
+# sol-high). A profile min_tier still floors a pin. Unknown passes or tiers
+# are refused at load. e.g.
+#   [models.pass_tiers]
+#   "pass-sweep" = "sol-high"
+#   "pass-baseline" = "sol-high"
+
+[models.tiers]
+# PassTier → model spec; the whole spec (incl. the `:thinking` suffix) rides
+# the built agent's `model:` field — pi's --model accepts the suffix, and the
+# native subagent extension reads only that field.
+"terra-med" = "openai-codex/gpt-6.1-sol:medium"
+"sol-med" = "openai-codex/gpt-6.1-sol:medium"
+"sol-high" = "openai-codex/gpt-6.1-sol:high"
+
+[models.pricing]
+# Spend rates keyed by bare model id, USD per million tokens. Consumed by
+# spend accounting; empty entries fall back to unpriced.
+# "gpt-6-sol" = { input_per_mtok = 0.0, output_per_mtok = 0.0 }
+
+[tui]
+# qcr tui — the operator TUI on the owner's PC, polling the review VM over ssh.
+# Read-only against the VM except the user's own keystrokes + inject files.
+#
+# target — where the daemon container lives relative to this TUI:
+#   "ssh"   — the VM/server topology (the always-on recommendation): every
+#             poll, attach, digest read and evidence copy rides
+#             `ssh <ssh_host> …`, sharing one control master.
+#   "local" — the laptop topology (everything on THIS machine, e.g. the
+#             compose stack): the SAME commands run against local docker
+#             directly and no ssh process is ever spawned. `ssh_host` is
+#             ignored; `sudo_docker` still decides the sudo prefix. The
+#             memory forward follows this knob too — it reaches the daemon
+#             container's loopback memory engine with a plain `docker exec`
+#             (the forward script's --local mode) instead of the ssh hop.
+# Always explicit: an empty ssh_host does NOT mean local.
+target = "ssh"
+ssh_host = ""                                # ← FILL (7): ssh alias of the VM running the container
+                                             #   (leave "" when target = "local" — it is unused)
+container = "quickreview-sandbox"       # bundled local Compose: "quickreview-daemon-1" (onboarding fills this)
+memory_container = ""             # the container the memory forward relays into. "" = `container`
+                                  # (OpenViking is the daemon container's child). On a VM running
+                                  # the memory sidecar (the openviking table's endpoint =
+                                  # "remote") set "quickreview-memory"; flip it back with the endpoint.
+remote_state_dir = "/opt/quickreview/state"  # host path on ssh; inside the daemon container on local
+remote_sandbox_root = ""         # "" = read the container's qcr.layout label (release: /opt/qcr, legacy: /opt/quickreview/sandbox);
+                                  # a value here wins and is never probed
+sudo_docker = true                # docker on the VM needs sudo (root-owned socket)
+poll_interval_s = 3
+stale_after_s = 90                # DATA STALE banner past this written_at age
+                                  # (the daemon rewrites status.json every ~30s)
+msg_timeout_s = 30                # quick-message: pending → undelivered after this
+evidence_timeout_s = 60           # evidence copier: per-remote-read
+                                  # budget. A wedged ssh costs one sweep — the
+                                  # copy is retried on the next poll, never
+                                  # blocking the poll or the paint loop.
+evidence_why_interval_s = 10      # evidence sweep pace: at most one
+                                  # `qcr why` per this many seconds (gap from
+                                  # the end of the last one), clamped 5–600 s.
+                                  # No `why` at all while the daemon is draining
+                                  # or its heartbeat is stale.
+
+[pi]
+# VERIFY-ON-PIN: package + version mirrored in package.json "qcrPi" block and the
+# ansible group_vars; the image never floats.
+package = "@earendil-works/pi-coding-agent"
+version = "1.4.0"
+session_dir = "state/pi-sessions"
+# The lens settings that used to live here (subagent_max_concurrency,
+# subagent_cache_group, subagent_cache_stagger_ms, subagent_pass_deadline_min)
+# moved to [engine] (lens_max_concurrency, lens_cache_group,
+# lens_cache_stagger_ms, lens_pass_deadline_min); a config that still sets them
+# is refused.
+# Who launches a round's lenses: "engine", our lens tool and discovery wave on
+# an SDK session, the only value ("native", pi's own subagent glue, is retired
+# and refused).
+# lens_runtime = "engine"
+# The round's engine starts the planned discovery wave itself at round start
+# (rule 9) and the main session joins it with lens_wave. false = the main
+# session launches the wave, with the same tools.
+# engine_wave = true
+
+# What hosts a pi session on the review, bench and scan routes: "sdk" runs it
+# in-process on the pi SDK (the default and the only value; "proc", pi as a
+# child process, is retired and refused). `qcr review` and the bench (`qcr-bench
+# review`, `defect-judge`) host the SDK: in the bench each case, and each case
+# of the judge's pool, runs in a host process of its own, so one crash or frozen
+# loop costs one case, and `[pi] lens_runtime = "engine"` gives the review our
+# lens tool. A route that has no host yet refuses "sdk".
+# In the image the SDK runs the model's bash as the separate tool uid and
+# fences the file tools off /proc, /run/qcr-in and the agent dir.
+# The scan runs its leaves on the SDK inside its own detached driver process
+# (`qcr scan start`), never inside the companion's pi; a scan the companion
+# drives itself refuses.
+# The lens tool's settings ride here too (docs/prompt-caching.md):
+#   lens_max_concurrency   cap on running lens sessions per round (default 4);
+#                          the daemon's [daemon] lens_permits is the bot's
+#                          cross-worker budget
+#   lens_cache_group       lens sessions per shared provider prompt-cache key
+#                          (default 5; 0 = a random id each, no cache hits)
+#   lens_cache_stagger_ms  how long a group's later sessions wait after its
+#                          first, so the cache is written first (default 2500)
+#   lens_pass_deadline_min per-pass deadline in minutes: a pass still running
+#                          is aborted and retried ONCE, and a second timeout
+#                          fails that pass alone; 0 = no deadline (default 8)
+# [engine]
+# runtime = "sdk"
+# lens_max_concurrency = 4
+# lens_cache_group = 5
+# lens_cache_stagger_ms = 2500
+# lens_pass_deadline_min = 8
+
+[memory]
+# Round seeding — how much memory rides each round prompt and how
+# long the daemon waits for it. Memory NEVER blocks or delays a round: past
+# the deadline the round dispatches memory-less and logs the gap.
+context_tokens = 2000
+# The seed's whole budget, in ms (clamped 100…15000). One document embedding
+# on a 2-CPU VM takes 3 s or more, and a seed's query queued behind one needs
+# room for it. It costs at most
+# a few seconds on a ~14-minute round. Keep it above the search's own
+# search_timeout_ms (the openviking block, below).
+context_timeout_ms = 9000
+# The embedding tail of one written finding case, in ms (clamped
+# 0…30000, 0 = off): the server goes on embedding a case batch after its
+# write returns, so a round seed that starts within (cases × this) of the
+# write waits that out before it sends its search — inside context_timeout_ms,
+# never past it, keeping 3 s of the budget for the search itself. While any
+# review round runs or is queued, the case writer also holds its backfill,
+# its late activity and every case those two owe (only cases the capture
+# pass's sync owes are written meanwhile).
+case_embed_tail_ms = 4000
+# Memory health (src/memory/health.ts) — how an outage reaches a
+# person. Every probe_interval_s the daemon lists the reviewer memories root
+# AUTHENTICATED, once with its own key and once with the sessions' ovcli.conf.
+# A refused credential wakes memory_auth_failed at once (never graced, never
+# held by a drain); no authenticated answer for down_after_min wakes
+# memory_down (a server still warming up reads "unknown" for boot_grace_min;
+# a drain holds the wake until it lifts). Either re-wakes every rewake_h while
+# it lasts. The state rides status.json `memory`: the TUI board banner, its
+# desktop notification, `qcr status`, and ONE tracker ticket the TUI files for
+# an incident older than incident_ticket_after_min.
+probe_interval_s = 120
+down_after_min = 10
+boot_grace_min = 5
+rewake_h = 6
+incident_ticket_after_min = 120
+# Writes that stick: every [feedback] signal is ledgered with
+# its memory state, and whatever memory has not taken yet the backfill pump
+# writes every backfill_interval_s (at most 20 a tick, only while memory
+# reads healthy). A signal owed for longer than write_backlog_after_min wakes
+# memory_write_backlog (and again every rewake_h while the backlog lasts). A
+# signal memory refused 12 times is given up on, loudly, and queued again at
+# the daemon's next start and once a day.
+backfill_interval_s = 60
+write_backlog_after_min = 120
+# Finding cases (src/cases.ts): one document per posted finding a
+# human answered or whose fate is known, in reviewer memory's `finding-cases/` — the
+# learner's context, searched by the EOD curator and the companion, never by a
+# review round. Every cases_interval_s the daemon works out from state.db which
+# cases are new or changed and, only while memory reads healthy, writes up to 2
+# (one batch-write — each case is ~3.4 s on the VM's one-thread embedder — and
+# never started while a review round is reading memory) and
+# backfills two more PRs from the last cases_backfill_days days (resumable; 0
+# turns the backfill off).
+cases_interval_s = 120
+cases_backfill_days = 60
+# The learner (src/learner/): lessons_mine_lead_min before the EOD
+# sweep (and on `qcr lessons mine`) the daemon mines the human outcomes of the
+# last lessons_mine_days — refuted / contested findings, the [feedback]
+# ledger, human comments and REQUEST_CHANGES on PRs the bot approved, recheck
+# flips, and commits that changed a bot-approved PR's lines within
+# lessons_recall_window_days of its merge — into lesson CANDIDATES. The EOD
+# sweep is handed them as state/eod/<day>/outcomes.md (at most
+# lessons_packet_new_max new a day, misses first; every undecided one is
+# carried; undecided after lessons_expiry_ops_days it expires, recorded) and
+# answers with an `eod-curation-receipt`. No receipt within
+# lessons_receipt_wait_min wakes eod_curation_missing; a refused or unfound
+# lesson wakes eod_lessons_not_persisted. The digests' "Learnings" from
+# lessons_digest_backfill_from..to (written while memory refused every write)
+# become candidates once.
+lessons_mine_lead_min = 15
+lessons_mine_days = 45
+lessons_receipt_wait_min = 180
+lessons_expiry_ops_days = 7
+lessons_packet_new_max = 40
+lessons_recall_window_days = 14
+lessons_recurrence_days = 90
+lessons_digest_backfill_from = "2026-08-31"
+lessons_digest_backfill_to = "2026-10-02"
+# How curated lessons and past finding cases reach a review.
+#   "off"    — nothing runs: no selection, no shadow ledger.
+#   "shadow" — (the shipped value) every round selects the lessons and cases
+#              it WOULD carry, through OpenViking — one prefetch per round
+#              (two finds: one for the lessons, one for the cases), started
+#              after the round's handoff so it never delays the round, at
+#              most shadow_budget_ms (≤ 20000) — and the shadow ledger records
+#              them, plus every posted finding a delivered dont-raise lesson
+#              would have touched. No prompt, task file or agent changes.
+#   "on"     — delivery: the same selection, awaited beside the round's
+#              memory seed within delivery_budget_ms (≤ 2000), reaches each
+#              lens's task file, the lessons files of the validator and of
+#              any lens the session adds, the main session's "Lessons in
+#              force" index and past-review cases (the bleed rule
+#              reworded), the validator's demotion-only `lesson-shape`
+#              addendum, and the repo facts for the paths a recheck or an
+#              author reply touches. A round that selects nothing renders
+#              exactly as under "off".
+# Read `qcr lessons shadow-report` (and the `lessons` clause of `qcr status`)
+# before switching to "on". The operator's kill switch sits beside this one:
+# `qcr lessons off|on` and `qcr lessons suppress|unsuppress <lesson>`, through
+# the root-sealed commands/operator/ channel only, stored in state.db.
+delivery = "shadow"
+delivery_budget_ms = 2000
+shadow_budget_ms = 10000
+# HOW MANY items the round's one context search may draw from each area it
+# searches. `context_tokens` above is the budget; this is the corpus — the two
+# bind independently.
+#
+# A round searches `experiences/` ONLY — the curated lessons of the memory
+# layout (src/memory/layout.ts). Ops notes and feedback events live in `events/`,
+# the owner's unpinned instructions in `preferences/` (the pinned ones ride the
+# round's guaranteed head in full), and none of them belongs in a round's
+# recalled context; nor do the built-in `skills`/`resources` overview blurbs
+# that take most of the block when no quotas are set.
+# Any other key here is IGNORED with one log line, and `experiences` defaults
+# to 24 when it is missing. The count is generous on purpose — its job is to
+# name the area, and `context_tokens` decides how much rides the prompt.
+context_quotas = { experiences = 24 }
+
+[openviking]
+# OpenViking (github.com/volcengine/OpenViking) — the review system's context
+# store, running as a SECOND process inside the quickreview container on
+# LOOPBACK :1933. The daemon supervises it as a child process
+# (restart + backoff, stdout folded into the daemon log) and reports its
+# health, version, RSS and CPU in the heartbeat.
+#
+# TRIPLE-MIRRORED PINS, same discipline as [pi]: `version` and
+# `llama_cpp_python_version` here == deploy/ansible/group_vars/all.yml
+# (openviking_version / llama_cpp_python_version) == the Dockerfile venv layer,
+# which installs BOTH by referencing those group_vars — never a literal.
+# tests/openviking.test.ts fails on any drift; the heartbeat drift-checks the
+# running server's self-reported /health version against `version` too.
+#
+# Every path below is a CONTAINER path. On a dev PC the binary is absent: the
+# supervisor logs once, reports unavailable, and never crash-loops.
+enabled = true
+# Who runs the server. "local" (the default): the daemon supervises it, and the
+# local embedder, as children of this container. "remote": the memory sidecar
+# (docker/memory/) runs both on `host`:`port` — set host to the sidecar's name
+# on the container network — and the daemon only probes its health. The sidecar
+# owns the boot provisioning and the embedder re-embed. Never publish its port.
+endpoint = "local"
+version = "0.4.15"
+# The vendored pi extension's upstream base commit (extensions/vendor/
+# openviking-pi). Pinned beside the server version so a bump re-verifies the
+# vendored patch series rather than silently rebasing onto new upstream behaviour.
+extension_commit = "d436baa23c83938b22bb0aab08b0ce48568b5ff4"
+# The daemon and every review session act as this user, holding a key the
+# server confines to it — that confinement is what keeps companion memory out
+# of a posted review. NEVER an ADMIN or ROOT key: ADMIN grants no cross-user
+# data access anyway, and can list every user key in plaintext.
+user = "reviewer"
+account = ""
+reviewer_key_file = "openviking_reviewer_key"
+# ov.conf `server.auth_mode`. `api_key` is the required posture: the
+# server confines each USER key to its own tree, and that confinement is the
+# only thing keeping companion memory out of a posted review. `dev` bypasses
+# authentication on loopback, which makes the two-user design nominal.
+# MIRRORED into group_vars (openviking_auth_mode), which the entrypoint renders; tests/openviking.test.ts
+# and the scripts/deploy.sh preflight both refuse on drift.
+auth_mode = "api_key"
+# The SERVER's own root key, by file name under the secrets mount. ov.conf
+# needs it to run in api_key mode and boot provisioning needs it to mint users.
+# It is the server's credential, never a client's: no daemon surface, no review
+# session and no companion process ever holds it (writeOvcliConf refuses it as
+# a session credential; packages/pi-plugin/extensions/bash-guard.ts refuses to read the files that
+# carry it). Mirrored as openviking_root_key_file.
+root_key_file = "openviking_root_key"
+# The users boot provisioning ENSURES exist — created if absent, left exactly
+# as they are if present, and NEVER rotated (a rotation orphans the keys
+# already distributed to the companion's PC). Mirrored as
+# openviking_provision_users (comma-joined).
+provision_users = ["reviewer", "companion"]
+request_timeout_ms = 10000
+# The round seed's one context search, in ms (clamped 100…15000) — above one
+# document embedding's time, and below
+# [memory] context_timeout_ms, and a seed that sent its search late passes
+# the time it has left, which wins when shorter.
+search_timeout_ms = 8000
+default_category = "experiences"
+read_cache_ttl_ms = 15000
+# NOT an openviking dependency — an undeclared optional extra. Without it the
+# default local dense embedder raises EmbeddingConfigurationError at startup,
+# so the official image cannot boot (verified against a running 0.4.15 server).
+# It is also the runtime of the local English embedder (below).
+llama_cpp_python_version = "0.3.35"
+host = "127.0.0.1"                # loopback ONLY — the port is never published
+port = 1933
+bin = "/opt/openviking/venv/bin/openviking-server"
+# ~/.openviking is symlinked here at boot: memory lives on the STATE VOLUME so
+# it survives an image rebuild. config_file/workspace derive from this.
+home = "/opt/quickreview/state/openviking"
+# config_file = ""                # empty ⇒ <home>/ov.conf
+# workspace = ""                  # empty ⇒ <home>/workspace
+# ov.conf is TEMPLATED at boot by the entrypoint — the interactive
+# `openviking-server init` wizard is never invoked in-container.
+workers = 1                       # ov.conf server.workers, 2-CPU cap
+queue_concurrency = 2             # accepted, unused: the entrypoint takes ov.conf's queue concurrency from the deploy (group_vars openviking_queue_concurrency)
+# Health gate is /ready, NEVER `doctor`: doctor makes live provider calls and
+# exits 1 when no `vlm` is configured, which is our normal state. /health is
+# unauthenticated and carries the version the drift check reads. The heartbeat
+# reports the CACHED sample, so writing status.json never waits on the network.
+health_interval_s = 30
+# The /health + /ready probe and the local embedder's /health, in ms (clamped
+# 100…20000). /ready runs an embedding and queues behind a case batch's
+# embeddings, so a shorter limit flaps /ready under load. Memory health's
+# "serving" half reads this probe.
+health_timeout_ms = 6000
+# The supervisor never gives up: a memory engine that stays down is worse than
+# a slow retry, and every call site already degrades memory-less.
+restart_backoff_ms = [1000, 2000, 5000, 15000, 30000, 60000]
+restart_reset_after_s = 120       # an uptime this long resets the ladder
+# The embedder. LOCAL is the shipped default: a small
+# ENGLISH embedding model (bge-small-en-v1.5, 384 dims) served on LOOPBACK
+# inside the container by scripts/openviking-embedder.py, over the pinned
+# llama-cpp-python — so nothing but the model call ever leaves the machine,
+# memory text included. ov.conf reaches it through the engine's
+# OpenAI-COMPATIBLE client (provider "openai", api_base http://127.0.0.1:<port>/v1,
+# no key): that client is asynchronous, so a search does not stall the
+# server. Hosted embeddings are an explicit opt-in: embedding_provider =
+# "openai" with model "text-embedding-3-small" / dimension 1536, and the
+# credential in the secrets dir under `embedding_key_file` — a SEPARATE file
+# from pi's `openai_api_key`, so either can be set without the other. ov.conf
+# carries NO `vlm` section either way: extraction, summaries and digest are off
+# (memories are authored, never extracted).
+# Changing the embedder changes the vector space: the boot detects it, moves
+# the old vectors aside and re-embeds reviewer memory (docs/memory-embeddings.md).
+# MIRRORED into group_vars (openviking_embedding_*), whose value the VM boot
+# renders — on the VM route an opt-in is written as inventory host vars beside
+# these keys; tests/openviking.test.ts pins the SHIPPED default to local.
+embedding_provider = "local"
+embedding_model = "bge-small-en-v1.5-f16"
+embedding_dimension = 384
+embedding_key_file = "openai_embeddings_api_key"
+# The local embedder's MODEL FILE — a rule-7 pin like `version`: the image
+# downloads the GGUF from `local_embedder_url` at BUILD time and refuses it
+# unless its sha256 matches; the service re-checks the hash at every start.
+# TRIPLE MIRROR: these == group_vars openviking_local_embedder_* == the
+# memory Dockerfile's model layer (tests/openviking.test.ts,
+# tests/memory-image.test.ts and the scripts/deploy.sh preflight refuse on
+# drift). A changed pin needs `scripts/deploy.sh rebuild`.
+local_embedder_file = "/opt/openviking/models/bge-small-en-v1.5-f16.gguf"
+local_embedder_url = "https://huggingface.co/CompendiumLabs/bge-small-en-v1.5-gguf/resolve/d32f8c040ea3b516330eeb75b72bcc2d3a780ab7/bge-small-en-v1.5-f16.gguf"
+local_embedder_sha256 = "f0b2fef971e8366438bfd2d9aefea1b0115919389448806d290237f638bae999"
+# The service: loopback only, never published (mirrored as
+# openviking_local_embedder_port / _threads). One thread is the latency budget
+# the model was chosen on — ~25 ms for a round's context query.
+local_embedder_port = 1934
+local_embedder_threads = 1
+
+[companion]
+# The local companion container — an ambient pi session on the owner's
+# PC that watches the daemon through the TUI's feed and raises alert files.
+# Every knob below is commented out: the defaults in src/config.ts
+# (COMPANION_DEFAULTS) are the shipped configuration; uncomment to override.
+# enabled = true                  # `qcr tui` starts it unless --no-companion
+# container_name = "qcr-companion"
+# image = "qcr-companion:release" # the release image (docker/Dockerfile) in companion mode, built from the app root: qcr companion rebuild
+# pihome_volume = "companion-pihome"   # its OWN pi auth — never the VM's auth.json
+# session = "companion"           # tmux session inside the container
+# model = "openai-codex/gpt-6.1-sol:medium"
+# repo_dir = ""                   # host review-sandbox repo → /workspace (rw);
+#                                 # empty = this sandbox root
+# tracker_dir = "~/projects/your-tracker"                  # → /tracker (rw)
+# tracker_docs_dir = "~/projects/your-tracker-docs"
+#                                 # → /tracker-docs (READ-ONLY): the tracker
+#                                 # protocol the companion follows. Outside
+#                                 # tracker_dir, so it needs its own mount.
+# reviewed_repo_dir = "~/projects/your-reviewed-repo"
+#                                 # → mounted READ-ONLY into the container: the
+#                                 # reviewed repo's source, so the companion
+#                                 # can read the code a review is about. Never
+#                                 # writable — and a missing checkout just
+#                                 # drops the mount (under-equipped, never a
+#                                 # companion that refuses to start).
+# evidence_dir = "~/.local/share/qcr/evidence"
+#                                 # → /evidence (READ-ONLY): finished-
+#                                 # round evidence (transcript, ledger, prompt,
+#                                 # verdict) the TUI copies down from the VM.
+#                                 # The companion reads plain files and gains
+#                                 # NO ssh and no credential. Kept indefinitely
+#                                 # and unbounded, so the default is a
+#                                 # deliberate home OUTSIDE the repo; empty
+#                                 # means <sandbox root>/evidence (gitignored).
+# feed_dir = ""                   # → /feed;    empty = state/companion/feed
+# alerts_dir = ""                 # → /alerts;  empty = state/companion/alerts
+# ssh_dir = "~/.ssh"              # accepted, unused: ~/.ssh is never mounted
+# overdue_grace_min = 30          # watcher knobs
+# stale_alert_s = 300
+# awaiting_age_h = 24
+# cooldown_min = 20
+
+[sink]
+# Where auto-filed defect flags (#bug reviewer-memory entries) land.
+# "github"    — defects filed as ISSUES on the reviewed repo. The TUI writes a
+#               file-issue command; the DAEMON files it through the one
+#               MutationGate with the [caps] day cap, title dedup and the
+#               [github] issue_label. In dry-run the gate writes an intent
+#               instead of creating anything. Recommended for new installs.
+# "wayfinder" — tickets in a local filesystem wayfinder tracker on the
+#               operator's PC (set root/effort/parent below).
+# "none"      — auto-filing off (also the default when [sink] is absent).
+kind = "none"                      # ← FILL (10): "github", "wayfinder", or "none"
+# root = ""                        # wayfinder: tracker root; empty = [companion] tracker_dir
+# effort = ""                      # wayfinder: effort auto-filed tickets land in (required)
+# parent = ""                      # wayfinder: parent map id stamped into each ticket (required)
+# tickets_effort = ""              # TUI [2]-tab ticket projection's effort; empty = `effort`
+
+[backfill]
+# One-shot pre-daemon history import (`qcr backfill`) — read-only against
+# GitHub, no gate involvement. Every knob defaults off [github] (see
+# backfillDefaults in src/config.ts); uncomment only to re-run against a
+# renamed label or a different identity.
+# bot_login = "your-app[bot]"     # reviews(author:) — with the [bot] suffix
+# bot_actor = "your-app"          # same identity as a timeline actor (no suffix)
+# reviewed_label = "Automatic Review"   # enumeration: the bot-review era marker
+# trigger_label = "AI review requested" # tier-1 trigger candidate
+# in_progress_label = "AI review in progress"   # tier-2 (dispatch moment) fallback
+# review_team_slug = "review"           # team review request = tier-1 trigger
+# concurrency = 2                       # per-PR detail queries in flight
+# max_search_pages = 10                 # 100 hits/page; search caps at 1,000
+
+[guards]
+# Posting-time guards. Enforced on the single MutationGate (packages/pi-plugin/src/guards.ts).
+# The sessions' post scripts (post-review.sh, approve-pr.sh, reply-thread.sh)
+# hold no guard logic: they ask the daemon to post over its IPC socket
+# (src/ipc/postshim.ts, src/postops.ts), so every post meets the same guards.
+# All are on; a knob exists so a guard can be taken out of the
+# path deliberately, in one place.
+downgrade_on_human_approval = true   # human APPROVED at this head ⇒ COMMENT, not REQUEST_CHANGES
+skip_unchanged_head = true           # same head, no author reply since ⇒ post nothing
+recheck_pr_state_before_post = true  # re-read the PR right before posting; merged/closed ⇒ refuse
+# Guard 4: no green CI at this head ⇒ APPROVE is unavailable,
+# regardless of findings. The review still posts, as a COMMENT with approval
+# withheld, and the PR is re-queued when CI goes green at that head.
+# Only the MOST RECENT run of each check name counts — GitHub auto-cancels
+# superseded runs, and their permanent `cancelled` husks would otherwise
+# withhold every approval forever. The latest run
+# of every name must succeed; a genuinely failing/cancelled LATEST run still
+# blocks exactly like a failing test.
+block_approve_on_red_ci = true       # red/pending CI ⇒ approval withheld, review posts as COMMENT
+# A head with ZERO check-runs (conflicted PR, CI not
+# started) carries no execution evidence — withhold there too. Set true for a repo that
+# always runs CI (then `none` means something is wrong, not "no CI setup").
+no_checks_is_red = true              # zero checks at head ⇒ approval withheld until checks pass
+# Guard 5: the head the round actually reviewed must still
+# be the PR's live head at posting time. Sessions export QCR_EXPECTED_HEAD
+# (the round prompt cites the sha) before posting; a mismatch refuses the
+# post — the session ends the round without a verdict and the daemon re-runs
+# against the new head. A missing expectation warns loudly but proceeds
+# (sessions on older prompts — same belt-and-braces as rule 10's legacy input).
+refuse_on_head_drift = true          # live head != the sha the round reviewed ⇒ refuse to post
+
+[recheck]
+# Post-approval delta recheck. Once a PR is approved, these triggers
+# ask the PR's OWN sticky session one question — "does this delta warrant a
+# review, or change the verdict to REQUEST_CHANGES?" — with the standing
+# verdict UPHELD BY DEFAULT. A trivial or empty delta costs one classification
+# and a no-op; the only transition the path can produce is
+# APPROVE -> REQUEST_CHANGES (never a re-approve, never a park). The fourth
+# trigger, an author reply, is owned by ping-pong (src/pingpong.ts) and has no
+# knob here.
+enabled = true
+on_push = true           # a push landing after an approve — the core case
+on_ci = true             # CI completing at the approved head (adverse => evidence)
+on_base_advance = true   # the base branch moved; no PR-owned file changed => no-op
+
+[review]
+# A first-party agent-directive edit (.claude/**, prompts/**,
+# AGENTS.md/CLAUDE.md in the reviewed repo) never auto-blocks on `kind:
+# injection` — the round still decides on the merits (there is no park) and
+# the review carries ONE short escalation comment
+# @-mentioning the most recent human author of the touched directive files. This is the fallback mention when git history yields no
+# attributable human login. It is a comment @-mention through the gated review
+# — never a GitHub reviewer nomination (the never-hand-to-a-human rule).
+escalation_mention_default = ""             # ← FILL (8): fallback GitHub login for escalation @-mentions ("" = no @)
+# The review preset: "default" (the measured best value — every
+# benchmark-driven lever on, the lean plan), "max" (every model at its highest
+# reasoning level + the full lever plan; ~2x cost, ~3x time) or "low" (every
+# model at low reasoning; ~half default's cost and time, about the pre-lever
+# review's recall). REVIEW_PRESETS in
+# packages/pi-plugin/src/reviewconfig.ts. A lever set below overrides the preset.
+preset = "default"
+# The default preset fetches the SOURCE of the npm/PyPI packages a PR imports
+# (package names and versions go to the public registries; nothing is
+# installed or run) so passes can read what a library does. Set false to keep
+# the reviewer off those registries — e.g. when your package names are private.
+# dependency_sources = false
+# Code-quality lenses (maintainability, duplication, abstraction; capped below
+# blocking) run once a PR's non-test code adds 20 lines; the style lens runs
+# only when your repo has a written style guide (a STYLEGUIDE/CODE_STYLE file
+# or a "Code style" section in CONTRIBUTING) and applies only that guide.
+# quality_lenses = false
+# style_lens = false
+# How many nits a review posts: "strict" (default — true-but-trivial nits are
+# dropped, and review volume comes out of nits) or "open" (every true nit
+# posts; style still needs your written guide).
+# nits = "open"
+# Per-lens cost knobs — both off by default, and the defaults are the review
+# as shipped. skip_lenses lists passes never planned nor addable (known pass
+# names only; pass-validate is refused — switch the validator off in the
+# profile instead). validate_consequence_rule
+# adds the validator's consequence rules (intent/contract appeals post as a
+# [question], dead or latent code demotes to nit, a CI-enabled lint rule is a
+# build defect, merges need a shared consequence).
+# skip_lenses = ["pass-abstraction", "pass-duplication"]
+# validate_consequence_rule = true
+# Review latency levers (bench/aacr/PERF.md §6) — each removes
+# serial time; none changes which lenses run. All on by default except
+# validator sharding:
+#   wide_lens_fanout — a batched lens launch runs as wide as
+#     [engine] lens_max_concurrency (deprecated: the lens tool sets its own
+#     width);
+#   task_files — the daemon writes each lens's complete task to a file, and
+#     the engine starts the planned discovery wave from those files at
+#     round start and the session's `lens_wave` tool joins it
+#     (packages/pi-plugin/src/engine/lens/tool.ts; off ⇒ hand-written per-row `lens` calls);
+#   render_outputs — the review body and inline comments are rendered from
+#     the findings record instead of being written out a second time;
+#   validator_shards — EXPERIMENTAL, off (1), unvalidated: split the
+#     candidates over this many pass-validate children. Measured once on a
+#     19-lens PR (PERF.md §7): the validator got SLOWER (101 -> 225 s) and the
+#     merged record dropped every doubted and downgraded mark, so it never
+#     earned the default; kept as a knob, not a recommended setting.
+# wide_lens_fanout = false   # deprecated: a no-op when [engine] runtime = "sdk" (the default)
+# task_files = false
+# render_outputs = false
+# validator_shards = 2
+# Duplicate merge (docs/duplicate-merge.md): one comment per root
+# cause. Lens candidates are grouped deterministically before the validator
+# (same file within 10 lines, a shared named identifier, or the same fix
+# target), the validator merges or splits each group, and a post-check at
+# render time merges two posted findings that are one root cause posted twice.
+# dedup_merge = false
+# Per-file coverage check: 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 it ran.
+# coverage_check = false
+# Follow-up rounds (docs/follow-up-rounds.md): every round after the
+# first verifies the prior findings and reviews only the PR-owned change since
+# the last reviewed head (base merges and rebases taken out), with one
+# whole-PR pre-approval sweep before an approval when no full look has run
+# since round 1 (or, once approved, when a push is large). Any doubt (no reviewed head, a rewound base, a git failure, a
+# delta above follow_up_max_delta_ratio of the PR's diff lines) runs a
+# full re-review instead. "full" re-reviews the whole PR every round.
+# follow_up = "full"
+# follow_up_max_delta_ratio = 0.6
+# follow_up_sweep = false
+# After a posted approval the sweep is owed only when the change since it
+# reaches this many lines (additions + deletions); 0 never owes it.
+# follow_up_post_approval_sweep_lines = 500
+# A delta of at most this many lines gets the LEAN plan: no per-file sweep
+# rows, and the quality and style lenses offered as addable instead of
+# planned; 0 never. Read only under follow_up_extent = "rules"; the shipped
+# "session" mode always plans the lean core and leaves this threshold to
+# the session.
+# follow_up_small_delta_lines = 150
+# Split pass-baseline on a very large change: over this many changed
+# lines (prose half; lockfiles, generated and vendored files not counted) the
+# baseline is planned as 2-3 rows, each starting from one group of the
+# change's files with the whole PR still its charter, so the round's longest
+# reading runs in parallel. 2000 splits only the largest PRs; 0 never splits.
+# baseline_split_lines = 2000
+# The round's CONTEXT PACK (docs/prompt-caching.md): "pack-first"
+# writes the diff, the change since the last review and the most-changed
+# files' full text beside the task files, and every lens child carries it at
+# the start of its prompt, after one cached warm-up per cache group — so the
+# lenses read it from cache instead of re-reading it uncached (each lens's
+# instructions move into a developer message after the pack). On by default
+# (measured 40% cheaper on 10 cases, verdicts and recall held); "off" sends
+# no pack. Needs [engine] lens_cache_group > 0.
+# context_pack = "off"
+# context_pack_max_tokens = 40000
+# Loosened-test hint: weakened assertions in the PR's test files
+# (exact → bound or contains, a tolerance widened, a count lowered, a timeout
+# lengthened, an assert removed or commented out, a skip added) are found by
+# code and named in pass-tests' plan reason; their presence also plans it.
+# loosened_test_hint = false
+# Repo profile — names a directory under profiles/ whose house-rule
+# addenda pack (profiles/<name>/addenda/*.md) composes onto the built pass
+# bodies after the built-in generic registry, and whose optional
+# heuristics.toml extends lens selection with your repo's file shapes
+# (framework settings globs, command dirs, flag-library names — ADD-only, the
+# generic selection core always stays). "" = no profile (generic addenda and
+# generic selection only). Ship-with options: "default" (the shipped
+# behaviour — the base your own profile extends with `extends = "default"`),
+# "minimal" (empty pack), "example-django" (a worked illustrative Django pack,
+# heuristics included).
+# See docs/profiles.md for authoring your own.
+profile = ""
+
+# EXTENSIONS to the first-party directive-path vocabulary the
+# directive-edit escalation flow keys on (packages/pi-plugin/src/severity.ts). Extend-only by design:
+# these ADD names, the built-ins (.claude/**, .cursor/**, root prompts/**,
+# AGENTS.md/AGENT.md/CLAUDE.md/.cursorrules anywhere,
+# .github/copilot-instructions.md) can never be removed — dropping one would
+# silently re-enable auto-blocking on first-party directive edits. Leave
+# empty unless your repo keeps agent directives under other names.
+[review.directives]
+extra_basenames = []           # e.g. ["COPILOT.md"]
+extra_dir_segments = []        # e.g. [".aider"] — whole subtree, any depth
+extra_root_dirs = []           # ROOT-only directive dirs, like prompts/
+extra_files = []               # exact repo-relative paths
+extra_vendored_segments = []   # extra third-party markers (case-insensitive)
+
+# ---------------------------------------------------------------------------
+# [escalation] — OPTIONAL, OFF BY DEFAULT.
+#
+# Two things this does NOT do, and cannot be configured to do:
+#
+#   * It never hands the review back. The reviewer always decides on the
+#     merits and posts the verdict; an escalation is a note that goes out
+#     BESIDE it. Nothing here can withhold, defer or replace a verdict.
+#   * It never asks anyone to "review this PR". Every escalation names ONE
+#     thing — a file and line range, a migration, a named decision — and why
+#     that person. Think of it as a `[check this]` item with a name on it.
+#
+# Leave `enabled = false` and nothing below is read: no rule is evaluated, no
+# extra API call is made, and the round prompts carry no escalation text
+# whatever — the system BEHAVES exactly as a build without the feature.
+# (The placeholder that renders empty leaves a blank line in the prompt, like
+# the sibling notes beside it.)
+# `qcr onboard`'s escalation step writes this section.
+#
+# The configuration cannot be half-done: `enabled = true` with no `targets`,
+# or a rule pointing at a login that is not a target, or a rule that declares
+# no condition, all REFUSE TO LOAD. That is deliberate — escalation switched
+# on with nobody to escalate to is not a configuration.
+[escalation]
+enabled = false
+# "comment" (the default) posts a gated COMMENT review @-mentioning the person
+# with the narrow ask. "review_request" ALSO puts the PR in their
+# review-requested queue — GitHub words that entry "review this pull request",
+# which is exactly the framing this feature rules out, so the comment is still
+# posted and still carries the real ask. "comment" is the shape that matches
+# the intent; pick "review_request" only if your team lives in that queue.
+shape = "comment"
+# The CLOSED set of logins any escalation may reach. A session that names
+# anyone else is silently dropped by the daemon — it is not negotiable.
+targets = []
+# May the PR's session ALSO escalate on its own judgement, bounded to the
+# targets above? Off by default: the rules below stand on their own, and they
+# are the half with no model in the loop.
+session_judgement = false
+# Hard cap per PR, across every round.
+max_per_pr = 2
+
+# Deterministic triggers. Each rule is a pure predicate over facts the daemon
+# already has — no LLM judgement anywhere. A rule fires when EVERY condition it
+# declares holds; a rule that declares none refuses to load.
+#
+# Conditions: paths (glob: * within a segment, ** across), labels (PR labels),
+# min_severity (the round posted a finding at or above P0/P1/P2/P3), and
+# failing_checks (the LATEST run of a named check is not green).
+#
+# [[escalation.rules]]
+# name = "migrations"
+# to = "example-teammate"          # must appear in `targets` above
+# why = "you own this repo's migration policy"
+# paths = ["**/migrations/*.py"]
+# [[escalation.rules]]
+# name = "blockers-on-payments"
+# to = "example-teammate"
+# why = "payments changes go past you before they merge"
+# paths = ["billing/**"]
+# min_severity = "P1"
+
+# Bounds on a SESSION-issued `drain` / `pause-pr`. A pi session
+# (the overseer, or a PR's session on the owner's behalf in Slack) may hold
+# either lever only for a bounded time, drawn from a per-day minute budget —
+# so a session can stop review work for a reason, never indefinitely. The
+# OPERATOR's own levers (`qcr drain on`, the deploy tab's D) are NOT bounded
+# here: the deploy-window drain stands until the new boot's first healthy
+# reconcile lifts it. Which of the two a command is comes
+# from the channel it arrived on (the operator's is the root-owned
+# `commands/operator/` directory a session cannot write into), never from a
+# field in the file. All values are minutes; budgets count per [ops] timezone day.
+[levers]
+session_drain_max_min = 30                 # longest single session drain
+session_drain_budget_min_per_day = 90      # total session-drain minutes per day (>= the cap)
+session_pause_max_min = 240                # longest single session pause of one PR
+session_pause_budget_min_per_day = 480     # total session-pause minutes per PR per day (>= the cap)
+
+# Archiving (docs/archiving.md): closed-PR history leaves every live
+# path for a compressed archive under <root>/archive/ — nothing of analysis
+# value is deleted, only proven duplicates. The archiver runs on its own timer,
+# never before the first healthy reconcile + start_delay_min, and holds while
+# draining, while the event loop is stalled or the CPU starved, and while
+# either mount's free space is low or unknown. "plan" (the shipped value)
+# computes what it WOULD move — status.json `archive`, `qcr status`,
+# `qcr archive status --plan` — and writes nothing. "on" MOVES, every tick:
+# first it restores reopened PRs' transcripts and payloads to their live paths;
+# then it moves the old reader-less event rows and webhook deliveries into
+# monthly SQLite files under archive/db/ (sealing finished months to .gz);
+# then each eligible closed PR's files — every pi transcript, round prompt,
+# session-command payload, finding, receipt, round file, inject leftover and
+# processed verdict — into archive/pr-<n>/, REMOVING each from the live tree
+# once its compressed copy is verified; then the overseer's non-current
+# transcripts and pi's day-old global session files the same way. Nothing is
+# deleted that is not verified in the archive or a proven duplicate. Read one
+# `qcr archive status --plan` before flipping it. All optional — these are the
+# defaults.
+[archive]
+mode = "plan"            # off | plan | on — an unknown value refuses to load
+after_days = 14          # closed PRs' files and webhook deliveries (clamped 7..3650)
+events_after_days = 35   # the reader-less event kinds (clamped 31..3650; keeps qcr metrics d30 exact)
+interval_s = 60          # the archiver's own timer (clamped 10..3600)
+start_delay_min = 10     # after the first healthy reconcile (clamped 0..1440)
+tick_budget_s = 20       # no new file is started after this (clamped 1..300)
+max_prs_per_tick = 5     # (clamped 1..100)
+max_mb_per_s = 8         # input rate cap for compress + verify (clamped 1..200)
+disk_headroom_gb = 2     # free space kept on both mounts (clamped 0.5..1024)
+db_batch_rows = 500      # the DB mover's starting batch; adapts 100..2000 to stay <= 25 ms
+gzip_level = 6           # (clamped 1..9)
+live_retention_days = 30 # a worker round's logs (state/live, state/lens) leave the live tree this long after
+                         # their last write, once the PR's archive holds a verified copy (clamped 7..3650)
+live_cap_gb = 20         # disk cap on state/live + state/lens; past it the archive_live_cap wake fires (0 = off, max 4096)
+
+# The bot login's single refresher (src/loginrefresh/): the VM-only
+# exception to "only the owner's pi /login refreshes" (packages/pi-plugin/src/engine/auth.ts).
+# After the cutover ONE process the daemon spawns and supervises owns
+# pihome/agent/auth.json and every worker borrows a refresh-blanked copy.
+# Off until the cutover's config turns it on: while tmux pi sessions exist they
+# refresh the file themselves, and a second refresher would rotate the refresh
+# token under them. margin_min must exceed [daemon] round_deadline_min.
+[login_refresh]
+enabled = false
+margin_min = 90          # refresh once the token has less than pi's 5 min + this left
+
+# The companion's whole-repo scan — read only inside the companion,
+# never on the VM. Stage 1 runs `pass-scan` over every unit of the saved unit
+# cut (tests, migrations, lockfiles and prose never). The FIRST scan at these
+# settings is a calibration run over a few units; every later cost preview is
+# priced from the coverage ledger's actual costs, and a run stops hard at the
+# estimate the operator approved. A repo profile's `[scan]` table overrides
+# effort / tier / validator / exclude / depth / deep_lenses (the profile
+# wins); the rest is the install's. All optional — these are the defaults.
+[scan]
+effort = "low"                 # stage 1's reasoning level: low | medium | high (= [models] effort_max)
+tier = "sol-med"               # whose model pass-scan runs on ([models.tiers])
+validator = true               # the skeptic: judges each finding at its lens's tier — confirmed / likely / doubtful, never dropped (its cost is in the price)
+exclude = []                   # repo-relative globs never scanned, e.g. ["generated/", "*.pb.go"]
+calibration_units = 3          # units the first-scan calibration run reads
+calibration_max_usd = 3.0      # the calibration run's hard stop
+concurrency = 8                # scan cases in flight at once (stage 1 and stage 2)
+case_max_files = 30            # one case reads at most this much; a bigger unit splits, name kept
+case_max_lines = 3000          # (stage-2 rows too: split a bigger row)
+unmeasured_rate_factor = 4     # stage 2: a deep lens never priced here costs stage 1's rate × this
+depth = "standard"             # "deep": stage 1 names a deep lens for every file, every lens digs past its row's
+                               # files, a stage-2 proposal adds the floor below, and only a deep reading covers a file
+deep_lenses = ["pass-consistency", "pass-delivery", "pass-duplication", "pass-maintainability"]
+                               # the deep floor: each of these over every file stage 1 reads (one switched off by the profile is skipped);
+                               # the order is the priority: under a budget the first lens covers the whole tree before the next starts
+# Where `qcr scan start` drives a run (not a profile key). "docker": in a throwaway
+# container from the companion image, mounting only the reviewed repo (read-only),
+# the state home, the companion's pi login (read-only) and this config (read-only)
+# — `qcr scan doctor` checks it all, and an image older than the checkout is
+# refused until `qcr scan rebuild` (which builds it and touches no container).
+# Unset, it is "host" inside the companion container.
+# "host": a detached process on this machine, running the `pi` on the PATH (its own login).
+#
+# One login: the companion's. Log its pi in once (`qcr scan login` runs pi's OAuth
+# login straight away, in the running companion or over its pi home volume); the
+# companion alone refreshes it.
+# A scan reads that login read-only and runs every case on a fresh private copy with
+# the refresh token neutralised, so it never refreshes and never writes anything the
+# companion reads. The price: a scan case cannot outlive the access token — a start
+# or a case it would not outlive is refused; open the companion so it refreshes.
+sandbox = "docker"
+# pihome_volume = "companion-pihome"  # whose login the scan reads; default [companion] pihome_volume
+# image = "qcr-scan"           # the sandbox's image (docker/companion/Dockerfile): qcr scan rebuild
+
+[slack]
+# The Slack concierge — ONE channel, one thread per PR. Tokens are
+# NEVER here: bot_token_file / app_token_file name flat files under
+# [github].secrets_dir (~/.config/qcr/<install>/secrets, /opt/quickreview/secrets in the
+# container). Turning `enabled` on is a deliberate deploy-time act: with it on,
+# a missing token file is a hard startup error, never a silent read-only mode.
+enabled = false
+channel = ""                      # ← FILL (9, if enabling Slack): the ONE channel id (C…)
+channel_kind = "public"           # "public" | "private" (private needs an invite)
+bot_token_file = "slack_bot_token"   # xoxb-…
+app_token_file = "slack_app_token"   # xapp-…, connections:write, socket mode only
+legacy_owner_slack_id = ""             # LEGACY alias of [owner] slack_id — set the [owner] key instead
+post_min_interval_ms = 1100       # Slack chat.postMessage is ~1 msg/s per channel
+reconnect_backoff_ms = [1000, 2000, 5000, 15000, 30000]
+server_ping_timeout_ms = 30000    # no server ping within this ⇒ reconnect
+catchup_max_age_s = 300           # accepted, unused: Slack inbound turns are retired
+max_reply_chars = 3000
+name_cache_ttl_s = 86400
+
+[slack.users]
+# Slack member id -> GitHub login. The ONLY source of own-PR rights: a message
+# from an id that is not listed here can never claim to be a PR's author.
+# U0OPERATOR = "operator-github-login"
+
+[slack.policy]
+# Every cap below is enforced in DAEMON CODE (src/slack/policy.ts), never by
+# prompt — a session can ask to speak, the daemon decides.
+daily_turns = 80                  # channel-wide model turns per policy day
+per_user_daily_turns = 20         # per person, same window
+thread_replies_per_day = 6        # daemon posts into any one thread
+soft_exchange_limit = 3           # accepted, unused (no reader enforces it)
+announcements_per_hour = 20       # rolling hour; announcements bypass turn caps
+default_cooldown_min = 60         # for a non-built-in cause with no cooldown_min of its own
+# The day boundary for every cap (DST-correct). Defaults from [ops] timezone;
+# uncomment to run the Slack caps on another clock.
+#timezone = "Europe/Warsaw"
+pickup_grace_min = 20
+downtime_notice_min = 5
+heartbeat_interval_min = 5
+storm_corrections = 5             # accepted, unused: no code raises reconcile.storm
+awaiting_author_stale_h = 48      # accepted, unused: no code raises pr.awaiting_author_stale
+broadcast_verdicts = "never"      # accepted, unused: verdicts always stay in-thread
+
+[slack.policy.causes]
+# Per-cause switch + cooldown. Keys are per-PR at runtime ("round.overdue:5263")
+# so one stuck PR can never silence another.
+"round.overdue"            = { enabled = true,  cooldown_min = 60 }
+"round.malformed_verdict"  = { enabled = true,  cooldown_min = 60 }
+"review.failed_loud"        = { enabled = true,  cooldown_min = 60 }
+"pr.not_picked_up"         = { enabled = true,  cooldown_min = 120 }
+"daemon.up"                = { enabled = true,  cooldown_min = 0 }
+"daemon.stopping"          = { enabled = true,  cooldown_min = 0 }
+"slack.cap_reached"        = { enabled = true,  cooldown_min = 0 }
+"reconcile.storm"          = { enabled = false, cooldown_min = 180 }
+"digest.eod"               = { enabled = false, cooldown_min = 0 }
+"pr.awaiting_author_stale" = { enabled = false, cooldown_min = 1440 }