@mjasnikovs/pi-task 0.38.32 → 0.39.1

package/dist/shared/child-process.js

@@ -1,5 +1,6 @@
 import { spawn as defaultSpawn, spawnSync as spawnSyncDefault } from 'node:child_process';
 import { realStreamTimerDeps, StreamWatchdog } from './stream-watchdog.js';
+import { realStallTimerDeps, StallProbe } from './stall-probe.js';
 import { workerChannel } from '../workers/worker-channels.js';
 /** Grace period between SIGTERM and SIGKILL (ms). */
 export const KILL_GRACE_MS = 5000;
@@ -12,6 +13,11 @@ export const CHILD_BASE_ARGS = [
     '--no-context-files',
     '--no-session'
 ];
+/** The cause a signal was aborted with, when its owner attached one. */
+function abortCause(reason) {
+    const tagged = reason;
+    return tagged?.by === 'command-timeout' ? reason : { by: 'aborted' };
+}
 // ─── JSON event-stream sink ──────────────────────────────────────────────────
 /**
  * Parses a child's `--mode json` event stream into assistant text plus side
@@ -179,7 +185,7 @@ export class JsonEventSink {
             if (opts.onToolCall) {
                 const hit = opts.onToolCall({ name: tn, args: evt.args, toolCallId: id });
                 if (hit)
-                    this.onLoopKill();
+                    this.onLoopKill(hit);
             }
             return;
         }
@@ -208,7 +214,7 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
     return new Promise(resolve => {
         let stdout = '';
         let stderr = '';
-        let aborted = false;
+        let kill;
         const discardStdout = opts?.mode === 'text' && opts.discardStdout === true;
         // Deliver the prompt on stdin, not argv. A large prompt — an inlined design
         // doc, say — exceeds the OS argv ceiling and the spawn fails outright rather
@@ -253,12 +259,13 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                 // group already gone
             }
         };
-        // One kill path, shared by user-abort and loop-kill: SIGTERM, then SIGKILL
-        // after a grace period if the child ignored the term. For a group-owning
-        // (model) child, ALSO sweep the group so anything it backgrounded dies with
-        // it — proc.kill hits only the leader, reapGroup the grandchildren.
-        const killProc = () => {
-            aborted = true;
+        // One kill path for every source: SIGTERM, then SIGKILL after a grace
+        // period if the child ignored the term. For a group-owning (model) child,
+        // ALSO sweep the group so anything it backgrounded dies with it —
+        // proc.kill hits only the leader, reapGroup the grandchildren. The FIRST
+        // cause wins: a stall kill's SIGTERM can trip the abort path behind it.
+        const killProc = (cause) => {
+            kill ??= cause;
             proc.kill('SIGTERM');
             if (ownGroup)
                 reapGroup('SIGTERM');
@@ -274,15 +281,11 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         // below structurally cannot catch. Suspended for the duration of a tool
         // call: a 12-minute build legitimately emits nothing, and that window is
         // the COMMAND watchdog's to police, not this one's.
-        let streamStalledIdleMs;
         const streamWatch = opts?.mode === 'json-events' && (opts.streamInactivityMs ?? 0) > 0 ?
             new StreamWatchdog({
                 getTimeoutMs: () => opts.streamInactivityMs,
                 ...realStreamTimerDeps,
-                onFire: idleMs => {
-                    streamStalledIdleMs = idleMs;
-                    killProc();
-                }
+                onFire: idleMs => killProc({ by: 'stream-stall', idleMs })
             })
             : null;
         streamWatch?.start();
@@ -307,41 +310,21 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                     }
                 }
                 : opts;
-        const sink = sinkOpts ? new JsonEventSink(sinkOpts, killProc) : null;
-        // Dead-backend stall guard (json-events children only; see the option
-        // docs). Any output resets the window; a reachable probe also resets it
-        // so the next probe is a full window away, not every tick.
+        const sink = sinkOpts ? new JsonEventSink(sinkOpts, hit => killProc({ by: 'loop', hit })) : null;
+        // Dead-backend stall guard (json-events children only; see the option docs).
         const stall = opts?.mode === 'json-events' ? opts.stall : undefined;
-        let lastActivity = Date.now();
-        let stalled = false;
-        let probing = false;
-        const stallTimer = stall ?
-            setInterval(() => {
-                if (probing || Date.now() - lastActivity < stall.afterMs)
-                    return;
-                probing = true;
-                stall
-                    .probe()
-                    .then(reachable => {
-                    probing = false;
-                    if (reachable || stalled) {
-                        lastActivity = Date.now();
-                        return;
-                    }
-                    stalled = true;
-                    killProc();
-                })
-                    .catch(() => {
-                    // A probe that itself crashed proves nothing —
-                    // benefit of the doubt, keep waiting.
-                    probing = false;
-                    lastActivity = Date.now();
-                });
-            }, Math.max(50, Math.min(stall.afterMs / 2, 15_000)))
-            : undefined;
+        const stallProbe = stall ?
+            new StallProbe({
+                afterMs: stall.afterMs,
+                probe: stall.probe,
+                ...realStallTimerDeps,
+                onDead: () => killProc({ by: 'stalled' })
+            })
+            : null;
+        stallProbe?.start();
         let firstByteFired = false;
         proc.stdout?.on('data', (d) => {
-            lastActivity = Date.now();
+            stallProbe?.note();
             streamWatch?.note();
             if (!firstByteFired) {
                 firstByteFired = true;
@@ -378,10 +361,11 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         // research-worker slices the TAIL of stderr in two places and the HEAD in a
         // third, and child-runner feeds the whole string into its failure message.
         proc.stderr?.on('data', (d) => {
-            lastActivity = Date.now();
+            stallProbe?.note();
             streamWatch?.note();
             stderr += d.toString();
         });
+        const onAbort = () => killProc(abortCause(signal?.reason));
         // One idempotent settle path for close/error/abort. Detaching the abort
         // listener here is the point. `{once: true}` fires-and-removes on an ACTUAL
         // abort and at no other time, so a child that finishes normally leaves its
@@ -394,10 +378,9 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         // the caller's callbacks close over.
         let settled = false;
         const cleanup = () => {
-            if (stallTimer)
-                clearInterval(stallTimer);
+            stallProbe?.stop();
             streamWatch?.stop();
-            signal?.removeEventListener('abort', killProc);
+            signal?.removeEventListener('abort', onAbort);
         };
         const settle = (result) => {
             cleanup();
@@ -422,23 +405,26 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                 stdout,
                 stderr,
                 exitCode: code ?? 0,
-                aborted,
+                aborted: kill !== undefined,
+                ...(kill ? { kill } : {}),
                 text,
-                modelError: sink?.modelError,
-                ...(stalled ? { stalled: true } : {}),
-                ...(streamStalledIdleMs !== undefined ?
-                    { streamStalled: { idleMs: streamStalledIdleMs } }
-                    : {})
+                modelError: sink?.modelError
             });
         });
         proc.once('error', () => {
-            settle({ stdout, stderr, exitCode: 1, aborted });
+            settle({
+                stdout,
+                stderr,
+                exitCode: 1,
+                aborted: kill !== undefined,
+                ...(kill ? { kill } : {})
+            });
         });
         if (signal) {
             if (signal.aborted)
-                killProc();
+                onAbort();
             else
-                signal.addEventListener('abort', killProc, { once: true });
+                signal.addEventListener('abort', onAbort, { once: true });
         }
     });
 }

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

@@ -130,6 +130,15 @@ export interface CommandKill {
      *  so the fresh child knows which call it must not repeat unbounded. */
     detail?: string;
 }
