one-code-extension 0.1.4 → 0.3.0

package/extensions/doctor/models.ts

@@ -0,0 +1,231 @@
+/**
+ * Which model each role runs on, and why (pure).
+ *
+ * The doctor does not re-decide anything: it calls the SAME resolvers the
+ * session uses — `resolveSubagentModel` for delegated work, `classifierCandidates`
+ * for auto mode's screener, `pickEconomicalContainedModel` for the web-fetch /
+ * recap reader, `resolveModelTier` for the prompt register — and reports their
+ * answers next to their sources. A user who asks "why did my subagent run on
+ * Haiku?" gets the resolver's own notice, not a paraphrase.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { loadAutoModeConfig } from "../auto-mode/config.ts";
+import { classifierCandidates, describeCandidate, type ClassifierNotice } from "../auto-mode/model-select.ts";
+import { ATTRIBUTION, capabilityFloor, configuredCapabilityKey, type FloorRole, type FloorVerdict, KEY_ADVICE, snapshotAgeMs } from "../lib/capability-index.ts";
+import { modelSpec, pricedInput } from "../lib/model-policy.ts";
+import {
+	currentCapabilitySnapshot,
+	intrinsicTier,
+	pickEconomicalContainedModel,
+	type PromptTier,
+	resolveModelTier,
+	tierOverride,
+} from "../lib/model-tier.ts";
+import { applicableSubagentDefault, loadSubagentDefault, type SubagentDefault } from "../subagents/default-model.ts";
+import { resolveSubagentModel, type SubagentModelResolution } from "../subagents/model-select.ts";
+import { contextLabel, type Finding, priceLabel, type ReportLine, type ReportSection, type SessionView } from "./report.ts";
+
+export interface ModelFacts {
+	session?: Model<Api>;
+	sessionTier?: PromptTier;
+	/** The register the system prompt is built in — the tier, or a CC_PROMPT_TIER override. */
+	promptTier: PromptTier;
+	promptTierForced: boolean;
+	subagent: SubagentModelResolution;
+	subagentConfigured?: SubagentDefault;
+	/** The configured default exists but does not apply to this session (Claude Code's env var on a non-Claude model). */
+	subagentConfiguredInapplicable: boolean;
+	classifier: { model?: Model<Api>; description?: string; notices: ClassifierNotice[]; configured?: string };
+	reader?: { model: Model<Api>; via: "tier" | "session" };
+	/**
+	 * The optional Artificial Analysis snapshot behind the measured capability
+	 * floor (lib/capability-index.ts): whether a key is configured, the snapshot's
+	 * age, and the verdict each automatic pick was judged on.
+	 */
+	capability: {
+		keyConfigured: boolean;
+		snapshot?: { fetchedAt: string; rows: number };
+		subagent?: FloorVerdict;
+		classifier?: FloorVerdict;
+		reader?: FloorVerdict;
+	};
+}
+
+export const TIER_LABEL: Record<PromptTier, string> = {
+	frontier: "frontier tier — terse Claude Code prompt",
+	workhorse: "workhorse tier — full Claude Code prompt",
+	cheap: "cheap tier — full prompt, Haiku register",
+	tiny: "tiny tier — full prompt plus weak-model scaffolding and grep/find/ls",
+};
+
+export function collectModelFacts(available: Model<Api>[], session: SessionView, home: string, env: NodeJS.ProcessEnv): ModelFacts {
+	const sessionModel = session.model;
+	const configuredAll = loadSubagentDefault(home, env);
+	const configured = applicableSubagentDefault(configuredAll, sessionModel);
+	const subagent = resolveSubagentModel({ configuredDefault: configured, sessionModel, available });
+	const autoConfig = loadAutoModeConfig(home);
+	const chain = classifierCandidates({
+		available,
+		sessionModel,
+		configured: autoConfig.classifierModel,
+		configuredSetForContainment: autoConfig.classifierModelSetFor,
+	});
+	const first = chain.candidates[0];
+	const reader = pickEconomicalContainedModel(available, sessionModel);
+	const snapshot = currentCapabilitySnapshot();
+	const verdict = (pick: Model<Api> | undefined, role: FloorRole): FloorVerdict | undefined =>
+		snapshot && sessionModel && pick && modelSpec(pick) !== modelSpec(sessionModel) ? capabilityFloor(snapshot, pick, sessionModel, role) : undefined;
+	const capability: ModelFacts["capability"] = {
+		keyConfigured: configuredCapabilityKey(home, env) !== undefined,
+		snapshot: snapshot ? { fetchedAt: snapshot.fetchedAt, rows: snapshot.rows.length } : undefined,
+		subagent: verdict(subagent.source === "automatic" ? subagent.model : undefined, "subagent"),
+		classifier: verdict(first?.source === "economical" ? first.model : undefined, "classifier"),
+		reader: verdict(reader?.via === "tier" ? reader.model : undefined, "reader"),
+	};
+	return {
+		capability,
+		session: sessionModel,
+		sessionTier: sessionModel ? intrinsicTier(sessionModel) : undefined,
+		promptTier: resolveModelTier(sessionModel, env),
+		promptTierForced: tierOverride(env) !== undefined,
+		subagent,
+		subagentConfigured: configuredAll,
+		subagentConfiguredInapplicable: configuredAll !== undefined && configured === undefined,
+		classifier: {
+			model: first?.model,
+			description: first ? describeCandidate(first) : undefined,
+			notices: chain.notices,
+			configured: autoConfig.classifierModel,
+		},
+		reader,
+	};
+}
+
+const SUBAGENT_SOURCE: Record<SubagentModelResolution["source"], string> = {
+	call: "named per call",
+	agent: "from the agent file",
+	default: "the configured default",
+	automatic: "automatic: cheapest capable model on this provider, cheaper than the main model",
+	session: "the main model — nothing cheaper and capable on this provider",
+};
+
+export function modelsSection(facts: ModelFacts, session: SessionView, findings: Finding[]): ReportSection {
+	const lines: ReportLine[] = [];
+	const { session: main } = facts;
+
+	if (!main) {
+		lines.push({
+			text: "Main: none — no model is available, so a session cannot start work yet",
+			level: "error",
+		});
+		return { title: "Models", lines };
+	}
+
+	const sourceNote =
+		session.modelSource === "session"
+			? "this session"
+			: session.modelSource === "default-setting"
+				? "saved default; the next start uses it"
+				: session.modelSource === "first-available"
+					? "no saved default — pi picks the first available model at startup"
+					: "";
+	const details = [priceLabel(main), contextLabel(main.contextWindow), sourceNote].filter(Boolean).join(" · ");
+	lines.push({ text: `Main: ${modelSpec(main)} — ${details}`, level: "ok" });
+	lines.push({
+		text: `Prompt register: ${TIER_LABEL[facts.promptTier]}${facts.promptTierForced ? " (forced by CC_PROMPT_TIER)" : ""}`,
+		indent: 1,
+		level: "dim",
+	});
+	if (session.thinkingLevel) lines.push({ text: `Effort: ${session.thinkingLevel} (/effort or shift+tab to change)`, indent: 1, level: "dim" });
+
+	const sub = facts.subagent;
+	if (sub.model) {
+		lines.push({ text: `Subagents and workflow agents: ${modelSpec(sub.model)} — ${SUBAGENT_SOURCE[sub.source]}`, level: "ok" });
+		if (facts.subagentConfigured) {
+			const knob = facts.subagentConfigured.source === "subagentModel setting" ? "subagentModel in ~/.onecode/settings.json" : "CLAUDE_CODE_SUBAGENT_MODEL";
+			lines.push({
+				text: `Setting: "${facts.subagentConfigured.spec}" via ${knob}${facts.subagentConfiguredInapplicable ? " — not applied: Claude Code's knob applies only when the main model is a Claude model" : ""}`,
+				indent: 1,
+				level: facts.subagentConfiguredInapplicable ? "warn" : "dim",
+			});
+		}
+		for (const notice of sub.notices) {
+			lines.push({ text: notice, indent: 1, level: "warn" });
+			findings.push({ level: "warn", text: `Subagent model: ${notice}`, fix: "Re-set the default with /subagent on this session, or /subagent clear." });
+		}
+	} else {
+		lines.push({ text: "Subagents: no model resolves", level: "error" });
+	}
+
+	const classifier = facts.classifier;
+	if (classifier.model) {
+		const live = session.permission?.classifier;
+		const pinned = session.permission?.pinned && live ? ` — screening this session on ${live}` : "";
+		lines.push({ text: `Auto-mode classifier: ${classifier.description ?? modelSpec(classifier.model)}${pinned}`, level: "ok" });
+	} else {
+		lines.push({ text: "Auto-mode classifier: none — auto mode stays out of the mode cycle until a model is available", level: "warn" });
+	}
+	for (const notice of classifier.notices) {
+		lines.push({ text: notice.text, indent: 1, level: notice.level === "warning" ? "warn" : "dim" });
+		if (notice.level === "warning") {
+			findings.push({ level: "warn", text: `Classifier: ${notice.text}`, fix: "Pick a model with /auto-mode model, or /auto-mode model clear for the automatic choice." });
+		}
+	}
+
+	if (facts.reader) {
+		lines.push({
+			text: `Web-fetch and recap reader: ${modelSpec(facts.reader.model)} — ${facts.reader.via === "tier" ? "cheapest capable model on this provider" : "the main model"}`,
+			level: "dim",
+		});
+	}
+
+	// The measured capability floor: what each automatic pick was judged on, or
+	// how to switch it on. Scores shown carry the attribution the free API requires.
+	const cap = facts.capability;
+	const verdictLine = (label: string, v: FloorVerdict | undefined): ReportLine | undefined => {
+		if (!v) return undefined;
+		if (v.verdict === "unscored") return { text: `${label}: not measured — ${v.reason ?? "no confirmed score"}; the name-class rule decided`, indent: 1, level: "dim" };
+		const basis = v.candidate?.variant === "non-reasoning" ? "thinking-off" : "default-effort";
+		return {
+			text: `${label}: coding index ${v.candidate?.coding} vs floor ${v.floor?.toFixed(1)} (${basis}; session ${v.session?.coding}, Sonnet 5 ${v.reference?.coding}) — ${v.verdict === "pass" ? "measured capable" : "below the floor"}`,
+			indent: 1,
+			level: "dim",
+		};
+	};
+	if (cap.snapshot) {
+		const ageH = Math.round(snapshotAgeMs({ fetchedAt: cap.snapshot.fetchedAt, source: "", rows: [] }) / 3_600_000);
+		lines.push({ text: `Capability scores: Artificial Analysis snapshot, ${cap.snapshot.rows} models, ${ageH} h old — measured picks for subagents and the classifier`, level: "ok" });
+		for (const line of [verdictLine("Subagent pick", cap.subagent), verdictLine("Classifier pick", cap.classifier), verdictLine("Reader pick", cap.reader)]) {
+			if (line) lines.push(line);
+		}
+		lines.push({ text: ATTRIBUTION, indent: 1, level: "dim" });
+	} else if (cap.keyConfigured) {
+		lines.push({ text: "Capability scores: key configured, snapshot not fetched yet — it downloads in the background on the next interactive start", level: "dim" });
+	} else {
+		lines.push({ text: "Capability scores: none — automatic picks use model names and generations only", level: "warn" });
+		findings.push({ level: "warn", text: "No Artificial Analysis key: subagent and classifier picks cannot be judged by measured coding ability.", fix: KEY_ADVICE });
+	}
+
+	if (session.permission) {
+		const mode = session.permission.mode;
+		const from = session.permission.source ? ` (${session.permission.source})` : "";
+		lines.push({ text: `Permission mode: ${mode}${from} — ctrl+q cycles, /permissions lists the rules`, level: "dim" });
+	}
+
+	if (facts.sessionTier === "tiny") {
+		findings.push({
+			level: "warn",
+			text: `${modelSpec(main)} is classed as a tiny-tier model: One Code adds weak-model scaffolding and search tools, and never auto-selects a tiny model for subagents or the classifier.`,
+			fix: "For coding work pick a cheap- or workhorse-tier model with /model; see /doctor presets.",
+		});
+	}
+	if (pricedInput(main) === undefined) {
+		lines.push({
+			text: "This model carries no price in the catalog, so automatic cost-based choices (cheaper subagents, a cheaper classifier) fall back to the main model.",
+			indent: 1,
+			level: "dim",
+		});
+	}
+	return { title: "Models", lines };
+}

