@mjasnikovs/pi-task 0.38.21 → 0.38.23

package/dist/config/reasoning.d.ts

@@ -31,7 +31,16 @@ import type { PiTaskConfig } from './config.js';
  * thinking, while two that reach the model by different code paths (`refine` via
  * runPhaseChild, `compress-label` via the same) want the same.
  *
- * - `research`     the four research workers, plus the ad-hoc `pi-worker` tool
+ * - `research`     the ad-hoc `pi-worker` subagent tool, and the FALLBACK the four
+ *                  research workers use when their own cell is unset
+ * - `research:files` / `research:apis` / `research:context` / `research:tooling`
+ *                  one cell per research worker. They are FOUR CELLS, not one,
+ *                  because the four wander differently: over mx5-n 2026-08-27
+ *                  every one of the 40.7 wasted research minutes was a restart
+ *                  in `tooling` or `context`, and `files` and `apis` never
+ *                  restarted once. A single `research` cell cannot be set to
+ *                  pay for thinking where it is needed without also paying for
+ *                  it where it measurably is not.
  * - `phase`        refine, verify-tooling, grill, compose, critique, compress-label
  * - `planning`     /task-auto's clarify / decompose / extract children
  * - `plan`         /task-plan's question and answer children
@@ -39,7 +48,7 @@ import type { PiTaskConfig } from './config.js';
  * - `extraction`   the --no-tools focused docs/fetch extractors
  * - `implementation` the host-session turn that writes the code (not a child)
  */
-export type ReasoningGroup = 'research' | 'phase' | 'planning' | 'plan' | 'gate' | 'extraction' | 'implementation';
+export type ReasoningGroup = 'research' | 'research:files' | 'research:apis' | 'research:context' | 'research:tooling' | 'phase' | 'planning' | 'plan' | 'gate' | 'extraction' | 'implementation';
 export declare const REASONING_GROUPS: readonly ReasoningGroup[];
 /**
  * The four profiles offered by /task-config.
@@ -132,6 +141,14 @@ export declare const DEFAULT_REASONING_TABLE: Readonly<Record<ReasoningGroup, Gr
  * would see "custom" in the file and the default table in behaviour.
  */
 export declare function sanitizeReasoningMode(value: unknown): ReasoningMode;
