@oh-my-pi/pi-coding-agent 15.7.3 → 15.7.5

package/src/internal-urls/local-protocol.ts

@@ -5,7 +5,7 @@ import { isEnoent } from "@oh-my-pi/pi-utils";
 import { AgentRegistry } from "../registry/agent-registry";
 import { parseInternalUrl } from "./parse";
 import { validateRelativePath } from "./skill-protocol";
-import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, UrlCompletion } from "./types";
 
 export interface LocalProtocolOptions {
 	getArtifactsDir?: () => string | null;
@@ -164,13 +164,25 @@ export class LocalProtocolHandler implements ProtocolHandler {
 	 * Returns the active local-protocol options.
 	 *
 	 * Resolution order:
-	 * 1. Explicit override installed via {@link setOverride} (used by subagents
-	 *    that share their parent's root and by SDK consumers with a custom
-	 *    artifacts/session id mapping).
-	 * 2. The main session in `AgentRegistry.global()`. Its `SessionManager`
-	 *    supplies both `getArtifactsDir` and `getSessionId`.
+	 * 1. **Caller-supplied** `context.localProtocolOptions` (the actual session
+	 *    that initiated the `read`/`find`/`search`/`router.resolve` call). This
+	 *    is what keeps `local://` reads pinned to the calling session in
+	 *    multi-session hosts (cmux/ACP, embedded SDK consumers) where every
+	 *    session registers as `kind: "main"` and "first one wins" would route
+	 *    to the wrong artifacts directory.
+	 * 2. Explicit process-global override installed via {@link setOverride}
+	 *    (used by SDK consumers with a custom artifacts/session-id mapping and
+	 *    by code paths that do not have a calling session, e.g. TUI hyperlink
+	 *    resolution).
+	 * 3. The first `main`-kind session in `AgentRegistry.global()`. Its
+	 *    `SessionManager` supplies both `getArtifactsDir` and `getSessionId`.
+	 *    Last-resort fallback — every caller that has a session reference
+	 *    SHOULD thread it through `context` so this branch is never taken in
+	 *    multi-session setups.
 	 */
-	static resolveOptions(): LocalProtocolOptions | undefined {
+	static resolveOptions(context?: ResolveContext): LocalProtocolOptions | undefined {
+		const fromContext = context?.localProtocolOptions;
+		if (fromContext) return fromContext;
 		const override = LocalProtocolHandler.#override;
 		if (override) return override;
 		const main = AgentRegistry.global()
@@ -184,8 +196,8 @@ export class LocalProtocolHandler implements ProtocolHandler {
 		};
 	}
 
-	async resolve(url: InternalUrl): Promise<InternalResource> {
-		const opts = LocalProtocolHandler.resolveOptions();
+	async resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
+		const opts = LocalProtocolHandler.resolveOptions(context);
 		if (!opts) {
 			throw new Error("No session - local:// unavailable");
 		}
@@ -247,8 +259,8 @@ export class LocalProtocolHandler implements ProtocolHandler {
 		};
 	}
 
-	async complete(): Promise<UrlCompletion[]> {
-		const opts = LocalProtocolHandler.resolveOptions();
+	async complete(_query?: string, context?: ResolveContext): Promise<UrlCompletion[]> {
+		const opts = LocalProtocolHandler.resolveOptions(context);
 		if (!opts) return [];
 		const localRoot = path.resolve(resolveLocalRoot(opts));
 		try {

package/src/internal-urls/types.ts

@@ -5,6 +5,8 @@
  * providing access to agent outputs and server resources without exposing filesystem paths.
  */
 
+import type { LocalProtocolOptions } from "./local-protocol";
+
 /**
  * Raw resource payload returned by protocol handlers. The `immutable` flag is
  * applied by the router from {@link ProtocolHandler.immutable}, so handlers do
@@ -77,6 +79,17 @@ export interface ResolveContext {
 	settings?: unknown;
 	/** Caller's abort signal. */
 	signal?: AbortSignal;
+	/**
+	 * Calling session's `local://` root mapping. When present, the local-protocol
+	 * handler resolves the URL against THIS session's artifacts dir instead of
+	 * picking the first `main`-kind session from the global `AgentRegistry`.
+	 *
+	 * Required for correctness in multi-session hosts (cmux/ACP, embedded SDK
+	 * consumers) where multiple sessions are registered as `main` and the
+	 * "first one wins" lookup picks the wrong artifacts directory — see
+	 * [#1608](https://github.com/can1357/oh-my-pi/issues/1608).
+	 */
+	localProtocolOptions?: LocalProtocolOptions;
 }
 
 /**
@@ -89,6 +102,8 @@ export interface WriteContext {
 	cwd?: string;
 	/** Caller's abort signal. */
 	signal?: AbortSignal;
+	/** Calling session's `local://` root mapping — see {@link ResolveContext.localProtocolOptions}. */
+	localProtocolOptions?: LocalProtocolOptions;
 }
 
 /**

package/src/lsp/client.ts

@@ -415,6 +415,10 @@ export const WARMUP_TIMEOUT_MS = 5000;
 /** Max time to wait for the server to report project loading completion via $/progress */
 const PROJECT_LOAD_TIMEOUT_MS = 15_000;
 
+/** Max time to wait for graceful LSP shutdown and process exit. */
+const SHUTDOWN_TIMEOUT_MS = 5_000;
+const EXIT_TIMEOUT_MS = 1_000;
+
 /**
  * Get or create an LSP client for the given server configuration and working directory.
  * @param config - Server configuration
@@ -768,8 +772,18 @@ export async function refreshFile(client: LspClient, filePath: string, signal?:
 	}
 }
 
+async function waitForExit(client: LspClient, timeoutMs: number): Promise<boolean> {
+	return await Promise.race([
+		client.proc.exited.then(
+			() => true,
+			() => true,
+		),
+		Bun.sleep(timeoutMs).then(() => false),
+	]);
+}
+
 /**
- * Shutdown a specific client by key.
+ * Shutdown a specific client instance using the LSP shutdown/exit handshake.
  */
 async function shutdownClientInstance(client: LspClient): Promise<void> {
 	const err = new Error("LSP client shutdown");
@@ -778,13 +792,22 @@ async function shutdownClientInstance(client: LspClient): Promise<void> {
 	}
 	client.pendingRequests.clear();
 
-	const timeout = Bun.sleep(5_000);
-	const shutdown = sendRequest(client, "shutdown", null).catch(() => {});
-	await Promise.race([shutdown, timeout]);
+	const shutdownCompleted = await sendRequest(client, "shutdown", null, undefined, SHUTDOWN_TIMEOUT_MS).then(
+		() => true,
+		() => false,
+	);
+	if (shutdownCompleted) {
+		await sendNotification(client, "exit", undefined).catch(() => {});
+		if (await waitForExit(client, EXIT_TIMEOUT_MS)) return;
+	}
+
 	client.proc.kill();
-	await Promise.race([client.proc.exited.catch(() => {}), Bun.sleep(1_000)]);
+	await waitForExit(client, EXIT_TIMEOUT_MS);
 }
 
+/**
+ * Shutdown a specific client by key.
+ */
 export async function shutdownClient(key: string): Promise<void> {
 	const client = clients.get(key);
 	if (!client) return;

package/src/mcp/manager.ts

@@ -59,6 +59,27 @@ type TrackedPromise<T> = {
 
 const STARTUP_TIMEOUT_MS = 250;
 
+/**
+ * Per-server reconnect-storm circuit breaker.
+ *
+ * `transport.onClose` (wired in {@link MCPManager.connectServers} and
+ * {@link MCPManager.#connectAndWireServer}) fires `reconnectServer` on every
+ * clean process exit, so a stdio MCP server that completes the
+ * `initialize` + `tools/list` handshake and then exits will pull the agent
+ * into a fork loop with no rate limit. That pathology shipped in issue #1592
+ * (a `php`-shebang MCP fork-bombing macOS, parented directly to the agent's
+ * `bun` PID via shebang exec).
+ *
+ * We keep the sliding window short — older crashes age out so a single
+ * transient failure stays cheap — but cap the burst tightly enough that the
+ * agent never spawns more than `RECONNECT_BURST_LIMIT * #doReconnect retries`
+ * (≤ 25) processes per stuck server per window. Manual `/mcp reconnect`
+ * resets the window so users can recover after fixing the underlying
+ * misconfiguration.
+ */
+const RECONNECT_BURST_WINDOW_MS = 30_000;
+const RECONNECT_BURST_LIMIT = 5;
+
 function trackPromise<T>(promise: Promise<T>): TrackedPromise<T> {
 	const tracked: TrackedPromise<T> = { promise, status: "pending" };
 	promise.then(
@@ -166,6 +187,11 @@ export class MCPManager {
 	#pendingReconnections = new Map<string, Promise<MCPServerConnection | null>>();
 	/** Preserved configs for reconnection after connection loss. */
 	#serverConfigs = new Map<string, MCPServerConfig>();
+	/**
+	 * Timestamps of recent `reconnectServer` invocations per server, used by the
+	 * crash-storm circuit breaker (see {@link RECONNECT_BURST_LIMIT}).
+	 */
+	#reconnectHistory = new Map<string, number[]>();
 	/** Monotonic epoch incremented on disconnectAll to invalidate stale reconnections. */
 	#epoch = 0;
 
@@ -666,6 +692,7 @@ export class MCPManager {
 		this.#sources.delete(name);
 		this.#serverConfigs.delete(name);
 		this.#pendingResourceRefresh.delete(name);
+		this.#reconnectHistory.delete(name);
 
 		const connection = this.#connections.get(name);
 
@@ -714,24 +741,80 @@ export class MCPManager {
 		this.#connections.clear();
 		this.#tools = [];
 		this.#subscribedResources.clear();
+		this.#reconnectHistory.clear();
 	}
 
 	/**
 	 * Reconnect to a server after a connection failure.
+	 *
 	 * Tears down the stale connection, re-resolves auth, establishes a new
-	 * connection, reloads tools, and notifies consumers.
-	 * Concurrent calls for the same server share one reconnection attempt.
-	 * Returns the new connection, or null if reconnection failed.
+	 * connection, reloads tools, and notifies consumers. Concurrent calls for
+	 * the same server share one reconnection attempt. Returns the new
+	 * connection, or `null` if reconnection failed or the per-server crash
+	 * burst limit (see {@link RECONNECT_BURST_LIMIT}) is exceeded.
+	 *
+	 * @param options.manual - When `true`, resets the crash-burst window so a
+	 *   user-driven retry (e.g. `/mcp reconnect`) is never blocked by an
+	 *   earlier storm. Defaults to `false`; the transport `onClose` callback
+	 *   and the per-tool-call retry path in `tool-bridge` MUST NOT set it.
 	 */
-	async reconnectServer(name: string): Promise<MCPServerConnection | null> {
+	async reconnectServer(name: string, options?: { manual?: boolean }): Promise<MCPServerConnection | null> {
+		if (options?.manual) {
+			this.#reconnectHistory.delete(name);
+		}
+
 		const pending = this.#pendingReconnections.get(name);
 		if (pending) return pending;
 
+		if (this.#tripReconnectBreaker(name)) {
+			return null;
+		}
+
 		const attempt = this.#doReconnect(name);
 		this.#pendingReconnections.set(name, attempt);
 		return attempt.finally(() => this.#pendingReconnections.delete(name));
 	}
 
+	/**
+	 * Record a reconnect attempt against the per-server crash window and report
+	 * whether the circuit breaker is now open. Sliding window: entries older
+	 * than {@link RECONNECT_BURST_WINDOW_MS} are pruned before the new
+	 * timestamp is appended, so a single transient failure ages out cheaply
+	 * but repeated rapid crashes accumulate until the limit is hit.
+	 */
+	#tripReconnectBreaker(name: string): boolean {
+		const now = Date.now();
+		const previous = this.#reconnectHistory.get(name) ?? [];
+		const recent = previous.filter(ts => now - ts < RECONNECT_BURST_WINDOW_MS);
+		recent.push(now);
+		this.#reconnectHistory.set(name, recent);
+
+		if (recent.length > RECONNECT_BURST_LIMIT) {
+			logger.error("MCP server crashed too many times; suspending automatic reconnects", {
+				path: `mcp:${name}`,
+				crashes: recent.length,
+				windowMs: RECONNECT_BURST_WINDOW_MS,
+			});
+			// Tear down the stale connection so `getConnectionStatus()` no
+			// longer reports it as "connected" and `waitForConnection()` does
+			// not hand a closed transport to callers. Tools stay registered
+			// in `#tools` — the user can recover with `/mcp reconnect <name>`
+			// once they've fixed the underlying misconfiguration. Mirrors the
+			// teardown in `#doReconnect`: detach `onClose` first so the
+			// transport's own `close()` cannot re-arm this path.
+			const stale = this.#connections.get(name);
+			if (stale) {
+				stale.transport.onClose = undefined;
+				void stale.transport.close().catch(() => {});
+				this.#connections.delete(name);
+			}
+			this.#pendingConnections.delete(name);
+			this.#pendingToolLoads.delete(name);
+			return true;
+		}
+		return false;
+	}
+
 	async #doReconnect(name: string): Promise<MCPServerConnection | null> {
 		const oldConnection = this.#connections.get(name);
 		const config = oldConnection?.config ?? this.#serverConfigs.get(name);

package/src/modes/controllers/command-controller.ts

@@ -1124,48 +1124,16 @@ export class CommandController {
 	}
 
 	/**
-	 * TUI handler for `/shake`. `elide`/`images` are instant structural drops;
-	 * `summary` runs the local on-device compressor behind a cancelable loader
-	 * (Esc aborts via `abortCompaction`). Rebuilds the chat and reports counts.
+	 * TUI handler for `/shake`. `elide` drops heavy structural content and
+	 * `images` strips image blocks. Rebuilds the chat and reports counts.
 	 */
 	async handleShakeCommand(mode: ShakeMode): Promise<void> {
 		let result: ShakeResult;
-		if (mode === "summary") {
-			if (this.ctx.loadingAnimation) {
-				this.ctx.loadingAnimation.stop();
-				this.ctx.loadingAnimation = undefined;
-			}
-			this.ctx.statusContainer.clear();
-			const originalOnEscape = this.ctx.editor.onEscape;
-			this.ctx.editor.onEscape = () => {
-				this.ctx.session.abortCompaction();
-			};
-			const loader = new Loader(
-				this.ctx.ui,
-				spinner => theme.fg("accent", spinner),
-				text => theme.fg("muted", text),
-				"Shaking context (summary)… (esc to cancel)",
-				getSymbolTheme().spinnerFrames,
-			);
-			this.ctx.statusContainer.addChild(loader);
-			this.ctx.ui.requestRender();
-			try {
-				result = await this.ctx.session.shake("summary");
-			} catch (error) {
-				this.ctx.showError(`Shake failed: ${error instanceof Error ? error.message : String(error)}`);
-				return;
-			} finally {
-				loader.stop();
-				this.ctx.statusContainer.clear();
-				this.ctx.editor.onEscape = originalOnEscape;
-			}
-		} else {
-			try {
-				result = await this.ctx.session.shake(mode);
-			} catch (error) {
-				this.ctx.showError(`Shake failed: ${error instanceof Error ? error.message : String(error)}`);
-				return;
-			}
+		try {
+			result = await this.ctx.session.shake(mode);
+		} catch (error) {
+			this.ctx.showError(`Shake failed: ${error instanceof Error ? error.message : String(error)}`);
+			return;
 		}
 
 		const dropped = result.toolResultsDropped + result.blocksDropped + (result.imagesDropped ?? 0);

package/src/modes/controllers/event-controller.ts

@@ -25,12 +25,14 @@ type AgentSessionEventKind = AgentSessionEvent["type"];
 
 const IRC_MESSAGE_VISIBLE_TTL_MS = 10_000;
 
-// Events that change which foreground tools are executing, or that reset a turn.
-// The eager native-scrollback rebuild mode is recomputed only on these — other
-// events (assistant text streaming, IRC, notices) leave it untouched so plain
-// streaming keeps the no-yank deferral.
-const TOOL_RENDER_MODE_EVENTS: Record<string, true> = {
+// Events that change foreground streaming state, or that reset a turn. The TUI
+// eager native-scrollback rebuild mode is recomputed only on these so unrelated
+// IRC/notices/status refreshes do not toggle scrollback replay policy.
+const STREAM_RENDER_MODE_EVENTS: Record<string, true> = {
 	agent_start: true,
+	agent_end: true,
+	message_start: true,
+	message_end: true,
 	tool_execution_start: true,
 	tool_execution_update: true,
 	tool_execution_end: true,
@@ -46,6 +48,7 @@ export class EventController {
 	#renderedCustomMessages = new Set<string>();
 	#lastIntent: string | undefined = undefined;
 	#backgroundToolCallIds = new Set<string>();
+	#assistantMessageStreaming = false;
 	#readToolCallArgs = new Map<string, Record<string, unknown>>();
 	#readToolCallAssistantComponents = new Map<string, AssistantMessageComponent>();
 	#lastAssistantComponent: AssistantMessageComponent | undefined = undefined;
@@ -169,24 +172,27 @@ export class EventController {
 
 		const run = this.#handlers[event.type] as (e: AgentSessionEvent) => Promise<void>;
 		await run(event);
-		// While a foreground tool is executing, its streaming result re-renders and can
-		// re-lay-out rows that already scrolled into native scrollback. Let the TUI
-		// rebuild history on those offscreen edits (a snap to the tail is acceptable
-		// mid-tool) instead of deferring, which would leave stale/duplicated rows.
-		// Background-running tools are excluded so their late async updates — and the
-		// assistant text that streams alongside them — keep the no-yank deferral;
-		// agent_start resets the mode at every turn boundary.
-		if (TOOL_RENDER_MODE_EVENTS[event.type]) {
+		// While assistant text or a foreground tool is streaming, rows above the
+		// viewport can re-layout after they have already entered native scrollback
+		// (Markdown fences, wrapping, previews). Let the TUI rebuild history on
+		// those offscreen edits instead of deferring, which otherwise leaves stale
+		// tail rows duplicated above the live viewport.
+		// Background-running tools are excluded so late async updates outside the
+		// active foreground stream keep the no-yank deferral; agent_start resets
+		// the mode at every turn boundary.
+		if (STREAM_RENDER_MODE_EVENTS[event.type]) {
 			this.#refreshToolRenderMode();
 		}
 	}
 
 	#refreshToolRenderMode(): void {
-		let foregroundToolActive = false;
-		for (const toolCallId of this.ctx.pendingTools.keys()) {
-			if (!this.#backgroundToolCallIds.has(toolCallId)) {
-				foregroundToolActive = true;
-				break;
+		let foregroundToolActive = this.#assistantMessageStreaming;
+		if (!foregroundToolActive) {
+			for (const toolCallId of this.ctx.pendingTools.keys()) {
+				if (!this.#backgroundToolCallIds.has(toolCallId)) {
+					foregroundToolActive = true;
+					break;
+				}
 			}
 		}
 		this.ctx.ui.setEagerNativeScrollbackRebuild(foregroundToolActive);
@@ -196,6 +202,7 @@ export class EventController {
 		this.#lastIntent = undefined;
 		this.#readToolCallArgs.clear();
 		this.#readToolCallAssistantComponents.clear();
+		this.#assistantMessageStreaming = false;
 		this.#lastAssistantComponent = undefined;
 		if (this.ctx.retryEscapeHandler) {
 			this.ctx.editor.onEscape = this.ctx.retryEscapeHandler;
@@ -268,6 +275,7 @@ export class EventController {
 			this.ctx.ui.requestRender();
 		} else if (event.message.role === "assistant") {
 			this.#lastThinkingCount = 0;
+			this.#assistantMessageStreaming = true;
 			this.#resetReadGroup();
 			this.ctx.streamingComponent = new AssistantMessageComponent(undefined, this.ctx.hideThinkingBlock, () =>
 				this.ctx.ui.requestRender(),
@@ -414,6 +422,9 @@ export class EventController {
 
 	async #handleMessageEnd(event: Extract<AgentSessionEvent, { type: "message_end" }>): Promise<void> {
 		if (event.message.role === "user") return;
+		if (event.message.role === "assistant") {
+			this.#assistantMessageStreaming = false;
+		}
 		if (this.ctx.streamingComponent && event.message.role === "assistant") {
 			this.ctx.streamingMessage = event.message;
 			let errorMessage: string | undefined;
@@ -596,8 +607,8 @@ export class EventController {
 			}
 		}
 	}
-
 	async #handleAgentEnd(_event: Extract<AgentSessionEvent, { type: "agent_end" }>): Promise<void> {
+		this.#assistantMessageStreaming = false;
 		if (this.ctx.loadingAnimation) {
 			this.ctx.loadingAnimation.stop();
 			this.ctx.loadingAnimation = undefined;
@@ -647,9 +658,7 @@ export class EventController {
 				? "Auto-handoff"
 				: event.action === "shake"
 					? "Auto-shake"
-					: event.action === "shake-summary"
-						? "Auto-shake (summary)"
-						: "Auto context-full maintenance";
+					: "Auto context-full maintenance";
 		this.ctx.autoCompactionLoader = new Loader(
 			this.ctx.ui,
 			spinner => theme.fg("accent", spinner),
@@ -673,7 +682,7 @@ export class EventController {
 			this.ctx.statusContainer.clear();
 		}
 		const isHandoffAction = event.action === "handoff";
-		const isShakeAction = event.action === "shake" || event.action === "shake-summary";
+		const isShakeAction = event.action === "shake";
 		if (event.aborted) {
 			this.ctx.showStatus(
 				isHandoffAction
@@ -690,9 +699,7 @@ export class EventController {
 				this.ctx.rebuildChatFromMessages();
 				this.ctx.statusLine.invalidate();
 				this.ctx.updateEditorTopBorder();
-				this.ctx.showStatus(
-					event.action === "shake-summary" ? "Auto-shake (summary) completed" : "Auto-shake completed",
-				);
+				this.ctx.showStatus("Auto-shake completed");
 			}
 		} else if (event.result) {
 			this.ctx.rebuildChatFromMessages();

package/src/modes/controllers/mcp-command-controller.ts

@@ -1425,7 +1425,7 @@ export class MCPCommandController {
 		this.#showMessage(["", theme.fg("muted", `Reconnecting to "${name}"...`), ""].join("\n"));
 
 		try {
-			const connection = await this.ctx.mcpManager.reconnectServer(name);
+			const connection = await this.ctx.mcpManager.reconnectServer(name, { manual: true });
 			if (connection) {
 				// refreshMCPTools re-registers tools and preserves the user's prior
 				// MCP tool selection. No need to call activateDiscoveredMCPTools —

package/src/prompts/system/project-prompt.md

@@ -1,4 +1,6 @@
-[PROJECT]
+PROJECT
+===================================
+
 <workstation>
 {{#list environment prefix="- " join="\n"}}{{label}}: {{value}}{{/list}}
 </workstation>
@@ -47,4 +49,3 @@ Today is {{date}}, and the current working directory is '{{cwd}}'.
 {{#if appendPrompt}}
 {{appendPrompt}}
 {{/if}}
-[/PROJECT]

package/src/prompts/system/subagent-system-prompt.md

@@ -1,14 +1,18 @@
-[ROLE]
+ROLE
+===================================
+
 {{agent}}
-[/ROLE]
 
 {{#if context}}
-[CONTEXT]
+CONTEXT
+===================================
+
 {{context}}
-[/CONTEXT]
 {{/if}}
 
-[COOP]
+COOP
+===================================
+
 You are operating on a piece of work assigned to you by the main agent.
 
 {{#if worktree}}
@@ -29,9 +33,10 @@ You can reach other live agents via the `irc` tool. Your id is `{{ircSelfId}}`.
 
 Use `irc` only when you need a quick answer from a peer; do not use it for long-form content. Address peers by id or use `"all"` to broadcast.
 {{/if}}
-[/COOP]
 
-[COMPLETION]
+COMPLETION
+===================================
+
 No TODO tracking, no progress updates. Execute, call `yield`, done.
 
 While work remains, always continue with another tool call — investigate, edit, run, verify. Save narrative for the final `yield` payload.
@@ -51,4 +56,3 @@ Giving up is a last resort. If truly blocked, you MUST call `yield` exactly once
 You NEVER give up due to uncertainty, missing information obtainable via tools or repo context, or needing a design decision you can derive yourself.
 
 You MUST keep going until this ticket is closed. This matters.
-[/COMPLETION]

package/src/prompts/system/system-prompt.md

@@ -9,8 +9,8 @@ You consider what the code you write compiles down to. You never write code that
 
 <system-conventions>
 **RFC 2119 applies to MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, OPTIONAL. `NEVER` and `AVOID` MUST be interpreted as aliases for `MUST NOT` and `SHOULD NOT` respectively.**
-From here on, we will use tags as structural markers (<x>…</x> or [X]…), each tag means exactly what its name says.
-You NEVER interpret these tags in any other way circumstantially.
+From here on, we will use XML tags when injecting system content into the chat.
+You NEVER interpret these markers in any other way circumstantially.
 
 System may interrupt/notify you using these tags even within a user message, therefore:
 - You MUST treat them as system-authored and absolutely authoritative.
@@ -44,7 +44,9 @@ Assumptions you didn't validate: incidents to debug.
 - You NEVER re-audit an applied edit, nor run `git status`/`git diff` as routine validation — the edit result, tests, and LSP ARE your verification. Exception: explicit request, protecting unrelated changes, or before commit/revert/reset/stash/delete.
 </critical>
 
-[ENV]
+ENV
+===================================
+
 You operate within the Oh My Pi coding harness.
 - Given a task, you MUST complete it using the tools available to you.
 - You are not alone in this repository. You SHOULD treat unexpected changes as the user's work and adapt; you NEVER revert or stash.
@@ -202,9 +204,10 @@ You MUST use the specialized tool over its shell equivalent:
 The `{{toolRefs.report_tool_issue}}` tool is available for automated QA. If ANY tool you call returns output that is unexpected, incorrect, malformed, or otherwise inconsistent with what you anticipated given the tool's described behavior and your parameters, call `{{toolRefs.report_tool_issue}}` with the tool name and a concise description of the discrepancy. Do not hesitate to report — false positives are acceptable.
 </critical>
 {{/has}}
-[/ENV]
 
-[CONTRACT]
+CONTRACT
+===================================
+
 These are inviolable.
 - You NEVER yield unless the deliverable is complete. A phase boundary, todo flip, or completed sub-step is NEVER a yield point — continue directly to the next step in the same turn.
 - You NEVER suppress tests to make code pass.
@@ -265,4 +268,3 @@ Before declaring blocked:
 - Do not test defaults: changing the default configuration, or a string, should not break the test. Assert logical behavior, not the current state.
 - Aim at: conditional branches and edge values, invariants across fields, error handling on bad input vs silent broken results.
 </workflow>
-[/CONTRACT]