@mjasnikovs/pi-task 0.38.31 → 0.39.0

package/README.md

@@ -214,7 +214,8 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | **command timeout** | 15 min | Wall-clock ceiling on a **single** tool execution. Local models routinely run a command that never returns (a hung build, a dev server, a check with no timeout) and the run wedges until you abort by hand — pi's bash tool has an optional timeout with no default, so this is the missing one. One knob, two surfaces: in the main session the overrun call is cancelled (killing the tool's whole process tree) plus a reminder turn; in the verify/fix gate children the child is killed and re-spawned with a hint, halving the ceiling on repeat hangs. Choices: 5/10/15/30 min or **off** — off unguards both surfaces, gates included. |
 | **stuck reply retry** | 10 min | Inactivity ceiling on the **model stream**. A hung or silently-dropped stream throws nothing at all, so neither the connection-error retry (it needs a reported error) nor the **command timeout** (tool calls only) nor the dead-backend stall guard (a reachable endpoint reads as proof of life) can see it — an mx5 run lost ~2.9h to three of them while the model server stayed healthy. Measured as time since the **last stream event of any kind**, so a slow model emitting one token every 30s is never touched, and it pauses while a tool runs. On expiry the main session aborts the turn (through the same channel the command watchdog uses) and posts a resume reminder; a child is killed and routed into the existing connection-error retry. Choices: 5/10/20/30 min or **off**. Keep it generous on local backends — prompt processing on a large context legitimately emits nothing for minutes. |
 | **yolo mode** | off | **Unattended runs.** Wherever pi-task would stop and ask, it takes the option already marked RECOMMENDED, stamps the artifact `(YOLO)` so an audit can tell a machine decided, and shows no prompt at all — clarify/grill answers, the verify-FAIL picker (auto-**Accept**, recorded as a yolo debt), and the final-gate picker (autofix while the budget lasts, then leave the run FAILED). A question with no recommendation is **skipped**, never invented. For throwaway/test projects nobody is watching; a real run should decide these itself. |
-| **reasoning** | default | How much the helper sessions think before answering. Local models differ sharply here: some break without reasoning, some waste minutes with it, and some cannot do it at all. The seven **think:** rows below set one level per group of steps — research workers, spec phases, /task-auto planning, /task-plan, the checking gates, the small extraction children, and the implementation turn itself. **default** uses the table pi-task has measured, **on** and **off** force one answer everywhere, and **custom** is whatever the think: rows say (changing any of them switches to custom). A step on **inherit** passes no flag at all, so it uses whatever thinking level pi itself is set to — which is what every step did before this setting existed, and is what every cell of the measured table currently holds. The think: rows always show what a step *actually* runs at, not what the stored table says. Three tiers of model exist and pi-task tells them apart: full levels (`reasoning_effort` in the chat template, e.g. Qwen3.8), on/off only (e.g. Qwen3.6, Gemma 4), and none at all. pi silently CLAMPS a level a model does not declare — a level you set can be erased, and an `off` can be clamped back up to `medium` — so a startup warning names the model and the steps it will not honour. It never fires while every step is on inherit. |
+| **profile** | default | How much the helper sessions think, in one word, for every step at once. Local models differ sharply here: some break without reasoning, some waste minutes with it, and some cannot do it at all. **default** uses the per-step table pi-task has measured, **on** and **off** force one answer everywhere and ignore that table, and **custom** is whatever the step rows say — changing any of them switches this to custom. A step on **inherit** passes no flag at all, so it uses whatever thinking level pi itself is set to, which is what every step did before this setting existed. |
+| **steps: …** | all `inherit` | One row per group of steps, carrying BOTH dials: the model those children run on and the level they think at, shown as `level · model`. Enter walks a two-step picker — model first, then level — and **the level step offers only what that model declares, opening on the one that will actually run**. That is the whole point of the merge: pi silently CLAMPS a level a model cannot do (a level you set can be erased, and an `off` can be clamped back up to `medium`), so instead of discovering that later you watch the cursor land on the level you are really getting. Models are offered from `pi.modelRegistry.getAvailable()` and stored as the canonical `provider/id` that pi's own `--model` takes. **inherit** on the model half emits no flag, so an all-inherit table is byte-identical to a build without this feature; that is the shipped default, because which models exist is a property of your machine and nothing here can be measured for you. A stored model this machine cannot resolve is never erased (you may have set it on another machine): the flag is dropped, the step runs on pi's default, and a startup hint names the step. Two need care — a provider registered by a host **extension** needs that extension enabled under **ext: …** or those children exit 1; and **implementation** is not free, because it is *your* session moved for the turn and moved back, and a model switch re-bills the whole prompt as a cache miss, twice per task. |
 | **debug logs** | events | How much of a run is written to `.pi-tasks/*-debug.log`. **`events`** keeps decisions and guard actions — which phase ran, why a worker was retried, what the git-state guard restored, what a write-capable child changed on disk, why a gate returned FAIL — a few lines per task. **`full`** adds every line the child model emitted and every tool result; that's ~85% of the bytes (a real 247 KB `verify-debug.log` is 1315 lines, 521 of them tool dumps) and is what you want while actively debugging. **`off`** writes nothing. Nothing in pi-task ever reads these files back, so the setting cannot change how a run behaves — only whether you can explain it afterwards, and a log not written can't be recovered later. |
 | **watch: …** | all on | One toggle per tool in the live session, deciding whether **command timeout** applies to it. The list is discovered from `pi.getAllTools()` when the menu opens — built-ins first, then each extension's tools with the owning entry-point path in the description — so nothing is typed by hand and an uninstalled tool just stops being listed. Turn one **off** only for a tool that already owns a longer bounded, cancellable contract of its own (the guard exists because pi's `bash` has an optional timeout with *no* default — that reasoning doesn't transfer to a tool that has one). Two things to know before you do: a genuine hang in an unwatched tool is caught by nothing, since **stuck reply retry** is paused for the whole time any tool runs; and an unwatched tool is still killed as collateral if a *watched* sibling in the same turn overruns, because pi runs sibling tool calls concurrently and the abort ends the whole turn. Stored as exemptions, so the default and every tool pi-task has never seen stay guarded. |
 | **ext: …** | all off | One toggle per installed host `pi` extension, loading it into every child session by explicit path. Children otherwise run with extensions off, so a provider registered by an extension (e.g. `pi-lmstudio`) doesn't exist in them and they can't resolve the default model. Children also inherit the extension's tools and hooks, so only enable ones you trust. The list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |

