@oh-my-pi/pi-coding-agent 14.0.3 → 14.0.5

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 ## [Unreleased]
 
+## [14.0.5] - 2026-04-11
+### Added
+
+- Added `designer` model role for UI/UX design tasks with Gemini 3.1 Pro as default model
+- Added support for model role fallback lists — roles can now resolve to multiple model patterns with automatic fallback to next available model
+- Added `extractReadableFromHtml` utility function to extract readable content from HTML with Readability article extraction and CSS selector fallback
+- Added support for GFM (GitHub Flavored Markdown) features including tables, strikethrough, and task lists in HTML-to-markdown conversion
+- Added `resolveDiagnosticTargets` utility function to handle glob pattern resolution with fallback to literal file paths for bracket-style paths
+
+### Changed
+
+- Clarified fenced code block editing behavior in markdown — the tool now preserves literal indentation inside fenced blocks, with content written verbatim as supplied
+- Updated guidance for inserting content after markdown section headings to use `after` on the heading chunk rather than `before`/`prepend` on the section itself
+- Reduced default image resize limits to 1568px (from 2000px) and 500KB (from 4.5MB) to match Anthropic's internal downscaling threshold and reduce payload sizes in tool calls
+- Adjusted screenshot compression to use 1024px max dimensions and 150KB budget for more aggressive optimization of browser screenshots in LLM requests
+- Updated JPEG quality defaults from 80 to 75 and refined quality ladder steps (70, 60, 50, 40) for tighter byte budgets
+- Improved image resize fast-path to skip re-encoding when images are already within dimensions and at ≤25% of byte budget, avoiding unnecessary processing of small icons and diagrams
+- Clarified that chunk names are truncated and must be copied from `read` or `?` output rather than constructed from source identifiers
+- Enhanced guidance for editing fenced code blocks in markdown to preserve exact whitespace using `raw` reads, as the tool normalizes tabs to spaces which can damage indentation-sensitive content
+- Updated designer agent to use `pi/designer` role alias instead of explicit model list
+- Refactored model role resolution to support multiple fallback patterns per role, improving model availability handling
+- Replaced regex-based HTML-to-markdown conversion with Turndown library and GFM plugin for more accurate formatting of complex HTML structures
+- Simplified no-changes response to omit redundant response text when chunk content already matches
+- Clarified region suffix behavior on leaf and compound statement chunks — `~` and `^` now fall back to whole-chunk replacement with explicit guidance to supply complete structural content
+- Updated CRC refresh guidance to direct users to use CRCs from edit responses or run `read(path="file", sel="?")`
+- Added clarification that region suffixes fall back to whole-chunk replacement for prose and data formats (markdown, YAML, JSON, fenced code blocks, frontmatter)
+- Documented `L20` shorthand syntax for single-line reads extending to end-of-file, with `L20-L20` for one-line windows
+- Refactored diagnostic target resolution to use new `resolveDiagnosticTargets` function, consolidating glob pattern detection and file matching logic
+- Updated chunk selector syntax from `@region` format to `~` (body) and `^` (head) suffixes for more concise region targeting
+- Simplified chunk edit documentation to use new `~` and `^` region syntax instead of `@head`, `@body`, `@tail`, `@decl` keywords
+- Replaced internal `raceAbort` function with imported `raceWithAbort` utility from pi-utils
+- Refactored cleanup timer to use async iterator pattern with `timers.setInterval` instead of `setInterval`
+- Made `#cleanupIdleSessions` synchronous and moved async cleanup loop logic to new `#runCleanupLoop` method
+- Replaced regex-based `htmlToBasicMarkdown` with a Turndown + GFM plugin pipeline (tables, strikethrough, task lists, nested lists now convert correctly). Added direct `turndown` and `turndown-plugin-gfm` dependencies
+
+### Fixed
+
+- Fixed chunk edit tool to report file-not-found error distinctly when attempting to use chunk selectors on non-existent files, with guidance to use write tool or verify the path
+- Fixed stale child selector reuse to correctly match chunks by checksum when multiple sibling chunks with the same name exist under the same parent
+- Fixed stale diagnostics being reused after unrelated file publishes by clearing cached diagnostics before refreshing file state
+- Fixed Codex search to use streamed answer text when final answer is an image placeholder or empty
+
+## [14.0.4] - 2026-04-10
+### Added
+
+- Added `PI_CHUNK_AUTOINDENT` environment variable to control whether chunk read/edit tools normalize indentation to canonical tabs or preserve literal file whitespace
+- Added dynamic chunk tool prompts that automatically adjust guidance based on `PI_CHUNK_AUTOINDENT` setting without exposing a tool parameter
+- Added `<instruction-priority>`, `<output-contract>`, `<default-follow-through>`, `<tool-persistence>`, and `<completeness-contract>` sections to system prompt for improved long-horizon agent workflows
+
+### Changed
+
+- Updated chunk edit tool to apply `normalizeIndent` setting during edit operations, enabling literal whitespace preservation when `PI_CHUNK_AUTOINDENT=0`
+- Refactored environment variable parsing to use `$flag()` and `$envpos()` utilities from pi-utils for consistent boolean and integer handling across codebase
+- Updated system prompt communication guidelines to emphasize conciseness and information density, and added guidance on avoiding repetition of user requests
+- Enhanced system prompt with explicit rules for design integrity, verification before yielding, and handling of missing context via tool-based retrieval
+- Added `PI_CHUNK_AUTOINDENT` to control whether chunk read/edit tools normalize indentation, and updated chunk prompts to switch guidance automatically based on that setting
+- Refined the default system prompt with explicit instruction-priority, output-contract, tool-persistence, completeness, and verification rules for long-horizon GPT-5.4-style agent workflows
+
+### Fixed
+
+- Fixed typo in system prompt: 'backwards compatibiltity' → 'backwards compatibility'
+
 ## [14.0.3] - 2026-04-09
 
 ### Fixed