package/extensions/doctor/presets.ts

@@ -0,0 +1,208 @@
+/**
+ * Model presets (pure): three named configurations — economical, balanced,
+ * maximum quality — computed against the models the user can actually run,
+ * shown with the concrete model each role would get, and applied with
+ * `/doctor preset <name>`.
+ *
+ * Presets never leave the current provider family: every automatic model choice
+ * in One Code is contained to the session's provider (a subagent inherits the
+ * transcript, the classifier reads the prompts — docs/decisions/model-policy.md),
+ * and a preset is a bundle of those same choices. A user who wants another
+ * provider switches with /model first and reruns /doctor presets there.
+ *
+ * Each preset pins ONE thing — the main model — and sets the two secondary
+ * knobs to the shape that matches its intent:
+ *   economical        main = cheapest capable (cheap tier, never tiny); subagents inherit it;
+ *                     classifier automatic (lands on the same model)
+ *   balanced          main = cheapest workhorse-tier model; subagents automatic (the
+ *                     cheapest model at the main's floor — often the main itself,
+ *                     since subagents share the classifier's workhorse floor);
+ *                     classifier automatic (workhorse floor)
+ *   maximum quality   main = the strongest (frontier, else priciest workhorse);
+ *                     subagents inherit it; classifier automatic
+ * so applying a preset is three settings writes the user can each undo by hand
+ * (/model, /subagent, /auto-mode model). The rows display what the resolvers
+ * would pick for that main model, computed with the resolvers themselves.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { classifierCandidates } from "../auto-mode/model-select.ts";
+import { isPriorGeneration, lacksToolCalls } from "../lib/model-facts.ts";
+import { isDatedDuplicate, modelsContainedToSession, modelSpec, pricedInput } from "../lib/model-policy.ts";
+import { intrinsicTier, type PromptTier } from "../lib/model-tier.ts";
+import { resolveSubagentModel } from "../subagents/model-select.ts";
+import type { ReportLine, ReportSection } from "./report.ts";
+
+export type PresetName = "economical" | "balanced" | "quality";
+
+export const PRESET_NAMES: readonly PresetName[] = ["economical", "balanced", "quality"];
+
+export const PRESET_LABEL: Record<PresetName, string> = {
+	economical: "economical",
+	balanced: "balanced",
+	quality: "maximum quality",
+};
+
+export const PRESET_INTENT: Record<PresetName, string> = {
+	economical: "lowest cost — one cheap model for everything",
+	balanced: "a capable main model, delegated work on the cheapest model at its floor",
+	quality: "the strongest model for the main session and its subagents",
+};
+
+export interface PresetPlan {
+	name: PresetName;
+	label: string;
+	main: Model<Api>;
+	/** What subagents resolve to under this preset, and the setting that produces it. */
+	subagents: { model: Model<Api>; setting: "inherit" | "auto" };
+	classifier?: Model<Api>;
+	/** True when the main session already runs this preset's main model. */
+	current: boolean;
+	/** Why the pick is weaker than the preset promises (one provider, one model…). */
+	note?: string;
+}
+
+/** Only well-known reasons a preset list is empty; the section renders them. */
+export type PresetsUnavailable = "no-model" | "no-priced-models";
+
+/**
+ * The candidate pool for one provider family: contained, priced, dated duplicates
+ * collapsed when the undated alias is present (`claude-haiku-4-5-20251001` next
+ * to `claude-haiku-4-5`). Tiny-tier rows stay in the pool only as a last resort.
+ */
+export function presetPool(available: Model<Api>[], sessionModel: Model<Api>): Model<Api>[] {
+	const contained = modelsContainedToSession(available, sessionModel).filter(
+		// A preset recommends a MAIN model: never one a generation behind its family
+		// or one models.dev says cannot call tools (model-facts.ts), whatever its tier.
+		(m) => pricedInput(m) !== undefined && !isPriorGeneration(m) && !lacksToolCalls(m),
+	);
+	return contained.filter((m) => !isDatedDuplicate(m, contained));
+}
+
+const price = (m: Model<Api>): number => pricedInput(m) ?? 0;
+const byTier = (pool: Model<Api>[], tier: PromptTier): Model<Api>[] => pool.filter((m) => intrinsicTier(m) === tier);
+const cheapest = (models: Model<Api>[]): Model<Api> | undefined => [...models].sort((a, b) => price(a) - price(b))[0];
+const priciest = (models: Model<Api>[]): Model<Api> | undefined => [...models].sort((a, b) => price(b) - price(a))[0];
+
+function pickMain(name: PresetName, pool: Model<Api>[]): { model: Model<Api>; note?: string } | undefined {
+	const cheap = byTier(pool, "cheap");
+	const workhorse = byTier(pool, "workhorse");
+	const frontier = byTier(pool, "frontier");
+	const capable = [...cheap, ...workhorse, ...frontier];
+	switch (name) {
+		case "economical": {
+			const pick = cheapest(cheap) ?? cheapest(workhorse) ?? cheapest(frontier);
+			if (pick) return { model: pick, note: cheap.length === 0 ? "no cheap-tier model on this provider; the cheapest capable one serves" : undefined };
+			const tiny = cheapest(pool);
+			return tiny ? { model: tiny, note: "only tiny-tier models on this provider — expect weaker results" } : undefined;
+		}
+		case "balanced": {
+			const pick = cheapest(workhorse) ?? cheapest(frontier) ?? priciest(cheap);
+			if (pick) return { model: pick, note: workhorse.length === 0 ? "no workhorse-tier model on this provider" : undefined };
+			const any = priciest(pool);
+			return any ? { model: any, note: "only tiny-tier models on this provider — expect weaker results" } : undefined;
+		}
+		case "quality": {
+			const pick = priciest(frontier) ?? priciest(workhorse) ?? priciest(capable) ?? priciest(pool);
+			if (!pick) return undefined;
+			const note =
+				frontier.length === 0 && workhorse.length === 0
+					? "no frontier- or workhorse-tier model on this provider"
+					: frontier.length === 0
+						? "no frontier-tier model on this provider; the strongest workhorse serves"
+						: undefined;
+			return { model: pick, note };
+		}
+	}
+}
+
+/**
+ * The three presets for the session's provider family. Empty with a reason when
+ * there is no session model (nothing to contain to) or no priced model (tiers
+ * cannot be told apart, so a preset would be a guess).
+ */
+export function computePresets(
+	available: Model<Api>[],
+	sessionModel: Model<Api> | undefined,
+): { presets: PresetPlan[]; unavailable?: PresetsUnavailable } {
+	if (!sessionModel) return { presets: [], unavailable: "no-model" };
+	const pool = presetPool(available, sessionModel);
+	if (pool.length === 0) return { presets: [], unavailable: "no-priced-models" };
+
+	const presets: PresetPlan[] = [];
+	for (const name of PRESET_NAMES) {
+		const main = pickMain(name, pool);
+		if (!main) continue;
+		const inherit = name !== "balanced";
+		// The resolvers judge the preset's main model as if it were the session's,
+		// over the same catalog the live session uses, so the preview names exactly
+		// what applying the preset produces.
+		const subagentModel = inherit
+			? main.model
+			: (resolveSubagentModel({ sessionModel: main.model, available }).model ?? main.model);
+		const classifier = classifierCandidates({ available, sessionModel: main.model }).candidates[0]?.model;
+		presets.push({
+			name,
+			label: PRESET_LABEL[name],
+			main: main.model,
+			subagents: { model: subagentModel, setting: inherit ? "inherit" : "auto" },
+			classifier,
+			current: modelSpec(main.model) === modelSpec(sessionModel),
+			note: main.note,
+		});
+	}
+	return { presets };
+}
+
+export function findPreset(presets: PresetPlan[], raw: string): PresetPlan | undefined {
+	const wanted = raw.trim().toLowerCase().replace(/\s+/g, "-");
+	const aliases: Record<string, PresetName> = { economical: "economical", economy: "economical", cheap: "economical", balanced: "balanced", balance: "balanced", quality: "quality", "maximum-quality": "quality", max: "quality", maximum: "quality", best: "quality" };
+	const name = aliases[wanted];
+	return name ? presets.find((p) => p.name === name) : undefined;
+}
+
+const shortId = (m: Model<Api>): string => m.id;
+
+export function presetsSection(result: ReturnType<typeof computePresets>, sessionModel: Model<Api> | undefined): ReportSection {
+	const lines: ReportLine[] = [];
+	if (result.unavailable === "no-model") {
+		lines.push({ text: "Connect a provider first (/login); presets are computed for the provider your main model runs on.", level: "dim" });
+		return { title: "Presets", lines };
+	}
+	if (result.unavailable === "no-priced-models" || result.presets.length === 0) {
+		lines.push({ text: "No priced models on this provider, so tiers cannot be told apart and no preset is offered.", level: "dim" });
+		return { title: "Presets", lines };
+	}
+	const family = sessionModel ? sessionModel.provider : "";
+	for (const preset of result.presets) {
+		const sub = preset.subagents.setting === "inherit" ? "same" : shortId(preset.subagents.model);
+		const cls = preset.classifier ? shortId(preset.classifier) : "none";
+		const cost = pricedInput(preset.main);
+		const tail = [cost !== undefined ? `$${cost}/M in` : "", preset.current ? "← current main model" : ""].filter(Boolean).join(" · ");
+		lines.push({
+			text: `${preset.label}: main ${shortId(preset.main)} · subagents ${sub} · classifier ${cls}${tail ? ` — ${tail}` : ""}`,
+			level: preset.current ? "ok" : "info",
+		});
+		lines.push({ text: PRESET_INTENT[preset.name] + (preset.note ? ` (${preset.note})` : ""), indent: 1, level: "dim" });
+	}
+	return {
+		title: "Presets",
+		subtitle: `within ${family} · apply with /doctor preset <economical|balanced|quality>`,
+		lines,
+	};
+}
+
+/**
+ * The three settings writes a preset amounts to, one line each with its undo —
+ * the text `/doctor preset` reports after applying. `mainSwitched` false means
+ * the session already ran the preset's main model, so that line says so.
+ */
+export function describePresetChanges(preset: PresetPlan, mainSwitched = true): string[] {
+	return [
+		mainSwitched ? `main model → ${modelSpec(preset.main)} (undo: /model)` : `main model: already ${modelSpec(preset.main)}`,
+		preset.subagents.setting === "inherit"
+			? "subagent default → inherit the main model (undo: /subagent clear)"
+			: `subagent default → automatic (picks ${modelSpec(preset.subagents.model)}; undo: /subagent)`,
+		`auto-mode classifier → automatic${preset.classifier ? ` (picks ${modelSpec(preset.classifier)})` : ""} (undo: /auto-mode model)`,
+	];
+}

