tumwater 0.1.2 → 0.2.0

package/dist/src/pi/pi-failure.js

@@ -0,0 +1,87 @@
+/** The backend-failure classifier for the pi seam: given provider/pi error text, decide
+ * whether it names a permanent configuration error or a transient backend failure, and which
+ * `BackendFailureKind` it is. This vocabulary is cross-cutting — the settle/team hold groups a
+ * storm by kind (src/team/team-hold.ts), the merge path pins a permanent config error, the pi
+ * adapter's stderr path (src/pi/pi-backend.ts) and the stream parser both classify — so it
+ * lives in its own module instead of hiding inside the stream parser (which used to be its
+ * only home: pi-backend.ts had to import a parser to get a classifier). Keep the per-kind
+ * regexes here so the transient gate and the kind classifier cannot disagree: they compose one
+ * `TRANSIENT_BACKEND` alternation and `backendKind` orders its checks the same way.
+ *
+ * The parser-local error heuristics that feed PiStreamParser's own flags — the context-overflow,
+ * predict-stream-timeout, and rate-limit+Retry-After patterns — stay in src/pi/pi-stream.ts:
+ * they are stream-parsing concerns (they drive `contextExceeded`/`transientServerTimeout`/
+ * `transientRateLimit`), not the cross-module "what kind of failure is this" vocabulary. */
+const PERMANENT_CONFIG_ERROR = /\b(?:400|401|403|404)\b|model_not_supported|invalid_request_error/i;
+/** True when an error text names a permanent provider configuration error (see
+ * PERMANENT_CONFIG_ERROR). Pure, exported so the merge path and the stderr path classify
+ * with one rule. */
+export function isPermanentConfigError(text) {
+    return PERMANENT_CONFIG_ERROR.test(text);
+}
+/** undici's spelling of a severed HTTP stream: the provider (or its own idle timeout) cuts
+ * the request while pi is still reading it, and undici's fetch rejects with the bare word
+ * "terminated" — the 2026-08-22 idle-timeout diagnosis. Anchored to the END of the error text
+ * on purpose: the real message is the bare word, optionally behind a prefix and closing
+ * punctuation, while an unrelated error that merely contains the word ("worker terminated
+ * with exit code 1") must not read as a backend failure. Module-private: matchBackendFailure
+ * below, the parser, and backendKind all share the one instance. */
+const STREAM_SEVERED = /(^|[^a-z])terminated[.!\s]*$/i;
+/** The connection-class backend-failure phrases: fetch-level "Connection error.", the
+ * refusals and resets Node surfaces. One home shared by the TRANSIENT_BACKEND gate and the
+ * backendKind classifier, so a spelling added to one cannot go missing from the other. */
+const CONNECTION_ERROR = /connection error|connection refused|connection reset|econn(refused|reset)/i;
+/** The timeout-class backend-failure phrase (OpenAI-style "Request timed out"). Shared by the
+ * TRANSIENT_BACKEND gate and the backendKind classifier. */
+const TIMEOUT_ERROR = /request timed out/i;
+/** The server-class backend-failure phrases: 5xx status texts, oMLX's model-server pause, and
+ * a provider pausing itself team-wide with a 503 whose body carries prose rather than any
+ * status phrase ("Provider '<name>' is currently failing for model '<id>' and has been paused
+ * by the provider"). Shared by the TRANSIENT_BACKEND gate and the backendKind classifier. */
+const SERVER_ERROR = /internal server error|bad gateway|service unavailable|gateway timeout|currently failing for model|paused by the provider/i;
+/** The model-load spelling (oMLX's "Failed to load model"): its backendKind is the
+ * "model-load" default, so only the gate names the pattern. */
+const MODEL_LOAD_ERROR = /failed to load model/i;
+/** The backend-failure error texts pi actually surfaces, matched against every error text
+ * feedLine sees — the same shapes as the rate-limit regex's various renderings.
+ * Deliberately does NOT match the 429 texts: feedLine checks TRANSIENT_RATE_LIMIT first and
+ * only falls through here, so a rate limit stays a rate limit (with its Retry-After hint)
+ * and never counts as a backend failure. Composed from the per-kind patterns above so each
+ * kind's spellings — including the stream-severed one (STREAM_SEVERED) — live in exactly one
+ * place. Only matchBackendFailure and PiStreamParser.feedLine match it; backendKind below
+ * classifies which phrase matched. */
+export const TRANSIENT_BACKEND = new RegExp(`${CONNECTION_ERROR.source}|${TIMEOUT_ERROR.source}|${SERVER_ERROR.source}|${MODEL_LOAD_ERROR.source}|${STREAM_SEVERED.source}`, "i");
+/** Which backend-failure kind an error text belongs to — pure, exported so the parser's
+ * classification is unit-testable without a stream (pi-parser.test.ts feeds the texts
+ * directly). Each check is the same per-kind pattern the TRANSIENT_BACKEND gate composes, so
+ * the gate and the classifier cannot disagree; the order matches that alternation. */
+export function backendKind(text) {
+    if (CONNECTION_ERROR.test(text))
+        return "connection";
+    if (TIMEOUT_ERROR.test(text))
+        return "timeout";
+    if (SERVER_ERROR.test(text))
+        return "server";
+    if (STREAM_SEVERED.test(text))
+        return "stream-severed";
+    return "model-load";
+}
+/** The backend-failure kind `text` names, or undefined when it names none — the stderr
+ * classifier (src/pi/pi-backend.ts's classifyExit) needs "no match" distinct from
+ * backendKind's "model-load" default. Gated by TRANSIENT_BACKEND, so a text the event path
+ * ignores is ignored on stderr too. Pure; exported for pi-backend.ts's classifyExit. */
+export function matchBackendFailure(text) {
+    return TRANSIENT_BACKEND.test(text) ? backendKind(text) : undefined;
+}
+/** The valid `backendKind` values, for validating a translator-supplied string at the wire
+ * boundary (the same untrusted-JSON policy every other field read here applies). */
+const BACKEND_FAILURE_KINDS = [
+    "connection",
+    "timeout",
+    "server",
+    "model-load",
+    "stream-severed",
+];
+export function isBackendFailureKind(value) {
+    return typeof value === "string" && BACKEND_FAILURE_KINDS.includes(value);
+}