+/**
+ * The group each research worker reads its level from, keyed by the section
+ * heading its output is assembled under (task/phases.ts `workerSpecs`).
+ *
+ * Exported so the wiring is one table rather than four string literals spread
+ * through the phase code, and so a test can assert every value is a real group.
+ */
+export declare const RESEARCH_WORKER_GROUPS: Readonly<Record<string, ReasoningGroup>>;
 /**
  * Always returns a COMPLETE record, never a partial one.
  *

package/dist/config/reasoning.js

@@ -1,5 +1,9 @@
 export const REASONING_GROUPS = [
     'research',
+    'research:files',
+    'research:apis',
+    'research:context',
+    'research:tooling',
     'phase',
     'planning',
     'plan',
@@ -148,7 +152,214 @@ 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',
+    // ── THE FOUR RESEARCH WORKERS, SPLIT OUT OF `research` 2026-08-28 ──
+    //
+    // WHY THE SPLIT EXISTS, from `research`'s own evidence. The override to
+    // `medium` above was aimed at ONE pathology — the restart tail — and that
+    // tail is not spread evenly. mx5-n 2026-08-27: 40.7 of the research phase's
+    // 81.4 wall-clock minutes were lost to restarts, ALL of them in
+    // `worker:tooling` and `worker:context`; `worker:files` and `worker:apis`
+    // never restarted once. With one cell, paying for thinking in the two that
+    // wander means paying for it in the two that do not.
+    //
+    // ── research:files — MEASURED, `off`. WRITTEN 2026-08-28 ──
+    //
+    // A/B 2026-08-26, Qwen3.8-27B-NVFP4-MTP-VERY-HIGH.gguf (llama.cpp
+    // b10620-0f3b51e03), scripts/live-reasoning-group-ab.ts, n=12/arm over 12
+    // distinct mx5 tasks. off 10/12 vs medium 11/12 (p=1.0000); clock PAIRED
+    // over the 10 usable pairs p=0.7090, mean off 79.4s vs medium 59.3s.
+    // off 95% CI [0.55, 0.95]. RUNG 3 — a DECISION, not a finding.
+    //
+    // THIS IS NOT A NEW RUN. It is ledger-research.jsonl, rescored under the
+    // group's new name:
+    //
+    //   AB_CORPUS=/home/edgars/hub/ab-grouplab/mx5-copy bun run \
+    //     scripts/rescore-reasoning-ledger.ts \
+    //     /home/edgars/hub/ab-grouplab/ledger-research.jsonl research:files --from-text
+    //
+    // That ledger was ALWAYS a FILES worker — `child: 'worker:files'`, prompt
+    // `RESEARCH_FILES_PROMPT`, run in each task's own before-tree — so the split
+    // did not strand it, it named it. The axis is the CONJUNCTION: every path
+    // named is real AND every pre-existing file the task edited is named. The
+    // full derivation, the stimulus screen, the parser fix and the confound sit
+    // on the `research` cell above; they are that ledger's, and this is that
+    // ledger.
+    //
+    // WHY THIS CELL DOES NOT FOLLOW `research`'s OVERRIDE. That override was
+    // aimed at the restart tail, and the tail is not here: `worker:files` never
+    // restarted once. The reason for paying does not apply to this worker, and
+    // its own ledger says the arms tied.
+    'research:files': 'off',
+    // NOT MEASURED. DECIDED BY PRIOR: a worker with no trial of its own keeps
+    // whatever `research` was decided to run at. No trial in this repo has ever
+    // run apis, context or tooling as its own arm, so a cell here that differed
+    // from `research` would be intuition wearing the authority of a default.
+    //
+    // AND AN AXIS IS THE HARD PART, not the GPU. Two candidates were screened
+    // offline and DIED there — scripts/research-worker-axes-step0.ts, no model,
+    // no GPU. For APIS: "every dotted symbol named is present in the tree"
+    // scores the recorded answers 28/28 tasks and 81/81 items. SATURATED, and
+    // loose with it — the check greps the symbol's LAST SEGMENT, so
+    // `Hono.c.json` passes on the word `json`. Tightening it has nothing to
+    // bite on, because APIS names are model-composed pseudo-symbols
+    // (`Hono.c.var`, `UUID regex`); that is the same wall
+    // [[apis-contract-stage3-refuted]] hit from the other side.
+    // TO REPLACE THIS WITH A MEASUREMENT, the axis must be an EXECUTION or a
+    // production adjudication, the way gate's and planning's are — not a
+    // property of the text.
+    //
+    // A COST RUN WAS DONE ANYWAY, 2026-08-28, and it found nothing to act on.
+    // n=20/arm on the same corpus and trees, production's tools, extensions,
+    // search hint and the task's own recorded FILES map: off 19/20 answered vs
+    // medium 20/20, and the PAIRED clock over 19 stimuli is off 127.2s vs
+    // medium 144.4s, p=0.5262. So thinking is neither better nor cheaper here
+    // by anything this run can see, and there is no cost argument for moving
+    // the cell either way. Ledger: ledger-research-apis.jsonl.
+    // THAT RUN CANNOT WRITE THIS CELL. Its axis is TERMINATION — "did it answer
+    // at all" — so its `off [rung 3]` line is the standing prior speaking with
+    // no quality reading behind it. See README-research-cost-runs.txt.
+    // ITS BUILD IS b10665-ca3d5a3e1, not the b10620-0f3b51e03 every other cell
+    // was measured on: llama.cpp was rebuilt mid-session. Internally paired, so
+    // off-vs-medium is fair within it; its SECONDS are not comparable to the
+    // files or tooling ledgers.
+    'research:apis': 'medium',
+    // NOT MEASURED. DECIDED BY PRIOR — see the block above `research:apis`.
+    // Its candidate axis died offline too: "every backticked project path in a
+    // CONTEXT bullet exists in the tree" scores the recorded answers 6/53 tasks
+    // and 213/391 items. THE CHECK LOSES, on exactly the residue the phase
+    // path-axis audit catalogued — npm specifiers (`@hono/zod-validator`),
+    // import paths (`hono/cookie`, `../server/auth`), bare filenames
+    // (`schema.ts`) and `src/` prefix elision.
+    // TO REPLACE THIS WITH A MEASUREMENT, note that this worker is one of the
+    // two the restart tail lives in, so the honest axis is the wander itself —
+    // and no Trial field records a tool-call count today.
+    //
+    // A COST RUN WAS DONE ANYWAY, 2026-08-28, n=20/arm, production's `read,grep`
+    // and no extensions. It found no clock difference — medians 81.2s vs 80.8s,
+    // paired p=0.8594 over 16 stimuli — but it did see the wander directly:
+    //
+    //     died in a loop        off 3/20  vs  medium 0/20   p=0.2308
+    //     emitted bullets       off 17/20 vs  medium 20/20  p=0.2308
+    //
+    // Neither reaches significance at n=20, and the second is TERMINATION, not
+    // quality. But this is the first time the restart tail has appeared INSIDE
+    // a measured run rather than in a production log, and it appeared only in
+    // the `off` arm. off's higher MEAN (97.8s vs 69.3s) is those three deaths,
+    // not slower work. THIS RUN CANNOT WRITE THIS CELL either: an underpowered
+    // termination signal is not a measurement, and its `off [rung 3]` verdict
+    // line is the prior, not a reading. THE CELL IS UNCHANGED. Ledger: ledger-research-context.jsonl,
+    // README-research-cost-runs.txt, build b10665-ca3d5a3e1.
+    //
+    // INSTRUMENT NOTE, because that run ABSTAINED first with 40 good answers
+    // already stored. It scored CONTEXT with `hasAnswerContent` — the FILES
+    // `name<gap>description` shape — and this worker emits a BULLET list of
+    // prose sentences, which `isEntryLine` rejects for ending in a full stop.
+    // Both arms read 0/20. Fixed by `contextEmittedBullets` and the stored
+    // trials rescored with no GPU. Fourth instance of
+    // [[ab-scorer-must-match-the-real-prompt]] in one harness.
+    // AND THE REPLACEMENT WAS WRONG BY ONE, found in review the same day: it
+    // asked for >=2 bullets where production's `classifyContextSilence` calls
+    // >=1 PRODUCTIVE, so a one-bullet answer production accepts read UNUSABLE
+    // in both arms. `countBullets` — production's own function, called not
+    // restated — moved 37/40 stored trials and the emitted-bullets line above
+    // from off 16/20 to off 17/20. The verdict, the cell and the clock are
+    // unchanged: still an underpowered termination signal, still a prior.
+    'research:context': 'medium',
+    // ── research:tooling — MEASURED, `medium`. RUNG 1. WRITTEN 2026-08-28 ──
+    //
+    // A/B 2026-08-28, Qwen3.8-27B-NVFP4-MTP-VERY-HIGH.gguf (llama.cpp
+    // b10620-0f3b51e03), scripts/live-reasoning-group-ab.ts, n=20/arm over 20
+    // distinct mx5 tasks, one rep each so the clock can pair.
+    //
+    //     every command runs   off 13/20  vs  medium 20/20   p=0.0083
+    //     wall clock (paired)  off 49.5s  vs  medium 15.9s   p=0.0400
+    //     off 95% CI [0.43, 0.82].  Ledger: ledger-research-tooling.jsonl.
+    //
+    // RUNG 1 — quality decided it, and this is only the SECOND cell in the table
+    // a quality axis has ever decided. THE FIRST WAS extraction, which went the
+    // other way. Note there is no trade here: medium is both better AND 3.1x
+    // faster, so the sampler caveat below cannot be what produced it.
+    //
+    // THE AXIS: every command the checker can adjudicate must RESOLVE in the
+    // tree the worker inspected (scripts/reasoning-ab-tooling-truth.ts). Not a
+    // property of the text — the same kind of truth as gate's executed VERIFY,
+    // which is why it lives where four `phase` text axes died. `unknown` is a
+    // first-class answer and is scored neither way: three of the four command
+    // shapes can only return `real` or `unknown`, because an undeclared binary
+    // may still be on PATH and `bun test` resolves through the runtime.
+    //
+    // OFF'S FAILURE IS ONE CLASS, AUDITED ROW BY ROW. All seven name a
+    // dev-server command against `src/server/index.ts` — a file that exists in
+    // NEITHER the before-tree nor the after-tree of any of those seven tasks;
+    // it first appears around TASK_0057. The worker's own prompt says "If a
+    // tool isn't present in the repo, omit it — don't invent." Medium omits it.
+    //
+    // THE CHECKER WAS WRONG THREE TIMES FIRST, and all three are pinned in
+    // reasoning-ab-tooling-truth.test.ts:
+    //   1. `bun run <file.ts>` is a file invocation, not a script lookup.
+    //      Caught offline; four of twelve reported failures were this bug.
+    //   2. `bun run <installed-bin>` falls back to `node_modules/.bin`.
+    //      VERIFIED BY EXECUTION: `bun run tsc --version` → `Version 6.0.3`,
+    //      exit 0; `bun run dev` → `error: Script not found "dev"`, exit 1.
+    //      Caught LIVE at trial 19. It cost two MEDIUM trials, and BOTH were
+    //      recovered by rescoring the stored text with no GPU — which is the
+    //      whole reason the ledger stores `output`.
+    //   3. `-f` is a compose file only when a compose token precedes it, and
+    //      `<runner> run <arg>` must be read for EVERY segment of a compound
+    //      line, not the first. Found in review: `curl -f <url>` and
+    //      `git clean -f -d` scored as invented paths (strict), while
+    //      `bun run lint && bun run dev` scored `real` on `lint` alone and let
+    //      `dev` — the exact class this cell turns on — through (LOOSE, and the
+    //      harder half to spot). Caught after the run; rescoring the stored text
+    //      moved 2/40 trials and left every number on this cell IDENTICAL.
+    // No fix moved the offline ceiling (32/45 tasks, 102/118 commands, before
+    // and after all three), so none loosened the check against known-good work.
+    //
+    // WHAT THIS CELL DOES NOT SAY. Medium sits at 20/20, so the axis has no
+    // headroom ABOVE it: a future run could not show medium getting worse. And
+    // the axis does not score the restart tail this worker is known for — no
+    // Trial field records a tool-call count — so "medium is better here" is
+    // about the ANSWER, not about the wander.
+    //
+    // REPRODUCE: `AB_SPECS=research:tooling:20 /abrun/run-group.sh`, then
+    //   AB_CORPUS=.../mx5-copy bun run scripts/rescore-reasoning-ledger.ts \
+    //     /home/edgars/hub/ab-grouplab/ledger-research-tooling.jsonl \
+    //     research:tooling --from-text
+    'research:tooling': '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,6 +664,42 @@ 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.
+    //
+    // OVERRIDE WITHDRAWN 2026-08-28; THE CELL IS `off` AGAIN, ON ITS OWN
+    // MEASUREMENT. Between 2026-08-27 and 2026-08-28 this cell read `medium` by
+    // user decision, overriding the rung-2 result above rather than a prior. The
+    // decision's stated reason was an implementation turn observed wandering in
+    // the mx5-n run, and the cell recorded honestly that the run's .pi-tasks logs
+    // had been destroyed before anyone could count the loop.
+    //
+    // A SECOND mx5-n RUN KEPT ITS LOGS, and they refute the reason. The run
+    // executed 10 tasks in 9h22 with this cell at `medium` — thinking ON for
+    // every implementation turn — and TASK_0004 wandered anyway: 167 assistant
+    // turns, 192 tool calls, 45 files and 2,355 lines committed against a
+    // one-file spec, and its own deliverable (src/server/migrate.ts) never
+    // written; it arrived four tasks later. Two single responses in that turn
+    // were 18,297 and 23,568 output tokens. Thinking did not prevent the
+    // rotation, so the lever the override was reaching for is not this one.
+    // Measured over the run's 15 implementation sessions: 441,399 output tokens,
+    // of which 59.3% by character was thinking (1,314,790 thinking chars vs
+    // 902,034 text chars).
+    //
+    // WHAT IS STRUCTURALLY TRUE, and still 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 superviseImplementation's MAX_COMPACTION_RESUMES, which the
+    // runaway above came nowhere near (it took 2 compactions of an allowed 20).
+    // So `implementation` remains the one group in this table where a rotation
+    // has no guard at all. That is an argument for GIVING it a guard, not for
+    // paying 1.8x in thinking that has now been observed not to guard it.
+    //
+    // THE CELL IS STILL RUNG 2 AND STILL THE WIDEST CI IN THE TABLE ([0.39,
+    // 0.78] at 12/20), so it is carried by the clock, not by quality. Nothing
+    // measured since has withdrawn the paired-clock win. To put it on more
+    // 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.
     implementation: 'off'
 };
 /**
@@ -463,6 +710,29 @@ export const DEFAULT_REASONING_TABLE = {
 export function sanitizeReasoningMode(value) {
     return REASONING_MODES.includes(value) ? value : 'default';
 }
+/**
+ * The group each research worker reads its level from, keyed by the section
+ * heading its output is assembled under (task/phases.ts `workerSpecs`).
+ *
+ * Exported so the wiring is one table rather than four string literals spread
+ * through the phase code, and so a test can assert every value is a real group.
+ */
+export const RESEARCH_WORKER_GROUPS = {
+    FILES: 'research:files',
+    APIS: 'research:apis',
+    CONTEXT: 'research:context',
+    TOOLING: 'research:tooling'
+};
+/**
+ * For a `research:*` group, the group a stored config falls back to when its own
+ * key is missing. Every other group maps to `undefined`.
+ */
+const RESEARCH_SUBGROUP_PARENT = {
+    'research:files': 'research',
+    'research:apis': 'research',
+    'research:context': 'research',
+    'research:tooling': 'research'
+};
 /**
  * Always returns a COMPLETE record, never a partial one.
  *
@@ -475,13 +745,33 @@ export function sanitizeReasoningLevels(value) {
     const stored = typeof value === 'object' && value !== null && !Array.isArray(value) ?
         value
         : {};
+    const valid = (v) => REASONING_SETTINGS.includes(v);
     const out = {};
     for (const group of REASONING_GROUPS) {
         const stored_ = stored[group];
+        if (valid(stored_)) {
+            out[group] = stored_;
+            continue;
+        }
+        // A `research:*` key absent from the file falls back to the user's own
+        // `research`, NOT to the default table. This is the migration path: a
+        // config written before the split carries one `research` level and
+        // nothing else, and filling the four sub-cells from the table would
+        // silently overrule a choice the user had already made — the four
+        // workers are exactly the children that `research` used to set.
+        //
+        // IT CANNOT TELL A CHOICE FROM A SEED, and that is accepted. Leaving
+        // `default`/`on`/`off` for ANY reason makes `applyReasoningLevel` seed
+        // every group from `resolveReasoning`, so a user who only ever nudged
+        // `gate` still has a `research` on disk they never picked. Inheriting
+        // it pins the four workers to the old default and the measured
+        // `research:files: 'off'` never reaches them. That is what CUSTOM MODE
+        // MEANS: a frozen table, not a subscription to later measurements — the
+        // same is true of every other group in the file. `default` mode is
+        // where a new reading takes effect, and it takes effect there at once.
+        const parent = RESEARCH_SUBGROUP_PARENT[group];
         out[group] =
-            REASONING_SETTINGS.includes(stored_) ?
-                stored_
-                : DEFAULT_REASONING_TABLE[group];
+            parent && valid(stored[parent]) ? stored[parent] : DEFAULT_REASONING_TABLE[group];
     }
     return out;
 }
@@ -515,8 +805,16 @@ export function thinkingArgs(setting) {
 }
 /** One honest sentence per group, for the /task-config rows. */
 export const REASONING_GROUP_HELP = {
-    research: 'The four research workers that read the codebase before a spec is written, '
-        + 'and the pi-worker subagent tool. Read-only exploration loops.',
+    research: 'The pi-worker subagent tool, and the fallback for any research worker below '
+        + 'whose own level is unset. Read-only exploration loops.',
+    'research:files': 'Research worker 1 of 4: maps which files the task will touch. Read-heavy. '
+        + 'Measured: the two arms tie, so it runs without thinking.',
+    'research:apis': 'Research worker 2 of 4: the symbols and signatures the task must call. '
+        + 'Read-heavy, docs- and search-capable.',
+    'research:context': 'Research worker 3 of 4: how the project is put together. One of the two that '
+        + 'burned wall-clock on restarts in the last full run.',
+    'research:tooling': 'Research worker 4 of 4: the commands that build, test and run the project. '
+        + 'Measured: thinking wins on both quality and speed.',
     phase: 'Refining your request, generating and answering the clarifying questions, '
         + 'writing the spec, and critiquing it.',
     planning: "/task-auto's planners: splitting a design document into tasks and extracting "

package/dist/config/register.d.ts

@@ -120,13 +120,25 @@ export declare function toolItems(tools: readonly GuardableTool[], exempt: reado
 }[];
 /** Apply a per-tool watchdog toggle to the exemption list (idempotent both ways). */
 export declare function applyToolToggle(exempt: readonly string[], toolName: string, watched: boolean): string[];
-export declare function reasoningItems(cfg: PiTaskConfig): {
-    id: string;
-    label: string;
-    description: string;
-    currentValue: string;
-    values: string[];
-}[];
+/**
+ * The label for one `think:` row.
+ *
+ * A group whose name carries a colon is a CHILD of the group before the colon —
+ * `research:files` is one of the four workers `research` fans out to. Rendered
+ * flat, those four read as four more peers of `research`, and the menu's one
+ * genuine hierarchy is invisible: the four are the only rows in the list whose
+ * parent is also a row.
+ *
+ * So a child is drawn as a tree branch under its parent and loses the repeated
+ * `think: research:` prefix, which is 15 columns of the same text on four
+ * consecutive lines. `└─` on the last child, `├─` on the rest, decided from the
+ * group's position in {@link REASONING_GROUPS} rather than a hand-kept list —
+ * adding a fifth worker moves the corner on its own.
+ *
+ * Leading spaces survive: SettingsList pads the label right, never trims it.
+ */
+export declare function reasoningRowLabel(group: ReasoningGroup): string;
+export declare function reasoningItems(cfg: PiTaskConfig): PanelItem[];
 /**
  * Apply one group row's new value.
  *
@@ -167,6 +179,14 @@ export type PanelItem = {
      * — the header does not need its own branch anywhere.
      */
     values?: string[];
+    /**
+     * What the headless one-line rendering calls this row, when `label` reads
+     * only in the panel. A tree branch means nothing on a line of `|`-joined
+     * rows: `├─ files` there names no parent, where `think: research:files`
+     * does. Set by the reasoning rows; every other row leaves it off and its
+     * `label` is used.
+     */
+    headlessLabel?: string;
 };
 /**
  * Builds the framed settings panel. Split out of the command handler so the

package/dist/config/register.js

@@ -314,10 +314,36 @@ export function applyToolToggle(exempt, toolName, watched) {
  *    whole point of having measured it.
  */
 const REASON_ID_PREFIX = 'reason:';