package/extensions/doctor/report.ts

@@ -0,0 +1,189 @@
+/**
+ * The doctor report (pure): the data shape every check writes into, and the
+ * plain-text renderer both the `/doctor` panel and the `onecode doctor` CLI
+ * print from.
+ *
+ * Shape follows Claude Code's `claude doctor` terminal diagnostics — titled
+ * sections of `└ label: value` lines, a warnings block, one closing verdict —
+ * extended with what a One Code user actually needs on a first session and
+ * Claude Code never has to explain: which provider is ready, which model each
+ * role (main, subagents, classifier, reader) resolves to and why, what of the
+ * imported Claude Code configuration is honoured, and which external programs
+ * are missing. Rationale: docs/decisions/doctor.md.
+ *
+ * No pi imports. The wiring (index.ts, cli.ts) gathers the live inputs and hands
+ * them to `buildDoctorReport`; everything below is deterministic given them.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { McpStatusEvent } from "../lib/mcp-status.ts";
+import { wrapProse } from "../subagents/panel-render.ts";
+import { countNoun } from "../lib/tui-render.ts";
+export { countNoun };
+
+export type LineLevel = "ok" | "info" | "warn" | "error" | "dim";
+
+export interface ReportLine {
+	text: string;
+	level?: LineLevel;
+	/** Nesting depth: 0 = `└ ` item, 1 = `  └ ` sub-item, 2 = deeper. */
+	indent?: number;
+}
+
+export interface ReportSection {
+	title: string;
+	lines: ReportLine[];
+	/** A dim trailer under the title (scope, hint). */
+	subtitle?: string;
+}
+
+export interface Finding {
+	level: "warn" | "error";
+	text: string;
+	/** What to do about it, when known. Rendered as a `Fix:` line. */
+	fix?: string;
+}
+
+export interface DoctorReport {
+	title: string;
+	/** Two or three plain sentences a first-time user can act on. */
+	summary: string;
+	sections: ReportSection[];
+	findings: Finding[];
+	/** False when an error-level finding means a session cannot do useful work yet. */
+	ready: boolean;
+}
+
+/** Everything the environment tells the doctor without touching pi's registry. */
+export interface DoctorEnvironment {
+	cwd: string;
+	home: string;
+	/** pi's live agent dir (honours PI_CODING_AGENT_DIR — the app isolates to ~/.onecode/agent). */
+	agentDir: string;
+	/** One Code's own state dir (~/.onecode or ONECODE_STATE_DIR). */
+	stateDir: string;
+	env: NodeJS.ProcessEnv;
+	platform: string;
+	arch: string;
+	nodeVersion: string;
+	oneCodeVersion: string;
+	/** How One Code was launched: the bundled `onecode` app or the extension on the user's own pi. */
+	install: "app" | "pi-package";
+	piVersion?: string;
+	/** Result of the registry lookup for the newest release, when one was attempted. */
+	latest?: { status: "current" | "behind" | "unknown" | "skipped"; version?: string; reason?: string };
+}
+
+/** The slice of pi's ModelRegistry the checks read — structural so tests and the CLI can supply it. */
+export interface RegistryView {
+	/** Every catalog row, authenticated or not (`getAll()`). */
+	all: Model<Api>[];
+	/** Rows the user has working credentials for (`getAvailable()`). */
+	available: Model<Api>[];
+	authStatus(provider: string): { configured: boolean; source?: string; label?: string };
+	displayName?(provider: string): string;
+}
+
+/** Live session facts; the CLI fills what it can from settings and leaves the rest undefined. */
+export interface SessionView {
+	model?: Model<Api>;
+	/** Where `model` came from: the running session, pi's saved default, or nowhere. */
+	modelSource: "session" | "default-setting" | "first-available" | "none";
+	thinkingLevel?: string;
+	permission?: { mode: string; classifier?: string; pinned?: boolean; source?: string };
+	mcp?: McpStatusEvent;
+}
+
+export const REPORT_TITLE = "One Code doctor";
+
+const GLYPH: Record<LineLevel, string> = { ok: "✔", info: "", warn: "⚠", error: "✘", dim: "" };
+
+export interface RenderOptions {
+	width?: number;
+	/** Theme painter; identity when absent (the CLI prints plain text). */
+	paint?: (color: string, text: string) => string;
+	bold?: (text: string) => string;
+}
+
+const COLOR: Record<LineLevel, string> = { ok: "success", info: "text", warn: "warning", error: "error", dim: "dim" };
+
+/** Resolve the optional painters once; identity when absent (the CLI prints plain text). */
+function painters(options: RenderOptions) {
+	return {
+		width: Math.max(20, options.width ?? 100),
+		paint: options.paint ?? ((_color: string, text: string) => text),
+		bold: options.bold ?? ((text: string) => text),
+	};
+}
+
+type Paint = (color: string, text: string) => string;
+
+/**
+ * One `└ `-style entry: the glyph for its level, word-wrapped to `width`, with
+ * continuation lines aligned under the text (past the bullet and the glyph) so a
+ * 300-char path never produces an overwide line (pi-tui crashes on one).
+ */
+function renderEntry(prefix: string, text: string, level: LineLevel | undefined, width: number, paint: Paint): string[] {
+	const glyph = level ? GLYPH[level] : "";
+	const lead = glyph ? `${glyph} ` : "";
+	return wrapProse(text, Math.max(10, width - prefix.length - lead.length)).map((segment, i) => {
+		const head = i === 0 ? `${prefix}${lead}` : " ".repeat(prefix.length + lead.length);
+		return head + (level ? paint(COLOR[level], segment) : segment);
+	});
+}
+
+/** One section — title, optional dim subtitle, its `└ ` lines — rendered standalone (the `/doctor presets` listing). */
+export function renderSection(section: ReportSection, options: RenderOptions = {}): string[] {
+	const { width, paint, bold } = painters(options);
+	const out: string[] = [bold(section.title) + (section.subtitle ? paint("dim", ` — ${section.subtitle}`) : "")];
+	if (section.lines.length === 0) out.push(paint("dim", "└ (nothing)"));
+	for (const line of section.lines) out.push(...renderEntry(`${"  ".repeat(line.indent ?? 0)}└ `, line.text, line.level, width, paint));
+	return out;
+}
+
+/** Render the whole report to lines no wider than `width`, Claude Code's `└ ` style. */
+export function renderDoctorReport(report: DoctorReport, options: RenderOptions = {}): string[] {
+	const { width, paint, bold } = painters(options);
+	const out: string[] = [bold(report.title), ...wrapProse(report.summary, width)];
+	for (const section of report.sections) out.push("", ...renderSection(section, options));
+	out.push("");
+	if (report.findings.length === 0) {
+		out.push(paint("success", "No setup issues found."));
+		return out;
+	}
+	const errors = report.findings.filter((f) => f.level === "error").length;
+	const warns = report.findings.length - errors;
+	out.push(bold(`Issues (${[errors ? countNoun(errors, "problem") : "", warns ? countNoun(warns, "warning") : ""].filter(Boolean).join(", ")})`));
+	for (const finding of report.findings) {
+		out.push(...renderEntry("└ ", finding.text, finding.level, width, paint));
+		if (finding.fix) out.push(...renderEntry("  ", `Fix: ${finding.fix}`, "dim", width, paint));
+	}
+	return out;
+}
+
+/** Plain-text form for `ctx.ui.notify`, `-p` output and the CLI. */
+export function renderDoctorText(report: DoctorReport, width = 100): string {
+	return renderDoctorReport(report, { width }).join("\n");
+}
+
+/** `$3/M in · $15/M out`, or `unpriced` when the catalog carries no usable price. */
+export function priceLabel(model: Model<Api>): string {
+	const input = model.cost?.input;
+	const output = model.cost?.output;
+	if (typeof input !== "number" || input <= 0) return "unpriced";
+	return typeof output === "number" && output > 0 ? `$${input}/M in · $${output}/M out` : `$${input}/M in`;
+}
+
+/** `1M`, `200k`, `32k` — a context window as users read it. */
+export function contextLabel(tokens: number | undefined): string {
+	if (!tokens || tokens <= 0) return "";
+	if (tokens >= 1_000_000) return `${Number.isInteger(tokens / 1_000_000) ? tokens / 1_000_000 : (tokens / 1_000_000).toFixed(1)}M context`;
+	return `${Math.round(tokens / 1000)}k context`;
+}
+
+/** `~/…` for anything under home, so paths stay readable at any width. */
+export function shortenHome(path: string, home: string): string {
+	if (path === home) return "~";
+	const root = home.endsWith("/") ? home : `${home}/`;
+	return path.startsWith(root) ? `~/${path.slice(root.length)}` : path;
+}

