@booplex/bpx-consult 0.1.0

package/src/cli-backend.ts

@@ -0,0 +1,256 @@
+/**
+ * cli-backend — external-CLI advisor calls via async pi.exec.
+ *
+ * An alternative to the inline `completeSimple` path: pipe the fitted context
+ * (as markdown) to an external CLI's stdin (codex / claude / opencode) and parse
+ * the reply. Replaces pi-external-advisor's `execSync` with async `pi.exec` —
+ * execSync blocks the event loop and would serialize a Promise.all council.
+ *
+ * The whole point of going async is that a CLI-backed council member can run
+ * in parallel with an inline member. A solo CLI call doesn't prove that; the
+ * mixed inline+cli council smoke test does.
+ *
+ * Defensive parsing is load-bearing: real CLIs print deprecation notices,
+ * progress warnings, and auth chatter to stdout/stderr before the payload.
+ * We don't crash on junk preamble — we scan for the JSON payload (codex/
+ * opencode JSONL) or fall back to the whole stdout (claude plain text).
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+import { spawn } from "node:child_process";
+import { withTimeout } from "./timeout.js";
+
+export type CliCommand = "codex" | "claude" | "opencode";
+
+/** Pre-baked invocations. Read prompt from stdin (`-` or `-p`). */
+const CLI_INVOCATIONS: Record<CliCommand, { command: string; args: string[] }> = {
+	codex: { command: "codex", args: ["exec", "--sandbox", "read-only", "--skip-git-repo-check", "-"] },
+	claude: { command: "claude", args: ["-p"] },
+	opencode: { command: "opencode", args: ["exec", "--sandbox", "read-only", "--skip-git-repo-check", "-"] },
+};
+
+export interface CliBackendConfig {
+	type: "cli";
+	command: CliCommand | string;
+	args?: string[];
+	timeoutMs?: number;
+}
+
+export interface CliCallInput {
+	systemPrompt: string;
+	/** Fitted, window-safe messages (already through §C). */
+	messages: Message[];
+	backend: CliBackendConfig;
+	signal: AbortSignal | undefined;
+	/** Working directory for the subprocess (usually ctx.cwd). */
+	cwd?: string;
+}
+
+export interface CliCallResult {
+	text: string;
+	/** Whether the subprocess timed out (res.killed). */
+	timedOut: boolean;
+	/** Non-zero exit without timeout. */
+	exitCode: number | null;
+	errorMessage?: string;
+}
+
+const DEFAULT_CLI_TIMEOUT_MS = 120_000;
+
+/**
+ * Run one CLI advisor call. Never throws — every failure path returns a result
+ * with errorMessage set, so a council can collect it as a failed member without
+ * a try/catch at every call site.
+ *
+ * Uses node:child_process.spawn directly (async, non-blocking) rather than
+ * pi.exec — pi 0.80.x's ExecOptions doesn't expose stdin, and these CLIs read
+ * the prompt from stdin. spawn is the right primitive: it's non-blocking (unlike
+ * execSync, which is what makes pi-external-advisor serialize under a council),
+ * so a CLI council member runs truly parallel to an inline completeSimple member.
+ */
+export async function callCliAdvisor(input: CliCallInput): Promise<CliCallResult> {
+	const { systemPrompt, messages, backend, signal, cwd } = input;
+	const inv = resolveInvocation(backend);
+	const promptText = buildPromptText(systemPrompt, messages);
+	const timeoutMs = backend.timeoutMs && backend.timeoutMs > 0 ? backend.timeoutMs : DEFAULT_CLI_TIMEOUT_MS;
+
+	// Race the subprocess against a wall-clock timeout that fires its own abort
+	// controller (linked to the parent signal so user-abort still propagates).
+	const outcome = await withTimeout(timeoutMs, signal, (timeoutSignal) => runSpawn(inv, promptText, cwd, timeoutSignal));
+
+	if (outcome.timedOut) {
+		return { text: "", timedOut: true, exitCode: null, errorMessage: `CLI "${inv.command}" timed out after ${timeoutMs}ms` };
+	}
+	if (!outcome.ok) {
+		// Non-timeout throw — likely ENOENT (CLI not installed).
+		const message = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
+		return { text: "", timedOut: false, exitCode: null, errorMessage: `CLI "${inv.command}" failed to run: ${message}` };
+	}
+
+	const { stdout, code } = outcome.value;
+	// FR5 branch order (from rpiv-args): non-zero exit here. (Timeout is handled
+	// above via withTimeout aborting the subprocess; a kill surfaces as a throw.)
+	if (code !== 0) {
+		const detail = truncate(outcome.value.stderr || stdout, 500);
+		return { text: "", timedOut: false, exitCode: code, errorMessage: `CLI "${inv.command}" exited ${code}${detail ? `: ${detail}` : ""}` };
+	}
+
+	const text = parseCliOutput(stdout, backend.command as CliCommand);
+	if (!text.trim()) {
+		return { text: "", timedOut: false, exitCode: 0, errorMessage: `CLI "${inv.command}" returned no usable output` };
+	}
+	return { text: text.trim(), timedOut: false, exitCode: 0 };
+}
+
+/** Spawn the CLI, write the prompt to stdin, collect stdout/stderr, resolve on exit. */
+function runSpawn(
+	inv: { command: string; args: string[] },
+	promptText: string,
+	cwd: string | undefined,
+	signal: AbortSignal,
+): Promise<{ stdout: string; stderr: string; code: number }> {
+	return new Promise((resolve, reject) => {
+		let child;
+		try {
+			child = spawn(inv.command, inv.args, { cwd, stdio: ["pipe", "pipe", "pipe"], signal });
+		} catch (e) {
+			reject(e);
+			return;
+		}
+
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.on("data", (d) => { stdout += d.toString(); });
+		child.stderr?.on("data", (d) => { stderr += d.toString(); });
+
+		child.on("error", reject); // ENOENT etc.
+		child.on("close", (code) => resolve({ stdout, stderr, code: code ?? 0 }));
+
+		// Write the prompt to stdin and close it so the CLI knows input is complete.
+		child.stdin?.on("error", reject);
+		child.stdin?.end(promptText);
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Invocation resolution
+// ---------------------------------------------------------------------------
+
+function resolveInvocation(backend: CliBackendConfig): { command: string; args: string[] } {
+	// Custom command path: user specified a command + args verbatim.
+	if (backend.args && backend.args.length > 0) {
+		return { command: String(backend.command), args: backend.args };
+	}
+	const preset = CLI_INVOCATIONS[backend.command as CliCommand];
+	if (preset) return preset;
+	// Unknown command name with no preset and no args — treat the string itself
+	// as a bare command (user-defined CLI).
+	return { command: String(backend.command), args: [] };
+}
+
+// ---------------------------------------------------------------------------
+// Prompt assembly — markdown transcript piped to stdin
+// ---------------------------------------------------------------------------
+
+function buildPromptText(systemPrompt: string, messages: Message[]): string {
+	const lines: string[] = [systemPrompt, "", "---", ""];
+	for (const msg of messages) {
+		const role = msg.role === "user" ? "User" : msg.role === "assistant" ? "Assistant" : "Tool result";
+		const text = messageToText(msg);
+		if (!text.trim()) continue;
+		lines.push(`=== ${role} ===`, text, "");
+	}
+	return lines.join("\n");
+}
+
+function messageToText(msg: Message): string {
+	if (msg.role === "user") {
+		return typeof msg.content === "string" ? msg.content : msg.content.filter((b): b is { type: "text"; text: string } => b.type === "text").map((b) => b.text).join("\n");
+	}
+	if (msg.role === "assistant") {
+		return msg.content
+			.map((b) => {
+				if (b.type === "text") return b.text;
+				if (b.type === "toolCall") return `[tool call: ${b.name}]`;
+				if (b.type === "thinking") return "";
+				return "";
+			})
+			.filter(Boolean)
+			.join("\n");
+	}
+	return msg.content.filter((b): b is { type: "text"; text: string } => b.type === "text").map((b) => b.text).join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Defensive output parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse CLI stdout into advisor text.
+ *
+ * - JSONL producers (codex, opencode): scan lines for `{"type":"item.completed",...}`
+ *   or any line that JSON-parses to an object with a `.text` / `.item.text` field.
+ *   Ignore everything else (deprecation notices, progress chatter, auth warnings).
+ * - Plain-text producers (claude): return the trimmed stdout.
+ *
+ * The junk-preamble tolerance is the whole point: a real codex run prints a
+ * "Using model X" line and sometimes a warning before the payload. We must not
+ * crash or return that junk as the advisor's reply.
+ */
+export function parseCliOutput(stdout: string, command: CliCommand): string {
+	const trimmed = stdout.trim();
+	if (!trimmed) return "";
+
+	// JSONL producers: collect text from every parseable line that carries it.
+	if (command === "codex" || command === "opencode") {
+		const collected: string[] = [];
+		for (const line of trimmed.split("\n")) {
+			const payload = extractJsonlText(line.trim());
+			if (payload) collected.push(payload);
+		}
+		if (collected.length > 0) return collected.join("\n");
+		// Fall through to plain text if no JSONL payload was found — some codex
+		// builds print plain text despite the documented JSONL contract.
+	}
+
+	// Plain text: return as-is (already trimmed).
+	return trimmed;
+}
+
+/**
+ * Try to extract advisor text from one JSONL line. Returns undefined for lines
+ * that aren't JSON, or JSON without a recognizable text field.
+ */
+function extractJsonlText(line: string): string | undefined {
+	if (!line.startsWith("{")) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(line);
+	} catch {
+		return undefined; // junk preamble that happens to start with '{' — skip
+	}
+	if (!parsed || typeof parsed !== "object") return undefined;
+
+	// codex/opencode shape: { type: "item.completed", item: { text: "..." } }
+	const obj = parsed as Record<string, unknown>;
+	const item = obj.item;
+	if (item && typeof item === "object") {
+		const t = (item as Record<string, unknown>).text;
+		if (typeof t === "string" && t.trim()) return t;
+	}
+	// Generic shape: { text: "..." } at the top level.
+	if (typeof obj.text === "string" && obj.text.trim()) return obj.text;
+	// message.content array shape (some CLIs echo the prompt schema).
+	if (Array.isArray(obj.content)) {
+		const text = obj.content
+			.map((c) => (c && typeof c === "object" && typeof (c as Record<string, unknown>).text === "string" ? (c as Record<string, unknown>).text : null))
+			.filter((x): x is string => !!x)
+			.join("\n");
+		if (text.trim()) return text;
+	}
+	return undefined;
+}
+
+function truncate(s: string, max: number): string {
+	return s.length > max ? `${s.slice(0, max)}…` : s;
+}

package/src/config.ts

@@ -0,0 +1,422 @@
+/**
+ * config — persisted bpx-consult config.
+ *
+ * Lives at the pi-native path `~/.pi/agent/bpx-consult.json` (not rpiv's
+ * `~/.config` convention) because bpx-consult is a pi extension first and
+ * should sit alongside pi's own state. Reuses @juicesharp/rpiv-config for
+ * the crash-resistant load/save + TypeBox-driven validate primitives rather
+ * than hand-rolling JSON I/O.
+ *
+ * Schema mirrors SPEC §X. personas and backends are intentionally left open
+ * (additionalProperties) so user-defined persona names and CLI commands
+ * survive validation instead of being stripped by Value.Clean.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import { loadJsonConfig, saveJsonConfig, validateConfig } from "@juicesharp/rpiv-config";
+import { type Static, type TObject, Type } from "typebox";
+
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+
+const ThinkingLevelSchema = Type.Union(
+	[
+		Type.Literal("minimal"),
+		Type.Literal("low"),
+		Type.Literal("medium"),
+		Type.Literal("high"),
+		Type.Literal("xhigh"),
+	],
+	{ description: "Reasoning effort. Mirrors @earendil-works/pi-ai ThinkingLevel." },
+);
+
+const FeedbackModeSchema = Type.Union(
+	[Type.Literal("show"), Type.Literal("pipe"), Type.Literal("steer")],
+	{ description: "How the advisor's response reaches the executor." },
+);
+
+const ConsultModeSchema = Type.Union(
+	[Type.Literal("solo"), Type.Literal("council"), Type.Literal("debate"), Type.Literal("gut-check")],
+	{ description: "Consultation mode selected when consult() is called." },
+);
+
+/** A provider/model string plus an optional effort. Shared by every mode entry. */
+const ModelEntrySchema = Type.Object(
+	{
+		model: Type.Optional(Type.String({ description: 'provider/model key, e.g. "anthropic/claude-sonnet-4-6"' })),
+		thinkingLevel: Type.Optional(ThinkingLevelSchema),
+		feedbackMode: Type.Optional(FeedbackModeSchema),
+	},
+	{ additionalProperties: true },
+);
+
+// ---------------------------------------------------------------------------
+// Modes
+// ---------------------------------------------------------------------------
+
+const SoloModeSchema = Type.Object(
+	{
+		model: Type.Optional(Type.String()),
+		thinkingLevel: Type.Optional(ThinkingLevelSchema),
+		feedbackMode: Type.Optional(FeedbackModeSchema),
+		// terse is honored when gut-check merges its config into solo. Caps the
+		// response so gut-check returns a short read, not an essay.
+		terse: Type.Optional(Type.Boolean()),
+	},
+	{ additionalProperties: true },
+);
+
+const GutCheckModeSchema = Type.Object(
+	{
+		model: Type.Optional(Type.String()),
+		thinkingLevel: Type.Optional(ThinkingLevelSchema),
+		terse: Type.Optional(Type.Boolean()),
+		feedbackMode: Type.Optional(FeedbackModeSchema),
+	},
+	{ additionalProperties: true },
+);
+
+const CouncilModeSchema = Type.Object(
+	{
+		members: Type.Optional(Type.Array(Type.String())),
+		synthesizer: Type.Optional(ModelEntrySchema),
+		parallel: Type.Optional(Type.Boolean()),
+		timeoutMs: Type.Optional(Type.Integer({ minimum: 0, description: "Per-member wall-clock budget. 0 disables." })),
+		feedbackMode: Type.Optional(FeedbackModeSchema),
+	},
+	{ additionalProperties: true },
+);
+
+const DebateModeSchema = Type.Object(
+	{
+		advocate: Type.Optional(Type.String()),
+		critic: Type.Optional(Type.String()),
+		rounds: Type.Optional(Type.Integer({ minimum: 1, maximum: 4 })),
+		timeoutMs: Type.Optional(Type.Integer({ minimum: 0, description: "Wall-clock budget for the whole debate (all rounds + synth). 0 disables." })),
+		feedbackMode: Type.Optional(FeedbackModeSchema),
+	},
+	{ additionalProperties: true },
+);
+
+const ModesSchema = Type.Object(
+	{
+		solo: Type.Optional(SoloModeSchema),
+		gutCheck: Type.Optional(GutCheckModeSchema),
+		council: Type.Optional(CouncilModeSchema),
+		debate: Type.Optional(DebateModeSchema),
+	},
+	{ additionalProperties: true },
+);
+
+// ---------------------------------------------------------------------------
+// Personas / backends (open — user-defined names must survive cleaning)
+// ---------------------------------------------------------------------------
+
+const PersonaSchema = Type.Object(
+	{
+		name: Type.Optional(Type.String()),
+		systemPrompt: Type.Optional(Type.String()),
+		stance: Type.Optional(Type.Union([Type.Literal("for"), Type.Literal("against"), Type.Literal("neutral")])),
+		defaultModel: Type.Optional(Type.String()),
+		thinkingLevel: Type.Optional(ThinkingLevelSchema),
+	},
+	{ additionalProperties: true },
+);
+
+const BackendSchema = Type.Object(
+	{
+		type: Type.Optional(Type.Union([Type.Literal("inline"), Type.Literal("cli")])),
+		command: Type.Optional(Type.String()),
+		args: Type.Optional(Type.Array(Type.String())),
+		timeoutMs: Type.Optional(Type.Integer({ minimum: 0 })),
+	},
+	{ additionalProperties: true },
+);
+
+// ---------------------------------------------------------------------------
+// Triggers / context budget / disabled-for-models
+// ---------------------------------------------------------------------------
+
+const TriggersSchema = Type.Object(
+	{
+		onDone: Type.Optional(Type.Boolean()),
+		whenStuck: Type.Optional(Type.Integer({ minimum: 0 })),
+	},
+	{ additionalProperties: true },
+);
+
+const ContextBudgetSchema = Type.Object(
+	{
+		userChars: Type.Optional(Type.Integer({ minimum: 0 })),
+		assistantChars: Type.Optional(Type.Integer({ minimum: 0 })),
+		toolArgChars: Type.Optional(Type.Integer({ minimum: 0 })),
+		toolResultChars: Type.Optional(Type.Integer({ minimum: 0 })),
+		keepFirst: Type.Optional(Type.Integer({ minimum: 0 })),
+		keepLast: Type.Optional(Type.Integer({ minimum: 0 })),
+		responseReserveTokens: Type.Optional(Type.Integer({ minimum: 0 })),
+	},
+	{ additionalProperties: true },
+);
+
+const DisabledEntrySchema = Type.Union([
+	Type.String(),
+	Type.Object({ model: Type.String(), minEffort: Type.Optional(ThinkingLevelSchema) }, { additionalProperties: true }),
+]);
+
+// ---------------------------------------------------------------------------
+// Root schema
+// ---------------------------------------------------------------------------
+
+export const BpxConsultConfigSchema = Type.Object(
+	{
+		enabled: Type.Optional(Type.Boolean()),
+		defaultMode: Type.Optional(ConsultModeSchema),
+		modes: Type.Optional(ModesSchema),
+		personas: Type.Optional(Type.Record(Type.String(), PersonaSchema)),
+		backends: Type.Optional(Type.Record(Type.String(), BackendSchema)),
+		triggers: Type.Optional(TriggersSchema),
+		feedbackMode: Type.Optional(FeedbackModeSchema),
+		contextBudget: Type.Optional(ContextBudgetSchema),
+		disabledForModels: Type.Optional(Type.Array(DisabledEntrySchema)),
+	},
+	{ additionalProperties: true },
+);
+
+export type BpxConsultConfig = Static<typeof BpxConsultConfigSchema>;
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+/**
+ * Built-in defaults. validateConfig() merges Value.Create(schema) under the
+ * cleaned user value, so these are only used where the schema itself doesn't
+ * express a default. Anything that must be a specific value regardless of
+ * schema defaults lives here and is re-asserted after validation.
+ */
+export const DEFAULT_CONFIG: BpxConsultConfig = {
+	enabled: true,
+	defaultMode: "solo",
+	modes: {
+		solo: { model: "anthropic/claude-sonnet-4-6", thinkingLevel: "high" },
+		gutCheck: { model: "google/gemini-2.5-flash", thinkingLevel: "low", terse: true },
+		council: {
+			members: ["architect", "critic", "simplifier"],
+			synthesizer: { model: "anthropic/claude-sonnet-4-6", thinkingLevel: "high" },
+			parallel: true,
+			timeoutMs: 120000,
+		},
+		debate: { advocate: "architect", critic: "critic", rounds: 2, timeoutMs: 180000 },
+	},
+	// Per-persona default models. CRITICAL: members must NOT all share one model/tier,
+	// and should avoid sharing the executor's model — parallel calls to the same
+	// free-tier provider trip QPM rate limits and silently kill members (caught
+	// in live testing). Default roster spreads across Anthropic tiers so the
+	// out-of-box council survives a parallel fan-out. Users with only one
+	// provider authed should override this to that provider's distinct tiers.
+	personas: {
+		architect: { defaultModel: "anthropic/claude-opus-4-6", thinkingLevel: "high" },  // strong, for the design-for seat
+		critic: { defaultModel: "anthropic/claude-sonnet-4-6", thinkingLevel: "high" },    // different tier, forces genuine critique
+		simplifier: { defaultModel: "anthropic/claude-haiku-4-5", thinkingLevel: "medium" }, // cheap+fast, questions complexity
+	},
+	triggers: { onDone: false, whenStuck: 3 },
+	feedbackMode: "steer",
+	contextBudget: {
+		userChars: 2800,
+		assistantChars: 1800,
+		toolArgChars: 800,
+		toolResultChars: 2000,
+		keepFirst: 2,
+		keepLast: 12,
+		responseReserveTokens: 4096,
+	},
+	disabledForModels: [],
+};
+
+// ---------------------------------------------------------------------------
+// Path
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the config path under pi's agent directory.
+ *
+ * We do NOT use rpiv-config.configPath() — that resolves under ~/.config,
+ * the rpiv family convention. bpx-consult lives in the pi ecosystem, so its
+ * state sits alongside pi's own (~/.pi/agent/) per SPEC §X. PI_CODING_AGENT_DIR
+ * is honoured if set, matching pi's own resolution (usage.md:293).
+ */
+export function bpxConfigPath(): string {
+	const base = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+	return join(base, "bpx-consult.json");
+}
+
+/**
+ * Project-local config path: `<cwd>/.pi/bpx-consult.json`.
+ *
+ * SPEC §X precedence is env > project (.pi, trusted) > global > defaults.
+ * Project-local is only honoured when the project is trusted (pi's trust model
+ * — an untrusted repo must not be able to silently reconfigure the advisor).
+ * The caller passes trust state from ctx.isProjectTrusted().
+ */
+export function projectConfigPath(cwd: string): string {
+	return join(cwd, ".pi", "bpx-consult.json");
+}
+
+// ---------------------------------------------------------------------------
+// Load / save
+// ---------------------------------------------------------------------------
+
+/** Options for loadConfig. Project-local config is only read when trusted. */
+export interface LoadConfigOptions {
+	/** Current working directory (for project-local config discovery). */
+	cwd?: string;
+	/** Whether the project is trusted (ctx.isProjectTrusted()). Defaults true. */
+	projectTrusted?: boolean;
+}
+
+/**
+ * Load, clean, and validate the config against the schema.
+ *
+ * Precedence (SPEC §X): project (.pi, trusted) > global > defaults. Project
+ * config is deep-merged ON TOP of global, so a project can override e.g.
+ * personas.solo.model without re-stating the whole file. Both layers pass
+ * through validateConfig independently so a malformed project config can't
+ * corrupt a valid global one — the bad layer just collapses to {}.
+ *
+ * Fail-soft: missing files, malformed JSON, or validation failures all collapse
+ * to defaults rather than throwing — an unreadable config must never break the
+ * extension at startup.
+ */
+export function loadConfig(options: LoadConfigOptions = {}): BpxConsultConfig {
+	const globalRaw = loadJsonConfig<unknown>(bpxConfigPath());
+	let mergedRaw = globalRaw;
+
+	const trusted = options.projectTrusted ?? true;
+	if (trusted && options.cwd) {
+		const pPath = projectConfigPath(options.cwd);
+		const projectRaw = loadJsonConfig<unknown>(pPath);
+		mergedRaw = deepMerge(globalRaw, projectRaw);
+	}
+
+	const validated = validateConfig(BpxConsultConfigSchema as TObject, mergedRaw);
+	return mergeDefaults(validated);
+}
+
+/**
+ * Shallow-per-section deep merge for config objects. Project wins at the leaf;
+ * arrays replace (not concat) — council.members in project replaces global's.
+ * Unknown top-level keys are ignored (validateConfig strips them anyway).
+ */
+function deepMerge(global: unknown, project: unknown): unknown {
+	if (!isObject(global)) return isObject(project) ? project : {};
+	if (!isObject(project)) return global;
+	const out: Record<string, unknown> = { ...global };
+	for (const [k, pv] of Object.entries(project as Record<string, unknown>)) {
+		const gv = (global as Record<string, unknown>)[k];
+		if (isObject(gv) && isObject(pv)) {
+			out[k] = deepMerge(gv, pv);
+		} else {
+			out[k] = pv;
+		}
+	}
+	return out;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+	return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/** Persist config. Returns true on successful write (see saveJsonConfig contract). */
+export function saveConfig(config: BpxConsultConfig): boolean {
+	return saveJsonConfig(bpxConfigPath(), config);
+}
+
+/**
+ * Deep-merge user config over built-in defaults, section by section.
+ *
+ * User values win at the leaf level; missing leaves fall back to DEFAULT_CONFIG.
+ * This is deliberately not a generic deep-merge — the shape is fixed and small,
+ * so an explicit per-section spread is easier to reason about than a recursive
+ * helper that has to special-case arrays (council.members must replace, not
+ * concat) and open records (personas/backends).
+ */
+function mergeDefaults(user: BpxConsultConfig): BpxConsultConfig {
+	return {
+		enabled: user.enabled ?? DEFAULT_CONFIG.enabled,
+		defaultMode: user.defaultMode ?? DEFAULT_CONFIG.defaultMode,
+		modes: {
+			solo: { ...DEFAULT_CONFIG.modes?.solo, ...user.modes?.solo },
+			gutCheck: { ...DEFAULT_CONFIG.modes?.gutCheck, ...user.modes?.gutCheck },
+			council: { ...DEFAULT_CONFIG.modes?.council, ...user.modes?.council },
+			debate: { ...DEFAULT_CONFIG.modes?.debate, ...user.modes?.debate },
+		},
+		personas: user.personas ?? {},
+		backends: user.backends ?? {},
+		triggers: { ...DEFAULT_CONFIG.triggers, ...user.triggers },
+		feedbackMode: user.feedbackMode ?? DEFAULT_CONFIG.feedbackMode,
+		contextBudget: { ...DEFAULT_CONFIG.contextBudget, ...user.contextBudget },
+		disabledForModels: user.disabledForModels ?? DEFAULT_CONFIG.disabledForModels,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Disabled-for-models — policy helper (mirrors rpiv-advisor's shape)
+// ---------------------------------------------------------------------------
+
+export type DisabledForModelsEntry = string | { model: string; minEffort?: ThinkingLevel };
+
+const EFFORT_ORDINAL: readonly ThinkingLevel[] = ["minimal", "low", "medium", "high", "xhigh"];
+
+/**
+ * Should consult be suppressed for this executor model?
+ *
+ * - A bare string entry disables unconditionally.
+ * - An object entry disables only below its minEffort (so a user can say
+ *   "don't bother consulting when I'm already on opus at high").
+ */
+/**
+ * Resolve a backend for a model key. Looks up `config.backends[modelKey]`;
+ * returns undefined (→ inline default) when no CLI override is configured.
+ *
+ * The backend map is keyed by the same provider/model string used everywhere
+ * else, so a user can say "route codex/codex to the codex CLI" without touching
+ * the rest of the config. A backend entry with no `type` defaults to inline.
+ */
+export function resolveBackend(config: BpxConsultConfig, modelKey: string | undefined): { type: "cli"; command: string; args?: string[]; timeoutMs?: number } | { type: "inline" } | undefined {
+	if (!modelKey) return undefined;
+	const entry = config.backends?.[modelKey];
+	if (!entry) return undefined;
+	if (entry.type === "cli") {
+		return {
+			type: "cli",
+			command: typeof entry.command === "string" ? entry.command : "codex",
+			args: Array.isArray(entry.args) ? entry.args : undefined,
+			timeoutMs: typeof entry.timeoutMs === "number" ? entry.timeoutMs : undefined,
+		};
+	}
+	return { type: "inline" };
+}
+
+export function isDisabledForModel(
+	entries: DisabledForModelsEntry[] | undefined,
+	executorModelLabel: string,
+	thinkingLevel: ThinkingLevel | undefined,
+): boolean {
+	if (!entries || entries.length === 0) return false;
+	const executorOrdinal = thinkingLevel ? EFFORT_ORDINAL.indexOf(thinkingLevel) : -1;
+	for (const entry of entries) {
+		if (typeof entry === "string") {
+			if (entry === executorModelLabel) return true;
+			continue;
+		}
+		if (entry.model !== executorModelLabel) continue;
+		if (entry.minEffort === undefined) return true;
+		const threshold = EFFORT_ORDINAL.indexOf(entry.minEffort);
+		if (threshold === -1) return true; // unknown effort → treat as unconditional
+		if (executorOrdinal !== -1 && executorOrdinal < threshold) return true;
+	}
+	return false;
+}