From 853d60d2c63329b927c13a615bd34306d42842b2 Mon Sep 17 00:00:00 2001
From: 7jrxt42BxFZo4iAnN4CX
 <72938937+7jrxt42BxFZo4iAnN4CX@users.noreply.github.com>
Date: Mon, 7 Sep 2026 15:57:11 +0300
Subject: [PATCH] docs(config): document R1 turn budgets and the goal loop
 example

---
 config.example.toml   | 15 +++++++++++++++
 docs/CONFIGURATION.md |  2 ++
 2 files changed, 17 insertions(+)

diff --git a/config.example.toml b/config.example.toml
index 2647e233e2..663d1953c3 100644
--- a/config.example.toml
+++ b/config.example.toml
@@ -1195,6 +1195,21 @@ initial_delay = 1.0
 max_delay = 60.0
 exponential_base = 2.0
 
+# ─────────────────────────────────────────────────────────────────────────────────
+# Goal loop (`[goal]`) — operate-mode persistent goals
+# ─────────────────────────────────────────────────────────────────────────────────
+# Operate-mode goals run to their completion gate with no default token, time,
+# or continuation ceiling. Token/time budgets, when supplied, are telemetry
+# only and do not stop a goal. The keys below are the opt-in circuit breakers.
+# [goal]
+# Optional safety backstop on automatic goal continuation passes.
+# Default: 0 (unlimited). Set a positive value to opt into a ceiling.
+# max_continuations = 100
+# Optional cancellable quiet period between successful turns, useful for
+# coordinator goals that poll on a cadence instead of keeping one provider
+# turn open. Default: 0 (continue immediately). Cap: 86400 (24h).
+# continuation_delay_seconds = 300
+
 # ─────────────────────────────────────────────────────────────────────────────────
 # Context Compaction
 # ─────────────────────────────────────────────────────────────────────────────────
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 4b78742e61..1aad8cb4a4 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -2256,6 +2256,8 @@ reasoning contract, and all four membership ids omit generic sampling fields.
 - `tui.stream_chunk_timeout_secs` (int, optional, default `900`): per-SSE-chunk idle timeout for streamed model responses. Slow local or compatible servers can raise this with `/config stream_chunk_timeout_secs <seconds>`; `0` maps to the default and explicit values must be `1..=3600`. The legacy `DEEPSEEK_STREAM_IDLE_TIMEOUT_SECS` env var is still honored when this key is omitted.
 - `tui.header_items` (array of strings, optional, default `[]`): opt-in header chips. Set `header_items = ["tokens"]` under `[tui]` to show the session input, cache-hit, and output token counts. Narrow terminals elide the optional chip; wide terminals show it alongside context utilization.
 - `tui.osc8_links` (bool, optional, default on for macOS/Linux, off for Windows): emit OSC 8 escape sequences around URLs in transcript output so supporting terminals (iTerm2, Terminal.app 13+, Ghostty, Kitty, WezTerm, Alacritty, recent gnome-terminal/konsole) can open them with the terminal's link gesture—usually Cmd-click on macOS and Ctrl-click on Linux/Windows. Terminals without OSC 8 support render the plain label and ignore the escape. The escapes are emitted out-of-band (not inside buffer cells), so column corruption is not a concern; set `false` only for terminals that misrender the OSC 8 terminator itself. Windows legacy consoles default off; opt in with `true`.
+- `tui.max_model_steps` (int, optional, default `200`): finite ceiling on model steps one turn may take. A "step" is one accepted provider response, so this bounds how many billable requests a single user message can trigger. Values are clamped to `1..=100000`; `0` (or absent) resolves to the default — there is no `0`-means-unlimited sentinel. At ~80% of the budget the model gets one soft-landing notice to stop exploring and write its final report; at exhaustion the turn ends `Failed` with `Maximum model steps reached before completion (limit: N)` (after one bounded final-report turn when the model still owes work). This is the interactive runaway guard and applies to every turn, including a single goal pass; raise this knob to enlarge one pass — a goal pass that needs more than 200 model steps in one turn (before a terminal `update_goal`) would otherwise fail the turn. Multi-turn goal runs already continue automatically (see the Goal loop section below).
+- `tui.turn_wall_clock_secs` (int, optional, default `3600`): cumulative per-turn wall-clock budget in seconds, measured across every model step of one turn (not per request). Time blocked on a human approval is excluded. Clamped to `30..=86400` (24 hours is the documented ceiling); `0` resolves to the default. When exhausted the turn stops before authorizing another billable request with a message naming the limit and the key to raise.
 - `transcript.prose_measure` (positive integer, optional, default absent = full width): wrap cap, in columns, for prose cells — user messages, assistant answers, and reasoning/thinking blocks — in the live transcript (#5436). Absent (or `0`) spends the full content width, consistent with tool/status cells and the #5322 wide-frame decision; the former 105-column prose rail is gone. Set a positive whole number (e.g. `prose_measure = 120` under `[transcript]`) to restore a bounded reading measure on ultrawide terminals. Narrow terminals always keep their content width — the cap clamps from above only. Tool, diff, and status cells never inherit this cap. Invalid values (negative or non-integer) are rejected at startup with a `transcript.prose_measure` config error. Resolved once per render pass, so the main transcript cache and the full-screen overlay always agree on the effective width.
 - `hooks` (optional): lifecycle hooks configuration (see `config.example.toml`).
 - `features.*` (optional): feature flag overrides (see below).