@mjasnikovs/pi-task 0.38.30 → 0.38.32

package/dist/config/register.js

@@ -1,11 +1,14 @@
 import { getKeybindings, SettingsList, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { clampToModel, supportedThinkingLevels } from '../shared/reasoning-capability.js';
+import { isModelSpec, MODEL_INHERIT, splitSpec } from './group-models.js';
+import { OptionPicker } from './option-picker.js';
 import { registerBridgeCommand } from '../remote/bridge.js';
 import { readPkgVersion } from '../shared/pkg-version.js';
 import { SEARCH_PROVIDERS, SEARCH_PROVIDER_LABELS, providerForLabel } from '../workers/search-types.js';
 import { COMMAND_TIMEOUT_OPTIONS, DEBUG_LOG_OPTIONS, getConfig, sanitizeDebugLogs, saveConfig, STREAM_INACTIVITY_OPTIONS } from './config.js';
 import { listInstalledExtensions } from './extension-list.js';
 import { listGuardableTools } from './tool-list.js';
-import { REASONING_GROUPS, REASONING_MODES, sanitizeReasoningMode, REASONING_GROUP_HELP, REASONING_SETTINGS, effectiveReasoning, resolveReasoning } from './reasoning.js';
+import { CHILD_GROUPS, REASONING_MODES, sanitizeReasoningMode, REASONING_GROUP_HELP, MODEL_GROUP_HELP, REASONING_SETTINGS, effectiveReasoning, resolveReasoning } from './reasoning.js';
 // Version in the title so a bug report or screenshot says which build it came
 // from without anyone having to go look it up.
 const CONFIG_TITLE = `pi-task ${readPkgVersion()} settings`;
@@ -73,6 +76,11 @@ export const SECTIONS = [
     { key: 'session', title: 'session' },
     { key: 'checks', title: 'after each task' },
     { key: 'research', title: 'research' },
+    // Immediately before `reasoning`, and a BLOCK of its own rather than a
+    // second column on the think: rows. Interleaving would double one block to
+    // 22 rows and print the `├─ files` tree branches twice, meaning two
+    // different things a line apart.
+    { key: 'models', title: 'models' },
     { key: 'reasoning', title: 'reasoning' },
     { key: 'unattended', title: 'unattended' },
     { key: 'logging', title: 'logging' },
@@ -83,6 +91,16 @@ export const SECTIONS = [
 ];
 /** Marks a header row, so onChange can ignore one and tests can find them. */
 export const SECTION_ID_PREFIX = 'section:';
+/**
+ * Is this row scenery rather than a setting?
+ *
+ * Reads the ID, not `values`. Those two agreed only while every real row cycled
+ * a list: a picker row has a `submenu` and may carry `values` purely for the
+ * round-trip contract, so "no values" stopped meaning "not a row". Both
+ * `sectionHeader` and `sectionGap` already stamp the prefix, so this is exact
+ * rather than a heuristic, and all three consumers ask the same question.
+ */
+export const isSectionRow = (item) => item.id.startsWith(SECTION_ID_PREFIX);
 /**
  * An inert titled row. No `values` ⇒ SettingsList's Enter handler no-ops on it,
  * and {@link SkipInertRows} steps the cursor straight over it.
@@ -335,7 +353,7 @@ const REASON_ID_PREFIX = 'reason:';
  * So a child is drawn as a tree branch under its parent and loses the repeated
  * `think: research:` prefix, the same text at the head of 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
+ * position in {@link CHILD_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.
@@ -345,17 +363,106 @@ export function reasoningRowLabel(group) {
     if (colon < 0)
         return `think: ${group}`;
     const parent = group.slice(0, colon);
-    const nextIsSibling = REASONING_GROUPS[REASONING_GROUPS.indexOf(group) + 1]?.startsWith(`${parent}:`);
+    const nextIsSibling = CHILD_GROUPS[CHILD_GROUPS.indexOf(group) + 1]?.startsWith(`${parent}:`);
     return `   ${nextIsSibling ? '├─' : '└─'} ${group.slice(colon + 1)}`;
 }
-export function reasoningItems() {
-    return REASONING_GROUPS.map(group => ({
+const MODEL_ID_PREFIX = 'model:';
+/** No registry reachable. Every row still renders; nothing narrows. */
+export const EMPTY_CATALOG = { specs: [], facts: () => undefined };
+export function modelItems(catalog) {
+    return CHILD_GROUPS.map(group => ({
+        id: MODEL_ID_PREFIX + group,
+        section: 'models',
+        label: reasoningRowLabel(group).replace('think: ', 'model: '),
+        headlessLabel: `model: ${group}`,
+        description: MODEL_GROUP_HELP[group],
+        // The COMPLETE accepted vocabulary, which is what the round-trip
+        // property quantifies over. With nothing discovered it is `['inherit']`:
+        // length 1, still selectable, still not a header. No degenerate case.
+        values: [MODEL_INHERIT, ...catalog.specs],
+        submenu: () => [
+            { value: MODEL_INHERIT, label: MODEL_INHERIT, description: "pi's own default" },
+            ...catalog.specs.map(spec => ({
+                value: spec,
+                label: spec,
+                ...(catalog.note?.(spec) === undefined ? {} : { description: catalog.note(spec) })
+            }))
+        ],
+        // VERBATIM, even when absent from `values` — the vanished-model case,
+        // where the row must still say what the config holds so the hint that
+        // names it has something to point at.
+        format: cfg => cfg.groupModels[group],
+        apply: (cfg, chosen) => applyGroupModel(cfg, group, chosen, catalog)
+    }));
+}
+/**
+ * Write a group's model, and RE-CLAMP its thinking cell in the same write.
+ *
+ * Narrowing the picker does nothing about a level already stored from before the
+ * model was chosen: on its own it would freeze a lie into a cell it has just
+ * made unconfigurable. `syncRows` re-renders every row, so the user sees the
+ * level move.
+ *
+ * The clamp reads `resolveReasoning`, NOT `cfg.reasoningLevels[group]`. In mode
+ * `on` or `off` the stored table is ignored entirely, so a user in `on` who
+ * picks a non-reasoning model has a stored cell that says nothing and an
+ * effective `medium` the model will erase — and comparing the stored cell would
+ * see no clamp and stay silent about a real lie.
+ *
+ * Guarded on the clamp actually MOVING something, because `applyReasoningLevel`
+ * flips the whole table to `custom`, and picking a fully-capable model must not
+ * do that as a side effect.
+ */
+export function applyGroupModel(cfg, group, chosen, catalog) {
+    // MEMBERSHIP, not just shape. A stored spec naming a vanished model must
+    // survive — that is the sanitizer's job, and `format` still renders it — but
+    // it may only ever ARRIVE here from the picker, which offers exactly these.
+    // Without this, the panel could write a spec this machine cannot resolve.
+    if (!isModelSpec(chosen))
+        return;
+    if (chosen !== MODEL_INHERIT && !catalog.specs.includes(chosen))
+        return;
+    cfg.groupModels = { ...cfg.groupModels, [group]: chosen };
+    const facts = catalog.facts(chosen);
+    if (facts === undefined)
+        return;
+    const wanted = resolveReasoning(group, cfg);
+    if (wanted === 'inherit')
+        return;
+    const clamped = clampToModel(facts, wanted);
+    if (clamped !== wanted)
+        applyReasoningLevel(cfg, group, clamped);
+}
+/**
+ * The levels a row may offer, given the model that row's group will run on.
+ *
+ * The INTERSECTION with `REASONING_SETTINGS`, not `supportedThinkingLevels`
+ * directly: that returns the whole ladder including `xhigh` and `max`, which
+ * this menu excludes on purpose (see reasoning.ts) because pi's own UI may not
+ * offer them. A model declaring `xhigh` must not smuggle it in here.
+ */
+export function offeredLevels(facts) {
+    if (facts === undefined)
+        return [...REASONING_SETTINGS];
+    const supported = supportedThinkingLevels(facts);
+    return REASONING_SETTINGS.filter(s => s === 'inherit' || supported.includes(s));
+}
+export function reasoningItems(catalog = EMPTY_CATALOG) {
+    return CHILD_GROUPS.map(group => ({
         id: REASON_ID_PREFIX + group,
         section: 'reasoning',
         label: reasoningRowLabel(group),
         headlessLabel: `think: ${group}`,
         description: REASONING_GROUP_HELP[group],
         values: [...REASONING_SETTINGS],
+        // A submenu, not a cycle, because what this row may offer depends on the
+        // model row above it — which the user can change while the panel is
+        // open. `values` is static and computed when the rows are built, and
+        // `syncRows` can only re-ask `format`; a factory runs at Enter-time.
+        submenu: (cfg) => offeredLevels(catalog.facts(cfg.groupModels[group])).map(level => ({
+            value: level,
+            label: level
+        })),
         // 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
         // run does not use is worse than no row. As a FUNCTION rather than a
@@ -441,18 +548,29 @@ const DOWN_KEY = '\x1b[B';
  *
  * It drives the list through its own public `handleInput` — pressing the very
  * key the user pressed, N times — rather than reaching for the private
- * `selectedIndex`. The mirror it keeps cannot drift: with search off and no
- * submenus, up and down are the only two things that move that index.
+ * `selectedIndex`. With search off, up and down are the only two things that
+ * move that index — EXCEPT while a submenu is open, when `SettingsList` forwards
+ * everything to the submenu and returns without moving it at all. So a picker
+ * suspends this entirely; see `suspended`.
  */
 class SkipInertRows {
     list;
     selectable;
+    suspended;
     index = 0;
     constructor(list, 
     /** True where a row can be selected, in the list's own order. */
-    selectable) {
+    selectable, 
+    /**
+     * True while a picker is open. The list then owns every key, so this
+     * must not intercept — see the flag's own comment in
+     * {@link createSettingsPanel}. Defaulted so the constructor's own
+     * opening walk, and every existing test, are unaffected.
+     */
+    suspended = () => false) {
         this.list = list;
         this.selectable = selectable;
+        this.suspended = suspended;
         // The first row is a header, so the panel would open on it. Only
         // synthesise the keypress if it is actually bound to "down" — feeding
         // a key the list ignores would move the mirror and not the cursor.
@@ -471,9 +589,10 @@ class SkipInertRows {
     }
     handleInput(data) {
         const kb = getKeybindings();
-        const step = kb.matches(data, 'tui.select.down') ? 1
-            : kb.matches(data, 'tui.select.up') ? -1
-                : 0;
+        const step = this.suspended() ? 0
+            : kb.matches(data, 'tui.select.down') ? 1
+                : kb.matches(data, 'tui.select.up') ? -1
+                    : 0;
         if (step === 0) {
             this.list.handleInput(data);
             return;
@@ -508,10 +627,31 @@ export function createSettingsPanel(items, theme,
  * `reasoning off` beside rows still claiming `inherit`.
  */
 onChange, onCancel) {
-    // A row with no `values` is a header or the blank line above one.
-    const headerLabels = new Set(items.filter(i => i.values === undefined).map(i => i.label));
-    const list = new SettingsList(items, MAX_VISIBLE, makeTheme(theme, label => headerLabels.has(label.trimEnd())), (id, newValue) => onChange(id, newValue, list), onCancel);
-    return new BorderedBox(new SkipInertRows(list, items.map(i => (i.values?.length ?? 0) > 0)), CONFIG_TITLE, s => theme.fg('borderMuted', s), s => theme.fg('accent', theme.bold(s)), settingsBodyHeight(items.map(i => i.description), MAX_VISIBLE, OVERLAY_WIDTH - 8));
+    const headerLabels = new Set(items.filter(isSectionRow).map(i => i.label));
+    /**
+     * True while a picker is open, so SkipInertRows stops intercepting arrows.
+     *
+     * `SettingsList.handleInput` delegates to an open submenu and RETURNS, so
+     * `selectedIndex` never moves while one is up. SkipInertRows keeps its own
+     * mirror of that index and replays the key once per row it skips — so
+     * without this flag, one arrow press inside a picker moves the mirror off
+     * the real cursor AND arrives in the picker two or three times when the walk
+     * crosses a section boundary.
+     */
+    let submenuOpen = false;
+    const settingItems = items.map(({ submenuOptions, ...row }) => submenuOptions === undefined ? row : ({
+        ...row,
+        submenu: (currentValue, done) => {
+            submenuOpen = true;
+            return new OptionPicker(submenuOptions(), currentValue, theme, v => {
+                submenuOpen = false;
+                done(v);
+            });
+        }
+    }));
+    const list = new SettingsList(settingItems, MAX_VISIBLE, makeTheme(theme, label => headerLabels.has(label.trimEnd())), (id, newValue) => onChange(id, newValue, list), onCancel);
+    return new BorderedBox(new SkipInertRows(list, items.map(i => !isSectionRow(i)
+        && ((i.values?.length ?? 0) > 0 || i.submenuOptions !== undefined)), () => submenuOpen), CONFIG_TITLE, s => theme.fg('borderMuted', s), s => theme.fg('accent', theme.bold(s)), settingsBodyHeight(items.map(i => i.description), MAX_VISIBLE, OVERLAY_WIDTH - 8));
 }
 /**
  * Every settings row for this session, fixed and DISCOVERED, in menu order.
@@ -524,11 +664,20 @@ onChange, onCancel) {
  * Fixed rows come before discovered ones within a section, so a freshly
  * installed extension appends rather than reshuffling the menu.
  */
-export function configRows(installed, tools = []) {
+export function configRows(installed, tools = [], 
+// A third positional with a default, exactly like `tools`, so every existing
+// test stays deterministic and no test has to know a registry exists.
+catalog = EMPTY_CATALOG) {
     // The discovered rows carry a section like every other row — the per-tool
     // watchdog exemptions under `timeouts` (they are exemptions FROM that
     // timeout), and the per-extension toggles under their own heading.
-    return [...ITEMS, ...reasoningItems(), ...toolItems(tools), ...extensionItems(installed)];
+    return [
+        ...ITEMS,
+        ...modelItems(catalog),
+        ...reasoningItems(catalog),
+        ...toolItems(tools),
+        ...extensionItems(installed)
+    ];
 }
 /** Render `rows` for the current config, grouped under their section headers. */
 export function renderRows(cfg, rows) {
@@ -542,6 +691,7 @@ export function renderRows(cfg, rows) {
             description: i.description,
             currentValue: i.format(cfg),
             values: i.values ?? ['on', 'off'],
+            ...(i.submenu === undefined ? {} : { submenuOptions: () => i.submenu(cfg) }),
             ...(i.headlessLabel === undefined ? {} : { headlessLabel: i.headlessLabel })
         }));
         // An empty section prints no header. `extensions` has no fixed rows at
@@ -555,8 +705,8 @@ export function renderRows(cfg, rows) {
     return out;
 }
 /** The full settings row list for the current config, in menu order. */
-export function panelItems(cfg, installed, tools = []) {
-    return renderRows(cfg, configRows(installed, tools));
+export function panelItems(cfg, installed, tools = [], catalog = EMPTY_CATALOG) {
+    return renderRows(cfg, configRows(installed, tools, catalog));
 }
 /**
  * Re-ask every row what it now displays, and write the answers back.
@@ -574,6 +724,59 @@ export function syncRows(cfg, rows, list) {
     for (const row of rows)
         list.updateValue(row.id, row.format(cfg));
 }
+/**
+ * The model rows' offer list, read live when the menu opens.
+ *
+ * `getAvailable()`, never `getAll()`: an unauthed model would spawn a child that
+ * exits 1 on every phase of that group, and offering it would be offering a
+ * config that cannot work.
+ *
+ * A provider registered by a host EXTENSION is offered with a note rather than
+ * hidden. Children run `--no-extensions`, which disables discovery only — pi
+ * still loads every explicit `-e` path, and `childBaseArgs` injects one per
+ * whitelisted extension. So such a model works in a child exactly when its
+ * extension is whitelisted, and we cannot tell which extension that is:
+ * `getRegisteredProviderIds()` gives ids, and the `{name, config, extensionPath}`
+ * triples live in the runner's internal state, drained at bind. Choosing it with
+ * the wrong whitelist fails LOUDLY — the child sees no such provider, so pi's
+ * resolver reports "not found" and exits 1 — which is why a note is enough.
+ */
+function liveCatalog(ctx) {
+    // Same contract as the tool enumeration above, for the same reason: the
+    // model runtime is not guaranteed usable at the moment a command runs, and a
+    // registry that cannot answer must cost the model rows, never the menu.
+    // Every row below still renders; `EMPTY_CATALOG` offers only `inherit` and
+    // narrows nothing, which is exactly the pre-feature panel.
+    let registry;
+    let available;
+    let fromExtension;
+    try {
+        registry = ctx.modelRegistry;
+        available = registry.getAvailable();
+        fromExtension = new Set(registry.getRegisteredProviderIds());
+    }
+    catch {
+        return EMPTY_CATALOG;
+    }
+    return {
+        specs: available.map(m => `${m.provider}/${m.id}`),
+        note: spec => {
+            const parts = splitSpec(spec);
+            return parts && fromExtension.has(parts.provider) ?
+                'provider comes from an extension — whitelist it under child extensions, '
+                    + "or this group's children exit 1"
+                : undefined;
+        },
+        facts: spec => {
+            // `inherit` means the session's own model, which is what a child
+            // resolves today. Its facts are what the thinking row must narrow to.
+            if (spec === MODEL_INHERIT)
+                return ctx.model;
+            const parts = splitSpec(spec);
+            return parts ? registry.find(parts.provider, parts.id) : undefined;
+        }
+    };
+}
 async function handleTaskConfig(_args, ctx, getTools = () => []) {
     const cfg = {
         ...getConfig(),
@@ -582,7 +785,8 @@ async function handleTaskConfig(_args, ctx, getTools = () => []) {
         // Copied for the same reason as the two arrays above: the panel mutates
         // its own draft, and sharing the live object would apply half-made
         // choices to running children before the user finished choosing.
-        reasoningLevels: { ...getConfig().reasoningLevels }
+        reasoningLevels: { ...getConfig().reasoningLevels },
+        groupModels: { ...getConfig().groupModels }
     };
     // Enumerated live at open so an installed extension appears and an
     // uninstalled one vanishes without pi-task doing any bookkeeping. A failed
@@ -592,17 +796,18 @@ async function handleTaskConfig(_args, ctx, getTools = () => []) {
     // one: getAllTools() throws until the extension runtime is initialized, so
     // it can only be read here, when the menu opens, never at registration.
     const tools = getTools();
+    const catalog = liveCatalog(ctx);
     if (ctx.mode !== 'tui') {
         // Built from panelItems and reading the SAME `format` the panel does,
         // so the two renderings cannot disagree about what a setting says. A
         // second walk of the same tables is the one place nobody would notice
         // them drifting, because a headless run has no panel to compare against.
-        const lines = panelItems(cfg, installed, tools)
+        const lines = panelItems(cfg, installed, tools, catalog)
             // The blank rows between sections are there to give the TUI air.
             // One line of `|`-joined text has none to give, and an empty label
             // would print as a stray `[]`.
             .filter(i => i.label !== '')
-            .map(i => i.values === undefined ?
+            .map(i => isSectionRow(i) ?
             `[${i.label.trim()}]`
             : `${(i.headlessLabel ?? i.label).padEnd(22)} ${i.currentValue}`);
         ctx.ui.notify(lines.join('  |  '), 'info');
@@ -610,7 +815,7 @@ async function handleTaskConfig(_args, ctx, getTools = () => []) {
     }
     // Built ONCE and shared by the renderer, the dispatch and the refresh, so
     // all three necessarily agree about which rows exist.
-    const rows = configRows(installed, tools);
+    const rows = configRows(installed, tools, catalog);
     await ctx.ui.custom((_tui, theme, _kb, done) => createSettingsPanel(renderRows(cfg, rows), theme, (id, newValue, list) => {
         // Every row parses its own value. There is no generic
         // fallback and no prefix ladder, so a row that forgets to

package/dist/index.js

@@ -6,6 +6,8 @@ import { registerWorkers } from './workers/index.js';
 import { registerRemote } from './remote/register.js';
 import { registerCommandWatchdog } from './task/command-watchdog.js';
 import { registerStreamWatchdog } from './task/stream-watchdog.js';
+import { registerImplementationGuards } from './task/implementation-guards.js';
+import { registerModelHoldRestore } from './task/model-hold-stash.js';
 export default function (pi) {
     registerConfig(pi);
     registerTask(pi);
@@ -15,4 +17,6 @@ export default function (pi) {
     registerRemote(pi);
     registerCommandWatchdog(pi);
     registerStreamWatchdog(pi);
+    registerImplementationGuards(pi);
+    registerModelHoldRestore(pi);
 }

package/dist/remote/push.js

@@ -1,13 +1,7 @@
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import webpush from 'web-push';
-/** Resolve the XDG data-home base. Same env-or-homedir shape the docs cache uses
- *  (workers/docs-core.ts), but rooted at data-home rather than cache-home: what
- *  lives under here is not reconstructible by re-fetching. */
-function dataHome() {
-    return process.env.XDG_DATA_HOME?.trim() || path.join(os.homedir(), '.local', 'share');
-}
+import { dataHome } from '../shared/data-home.js';
 /** Where the VAPID keypair is persisted. The browser subscribes with this
  *  public key as its applicationServerKey (see ui-script.ts), so the pair has to
  *  outlive the process that created it. */

package/dist/shared/command-watchdog.d.ts

@@ -122,3 +122,66 @@ export declare class CommandWatchdog {
  * the call it watches.
  */
 export declare const realTimerDeps: Pick<WatchdogDeps, 'schedule' | 'cancel'>;
+/** What the command watchdog recorded when it killed a child attempt. */
+export interface CommandKill {
+    toolName: string;
+    timeoutMs: number;
+    /** The command line itself, when the tool carried one — quoted into the hint
+     *  so the fresh child knows which call it must not repeat unbounded. */
+    detail?: string;
+}
+/**
+ * The tool-call fields the child-side watchdog reads. Structural rather than
+ * `ToolCall` from child-process.ts, so this module keeps its zero imports and a
+ * caller cannot be forced to reach for the runner's types to arm a timer.
+ */
+export interface WatchedToolCall {
+    name: string;
+    toolCallId?: string;
+    args: unknown;
+}
+/**
+ * Build the child-side command watchdog for ONE attempt: a per-tool-call timer
+ * machine whose `onFire` aborts `signal`, which runChild turns into a
+ * process-GROUP kill — reaping the hung command itself, not just the pi child
+ * holding it.
+ *
+ * LIMIT: the group kill only reaches processes still IN the group. A hung command
+ * that detached a daemon (setsid, nohup, a background dev server) leaves it
+ * running, so the fresh attempt can hit a port the dead attempt's escapee still
+ * holds. There is no cheap fix from here; the restart hint's "check current state"
+ * line is the mitigation.
+ *
+ * Returns null when the watchdog is off, so the caller keeps the plain timeout
+ * signal and no per-call bookkeeping happens at all.
+ */
+export declare function commandWatch(timeoutMs: number): {
+    onStart: (call: WatchedToolCall) => void;
+    onEnd: (toolCallId: string | undefined) => void;
+    killed: () => CommandKill | undefined;
+    signal: AbortSignal;
+    clear: () => void;
+} | null;
+/**
+ * The per-command ceiling for attempt N, halving each time a hang recurs.
+ *
+ * The first attempt gets the full configured ceiling — a genuinely slow build or
+ * test suite deserves it. But every hang-caused restart carries
+ * commandTimeoutHint, which tells the model in as many words to bound its
+ * command; a SECOND hang means it ignored an explicit instruction, and a third
+ * means it ignored it twice. Giving a non-complying child the full ceiling again
+ * makes the worst case three times the ceiling, resting entirely on the model
+ * obeying prose. Halving bounds it at under twice the ceiling while costing a
+ * complying child nothing.
+ *
+ * `priorHangs` counts watchdog kills specifically, NOT total restarts — the
+ * restart budget is shared with loop kills, and a child restarted for LOOPING
+ * never received the bound-your-command hint, so its first hang still deserves
+ * the full ceiling. Only a hang after a hang is defiance.
+ *
+ * Floored at 30s so repeated halving cannot shrink the ceiling to something no
+ * real command could finish inside — but the floor is `min(base, 30s)`, never
+ * above the configured ceiling, so a caller asking for 10s keeps 10s at every
+ * hang count. A base of 0 or less disables the watchdog and stays 0.
+ */
+export declare function commandCeilingForAttempt(baseMs: number, priorHangs: number): number;

package/dist/shared/command-watchdog.js

@@ -172,3 +172,90 @@ export const realTimerDeps = {
     schedule: (fn, ms) => setTimeout(fn, ms),
     cancel: handle => clearTimeout(handle)
 };
+/**
+ * Build the child-side command watchdog for ONE attempt: a per-tool-call timer
+ * machine whose `onFire` aborts `signal`, which runChild turns into a
+ * process-GROUP kill — reaping the hung command itself, not just the pi child
+ * holding it.
+ *
+ * LIMIT: the group kill only reaches processes still IN the group. A hung command
+ * that detached a daemon (setsid, nohup, a background dev server) leaves it
+ * running, so the fresh attempt can hit a port the dead attempt's escapee still
+ * holds. There is no cheap fix from here; the restart hint's "check current state"
+ * line is the mitigation.
+ *
+ * Returns null when the watchdog is off, so the caller keeps the plain timeout
+ * signal and no per-call bookkeeping happens at all.
+ */
+export function commandWatch(timeoutMs) {
+    if (!(timeoutMs > 0))
+        return null;
+    const ctrl = new AbortController();
+    // pi's toolCallId pairs start↔end. When it is absent (a fake stream in a
+    // test, an older pi), fall back to one shared slot: tool executions in a
+    // child are sequential, so a single slot is still correctly paired.
+    const key = (id) => id ?? 'anon';
+    const details = new Map();
+    let killed;
+    const watchdog = new CommandWatchdog({
+        getTimeoutMs: () => timeoutMs,
+        ...realTimerDeps,
+        onFire: (toolCallId, toolName, ms) => {
+            killed = {
+                toolName,
+                timeoutMs: ms,
+                ...(details.has(toolCallId) ? { detail: details.get(toolCallId) } : {})
+            };
+            ctrl.abort();
+        }
+    });
+    return {
+        onStart: call => {
+            const id = key(call.toolCallId);
+            const args = call.args;
+            if (typeof args?.command === 'string') {
+                details.set(id, args.command.slice(0, 120));
+            }
+            watchdog.onStart(id, call.name);
+        },
+        onEnd: id => {
+            // Drop the command line with its call. The `'anon'` fallback above is a
+            // SHARED slot, so a stale entry would be attributed to whatever ran
+            // next: a `read` that later overran would be reported as
+            // "ran a `read` command (bun run dev)".
+            details.delete(key(id));
+            watchdog.onEnd(key(id));
+        },
+        killed: () => killed,
+        signal: ctrl.signal,
+        clear: () => watchdog.clearAll()
+    };
+}
+/**
+ * The per-command ceiling for attempt N, halving each time a hang recurs.
+ *
+ * The first attempt gets the full configured ceiling — a genuinely slow build or
+ * test suite deserves it. But every hang-caused restart carries
+ * commandTimeoutHint, which tells the model in as many words to bound its
+ * command; a SECOND hang means it ignored an explicit instruction, and a third
+ * means it ignored it twice. Giving a non-complying child the full ceiling again
+ * makes the worst case three times the ceiling, resting entirely on the model
+ * obeying prose. Halving bounds it at under twice the ceiling while costing a
+ * complying child nothing.
+ *
+ * `priorHangs` counts watchdog kills specifically, NOT total restarts — the
+ * restart budget is shared with loop kills, and a child restarted for LOOPING
+ * never received the bound-your-command hint, so its first hang still deserves
+ * the full ceiling. Only a hang after a hang is defiance.
+ *
+ * Floored at 30s so repeated halving cannot shrink the ceiling to something no
+ * real command could finish inside — but the floor is `min(base, 30s)`, never
+ * above the configured ceiling, so a caller asking for 10s keeps 10s at every
+ * hang count. A base of 0 or less disables the watchdog and stays 0.
+ */
+export function commandCeilingForAttempt(baseMs, priorHangs) {
+    if (!(baseMs > 0))
+        return 0;
+    const floor = Math.min(baseMs, 30_000);
+    return Math.max(floor, Math.round(baseMs / 2 ** priorHangs));
+}

package/dist/shared/data-home.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The XDG data-home base. Same env-or-homedir shape the docs cache uses
+ * (workers/docs-core.ts), but rooted at data-home rather than cache-home: what
+ * lives under here is not reconstructible by re-fetching.
+ */
+export declare function dataHome(): string;
+/** A file under this machine's pi-task state directory. */
+export declare function stateFile(name: string): string;

package/dist/shared/data-home.js

@@ -0,0 +1,14 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+/**
+ * The XDG data-home base. Same env-or-homedir shape the docs cache uses
+ * (workers/docs-core.ts), but rooted at data-home rather than cache-home: what
+ * lives under here is not reconstructible by re-fetching.
+ */
+export function dataHome() {
+    return process.env.XDG_DATA_HOME?.trim() || path.join(os.homedir(), '.local', 'share');
+}
+/** A file under this machine's pi-task state directory. */
+export function stateFile(name) {
+    return path.join(dataHome(), 'pi-task', name);
+}

package/dist/shared/model-endpoint.d.ts

@@ -1,5 +1,58 @@
 /** Base URLs of every custom provider pi is configured with (possibly none). */
 export declare function discoverModelEndpoints(agentDir?: string): string[];
+/**
+ * The provider/id a child pi process will actually resolve.
+ *
+ * Children carry no `-m` (CHILD_BASE_ARGS), so they fall back to pi's saved
+ * default — which is this, not the host session's model. `undefined` means we
+ * could not read it, and every caller here treats that as "do not guess".
+ */
+export interface ModelRef {
+    provider: string;
+    id: string;
+}
+export declare function defaultModelRef(agentDir?: string): ModelRef | undefined;
+/**
+ * The base URL one model is served from, or `undefined` for "not configured on
+ * this machine".
+ *
+ * Two files, two shapes, and the difference is not cosmetic. `models.json` is
+ * hand-written and hangs `baseUrl` off the PROVIDER; `models-store.json` is the
+ * cached remote catalogue and hangs it off each MODEL — its provider objects are
+ * `{models, checkedAt, lastModified, etag}` with no `baseUrl` key at all. A
+ * reader that knows only the first shape sees one endpoint on a machine that has
+ * fifteen.
+ *
+ * `undefined` is the honest answer for a model pi serves from `@earendil-works/
+ * pi-ai`'s built-in catalogue, whose URLs live in that package rather than on
+ * disk. We do not import it — see the header of this file — so we say we do not
+ * know, and the caller declines to probe rather than probing something else.
+ */
+export declare function modelBaseUrl(ref: ModelRef, agentDir?: string): string | undefined;
+/**
+ * What to probe on behalf of one child — the endpoint that child's own model
+ * uses, not every endpoint on the machine.
+ *
+ * The bug this closes is `probeModelEndpoints`'s `.some(Boolean)`: with a live
+ * cloud provider and a dead local one, the OR answers "reachable" and the stall
+ * guard is disarmed for a child that will never speak again. Handing it ONE url
+ * makes the OR a no-op and the verdict exact.
+ *
+ * `spec` is the child's OWN `provider/id`, as carried by its argv. `undefined`
+ * means the child carries no `--model` and will resolve pi's saved default,
+ * which is then the right thing to probe. Reading the saved default for a child
+ * that IS pinned asks about the wrong server in BOTH directions: it can kill a
+ * child whose own backend is healthy, and it can leave the guard disarmed for
+ * one whose backend is dead.
+ *
+ * Two escapes, both toward never killing:
+ *  - model known, endpoint not on disk (a built-in provider) → `[]`, which
+ *    `probeModelEndpoints` reads as reachable. We cannot see that server, so we
+ *    do not get a vote. Probing some OTHER provider's url instead would import a
+ *    false positive, which is the one thing today's blind OR never does.
+ *  - no readable default → today's behaviour, unchanged.
+ */
+export declare function childModelEndpoints(spec?: string, agentDir?: string): string[];
 /**
  * true → at least one endpoint ANSWERED. Any HTTP status counts, because the
  * question is liveness, not correctness: probing a path that 404s still returns