+/**
+ * The kill, as the REASON the watchdog aborts its signal with. runChild reads
+ * it off the combined signal, so a command kill reaches `ChildResult.kill` by
+ * the same road every other guard's kill does — not through a side query the
+ * caller has to remember to make.
+ */
+export interface CommandKillReason extends CommandKill {
+    by: 'command-timeout';
+}
 /**
  * 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
@@ -142,9 +151,9 @@ export interface WatchedToolCall {
 }
 /**
  * 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.
+ * machine whose `onFire` aborts `signal` WITH the kill as its reason, which
+ * runChild turns into a process-GROUP kill — reaping the hung command itself,
+ * not just the pi child holding it — and reports as `kill.by === 'command-timeout'`.
  *
  * 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
@@ -158,7 +167,6 @@ export interface WatchedToolCall {
 export declare function commandWatch(timeoutMs: number): {
     onStart: (call: WatchedToolCall) => void;
     onEnd: (toolCallId: string | undefined) => void;
-    killed: () => CommandKill | undefined;
     signal: AbortSignal;
     clear: () => void;
 } | null;

package/dist/shared/command-watchdog.js

@@ -174,9 +174,9 @@ export const realTimerDeps = {
 };
 /**
  * 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.
+ * machine whose `onFire` aborts `signal` WITH the kill as its reason, which
+ * runChild turns into a process-GROUP kill — reaping the hung command itself,
+ * not just the pi child holding it — and reports as `kill.by === 'command-timeout'`.
  *
  * 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
@@ -196,17 +196,17 @@ export function commandWatch(timeoutMs) {
     // 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 = {
+            const reason = {
+                by: 'command-timeout',
                 toolName,
                 timeoutMs: ms,
                 ...(details.has(toolCallId) ? { detail: details.get(toolCallId) } : {})
             };
-            ctrl.abort();
+            ctrl.abort(reason);
         }
     });
     return {
@@ -226,7 +226,6 @@ export function commandWatch(timeoutMs) {
             details.delete(key(id));
             watchdog.onEnd(key(id));
         },
-        killed: () => killed,
         signal: ctrl.signal,
         clear: () => watchdog.clearAll()
     };

package/dist/shared/connection-error.d.ts

@@ -0,0 +1,7 @@
+export declare function isConnectionError(cause: string): boolean;
+/**
+ * Exponential backoff before a connection-error retry: 500ms, 1s, 2s — three
+ * requests over 3.5s, which is not a storm even against a throttle. pi's own
+ * ladder is three at 2s/4s/8s.
+ */
+export declare function connectionRetryBackoffMs(attempt: number): number;

