pi-pignon 0.1.1 → 0.1.2

package/docs/CONFIGURATION.md

@@ -0,0 +1,234 @@
+# Configuration
+
+pignon reads `~/.pi/agent/pignon.json` (or the path in `PIGNON_CONFIG`).
+Every key is optional: with no file, it uses the built-in defaults shown below.
+Add the `$schema` line for autocompletion and inline validation in your editor.
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/siiick/pi-pignon/main/schema/config.schema.json",
+  "version": 2
+}
+```
+
+Run `/pignon config` to see the resolved table currently in use.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PIGNON_CONFIG` | `<Pi config dir>/pignon.json` | Path of the optional config file |
+| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | Pi's config directory; pignon keeps its config and exports there |
+| `TYPESAFE_API_KEY` | *(unset)* | Jev API key (another variable can be named with `apiKeyEnv`) |
+| `TYPESAFE_BASE_URL` | `https://api.typesafe.ai` | Jev API root, when `baseURL` is not set |
+| `TYPESAFE_DEFAULT_MODEL` | `jev-latest` | Jev model, when `model` is not set |
+| `LAYA_ROUTER_CONFIG` | `~/.pi/agent/laya-router.json` | **Legacy:** read only when there is no pignon config |
+
+laya-serve reads its own `LAYA_*` variables (`LAYA_HOST`, `LAYA_PORT`, `LAYA_MODELS`, `LAYA_API_KEY`, …) when it starts; see [Laya's documentation](https://pypi.org/project/laya/). The variables of the experimental worker are listed in its [section below](#experimental-pignons-mlx-worker).
+
+## Deciders
+
+`deciders` picks the decision model. `/pignon init` writes it for you. Without it, pignon uses the experimental worker when installed, else Jev when `TYPESAFE_API_KEY` is set; it does not look for laya-serve on its own.
+
+```json
+{
+  "deciders": [
+    { "type": "laya-serve" }
+  ]
+}
+```
+
+| Type | Key | Default | Meaning |
+|------|-----|---------|---------|
+| `laya-serve` | `url` | `http://127.0.0.1:8000` | Where laya-serve listens. On another machine, prompts leave yours and cards show ☁ |
+| | `model` | *(server's choice)* | Laya checkpoint: `english`, `multilingual` or `typed-decisions`. By default the server picks one from the prompt's language |
+| | `apiKeyEnv` | *(none)* | Environment variable holding the server's key, when you started it with `LAYA_API_KEY`. Your TypeSafe key is never sent to laya-serve |
+| | `timeoutMs` | `1500` | Timeout for one decision |
+| `laya-local` | | | [Experimental worker](#experimental-pignons-mlx-worker), see its section |
+| `jev` | `model` | `jev-latest` | Jev version to pin. Confidences are calibrated per version, so pinning keeps your thresholds valid |
+| | `apiKeyEnv` | `TYPESAFE_API_KEY` | Environment variable holding the key. Keys are never read from the config file |
+| | `baseURL` | TypeSafe | `https://openrouter.ai/api` to go through OpenRouter (with `"apiKeyEnv": "OPENROUTER_API_KEY"`) |
+| | `timeoutMs` | `1500` | Timeout for one decision |
+| | `maxRetries` | `0` | Retries after a failed call; each gets the full timeout |
+
+### Using several deciders
+
+List more than one and `strategy` says how they work together:
+
+```json
+{
+  "deciders": [{ "type": "laya-serve" }, { "type": "jev" }],
+  "strategy": { "mode": "sequential", "escalateBelow": 0.75 }
+}
+```
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `mode` | `sequential` | `sequential`: ask the deciders in order; the next one is asked only when the previous one is not ready, fails (e.g. laya-serve not running), or is less confident than `escalateBelow`. Remote deciders are only called when needed. `parallel`: ask all of them at once |
+| `escalateBelow` | `0.75` | Sequential: tier confidence under which the next decider is asked. The most confident answer wins |
+| `pick` | `most-confident` | Parallel: route on the most confident answer, or `first`: on the first decider in the list that answered, the others being only recorded |
+| `budgetMs` | `3000` | Wall-time limit for one decision, all deciders included |
+
+**Benchmark Laya against Jev** without changing how you route: keep Laya in charge and record Jev's answers next to it, then compare.
+
+```json
+{
+  "deciders": [{ "type": "laya-serve" }, { "type": "jev" }],
+  "strategy": { "mode": "parallel", "pick": "first" }
+}
+```
+
+`/pignon-stats compare` shows tier and exploration agreement, a confusion matrix, mean confidence, latency, failures and cost per decider.
+`/pignon-stats export` writes every decision (with each decider's answer) as JSON lines for your own analysis. In parallel mode, every routed prompt is sent to Jev.
+
+Laya's confidence is low (0.05–0.27 on typical prompts: the checkpoint's temperatures are uncalibrated), so with the default `escalateBelow` of 0.75, sequential mode asks Jev on almost every prompt. Lower `escalateBelow`, or set `"confidenceSource": "top-probability"` (see [Other settings](#other-settings)).
+
+### Start laya-serve at login (macOS)
+
+A launchd agent keeps laya-serve running in the background and restarts it if it stops. Save this as `~/Library/LaunchAgents/local.laya-serve.plist`, replacing `/Users/you/.local/bin/laya-serve` with the output of `which laya-serve`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>local.laya-serve</string>
+  <key>ProgramArguments</key>
+  <array><string>/Users/you/.local/bin/laya-serve</string></array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>LAYA_HOST</key><string>127.0.0.1</string>
+    <key>LAYA_MODELS</key><string>english,multilingual</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardErrorPath</key><string>/tmp/laya-serve.log</string>
+</dict>
+</plist>
+```
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.laya-serve.plist   # start now and at login
+launchctl bootout gui/$(id -u)/local.laya-serve                                  # stop and disable
+```
+
+## Experimental: pignon's MLX worker
+
+pignon also has its own Laya worker (`worker/` in this repository), built on [laya-mlx](https://github.com/mizorewww/laya-mlx). It is a little faster than laya-serve on Apple Silicon (~61 ms against ~75 ms per decision, with the same answers), smaller to install, and needs no server: pignon starts it with the session and stops it afterwards. It is **experimental and not published**, and its interface may change; prefer laya-serve.
+
+It needs an Apple Silicon Mac and a clone of this repository:
+
+```bash
+git clone https://github.com/siiick/pi-pignon
+uv tool install ./pi-pignon/worker            # puts pignon-laya on PATH
+```
+
+then `"deciders": [{ "type": "laya-local" }]`. pignon starts the worker with the first of:
+
+1. `command` in the `laya-local` decider, e.g. `["uv", "run", "--project", "/path/to/pi-pignon/worker", "pignon-laya"]`;
+2. `LAYA_PYTHON`, running `laya_worker.py` from `LAYA_WORKER_DIR`;
+3. a source checkout's `worker/.venv` (after `uv sync`), when pignon itself runs from that checkout;
+4. `pignon-laya` on `PATH`.
+
+`/pignon doctor` says which one is used. The worker reports its protocol version when it starts; pignon refuses a worker it cannot talk to and says which side to update. Its settings:
+
+| Key or variable | Default | Meaning |
+|-----------------|---------|---------|
+| `timeoutMs` (decider) | `thresholds.layaTimeoutMs` | Timeout for one decision |
+| `command` (decider) | *(found automatically)* | Command that starts the worker |
+| `LAYA_MODEL` | `aac6fef/laya-mlx` | Checkpoint (e.g. `aac6fef/laya-multilingual-mlx`); fixed for the life of the worker |
+| `LAYA_MODEL_REVISION` | pinned commit for the default model, latest for others | Hugging Face revision to load; empty string means latest |
+| `LAYA_PYTHON` | *(unset)* | Run `laya_worker.py` with this interpreter |
+| `LAYA_WORKER_DIR` | `<extension>/worker` | Directory containing `laya_worker.py` |
+| `LAYA_WORKER_SCRIPT` | `<worker dir>/laya_worker.py` | Explicit worker script path |
+| `LAYA_DTYPE` | `float16` | Model dtype (`float16` / `float32`) |
+| `LAYA_DEVICE` | *(auto)* | Device (`gpu` / `cpu` / empty) |
+| `LAYA_BATCH_SIZE` | `16` | Questions per forward pass |
+
+## Swap a model
+
+Tiers refer to models by name. The built-in names are `fast`, `balanced`, `reasoner` and `agent`; redefine one to change every tier that uses it:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/siiick/pi-pignon/main/schema/config.schema.json",
+  "version": 2,
+  "models": {
+    "reasoner": { "provider": "anthropic", "modelId": "claude-opus-5-5", "thinking": "high" }
+  }
+}
+```
+
+`thinking` is one of `off`, `low`, `medium`, `high`, `xhigh`; Pi clamps it to what the model supports. Check model ids with `pi --list-models`.
+
+## Presets
+
+A preset fills the four built-in model names from one provider. Use it with `extends`, and override any name under `models`:
+
+```json
+{
+  "extends": "anthropic",
+  "models": { "fast": { "provider": "anthropic", "modelId": "claude-haiku-4-5-20251001", "thinking": "off" } }
+}
+```
+
+| Preset | `fast` | `balanced` | `reasoner` | `agent` |
+|--------|--------|------------|------------|---------|
+| `openrouter` (default) | deepseek-v4-flash-0731 · off | deepseek-v4.1-flash · low | glm-5.3 · high | hy4-preview · low |
+| `anthropic` | claude-haiku-4-5 · off | claude-sonnet-5 · low | claude-opus-5-5 · high | claude-sonnet-5 · medium |
+| `openai` | gpt-6-luna · off | gpt-5.6-terra · low | gpt-6-sol · high | gpt-5.3-codex · medium |
+
+Presets are starting points, not recommendations: check prices and quality on your own work (`/pignon-stats`, shadow mode).
+
+## Write your own tiers
+
+`tiers` replaces the built-in list as a whole: 2 to 8 tiers, **easiest first** (position is rank, so moving down the list is a downgrade). Each tier has:
+
+| Key | Meaning |
+|-----|---------|
+| `id` | Tier name shown on decision cards (lowercase, digits, `-`, `_`) |
+| `criterion` | How to recognize a task of this tier. **This is the text the decision model reads**, so write it as a description of the task |
+| `model` | Model for every task of the tier… |
+| `direct` / `exploration` | …or one model for each form |
+| `explorationAllowed` | `false` sends tasks that need exploration to the next tier up (default `true`) |
+
+A model is a name from `models` or an inline `{ provider, modelId, thinking }`. See [`examples/pignon.json`](../examples/pignon.json) for a four-tier table.
+
+When you change the wording of criteria or questions, also change `questions.version`: it is stored with each decision, so you can tell which wording your thresholds were calibrated on.
+
+### Built-in table
+
+| Tier | Direct | Exploration |
+|------|--------|-------------|
+| trivial | `fast`: `openrouter/deepseek/deepseek-v4-flash-0731` · off | → standard (`explorationAllowed: false`) |
+| standard | `balanced`: `openrouter/deepseek/deepseek-v4.1-flash` · low | same |
+| hard | `reasoner`: `openrouter/z-ai/glm-5.3` · high | `agent`: `openrouter/tencent/hy4-preview` · low |
+
+## Other settings
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `questions.version` | `q1` | Label stored with each decision |
+| `questions.tierInstructions` | *How much reasoning does solving this request demand…* | The tier question |
+| `questions.explorationInstructions` | *Does answering require exploring the codebase…* | The exploration question |
+| `questions.explorationCriteria` | `{ yes, no }` | What `yes` and `no` mean |
+| `confidenceSource` | `reported` | `top-probability` routes on the chosen answer's probability instead of the model's confidence, for checkpoints whose confidence is uncalibrated |
+
+| Threshold | Default | Meaning |
+|-----------|---------|---------|
+| `minConfidenceDowngrade` | `0.85` | Tier confidence needed to downgrade, or to move in from a model outside the table |
+| `minConfidenceUpgrade` | `0.5` | Tier confidence needed to upgrade |
+| `minConfidenceForm` | `0.6` | Confidence needed to call a task `direct` rather than `exploration` |
+| `minPromptsBetweenSwitches` | `2` | Prompts to wait after a switch before the next downgrade or lateral switch |
+| `maxPaybackRequests` | `3` | A downgrade must recoup its cache-miss cost within this many LLM requests |
+| `assumedOutputTokensPerRequest` | `1000` | Output per request assumed when estimating what a downgrade saves |
+| `cacheGuardTokens` | `60000` | Context size above which lateral switches (and downgrades, when prices are unknown) are refused |
+| `layaTimeoutMs` | `2500` | Timeout for one decision of the experimental worker |
+
+## Coming from laya-router
+
+A `~/.pi/agent/laya-router.json` is still read when there is no `pignon.json`,
+including its old `tiers: { hard: { direct: … } }` format. pignon warns at
+session start; run `/pignon config migrate` to write the equivalent
+`pignon.json` (a `pignon.json` in the old format is backed up to
+`pignon.json.bak` first), then `/reload`.

package/docs/DESIGN.md

@@ -0,0 +1,49 @@
+# Design notes
+
+## Privacy
+
+With `laya-serve` on this machine (`127.0.0.1` or `localhost`) or `laya-local`, prompts never leave it. With `jev`, or a laya-serve on another host, the first 4 000 characters of each routed prompt are sent over the network, and decision cards are marked ☁. The SDK's own logging is capped at `warn` and kept in `/pignon log`, so prompts are never logged, even with `TYPESAFE_LOG_LEVEL=debug`.
+
+## Fail-open
+
+If a decider cannot be reached or a decision fails, the decision is `null` and the extension keeps the current model. A laya-serve that is down refuses the connection at once, so the prompt waits a few milliseconds, not a timeout. The experimental worker loads its model in the background from `session_start`; prompts sent before it is ready are not routed (status shows `model loading — prompt not routed`) rather than held. It stays warm for the session, is reloaded in the background if it crashes, and is stopped on `session_shutdown`. A worker that is not ready within 5 minutes is killed.
+
+## Switch cost
+
+Switching models throws away the prompt cache: the first request on the new model reads the whole context at the uncached (or cache-write) price. Upgrades are quality-driven and only gated by confidence. A downgrade, or a move in from a model outside the table, must pay that premium back within `maxPaybackRequests` LLM requests out of what it saves per request (cheaper cache reads on the context plus cheaper output). Prices come from Pi's model registry; when either model has no price, the flat `cacheGuardTokens` limit applies instead. Lateral switches (direct ↔ exploration) are about fit rather than price and use the flat limit.
+
+## Hysteresis
+
+After the router switches, it waits `minPromptsBetweenSwitches` prompts before the next downgrade or lateral switch, so it does not flap between models. Upgrades are never delayed.
+
+## Manual pin
+
+If the user explicitly selects a model via `/model` or `Ctrl+P`, the extension steps back (`manualPin`) until `/pignon unpin`. The router's own switches also emit `model_select` (`source: "set"`) and are ignored.
+
+## Unrouted models
+
+If the current model is not in the routing table (matched on provider and model id), the router switches into the table only when tier confidence meets the downgrade threshold and the switch-cost check passes.
+
+## Shared models
+
+Cells mapped to the same provider, model and thinking level count as one; the router never re-selects the model already in use.
+
+## Worker isolation
+
+The worker gets an allowlisted environment (`PATH`, `HOME`, locale, proxies, CA bundles, `LAYA_*`, `HF_*`, `HUGGINGFACE_*`, `MLX_*`), not Pi's full environment with provider API keys. Its stderr is kept in memory (last 200 lines, see `/pignon log`) instead of being written over the TUI.
+
+## Pinned model
+
+The default checkpoint is pinned to the Hugging Face commit the router was calibrated on, so changes pushed to the Hub repo do not silently change routing. Bump `PINNED_REVISION` in `worker/laya_worker.py` deliberately, after re-checking decisions in shadow mode.
+
+## Prompt privacy
+
+Session log entries (`pignon-decision`) record a 16-hex-digit SHA-256 prefix and the length of each prompt, never its text.
+
+## Bounded worker load
+
+Only the first 4 000 characters of a prompt are sent (Laya reads about 320 tokens from the start anyway). Each request carries a deadline; the worker skips requests that expired while queued, so slow requests cannot pile up behind each other.
+
+## Shadow mode default
+
+New installs run in shadow mode so you can calibrate confidence thresholds on your own prompts before going live.

package/docs/PLAN-command-output.md

@@ -0,0 +1,161 @@
+# Plan (pignon): command output that is not truncated and does not persist
+
+Status: implemented · 2026-09-23 (see *Changes from the proposal*)
+
+## Problem
+
+`/pignon doctor` (and `config`, `log`, `stats`) render through `ctx.ui.setWidget(key, string[])`.
+Two consequences, both bad UX:
+
+1. **Truncated.** Pi keeps only the first 10 lines of a string-array widget and appends
+   `... (widget truncated)`. Doctor emits ~15–25 lines, so the model checks — the part the
+   user ran the command for — are silently dropped.
+2. **Persists.** A widget is a persistent slot: it stays above the editor through every
+   following prompt until `setWidget(key, undefined)`, i.e. until `/pignon doctor clear`.
+
+## Why it happens (verified in the Pi source)
+
+`@earendil-works/pi-coding-agent` 0.87.1, `InteractiveMode` in
+`dist/bundle/chunks/chunk-OJP47DM6.js`:
+
+```js
+if (Array.isArray(content)) {
+  let container = new Container;
+  for (let line of content.slice(0, _InteractiveMode.MAX_WIDGET_LINES))
+    container.addChild(new Text(line, 1, 0));
+  content.length > _InteractiveMode.MAX_WIDGET_LINES &&
+    container.addChild(new Text(theme.fg("muted", "... (widget truncated)"), 1, 0));
+  component = container;
+} else component = content(this.ui, theme);   // factory overload: no cap
+```
+
+with `static MAX_WIDGET_LINES = 10`.
+
+The cap applies **only** to the `string[]` overload. The component-factory overload is
+uncapped — `src/ui.ts` already relies on that for the `pignon-deciding` spinner.
+
+Corroborated by a third-party extension (`itayinbarr/little-coder`,
+`.pi/extensions/extensions-info/manifest.ts`):
+
+> pi slices a string-array widget to MAX_WIDGET_LINES (10) and appends
+> "... (widget truncated)", so anything past that is silently lost.
+
+Persistence is by design, not a bug: `docs/tui.md` lists `ctx.ui.setWidget()` under
+*"Persistent content near the editor"*. The fix is therefore to stop using a widget for
+one-shot reports, not to tune the widget.
+
+## What each command emits today
+
+| command | lines | vs the 10-line cap |
+| --- | --- | --- |
+| `doctor` | ~15–25: header, `config` + 1–2, `deciders` + 1–3, `models` + up to 8 | truncated |
+| `log` | 30 (`LOG_WIDGET_LINES`) | truncated to 10 — worst case |
+| `stats` | ~12+: header, bucket header, 3 tiers × 2 forms, summary | truncated |
+| `config` | ~8: header, column header, N tiers, footer, hint | ok at 3 tiers, truncates at 4+ |
+
+## Decision
+
+Render one-shot reports in a **dismissible overlay** (`ctx.ui.custom({ overlay: true })`)
+that scrolls itself: no line cap, scrollable, disposed on close so nothing persists.
+Fallback to `notify` in RPC mode and to stderr in print/JSON mode.
+
+Apply it to **all four** commands through one shared helper.
+
+## Design
+
+### `src/report.ts` (new)
+
+```ts
+export async function showReport(
+  ctx: ExtensionContext,
+  title: string,
+  lines: string[] | Promise<string[]>,
+): Promise<void>
+```
+
+Three tiers, following `docs/extensions.md` (*"Guard terminal-only behavior with
+`ctx.mode === "tui"` and use `ctx.hasUI` for interactions supported by interactive and RPC
+clients"*):
+
+| mode | behaviour |
+| --- | --- |
+| `ctx.mode === "tui"` | `ctx.ui.custom(..., { overlay: true })` — `ReportOverlay` below |
+| RPC (`ctx.hasUI`, not tui) | `ctx.ui.notify(lines.join("\n"), "info")` — RPC forwards `notify`, not custom components |
+| print / JSON (`!ctx.hasUI`) | `process.stderr.write(lines.join("\n") + "\n")` — stdout stays parseable in JSON mode |
+
+The `Promise<string[]>` overload matters for `doctor`, which can block ~15 s on the decider
+probe: open the overlay immediately with `running checks…`, then `setLines()` →
+`invalidate()` + `tui.requestRender()` when it resolves. The editor is never left looking
+frozen.
+
+### `ReportOverlay`
+
+A `Component` (`render(width)` / `handleInput(data)` / `invalidate()` / `dispose()`):
+
+- Keeps its own line offset and renders only the visible slice, framed by a
+  rounded border: title in the top rule; hint and `a–b/n` position in the bottom rule
+- Body height: 70% of `tui.terminal.rows` (read on each render) minus the 2 border rows
+- Overlay options: `{ width: <widest line + frame>, minWidth: 40, anchor: "center", margin: 1 }`;
+  `90%` while doctor's lines are still pending (Pi resolves overlay options once, at open)
+- Keys: ↑↓ / `j` `k` (line), PgUp / PgDn / space (page), Home / End / `g` `G`,
+  `Esc` / `q` / `Enter` → `done()`
+- Every line passes through `truncateToWidth(…, pad)` — see Risks
+
+## Files
+
+| file | change |
+| --- | --- |
+| `src/report.ts` | **new** — `showReport()` + `ReportOverlay` |
+| `src/extension.ts` | replace the 4 report `showWidget(...)` calls with `showReport(...)`; drop the `"(/pignon X clear to hide)"` trailers; raise `LOG_WIDGET_LINES` 30 → 200 (the overlay scrolls) |
+| `src/config/describe.ts` | drop its internal `"(/pignon config clear to hide)"` line |
+| `src/ui.ts` | unchanged — `showDeciding` is *meant* to persist, and already uses the uncapped factory overload |
+| `src/onboarding.ts` | unchanged — already returns plain `string[]` |
+| `tests/extension.test.ts`, `tests/extension-routing.test.ts` | add `custom` and `mode` to the mocks; update the `ctx.ui.setWidget` assertions |
+| `tests/report.test.ts` | **new** — overlay line rendering and key handling (pure, no terminal) |
+| `tests/helpers/fake-report.ts` | **new** — a `ctx.ui.custom` fake that keeps the overlay for assertions |
+| `src/stats.ts`, `src/compare.ts` | drop their `"(/pignon-stats clear to hide)"` lines |
+| `README.md`, `CHANGELOG.md` | the four commands no longer need `clear`; keep the subcommands as no-ops for back-compat |
+
+## Steps
+
+1. Write `src/report.ts`: `ReportOverlay` (Box + ScrollView + Text) and `showReport()`.
+2. Rewire `doctor`, `config`, `log`, `stats` in `src/extension.ts`; remove the "clear to
+   hide" trailers.
+3. Extend the test mocks with `custom` and `mode`, then update and add tests.
+4. Update README and CHANGELOG.
+
+## Risks
+
+- **Width overflow.** pi-tui throws on over-wide lines (reported upstream as issue #48 by
+  `little-coder`). `truncateToWidth()` on every line is load-bearing, not cosmetic.
+- **Modal.** `doctor` now needs `Esc` before the user can type again. Accepted: it is a
+  diagnostic, and it is the cost of nothing persisting.
+- **Key collision.** `matchesKey(data, "q")` is safe here only because the overlay has no
+  text input. Any future search/filter field inside it must handle `q` as text first.
+- **Back-compat.** `doctor clear` / `config clear` / `stats clear` / `log clear` stay
+  accepted and keep clearing the (now unused) widget key so a stale widget from an older
+  session cannot linger.
+
+## Changes from the proposal
+
+- **No `ScrollView`.** Pi composites overlays in `TUI.compositeOverlays()`
+  (`pi-tui/dist/tui.js`): it calls `component.render(width)` and slices the result to
+  `maxHeight`. The `[LAYOUT_NODE]` / `updateLayout` path runs only in
+  `renderLayoutFrame()` for the alt-screen root, never for overlays, and
+  `ScrollView.render()` returns all of its child's lines. A `ScrollView` in an overlay
+  would therefore never scroll, and `maxHeight: "70%"` would truncate it silently: the
+  same bug with a border around it. `ReportOverlay` scrolls itself instead.
+- **Overlay options go under `overlayOptions`**, not at the top level of the `custom()`
+  options.
+- **Width fits the content** instead of a fixed 80%, which truncated the config table's
+  last column at 100 columns.
+- **Five call sites, not four**: `/pignon-stats compare` also used the widget. `stats.ts`
+  and `compare.ts` had their own "clear to hide" lines too.
+- **Titles move into the border.** Each report's first line (`pignon doctor`,
+  `pignon config · <source>`, …) becomes the overlay title. The producers are unchanged,
+  so RPC and stderr output still start with it.
+- `clear` subcommands are no longer offered in completion, but are still accepted.
+- A rejected `lines` promise shows `✗ <message>` in the overlay instead of leaving
+  `running checks…` forever.
+- Verified in Pi 0.87.1 through a pty: config and doctor render whole, doctor scrolls on a
+  14-row terminal, and Esc leaves nothing above the editor.