package/dist/src/pi/pi-models.js

@@ -1,17 +1,30 @@
 import os from "node:os";
 import path from "node:path";
 import { enabledRoleIds } from "../config/config.js";
-import { configForRole, fallbackPair, resolverConfig, reviewConfig } from "../config/config-views.js";
-import { isAgentId } from "../config/model-selector.js";
+import { configForRole, resolverConfig, reviewConfig } from "../config/config-views.js";
+import { fallbackPair } from "../config/config-fallbacks.js";
+import { seamAgent } from "../config/model-selector.js";
 import { cachedByStat } from "../files/stat-cache.js";
 import { isJsonObject } from "../files/json-object.js";
 import { readJsonFile } from "../files/json-files.js";
+import { expandHomeTilde } from "../files/files.js";
+import { declaredWindow } from "../pi-extension/context-window.js";
+import { piSettingsPath, readPiDefaultModel } from "./pi-settings.js";
+import { opencodeModelFree, opencodeModelKey, readOpencodeCache } from "../agent/opencode/opencode-catalog.js";
 /** pi's model definitions — the custom providers and models they serve, with each model's
- * declared cost. This is where a local (free) fleet differs from an API one: unpriced or
+ * declared cost. This is where a local (free) team differs from an API one: unpriced or
  * zero-cost models never accumulate spend against the daily budget cap, so the badge can
  * read n/a instead of a dollar figure that can never move. */