@@ -6900,4 +6962,4 @@ Initial public release.
 - Git branch display in footer
 - Message queueing during streaming responses
 - OAuth integration for Gmail and Google Calendar access
-- HTML export with syntax highlighting and collapsible sections
+- HTML export with syntax highlighting and collapsible sections

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "14.0.3",
+	"version": "14.0.5",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -46,12 +46,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@oh-my-pi/omp-stats": "14.0.3",
-		"@oh-my-pi/pi-agent-core": "14.0.3",
-		"@oh-my-pi/pi-ai": "14.0.3",
-		"@oh-my-pi/pi-natives": "14.0.3",
-		"@oh-my-pi/pi-tui": "14.0.3",
-		"@oh-my-pi/pi-utils": "14.0.3",
+		"@oh-my-pi/omp-stats": "14.0.5",
+		"@oh-my-pi/pi-agent-core": "14.0.5",
+		"@oh-my-pi/pi-ai": "14.0.5",
+		"@oh-my-pi/pi-natives": "14.0.5",
+		"@oh-my-pi/pi-tui": "14.0.5",
+		"@oh-my-pi/pi-utils": "14.0.5",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",
@@ -63,10 +63,13 @@
 		"lru-cache": "11.3.1",
 		"markit-ai": "0.5.0",
 		"puppeteer": "^24.37",
+		"turndown": "7.2.4",
+		"turndown-plugin-gfm": "1.0.2",
 		"zod": "4.3.6"
 	},
 	"devDependencies": {
-		"@types/bun": "^1.3"
+		"@types/bun": "^1.3",
+		"@types/turndown": "5.0.6"
 	},
 	"engines": {
 		"bun": ">=1.3.7"

package/src/config/model-registry.ts

@@ -39,7 +39,7 @@ export function isAuthenticated(apiKey: string | undefined | null): apiKey is st
 	return Boolean(apiKey) && apiKey !== kNoAuth;
 }
 
