@mjasnikovs/pi-task 0.38.20 → 0.38.22

package/dist/config/reasoning.js

@@ -148,7 +148,40 @@ export const DEFAULT_REASONING_TABLE = {
     // so the `off` arm decodes on sampling tuned for the `on` arm. That is the
     // regime this machine really runs pi-task in, so the result is
     // ecologically valid — it is NOT a clean comparison.
-    research: 'off',
+    //
+    // OVERRIDDEN TO `medium` BY USER DECISION, 2026-08-27. THIS IS NOT A NEW
+    // MEASUREMENT — the trials above are unchanged and still say the arms tied.
+    // What changed is the prior. Rung 3 says "no reason found to pay for
+    // thinking"; it does not say thinking is worthless, and at n=12 an absent
+    // effect and an undetected one look identical.
+    //
+    // WHAT THE SAME LEDGER SAYS ABOUT THE CLOCK, re-read for this decision:
+    // medium is the FASTER arm on the mean, 62.9s vs 105.6s over the 12 paired
+    // stimuli (median 51.7s vs 87.7s), and it is faster on 6 of 12 by 1-265s
+    // while slower on 6 by 0-43s. The mean gap is entirely `off`'s TAIL: off's
+    // two slowest trials are 289s and 367s, medium's slowest is 131s. So the
+    // typical trial is a coin flip worth under a minute and the difference the
+    // arms actually have is in the tail.
+    //
+    // AND THE TAIL IS THE PATHOLOGY THIS CHANGE IS AIMED AT. mx5-n 2026-08-27:
+    // 40.7 of the research phase's 81.4 wall-clock minutes were thrown away on
+    // restarts, all of them in `worker:tooling` and `worker:context` — `files`
+    // and `apis` never restarted once. The worst was 550 tool calls over 20
+    // distinct files in 20 minutes for 25s of useful work.
+    //
+    // THE HONEST LIMIT OF THIS DECISION: no axis in
+    // scripts/live-reasoning-group-ab.ts scores tool-call count or repetition —
+    // the Trial record has no such field and RunWorkerResult exposes no count —
+    // so the ledger CANNOT say whether thinking prevents the wander. It was
+    // never asked. And the ledger's stimuli are the FILES worker, not the two
+    // that looped. Anyone flipping this back should note that the evidence for
+    // `off` is equally silent on the question.
+    //
+    // The structural fix for the wander shipped separately and does not depend
+    // on this cell: StallDetector is now wired into runWorker (it was in phase
+    // children only), so a rotation is killed ~8 calls into its second lap
+    // rather than at the 20-minute ceiling.
+    research: 'medium',
     // NOT MEASURED. DECIDED BY PRIOR, 2026-08-27 — the same prior that carries
     // every rung-3 cell in this table: thinking that buys nothing measurable is
     // not worth its tokens. `off`.
@@ -453,7 +486,40 @@ export const DEFAULT_REASONING_TABLE = {
     // carry the cell. The value is unchanged; only its standing improved, from
     // a stated prior to a measured win. Rescored from the original ledger on 2026-08-25 when the harness
     // moved to a forced two-way verdict; the trials are unchanged.
-    implementation: 'off'
+    //
+    // OVERRIDDEN TO `medium` BY USER DECISION, 2026-08-27, AND THIS ONE
+    // OVERRIDES A MEASUREMENT RATHER THAN A PRIOR. Say so plainly: quality tied
+    // 12/20 in both arms, and the PAIRED clock — the statistic that matches this
+    // design — put `off` ahead in 9 of the 12 specs that pass in both arms,
+    // geometric mean 0.55x, p=0.0166. That is the rung-2 win that WROTE this
+    // cell `off`, and it is not withdrawn by anything measured since.
+    //
+    // WHAT THE DECISION COSTS, from those same numbers: expect implementation
+    // turns to take roughly 1.8x as long, for no measured quality gain. The
+    // quality CI is the widest in the table ([0.39, 0.78] at 12/20), so a real
+    // quality difference either way would have been invisible at n=20 — that is
+    // the room the decision is being made in, and it cuts both ways.
+    //
+    // THE STATED REASON FOR THE OVERRIDE is that the implementation turn was
+    // observed wandering in the same mx5-n run. That observation is NOT in this
+    // repo's evidence: the run's .pi-tasks logs were destroyed before they could
+    // be mined, so no loop was ever counted here and this cell must not claim
+    // one. It is the user's judgement, recorded as such.
+    //
+    // WHAT IS STRUCTURALLY TRUE, and checked: the implementation turn runs in
+    // the USER'S OWN SESSION (see task/implementation-thinking.ts and
+    // task/implementation-turn.ts), not as a child. It therefore has NO
+    // LoopDetector and NO StallDetector — only the per-tool-call command
+    // watchdog and the steer loop's resume cap. The 2026-08-27 fix that wired
+    // StallDetector into runWorker does NOT reach it. So of the groups in this
+    // table, `implementation` is the one where a rotation has no guard at all,
+    // and thinking is the only lever currently pointed at it.
+    //
+    // TO PUT THIS CELL BACK ON EVIDENCE, re-run
+    // scripts/live-implementation-thinking-ab.ts at a larger n. The ledger is
+    // /home/edgars/hub/ab-implab/impl-ledger.jsonl, 40 rows, b10618 — the odd
+    // build out, so a re-run on b10620 is not a replicate of it.
+    implementation: 'medium'
 };
 /**
  * A hand-edited or stale mode must not reach {@link resolveReasoning}'s switch as

package/dist/config/register.js

@@ -1,4 +1,4 @@
-import { SettingsList, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { getKeybindings, 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';
@@ -74,22 +74,43 @@ export const SECTIONS = [
     { key: 'checks', title: 'after each task' },
     { key: 'research', title: 'research' },
     { key: 'reasoning', title: 'reasoning' },
-    { key: 'timeouts', title: 'timeouts' },
     { key: 'unattended', title: 'unattended' },
     { key: 'logging', title: 'logging' },
-    { key: 'extensions', title: 'child extensions' }
+    { key: 'extensions', title: 'child extensions' },
+    // Last on purpose. It is the longest block (a fixed timeout plus one row
+    // per live tool, so it grows with the host) and the least often changed —
+    // in front of `unattended` it pushed every short section off the screen.
+    { key: 'timeouts', title: 'timeouts' }
 ];
 /** Marks a header row, so onChange can ignore one and tests can find them. */
 export const SECTION_ID_PREFIX = 'section:';
-/** An inert titled row. No `values` ⇒ SettingsList's Enter handler no-ops on it. */
+/**
+ * An inert titled row. No `values` ⇒ SettingsList's Enter handler no-ops on it,
+ * and {@link SkipInertRows} steps the cursor straight over it.
+ *
+ * Upper case, and styled muted by {@link makeTheme}, because the dashed
+ * lower-case form it replaces was the same case, colour and weight as the
+ * setting labels underneath it — eight headings that read as nine more rows.
+ */
 function sectionHeader(title) {
     return {
         id: SECTION_ID_PREFIX + title,
-        label: `── ${title} ──`,
+        label: title.toUpperCase(),
         description: '',
         currentValue: ''
     };
 }
+/**
+ * A blank row between two sections.
+ *
+ * `SettingsList` renders exactly one line per item, so the only way to put air
+ * above a heading is to hand it an empty row. It carries the header prefix so
+ * everything that already treats a header as scenery — the inert check, the
+ * cursor skip, the headless rendering — covers it with no second rule.
+ */
+function sectionGap(title) {
+    return { id: `${SECTION_ID_PREFIX}gap:${title}`, label: '', description: '', currentValue: '' };
+}
 /**
  * The shared pair for a boolean setting: shown as on/off, stored as a boolean.
  * Every non-enum row uses this, so a boolean cannot be given a bespoke parser by
@@ -345,7 +366,7 @@ export function applyReasoningLevel(cfg, group, chosen) {
 /** 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;
+const MAX_VISIBLE = 11;
 /**
  * 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
@@ -356,9 +377,19 @@ 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) {
+function makeTheme(theme, isHeader) {
     return {
-        label: (text, selected) => selected ? theme.fg('accent', theme.bold(text)) : theme.fg('text', text),
+        label: (text, selected) => {
+            // Headers are scenery, so they are rendered quieter than the rows
+            // they title rather than louder. `isHeader` is asked by text
+            // because SettingsListTheme only ever sees the padded label —
+            // matching on the text is what keeps the styling in one place
+            // instead of pre-colouring the string back in panelItems, which
+            // has no theme to colour it with.
+            if (isHeader(text))
+                return theme.fg('muted', theme.bold(text));
+            return 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.
@@ -376,6 +407,70 @@ function makeTheme(theme) {
         hint: text => theme.fg('dim', text)
     };
 }
+/** The arrow key SettingsList moves down on, under the default bindings. */
+const DOWN_KEY = '\x1b[B';
+/**
+ * Moves the cursor over the section headers and the blank rows between them.
+ *
+ * Those rows are decoration: they carry no `values`, so Enter already does
+ * nothing on them. Without this they were still stops on the way down — with a
+ * heading AND a blank line per section that is sixteen dead keypresses in a
+ * thirty-row menu, and the panel opens with the cursor parked on a heading that
+ * has no description to show.
+ *
+ * It drives the list through its own public `handleInput` — pressing the very
+ * key the user pressed, N times — rather than reaching for the private
+ * `selectedIndex`. The mirror it keeps cannot drift: with search off and no
+ * submenus, up and down are the only two things that move that index.
+ */
+class SkipInertRows {
+    list;
+    selectable;
+    index = 0;
+    constructor(list, 
+    /** True where a row can be selected, in the list's own order. */
+    selectable) {
+        this.list = list;
+        this.selectable = selectable;
+        // The first row is a header, so the panel would open on it. Only
+        // synthesise the keypress if it is actually bound to "down" — feeding
+        // a key the list ignores would move the mirror and not the cursor.
+        if (!getKeybindings().matches(DOWN_KEY, 'tui.select.down'))
+            return;
+        while (this.index < selectable.length && !selectable[this.index]) {
+            this.list.handleInput(DOWN_KEY);
+            this.index++;
+        }
+    }
+    render(width) {
+        return this.list.render(width);
+    }
+    invalidate() {
+        this.list.invalidate();
+    }
+    handleInput(data) {
+        const kb = getKeybindings();
+        const step = kb.matches(data, 'tui.select.down') ? 1
+            : kb.matches(data, 'tui.select.up') ? -1
+                : 0;
+        if (step === 0) {
+            this.list.handleInput(data);
+            return;
+        }
+        const n = this.selectable.length;
+        let target = this.index;
+        for (let moved = 1; moved <= n; moved++) {
+            target = (target + step + n) % n;
+            if (this.selectable[target]) {
+                for (let i = 0; i < moved; i++)
+                    this.list.handleInput(data);
+                this.index = target;
+                return;
+            }
+        }
+        // Every row is scenery. Nothing to select, so nothing to move.
+    }
+}
 /**
  * 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
@@ -392,8 +487,10 @@ export function createSettingsPanel(items, theme,
  * beside seven rows still claiming `inherit` — which is what it did.
  */
 onChange, onCancel) {
-    const list = new SettingsList(items, MAX_VISIBLE, makeTheme(theme), (id, newValue) => onChange(id, newValue, list), 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));
+    // A row with no `values` is a header or the blank line above one.
+    const headerLabels = new Set(items.filter(i => i.values === undefined).map(i => i.label));
+    const list = new SettingsList(items, MAX_VISIBLE, makeTheme(theme, label => headerLabels.has(label.trimEnd())), (id, newValue) => onChange(id, newValue, list), onCancel);
+    return new BorderedBox(new SkipInertRows(list, items.map(i => (i.values?.length ?? 0) > 0)), 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, tools = []) {
@@ -421,6 +518,8 @@ export function panelItems(cfg, installed, tools = []) {
         // all, so with nothing installed the heading would otherwise sit alone.
         if (rows.length === 0)
             continue;
+        if (out.length > 0)
+            out.push(sectionGap(title));
         out.push(sectionHeader(title), ...rows);
     }
     return out;
@@ -449,8 +548,13 @@ async function handleTaskConfig(_args, ctx, getTools = () => []) {
         // Built from panelItems, not a second hand-written walk of the same
         // tables: the two renderings used to be able to disagree about what a
         // setting said, and a headless run is the one place nobody would notice.
-        const lines = panelItems(cfg, installed, tools).map(i => i.values === undefined ?
-            `[${i.label.replace(/─/g, '').trim()}]`
+        const lines = panelItems(cfg, installed, tools)
+            // The blank rows between sections are there to give the TUI air.
+            // One line of `|`-joined text has none to give, and an empty label
+            // would print as a stray `[]`.
+            .filter(i => i.label !== '')
+            .map(i => i.values === undefined ?
+            `[${i.label.trim()}]`
             : `${i.label.padEnd(22)} ${i.currentValue}`);
         ctx.ui.notify(lines.join('  |  '), 'info');
         return;

package/dist/workers/pi-worker-core.d.ts

@@ -1,5 +1,4 @@
-import { type ContextSnapshot, type SpawnFn } from '../shared/child-process.js';
-import { type LoopHit } from '../task/loop-detector.js';
+import { type ContextSnapshot, type LoopHit, type SpawnFn } from '../shared/child-process.js';
 /**
  * Tool calls that can GROUND an APIS claim — i.e. return content a signature or
  * command could be cited from. `pi-worker-docs` (the primary), `read` and `grep`
@@ -125,6 +124,27 @@ export interface RunWorkerInput {
         threshold?: number;
         pathThreshold?: number;
     } | false;
+    /**
+     * Whole-run progress guard (task/stall-detector.ts). Default ON.
+     *
+     * WHY BOTH. LoopDetector judges ARGUMENTS over a 20-call window, so a child
+     * that rotates through MORE DISTINCT CALLS THAN THE WINDOW HOLDS is invisible
+     * to it — every key occurs once per window and the count never reaches the
+     * threshold. Measured: mx5-n 2026-08-27, worker:tooling made 550 calls over
+     * exactly 20 distinct files, ~36 reads each, and neither the exact rule nor
+     * the path rule ever tripped. It died 20 minutes later on the absolute
+     * progress ceiling, having done 25s of useful work.
+     *
+     * StallDetector judges RESULTS, which a rotating reader cannot vary. It was
+     * written for exactly this class and was wired only into phase children
+     * (task/child-runner.ts) until this option existed.
+     *
+     * Pass `false` to disable, or override the thresholds (tests, harnesses).
+     */
+    stallGuard?: {
+        limit?: number;
+        churnFactor?: number;
+    } | false;
     /**
      * Dead-backend stall guard override. Default ON: no output for
      * STALL_AFTER_MS → probe the model endpoints pi is configured with →

package/dist/workers/pi-worker-core.js

@@ -4,6 +4,7 @@ import { CommandWatchdog, commandTimeoutHint, realTimerDeps } from '../shared/co
 import { isGroundingRetrieval as isGrounding, workerChannel } from './worker-channels.js';
 import { childBaseArgs } from '../shared/child-extensions.js';
 import { LoopDetector } from '../task/loop-detector.js';
+import { StallDetector, formatStallHint } from '../task/stall-detector.js';
 import { LOOP_WINDOW, LOOP_THRESHOLD, MAX_LOOP_RESTARTS, formatLoopHint, isConnectionError, connectionRetryBackoffMs } from '../task/child-runner.js';
 import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
 import { discoverModelEndpoints, probeModelEndpoints } from '../shared/model-endpoint.js';
@@ -282,9 +283,16 @@ const RESTART_RULES = [
         // re-spawn avoids it. Bounded by the shared restart budget.
         reason: 'loop',
         detect: s => s.loopHit && s.restartBudgetSpent < MAX_LOOP_RESTARTS ?
-            { detail: `${s.loopHit.call.name} ×${s.loopHit.count}/${s.loopHit.windowSize}` }
+            {
+                // A stall hit carries no meaningful windowSize (rule 1 sets
+                // it to 0), so printing the loop shape would misname why the
+                // attempt died.
+                detail: s.loopHit.stall ?
+                    `${s.loopHit.call.name} ${s.loopHit.stall} ×${s.loopHit.count}`
+                    : `${s.loopHit.call.name} ×${s.loopHit.count}/${s.loopHit.windowSize}`
+            }
             : null,
-        hint: s => formatLoopHint(s.loopHit),
+        hint: s => s.loopHit.stall ? formatStallHint(s.loopHit.stall) : formatLoopHint(s.loopHit),
         counters: { shared: true }
     },
     {
@@ -499,6 +507,16 @@ export async function runWorker(input) {
                 const threshold = input.loop?.threshold ?? LOOP_THRESHOLD;
                 return new LoopDetector(window, threshold, input.loop?.pathThreshold ?? threshold);
             })();
+        // Reset EACH attempt, like the loop detector: a restart discards the
+        // previous attempt's calls along with its text, so a fresh child must not
+        // inherit a dead streak it did not earn.
+        const stallDetector = input.stallGuard === false ?
+            null
+            : new StallDetector(input.stallGuard?.limit, input.stallGuard?.churnFactor);
+        // Arm the churn rule BEFORE the first tool call. pi's stream carries no
+        // context event (issue #16), so waiting for one leaves the rule
+        // permanently disarmed. The parent knows the window at spawn time.
+        stallDetector?.noteContext(input.contextWindow ?? 0);
         // Capture the hit the detector reports (it also returns it to the unified
         // runner, which kills the child on a hit). Without capturing it here the
         // SIGTERM that kill produces would surface as a bare non-zero exit the
@@ -543,9 +561,11 @@ export async function runWorker(input) {
                     }
                     if (isGrounding(call.name))
                         groundingRetrievalCount++;
-                    if (!loopDetector)
-                        return null;
-                    const hit = loopDetector.record(call);
+                    // Loop detector first: it names the offending call and its
+                    // hint is the more specific one. The stall detector is the
+                    // backstop for the thrash shapes a 20-call argument window
+                    // cannot see.
+                    const hit = loopDetector?.record(call) ?? stallDetector?.record(call) ?? null;
                     if (hit && !loopHit)
                         loopHit = hit;
                     return hit;
@@ -565,9 +585,15 @@ export async function runWorker(input) {
                 onToolResult: r => {
                     timeout.progress();
                     cmdWatch?.onEnd(r.toolCallId);
+                    // The RESULT is what entered the child's context, so it —
+                    // not the arguments — decides whether it learned anything.
+                    stallDetector?.noteResult(r.text, r.isError);
                     input.onToolResult?.(r);
                 },
-                onContextUsage: input.onContextUsage,
+                onContextUsage: snapshot => {
+                    stallDetector?.noteContext(snapshot.contextWindow);
+                    input.onContextUsage?.(snapshot);
+                },
                 ...(input.contextWindow && input.contextWindow > 0 ?
                     { contextWindow: input.contextWindow }
                     : {})

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.38.20",
+    "version": "0.38.22",
     "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",