-export function piModelsPath() {
-    return path.join(os.homedir(), ".pi", "agent", "models.json");
+export function piModelsPath(env = process.env, homeDir = os.homedir()) {
+    return path.join(piAgentDir(env, homeDir), "models.json");
+}
+/** pi's config directory: `$PI_CODING_AGENT_DIR` when non-empty (a leading `~` expands against
+ * the home dir), else `~/.pi/agent`. This mirrors pi's `getAgentDir`. */
+export function piAgentDir(env = process.env, homeDir = os.homedir()) {
+    const dir = env.PI_CODING_AGENT_DIR;
+    if (!dir)
+        return path.join(homeDir, ".pi", "agent");
+    return expandHomeTilde(dir, homeDir);
 }
 /** The cost components pi's models.json may declare. */
 const COST_KEYS = ["input", "output", "cacheRead", "cacheWrite"];
@@ -33,7 +46,7 @@ function costIsFree(cost) {
     });
 }
 /** Per-poll cache of the parsed definitions, keyed by models path: both dashboards poll
- * fleetModelsFree every second while models.json changes only when a user edits it — and it grows
+ * teamModelsFree every second while models.json changes only when a user edits it — and it grows
  * with the model catalog (every added provider/model entry), so an unchanged file costs one stat
  * per poll instead of a re-read plus JSON.parse of the whole catalog. Any write invalidates via
  * dev/ino/mtime/size (stat-cache.cachedByStat, same freshness check as the other polled files in
@@ -45,6 +58,17 @@ const providersCache = new Map();
  * Exported for budget-gates.ts's per-tier resolution, which prices several candidate pairs
  * against the same snapshot instead of re-entering this cache per pair.
  */
