@mjasnikovs/pi-task 0.18.47 → 0.18.49

package/README.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/@mjasnikovs/pi-task?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mjasnikovs/pi-task)
 [![license](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
-[![tests](https://img.shields.io/badge/tests-1936%20passing-3fb950)](#development)
+[![tests](https://img.shields.io/badge/tests-2077%20passing-3fb950)](#development)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
 
 </div>
@@ -65,7 +65,7 @@ A whole plan — `/task-auto` splits it into an ordered task list and runs each
 | `/task-auto <feature>` | Plan a feature into a task list and run each title through `/task` in order (resumable). |
 | `/task-auto-resume [--unattended]` | Resume the active `/task-auto` run at the next unfinished task. `--unattended` is the boot-hook form: in-flight runs only. |
 | `/task-auto-cancel` | Stop the `/task-auto` loop after the current task (still resumable). |
-| `/task-config` | Toggle pi-task settings in an editor dialog: remote server, compress reasoning, auto-commit, orientation, verify work, enforce guidelines, command timeout, stream watchdog, and the extension whitelist for child sessions. |
+| `/task-config` | Toggle pi-task settings in an editor dialog: remote control, compress thinking, auto-commit, verify work, enforce guidelines, project tour, command timeout, stuck reply retry, and one `ext:` toggle per installed host extension. |
 | `/remote` | Show the QR code & URLs for the web view (`/remote stop` to stop). Answer grill questions, start tasks, and watch progress from your phone. |
 
 ## The pipeline
@@ -171,25 +171,25 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 
 | Setting | Default | What it does |
 | --- | --- | --- |
-| **remote** | on | The remote UI server (QR code, phone access). Turn off to never start it. |
-| **compress reasoning** | on | After each message, compresses the model's `<think>` blocks down to the decisions/constraints/facts that matter later — keeping long local-model runs from drowning their own context in self-talk. |
+| **remote control** | on | The remote UI server (QR code, phone access). Turn off to never start it. |
+| **compress thinking** | on | After each message, compresses the model's `<think>` blocks down to the decisions/constraints/facts that matter later — keeping long local-model runs from drowning their own context in self-talk. |
 | **auto-commit** | on | Snapshots the working tree into one git commit per `/task-auto` sub-task (see above). |
-| **orientation** | on | Pre-reads the project's core files (manifest, config, domain types, schema, entrypoints, API surface) once and hands the contents to the read-heavy research workers, so they skip re-discovering the same files cold. Bounded by a hard byte budget; applied only where it helps (FILES/APIS workers). |
 | **verify work** | on | After each `/task` (and `/task-auto` task) implements — but **before** it's checked off or committed — actually **runs** the spec's own `VERIFY` block in the real workspace. pi-task otherwise only _authors_ a VERIFY block and never executes it, so a task that doesn't build is indistinguishable from one that works. A fresh `read` + `bash` child of the same local model runs the declared check, observes the real output, and reports **PASS/FAIL** (a legitimately no-op VERIFY is a PASS). On FAIL the run doesn't dead-stop: you get a boxed picker — **Autofix** (re-run the implementation turn against the failure, then re-verify; no attempt cap) or **Accept** (override a misjudged artifact) — and dismissing it pauses the run, resumable. A genuine clean pass is also the behavioral signal that lets **enforce guidelines** fix in place (see below). |
 | **enforce guidelines** | on | After each `/task` (and `/task-auto` task) is committed, re-checks that commit's work against the project's `AGENTS.md` / `CLAUDE.md` (in the working directory). A bare fix-in-place pass trashes working code (A/B-proven), so enforcement is gated on the **verify work** signal. **With** a genuine verify pass: a fresh `read` + `edit` child of the same local model reads the **last commit's** diff and fixes violations in place; its fixes are committed **separately** as an `ENFORCE GUIDELINES` commit, then the verify signal is re-run against the enforced tree — a regression **reverts** the enforce commit and keeps the verified work. **Without** that signal (verify off, no spec, or an accept-override): the pass runs read-only and only **reports** violations, never rewrites logic. Either way a violation it can't clear (or a pass that can't run) only **warns** — the task commit already landed, so the run continues. Skipped when nothing was committed for the task. |
+| **project tour** | on | Pre-reads the project's core files (manifest, config, domain types, schema, entrypoints, API surface) once and hands the contents to the read-heavy research workers, so they skip re-discovering the same files cold. Bounded by a hard byte budget; applied only where it helps (FILES/APIS workers). |
 | **parallel research** | off | Run the four research workers concurrently instead of one at a time. Leave off on a single-GPU local backend (concurrent streams split the GPU and slow each other down); turn on only for a parallel-capable model server. |
 | **research cache** | on | Cache docs/search/fetch worker results for the duration of one `/task-auto` run so sibling tasks re-asking the same package/URL + query reuse the first pipeline's digest instead of re-fetching. Per-run isolated, external-only (project-source `.` lookups excluded), success-only. |
-| **search provider** | Exa | Engine behind `pi-worker-search` and freshness/enrichment checks. **Exa** (default) and **DuckDuckGo** need no API key; **Brave** requires `BRAVE_SEARCH_API_KEY`. |
+| **search engine** | Exa | Engine behind `pi-worker-search` and freshness/enrichment checks. **Exa** (default) and **DuckDuckGo** need no API key; **Brave** requires `BRAVE_SEARCH_API_KEY`. |
 | **command timeout** | 15 min | Wall-clock ceiling on a **single** tool execution. Local models routinely run a command that never returns (a hung build, a dev server, a check with no timeout) and the run wedges until you abort by hand — pi's bash tool has an optional timeout with no default, so this is the missing one. One knob, two surfaces: in the main session the overrun call is cancelled (killing the tool's whole process tree) plus a reminder turn; in the verify/fix gate children the child is killed and re-spawned with a hint, halving the ceiling on repeat hangs. Choices: 5/10/15/30 min or **off** — off unguards both surfaces, gates included. |
-| **stream watchdog** | 10 min | Inactivity ceiling on the **model stream**. A hung or silently-dropped stream throws nothing at all, so neither the connection-error retry (it needs a reported error) nor the **command timeout** (tool calls only) nor the dead-backend stall guard (a reachable endpoint reads as proof of life) can see it — an mx5 run lost ~2.9h to three of them while the model server stayed healthy. Measured as time since the **last stream event of any kind**, so a slow model emitting one token every 30s is never touched, and it pauses while a tool runs. On expiry the main session aborts the turn (through the same channel the command watchdog uses) and posts a resume reminder; a child is killed and routed into the existing connection-error retry. Choices: 5/10/20/30 min or **off**. Keep it generous on local backends — prompt processing on a large context legitimately emits nothing for minutes. |
+| **stuck reply retry** | 10 min | Inactivity ceiling on the **model stream**. A hung or silently-dropped stream throws nothing at all, so neither the connection-error retry (it needs a reported error) nor the **command timeout** (tool calls only) nor the dead-backend stall guard (a reachable endpoint reads as proof of life) can see it — an mx5 run lost ~2.9h to three of them while the model server stayed healthy. Measured as time since the **last stream event of any kind**, so a slow model emitting one token every 30s is never touched, and it pauses while a tool runs. On expiry the main session aborts the turn (through the same channel the command watchdog uses) and posts a resume reminder; a child is killed and routed into the existing connection-error retry. Choices: 5/10/20/30 min or **off**. Keep it generous on local backends — prompt processing on a large context legitimately emits nothing for minutes. |
 | **yolo mode** | off | **Unattended runs.** Wherever pi-task would stop and ask, it takes the option already marked RECOMMENDED, stamps the artifact `(YOLO)` so an audit can tell a machine decided, and shows no prompt at all — clarify/grill answers, the verify-FAIL picker (auto-**Accept**, recorded as a yolo debt), and the final-gate picker (autofix while the budget lasts, then leave the run FAILED). A question with no recommendation is **skipped**, never invented. For throwaway/test projects nobody is watching; a real run should decide these itself. |
-| **extension whitelist** | empty | Host `pi` extensions to load into every child session by explicit path. Children otherwise run with extensions off, so a provider registered by an extension (e.g. `pi-lmstudio`) doesn't exist in them and they can't resolve the default model. `/task-config` enumerates the currently installed extensions as individual `ext: …` toggles; the list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |
+| **ext: …** | all off | One toggle per installed host `pi` extension, loading it into every child session by explicit path. Children otherwise run with extensions off, so a provider registered by an extension (e.g. `pi-lmstudio`) doesn't exist in them and they can't resolve the default model. Children also inherit the extension's tools and hooks, so only enable ones you trust. The list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |
 
 ## Configuration
 
 | Variable | Used by | Notes |
 | --- | --- | --- |
-| `BRAVE_SEARCH_API_KEY` / `BRAVE_API_KEY` | `pi-worker-search`, research enrichment | Required only when the **Brave** search provider is selected in `/task-config`. |
+| `BRAVE_SEARCH_API_KEY` / `BRAVE_API_KEY` | `pi-worker-search`, research enrichment | Required only when the **Brave** search engine is selected in `/task-config`. |
 | `XDG_CACHE_HOME` | `pi-worker-docs` | Overrides the docs cache location (defaults to `~/.cache`). |
 | `XDG_DATA_HOME` | remote push | Where the VAPID keypair is stored (defaults to `~/.local/share`). |
 | `PI_REMOTE_PUSH_SUBJECT` | remote push | VAPID JWT `sub` contact. Defaults to the project URL; set your own `mailto:you@domain.com` or `https://…`. |
@@ -202,7 +202,7 @@ Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. Add `.pi-tasks/` to your
 
 ```sh
 bun install
-bun run test       # 1939 tests across 121 files
+bun run test       # 2078 tests across 129 files
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```

package/dist/config/register.d.ts

@@ -1,5 +1,42 @@
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import type { Component } from '@earendil-works/pi-tui';
+import { type PiTaskConfig } from './config.js';
 import { type InstalledExtension } from './extension-list.js';
+type Theme = ExtensionCommandContext['ui']['theme'];
+/**
+ * Frames a child component (the settings list) in a rounded border with a title
+ * woven into the top edge. Without this the overlay's content sits flush against
+ * the chat scrollback and reads as just more console text; the border gives it a
+ * distinct panel. Layout mirrors {@link renderQuestionBox}'s box chrome: render
+ * the child at the inner width, pad each line so the right edge lines up, then
+ * frame. Input and invalidation are forwarded straight through to the child.
+ */
+declare class BorderedBox implements Component {
+    private readonly child;
+    private readonly title;
+    private readonly border;
+    private readonly titleColor;
+    /**
+     * Body lines to pad out to. The settings list grows and shrinks with the
+     * selected item's description, so without a floor the whole panel jumps
+     * a few rows every time the cursor moves. Padding to the tallest layout
+     * keeps the border still while the contents change.
+     */
+    private readonly minBodyLines;
+    constructor(child: Component & {
+        handleInput(data: string): void;
+    }, title: string, border: (s: string) => string, titleColor: (s: string) => string, 
+    /**
+     * Body lines to pad out to. The settings list grows and shrinks with the
+     * selected item's description, so without a floor the whole panel jumps
+     * a few rows every time the cursor moves. Padding to the tallest layout
+     * keeps the border still while the contents change.
+     */
+    minBodyLines?: number);
+    render(width: number): string[];
+    invalidate(): void;
+    handleInput(data: string): void;
+}
 export declare function extensionItems(extensions: InstalledExtension[], whitelist: readonly string[]): {
     id: string;
     label: string;
@@ -9,4 +46,28 @@ export declare function extensionItems(extensions: InstalledExtension[], whiteli
 }[];
 /** Apply an extension toggle to the config's whitelist (idempotent both ways). */
 export declare function applyExtensionToggle(whitelist: readonly string[], entryPath: string, on: boolean): string[];
+/**
+ * Tallest body the settings list can render, so {@link BorderedBox} can pad
+ * every frame to it and hold the border still. Mirrors SettingsList's own
+ * layout: one pad row, the visible rows, the scroll counter, a blank, the
+ * selected item's wrapped description, a blank, the key hint.
+ */
+export declare function settingsBodyHeight(descriptions: string[], maxVisible: number, wrapWidth: number): number;
+/** A settings row as {@link SettingsList} wants it. */
+export type PanelItem = {
+    id: string;
+    label: string;
+    description: string;
+    currentValue: string;
+    values: string[];
+};
+/**
+ * Builds the framed settings panel. Split out of the command handler so the
+ * exact component the overlay shows can be rendered to a string in a test or a
+ * preview script, rather than only being inspectable by opening the TUI.
+ */
+export declare function createSettingsPanel(items: PanelItem[], theme: Theme, onChange: (id: string, newValue: string) => void, onCancel: () => void): BorderedBox;
+/** The full settings row list for the current config, in menu order. */
+export declare function panelItems(cfg: PiTaskConfig, installed: InstalledExtension[]): PanelItem[];
 export declare function registerConfig(pi: ExtensionAPI): void;
+export {};

package/dist/config/register.js

@@ -1,9 +1,12 @@
-import { SettingsList, visibleWidth } from '@earendil-works/pi-tui';
+import { SettingsList, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
 import { registerBridgeCommand } from '../remote/bridge.js';
+import { readPkgVersion } from '../shared/pkg-version.js';
 import { SEARCH_PROVIDERS, SEARCH_PROVIDER_LABELS, providerForLabel } from '../workers/search-types.js';
 import { COMMAND_TIMEOUT_OPTIONS, getConfig, saveConfig, STREAM_INACTIVITY_OPTIONS } from './config.js';
 import { listInstalledExtensions } from './extension-list.js';
-const CONFIG_TITLE = 'pi-task settings';
+// Version in the title so a bug report or screenshot says which build it came
+// from without anyone having to go look it up.
+const CONFIG_TITLE = `pi-task ${readPkgVersion()} settings`;
 /**
  * Frames a child component (the settings list) in a rounded border with a title
  * woven into the top edge. Without this the overlay's content sits flush against
@@ -17,11 +20,20 @@ class BorderedBox {
     title;
     border;
     titleColor;
-    constructor(child, title, border, titleColor) {
+    minBodyLines;
+    constructor(child, title, border, titleColor, 
+    /**
+     * Body lines to pad out to. The settings list grows and shrinks with the
+     * selected item's description, so without a floor the whole panel jumps
+     * a few rows every time the cursor moves. Padding to the tallest layout
+     * keeps the border still while the contents change.
+     */
+    minBodyLines = 0) {
         this.child = child;
         this.title = title;
         this.border = border;
         this.titleColor = titleColor;
+        this.minBodyLines = minBodyLines;
     }
     render(width) {
         const innerWidth = Math.max(1, width - 4); // "│ " + content + " │"
@@ -33,7 +45,13 @@ class BorderedBox {
         const top = rest >= 0 ?
             this.border(`╭${dash(lead)}`) + this.titleColor(tag) + this.border(`${dash(rest)}╮`)
             : this.border(`╭${dash(width - 2)}╮`);
-        const body = this.child.render(innerWidth).map(line => {
+        // One blank row under the title so the first setting is not welded to
+        // the border, then the child, then padding up to the stable height.
+        const childLines = this.child.render(innerWidth);
+        const raw = ['', ...childLines];
+        while (raw.length < this.minBodyLines)
+            raw.push('');
+        const body = raw.map(line => {
             const pad = innerWidth - visibleWidth(line);
             const padded = pad > 0 ? line + ' '.repeat(pad) : line;
             return this.border('│ ') + padded + this.border(' │');
@@ -53,83 +71,95 @@ class BorderedBox {
  * toggle on/off; enum settings list their values and cycle through them.
  */
 const ITEMS = [
-    { id: 'remote', label: 'remote', description: 'Remote UI server (QR code, phone access)' },
+    {
+        id: 'remote',
+        label: 'remote control',
+        description: 'Serve the task UI on your local network so you can follow and steer a run from '
+            + 'your phone. Prints a QR code to scan when it starts'
+    },
     {
         id: 'compressReasoning',
-        label: 'compress reasoning',
-        description: 'Compress <think> blocks after each message'
+        label: 'compress thinking',
+        description: "Shrink the model's thinking blocks once it has moved on, so a long run keeps more "
+            + 'room for the work itself'
     },
     {
         id: 'autoCommit',
         label: 'auto-commit',
-        description: 'git commit around each /task-auto sub-task (checkpoint before, snapshot after)'
-    },
-    {
-        id: 'orientation',
-        label: 'orientation',
-        description: 'Pre-supply the project core (manifest, types, schema…) to the read-heavy research workers'
+        description: 'Make a git commit before and after every sub-task, so each step is a checkpoint '
+            + 'you can read back or roll back to'
     },
     {
         id: 'verifyWork',
         label: 'verify work',
-        description: "After each /task (and /task-auto task), RUN its spec's VERIFY block in the workspace and report a PASS/FAIL verdict (also the signal that lets 'enforce guidelines' fix safely). Enabling it makes /task wait for the implementation"
+        description: 'When a task says it is done, actually run the checks its spec asks for and report '
+            + "PASS or FAIL instead of taking the model's word for it. This is also what lets "
+            + '"enforce guidelines" fix things safely. /task waits for the work to finish'
     },
     {
         id: 'enforceGuidelines',
         label: 'enforce guidelines',
-        description: "Check each /task and /task-auto commit against AGENTS.md/CLAUDE.md. Needs 'verify work' to FIX drift (fixes are reverted if they regress verification); without it, only reports violations. Enabling it makes /task wait for the implementation"
+        description: 'Check what each task committed against your AGENTS.md / CLAUDE.md rules. With '
+            + '"verify work" on it also fixes what it finds, undoing any fix that breaks the '
+            + 'checks; on its own it only reports. /task waits for the work to finish'
+    },
+    {
+        id: 'orientation',
+        label: 'project tour',
+        description: 'Show the research workers the shape of the project first — package manifest, '
+            + 'types, schema — so they spend their steps on the question instead of on finding '
+            + 'their way around'
     },
     {
         id: 'parallelResearchWorkers',
         label: 'parallel research',
-        description: 'Run the 4 research workers concurrently. Leave OFF on a single-GPU local server (serial is measurably faster there); turn on only for a parallel-capable model backend'
+        description: 'Run the 4 research workers at once instead of one after another. Only faster if '
+            + 'your model backend can answer several requests at the same time — on a single '
+            + 'local GPU it is measurably slower, so leave it off there'
     },
     {
         id: 'researchCache',
         label: 'research cache',
-        description: 'Cache docs/search/fetch results within one /task-auto run so sibling tasks reuse the first pipeline’s digest instead of re-fetching the same external docs. Per-run isolated, external-only, success-only'
+        description: 'Remember docs and web pages for the length of one run, so later tasks reuse what '
+            + 'the first one already fetched instead of downloading it again. Only external '
+            + 'sources, only successful fetches, and it is dropped when the run ends'
     },
     {
         id: 'searchProvider',
-        label: 'search provider',
-        description: 'Engine behind web search (pi-worker-search + freshness checks). Exa and DuckDuckGo need no API key; Brave needs BRAVE_SEARCH_API_KEY',
+        label: 'search engine',
+        description: 'Which engine backs web search. Exa and DuckDuckGo work with no setup; Brave needs '
+            + 'a BRAVE_SEARCH_API_KEY in your environment',
         // Display full engine names; the stored config value stays the short id.
         values: SEARCH_PROVIDERS.map(p => SEARCH_PROVIDER_LABELS[p])
     },
     {
         id: 'requestTimeoutMs',
         label: 'command timeout',
-        description: 'Cancel a single command that runs longer than this and remind the model to set '
-            + 'its own timeout. Catches a local model that runs a command which never returns '
-            + '(hung build, dev server, no-timeout check) so the run stops itself instead of '
-            + 'waiting for a manual abort. One knob for both surfaces: the main session AND '
-            + 'the verify/fix gate children. off disables it everywhere — gates can then hang '
-            + 'unbounded',
+        description: 'Give up on any single command that runs this long, and tell the model to set its '
+            + 'own timeout next time. Stops a run from waiting forever on a dev server or a '
+            + 'hung build. Covers the main session and the checking steps; "off" lets a stuck '
+            + 'command hang the run until you notice',
         // Display human labels; the stored config value stays the ms number.
         values: COMMAND_TIMEOUT_OPTIONS.map(o => o.label)
     },
     {
         id: 'streamInactivityMs',
-        label: 'stream watchdog',
-        description: 'Abort and retry a model request whose stream goes SILENT for this long — a hung '
-            + 'or dropped stream reports no error at all, so nothing else catches it (mx5 run '
-            + '14 lost ~2.9h to three of them while the model server stayed healthy). Counts '
-            + 'time since the last stream event of any kind, so a slow model that keeps '
-            + 'emitting tokens is never touched, and it pauses while a tool runs. Keep it '
-            + 'generous on local backends: prompt processing on a large context legitimately '
-            + 'emits nothing for minutes. off disables it on both the main session and children',
+        label: 'stuck reply retry',
+        description: 'Give up on a model reply that has sent nothing for this long and ask again. A '
+            + 'dropped connection looks exactly like a model thinking hard and reports no '
+            + 'error, so a run can sit dead for hours. Only total silence counts, and the clock '
+            + 'pauses while a command runs — local models go quiet for minutes on long prompts, '
+            + 'so leave room',
         // Display human labels; the stored config value stays the ms number.
         values: STREAM_INACTIVITY_OPTIONS.map(o => o.label)
     },
     {
         id: 'yoloMode',
         label: 'yolo mode',
-        description: 'UNATTENDED: auto-answer every question with the option pi already recommends, '
-            + 'and show no prompts at all — clarify/grill answers, the verify-FAIL picker '
-            + '(auto-ACCEPT, recorded as a yolo debt), and the final-gate picker (autofix '
-            + 'while the budget lasts, then leave the run FAILED). Every auto-pick is stamped '
-            + '(YOLO) in the task file and debt ledger. For THROWAWAY/TEST projects you are '
-            + 'not watching — a real run should decide these itself'
+        description: 'Stop asking you anything: every question takes the option pi recommends, a failed '
+            + 'check is accepted and written down as debt, and a failed final check is retried '
+            + 'until the budget runs out. Each auto-answer is marked (YOLO) in the task file. '
+            + 'For throwaway projects you are not watching'
     }
 ];
 /** Human label for the stored command-timeout ms (falls back to the raw ms). */
@@ -162,10 +192,10 @@ export function extensionItems(extensions, whitelist) {
     return extensions.map(e => ({
         id: EXT_ID_PREFIX + e.path,
         label: `ext: ${e.label}`,
-        description: `Also load this extension (${e.origin}) in pi-task child sessions — needed when it `
-            + 'registers the model provider the children must use (e.g. pi-lmstudio). Children '
-            + 'otherwise run with extensions off; whitelist only provider-type extensions you '
-            + `trust, since children also get its tools and hooks. ${e.path}`,
+        description: `Load this ${e.origin} extension in the helper sessions pi-task spawns. They run `
+            + 'with extensions off by default, so turn this on when the extension provides the '
+            + 'model they need (pi-lmstudio, for example). They also inherit its tools and '
+            + `hooks, so only enable ones you trust. ${e.path}`,
         currentValue: whitelist.includes(e.path) ? 'on' : 'off',
         values: ['on', 'off']
     }));
@@ -175,15 +205,62 @@ export function applyExtensionToggle(whitelist, entryPath, on) {
     const rest = whitelist.filter(p => p !== entryPath);
     return on ? [...rest, entryPath] : rest;
 }
+/** Overlay width; the list gets `- 4` of it, the description `- 4` again. */
+const OVERLAY_WIDTH = 68;
+/** Settings rows shown at once before the list scrolls. */
+const MAX_VISIBLE = 9;
+/**
+ * Tallest body the settings list can render, so {@link BorderedBox} can pad
+ * every frame to it and hold the border still. Mirrors SettingsList's own
+ * layout: one pad row, the visible rows, the scroll counter, a blank, the
+ * selected item's wrapped description, a blank, the key hint.
+ */
+export function settingsBodyHeight(descriptions, maxVisible, wrapWidth) {
+    const tallestDescription = Math.max(0, ...descriptions.map(d => wrapTextWithAnsi(d, wrapWidth).length));
+    return 1 + maxVisible + 1 + 1 + tallestDescription + 1 + 1;
+}
 function makeTheme(theme) {
     return {
-        label: (text, selected) => (selected ? theme.fg('accent', text) : text),
-        value: text => (text === 'on' ? theme.fg('success', text) : theme.fg('muted', text)),
+        label: (text, selected) => selected ? theme.fg('accent', theme.bold(text)) : theme.fg('text', text),
+        // A filled/hollow dot makes the on/off column scannable at a glance
+        // without reading a word on every row. Enum values (an engine name, a
+        // duration) are real content, so they stay readable rather than muted.
+        value: (text, selected) => {
+            if (text === 'on')
+                return theme.fg('success', '● on');
+            if (text === 'off')
+                return theme.fg('dim', '○ off');
+            return theme.fg(selected ? 'accent' : 'muted', text);
+        },
         description: text => theme.fg('muted', text),
-        cursor: theme.fg('accent', '>'),
+        // Two cells wide to match the unselected row's "  " indent — a
+        // single-cell cursor shifts the selected label one column left.
+        cursor: theme.fg('accent', '❯') + ' ',
         hint: text => theme.fg('dim', text)
     };
 }
+/**
+ * Builds the framed settings panel. Split out of the command handler so the
+ * exact component the overlay shows can be rendered to a string in a test or a
+ * preview script, rather than only being inspectable by opening the TUI.
+ */
+export function createSettingsPanel(items, theme, onChange, onCancel) {
+    const list = new SettingsList(items, MAX_VISIBLE, makeTheme(theme), onChange, onCancel);
+    return new BorderedBox(list, CONFIG_TITLE, s => theme.fg('borderMuted', s), s => theme.fg('accent', theme.bold(s)), settingsBodyHeight(items.map(i => i.description), MAX_VISIBLE, OVERLAY_WIDTH - 8));
+}
+/** The full settings row list for the current config, in menu order. */
+export function panelItems(cfg, installed) {
+    return [
+        ...ITEMS.map(({ id, label, description, values }) => ({
+            id: id,
+            label,
+            description,
+            currentValue: displayValue(cfg, id, Boolean(values)),
+            values: values ?? ['on', 'off']
+        })),
+        ...extensionItems(installed, cfg.extensionWhitelist)
+    ];
+}
 async function handleTaskConfig(_args, ctx) {
     const cfg = { ...getConfig(), extensionWhitelist: [...getConfig().extensionWhitelist] };
     // Enumerated live at open so an installed extension appears and an
@@ -199,50 +276,36 @@ async function handleTaskConfig(_args, ctx) {
         ctx.ui.notify(lines.join('  |  '), 'info');
         return;
     }
-    await ctx.ui.custom((_tui, theme, _kb, done) => {
-        const listTheme = makeTheme(theme);
-        const items = [
-            ...ITEMS.map(({ id, label, description, values }) => ({
-                id: id,
-                label,
-                description,
-                currentValue: displayValue(cfg, id, Boolean(values)),
-                values: values ?? ['on', 'off']
-            })),
-            ...extensionItems(installed, cfg.extensionWhitelist)
-        ];
-        const list = new SettingsList(items, 10, listTheme, (id, newValue) => {
-            if (id.startsWith(EXT_ID_PREFIX)) {
-                cfg.extensionWhitelist = applyExtensionToggle(cfg.extensionWhitelist, id.slice(EXT_ID_PREFIX.length), newValue === 'on');
-            }
-            else if (id === 'searchProvider') {
-                const provider = providerForLabel(newValue);
-                if (provider)
-                    cfg.searchProvider = provider;
-            }
-            else if (id === 'requestTimeoutMs') {
-                const opt = COMMAND_TIMEOUT_OPTIONS.find(o => o.label === newValue);
-                if (opt)
-                    cfg.requestTimeoutMs = opt.ms;
-            }
-            else if (id === 'streamInactivityMs') {
-                const opt = STREAM_INACTIVITY_OPTIONS.find(o => o.label === newValue);
-                if (opt)
-                    cfg.streamInactivityMs = opt.ms;
-            }
-            else {
-                ;
-                cfg[id] = newValue === 'on';
-            }
-            saveConfig(cfg).catch(() => { });
-        }, () => done(undefined));
-        return new BorderedBox(list, CONFIG_TITLE, s => theme.fg('borderMuted', s), s => theme.fg('accent', theme.bold(s)));
-    }, { overlay: true, overlayOptions: { width: 58 } });
+    await ctx.ui.custom((_tui, theme, _kb, done) => createSettingsPanel(panelItems(cfg, installed), theme, (id, newValue) => {
+        if (id.startsWith(EXT_ID_PREFIX)) {
+            cfg.extensionWhitelist = applyExtensionToggle(cfg.extensionWhitelist, id.slice(EXT_ID_PREFIX.length), newValue === 'on');
+        }
+        else if (id === 'searchProvider') {
+            const provider = providerForLabel(newValue);
+            if (provider)
+                cfg.searchProvider = provider;
+        }
+        else if (id === 'requestTimeoutMs') {
+            const opt = COMMAND_TIMEOUT_OPTIONS.find(o => o.label === newValue);
+            if (opt)
+                cfg.requestTimeoutMs = opt.ms;
+        }
+        else if (id === 'streamInactivityMs') {
+            const opt = STREAM_INACTIVITY_OPTIONS.find(o => o.label === newValue);
+            if (opt)
+                cfg.streamInactivityMs = opt.ms;
+        }
+        else {
+            ;
+            cfg[id] = newValue === 'on';
+        }
+        saveConfig(cfg).catch(() => { });
+    }, () => done(undefined)), { overlay: true, overlayOptions: { width: OVERLAY_WIDTH } });
 }
 export function registerConfig(pi) {
     registerBridgeCommand(pi, 'task-config', {
-        description: 'Configure pi-task settings (remote, compress reasoning, auto-commit, orientation, '
-            + 'enforce guidelines, command timeout, extension whitelist for child sessions).',
+        description: 'Configure pi-task settings (remote control, auto-commit, verify work, enforce '
+            + 'guidelines, research, timeouts, extensions for helper sessions).',
         handler: handleTaskConfig
     });
 }

package/dist/shared/pkg-version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The installed pi-task version, read from package.json at runtime so nothing
+ * has to be regenerated on release. Two levels up holds for both src/<dir>
+ * (tests) and dist/<dir> (build), since tsc preserves the layout under rootDir.
+ * Falls back to '0.0.0' rather than throwing: every caller here is cosmetic
+ * (a User-Agent, a title bar) and none is worth failing over.
+ */
+export declare function readPkgVersion(): string;

package/dist/shared/pkg-version.js

@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The installed pi-task version, read from package.json at runtime so nothing
+ * has to be regenerated on release. Two levels up holds for both src/<dir>
+ * (tests) and dist/<dir> (build), since tsc preserves the layout under rootDir.
+ * Falls back to '0.0.0' rather than throwing: every caller here is cosmetic
+ * (a User-Agent, a title bar) and none is worth failing over.
+ */
+export function readPkgVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/dist/workers/html-clean.js

@@ -1,9 +1,7 @@
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
 import { parseHTML } from 'linkedom';
 import { Readability } from '@mozilla/readability';
 import TurndownService from 'turndown';
+import { readPkgVersion } from '../shared/pkg-version.js';
 const turndown = new TurndownService({
     codeBlockStyle: 'fenced',
     headingStyle: 'atx',
@@ -33,21 +31,9 @@ export function cleanHtml(html, baseUrl) {
 }
 const DEFAULT_TIMEOUT_MS = 15_000;
 const DEFAULT_MAX_BYTES = 2 * 1024 * 1024; // 2 MB
+// Read at runtime so the User-Agent never drifts out of sync with releases.
 const PKG_VERSION = readPkgVersion();
 const USER_AGENT = `pi-worker/${PKG_VERSION} (+https://npmjs.com/package/@mjasnikovs/pi-worker)`;
-// Read the version from package.json at runtime so the User-Agent never drifts
-// out of sync with releases. Two levels up holds for both src/workers (tests)
-// and dist/workers (build) since tsc preserves the layout under rootDir.
-function readPkgVersion() {
-    try {
-        const here = dirname(fileURLToPath(import.meta.url));
-        const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8'));
-        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
-    }
-    catch {
-        return '0.0.0';
-    }
-}
 // Decide how to handle a response based on its content-type. HTML is run through
 // the readability/turndown pipeline; text-ish formats (markdown, plain text,
 // JSON, XML/feeds) are already clean and pass through verbatim; binary formats

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.18.47",
+    "version": "0.18.49",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",