+/**
+ * The label for one `think:` row.
+ *
+ * A group whose name carries a colon is a CHILD of the group before the colon —
+ * `research:files` is one of the four workers `research` fans out to. Rendered
+ * flat, those four read as four more peers of `research`, and the menu's one
+ * genuine hierarchy is invisible: the four are the only rows in the list whose
+ * parent is also a row.
+ *
+ * So a child is drawn as a tree branch under its parent and loses the repeated
+ * `think: research:` prefix, which is 15 columns of the same text on four
+ * consecutive lines. `└─` on the last child, `├─` on the rest, decided from the
+ * group's position in {@link REASONING_GROUPS} rather than a hand-kept list —
+ * adding a fifth worker moves the corner on its own.
+ *
+ * Leading spaces survive: SettingsList pads the label right, never trims it.
+ */
+export function reasoningRowLabel(group) {
+    const colon = group.indexOf(':');
+    if (colon < 0)
+        return `think: ${group}`;
+    const parent = group.slice(0, colon);
+    const nextIsSibling = REASONING_GROUPS[REASONING_GROUPS.indexOf(group) + 1]?.startsWith(`${parent}:`);
+    return `   ${nextIsSibling ? '├─' : '└─'} ${group.slice(colon + 1)}`;
+}
 export function reasoningItems(cfg) {
     return REASONING_GROUPS.map(group => ({
         id: REASON_ID_PREFIX + group,
-        label: `think: ${group}`,
+        label: reasoningRowLabel(group),
+        headlessLabel: `think: ${group}`,
         description: REASONING_GROUP_HELP[group],
         // The EFFECTIVE level, not cfg.reasoningLevels[group]: in default/on/off
         // the stored table is not what runs, and a row that shows a value the
@@ -555,7 +581,7 @@ async function handleTaskConfig(_args, ctx, getTools = () => []) {
             .filter(i => i.label !== '')
             .map(i => i.values === undefined ?
             `[${i.label.trim()}]`
-            : `${i.label.padEnd(22)} ${i.currentValue}`);
+            : `${(i.headlessLabel ?? i.label).padEnd(22)} ${i.currentValue}`);
         ctx.ui.notify(lines.join('  |  '), 'info');
         return;
     }

package/dist/task/phases.d.ts

@@ -123,6 +123,22 @@ export declare function resolveOwnedFreezeForThisTask(deps: PhaseDeps, spec: str
 export declare function claimOwnedFreezeForThisTask(deps: PhaseDeps, refined: string): Promise<void>;
 export declare const phaseRefine: (deps: PhaseDeps, raw: string, planContext?: string) => Promise<string>;
 export declare function phaseVerifyTooling(deps: PhaseDeps, research: string): Promise<string>;
+/**
+ * The worker channels the APIS research worker is given.
+ *
+ * `pi-worker-search` + `pi-worker-fetch` ride along only when the configured
+ * engine is usable (a keyless engine always is; brave needs its key). A tool
+ * without a key just errors, and a weak model burns calls on it — while search
+ * being ABSENT was structural in the other direction: three consecutive audited
+ * runs made 0 search calls because the child literally did not have the tool.
+ *
+ * Both halves of "given a channel" — the tools string and the `-e` path — come
+ * from the same rows, so they cannot disagree.
+ */
+export declare function apisWorkerChannels(): {
+    tools: string;
+    extensions: string[];
+};
 /**
  * Is live web search configured for this process? The keyless providers (exa,
  * ddg) always are; only brave needs its API key.

package/dist/task/phases.js

@@ -43,6 +43,7 @@ import { SessionUI } from '../remote/bridge.js';
 import { isYoloMode, yoloPickAutoAnswer } from './yolo.js';
 import { QaTranscript, GRILL_QA_POLICY } from './qa-transcript.js';
 import { groupThinkingArgs } from '../config/reasoning-args.js';
+import { RESEARCH_WORKER_GROUPS } from '../config/reasoning.js';
 // ─── Re-export constants from their home modules ────────────────────────────
 export { MAX_GRILL_QUESTIONS };
 // ─── Tooling helpers ─────────────────────────────────────────────────────────
@@ -326,7 +327,7 @@ export async function phaseVerifyTooling(deps, research) {
  * Both halves of "given a channel" — the tools string and the `-e` path — come
  * from the same rows, so they cannot disagree.
  */
-function apisWorkerChannels() {
+export function apisWorkerChannels() {
     return channelSet([
         'pi-worker-docs',
         ...(searchConfigured() ? ['pi-worker-search', 'pi-worker-fetch'] : [])
@@ -901,11 +902,18 @@ export async function phaseResearch(deps, refined) {
             cwd: deps.cwd,
             signal: deps.signal,
             spawn: deps.spawn,
-            // All four research workers share one group: they are the same
-            // job (read-only exploration of the repo) run over four
-            // questions, and a table that could set them apart would be
-            // four cells nobody has the trials to fill.
-            thinking: groupThinkingArgs('research'),
+            // ONE CELL PER WORKER since 2026-08-28. They used to share
+            // the `research` cell on the grounds that they are the same
+            // job over four questions; the run logs disagree. All 40.7
+            // wasted research minutes in mx5-n were restarts in
+            // `tooling` and `context`, and `files`/`apis` never
+            // restarted — so the level that pays for one pair is being
+            // paid for the other. THE FOUR CELLS DO NOT SHIP IDENTICAL:
+            // `research:files` is `off` on a measured tie while the
+            // other three are `medium`, so this line changes what the
+            // FILES worker runs at for every default-mode user. The
+            // evidence is on each cell in reasoning.ts.
+            thinking: groupThinkingArgs(RESEARCH_WORKER_GROUPS[spec.section] ?? 'research'),
             ...(spec.tools ? { tools: spec.tools } : {}),
             ...(spec.extensions ? { extensions: spec.extensions } : {}),
             // 5B SCALE arm — null unless both env vars are set. Only the

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.21",
+    "version": "0.38.23",
     "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",