+/** A provider/model pair's claimed image input from pi's definitions: `true` when the model
+ * declares `"image"` in its `input`, `false` when the pair resolves but declares no image
+ * support (input absent, or present without `"image"` — pi's own text-only default for the
+ * custom model), and `null` when the pair cannot be resolved at all (see resolveModelDef). The
+ * null case is left to the doctor's `tier models` check, which already fails such pairs. */
+export function piModelImageInput(providers, provider, model) {
+    const def = resolveModelDef(providers, provider, model);
+    if (!def)
+        return null;
+    return Array.isArray(def.input) ? def.input.includes("image") : false;
+}
 export function readPiProviders(modelsPath) {
     return cachedByStat(providersCache, modelsPath, // Keyed by path so distinct roots and test files never collide.
     modelsPath, () => {
@@ -70,6 +94,47 @@ export function readPiProviders(modelsPath) {
     // A copy: callers may treat the result as their own.
     (providers) => new Map([...providers].map(([name, models]) => [name, [...models]])));
 }
+/** The context window a run's model declares, or null when it cannot be known: an unresolvable
+ * pair, a missing or unusable window, or a backend that is neither pi nor opencode (its catalog
+ * is elsewhere). A pi seam names its window from pi's models.json, running on pi's saved default
+ * (readPiDefaultModel) when it names no provider/model — exactly the model pi will start on. An
+ * opencode seam names its window from the models.dev catalog (part 6e/7): the same cache entry
+ * and key the free-ness check reads, so the window and the price always come from one model.
+ * A missing cache, an unknown model, or an unusable `context` reads null, as an unknown pi
+ * model does. */
+export function seamContextWindow(seam, projectRoot, modelsPath = piModelsPath()) {
+    const agent = seamAgent(seam);
+    switch (agent) {
+        case "pi":
+            let { provider, model } = seam;
+            if (!provider || !model) {
+                const piDefault = readPiDefaultModel(piSettingsPath(modelsPath), projectRoot);
+                provider = piDefault?.provider;
+                model = piDefault?.model;
+            }
+            return declaredWindow(resolveModelDef(readPiProviders(modelsPath), provider, model)?.contextWindow);
+        case "opencode":
+            // The models.dev cache (readOpencodeCache, an empty cache when the file is missing) holds
+            // the window part 6a/7 parsed from `limit.context`, keyed by the gateway-qualified id the
+            // run actually invokes (opencodeModelKey) — the same key and entry the free-ness check
+            // prices by, so a seam's window never disagrees with the model it runs.
+            if (seam.model === undefined)
+                return null;
+            return declaredWindow(readOpencodeCache(projectRoot).models[opencodeModelKey(seam.model)]?.context);
+        default:
+            return null;
+    }
+}
+/** A provider's `baseUrl` from pi's models.json, or null when the file, the provider or the
+ * field is missing — what doctor probes to tell a local server that is down from one that is up. */
+export function piProviderBaseUrl(modelsPath, provider) {
+    const doc = readJsonFile(modelsPath);
+    const providers = doc?.providers;
+    if (!isJsonObject(providers) || !Object.hasOwn(providers, provider))
+        return null;
+    const pdef = providers[provider];
+    return isJsonObject(pdef) && typeof pdef.baseUrl === "string" ? pdef.baseUrl : null;
+}
 /** Resolve a `provider`/`model` pair against pi's definitions — the shared first step of
  * pairFree and cacheReadUnpriced. Undefined when the pair cannot be resolved at all: an
  * omitted provider or model (pi's own default), a missing or malformed definitions file, an
@@ -118,50 +183,72 @@ function accountUsesOverage(account) {
     return account !== null && Object.values(account.windows).some((w) => w.isUsingOverage === true);
 }
 /** Whether a seam may be called free: a subscription claude seam is free money (its marginal
- * cost is zero, plans/agent-backends.md "Free-ness"), and a pi seam is free when pi's own
- * models.json prices it at zero. A subscription that is spending into overage is NOT free: that
- * overflow is API-priced real money, exactly as `runCostIsReal` treats a run that saw
- * `isUsingOverage`. Everything else is NOT free — an API-billed claude seam, an overage
- * subscription claude seam, an unresolvable or priced pi pair, and any other backend — so the
+ * cost is zero, plans/agent-backends.md "Free-ness"), a pi seam is free when pi's own
+ * models.json prices it at zero, and an opencode seam is free when the models.dev catalog
+ * prices its model at zero and no run has billed it (part 6b/7). A subscription that is
+ * spending into overage is NOT free: that overflow is API-priced real money, exactly as
+ * `runCostIsReal` treats a run that saw `isUsingOverage`. Everything else is NOT free — an
+ * API-billed claude seam, an overage subscription claude seam, an unresolvable or priced pi
+ * pair, an opencode model the catalog does not price at zero, and any other backend — so the
  * badge never reads n/a while spend it cannot see could still reach the cap. The one central
  * rule: the budget gate, the fallback view, and the status free-ness read all judge seams
- * through it (plans/agent-backends.md "Free-ness" and "Every seam, checked"). */
-export function seamFree(providers, seam, account = null) {
-    const agent = seam.agent ?? (isAgentId(seam.provider) ? seam.provider : "pi");
-    if (agent === "claude")
-        return account?.billing === "subscription" && !accountUsesOverage(account);
-    if (agent !== "pi")
-        return false;
-    return pairFree(providers, seam.provider, seam.model);
+ * through it (plans/agent-backends.md "Free-ness" and "Every seam, checked"). The opencode
+ * `catalog` is threaded the way the claude `account` is: an absent catalog means "no cache to
+ * read", so an opencode seam reads NOT free, the safe direction for a budget gate. */
+export function seamFree(providers, seam, account = null, catalog = null) {
+    const agent = seamAgent(seam);
+    // One free-ness rule per backend: pi's pair price, claude's subscription, opencode's catalog,
+    // and nothing for any other backend (its spend could still reach the cap, so the badge must
+    // not read n/a). The opencode arm reads the gateway-qualified id (part 6b/7) and changes the
+    // pi and claude arms nothing.
+    switch (agent) {
+        case "pi":
+            return pairFree(providers, seam.provider, seam.model);
+        case "claude":
+            return account?.billing === "subscription" && !accountUsesOverage(account);
+        case "opencode":
+            // A null catalog — no cache to read — and an unknown or billed model must all read NOT
+            // free (opencodeModelFree's safe direction): the badge never reads n/a while spend it
+            // cannot see could still reach the cap (plans/opencode-backend.md §7 "Free-ness").
+            // opencodeModelKey is the models.dev cache key for the run's resolved selector — the
+            // same `<provider>/<model>` join opencodeArgs invokes — so the seam's free-ness lookup
+            // never disagrees with the model it actually runs, and the free-ness key is the one
+            // billing key (part 6b/7).
+            return catalog !== null && seam.model !== undefined && opencodeModelFree(catalog, opencodeModelKey(seam.model));
+        default:
+            return false;
+    }
 }
 /** Whether a fallback-config pair may be called free: a `claude/<id>` pair is free while the
- * account bills a subscription and is not using overage, and a pi provider/model is free when
- * models.json prices it at zero. A non-claude agent namespace, or an unresolvable pi pair, is
- * refused — the badge must not read n/a while a backend whose billing it cannot see runs.
- * Exported so the budget gate (src/gates/budget-gates.ts) and the status pause set
- * (src/status/status-data.ts) judge fallback pairs with the same predicate the free-ness view
- * does — neither may engage a backend their own badge would not call free. */
-export function piPairFree(providers, provider, model, account = null) {
-    return seamFree(providers, { provider, model }, account);
-}
-/** The free fallback pair the budget gate would engage for the fleet, or null when none is
+ * account bills a subscription and is not using overage, a pi provider/model is free when
+ * models.json prices it at zero, and an opencode pair is free when the catalog prices it at
+ * zero (part 6b/7). Any other agent namespace, or an unresolvable pair, is refused — the badge
+ * must not read n/a while a backend whose billing it cannot see runs. Exported so the budget
+ * gate (src/gates/budget-gates.ts), the status pause set (src/status/status-data.ts) and the
+ * free-ness view judge fallback pairs with the same predicate — neither may engage a backend
+ * their own badge would not call free. `catalog` is the opencode cache, threaded like `account`;
+ * absent, an opencode pair reads NOT free. */
+export function piPairFree(providers, provider, model, account = null, catalog = null) {
+    return seamFree(providers, { provider, model }, account, catalog);
+}
+/** The free fallback pair the budget gate would engage for the team, or null when none is
  * usable: the price-aware resolution of the default tier (fallbackPair over
  * resolveTierFallbacks' borrow order), so a map whose `default` entry is absent or priced
  * still names the free pair the tier borrows. Null for a missing, unresolvable, or priced
  * pair — the gate's refusal, and the pair the badge/doctor must not advertise. */
-export function fallbackModelPair(config, modelsPath = piModelsPath(), account = null) {
+export function fallbackModelPair(config, modelsPath = piModelsPath(), account = null, catalog = null) {
     const providers = readPiProviders(modelsPath);
-    return fallbackPair(config, (p) => piPairFree(providers, p.provider, p.model, account));
+    return fallbackPair(config, (p) => piPairFree(providers, p.provider, p.model, account, catalog));
 }
 /** True when the configured fallback model (plans/fallback-model.md) is one the budget gate may
  * actually engage: configured at all, resolvable to a provider/model pair, and priced at zero in
  * pi's definitions. False for every other case — no fallback, a half-named pair that would fall
  * through to pi's own default, an unknown id, or a priced one — and the gate then pauses role
  * loops exactly as it did before this feature. */
-export function fallbackModelFree(config, modelsPath = piModelsPath(), account = null) {
-    return fallbackModelPair(config, modelsPath, account) !== null;
+export function fallbackModelFree(config, modelsPath = piModelsPath(), account = null, catalog = null) {
+    return fallbackModelPair(config, modelsPath, account, catalog) !== null;
 }
-/** True when every model the fleet could use is free: each enabled role's effective
+/** True when every model the team could use is free: each enabled role's effective
  * provider/model (configForRole — the director included, it is a catalog role, resolved at
  * its tier per plans/model-tiers.md) plus the reviewer's while review is on, plus the
  * `strong` tier's own model whenever any role is enabled — the conflict resolver (part 4/8)
@@ -169,10 +256,11 @@ export function fallbackModelFree(config, modelsPath = piModelsPath(), account =
  * Every pair is judged by `seamFree` above: a subscription claude seam is free, a pi seam is
  * free when models.json prices it at zero, and everything else counts as NOT free — the badge
  * must never read n/a while spend it is tracking could still reach the cap. With no enabled
- * roles and review off there are no pairs at all, so the fleet cannot spend and the answer is
+ * roles and review off there are no pairs at all, so the team cannot spend and the answer is
  * true. `account` is the persisted claude billing answer (6a/7's reader), absent meaning "no
- * subscription". */
-export function fleetModelsFree(config, modelsPath = piModelsPath(), account = null) {
+ * subscription", and `catalog` the opencode models cache (absent, an opencode seam reads not
+ * free). */
+export function teamModelsFree(config, modelsPath = piModelsPath(), account = null, catalog = null) {
     const pairs = [];
     for (const role of enabledRoleIds(config)) {
         const rc = configForRole(config, role);
@@ -193,5 +281,5 @@ export function fleetModelsFree(config, modelsPath = piModelsPath(), account = n
     if (pairs.length === 0)
         return true;
     const providers = readPiProviders(modelsPath);
-    return pairs.every((seam) => seamFree(providers, seam, account));
+    return pairs.every((seam) => seamFree(providers, seam, account, catalog));
 }

package/dist/src/pi/pi-run-result.js

@@ -1,7 +1,7 @@
 /** Whether a run's cost is real money that charges the daily cap (plans/agent-backends.md
  * part 6a): an API-billed run, or a subscription run that saw overage. A plain subscription
  * run's cost is notional — API-equivalent spend that never moves the cap. The one predicate
- * both the tick-usage fold and the landing accumulator split on, so the two cannot drift. */
+ * both the tick-usage fold and the merge accumulator split on, so the two cannot drift. */
 export function runCostIsReal(run) {
     return run.billing !== "subscription" || run.usedOverage === true;
 }

package/dist/src/pi/pi-settings.js

@@ -0,0 +1,86 @@
+import path from "node:path";
+import { cachedByStat } from "../files/stat-cache.js";
+import { isJsonObject } from "../files/json-object.js";
+import { readJsonFile } from "../files/json-files.js";
+/** pi's own saved-default model, read from pi's `settings.json` beside the models catalog —
+ * the name a loop row shows when `tumwater.json` resolves no model and pi starts on its own
+ * default. This mirrors step 3 of pi 1.2.0's start-up model choice, "saved default from
+ * settings" (`findInitialModel` in pi's `dist/core/model-resolver.js`), for a run tumwater
+ * starts without `--provider`/`--model`. The reader does NOT model pi's last step: when the
+ * default pair is missing from pi's catalog or has no auth, pi picks the first available
+ * model — tumwater cannot resolve that pattern (see `enabledModels` below), so it shows
+ * nothing rather than a name pi may not run. */
+/** pi's `settings.json` path, derived from the models catalog path so the two files share one
+ * seam: `snapshot` and `rolePayload` already take `modelsPath`, and the default
+ * `piModelsPath()` follows `$PI_CODING_AGENT_DIR` through `piAgentDir`. The secret-leak gate
+ * derives `auth.json` the same way. */
+export function piSettingsPath(modelsPath) {
+    return path.join(path.dirname(modelsPath), "settings.json");
+}
+/** Per-poll cache of the parsed default, keyed by settings path: the snapshot runs on every
+ * poll while settings.json changes only when a user edits it, so an unchanged file costs one
+ * stat per poll instead of a re-read plus JSON.parse. Any write invalidates via
+ * dev/ino/mtime/size (stat-cache.cachedByStat, same freshness check as the other polled files);
+ * a missing or malformed file yields null and is not cached, so a mid-edit broken file recovers
+ * on the next poll exactly like before. */
+const settingsCache = new Map();
+/** The keys of pi's settings.json that decide the saved default (findInitialModel's inputs):
+ * the default pair, its preferred thinking, and the two scope patterns — `enabledModels`
+ * (pi starts on the first scoped model instead) and the project-local override file's own
+ * settings. */
+const DEFAULT_KEYS = [
+    "defaultProvider",
+    "defaultModel",
+    "defaultThinkingLevel",
+    "enabledModels",
+    "modelThinkingLevels",
+];
+/** The model pi starts on when tumwater names none, or null when it cannot be known. Mirrors
+ * step 3 of pi 1.2.0's start-up model choice ("saved default from settings") for a run started
+ * without `--provider`/`--model`. Null when the file is missing, unreadable, or not a JSON
+ * object; when `defaultProvider` and `defaultModel` are not both non-empty strings (pi uses a
+ * saved default only as a pair); when `enabledModels` is a non-empty array (pi then starts on
+ * the first scoped model, a pattern tumwater does not resolve); or when
+ * `<projectRoot>/.pi/settings.json` exists and names any of the default keys — pi merges that
+ * file over the global one only for a project it trusts, and tumwater cannot tell whether it
+ * does, so showing nothing is better than naming a model pi may not run. Otherwise returns
+ * `{ provider, model }` with `thinking` from `modelThinkingLevels["<provider>/<model>"]` when
+ * that is a string, else from `defaultThinkingLevel` when that is a string — pi's precedence. */
+export function readPiDefaultModel(settingsPath, projectRoot) {
+    return cachedByStat(settingsCache, settingsPath, // Keyed by path so distinct roots and test files never collide.
+    settingsPath, () => readPiDefaultModelUncached(settingsPath, projectRoot), (defaultModel) => ({ ...defaultModel }));
+}
+function readPiDefaultModelUncached(settingsPath, projectRoot) {
+    // readJsonFile is the shared "missing or torn reads as no data" policy for a JSON object
+    // file; the nested shapes get the same isJsonObject guard.
+    const doc = readJsonFile(settingsPath);
+    if (!doc)
+        return null;
+    const { defaultProvider, defaultModel } = doc;
+    if (typeof defaultProvider !== "string" || defaultProvider === "")
+        return null;
+    if (typeof defaultModel !== "string" || defaultModel === "")
+        return null;
+    if (Array.isArray(doc.enabledModels) && doc.enabledModels.length > 0)
+        return null;
+    // A project-local override that names any default key means pi's final choice depends on
+    // whether it trusts the project — unknowable to tumwater, so show nothing.
+    const proj = readJsonFile(path.join(projectRoot, ".pi", "settings.json"));
+    if (proj) {
+        for (const key of DEFAULT_KEYS) {
+            if (proj[key] !== undefined)
+                return null;
+        }
+    }
+    const key = `${defaultProvider}/${defaultModel}`;
+    const levels = doc.modelThinkingLevels;
+    const level = isJsonObject(levels) ? levels[key] : undefined;
+    let thinking;
+    if (typeof level === "string")
+        thinking = level;
+    else if (typeof doc.defaultThinkingLevel === "string")
+        thinking = doc.defaultThinkingLevel;
+    return thinking !== undefined
+        ? { provider: defaultProvider, model: defaultModel, thinking }
+        : { provider: defaultProvider, model: defaultModel };
+}