package/dist/shared/connection-error.js

@@ -0,0 +1,65 @@
+/**
+ * Which model errors are worth another attempt.
+ *
+ * A connection-class model error is transient: a single dropped fetch to a live
+ * endpoint, not a repeatable mistake. On a local single-slot server (e.g.
+ * llama-server with `--parallel 1`) pi-task's own concurrent fan-out can briefly
+ * saturate the slot, and one request fails to connect even though the model is
+ * up and the next request succeeds. pi already retries internally, but those
+ * retries don't always absorb it on a saturated local server — and a fail-fast
+ * then kills the whole task for a single blip.
+ *
+ * A NON-connection model error (bad request, context-length overflow, auth,
+ * provider 5xx that names a real fault) still fails fast: re-spawning against
+ * the same request won't fix it, so burning the budget only delays the report.
+ *
+ * SCOPE, and it is deliberate: connection classes only. pi's own
+ * `isRetryableAssistantError` (@earendil-works/pi-ai, `dist/utils/retry.js`) also
+ * retries the provider-LOAD family — `429`, `5xx`, `rate limit`, `overloaded` —
+ * which `does NOT match real, non-transient faults` in child-runner.test.ts
+ * explicitly rejects. That disagreement is real and OPEN; it is not settled here,
+ * because this backoff starts at 500ms and a 429 answered that fast is a retry
+ * storm, not a recovery.
+ *
+ * MEASURED against pi before widening: the transport entries here — a bare
+ * `timed out`, `getaddrinfo ENOTFOUND`, `upstream connect`, `reset before
+ * headers`, a truncated Anthropic stream and a closed websocket — were all
+ * MISSES. Every one is a REMOTE-provider failure, which is why a local llama.cpp
+ * setup never surfaced the gap. The errno spellings are pi-task's own: a child
+ * reports them through stderr, and pi never sees them.
+ *
+ * pi's bare `timeout` is deliberately NOT reproduced. It matched a provider 400
+ * that merely echoed a `timeout` field back, turning a fail-fast into a full
+ * retry budget, and it caught nothing the `timed out` spellings above miss.
+ */
+const CONNECTION_ERROR_RE = /\b(?:connection error|connection (?:lost|closed|reset|refused|aborted)|econnreset|econnrefused|econnaborted|epipe|etimedout|enetunreach|enetdown|eai_again|socket hang up|socket connection was closed|fetch failed|network (?:error|timeout)|premature close|terminated|unreachable|getaddrinfo|enotfound|upstream.?connect|reset before headers|timed? out|ended without|stream ended before message_stop|websocket.?(?:closed|error))\b/i;
+/**
+ * Provider LOAD, which is transient in a different way: the server is up and
+ * saying "not now". pi retries all of these; 53f0488 did not, but its own message
+ * names only "context overflow, bad request, auth" as the fail-fast set — a
+ * throttle was never argued for, it just rode along in a list written for a LOCAL
+ * server, where none of these can occur.
+ *
+ * Words carry no trailing \b (`overloaded_error` joins on `_`, which is a word
+ * character); the bare status codes carry one, or `500` matches inside `15000`.
+ */
+const PROVIDER_LOAD_RE = /(?:overloaded|rate.?limit|too many requests|service.?unavailable|server.?error|internal.?error|provider.?returned.?error)|\b(?:429|500|502|503|504|524)\b/i;
+/**
+ * Account facts, not liveness: a budget does not refill on a retry. Checked FIRST,
+ * because these arrive worded as a throttle — `429 GoUsageLimitError` is a
+ * subscription limit, not a queue.
+ */
+const NON_RETRYABLE_RE = /\b(?:insufficient_quota|quota exceeded|out of budget|billing|usage limit reached|available balance|GoUsageLimitError|FreeUsageLimitError)\b/i;
+export function isConnectionError(cause) {
+    if (NON_RETRYABLE_RE.test(cause))
+        return false;
+    return CONNECTION_ERROR_RE.test(cause) || PROVIDER_LOAD_RE.test(cause);
+}
+/**
+ * Exponential backoff before a connection-error retry: 500ms, 1s, 2s — three
+ * requests over 3.5s, which is not a storm even against a throttle. pi's own
+ * ladder is three at 2s/4s/8s.
+ */
+export function connectionRetryBackoffMs(attempt) {
+    return 500 * 2 ** attempt;
+}

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

