@oh-my-pi/pi-coding-agent 15.10.11 → 15.10.12

package/src/config/settings.ts

@@ -64,6 +64,8 @@ export interface SettingsOptions {
 	inMemory?: boolean;
 	/** Initial overrides */
 	overrides?: Partial<Record<SettingPath, unknown>>;
+	/** Extra config.yml-style overlays loaded after global/project settings */
+	configFiles?: string[];
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -116,10 +118,12 @@ type PathScopedStringArrayEntry = {
 	providers?: unknown;
 };
 
+function expandTilde(p: string): string {
+	return p === "~" ? os.homedir() : p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
+}
+
 function normalizePathPrefix(prefix: string): string {
-	const expanded =
-		prefix === "~" ? os.homedir() : prefix.startsWith("~/") ? path.join(os.homedir(), prefix.slice(2)) : prefix;
-	return path.resolve(expanded);
+	return path.resolve(expandTilde(prefix));
 }
 
 function pathMatchesPrefix(cwd: string, prefix: string): boolean {
@@ -193,10 +197,13 @@ export class Settings {
 	#agentDir: string;
 	#storage: AgentStorage | null = null;
 
+	#configFiles: string[] = [];
 	/** Global settings from config.yml */
 	#global: RawSettings = {};
 	/** Project settings from .claude/settings.yml etc */
 	#project: RawSettings = {};
+	/** Extra config.yml-style overlays passed by CLI */
+	#configOverlay: RawSettings = {};
 	/** Runtime overrides (not persisted) */
 	#overrides: RawSettings = {};
 	/** Merged view (global + project + overrides) */
@@ -221,6 +228,7 @@ export class Settings {
 		this.#cwd = path.normalize(options.cwd ?? getProjectDir());
 		this.#agentDir = path.normalize(options.agentDir ?? getAgentDir());
 		this.#configPath = options.inMemory ? null : path.join(this.#agentDir, "config.yml");
+		this.#configFiles = options.configFiles?.map(file => path.resolve(this.#cwd, expandTilde(file))) ?? [];
 		this.#persist = !options.inMemory;
 
 		if (options.overrides) {
@@ -256,6 +264,7 @@ export class Settings {
 			},
 			error => {
 				globalInstance = null;
+				globalInstancePromise = null;
 				clearBoundSettingsMethods();
 				throw error;
 			},
@@ -303,6 +312,14 @@ export class Settings {
 		return resolved as SettingValue<P>;
 	}
 
+	/**
+	 * Whether `path` has an explicitly configured value (global config, project
+	 * config, or runtime override) rather than falling back to the schema default.
+	 */
+	isConfigured(path: SettingPath): boolean {
+		return getByPath(this.#merged, SETTING_PATH_SEGMENTS[path]) !== undefined;
+	}
+
 	/**
 	 * Set a setting value (sync).
 	 * Updates global settings and queues a background save.
@@ -386,6 +403,8 @@ export class Settings {
 		cloned.#storage = this.#storage;
 		cloned.#global = structuredClone(this.#global);
 		cloned.#project = this.#persist ? await cloned.#loadProjectSettings() : structuredClone(this.#project);
+		cloned.#configFiles = [...this.#configFiles];
+		cloned.#configOverlay = structuredClone(this.#configOverlay);
 		cloned.#overrides = structuredClone(this.#overrides);
 		cloned.#rebuildMerged();
 		cloned.#fireAllHooks();
@@ -557,6 +576,7 @@ export class Settings {
 		}
 
 		this.#project = await projectPromise;
+		this.#configOverlay = await this.#loadConfigOverlays();
 
 		// Build merged view (global → project → overrides; project wins over global)
 		this.#rebuildMerged();
@@ -594,6 +614,43 @@ export class Settings {
 		}
 	}
 
+	async #loadConfigOverlays(): Promise<RawSettings> {
+		let merged: RawSettings = {};
+		for (const filePath of this.#configFiles) {
+			merged = this.#deepMerge(merged, await this.#loadOverlayYaml(filePath));
+		}
+		return merged;
+	}
+
+	/**
+	 * Strict loader for explicit `--config` overlays: unlike `#loadYaml`,
+	 * missing or malformed files are hard errors so a typo'd path cannot
+	 * silently fall back to the persistent settings.
+	 */
+	async #loadOverlayYaml(filePath: string): Promise<RawSettings> {
+		let content: string;
+		try {
+			content = await Bun.file(filePath).text();
+		} catch (error) {
+			throw new Error(
+				isEnoent(error)
+					? `Config overlay not found: ${filePath}`
+					: `Failed to read config overlay ${filePath}: ${String(error)}`,
+			);
+		}
+		let parsed: unknown;
+		try {
+			parsed = YAML.parse(content);
+		} catch (error) {
+			throw new Error(`Failed to parse config overlay ${filePath}: ${String(error)}`);
+		}
+		if (parsed === null || parsed === undefined) return {};
+		if (typeof parsed !== "object" || Array.isArray(parsed)) {
+			throw new Error(`Config overlay must be a YAML mapping: ${filePath}`);
+		}
+		return this.#migrateRawSettings(parsed as RawSettings);
+	}
+
 	async #migrateFromLegacy(): Promise<void> {
 		if (!this.#configPath) return;
 
@@ -898,6 +955,7 @@ export class Settings {
 
 	#rebuildMerged(): void {
 		this.#merged = this.#deepMerge(this.#deepMerge({}, this.#global), this.#project);
+		this.#merged = this.#deepMerge(this.#merged, this.#configOverlay);
 		this.#merged = this.#deepMerge(this.#merged, this.#overrides);
 		this.#resolvedCache.clear();
 	}

package/src/edit/hashline/execute.ts

@@ -23,11 +23,13 @@ import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import type { FileDiagnosticsResult, WritethroughCallback, WritethroughDeferredHandle } from "../../lsp";
 import type { ToolSession } from "../../tools";
 import { outputMeta } from "../../tools/output-meta";
+import { ToolError } from "../../tools/tool-errors";
 import { generateDiffString } from "../diff";
 import { getFileSnapshotStore } from "../file-snapshot-store";
 import type { EditToolDetails, EditToolPerFileResult, LspBatchRequest } from "../renderer";
 import { nativeBlockResolver } from "./block-resolver";
 import { HashlineFilesystem } from "./filesystem";
+import { hashPatchInput, NOOP_HARD_LIMIT, recordNoopEdit, resetNoopEdit } from "./noop-loop-guard";
 import { type HashlineParams, hashlineEditParamsSchema } from "./params";
 
 export interface ExecuteHashlineSingleOptions {
@@ -54,6 +56,24 @@ function noChangeDiagnostic(path: string): string {
 	);
 }
 
+/**
+ * Escalated diagnostic surfaced once the same payload has no-op'd
+ * {@link NOOP_HARD_LIMIT} times in a row on the same canonical path. Thrown as
+ * a {@link ToolError} so the agent loop sees a tool *failure* — empirically
+ * far more effective at breaking a no-op edit loop than the soft hint alone
+ * (issue #2081 saw 182 byte-identical no-op results in 205 calls before the
+ * user aborted).
+ */
+function noChangeLoopDiagnostic(path: string, count: number): string {
+	return (
+		`STOP. Edits to ${path} have been a byte-identical no-op ${count} times in a row — ` +
+		`the patch body matches the file at the targeted lines and the soft hint did not break the cycle. ` +
+		`Cease re-issuing this payload. Either the intended change is already on disk (move on), ` +
+		`or your anchor is wrong (re-read the file with \`read\` to observe the current line numbers and ` +
+		`tag, then author a different edit). This exact payload will keep being rejected until it changes.`
+	);
+}
+
 function assertUniqueCanonicalPaths(prepared: readonly PreparedSection[]): void {
 	const seen = new Map<string, string>();
 	for (const entry of prepared) {
@@ -156,13 +176,19 @@ export async function executeHashlineSingle(
 	const patcher = new Patcher({ fs, snapshots, blockResolver: nativeBlockResolver });
 
 	// Single-section fast path: prepare, commit, render.
+	const inputHash = hashPatchInput(options.input);
 	if (patch.sections.length === 1) {
 		fs.setBatchRequest(narrowBatchRequest(options.batchRequest, true));
 		const prepared = await patcher.prepare(patch.sections[0]);
 		const sectionResult = await patcher.commit(prepared);
 		if (sectionResult.op === "noop") {
+			const { count, escalate } = recordNoopEdit(options.session, sectionResult.canonicalPath, inputHash);
+			if (escalate) {
+				throw new ToolError(noChangeLoopDiagnostic(sectionResult.path, count));
+			}
 			return renderSection(sectionResult, undefined).toolResult;
 		}
+		resetNoopEdit(options.session, sectionResult.canonicalPath);
 		return renderSection(sectionResult, fs.consumeDiagnostics(sectionResult.path)).toolResult;
 	}
 
@@ -172,7 +198,12 @@ export async function executeHashlineSingle(
 	for (const section of patch.sections) prepared.push(await patcher.prepare(section));
 	assertUniqueCanonicalPaths(prepared);
 	for (const entry of prepared) {
-		if (entry.isNoop) throw new Error(noChangeDiagnostic(entry.section.path));
+		if (entry.isNoop) {
+			const { count, escalate } = recordNoopEdit(options.session, entry.canonicalPath, inputHash);
+			throw escalate
+				? new ToolError(noChangeLoopDiagnostic(entry.section.path, count))
+				: new ToolError(noChangeDiagnostic(entry.section.path));
+		}
 	}
 	// Then commit each one, narrowing the LSP batch flush flag to the final
 	// section only. A no-op apply mid-batch is treated as a hard failure —
@@ -182,7 +213,13 @@ export async function executeHashlineSingle(
 		const isLast = i === prepared.length - 1;
 		fs.setBatchRequest(narrowBatchRequest(options.batchRequest, isLast));
 		const sectionResult = await patcher.commit(prepared[i]);
-		if (sectionResult.op === "noop") throw new Error(noChangeDiagnostic(sectionResult.path));
+		if (sectionResult.op === "noop") {
+			const { count, escalate } = recordNoopEdit(options.session, sectionResult.canonicalPath, inputHash);
+			throw escalate
+				? new ToolError(noChangeLoopDiagnostic(sectionResult.path, count))
+				: new ToolError(noChangeDiagnostic(sectionResult.path));
+		}
+		resetNoopEdit(options.session, sectionResult.canonicalPath);
 		rendered.push(renderSection(sectionResult, fs.consumeDiagnostics(sectionResult.path)));
 	}
 

package/src/edit/hashline/noop-loop-guard.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-session guard against subagents looping on byte-identical no-op edits.
+ *
+ * A hashline patch can apply cleanly yet produce no change when the body rows
+ * are already byte-identical to the targeted lines. {@link executeHashlineSingle}
+ * surfaces a soft hint ("re-read the file before issuing another edit"), but in
+ * the wild some models ignore the hint and keep re-issuing the same bytes
+ * (issue #2081 captured 182 such repeats in 205 calls before the user aborted).
+ *
+ * This module tracks consecutive byte-identical no-op edits per canonical file
+ * path within a single session. Once the same payload no-ops {@link NOOP_HARD_LIMIT}
+ * times in a row the caller is expected to escalate from a soft text result to
+ * a thrown {@link ToolError} so the agent loop sees a tool *failure* — empirically
+ * far more effective at breaking the cycle than the soft hint alone.
+ *
+ * A successful (non-noop) commit for a path resets that path's counter; a
+ * different payload on the same path also resets it because the body hash
+ * changed, which is a sign of model progress and deserves another soft hint.
+ */
+
+interface NoopLoopEntry {
+	/** Hash of the most recent input that no-op'd on this canonical path. */
+	hash: string;
+	/** Consecutive no-op count for the same `hash` on this path. */
+	count: number;
+}
+
+/** Cross-session-safe state slot held on the `ToolSession`. */
+export interface NoopLoopGuard {
+	entries: Map<string, NoopLoopEntry>;
+}
+
+/**
+ * After this many consecutive byte-identical no-op edits on the same path,
+ * {@link recordNoopEdit} returns `escalate: true`. Picked deliberately small
+ * so the soft hint still fires once or twice before we escalate — the model
+ * deserves a chance to recover, but a tight bound is what actually breaks
+ * loops in practice.
+ */
+export const NOOP_HARD_LIMIT = 3;
+
+interface NoopLoopGuardOwner {
+	noopLoopGuard?: NoopLoopGuard;
+}
+
+/** Lazily create the per-session guard, mirroring `getFileSnapshotStore`. */
+export function getNoopLoopGuard(session: NoopLoopGuardOwner): NoopLoopGuard {
+	if (!session.noopLoopGuard) session.noopLoopGuard = { entries: new Map() };
+	return session.noopLoopGuard;
+}
+
+/** Result of recording one no-op against the guard. */
+export interface NoopRecordResult {
+	/** Consecutive identical no-op count, including the current one. */
+	count: number;
+	/** True once `count >= NOOP_HARD_LIMIT` and the caller MUST escalate. */
+	escalate: boolean;
+}
+
+/**
+ * Record a no-op edit for `canonicalPath` keyed by `inputHash` (a stable hash
+ * of the raw patch input bytes). Returns the running consecutive-no-op count
+ * and whether the caller should escalate from a soft text result to a thrown
+ * error.
+ *
+ * `inputHash` is intentionally derived from the raw model-authored bytes
+ * rather than from file content: when the model emits a different payload
+ * (even whitespace-only) that's progress and earns a fresh soft hint, but
+ * re-issuing the same bytes after being warned is what we want to break.
+ */
+export function recordNoopEdit(
+	session: NoopLoopGuardOwner,
+	canonicalPath: string,
+	inputHash: string,
+): NoopRecordResult {
+	const guard = getNoopLoopGuard(session);
+	const prev = guard.entries.get(canonicalPath);
+	const count = prev && prev.hash === inputHash ? prev.count + 1 : 1;
+	guard.entries.set(canonicalPath, { hash: inputHash, count });
+	return { count, escalate: count >= NOOP_HARD_LIMIT };
+}
+
+/**
+ * Clear the no-op counter for `canonicalPath`. Call after a non-noop commit
+ * for the same path so a future no-op starts fresh from the soft hint.
+ */
+export function resetNoopEdit(session: NoopLoopGuardOwner, canonicalPath: string): void {
+	const guard = session.noopLoopGuard;
+	if (!guard) return;
+	guard.entries.delete(canonicalPath);
+}
+
+/**
+ * Stable hash of the raw patch input. Bun's `Bun.hash` is xxHash64 — fast,
+ * non-cryptographic, more than adequate for "is this the same payload?".
+ */
+export function hashPatchInput(input: string): string {
+	return Bun.hash(input).toString(16);
+}

package/src/eval/completion-bridge.ts

@@ -163,6 +163,7 @@ export async function runEvalCompletion(
 				apiKey: registry.resolver(model.provider, {
 					sessionId: options.session.getSessionId?.() ?? undefined,
 					baseUrl: model.baseUrl,
+					modelId: model.id,
 				}),
 				signal: options.signal,
 				reasoning: reasoningForTier(tier, model),

package/src/eval/py/executor.ts

@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
 
 import { getProjectDir, logger } from "@oh-my-pi/pi-utils";
@@ -15,6 +16,7 @@ import {
 	type KernelRuntimeEnv,
 	PythonKernel,
 } from "./kernel";
+import { resolveExplicitPythonRuntime } from "./runtime";
 import { ensurePyToolBridge, registerPyToolBridge } from "./tool-bridge";
 
 export type PythonKernelMode = "session" | "per-call";
@@ -42,6 +44,11 @@ export interface PythonExecutorOptions {
 	kernelOwnerId?: string;
 	/** Kernel mode (session reuse vs per-call) */
 	kernelMode?: PythonKernelMode;
+	/**
+	 * Explicit interpreter path (`python.interpreter` resolved from the
+	 * session's settings). Skips automatic runtime discovery when set.
+	 */
+	interpreter?: string;
 	/** Restart the kernel before executing */
 	reset?: boolean;
 	/** Session file path for accessing task outputs */
@@ -116,9 +123,9 @@ export interface PythonResult {
 // ---------------------------------------------------------------------------
 // Session bookkeeping
 //
-// One PythonKernel subprocess per (session id, cwd) tuple. The runner mutates
-// process-global cwd/sys.path during execution, so cross-directory work MUST
-// never share a live kernel. Multiple agent owners can still register against
+// One PythonKernel subprocess per (session id, cwd, interpreter) tuple. The
+// runner mutates process-global cwd/sys.path during execution, so cross-directory
+// work must never share a live kernel. Multiple agent owners can still register against
 // the same tuple; the kernel stays alive until the last owner detaches.
 // ---------------------------------------------------------------------------
 
@@ -139,8 +146,19 @@ function normalizeSessionCwd(cwd: string): string {
 	return path.resolve(cwd);
 }
 
-function buildSessionKey(sessionId: string, cwd: string): string {
-	return `${sessionId}\0${normalizeSessionCwd(cwd)}`;
+function normalizeExplicitInterpreter(cwd: string, interpreter: string | undefined): string {
+	if (interpreter === undefined) return "";
+	const resolved = resolveExplicitPythonRuntime(interpreter, cwd, {}).pythonPath;
+	try {
+		return fs.realpathSync.native(resolved);
+	} catch {
+		return resolved;
+	}
+}
+
+function buildSessionKey(sessionId: string, cwd: string, interpreter: string | undefined): string {
+	const normalizedCwd = normalizeSessionCwd(cwd);
+	return `${sessionId}\0${normalizedCwd}\0${normalizeExplicitInterpreter(normalizedCwd, interpreter)}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -326,6 +344,7 @@ async function startKernel(cwd: string, options: PythonExecutorOptions): Promise
 		env: buildKernelEnv(options),
 		signal: options.signal,
 		deadlineMs: options.deadlineMs,
+		interpreter: options.interpreter,
 	});
 }
 
@@ -587,7 +606,10 @@ async function executeWithKernel(
 }
 
 async function ensureKernelAvailable(cwd: string, options: PythonExecutorOptions): Promise<void> {
-	const availability = await waitForPromiseWithCancellation(checkPythonKernelAvailability(cwd), options);
+	const availability = await waitForPromiseWithCancellation(
+		checkPythonKernelAvailability(cwd, options.interpreter),
+		options,
+	);
 	if (!availability.ok) {
 		throw new Error(availability.reason ?? "Python kernel unavailable");
 	}
@@ -618,7 +640,7 @@ async function executePerCall(code: string, cwd: string, options: PythonExecutor
 
 async function executeOnSession(code: string, cwd: string, options: PythonExecutorOptions): Promise<PythonResult> {
 	const sessionId = options.sessionId ?? `session:${cwd}`;
-	const sessionKey = buildSessionKey(sessionId, cwd);
+	const sessionKey = buildSessionKey(sessionId, cwd, options.interpreter);
 	if (options.bridge && !options.bridgeSessionId) {
 		options.bridgeSessionId = sessionId;
 	}

package/src/eval/py/index.ts

@@ -19,13 +19,17 @@ function readSetting<T>(session: ToolSession, key: string): T | undefined {
 	return settings?.get?.(key);
 }
 
+function readInterpreterSetting(session: ToolSession): string | undefined {
+	return readSetting<string>(session, "python.interpreter")?.trim() || undefined;
+}
+
 export default {
 	id: "python",
 	label: "Python",
 	highlightLang: "python",
 
 	async isAvailable(session: ToolSession): Promise<boolean> {
-		const availability = await checkPythonKernelAvailability(session.cwd);
+		const availability = await checkPythonKernelAvailability(session.cwd, readInterpreterSetting(session));
 		return availability.ok;
 	},
 
@@ -37,6 +41,7 @@ export default {
 			signal: opts.signal,
 			sessionId: namespaceSessionId(opts.sessionId),
 			kernelMode,
+			interpreter: readInterpreterSetting(opts.session),
 			sessionFile: opts.sessionFile,
 			artifactsDir: opts.session.getArtifactsDir?.() ?? undefined,
 			localRoots: resolveEvalUrlRoots(opts.session),

package/src/eval/py/kernel.ts

@@ -17,7 +17,13 @@ import { Settings } from "../../config/settings";
 import { type KernelDisplayOutput, renderKernelDisplay } from "./display";
 import { PYTHON_PRELUDE } from "./prelude";
 import RUNNER_SCRIPT from "./runner.py" with { type: "text" };
-import { enumeratePythonRuntimes, filterEnv, type PythonRuntime, resolvePythonRuntime } from "./runtime";
+import {
+	enumeratePythonRuntimes,
+	filterEnv,
+	type PythonRuntime,
+	resolveExplicitPythonRuntime,
+	resolvePythonRuntime,
+} from "./runtime";
 import { hostHasInheritableConsole, shouldHideKernelWindow } from "./spawn-options";
 
 export type { KernelDisplayOutput, PythonStatusEvent } from "./display";
@@ -96,6 +102,11 @@ interface KernelLifecycleOptions {
 interface KernelStartOptions extends KernelLifecycleOptions {
 	cwd: string;
 	env?: Record<string, string | undefined>;
+	/**
+	 * Explicit interpreter path (`python.interpreter` from the session's
+	 * settings). When set, runtime discovery is skipped entirely.
+	 */
+	interpreter?: string;
 }
 
 interface KernelShutdownOptions {
@@ -129,20 +140,24 @@ function throwIfAborted(signal: AbortSignal | undefined, fallbackReason: string)
 	throw createAbortError("AbortError", typeof reason === "string" ? reason : fallbackReason);
 }
 
-// Cache successful probes per resolved cwd: every cell otherwise pays one (or
-// two — backend.isAvailable + ensureKernelAvailable) interpreter spawns even
-// when the kernel is already hot. Failures are not cached so installing a
-// Python mid-session is picked up on the next attempt.
+// Cache successful probes per resolved cwd + explicit interpreter: every cell
+// otherwise pays one (or two — backend.isAvailable + ensureKernelAvailable)
+// interpreter spawns even when the kernel is already hot. Failures are not
+// cached so installing a Python mid-session is picked up on the next attempt.
 const availabilityCache = new Map<string, Promise<PythonKernelAvailability>>();
 
-export async function checkPythonKernelAvailability(cwd: string): Promise<PythonKernelAvailability> {
+export async function checkPythonKernelAvailability(
+	cwd: string,
+	interpreter?: string,
+): Promise<PythonKernelAvailability> {
 	if (isBunTestRuntime() || $flag("PI_PYTHON_SKIP_CHECK")) {
 		return { ok: true };
 	}
-	const key = path.resolve(cwd);
+	const resolvedCwd = path.resolve(cwd);
+	const key = `${resolvedCwd}\0${interpreter ?? ""}`;
 	const cached = availabilityCache.get(key);
 	if (cached) return await cached;
-	const probe = probePythonKernelAvailability(key);
+	const probe = probePythonKernelAvailability(resolvedCwd, interpreter);
 	availabilityCache.set(key, probe);
 	const result = await probe;
 	if (!result.ok && availabilityCache.get(key) === probe) {
@@ -151,12 +166,14 @@ export async function checkPythonKernelAvailability(cwd: string): Promise<Python
 	return result;
 }
 
-async function probePythonKernelAvailability(cwd: string): Promise<PythonKernelAvailability> {
+async function probePythonKernelAvailability(cwd: string, interpreter?: string): Promise<PythonKernelAvailability> {
 	try {
 		const settings = await Settings.init();
 		const { env } = settings.getShellConfig();
 		const baseEnv = filterEnv(env);
-		const runtimes = enumeratePythonRuntimes(cwd, baseEnv);
+		const runtimes = interpreter
+			? [resolveExplicitPythonRuntime(interpreter, cwd, baseEnv)]
+			: enumeratePythonRuntimes(cwd, baseEnv);
 		if (runtimes.length === 0) {
 			return { ok: false, reason: "Python executable not found on PATH" };
 		}
@@ -239,6 +256,7 @@ export class PythonKernel {
 			"PythonKernel.start:availabilityCheck",
 			checkPythonKernelAvailability,
 			options.cwd,
+			options.interpreter,
 		);
 		if (!availability.ok) {
 			throw new Error(availability.reason ?? "Python kernel unavailable");
@@ -251,7 +269,9 @@ export class PythonKernel {
 		let runtime = availability.runtime;
 		if (!runtime) {
 			const { env: shellEnv } = (await Settings.init()).getShellConfig();
-			runtime = resolvePythonRuntime(options.cwd, filterEnv(shellEnv));
+			runtime = options.interpreter
+				? resolveExplicitPythonRuntime(options.interpreter, options.cwd, filterEnv(shellEnv))
+				: resolvePythonRuntime(options.cwd, filterEnv(shellEnv));
 		}
 		const spawnEnv: Record<string, string> = {};
 		for (const [key, value] of Object.entries(runtime.env)) {

package/src/eval/py/runtime.ts

@@ -5,6 +5,7 @@
  * for both the shared gateway and local kernel spawning.
  */
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { $env, $which, getPythonEnvDir } from "@oh-my-pi/pi-utils";
 
@@ -182,6 +183,42 @@ function venvBinDir(venvPath: string): string {
 	return process.platform === "win32" ? path.join(venvPath, "Scripts") : path.join(venvPath, "bin");
 }
 
+function detectExplicitVenv(pythonPath: string): { venvPath: string; binDir: string } | undefined {
+	const binDir = path.dirname(pythonPath);
+	const venvPath = path.dirname(binDir);
+	if (fs.existsSync(path.join(venvPath, "pyvenv.cfg"))) {
+		return { venvPath, binDir };
+	}
+	return undefined;
+}
+
+/**
+ * Resolve an explicitly configured interpreter (`python.interpreter`) into a
+ * runtime, bypassing discovery. Does not probe or validate the executable —
+ * callers must check it actually runs. `~` expands to the home directory and
+ * relative paths resolve against `cwd`. When the interpreter sits inside a
+ * virtualenv (a `pyvenv.cfg` above its bin dir), the venv activation env is
+ * applied so subprocesses and `pip` resolve consistently.
+ */
+export function resolveExplicitPythonRuntime(
+	interpreter: string,
+	cwd: string,
+	baseEnv: Record<string, string | undefined>,
+): PythonRuntime {
+	const expanded =
+		interpreter === "~"
+			? os.homedir()
+			: interpreter.startsWith("~/")
+				? path.join(os.homedir(), interpreter.slice(2))
+				: interpreter;
+	const pythonPath = path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
+	const venv = detectExplicitVenv(pythonPath);
+	if (venv) {
+		return { pythonPath, env: applyVenvEnv(baseEnv, venv.venvPath, venv.binDir), venvPath: venv.venvPath };
+	}
+	return { pythonPath, env: { ...baseEnv } };
+}
+
 /**
  * Enumerate candidate Python runtimes in priority order: an active/project venv,
  * the managed `~/.omp/python-env`, then the system interpreter on PATH. Every