package/extensions/doctor/update-lookup.ts

@@ -0,0 +1,46 @@
+/**
+ * Newest-release lookup for the doctor's Installation section (pure given a
+ * fetch). Mirrors the app's daily update check (app/update-check.mjs): the same
+ * registry endpoints, a short timeout, silent on failure, and skipped under
+ * pi's offline switch or ONECODE_NO_UPDATE_CHECK — a diagnostic must never hang
+ * on the network or restore egress the user turned off.
+ */
+
+import { compareVersions } from "../lib/pi-version.ts";
+import type { DoctorEnvironment } from "./report.ts";
+
+export const APP_REGISTRY_URL = "https://registry.npmjs.org/@one-ai%2Fone-code/latest";
+export const PACKAGE_REGISTRY_URL = "https://registry.npmjs.org/one-code-extension/latest";
+export const LOOKUP_TIMEOUT_MS = 3000;
+
+export type LatestLookup = NonNullable<DoctorEnvironment["latest"]>;
+
+/** pi's truthy-flag reading for PI_OFFLINE (1/true/yes). */
+export function isOffline(env: NodeJS.ProcessEnv): boolean {
+	return /^(1|true|yes)$/i.test(String(env.PI_OFFLINE ?? "").trim());
+}
+
+export async function lookupLatestVersion(input: {
+	install: "app" | "pi-package";
+	current: string;
+	env: NodeJS.ProcessEnv;
+	fetchImpl?: typeof fetch;
+	timeoutMs?: number;
+}): Promise<LatestLookup> {
+	if (isOffline(input.env)) return { status: "skipped", reason: "offline" };
+	if (input.env.ONECODE_NO_UPDATE_CHECK === "1") return { status: "skipped", reason: "ONECODE_NO_UPDATE_CHECK=1" };
+	const url = input.install === "app" ? APP_REGISTRY_URL : PACKAGE_REGISTRY_URL;
+	const fetchImpl = input.fetchImpl ?? globalThis.fetch;
+	try {
+		const response = await fetchImpl(url, { signal: AbortSignal.timeout(input.timeoutMs ?? LOOKUP_TIMEOUT_MS) });
+		if (!response.ok) return { status: "unknown", reason: `registry answered ${response.status}` };
+		const body = (await response.json()) as { version?: unknown };
+		if (typeof body.version !== "string") return { status: "unknown", reason: "unexpected registry payload" };
+		const cmp = compareVersions(body.version, input.current);
+		if (cmp === undefined) return { status: "unknown", version: body.version, reason: "unparseable version" };
+		return { status: cmp > 0 ? "behind" : "current", version: body.version };
+	} catch (error) {
+		const message = error instanceof Error ? (error.name === "TimeoutError" ? "timed out" : error.message) : String(error);
+		return { status: "unknown", reason: message };
+	}
+}