package/dist/config/config.d.ts

@@ -1,5 +1,5 @@
 import { type SearchProvider } from '../workers/search-types.js';
-import { type GroupSetting, type ReasoningGroup, type ReasoningMode } from './reasoning.js';
+import { type GroupSetting, type ChildGroup, type ReasoningMode } from './reasoning.js';
 export interface PiTaskConfig {
     remote: boolean;
     autoCommit: boolean;
@@ -155,7 +155,21 @@ export interface PiTaskConfig {
      * survives the watchdog being turned off. Its sanitizer always returns a
      * complete record, so no consumer needs a per-key fallback.
      */
-    reasoningLevels: Record<ReasoningGroup, GroupSetting>;
+    reasoningLevels: Record<ChildGroup, GroupSetting>;
+    /**
+     * The per-group MODEL, as a `provider/id` string, or `inherit` to emit no
+     * `--model` and let the child resolve pi's saved default as it always has.
+     *
+     * DEFAULT: every cell `inherit`, which makes every child's argv
+     * byte-identical to a build without this field. There is no mode enum and no
+     * shipped table — a model id is machine-local, so there is nothing to ship.
+     *
+     * Its sanitizer checks SHAPE, never existence: a spec naming a model this
+     * machine cannot resolve survives, because the alternative is deleting a
+     * setting the user made on their other machine. The once-per-session
+     * resolution check names it instead.
+     */
+    groupModels: Record<ChildGroup, string>;
 }
 /** How verbose the `.pi-tasks/*-debug.log` trail is. See {@link PiTaskConfig.debugLogs}. */
 export type DebugLogLevel = 'off' | 'events' | 'full';

package/dist/config/config.js

@@ -4,6 +4,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import { isSearchProvider } from '../workers/search-types.js';
 import { DEFAULT_REASONING_TABLE, sanitizeReasoningLevels, sanitizeReasoningMode } from './reasoning.js';
+import { DEFAULT_GROUP_MODELS, sanitizeGroupModels } from './group-models.js';
 import { DEFAULT_STREAM_INACTIVITY_MS } from '../shared/stream-watchdog.js';
 /**
  * The debug-log choices offered by /task-config, in cycle order (quietest →
@@ -108,7 +109,10 @@ export const DEFAULT_CONFIG = {
     // DEFAULT: the shipped per-group table. A cell left at `inherit` emits no
     // --thinking flag, so that child keeps the host's own level.
     reasoningMode: 'default',
-    reasoningLevels: { ...DEFAULT_REASONING_TABLE }
+    reasoningLevels: { ...DEFAULT_REASONING_TABLE },
+    // INHERIT everywhere. Nothing is measured here and nothing can be: which
+    // models exist is a property of the machine, not of pi-task.
+    groupModels: { ...DEFAULT_GROUP_MODELS }
 };
 /**
  * A hand-edited config can hold anything; keep only string entries so a stray
@@ -154,7 +158,8 @@ export const CONFIG_LOADERS = {
     streamInactivityMs: sanitizeStreamInactivityMs,
     debugLogs: sanitizeDebugLogs,
     reasoningMode: sanitizeReasoningMode,
-    reasoningLevels: sanitizeReasoningLevels
+    reasoningLevels: sanitizeReasoningLevels,
+    groupModels: sanitizeGroupModels
 };
 /**
  * Turn parsed config JSON into a `PiTaskConfig`. Pure, so every hostile-value

package/dist/config/group-args.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The live-config bridge for per-group child settings: group in, argv fragment out.
+ *
+ * Separate from reasoning.ts and group-models.ts because those must take no
+ * import with a runtime side effect — see their headers. The `getConfig()` read
+ * lives here instead: this file imports them and nothing in config/ imports it
+ * back, so the graph stays a tree.
+ *
+ * Read PER CALL, never cached at module scope, so a /task-config change lands on
+ * the next child without a restart. Same contract `childBaseArgs` keeps.
+ */
+import { type PiTaskConfig } from './config.js';
+import type { ChildGroup } from './groups.js';
+export declare function setUnusableSpecs(specs: Iterable<string>): void;
+export declare function isSpecUsable(spec: string): boolean;
+export declare function setGroupWindows(windows: Readonly<Partial<Record<ChildGroup, number>>>): void;
+/** The group's own window, or `undefined` for "caller keeps its fallback". */
+export declare function groupWindow(group: ChildGroup): number | undefined;
+/**
+ * The `['--model', spec]` fragment for a group, or `[]` for `inherit` and for a
+ * spec this session proved unresolvable.
+ *
+ * Dropping the flag is not the same failure class as passing it. A spec naming a
+ * model that is gone, whose PROVIDER still has other models, does not make pi
+ * exit — `buildFallbackModel` invents a synthetic model id, forces
+ * `reasoning: true` onto it, inherits the provider's default baseUrl and answers
+ * at exit 0. Dropping the flag runs the same child the user got last week and
+ * says so out loud; passing it runs a model nobody chose and says nothing.
+ */
+export declare function groupModelArgs(group: ChildGroup, cfg?: PiTaskConfig): string[];
+/**
+ * The `['--thinking', level]` fragment for a group, or `[]` when the group is
+ * `inherit` and the child should keep falling back to settings.json.
+ *
+ * Still exported on its own: the host-session turn (implementation-hold.ts) and
+ * the settings UI (register.ts) need the level rather than a whole fragment.
+ */
+export declare function groupThinkingArgs(group: ChildGroup, cfg?: PiTaskConfig): string[];
+/**
+ * Everything one group contributes to a child's argv, in one fragment.
+ *
+ * Every argv builder calls THIS rather than composing the two halves itself.
+ * That is why there is one carried field (`groupArgs`) rather than a `model`
+ * beside a `thinking`: a second required field would double the obligation on
+ * every future wiring, and a fragment assembled by hand is a doubled
+ * `--thinking` waiting to happen.
+ *
+ * ORDER: `--model` then `--thinking`. pi's parser is a flat loop, so it does not
+ * care. A human diffing two runs does — the identity of the child first, then
+ * the dial on it.
+ */
+export declare function groupChildArgs(group: ChildGroup, cfg?: PiTaskConfig): string[];

package/dist/config/group-args.js

@@ -0,0 +1,110 @@
+/**
+ * The live-config bridge for per-group child settings: group in, argv fragment out.
+ *
+ * Separate from reasoning.ts and group-models.ts because those must take no
+ * import with a runtime side effect — see their headers. The `getConfig()` read
+ * lives here instead: this file imports them and nothing in config/ imports it
+ * back, so the graph stays a tree.
+ *
+ * Read PER CALL, never cached at module scope, so a /task-config change lands on
+ * the next child without a restart. Same contract `childBaseArgs` keeps.
+ */
+import { getConfig } from './config.js';
+import { MODEL_INHERIT, modelArgs } from './group-models.js';
+import { resolveReasoning, thinkingArgs } from './reasoning.js';
+/**
+ * Specs this session has proven a child cannot resolve.
+ *
+ * WHY A SESSION-SCOPED SET AND NOT A LOOKUP
+ * -----------------------------------------
+ * The honest question is "can a `--no-extensions` child resolve this spec?", and
+ * only `ctx.modelRegistry` can answer it. Five of the six argv producers have no
+ * `ctx` — `pi-worker`, `pi-worker-docs`, `docs-core`, `fetch-core` and
+ * `child-runner` — so the answer cannot be fetched where it is needed. It also
+ * cannot be read from disk: models.json and models-store.json are only part of
+ * the catalogue, since pi-ai ships built-in model lists for 39 providers, and
+ * this project does not depend on pi-ai.
+ *
+ * So it is answered ONCE, at session_start, where ctx exists and every task is
+ * still in the future, and the verdict is left here.
+ *
+ * EMPTY MEANS EMIT. A host that never fires session_start therefore behaves
+ * exactly as it does today — the failure direction is "pi decides", never "we
+ * silently dropped a flag nobody checked".
+ */
+let unusableSpecs = new Set();
+export function setUnusableSpecs(specs) {
+    unusableSpecs = new Set(specs);
+}
+export function isSpecUsable(spec) {
+    return !unusableSpecs.has(spec);
+}
+/**
+ * The context window of each group's model, resolved in the SAME session pass
+ * that filled {@link setUnusableSpecs}.
+ *
+ * It lives here for the same reason that set does — `child-runner` and the
+ * workers have no `ctx`, so they cannot ask a registry — and it is filled by the
+ * same walk, so the two can never disagree about which model a group runs on.
+ *
+ * The number drives `StallDetector`'s churn rule, where the two error directions
+ * are NOT symmetric: too large fires late (degraded, and the no-new-ground rule
+ * still covers it), too small fires early and KILLS A HEALTHY CHILD. So an
+ * absent answer means "use the parent's", never a guess.
+ */
+let groupWindows = {};
+export function setGroupWindows(windows) {
+    groupWindows = { ...windows };
+}
+/** The group's own window, or `undefined` for "caller keeps its fallback". */
+export function groupWindow(group) {
+    const w = groupWindows[group];
+    return w !== undefined && w > 0 ? w : undefined;
+}
+/**
+ * The `['--model', spec]` fragment for a group, or `[]` for `inherit` and for a
+ * spec this session proved unresolvable.
+ *
+ * Dropping the flag is not the same failure class as passing it. A spec naming a
+ * model that is gone, whose PROVIDER still has other models, does not make pi
+ * exit — `buildFallbackModel` invents a synthetic model id, forces
+ * `reasoning: true` onto it, inherits the provider's default baseUrl and answers
+ * at exit 0. Dropping the flag runs the same child the user got last week and
+ * says so out loud; passing it runs a model nobody chose and says nothing.
+ */
+export function groupModelArgs(group, cfg) {
+    const spec = (cfg ?? getConfig()).groupModels[group];
+    if (spec === undefined || spec === MODEL_INHERIT)
+        return [];
+    return isSpecUsable(spec) ? modelArgs(spec) : [];
+}
+/**
+ * The `['--thinking', level]` fragment for a group, or `[]` when the group is
+ * `inherit` and the child should keep falling back to settings.json.
+ *
+ * Still exported on its own: the host-session turn (implementation-hold.ts) and
+ * the settings UI (register.ts) need the level rather than a whole fragment.
+ */
+export function groupThinkingArgs(group, cfg) {
+    // The default is evaluated HERE, per call. Hoisting the read to module scope
+    // would leave every test green, so the optional parameter is what makes the
+    // per-call contract assertable.
+    return thinkingArgs(resolveReasoning(group, cfg ?? getConfig()));
+}
+/**
+ * Everything one group contributes to a child's argv, in one fragment.
+ *
+ * Every argv builder calls THIS rather than composing the two halves itself.
+ * That is why there is one carried field (`groupArgs`) rather than a `model`
+ * beside a `thinking`: a second required field would double the obligation on
+ * every future wiring, and a fragment assembled by hand is a doubled
+ * `--thinking` waiting to happen.
+ *
+ * ORDER: `--model` then `--thinking`. pi's parser is a flat loop, so it does not
+ * care. A human diffing two runs does — the identity of the child first, then
+ * the dial on it.
+ */
+export function groupChildArgs(group, cfg) {
+    const live = cfg ?? getConfig();
+    return [...groupModelArgs(group, live), ...groupThinkingArgs(group, live)];
+}

package/dist/config/group-models.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Which model each child group runs on — the second table keyed on ChildGroup.
+ *
+ * PURE MODULE, like reasoning.ts and groups.ts: config.ts imports this during
+ * its own evaluation, so nothing here may have a runtime side effect.
+ *
+ * WHY THERE IS NO MODE ENUM
+ * -------------------------
+ * reasoningMode has four modes because there is a measured, shipped table worth
+ * a one-word "use the project's numbers", plus meaningful global on/off. Neither
+ * exists here. A model id is machine-local, so there can be no shipped table,
+ * and "all models on" is not a sentence. A mode enum would be four states of
+ * which three are unreachable.
+ *
+ * WHY THE CELL IS A STRING AND NOT A STRUCT
+ * -----------------------------------------
+ * `provider/id` is exactly what pi's `--model` takes, so the stored value goes
+ * to argv untouched. The round-trip property in config-items.test.ts needs the
+ * stored value recoverable verbatim from the offered label; a struct forces a
+ * format/parse pair that can drift.
+ */
+import { type ChildGroup } from './groups.js';
+/**
+ * The cell value meaning "emit no `--model`". Identical in spirit to `inherit`
+ * in the reasoning table, and identical in effect: an all-`inherit` table makes
+ * every child's argv byte-identical to a build without this feature.
+ *
+ * It is not a legal `provider/id` — pi rejects an unslashed pattern that matches
+ * no model — so it cannot collide with a real spec.
+ */
+export declare const MODEL_INHERIT = "inherit";
+/** Every cell on `inherit`. The shipped default, and deliberately not a table. */
+export declare const DEFAULT_GROUP_MODELS: Readonly<Record<ChildGroup, string>>;
+/**
+ * SHAPE ONLY, never existence.
+ *
+ * A config written on machine A must survive a session on machine B whose
+ * provider extension failed to load, or whose models.json is a different file
+ * entirely. Erasing a spec because this machine cannot resolve it would punish
+ * the two-machine user and lose a setting they never changed. Whether a spec
+ * resolves is asked once per session, where a warning can name it — not here,
+ * where the only available answer is deletion.
+ *
+ * So this rejects exactly what could RESHAPE argv, and nothing else:
+ *  - a non-string, which cannot be an argv token at all
+ *  - empty or whitespace-only, which pi would read as a missing value and
+ *    consume the following flag as the model pattern
+ *  - a leading `-`, which pi's flat parser reads as the next FLAG
+ *  - embedded whitespace, which is one token here and two on a shell round-trip
+ */
+export declare function isModelSpec(value: unknown): value is string;
+export declare function sanitizeGroupModels(value: unknown): Record<ChildGroup, string>;
+/**
+ * The `['--model', spec]` fragment for a resolved cell, or `[]` for `inherit`.
+ *
+ * NEVER `--provider`. Adding it is what turns pi's loud "model not found, exit
+ * 1" into `buildFallbackModel`'s silent synthetic model at exit 0 — the branch
+ * is `if (provider)` in pi's model-resolver, and a canonical `provider/id`
+ * reaches it through inference only when that provider already has a model the
+ * child can see. One flag keeps the loud failure loud.
+ *
+ * No `:thinking` suffix either. We emit an explicit `--thinking`, which pi
+ * prefers over the suffix, so a suffix would be a second dead source of truth
+ * for the same dial.
+ */
+export declare function modelArgs(spec: string): string[];
+/**
+ * The spec a built argv fragment actually carries, or `undefined` for a child
+ * that will resolve pi's saved default.
+ *
+ * Read BACK OUT of the argv rather than threaded alongside it, deliberately. The
+ * argv is what the child runs; a second field carrying "the model we meant"
+ * could disagree with it after any future edit, and the one consumer — the
+ * dead-backend probe — must ask about the endpoint the child will really use.
+ */
+export declare function modelSpecFromArgs(args: readonly string[]): string | undefined;
+/**
+ * Split a stored spec on its FIRST slash.
+ *
+ * `openrouter/z-ai/glm-4.6` is provider `openrouter` and id `z-ai/glm-4.6`:
+ * OpenRouter-style ids contain slashes of their own, and splitting on the last
+ * one would invent the provider `openrouter/z-ai`. Returns `undefined` for a
+ * spec with no slash, which `inherit` is and a canonical spec never is.
+ */
+export declare function splitSpec(spec: string): {
+    provider: string;
+    id: string;
+} | undefined;

package/dist/config/group-models.js

@@ -0,0 +1,117 @@
+/**
+ * Which model each child group runs on — the second table keyed on ChildGroup.
+ *
+ * PURE MODULE, like reasoning.ts and groups.ts: config.ts imports this during
+ * its own evaluation, so nothing here may have a runtime side effect.
+ *
+ * WHY THERE IS NO MODE ENUM
+ * -------------------------
+ * reasoningMode has four modes because there is a measured, shipped table worth
+ * a one-word "use the project's numbers", plus meaningful global on/off. Neither
+ * exists here. A model id is machine-local, so there can be no shipped table,
+ * and "all models on" is not a sentence. A mode enum would be four states of
+ * which three are unreachable.
+ *
+ * WHY THE CELL IS A STRING AND NOT A STRUCT
+ * -----------------------------------------
+ * `provider/id` is exactly what pi's `--model` takes, so the stored value goes
+ * to argv untouched. The round-trip property in config-items.test.ts needs the
+ * stored value recoverable verbatim from the offered label; a struct forces a
+ * format/parse pair that can drift.
+ */
+import { sanitizeGroupRecord } from './groups.js';
+/**
+ * The cell value meaning "emit no `--model`". Identical in spirit to `inherit`
+ * in the reasoning table, and identical in effect: an all-`inherit` table makes
+ * every child's argv byte-identical to a build without this feature.
+ *
+ * It is not a legal `provider/id` — pi rejects an unslashed pattern that matches
+ * no model — so it cannot collide with a real spec.
+ */
+export const MODEL_INHERIT = 'inherit';
+/** Every cell on `inherit`. The shipped default, and deliberately not a table. */
+export const DEFAULT_GROUP_MODELS = {
+    research: MODEL_INHERIT,
+    'research:files': MODEL_INHERIT,
+    'research:apis': MODEL_INHERIT,
+    'research:context': MODEL_INHERIT,
+    'research:tooling': MODEL_INHERIT,
+    phase: MODEL_INHERIT,
+    planning: MODEL_INHERIT,
+    plan: MODEL_INHERIT,
+    gate: MODEL_INHERIT,
+    extraction: MODEL_INHERIT,
+    implementation: MODEL_INHERIT
+};
+/**
+ * SHAPE ONLY, never existence.
+ *
+ * A config written on machine A must survive a session on machine B whose
+ * provider extension failed to load, or whose models.json is a different file
+ * entirely. Erasing a spec because this machine cannot resolve it would punish
+ * the two-machine user and lose a setting they never changed. Whether a spec
+ * resolves is asked once per session, where a warning can name it — not here,
+ * where the only available answer is deletion.
+ *
+ * So this rejects exactly what could RESHAPE argv, and nothing else:
+ *  - a non-string, which cannot be an argv token at all
+ *  - empty or whitespace-only, which pi would read as a missing value and
+ *    consume the following flag as the model pattern
+ *  - a leading `-`, which pi's flat parser reads as the next FLAG
+ *  - embedded whitespace, which is one token here and two on a shell round-trip
+ */
+export function isModelSpec(value) {
+    if (typeof value !== 'string')
+        return false;
+    if (value.trim() !== value || value.length === 0)
+        return false;
+    if (value.startsWith('-'))
+        return false;
+    return !/\s/.test(value);
+}
+export function sanitizeGroupModels(value) {
+    return sanitizeGroupRecord(value, isModelSpec, () => MODEL_INHERIT);
+}
+/**
+ * The `['--model', spec]` fragment for a resolved cell, or `[]` for `inherit`.
+ *
+ * NEVER `--provider`. Adding it is what turns pi's loud "model not found, exit
+ * 1" into `buildFallbackModel`'s silent synthetic model at exit 0 — the branch
+ * is `if (provider)` in pi's model-resolver, and a canonical `provider/id`
+ * reaches it through inference only when that provider already has a model the
+ * child can see. One flag keeps the loud failure loud.
+ *
+ * No `:thinking` suffix either. We emit an explicit `--thinking`, which pi
+ * prefers over the suffix, so a suffix would be a second dead source of truth
+ * for the same dial.
+ */
+export function modelArgs(spec) {
+    return spec === MODEL_INHERIT ? [] : ['--model', spec];
+}
+/**
+ * The spec a built argv fragment actually carries, or `undefined` for a child
+ * that will resolve pi's saved default.
+ *
+ * Read BACK OUT of the argv rather than threaded alongside it, deliberately. The
+ * argv is what the child runs; a second field carrying "the model we meant"
+ * could disagree with it after any future edit, and the one consumer — the
+ * dead-backend probe — must ask about the endpoint the child will really use.
+ */
+export function modelSpecFromArgs(args) {
+    const i = args.indexOf('--model');
+    return i === -1 ? undefined : args[i + 1];
+}
+/**
+ * Split a stored spec on its FIRST slash.
+ *
+ * `openrouter/z-ai/glm-4.6` is provider `openrouter` and id `z-ai/glm-4.6`:
+ * OpenRouter-style ids contain slashes of their own, and splitting on the last
+ * one would invent the provider `openrouter/z-ai`. Returns `undefined` for a
+ * spec with no slash, which `inherit` is and a canonical spec never is.
+ */
+export function splitSpec(spec) {
+    const i = spec.indexOf('/');
+    if (i <= 0 || i === spec.length - 1)
+        return undefined;
+    return { provider: spec.slice(0, i), id: spec.slice(i + 1) };
+}

package/dist/config/groups.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The child roster — which children exist, and which of them share one setting.
+ *
+ * Split out of reasoning.ts because the roster is not about reasoning. Two
+ * tables are keyed on it now (thinking level, and model), and a third would be
+ * no more surprising. A roster named after one of its consumers reads as though
+ * adding a second consumer were a special case.
+ *
+ * PURE MODULE, for the same reason reasoning.ts is: config.ts imports both
+ * during its own module evaluation, so neither may take an import with a runtime
+ * side effect.
+ *
+ * Grouped by JOB, not by spawn mechanism — two children that both go through
+ * `runWorker` (a research worker and a verify gate) want different amounts of
+ * thinking, while `refine` in phases.ts and `compress-label` in title-label.ts
+ * want the same amount and share the `phase` cell.
+ *
+ * - `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, so a level can be paid for in
+ *                  one worker without paying for it in the other three
+ * - `phase`        refine, verify-tooling, grill, compose, critique, compress-label
+ * - `planning`     /task-auto's planning children — clarify, decompose, and the
+ *                  extract/coverage passes around them
+ * - `plan`         /task-plan's question and answer children
+ * - `gate`         enforce, verify, lint-fix, final-fix, recommend
+ * - `extraction`   the --no-tools focused docs/fetch extractors
+ * - `implementation` the host-session turn that writes the code (not a child)
+ */
+export type ChildGroup = 'research' | 'research:files' | 'research:apis' | 'research:context' | 'research:tooling' | 'phase' | 'planning' | 'plan' | 'gate' | 'extraction' | 'implementation';
+export declare const CHILD_GROUPS: readonly ChildGroup[];
+/**
+ * Which group each NAMED child belongs to.
+ *
+ * The name is the one `runChild` is called with, so this is exhaustive over the
+ * children that carry one. `config/groups.test.ts` scans the source for those
+ * call sites and fails if a name is missing here. A defaulting lookup would let a
+ * phase added later opt itself out of the tables without anyone deciding to.
+ *
+ * The gate and extraction groups are NOT here: those children reach the model
+ * through `groupChildArgs('gate' | 'extraction')` at call sites with no name in
+ * scope (gate-deps.ts, fetch-core.ts, docs-core.ts, pi-worker-docs.ts). The four
+ * research workers do have a name — their `spec.label` — so they are here.
+ */
+export declare const GROUP_BY_CHILD: Readonly<Record<string, ChildGroup>>;
+/**
+ * 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 groupForChild(name: string): ChildGroup | undefined;
+/**
+ * For a `research:*` group, the group a stored config falls back to when its own
+ * key is missing. Every other group maps to `undefined`.
+ */
+export declare const RESEARCH_SUBGROUP_PARENT: Readonly<Partial<Record<ChildGroup, ChildGroup>>>;
+/**
+ * Always returns a COMPLETE record, never a partial one, for any per-group table.
+ *
+ * A hand-edited file missing a group, or one carrying a group from a future
+ * version, must not reach a resolver as a hole: `table[group]` would be
+ * `undefined`, and every call site would need its own fallback. Filling the gaps
+ * here means the type is true at the only place that constructs the value.
+ *
+ * `fallbackFor` is a function of the GROUP, not a value. The reasoning table
+ * falls back per group to its measured default; the model table falls back to
+ * the constant `inherit`. A scalar parameter cannot express the first, which is
+ * the one that already ships.
+ */
+export declare function sanitizeGroupRecord<T>(value: unknown, valid: (v: unknown) => v is T, fallbackFor: (group: ChildGroup) => T): Record<ChildGroup, T>;

package/dist/config/groups.js

@@ -0,0 +1,110 @@
+export const CHILD_GROUPS = [
+    'research',
+    'research:files',
+    'research:apis',
+    'research:context',
+    'research:tooling',
+    'phase',
+    'planning',
+    'plan',
+    'gate',
+    'extraction',
+    'implementation'
+];
+/**
+ * Which group each NAMED child belongs to.
+ *
+ * The name is the one `runChild` is called with, so this is exhaustive over the
+ * children that carry one. `config/groups.test.ts` scans the source for those
+ * call sites and fails if a name is missing here. A defaulting lookup would let a
+ * phase added later opt itself out of the tables without anyone deciding to.
+ *
+ * The gate and extraction groups are NOT here: those children reach the model
+ * through `groupChildArgs('gate' | 'extraction')` at call sites with no name in
+ * scope (gate-deps.ts, fetch-core.ts, docs-core.ts, pi-worker-docs.ts). The four
+ * research workers do have a name — their `spec.label` — so they are here.
+ */
+export const 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',
+    // ── research: task/phases.ts `workerSpecs`, keyed on the spec's LABEL ─────
+    'worker:files': 'research:files',
+    'worker:apis': 'research:apis',
+    'worker:context': 'research:context',
+    'worker:tooling': 'research:tooling'
+};
+/**
+ * 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 groupForChild(name) {
+    return GROUP_BY_CHILD[name];
+}
+/**
+ * For a `research:*` group, the group a stored config falls back to when its own
+ * key is missing. Every other group maps to `undefined`.
+ */
+export 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, for any per-group table.
+ *
+ * A hand-edited file missing a group, or one carrying a group from a future
+ * version, must not reach a resolver as a hole: `table[group]` would be
+ * `undefined`, and every call site would need its own fallback. Filling the gaps
+ * here means the type is true at the only place that constructs the value.
+ *
+ * `fallbackFor` is a function of the GROUP, not a value. The reasoning table
+ * falls back per group to its measured default; the model table falls back to
+ * the constant `inherit`. A scalar parameter cannot express the first, which is
+ * the one that already ships.
+ */
+export function sanitizeGroupRecord(value, valid, fallbackFor) {
+    const stored = typeof value === 'object' && value !== null && !Array.isArray(value) ?
+        value
+        : {};
+    const out = {};
+    for (const group of CHILD_GROUPS) {
+        const own = stored[group];
+        if (valid(own)) {
+            out[group] = own;
+            continue;
+        }
+        // A `research:*` key the stored config never had falls back to its
+        // parent `research` value, so a config written before the split keeps
+        // meaning what it meant.
+        const parent = RESEARCH_SUBGROUP_PARENT[group];
+        const inherited = parent === undefined ? undefined : stored[parent];
+        out[group] = valid(inherited) ? inherited : fallbackFor(group);
+    }
+    return out;
+}