@@ -1,5 +1,3 @@
-/** 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.
  *
@@ -11,24 +9,12 @@ 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.
+ * Still read from settings.json rather than the session snapshot: pi persists a
+ * `/model` switch there, and a child with no `--model` resolves it fresh, so the
+ * file is the one source that is right after a mid-session switch.
  */
-export declare function modelBaseUrl(ref: ModelRef, agentDir?: string): string | undefined;
+export declare function defaultModelRef(agentDir?: string): ModelRef | undefined;
 /**
  * What to probe on behalf of one child — the endpoint that child's own model
  * uses, not every endpoint on the machine.
@@ -45,12 +31,14 @@ export declare function modelBaseUrl(ref: ModelRef, agentDir?: string): string |
  * 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.
+ * Every escape is toward never killing: an unknown model, a model with no URL,
+ * an unreadable default and a session that has not started all answer `[]`,
+ * which `probeModelEndpoints` reads as reachable. Probing some OTHER model's
+ * url instead would import a false positive, which is the one thing a blind
+ * guard never does.
+ *
+ * `agentDir` locates settings.json for the unpinned case only. The URL always
+ * comes from this session's registry snapshot, never from a file under it.
  */
 export declare function childModelEndpoints(spec?: string, agentDir?: string): string[];
 /**

package/dist/shared/model-endpoint.js

@@ -1,6 +1,6 @@
 /**
- * model-endpoint — discovery + reachability probe for the model backend(s) a
- * child pi process talks to.
+ * model-endpoint — which backend a child pi process talks to, and whether it
+ * still answers.
  *
  * The failure this serves: the model server dies mid-child and the child hangs
  * mute. pi's own connection-error handling cannot help, because it runs from a
@@ -10,43 +10,26 @@
  * while it runs, so only "no output AND the endpoint does not answer" counts as
  * a dead backend.
  *
- * Discovery is generic — no provider or server name is hardcoded anywhere here.
- * No discoverable endpoint means nothing to probe, and the guard then NEVER
- * kills: a child on a backend we cannot see gets the benefit of the doubt.
- *
- * `childModelEndpoints` is what the guards call; `discoverModelEndpoints` is its
- * last resort. The difference is the point. Discovery answers "every endpoint on
- * this machine", and `probeModelEndpoints` ORs over it, so one healthy provider
- * says "reachable" for a child stranded on a dead one. Resolving the child's OWN
- * model first turns that OR into a single exact question.
+ * WHERE THE URL COMES FROM. The registry, snapshotted at session_start by
+ * workers/model-warning.ts into config/group-args.ts — the guards run where no
+ * `ctx` exists. It used to be re-parsed out of pi's `models.json` and
+ * `models-store.json`, which answer `undefined` for every one of pi-ai's 39
+ * built-in providers, so the guard was blind exactly where the registry knew
+ * the URL. It is now ARMED for those. The other direction is unchanged: no
+ * snapshot yet, or a model with no URL, means nothing to probe, and the guard
+ * then NEVER kills — a child on a backend we cannot see gets the benefit of the
+ * doubt.
  */
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-/** Base URLs of every custom provider pi is configured with (possibly none). */
-export function discoverModelEndpoints(agentDir = path.join(os.homedir(), '.pi', 'agent')) {
-    try {
-        const j = JSON.parse(fs.readFileSync(path.join(agentDir, 'models.json'), 'utf8'));
-        const urls = [];
-        for (const p of Object.values(j.providers ?? {})) {
-            if (typeof p?.baseUrl === 'string' && p.baseUrl.length > 0)
-                urls.push(p.baseUrl);
-        }
-        return [...new Set(urls)];
-    }
-    catch {
-        return [];
-    }
-}
-/** A `provider/id` spec as a ref, splitting on the FIRST slash. */
-function specRef(spec) {
-    if (spec === undefined)
-        return undefined;
-    const i = spec.indexOf('/');
-    if (i <= 0 || i === spec.length - 1)
-        return undefined;
-    return { provider: spec.slice(0, i), id: spec.slice(i + 1) };
-}
+import { modelEndpoint } from '../config/group-args.js';
+import { specOf } from './model-resolve.js';
+/**
+ * Still read from settings.json rather than the session snapshot: pi persists a
+ * `/model` switch there, and a child with no `--model` resolves it fresh, so the
+ * file is the one source that is right after a mid-session switch.
+ */
 export function defaultModelRef(agentDir = path.join(os.homedir(), '.pi', 'agent')) {
     try {
         const j = JSON.parse(fs.readFileSync(path.join(agentDir, 'settings.json'), 'utf8'));
@@ -62,43 +45,6 @@ export function defaultModelRef(agentDir = path.join(os.homedir(), '.pi', 'agent
         return 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 function modelBaseUrl(ref, agentDir = path.join(os.homedir(), '.pi', 'agent')) {
-    const url = (v) => typeof v === 'string' && v.length > 0 ? v : undefined;
-    try {
-        const j = JSON.parse(fs.readFileSync(path.join(agentDir, 'models.json'), 'utf8'));
-        const p = j.providers?.[ref.provider];
-        if (p) {
-            const own = p.models?.find(m => m.id === ref.id);
-            return url(own?.baseUrl) ?? url(p.baseUrl);
-        }
-    }
-    catch {
-        /* fall through to the store */
-    }
-    try {
-        const j = JSON.parse(fs.readFileSync(path.join(agentDir, 'models-store.json'), 'utf8'));
-        return url(j[ref.provider]?.models?.find(m => m.id === ref.id)?.baseUrl);
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * What to probe on behalf of one child — the endpoint that child's own model
  * uses, not every endpoint on the machine.
@@ -115,18 +61,22 @@ export function modelBaseUrl(ref, agentDir = path.join(os.homedir(), '.pi', 'age
  * 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.
+ * Every escape is toward never killing: an unknown model, a model with no URL,
+ * an unreadable default and a session that has not started all answer `[]`,
+ * which `probeModelEndpoints` reads as reachable. Probing some OTHER model's
+ * url instead would import a false positive, which is the one thing a blind
+ * guard never does.
+ *
+ * `agentDir` locates settings.json for the unpinned case only. The URL always
+ * comes from this session's registry snapshot, never from a file under it.
  */
 export function childModelEndpoints(spec, agentDir = path.join(os.homedir(), '.pi', 'agent')) {
-    const ref = specRef(spec) ?? defaultModelRef(agentDir);
-    if (!ref)
-        return discoverModelEndpoints(agentDir);
-    const url = modelBaseUrl(ref, agentDir);
+    let ref = spec;
+    if (ref === undefined) {
+        const saved = defaultModelRef(agentDir);
+        ref = saved && specOf(saved);
+    }
+    const url = ref === undefined ? undefined : modelEndpoint(ref);
     return url === undefined ? [] : [url];
 }
 /**

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

@@ -0,0 +1,105 @@
+/**
+ * The one seam between a stored `provider/id` spec and pi's live model registry.
+ *
+ * Every question of the form "which pi Model does X run on" comes through here:
+ * the session hints, the context-window table, the settings panel's catalogue
+ * and the implementation hold. They used to each carry their own split-then-
+ * `find`, and each re-decided what `inherit` means. One of them getting it
+ * wrong is a warning naming the wrong model or a hold restoring the wrong one.
+ *
+ * `ctx` is the STRUCTURAL minimum, not one of pi's context interfaces: a tool
+ * context, a command context and a test literal all satisfy it. `ctx.model` and
+ * `ctx.modelRegistry` are GETTERS on the real thing that call `assertActive()`
+ * and throw on a stale context, so every reader here answers `undefined`
+ * instead of throwing — a session hint must not take the session down.
+ */
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { type ChildGroup } from '../config/groups.js';
+/**
+ * pi's own `Model`, named without importing `@earendil-works/pi-ai` — which is
+ * neither a dependency, a devDependency nor a peerDependency of this package.
+ * The context already carries the type, so deriving it adds no edge to the graph.
+ */
+export type PiModel = NonNullable<ExtensionContext['model']>;
+/** The two registry questions this asks. `getAvailable` only feeds the endpoint map. */
+export interface ModelRegistryView {
+    find(provider: string, id: string): PiModel | undefined;
+    getRegisteredProviderIds?(): readonly string[];
+    getAvailable?(): readonly PiModel[];
+}
+export interface ModelContext {
+    model?: PiModel;
+    modelRegistry?: ModelRegistryView;
+}
+/** A spec, resolved. Structurally a `GroupModelFacts`, so it feeds the reasoning check as-is. */
+export interface ResolvedModel {
+    /** Canonical `provider/id` — for `inherit`, the session model's own. */
+    spec: string;
+    name: string;
+    reasoning: boolean;
+    thinkingLevelMap?: PiModel['thinkingLevelMap'];
+    /** Absent when the model declares none; a probe cannot be aimed at it. */
+    baseUrl?: string;
+    /** 0 when the model declares none, so `||` falls through to the parent's. */
+    contextWindow: number;
+    /**
+     * Its provider was registered by a host extension. Children run
+     * `--no-extensions`, so the model works in a child exactly when that
+     * extension is in the child whitelist — a warning, never a drop.
+     */
+    fromExtension: boolean;
+    handle: PiModel;
+}
+/** The `provider/id` inverse of {@link splitSpec}. */
+export declare function specOf(model: {
+    provider: string;
+    id: string;
+}): string;
+/**
+ * `inherit` is the session's model. That is decision 3 of the model table —
+ * children are NOT switched to follow the host — and the honest value is
+ * settings.json's default, which need not be the session's. Naming the
+ * session's model is still the better of the two: it is the one the user can
+ * see, and on every machine with one provider the two agree.
+ *
+ * `find` is EXACT, deliberately stricter than pi's own CLI, which also
+ * substring-matches. We store a canonical `provider/id`, so exact is the only
+ * match that should ever count.
+ */
+export declare function resolveModel(ctx: ModelContext, spec: string): ResolvedModel | undefined;
+/**
+ * One group's cell, as the code with no `ctx` needs it (see config/group-args.ts).
+ *
+ * `unresolved` — no such model here, so the `--model` flag is dropped.
+ * `extension` — see {@link ResolvedModel.fromExtension}; a warning, not a drop.
+ */
+export interface GroupModelSnapshot {
+    spec: string;
+    /** false ⇒ emit no `--model` for this group. Only `unresolved` clears it. */
+    usable: boolean;
+    /** Absent for `inherit` and for an unresolved spec: the caller keeps its live parent value. */
+    contextWindow?: number;
+    problem?: 'unresolved' | 'extension';
+}
+/**
+ * Every group's cell in ONE registry walk, so the argv drop, the churn window
+ * and the hint can never disagree about which model a group runs on.
+ *
+ * An `inherit` cell gets NO window. Storing the parent's would freeze a
+ * session_start snapshot in front of the live per-run value: a user who
+ * switches the session model with Ctrl+P to a bigger one would have every
+ * child judged against the old window, and the churn rule then fires early and
+ * kills a healthy child. An unresolved cell gets none for the same reason —
+ * such a child runs on the live default, whichever that is by then.
+ *
+ * A registry that cannot answer condemns NOTHING: every cell stays usable and
+ * carries no window. Claiming every spec unresolved would drop every `--model`
+ * on a session whose runtime merely was not ready.
+ */
+export declare function resolveGroupModels(ctx: ModelContext, specs: Readonly<Record<ChildGroup, string>>): Record<ChildGroup, GroupModelSnapshot>;
+/**
+ * `spec → baseUrl` for every model this session can use, for the dead-backend
+ * probe (shared/model-endpoint.ts). Empty when the registry cannot answer,
+ * which the probe reads as "cannot see, so never kill".
+ */
+export declare function resolveModelEndpoints(ctx: ModelContext): Map<string, string>;