@mjasnikovs/pi-task 0.38.18 → 0.38.20

package/dist/task/orchestrator.d.ts

@@ -20,6 +20,7 @@ import { type WidgetState } from './widget.js';
 import { type RunTaskFn } from './gate-deps.js';
 import { type GateDeps } from './task-gates.js';
 import { type PhaseDeps } from './child-runner.js';
+import { type ThinkingControl } from './implementation-thinking.js';
 import { type RunEnd } from './run-end.js';
 import type { SpawnFn } from '../shared/child-process.js';
 import { type SuperviseOptions } from './implementation-turn.js';
@@ -166,6 +167,12 @@ export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId'
      * internal per-task runs, which must stay silent. Default false.
      */
     notifyFinish?: boolean;
+    /**
+     * How the implementation turn's thinking level is read and written. Defaults
+     * to the live pi session; injected by tests, which must be able to assert
+     * the restore without a real session to restore.
+     */
+    thinkingControl?: ThinkingControl;
 }
 export interface RunSingleTaskResult {
     taskId: string;

package/dist/task/orchestrator.js

@@ -36,6 +36,7 @@ import { findDeliveryPhantoms, formatApiOverrideBanner } from '../workers/phanto
 import { titleForDisplay } from './parsers.js';
 import { USER_CANCELLED } from './child-runner.js';
 import { cancelCheckpoint } from './cancel-points.js';
+import { holdImplementationThinking } from './implementation-thinking.js';
 import { rearmCancelListener } from './cancel-input.js';
 import { takeHeldInput } from './mid-run-input.js';
 import { withRun, announceTerminal } from './run-bracket.js';
@@ -57,6 +58,21 @@ function clearActiveTask(runner) {
 }
 // Captured from the factory so command handlers can call pi.sendUserMessage.
 let piApi = null;
+/**
+ * The live session's thinking level, as a {@link ThinkingControl}.
+ *
+ * Goes through `piApi` rather than the command ctx because
+ * `ExtensionCommandContext` exposes `thinkingLevel` READ-ONLY; the setter lives
+ * on the extension API. Before `registerTask(pi)` has run there is nothing to
+ * control, so this degrades to a no-op pair rather than throwing — a task that
+ * cannot move the level should still run.
+ */
+function piThinkingControl() {
+    const api = piApi;
+    if (!api)
+        return { get: () => 'off', set: () => { } };
+    return { get: () => api.getThinkingLevel(), set: level => api.setThinkingLevel(level) };
+}
 // ─── TaskRunner class ────────────────────────────────────────────────────────
 /** Encapsulates the full lifecycle of a single pi-task run. */
 export class TaskRunner {
@@ -122,6 +138,10 @@ export class TaskRunner {
             onChildOutput: (line) => {
                 this._widgetState.lastLine = line;
             },
+            // Handed DOWN so the child's own snapshot carries a window and the
+            // StallDetector's churn rule can arm; resolveContextUsage below stays
+            // as the fallback for a child that still reports none (issue #16).
+            contextWindow: parentContextWindow,
             onContextUsage: snapshot => {
                 this._widgetState.contextUsage = resolveContextUsage(snapshot, this._widgetState.contextUsage, parentContextWindow);
             },
@@ -432,20 +452,32 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                 rawPrompt,
                 resumeId: opts.resumeId,
                 sendSpec: async (spec) => {
-                    // Queue-or-run: never throws, whatever else is on the session (issue #8).
-                    await newCtx.sendUserMessage(spec, { deliverAs: 'followUp' });
-                    if (opts.waitForImplementation) {
-                        await newCtx.waitForIdle();
-                        // A threshold auto-compaction parks the turn at idle WITHOUT
-                        // auto-continuing, and a user ESC ends it "aborted": the
-                        // first idle is not the turn's real end. superviseImplementation
-                        // resumes across compactions, steers across interrupts, and
-                        // reads how the turn ACTUALLY ended.
-                        const outcome = await superviseImplementation(newCtx, {
-                            promptSteer: opts.promptSteer
-                        });
-                        interrupted = outcome.interrupted;
-                        implError = outcome.error;
+                    // The implementation turn is the one "child" that is not a
+                    // child: it runs in the user's own session, so its reasoning
+                    // group is applied by moving pi's level and moving it back.
+                    // The autofix re-runner (gateRunTask) re-enters runSingleTask
+                    // and so re-enters this closure, which is why the hold lives
+                    // here rather than at either call site.
+                    const release = holdImplementationThinking(opts.thinkingControl ?? piThinkingControl());
+                    try {
+                        // Queue-or-run: never throws, whatever else is on the session (issue #8).
+                        await newCtx.sendUserMessage(spec, { deliverAs: 'followUp' });
+                        if (opts.waitForImplementation) {
+                            await newCtx.waitForIdle();
+                            // A threshold auto-compaction parks the turn at idle WITHOUT
+                            // auto-continuing, and a user ESC ends it "aborted": the
+                            // first idle is not the turn's real end. superviseImplementation
+                            // resumes across compactions, steers across interrupts, and
+                            // reads how the turn ACTUALLY ended.
+                            const outcome = await superviseImplementation(newCtx, {
+                                promptSteer: opts.promptSteer
+                            });
+                            interrupted = outcome.interrupted;
+                            implError = outcome.error;
+                        }
+                    }
+                    finally {
+                        release();
                     }
                 },
                 spawnFn: opts.spawnFn,

package/dist/task/phases.js

@@ -21,7 +21,7 @@ import { getConfig } from '../config/config.js';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { buildExternalContext, gatherExternalContext } from './external-context.js';
-import { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, GRILL_AUTO_FORMAT_HINT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, MAX_GRILL_QUESTIONS, appendNoThink } from './prompts.js';
+import { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, GRILL_AUTO_FORMAT_HINT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, MAX_GRILL_QUESTIONS } from './prompts.js';
 import { appendGateRecord, readSection, removeTaskSection, setTaskSection, updateTaskFrontMatter } from './task-io.js';
 import { applyRefutations } from './refuted-constraint.js';
 import { spawnSync } from 'node:child_process';
@@ -29,7 +29,7 @@ import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js'
 import { isDuplicateQuestion, MAX_DUP_STRIKES, DUP_REPROMPT_HINT } from './question-dedup.js';
 import { parseGrillQuestions, parseAutoAnswer, autoAnswerHasTag, parseVerifyToolingOutput, deriveTitle } from './parsers.js';
 import { compressTitle } from './title-label.js';
-import { parseVerifyBlock, validateSpecShape, stripSpecPreamble, isCritiqueClean } from './spec-validation.js';
+import { parseVerifyBlock, validateSpecShape, validateRefineShape, stripSpecPreamble, isCritiqueClean } from './spec-validation.js';
 import { collectCritiqueDefects } from './critique-probes.js';
 import { buildOptionCards, resolveAnswer } from './question-dialog.js';
 import { findSynthesizedApis, synthesizedApiReaskHint } from './api-synthesis.js';
@@ -42,6 +42,7 @@ import { runPhaseChild, runWithEmphasisRetry, prependHint, USER_CANCELLED } from
 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';
 // ─── Re-export constants from their home modules ────────────────────────────
 export { MAX_GRILL_QUESTIONS };
 // ─── Tooling helpers ─────────────────────────────────────────────────────────
@@ -265,7 +266,7 @@ export const phaseRefine = async (deps, raw, planContext) => {
     // re-check the output below (lever). Empty on an ordinary prompt → refine unchanged.
     const directives = extractUserDirectives(raw);
     const directivesBlock = preserveDirectivesBlock(directives);
-    const refined = await runPhaseChild(deps, 'refine', 'read', appendNoThink(REFINE_PROMPT(raw, planContext, existingFiles, contracts, directivesBlock)), 
+    const refined = await runPhaseChild(deps, 'refine', 'read', REFINE_PROMPT(raw, planContext, existingFiles, contracts, directivesBlock), 
     // refine's deliverable is a 4-section text rewrite that never strictly
     // needs a successful read — on a test-writing task against a large
     // existing codebase the model over-explores (re-reads source hunting for
@@ -274,6 +275,16 @@ export const phaseRefine = async (deps, raw, planContext) => {
     // refine looped 3×/resume forever; the deliverable was always producible
     // from the title + design doc alone.
     { degradeOnExhaustion: true, verb: 'restart' });
+    // Shape check, REPORTED not enforced. Refine's four sections are what
+    // extractCapsSection, scopedToolingGoal, deriveTitle and extractEnrichTargets
+    // each look for, and all four fail SILENTLY when one is missing — so the loss
+    // was previously invisible. Deliberately not a retry or a throw: refine's
+    // output is usable prose even when a heading is gone (the four consumers
+    // degrade, they do not break), and a run must not die over a heading. This
+    // puts the miss in the debug log where an audit can find it.
+    const shape = validateRefineShape(refined);
+    if (shape)
+        deps.logDebug?.(`refine: ${shape}`);
     // Deterministic backstop: if the refined spec still dropped a directive, append
     // it verbatim rather than trusting the paraphrase. No model in this path.
     const { text, appended } = enforceDirectives(refined, directives);
@@ -291,7 +302,7 @@ export async function phaseVerifyTooling(deps, research) {
     const toolingList = commands.join('\n');
     let verifyOutput;
     try {
-        verifyOutput = await runPhaseChild(deps, 'verify-tooling', 'read,bash', appendNoThink(VERIFY_TOOLING_PROMPT(toolingList)));
+        verifyOutput = await runPhaseChild(deps, 'verify-tooling', 'read,bash', VERIFY_TOOLING_PROMPT(toolingList));
     }
     catch {
         return replaceToolingWithVerified(research, commands);
@@ -717,26 +728,33 @@ export async function phaseResearch(deps, refined) {
         return r;
     });
     // Run the four workers ONE AT A TIME. Settled by an A/B on the local
-    // llama.cpp backend (single GPU, same task/model) — and the answer flips
+    // llama.cpp backend (single GPU, same task/model) — and the answer FLIPS
     // with thinking:
-    //   - thinking ON → parallel wins: long decodes batch well, 4 concurrent
+    //   - thinking ON  → parallel wins: long decodes batch well, 4 concurrent
     //     finish in ~max(worker), not the sum.
-    //   - /no_think   → sequential wins: with short decodes the batching upside
+    //   - thinking OFF → sequential wins: with short decodes the batching upside
     //     is gone, but 4 concurrent streams still split the one GPU and slow
     //     each other ~4x (context worker measured 27s solo vs 128s under load),
     //     so summed-but-fast (~100s) beats max-of-slowed (~130s).
-    // Every worker runs /no_think (below), so sequential is the faster regime.
-    // Do NOT switch the DEFAULT back to concurrent without re-running that A/B;
-    // the opt-in `parallelResearchWorkers` config flag exists for backends that
-    // genuinely serve parallel streams.
     //
-    // `/no_think` is the big win: these are agentic exploration loops, and on a
-    // reasoning model the child would otherwise emit a full <think> trace at
-    // every tool step ("let me read X next…") — the single largest decode sink
-    // in the pipeline. Stripping it cut each worker's decode 3-8x in the A/B.
-    // The worker still calls as many tools as it wants; it just stops narrating
-    // between them. See appendNoThink. Result order (files, apis, context,
-    // tooling) is preserved for assembly.
+    // KNOWN-OPEN, AND THIS IS THE HONEST STATE OF IT. That A/B was run when
+    // every worker carried Qwen3's `/no_think` prompt suffix, so "thinking OFF"
+    // was assumed and sequential followed. The suffix has since been measured
+    // INERT — with server thinking on and `/no_think` still in the prompt,
+    // Qwen3.8 emitted a median 17k-char trace anyway (n=25) — and it has been
+    // removed in favour of the `research` reasoning group (config/reasoning.ts).
+    // So the arm this default was chosen under may never have been the arm that
+    // ran, and the group's level is now a user-visible setting rather than a
+    // constant.
+    //
+    // The default stays SEQUENTIAL because that is the measured-safe arm on a
+    // single-GPU box and because flipping a shipped default on an invalidated
+    // premise would be replacing one unmeasured claim with another. The
+    // parallel x reasoning-level interaction is unmeasured; re-run the A/B
+    // before changing this, and treat `parallelResearchWorkers` as the opt-in
+    // for backends that genuinely serve parallel streams.
+    //
+    // Result order (files, apis, context, tooling) is preserved for assembly.
     // Resolved once: `searchConfigured()` reads the environment, and the tools
     // string and the `-e` paths must be derived from the SAME answer.
     const apisChannels = apisWorkerChannels();
@@ -745,7 +763,7 @@ export async function phaseResearch(deps, refined) {
             section: 'FILES',
             label: 'worker:files',
             // Read-heavy: gets the orientation core (see note above).
-            prompt: appendNoThink(orientation.block + promptHeader + RESEARCH_FILES_PROMPT(refined))
+            prompt: orientation.block + promptHeader + RESEARCH_FILES_PROMPT(refined)
         },
         {
             section: 'APIS',
@@ -756,7 +774,7 @@ export async function phaseResearch(deps, refined) {
             // the worker doesn't re-derive where-things-live via docs-"."
             // queries the FILES worker just answered (run-7 F7: up to 10
             // duplicate `.`-decodes per task through the serial bottleneck).
-            prompt: prior => appendNoThink(orientation.block
+            prompt: prior => orientation.block
                 + promptHeader
                 + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined)
                 + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')
@@ -764,7 +782,7 @@ export async function phaseResearch(deps, refined) {
                 // set. The tool-side half lives in pi-worker-docs.ts; a
                 // budget enforced without being announced would just read
                 // to the worker as a broken tool.
-                + (fanoutBudget === null ? '' : projectDocsBudgetNotice(fanoutBudget))),
+                + (fanoutBudget === null ? '' : projectDocsBudgetNotice(fanoutBudget)),
             // The tools string and the `-e` paths are ONE fact — which worker
             // channels this research worker is given — and used to be two literals
             // kept in step by eye. `channelSet` derives both from the same rows.
@@ -798,7 +816,7 @@ export async function phaseResearch(deps, refined) {
         {
             section: 'CONTEXT',
             label: 'worker:context',
-            prompt: appendNoThink(promptHeader + RESEARCH_CONTEXT_PROMPT(refined)),
+            prompt: promptHeader + RESEARCH_CONTEXT_PROMPT(refined),
             // Context owns architectural understanding, not path discovery —
             // FILES handles that. Dropping `find`/`ls` keeps the worker from
             // spawning long enumeration loops whose output then inflates
@@ -843,7 +861,7 @@ export async function phaseResearch(deps, refined) {
             label: 'worker:tooling',
             // Scope to the goal prose only — not the per-file edit checklist that
             // makes a weak model spelunk source and loop. See scopedToolingGoal.
-            prompt: appendNoThink(promptHeader + RESEARCH_TOOLING_PROMPT(scopedToolingGoal(refined))),
+            prompt: promptHeader + RESEARCH_TOOLING_PROMPT(scopedToolingGoal(refined)),
             // Block re-reads in-process so a weak model that wants to re-read the
             // same file is told to answer from what it has instead of looping.
             extensions: [SINGLE_READ_EXTENSION_PATH]
@@ -883,6 +901,11 @@ 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'),
             ...(spec.tools ? { tools: spec.tools } : {}),
             ...(spec.extensions ? { extensions: spec.extensions } : {}),
             // 5B SCALE arm — null unless both env vars are set. Only the
@@ -1453,7 +1476,7 @@ extraDefects) {
             // Granting `read` here let it wander the repo to "verify" findings,
             // which made the supposedly-cheap pass cost as much as a rewrite
             // (observed ~133s). The judgement needs no file access.
-            verdict = await runPhaseChild(deps, 'critique-triage', '', appendNoThink(CRITIQUE_TRIAGE_PROMPT(spec, refined, qa, contractsBlock)));
+            verdict = await runPhaseChild(deps, 'critique-triage', '', CRITIQUE_TRIAGE_PROMPT(spec, refined, qa, contractsBlock));
         }
         catch {
             verdict = null;

package/dist/task/prompts.d.ts

@@ -5,29 +5,6 @@
  * effects, trivially testable.
  */
 export declare const MAX_GRILL_QUESTIONS = 20;
-/**
- * Qwen3 "soft switch": placing `/no_think` in the prompt disables the model's
- * <think> reasoning trace for that turn and persists across the tool-call loop
- * within the same child session.
- *
- * On a local reasoning model decode is the bottleneck (~50 t/s here) while
- * prefill is ~10x faster, so cost is dominated by *generated* tokens. A runaway
- * think trace can be 10k+ tokens — minutes — even when the phase's real output
- * is a short list or a one-word verdict (an observed triage spent ~384s
- * thinking to emit "CLEAN"). Stripping the monologue does NOT limit the model's
- * exploration: it still calls every tool it wants and takes every step it
- * needs — it just stops narrating between actions.
- *
- * We strip thinking from the mechanical / exploration phases (refine, the four
- * research workers, verify-tooling, triage) and keep it ON for the judgment
- * phases (compose, grill, critique rewrite) where the reasoning earns its
- * decode cost. pi's `--thinking off` flag is a no-op for this provider
- * (`supportsReasoningEffort: false` in models.json), so the in-prompt soft
- * switch is the reliable control.
- */
-export declare const NO_THINK = "/no_think";
-/** Append the Qwen3 `/no_think` soft switch to a prompt. See {@link NO_THINK}. */
-export declare function appendNoThink(prompt: string): string;
 /**
  * Compress a verbose task title into a short status-bar label. Pure judgment, no
  * tools — the child reads only the title we hand it. The output is sanitised and

package/dist/task/prompts.js

@@ -8,31 +8,6 @@
 // and the grill loop's total iterations, so a model that never emits NONE can't
 // run unbounded.
 export const MAX_GRILL_QUESTIONS = 20;
-/**
- * Qwen3 "soft switch": placing `/no_think` in the prompt disables the model's
- * <think> reasoning trace for that turn and persists across the tool-call loop
- * within the same child session.
- *
- * On a local reasoning model decode is the bottleneck (~50 t/s here) while
- * prefill is ~10x faster, so cost is dominated by *generated* tokens. A runaway
- * think trace can be 10k+ tokens — minutes — even when the phase's real output
- * is a short list or a one-word verdict (an observed triage spent ~384s
- * thinking to emit "CLEAN"). Stripping the monologue does NOT limit the model's
- * exploration: it still calls every tool it wants and takes every step it
- * needs — it just stops narrating between actions.
- *
- * We strip thinking from the mechanical / exploration phases (refine, the four
- * research workers, verify-tooling, triage) and keep it ON for the judgment
- * phases (compose, grill, critique rewrite) where the reasoning earns its
- * decode cost. pi's `--thinking off` flag is a no-op for this provider
- * (`supportsReasoningEffort: false` in models.json), so the in-prompt soft
- * switch is the reliable control.
- */
-export const NO_THINK = '/no_think';
-/** Append the Qwen3 `/no_think` soft switch to a prompt. See {@link NO_THINK}. */
-export function appendNoThink(prompt) {
-    return `${prompt}\n\n${NO_THINK}`;
-}
 /**
  * Compress a verbose task title into a short status-bar label. Pure judgment, no
  * tools — the child reads only the title we hand it. The output is sanitised and

package/dist/task/reasoning-groups.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Child NAME → reasoning group, for every child that goes through
+ * `runPhaseChild` / `runPlanningChild`.
+ *
+ * WHY KEYED ON THE NAME
+ * ---------------------
+ * The name is the only identifier in scope at all three spawn paths (phases,
+ * /task-auto planning, /task-plan), it is what the loader and the debug trail
+ * already print, and it is the one thing a reader can check against the phase
+ * list without following the call graph. Threading a group parameter through
+ * `PhaseDeps` / `AutoDeps` instead would touch both orchestrators' dep bags to
+ * express something the call site already says out loud.
+ *
+ * AN UNMAPPED NAME IS A BUILD FAILURE, not a silent `inherit`.
+ * `reasoning-groups.test.ts` scans every literal child name in src/ and fails if
+ * it is missing here. A defaulting lookup would let a phase added next year opt
+ * itself out of a measured setting without anyone deciding to — which is exactly
+ * how `/no_think` ended up applied to eight prompts and read by none of them.
+ *
+ * The gate, research and extraction groups are NOT here: those children reach the
+ * model through `runWorker` / `focusedChildArgs`, where the group is a property
+ * of the call site rather than of a name, and is passed directly.
+ */
+import type { ReasoningGroup } from '../config/reasoning.js';
+export declare const REASONING_GROUP_BY_CHILD: Readonly<Record<string, ReasoningGroup>>;
+/**
+ * The group a named child belongs to.
+ *
+ * Returns `undefined` for a name the table does not know, and the CALLER decides
+ * what that means. `runPhaseChild` treats it as `inherit` — a child that reaches
+ * the model with today's argv is always safe — while the test treats it as a
+ * failure. That split is deliberate: the guard belongs at build time, where
+ * someone can fix it, not at run time, where it would abort a user's task over a
+ * missing table row.
+ */
+export declare function reasoningGroupForChild(name: string): ReasoningGroup | undefined;

package/dist/task/reasoning-groups.js

@@ -0,0 +1,36 @@
+export const REASONING_GROUP_BY_CHILD = {
+    // ── phase: task/phases.ts + task/title-label.ts ──────────────────────────
+    refine: 'phase',
+    'verify-tooling': 'phase',
+    'grill-auto': 'phase',
+    'grill-gen': 'phase',
+    compose: 'phase',
+    critique: 'phase',
+    'critique-triage': 'phase',
+    'compress-label': 'phase',
+    // ── planning: task/auto-orchestrator.ts ──────────────────────────────────
+    'clarify-triage': 'planning',
+    'auto-clarify': 'planning',
+    'auto-decompose': 'planning',
+    'requirement-extract': 'planning',
+    'decompose-coverage': 'planning',
+    'coverage-map': 'planning',
+    'contract-extract': 'planning',
+    'launch-extract': 'planning',
+    // ── plan: task/plan-orchestrator.ts ──────────────────────────────────────
+    'plan-question': 'plan',
+    'plan-answer': 'plan'
+};
+/**
+ * The group a named child belongs to.
+ *
+ * Returns `undefined` for a name the table does not know, and the CALLER decides
+ * what that means. `runPhaseChild` treats it as `inherit` — a child that reaches
+ * the model with today's argv is always safe — while the test treats it as a
+ * failure. That split is deliberate: the guard belongs at build time, where
+ * someone can fix it, not at run time, where it would abort a user's task over a
+ * missing table row.
+ */
+export function reasoningGroupForChild(name) {
+    return REASONING_GROUP_BY_CHILD[name];
+}

package/dist/task/spec-validation.d.ts

@@ -35,3 +35,31 @@ export declare function isCritiqueClean(text: string): boolean;
  */
 export declare function stripSpecPreamble(spec: string): string;
 export declare function validateSpecShape(spec: string): string | null;
+/** The four sections REFINE_PROMPT demands, in the order it demands them. */
+export declare const REFINE_SECTIONS: readonly ["GOAL", "CONSTRAINTS", "KNOWN-UNKNOWNS", "EXTERNAL-DEPENDENCIES"];
+/**
+ * Is a refine child's output shaped like a refined prompt?
+ *
+ * Refine shipped with NO shape check at all — `phaseRefine` passes no validator,
+ * unlike compose and critique — and every downstream reader of a refined prompt
+ * is a PARTIAL parser that tolerates a missing section SILENTLY:
+ * `extractCapsSection` (refuted-constraint.ts) returns null, `scopedToolingGoal`
+ * (phases.ts) returns the whole text, `deriveTitle` and `extractEnrichTargets`
+ * fall back. So a refine answer that dropped a heading degrades four features at
+ * once and says nothing. This names the contract in one place.
+ *
+ * WHAT IT CHECKS, and why it is only this. Every one of those consumers looks
+ * for a BARE ALL-CAPS heading alone on its own line — `l.trim() === heading`,
+ * `/^GOAL[ \t]*\n/m`. That is the operative contract, so that is the test.
+ *
+ * It does NOT require the text to START with GOAL, even though REFINE_PROMPT
+ * says "four sections, exact headings, in this order" and forbids a preamble.
+ * Measured over the 57-task mx5 corpus: 55/56 non-empty refined prompts carry
+ * all four bare headings, but only 25/56 open with one — a preamble is what real
+ * refine output usually looks like, and production has always consumed it fine.
+ * A validator stricter than its consumers would reject work that works.
+ *
+ * Returns a problem string, or null when the shape is good — same contract as
+ * `validateSpecShape` above.
+ */
+export declare function validateRefineShape(refined: string): string | null;

package/dist/task/spec-validation.js

@@ -108,3 +108,47 @@ export function validateSpecShape(spec) {
     }
     return null;
 }
+// ─── Refine shape gate ───────────────────────────────────────────────────────
+/** The four sections REFINE_PROMPT demands, in the order it demands them. */
+export const REFINE_SECTIONS = [
+    'GOAL',
+    'CONSTRAINTS',
+    'KNOWN-UNKNOWNS',
+    'EXTERNAL-DEPENDENCIES'
+];
+/**
+ * Is a refine child's output shaped like a refined prompt?
+ *
+ * Refine shipped with NO shape check at all — `phaseRefine` passes no validator,
+ * unlike compose and critique — and every downstream reader of a refined prompt
+ * is a PARTIAL parser that tolerates a missing section SILENTLY:
+ * `extractCapsSection` (refuted-constraint.ts) returns null, `scopedToolingGoal`
+ * (phases.ts) returns the whole text, `deriveTitle` and `extractEnrichTargets`
+ * fall back. So a refine answer that dropped a heading degrades four features at
+ * once and says nothing. This names the contract in one place.
+ *
+ * WHAT IT CHECKS, and why it is only this. Every one of those consumers looks
+ * for a BARE ALL-CAPS heading alone on its own line — `l.trim() === heading`,
+ * `/^GOAL[ \t]*\n/m`. That is the operative contract, so that is the test.
+ *
+ * It does NOT require the text to START with GOAL, even though REFINE_PROMPT
+ * says "four sections, exact headings, in this order" and forbids a preamble.
+ * Measured over the 57-task mx5 corpus: 55/56 non-empty refined prompts carry
+ * all four bare headings, but only 25/56 open with one — a preamble is what real
+ * refine output usually looks like, and production has always consumed it fine.
+ * A validator stricter than its consumers would reject work that works.
+ *
+ * Returns a problem string, or null when the shape is good — same contract as
+ * `validateSpecShape` above.
+ */
+export function validateRefineShape(refined) {
+    const trimmed = refined.trim();
+    if (trimmed.length === 0)
+        return 'refined prompt is empty';
+    const lines = trimmed.split('\n').map(l => l.trim());
+    const missing = REFINE_SECTIONS.filter(s => !lines.includes(s));
+    if (missing.length > 0) {
+        return `refined prompt missing required section(s): ${missing.join(', ')}`;
+    }
+    return null;
+}

package/dist/task/stall-detector.d.ts

@@ -38,6 +38,11 @@
  *      rule 1 alone would not have caught it. The bound scales with the model's
  *      OWN window, so a 1M-context model gets a 1M-context allowance.
  *
+ *      The window is supplied by the PARENT at spawn (`PhaseDeps.contextWindow`),
+ *      not read off the child's event stream: pi emits no context event at all,
+ *      which is why this rule sat disarmed from the day it was written until
+ *      GitHub issue #16.
+ *
  * Neither rule can fire on a child that is thinking rather than calling tools:
  * that case is bounded by the model's max tokens (server-enforced) and by the
  * stream watchdog if the stream goes silent. Between the three there is no

package/dist/task/stall-detector.js

@@ -38,6 +38,11 @@
  *      rule 1 alone would not have caught it. The bound scales with the model's
  *      OWN window, so a 1M-context model gets a 1M-context allowance.
  *
+ *      The window is supplied by the PARENT at spawn (`PhaseDeps.contextWindow`),
+ *      not read off the child's event stream: pi emits no context event at all,
+ *      which is why this rule sat disarmed from the day it was written until
+ *      GitHub issue #16.
+ *
  * Neither rule can fire on a child that is thinking rather than calling tools:
  * that case is bounded by the model's max tokens (server-enforced) and by the
  * stream watchdog if the stream goes silent. Between the three there is no

package/dist/task/title-label.js

@@ -12,7 +12,7 @@
  */
 import { runPhaseChild } from './child-runner.js';
 import { LABEL_MAX, truncateLabel } from './parsers.js';
-import { COMPRESS_LABEL_PROMPT, appendNoThink } from './prompts.js';
+import { COMPRESS_LABEL_PROMPT } from './prompts.js';
 /**
  * Reduce a raw model completion to a single clean label line: first non-empty
  * line, stripped of surrounding quotes/backticks and a leading "label:" echo,
@@ -37,7 +37,7 @@ export async function compressTitle(deps, title) {
     if (title.replace(/\s+/g, ' ').trim().length <= LABEL_MAX)
         return fallback;
     try {
-        const raw = await runPhaseChild(deps, 'compress-label', '', appendNoThink(COMPRESS_LABEL_PROMPT(title, LABEL_MAX)));
+        const raw = await runPhaseChild(deps, 'compress-label', '', COMPRESS_LABEL_PROMPT(title, LABEL_MAX));
         const cleaned = sanitizeLabel(raw);
         if (cleaned.length === 0)
             return fallback;

package/dist/workers/docs-core.js

@@ -10,6 +10,7 @@ import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
 import { runChild } from '../shared/child-process.js';
 import { runFocusedExtraction } from './focused-extractor.js';
 import { buildExtractionPrompt } from './abstention.js';
+import { groupThinkingArgs } from '../config/reasoning-args.js';
 const DEFAULT_LIMIT = PACKAGE_RETRIEVE_LIMIT;
 const DEFAULT_BUDGET = RETRIEVE_CONTENT_BUDGET;
 const NO_CACHE_HEAD = 25_000;
@@ -562,6 +563,9 @@ export async function docsFocused(input) {
         cwd: input.cwd,
         signal: input.signal,
         spawn,
+        // The `extraction` group's level. Resolved at the call site so the
+        // extractor itself never reads ambient config.
+        thinking: groupThinkingArgs('extraction'),
         abortedMessage: 'Docs lookup aborted.'
     });
     const base = {

package/dist/workers/fetch-core.js

@@ -1,6 +1,7 @@
 import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
 import { runFocusedExtraction } from './focused-extractor.js';
 import { abstentionSentence } from './abstention.js';
+import { groupThinkingArgs } from '../config/reasoning-args.js';
 const CONTENT_BUDGET = 30_000;
 const HEAD_CHARS = 25_000;
 const TAIL_CHARS = 5_000;
@@ -79,6 +80,9 @@ export async function fetchFocused(input) {
         cwd: input.cwd,
         signal: input.signal,
         spawn: input.spawn,
+        // The `extraction` group's level. Resolved at the call site so the
+        // extractor itself never reads ambient config.
+        thinking: groupThinkingArgs('extraction'),
         abortedMessage: 'Fetch aborted.'
     });
     const base = {

package/dist/workers/focused-extractor.d.ts

@@ -8,7 +8,7 @@ import { type ExcerptVerification } from '../shared/child-output.js';
  * `--no-tools` is the contract, not a default: the child is given all the content it may use
  * inside its prompt, so a tool call could only reach for something unsourced.
  */
-export declare const focusedChildArgs: () => string[];
+export declare const focusedChildArgs: (thinking?: readonly string[]) => string[];
 export interface FocusedRequest {
     /** The fully assembled prompt, including the content block. Delivered on stdin. */
     prompt: string;
@@ -33,6 +33,17 @@ export interface FocusedRequest {
     spawn?: SpawnFn;
     /** The message reported when the child was aborted, e.g. `'Docs lookup aborted.'`. */
     abortedMessage: string;
+    /**
+     * An already-resolved `['--thinking', level]` fragment, or `[]`/omitted to
+     * inherit the session default.
+     *
+     * Supplied by the CALLER even though all three call sites are the same
+     * `extraction` group. Resolving it inside this module would make
+     * `focusedChildArgs` read ambient config, and a function that reads config
+     * internally cannot be tested without the developer's own machine state —
+     * which is exactly how a `getConfig()` assertion got into a unit test.
+     */
+    thinking?: readonly string[];
 }
 /** What every outcome carries, success or failure — the raw child evidence. */
 interface FocusedChildEvidence {

package/dist/workers/focused-extractor.js

@@ -37,7 +37,11 @@ import { formatChildFailure } from './shared.js';
  * `--no-tools` is the contract, not a default: the child is given all the content it may use
  * inside its prompt, so a tool call could only reach for something unsourced.
  */
-export const focusedChildArgs = () => [...childBaseArgs(), '--no-tools'];
+export const focusedChildArgs = (thinking = []) => [
+    ...childBaseArgs(),
+    ...thinking,
+    '--no-tools'
+];
 /**
  * Run one focused extraction: spawn the no-tools child on `prompt`, and on success parse its
  * `<answer>`/`<excerpt>` and verify the excerpt against `verifyAgainst`.
@@ -47,7 +51,7 @@ export const focusedChildArgs = () => [...childBaseArgs(), '--no-tools'];
  */
 export async function runFocusedExtraction(req) {
     const spawn = req.spawn ?? defaultSpawn;
-    const invocation = getPiInvocation(focusedChildArgs(), req.prompt);
+    const invocation = getPiInvocation(focusedChildArgs(req.thinking), req.prompt);
     const child = await runChild(spawn, invocation, req.cwd, req.signal);
     const evidence = {
         exitCode: child.exitCode,