-export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "commit" | "task";
+export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "designer" | "commit" | "task";
 
 export interface ModelRoleInfo {
 	tag?: string;
@@ -53,11 +53,12 @@ export const MODEL_ROLES: Record<ModelRole, ModelRoleInfo> = {
 	slow: { tag: "SLOW", name: "Thinking", color: "accent" },
 	vision: { tag: "VISION", name: "Vision", color: "error" },
 	plan: { tag: "PLAN", name: "Architect", color: "muted" },
+	designer: { tag: "DESIGNER", name: "Designer", color: "muted" },
 	commit: { tag: "COMMIT", name: "Commit", color: "dim" },
 	task: { tag: "TASK", name: "Subtask", color: "muted" },
 };
 
-export const MODEL_ROLE_IDS: ModelRole[] = ["default", "smol", "slow", "vision", "plan", "commit", "task"];
+export const MODEL_ROLE_IDS: ModelRole[] = ["default", "smol", "slow", "vision", "plan", "designer", "commit", "task"];
 
 /** Alias for ModelRoleInfo - used for both built-in and custom roles */
 export type RoleInfo = ModelRoleInfo;

package/src/config/model-resolver.ts

@@ -387,7 +387,7 @@ function isSessionInheritedAgentPattern(value: string): boolean {
 	return value === DEFAULT_MODEL_ROLE || value === `${PREFIX_MODEL_ROLE}${DEFAULT_MODEL_ROLE}` || value === "pi/task";
 }
 
-function resolveConfiguredRolePattern(value: string, settings?: Settings): string | undefined {
+function resolveConfiguredRolePattern(value: string, settings?: Settings): string[] | undefined {
 	const normalized = value.trim();
 	if (!normalized) return undefined;
 
@@ -396,11 +396,16 @@ function resolveConfiguredRolePattern(value: string, settings?: Settings): strin
 		lastColonIndex > PREFIX_MODEL_ROLE.length ? parseThinkingLevel(normalized.slice(lastColonIndex + 1)) : undefined;
 	const aliasCandidate = thinkingLevel ? normalized.slice(0, lastColonIndex) : normalized;
 	const role = getModelRoleAlias(aliasCandidate);
-	if (!role) return normalized;
+	if (!role) return [normalized];
 
 	const configured = settings?.getModelRole(role)?.trim();
-	if (!configured) return undefined;
-	return thinkingLevel ? `${configured}:${thinkingLevel}` : configured;
+	const roleDefaults = normalizeModelPatternList(MODEL_PRIO[role as keyof typeof MODEL_PRIO]);
+	const resolved = configured ? normalizeModelPatternList(configured) : roleDefaults;
+	if (!resolved || resolved.length === 0) {
+		return undefined;
+	}
+
+	return thinkingLevel ? resolved.map(pattern => `${pattern}:${thinkingLevel}`) : resolved;
 }
 
 /**
@@ -412,7 +417,7 @@ export function expandRoleAlias(value: string, settings?: Settings): string {
 		return settings?.getModelRole("default") ?? value;
 	}
 
-	const resolved = resolveConfiguredRolePattern(value, settings);
+	const resolved = resolveConfiguredRolePattern(value, settings)?.[0];
 	return resolved ?? value;
 }
 
@@ -420,10 +425,9 @@ export function resolveConfiguredModelPatterns(value: string | string[] | undefi
 	const patterns = normalizeModelPatternList(value);
 	return patterns.flatMap(pattern => {
 		const resolved = resolveConfiguredRolePattern(pattern, settings);
-		return resolved ? [resolved] : [];
+		return resolved ?? [];
 	});
 }
-
 export interface AgentModelPatternResolutionOptions {
 	settingsOverride?: string | string[];
 	agentModel?: string | string[];
@@ -477,28 +481,32 @@ export function resolveModelRoleValue(
 	}
 
 	const lastColonIndex = normalized.lastIndexOf(":");
-	const thinkingSelector =
+	const _thinkingSelector =
 		lastColonIndex > PREFIX_MODEL_ROLE.length ? parseThinkingLevel(normalized.slice(lastColonIndex + 1)) : undefined;
-	const aliasCandidate = thinkingSelector ? normalized.slice(0, lastColonIndex) : normalized;
-	const effectivePattern = resolveConfiguredRolePattern(aliasCandidate, options?.settings);
-	if (!effectivePattern) {
+	const effectivePatterns = resolveConfiguredRolePattern(normalized, options?.settings);
+	if (!effectivePatterns || effectivePatterns.length === 0) {
 		return { model: undefined, thinkingLevel: undefined, explicitThinkingLevel: false, warning: undefined };
 	}
-	const patternWithSuffix = thinkingSelector ? `${effectivePattern}:${thinkingSelector}` : effectivePattern;
-	const { model, thinkingLevel, warning, explicitThinkingLevel } = parseModelPattern(
-		patternWithSuffix,
-		availableModels,
-		options?.matchPreferences,
-	);
 
-	return {
-		model,
-		thinkingLevel: explicitThinkingLevel
-			? (resolveThinkingLevelForModel(model, thinkingLevel) ?? thinkingLevel)
-			: thinkingLevel,
-		explicitThinkingLevel,
-		warning,
-	};
+	let warning: string | undefined;
+	for (const effectivePattern of effectivePatterns) {
+		const resolved = parseModelPattern(effectivePattern, availableModels, options?.matchPreferences);
+		if (resolved.model) {
+			return {
+				model: resolved.model,
+				thinkingLevel: resolved.explicitThinkingLevel
+					? (resolveThinkingLevelForModel(resolved.model, resolved.thinkingLevel) ?? resolved.thinkingLevel)
+					: resolved.thinkingLevel,
+				explicitThinkingLevel: resolved.explicitThinkingLevel,
+				warning: resolved.warning,
+			};
+		}
+		if (!warning && resolved.warning) {
+			warning = resolved.warning;
+		}
+	}
+
+	return { model: undefined, thinkingLevel: undefined, explicitThinkingLevel: false, warning };
 }
 
 export function extractExplicitThinkingSelector(

package/src/config/settings.ts

@@ -13,8 +13,15 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { setDefaultTabWidth } from "@oh-my-pi/pi-natives";
-import { getAgentDbPath, getAgentDir, getProjectDir, isEnoent, logger, procmgr } from "@oh-my-pi/pi-utils";
+import {
+	getAgentDbPath,
+	getAgentDir,
+	getProjectDir,
+	isEnoent,
+	logger,
+	procmgr,
+	setDefaultTabWidth,
+} from "@oh-my-pi/pi-utils";
 import { YAML } from "bun";
 import { type Settings as SettingsCapabilityItem, settingsCapability } from "../capability/settings";
 import type { ModelRole } from "../config/model-registry";

package/src/dap/session.ts

@@ -1,5 +1,6 @@
 import * as path from "node:path";
-import { logger, ptree } from "@oh-my-pi/pi-utils";
+import * as timers from "node:timers/promises";
+import { logger, ptree, untilAborted } from "@oh-my-pi/pi-utils";
 import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
 import { DapClient } from "./client";
 import type {
@@ -154,27 +155,10 @@ function buildSummary(session: DapSession): DapSessionSummary {
 	};
 }
 
-async function raceAbort<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
-	if (!signal) return promise;
-	if (signal.aborted) {
-		throw signal.reason instanceof Error ? signal.reason : new Error("Operation aborted");
-	}
-	const { promise: abortPromise, reject } = Promise.withResolvers<never>();
-	const onAbort = () => {
-		reject(signal.reason instanceof Error ? signal.reason : new Error("Operation aborted"));
-	};
-	signal.addEventListener("abort", onAbort, { once: true });
-	try {
-		return await Promise.race([promise, abortPromise]);
-	} finally {
-		signal.removeEventListener("abort", onAbort);
-	}
-}
-
 export class DapSessionManager {
 	#sessions = new Map<string, DapSession>();
 	#activeSessionId: string | null = null;
-	#cleanupTimer?: NodeJS.Timeout;
+	#cleanupLoopPromise?: Promise<void>;
 	#nextId = 0;
 
 	constructor() {
@@ -235,7 +219,7 @@ export class DapSessionManager {
 			// Try to capture initial stopped state (e.g. stopOnEntry).
 			// Timeout is acceptable — the program may simply be running.
 			try {
-				await raceAbort(initialStopPromise, signal);
+				await untilAborted(signal, initialStopPromise);
 				if (session.status === "stopped") {
 					await this.#fetchTopFrame(session, signal, Math.min(timeoutMs, STOP_CAPTURE_TIMEOUT_MS));
 				}
@@ -283,7 +267,7 @@ export class DapSessionManager {
 			await this.#completeConfigurationHandshake(session, signal, timeoutMs);
 			await attachPromise;
 			try {
-				await raceAbort(initialStopPromise, signal);
+				await untilAborted(signal, initialStopPromise);
 				if (session.status === "stopped") {
 					await this.#fetchTopFrame(session, signal, Math.min(timeoutMs, STOP_CAPTURE_TIMEOUT_MS));
 				}
@@ -696,9 +680,9 @@ export class DapSessionManager {
 		// between the request and here. Wait for it, but tolerate timeout if the
 		// session already transitioned.
 		try {
-			await raceAbort(
-				session.client.waitForEvent<DapStoppedEventBody>("stopped", undefined, signal, timeoutMs),
+			await untilAborted(
 				signal,
+				session.client.waitForEvent<DapStoppedEventBody>("stopped", undefined, signal, timeoutMs),
 			);
 		} catch {
 			// Timeout or abort — report current state regardless
@@ -833,16 +817,16 @@ export class DapSessionManager {
 		session.lastUsedAt = Date.now();
 		if (session.status !== "terminated") {
 			if (session.capabilities?.supportsTerminateRequest) {
-				await raceAbort(
-					session.client.sendRequest("terminate", undefined, signal, timeoutMs).catch(() => undefined),
+				await untilAborted(
 					signal,
+					session.client.sendRequest("terminate", undefined, signal, timeoutMs).catch(() => undefined),
 				);
 			}
-			await raceAbort(
+			await untilAborted(
+				signal,
 				session.client
 					.sendRequest("disconnect", { terminateDebuggee: true }, signal, timeoutMs)
 					.catch(() => undefined),
-				signal,
 			);
 		}
 		session.status = "terminated";
@@ -852,22 +836,30 @@ export class DapSessionManager {
 	}
 
 	#startCleanupTimer(): void {
-		if (this.#cleanupTimer) return;
-		this.#cleanupTimer = setInterval(() => {
-			void this.#cleanupIdleSessions();
-		}, CLEANUP_INTERVAL_MS);
-		this.#cleanupTimer.unref?.();
+		if (this.#cleanupLoopPromise) return;
+		this.#cleanupLoopPromise = this.#runCleanupLoop();
+	}
+
+	async #runCleanupLoop(): Promise<void> {
+		for await (const _ of timers.setInterval(CLEANUP_INTERVAL_MS, null, { ref: false })) {
+			try {
+				this.#cleanupIdleSessions();
+			} catch (error) {
+				logger.error("DAP idle session cleanup failed", { error: toErrorMessage(error) });
+			}
+		}
 	}
 
-	async #cleanupIdleSessions(): Promise<void> {
+	#cleanupIdleSessions(): void {
+		if (this.#sessions.size === 0) return;
 		const now = Date.now();
-		for (const session of Array.from(this.#sessions.values())) {
+		for (const session of this.#sessions.values()) {
 			if (
 				session.status === "terminated" ||
 				now - session.lastUsedAt > IDLE_TIMEOUT_MS ||
 				!session.client.isAlive()
 			) {
-				await this.#disposeSession(session);
+				this.#disposeSession(session);
 			}
 		}
 	}
@@ -1006,7 +998,7 @@ export class DapSessionManager {
 		// Wait for the initialized event if we haven't seen it yet.
 		if (!session.initializedSeen) {
 			try {
-				await raceAbort(session.client.waitForEvent("initialized", undefined, signal, timeoutMs), signal);
+				await untilAborted(signal, session.client.waitForEvent("initialized", undefined, signal, timeoutMs));
 			} catch {
 				// Adapter may not send initialized (e.g. it already terminated).
 				// Proceed anyway — the launch/attach response will surface any real error.
@@ -1100,7 +1092,7 @@ export class DapSessionManager {
 		timeoutMs: number = 30_000,
 	): Promise<DapContinueOutcome> {
 		try {
-			await raceAbort(outcomePromise, signal);
+			await untilAborted(signal, outcomePromise);
 			if (session.status === "stopped") {
 				await this.#fetchTopFrame(session, signal, Math.min(timeoutMs, 5_000));
 			}
@@ -1243,12 +1235,12 @@ export class DapSessionManager {
 		return session;
 	}
 
-	async #disposeSession(session: DapSession): Promise<void> {
+	#disposeSession(session: DapSession) {
 		if (this.#activeSessionId === session.id) {
 			this.#activeSessionId = null;
 		}
 		this.#sessions.delete(session.id);
-		await session.client.dispose().catch(() => {});
+		void session.client.dispose().catch(() => {});
 	}
 }
 

package/src/debug/log-formatting.ts

@@ -1,5 +1,5 @@
-import { sanitizeText, wrapTextWithAnsi } from "@oh-my-pi/pi-natives";
-import { replaceTabs, truncateToWidth } from "../tools/render-utils";
+import { sanitizeText } from "@oh-my-pi/pi-natives";
+import { replaceTabs, truncateToWidth, wrapTextWithAnsi } from "../tools/render-utils";
 
 export function formatDebugLogLine(line: string, maxWidth: number): string {
 	const sanitized = sanitizeText(line);

package/src/edit/index.ts

@@ -19,6 +19,7 @@ import {
 	executeChunkMode,
 	isChunkParams,
 	resolveAnchorStyle,
+	resolveChunkAutoIndent,
 } from "./modes/chunk";
 import { executeHashlineMode, type HashlineParams, hashlineEditParamsSchema, isHashlineParams } from "./modes/hashline";
 import { executePatchMode, isPatchParams, type PatchParams, patchEditSchema } from "./modes/patch";
@@ -197,6 +198,7 @@ export class EditTool implements AgentTool<TInput> {
 				description: (session: ToolSession) =>
 					prompt.render(chunkEditDescription, {
 						anchorStyle: resolveAnchorStyle(session.settings),
+						chunkAutoIndent: resolveChunkAutoIndent(),
 					}),
 				parameters: chunkEditParamsSchema,
 				invalidParamsMessage: "Invalid edit parameters for chunk mode.",

package/src/edit/modes/chunk.ts

@@ -11,6 +11,7 @@ import {
 	ChunkState,
 	type EditOperation as NativeEditOperation,
 } from "@oh-my-pi/pi-natives";
+import { $envpos } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
 import type { BunFile } from "bun";
 import { LRUCache } from "lru-cache";
@@ -63,6 +64,34 @@ const validAnchorStyles: Record<string, ChunkAnchorStyle> = {
 	bare: ChunkAnchorStyle.Bare,
 };
 
+export function resolveChunkAutoIndent(rawValue = Bun.env.PI_CHUNK_AUTOINDENT): boolean {
+	if (!rawValue) return true;
+	const normalized = rawValue.trim().toLowerCase();
+	switch (normalized) {
+		case "1":
+		case "true":
+		case "yes":
+		case "on":
+			return true;
+		case "0":
+		case "false":
+		case "no":
+		case "off":
+			return false;
+		default:
+			throw new Error(`Invalid PI_CHUNK_AUTOINDENT: ${rawValue}`);
+	}
+}
+
+function getChunkRenderIndentOptions(): {
+	normalizeIndent: boolean;
+	tabReplacement: string;
+} {
+	return resolveChunkAutoIndent()
+		? { normalizeIndent: true, tabReplacement: "    " }
+		: { normalizeIndent: false, tabReplacement: "\t" };
+}
+
 export function resolveAnchorStyle(settings?: Settings): ChunkAnchorStyle {
 	const envStyle = Bun.env.PI_ANCHOR_STYLE;
 	return (
@@ -72,16 +101,8 @@ export function resolveAnchorStyle(settings?: Settings): ChunkAnchorStyle {
 	);
 }
 
-const readEnvInt = (name: string, defaultValue: number): number => {
-	const value = Bun.env[name];
-	if (!value) return defaultValue;
-	const parsed = Number.parseInt(value, 10);
-	if (Number.isNaN(parsed) || parsed <= 0) return defaultValue;
-	return parsed;
-};
-
 const chunkStateCache = new LRUCache<string, ChunkCacheEntry>({
-	max: readEnvInt("PI_CHUNK_CACHE_MAX_ENTRIES", 200),
+	max: $envpos("PI_CHUNK_CACHE_MAX_ENTRIES", 200),
 });
 
 export function invalidateChunkCache(filePath: string): void {
@@ -215,6 +236,7 @@ export async function formatChunkedRead(params: {
 	const normalizedLanguage = normalizeLanguage(language);
 	const { state } = await loadChunkStateForFile(filePath, normalizedLanguage);
 	const displayPath = displayPathForFile(filePath, cwd);
+	const renderIndentOptions = getChunkRenderIndentOptions();
 	const result = state.renderRead({
 		readPath,
 		displayPath,
@@ -224,8 +246,8 @@ export async function formatChunkedRead(params: {
 		absoluteLineRange: absoluteLineRange
 			? { startLine: absoluteLineRange.startLine, endLine: absoluteLineRange.endLine ?? absoluteLineRange.startLine }
 			: undefined,
-		tabReplacement: "    ",
-		normalizeIndent: true,
+		tabReplacement: renderIndentOptions.tabReplacement,
+		normalizeIndent: renderIndentOptions.normalizeIndent,
 	});
 	return { text: result.text, resolvedPath: filePath, chunk: result.chunk };
 }
@@ -280,6 +302,7 @@ export function applyChunkEdits(params: {
 	const state = ChunkState.parse(normalizedSource, normalizeLanguage(params.language));
 	const result = state.applyEdits({
 		operations: nativeOperations,
+		normalizeIndent: resolveChunkAutoIndent(),
 		defaultSelector: params.defaultSelector,
 		defaultCrc: params.defaultCrc,
 		anchorStyle: params.anchorStyle,
@@ -309,10 +332,11 @@ export const chunkToolEditSchema = Type.Object({
 	op: StringEnum(CHUNK_OP_VALUES),
 	sel: Type.String({
 		description:
-			"Chunk selector. Format: 'path@region' for insertions, 'path#CRC@region' for replace. Omit @region to target the full chunk. Valid regions: head, body, tail, decl.",
+			"Chunk selector. Use 'path~' or 'path^' for insertions, 'path#CRC~' or 'path#CRC^' for replace, or omit the suffix to target the full chunk.",
 	}),
 	content: Type.String({
-		description: "New content. Use \\t for indentation. Do NOT include the chunk's base padding.",
+		description:
+			"New content. Write indentation relative to the targeted region as described in the tool prompt. Do NOT include the chunk's base padding.",
 	}),
 });
 export const chunkEditParamsSchema = Type.Object(
@@ -387,7 +411,7 @@ async function writeChunkResult(params: {
 	invalidateFsScanAfterWrite(resolvedPath);
 
 	const diffResult = generateUnifiedDiffString(result.diffSourceBefore, result.diffSourceAfter);
-	const warningsBlock = result.warnings.length > 0 ? `\n\n${result.warnings.join("\n")}` : "";
+	const warningsBlock = result.warnings.length > 0 ? `\n\nWarnings:\n${result.warnings.join("\n")}` : "";
 	const meta = outputMeta()
 		.diagnostics(diagnostics?.summary ?? "", diagnostics?.messages ?? [])
 		.get();
@@ -419,6 +443,12 @@ export async function executeChunkMode(
 	}
 	const normalizedOperations = normalizeChunkEditOperations(edits);
 
+	if (!sourceExists && normalizedOperations.some(op => op.sel)) {
+		throw new Error(
+			`File does not exist: ${path}. Cannot resolve chunk selectors on a non-existent file. Use the write tool to create a new file, or check the path for typos.`,
+		);
+	}
+
 	const chunkResult = applyChunkEdits({
 		source: rawContent,
 		language: chunkLanguage,
@@ -429,9 +459,8 @@ export async function executeChunkMode(
 	});
 
 	if (!chunkResult.changed) {
-		const responseText = `[No changes needed — content already matches.]\n\n${chunkResult.responseText}`;
 		return {
-			content: [{ type: "text", text: responseText }],
+			content: [{ type: "text", text: "[No changes needed \u2014 content already matches.]" }],
 			details: {
 				diff: "",
 				op: sourceExists ? "update" : "create",

package/src/edit/modes/hashline.ts

@@ -156,8 +156,8 @@ interface ExecuteHashlineModeOptions {
 	beginDeferredDiagnosticsForPath: (path: string) => WritethroughDeferredHandle;
 }
 
-export function hashlineParseText(edit: string[] | string | null): string[] {
-	if (edit === null) return [];
+export function hashlineParseText(edit: string[] | string | null | undefined): string[] {
+	if (edit == null) return [];
 	if (typeof edit === "string") {
 		const normalizedEdit = edit.endsWith("\n") ? edit.slice(0, -1) : edit;
 		edit = normalizedEdit.replaceAll("\r", "").split("\n");

package/src/ipy/executor.ts

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { getAgentDir, getProjectDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
+import { getAgentDir, getProjectDir, isBunTestRuntime, isEnoent, logger } from "@oh-my-pi/pi-utils";
 import { OutputSink } from "../session/streaming-output";
 import { shutdownSharedGateway } from "./gateway-coordinator";
 import {
@@ -299,10 +299,6 @@ async function writePreludeCache(state: PreludeCacheState, helpers: PreludeHelpe
 	}
 }
 
-function isPythonTestEnvironment(): boolean {
-	return Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
-}
-
 function getPreludeIntrospectionOptions(
 	options: KernelSessionExecutionOptions = {},
 ): Pick<KernelExecuteOptions, "signal" | "timeoutMs"> {
@@ -318,7 +314,7 @@ async function cachePreludeDocs(
 	cacheState?: PreludeCacheState | null,
 ): Promise<PreludeHelper[]> {
 	cachedPreludeDocs = docs;
-	if (!isPythonTestEnvironment() && docs.length > 0) {
+	if (!isBunTestRuntime() && docs.length > 0) {
 		const state = cacheState ?? (await buildPreludeCacheState(cwd));
 		await writePreludeCache(state, docs);
 	}
@@ -416,7 +412,7 @@ export async function warmPythonEnvironment(
 		cachedPreludeDocs = [];
 		return { ok: false, reason, docs: [] };
 	}
-	if (!isPythonTestEnvironment()) {
+	if (!isBunTestRuntime()) {
 		try {
 			cacheState = await buildPreludeCacheState(cwd);
 			const cached = await readPreludeCache(cacheState);

package/src/ipy/kernel.ts

@@ -1,4 +1,4 @@
-import { $env, logger, Snowflake } from "@oh-my-pi/pi-utils";
+import { $env, $flag, isBunTestRuntime, logger, Snowflake } from "@oh-my-pi/pi-utils";
 import { $ } from "bun";
 import { Settings } from "../config/settings";
 import { htmlToBasicMarkdown } from "../web/scrapers/types";
@@ -10,7 +10,7 @@ import { filterEnv, resolvePythonRuntime } from "./runtime";
 
 const TEXT_ENCODER = new TextEncoder();
 const TEXT_DECODER = new TextDecoder();
-const TRACE_IPC = $env.PI_PYTHON_IPC_TRACE === "1";
+const TRACE_IPC = $flag("PI_PYTHON_IPC_TRACE");
 const PRELUDE_INTROSPECTION_SNIPPET = "import json\nprint(json.dumps(__omp_prelude_docs__()))";
 
 class SharedGatewayCreateError extends Error {
@@ -195,7 +195,7 @@ export interface PythonKernelAvailability {
 }
 
 export async function checkPythonKernelAvailability(cwd: string): Promise<PythonKernelAvailability> {
-	if (Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test" || $env.PI_PYTHON_SKIP_CHECK === "1") {
+	if (isBunTestRuntime() || $flag("PI_PYTHON_SKIP_CHECK")) {
 		return { ok: true };
 	}