@oh-my-pi/pi-coding-agent 15.10.0 → 15.10.1

package/src/lsp/utils.ts

@@ -153,9 +153,10 @@ export function formatDiagnostic(diagnostic: Diagnostic, filePath: string): stri
 const DIAG_PATH_RE = /^(.+?):(\d+:\d+\s+.*)$/;
 
 /**
- * Reformat pre-formatted diagnostic messages into grep-style directory/file groups.
+ * Reformat pre-formatted diagnostic messages into a multi-level, prefix-folded
+ * directory/file grouping (see `formatGroupedFiles`).
  * Input:  ["path:line:col [sev] msg", ...]
- * Output: "# dir/\n## file.ts\n  line:col [sev] msg"
+ * Output: "# pkg/src/\n## file.ts\n  line:col [sev] msg"
  *
  * Messages that don't match the expected format are appended ungrouped at the end.
  */

package/src/main.ts

@@ -278,7 +278,10 @@ async function runInteractiveMode(
 			})
 		: [];
 
-	await mode.init({ suppressWelcomeIntro: resuming || setupScenes.length > 0 });
+	await mode.init({
+		suppressWelcomeIntro: resuming || setupScenes.length > 0,
+		clearInitialTerminalHistory: true,
+	});
 
 	if (setupWizard && setupScenes.length > 0) {
 		await setupWizard.runSetupWizard(mode, setupScenes);
@@ -295,12 +298,11 @@ async function runInteractiveMode(
 		})
 		.catch(() => {});
 
-	// Cold-launch cleanup: wipe the terminal scrollback before painting the
-	// resumed/new transcript. The TUI's initial paint deliberately preserves
-	// native scrollback (prior shell content), but on `omp`/`omp -c` that leaves
-	// the previous run's welcome + transcript stacked above the fresh one. Every
-	// in-process session load already clears via `clearTerminalHistory`; the cold
-	// launch is the lone path that did not.
+	// Cold-launch cleanup: the first paint already clears native history, and this
+	// replay replaces the welcome/startup frame with the resumed/new transcript.
+	// Every in-process session load also uses `clearTerminalHistory`; cold launch
+	// follows the same clean-cutover path instead of preserving a previous run's
+	// transcript above the fresh one.
 	mode.renderInitialMessages(undefined, { preserveExistingChat: true, clearTerminalHistory: true });
 
 	for (const notify of notifs) {

package/src/memories/index.ts

@@ -3,8 +3,9 @@ import type * as fsNode from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
-import { clampThinkingLevelForModel, completeSimple, Effort, type Model } from "@oh-my-pi/pi-ai";
+import { type ApiKey, clampThinkingLevelForModel, completeSimple, Effort, type Model } from "@oh-my-pi/pi-ai";
 import { getAgentDbPath, getMemoriesDir, logger, parseJsonlLenient, prompt } from "@oh-my-pi/pi-utils";
+
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveModelRoleValue } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
@@ -271,7 +272,10 @@ async function runPhase1(options: {
 			const result = await runStage1Job({
 				claim,
 				model: phase1Model,
-				apiKey: phase1ApiKey,
+				apiKey: modelRegistry.resolver(phase1Model.provider, {
+					sessionId: session.sessionId,
+					baseUrl: phase1Model.baseUrl,
+				}),
 				modelMaxTokens: computeModelTokenBudget(phase1Model, config),
 				config,
 				metadata: session.agent?.metadataForProvider(phase1Model.provider),
@@ -428,7 +432,10 @@ async function runPhase2(options: {
 			const consolidated = await runConsolidationModel({
 				memoryRoot,
 				model: phase2Model,
-				apiKey: phase2ApiKey,
+				apiKey: modelRegistry.resolver(phase2Model.provider, {
+					sessionId: session.sessionId,
+					baseUrl: phase2Model.baseUrl,
+				}),
 				metadata: session.agent?.metadataForProvider(phase2Model.provider),
 			});
 			await applyConsolidation(memoryRoot, consolidated);
@@ -574,7 +581,7 @@ function extractPersistableMessages(payload: string): AgentMessage[] {
 async function runStage1Job(options: {
 	claim: Stage1Claim;
 	model: Model;
-	apiKey: string;
+	apiKey: ApiKey;
 	modelMaxTokens: number;
 	config: MemoryRuntimeConfig;
 	metadata?: Record<string, unknown>;
@@ -718,7 +725,7 @@ async function readRolloutSummaries(memoryRoot: string): Promise<string> {
 async function runConsolidationModel(options: {
 	memoryRoot: string;
 	model: Model;
-	apiKey: string;
+	apiKey: ApiKey;
 	metadata?: Record<string, unknown>;
 }): Promise<{
 	memoryMd: string;

package/src/mnemopi/backend.ts

@@ -5,6 +5,7 @@ import { Mnemopi } from "@oh-my-pi/pi-mnemopi";
 import { BankManager } from "@oh-my-pi/pi-mnemopi/core";
 import { type DiagnosticSummary, inspectDatabase } from "@oh-my-pi/pi-mnemopi/diagnose";
 import { logger } from "@oh-my-pi/pi-utils";
+
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveRoleSelection } from "../config/model-resolver";
 import type { MemoryBackend, MemoryBackendStartOptions } from "../memory-backend/types";
@@ -334,7 +335,10 @@ async function resolveMnemopiProviderOptions(
 						messages: [{ role: "user", content: prompt, timestamp: Date.now() }],
 					},
 					{
-						apiKey,
+						apiKey: modelRegistry.resolver(model.provider, {
+							sessionId,
+							baseUrl: model.baseUrl,
+						}),
 						maxTokens: opts?.maxTokens,
 						temperature: opts?.temperature,
 					},

package/src/modes/acp/acp-agent.ts

@@ -1,3 +1,4 @@
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import {
 	type Agent,
@@ -62,7 +63,7 @@ import { MCPManager } from "../../mcp/manager";
 import type { MCPServerConfig } from "../../mcp/types";
 import { loadAllExtensions } from "../../modes/components/extensions/state-manager";
 import { theme } from "../../modes/theme/theme";
-import { type PlanApprovalDetails, renameApprovedPlanFile, resolvePlanTitle } from "../../plan-mode/approved-plan";
+import { type PlanApprovalDetails, resolveApprovedPlan } from "../../plan-mode/approved-plan";
 import type { AgentSession, AgentSessionEvent } from "../../session/agent-session";
 import { isSilentAbort, SKILL_PROMPT_MESSAGE_TYPE } from "../../session/messages";
 import {
@@ -1425,24 +1426,16 @@ export class AcpAgent implements Agent {
 				if (!state?.enabled) {
 					throw new ToolError("Plan mode is not active.");
 				}
-				const planFilePath = state.planFilePath;
-				const planContent = await this.#readAcpPlanFile(session, planFilePath);
-				if (planContent === null) {
-					throw new ToolError(
-						`Plan file not found at ${planFilePath}. Write the finalized plan to ${planFilePath} before requesting approval.`,
-					);
-				}
-				const normalized = resolvePlanTitle({
+				const { planFilePath, planContent, title } = await resolveApprovedPlan({
 					suppliedTitle: extra?.title,
-					planContent,
-					planFilePath,
+					statePlanFilePath: state.planFilePath,
+					readPlan: url => this.#readAcpPlanFile(session, url),
+					listPlanFiles: () => this.#listAcpLocalPlanFiles(session),
 				});
-				const finalPlanFilePath = `local://${normalized.fileName}`;
-				const approved = await this.#requestAcpPlanApprovalChoice(session.sessionId, normalized.title, planContent);
+				const approved = await this.#requestAcpPlanApprovalChoice(session.sessionId, title, planContent);
 				const details: PlanApprovalDetails = {
 					planFilePath,
-					finalPlanFilePath,
-					title: normalized.title,
+					title,
 					planExists: true,
 				};
 				if (!approved) {
@@ -1458,16 +1451,10 @@ export class AcpAgent implements Agent {
 						details,
 					};
 				}
-				// Approved. Rename plan to its titled filename, set the plan
-				// reference so the next turn injects the plan content as
-				// context, then exit plan mode so the agent regains full tools.
-				await renameApprovedPlanFile({
-					planFilePath,
-					finalPlanFilePath,
-					getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
-					getSessionId: () => session.sessionManager.getSessionId(),
-				});
-				session.setPlanReferencePath(finalPlanFilePath);
+				// Approved. Set the plan reference so the next turn injects the plan
+				// content as context (the file keeps its agent-chosen name — no
+				// rename), then exit plan mode so the agent regains full tools.
+				session.setPlanReferencePath(planFilePath);
 				session.setStandingResolveHandler?.(null);
 				session.setPlanModeState(undefined);
 				try {
@@ -1486,7 +1473,7 @@ export class AcpAgent implements Agent {
 					content: [
 						{
 							type: "text" as const,
-							text: `Plan approved at ${finalPlanFilePath}. Plan mode exited; proceed with the implementation.`,
+							text: `Plan approved at ${planFilePath}. Plan mode exited; proceed with the implementation.`,
 						},
 					],
 					details,
@@ -1518,6 +1505,26 @@ export class AcpAgent implements Agent {
 		}
 	}
 
+	/** `local://` URLs of plan files in the session-local root, newest first —
+	 *  the `resolveApprovedPlan` fallback for a dropped `extra.title`. */
+	async #listAcpLocalPlanFiles(session: AgentSession): Promise<string[]> {
+		const localRoot = this.#resolveAcpPlanFilePath(session, "local://");
+		try {
+			const entries = await fs.readdir(localRoot, { withFileTypes: true });
+			const plans = await Promise.all(
+				entries
+					.filter(entry => entry.isFile() && /plan\.md$/i.test(entry.name))
+					.map(async entry => {
+						const stat = await fs.stat(path.join(localRoot, entry.name)).catch(() => null);
+						return { url: `local://${entry.name}`, mtime: stat?.mtimeMs ?? 0 };
+					}),
+			);
+			return plans.sort((a, b) => b.mtime - a.mtime).map(plan => plan.url);
+		} catch {
+			return [];
+		}
+	}
+
 	/**
 	 * Ask the ACP client to confirm plan approval. Returns `true` only on an
 	 * explicit `APPROVE_OPTION` selection. Refine, dismissal (`undefined`), or

package/src/modes/components/assistant-message.ts

@@ -4,7 +4,7 @@ import { formatNumber } from "@oh-my-pi/pi-utils";
 import { settings } from "../../config/settings";
 import type { AssistantThinkingRenderer } from "../../extensibility/extensions/types";
 import { getMarkdownTheme, theme } from "../../modes/theme/theme";
-import { isSilentAbort } from "../../session/messages";
+import { isSilentAbort, resolveAbortLabel } from "../../session/messages";
 import { resolveImageOptions } from "../../tools/render-utils";
 
 /**
@@ -208,10 +208,6 @@ export class AssistantMessageComponent extends Container {
 			c => (c.type === "text" && c.text.trim()) || (c.type === "thinking" && c.thinking.trim()),
 		);
 
-		if (hasVisibleContent) {
-			this.#contentContainer.addChild(new Spacer(1));
-		}
-
 		// Render content in order
 		let thinkingIndex = 0;
 		for (let i = 0; i < message.content.length; i++) {
@@ -257,10 +253,7 @@ export class AssistantMessageComponent extends Container {
 		const hasToolCalls = message.content.some(c => c.type === "toolCall");
 		if (!hasToolCalls) {
 			if (message.stopReason === "aborted" && !isSilentAbort(message.errorMessage)) {
-				const abortMessage =
-					message.errorMessage && message.errorMessage !== "Request was aborted"
-						? message.errorMessage
-						: "Operation aborted";
+				const abortMessage = resolveAbortLabel(message.errorMessage);
 				if (hasVisibleContent) {
 					this.#contentContainer.addChild(new Spacer(1));
 				} else {

package/src/modes/components/chat-block.ts

@@ -0,0 +1,111 @@
+import { Container } from "@oh-my-pi/pi-tui";
+
+/**
+ * Capabilities a mounted {@link ChatBlock} may use against its host transcript.
+ * Kept minimal so blocks never reach into the full TUI/InteractiveMode surface.
+ */
+export interface ChatBlockHost {
+	/** Schedule a repaint of the transcript. */
+	requestRender(): void;
+}
+
+/**
+ * Lifecycle-aware transcript block — the "return a block, let the host mount it"
+ * primitive, modelled on React/Svelte component lifecycles.
+ *
+ * Producers build and return a `ChatBlock` instead of poking `chatContainer` and
+ * `ui.requestRender()` directly. The host (`ctx.present`) appends it and calls
+ * {@link mount}, which runs {@link onMount}; effects started there register
+ * teardown via {@link onCleanup}. The block repaints through {@link requestRender}
+ * — never touching the TUI — and tears down exactly once on {@link finish}
+ * (self-complete: stop the animation, keep the final frame in the transcript) or
+ * {@link dispose} (host discards it, e.g. a transcript reset).
+ *
+ * While mounted and unfinished a block reports `isTranscriptBlockFinalized() ===
+ * false` so {@link "../components/transcript-container".TranscriptContainer}
+ * keeps it in the live, repaintable region on ED3-risk terminals; after
+ * `finish()`/`dispose()` it reports `true` and freezes at its final content.
+ */
+export abstract class ChatBlock extends Container {
+	#host: ChatBlockHost | undefined;
+	#cleanups: Array<() => void> = [];
+	#active = false;
+	#disposed = false;
+
+	/**
+	 * Run setup after the block is in the transcript: start timers/subscriptions
+	 * and register their teardown with {@link onCleanup}. Default: no-op (a block
+	 * whose content is fixed at construction needs no mount work).
+	 */
+	protected onMount(): void {}
+
+	/**
+	 * Register a teardown to run on {@link finish}/{@link dispose}, à la a
+	 * `useEffect` cleanup. If the block is already disposed the cleanup runs
+	 * immediately so callers never leak.
+	 */
+	protected onCleanup(cleanup: () => void): void {
+		if (this.#disposed) {
+			cleanup();
+			return;
+		}
+		this.#cleanups.push(cleanup);
+	}
+
+	/** Ask the host to repaint. No-op before mount or after dispose. */
+	protected requestRender(): void {
+		this.#host?.requestRender();
+	}
+
+	/** True between {@link mount} and {@link finish}/{@link dispose}. */
+	protected get active(): boolean {
+		return this.#active;
+	}
+
+	/**
+	 * Host-only: attach the host and run {@link onMount}. Idempotent — a second
+	 * call (e.g. a transcript rebuild that re-presents the same instance) is a
+	 * no-op.
+	 */
+	mount(host: ChatBlockHost): void {
+		if (this.#host || this.#disposed) return;
+		this.#host = host;
+		this.#active = true;
+		this.onMount();
+	}
+
+	/**
+	 * Self-complete: stop ongoing effects and freeze the block at its current
+	 * content, leaving it rendered in the transcript. Use when the operation the
+	 * block represents finishes (connection resolved, download done).
+	 */
+	finish(): void {
+		if (!this.#active) return;
+		this.#active = false;
+		this.#runCleanups();
+		this.requestRender();
+	}
+
+	/**
+	 * Host-only teardown: release everything and propagate to children. Called
+	 * when the host permanently discards the block (transcript reset). Idempotent.
+	 */
+	override dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		this.#active = false;
+		this.#runCleanups();
+		super.dispose();
+		this.#host = undefined;
+	}
+
+	/** Live blocks stay repaintable; finished/disposed ones may freeze. */
+	isTranscriptBlockFinalized(): boolean {
+		return !this.#active;
+	}
+
+	#runCleanups(): void {
+		const cleanups = this.#cleanups.splice(0);
+		for (const cleanup of cleanups) cleanup();
+	}
+}

package/src/modes/components/copy-selector.ts

@@ -10,6 +10,7 @@ import {
 	matchesSelectUp,
 } from "../utils/keybinding-matchers";
 import { keyHint, rawKeyHint } from "./keybinding-hints";
+import { bottomBorder, divider, row, topBorder } from "./overlay-box";
 
 /** Minimum rows reserved for the tree even on short terminals. */
 const MIN_TREE_ROWS = 3;
@@ -32,50 +33,6 @@ interface FlatNode {
 	ancestorHasNext: boolean[];
 }
 
-/** Pad or truncate a (possibly ANSI-styled) string to exactly `width` columns. */
-function fit(text: string, width: number): string {
-	if (width <= 0) return "";
-	const w = visibleWidth(text);
-	if (w === width) return text;
-	if (w < width) return text + padding(width - w);
-	const cut = truncateToWidth(text, width);
-	const cw = visibleWidth(cut);
-	return cw < width ? cut + padding(width - cw) : cut;
-}
-
-function paint(s: string): string {
-	return theme.fg("border", s);
-}
-
-function topBorder(width: number, title: string): string {
-	const box = theme.boxSharp;
-	const inner = Math.max(0, width - 2);
-	if (!title) return paint(box.topLeft + box.horizontal.repeat(inner) + box.topRight);
-	const shown = truncateToWidth(` ${title} `, Math.max(0, inner - 2));
-	const fillWidth = Math.max(0, inner - 1 - visibleWidth(shown));
-	return (
-		paint(box.topLeft + box.horizontal) +
-		theme.bold(theme.fg("accent", shown)) +
-		paint(box.horizontal.repeat(fillWidth) + box.topRight)
-	);
-}
-
-function divider(width: number): string {
-	const box = theme.boxSharp;
-	return paint(box.teeRight + box.horizontal.repeat(Math.max(0, width - 2)) + box.teeLeft);
-}
-
-function bottomBorder(width: number): string {
-	const box = theme.boxSharp;
-	return paint(box.bottomLeft + box.horizontal.repeat(Math.max(0, width - 2)) + box.bottomRight);
-}
-
-/** Wrap pre-styled content in vertical borders with single-column insets. */
-function row(content: string, width: number): string {
-	const box = theme.boxSharp;
-	return `${paint(box.vertical)} ${fit(content, Math.max(0, width - 4))} ${paint(box.vertical)}`;
-}
-
 /** Render one tree connector as exactly three cells (e.g. "├─ ", "└─ ", "|--"). */
 function connectorCells(symbol: string): string {
 	const chars = Array.from(symbol);

package/src/modes/components/custom-editor.ts

@@ -47,6 +47,21 @@ const DEFAULT_ACTION_KEYS: Record<ConfigurableEditorAction, KeyId[]> = {
 	"app.clipboard.copyPrompt": ["alt+shift+c"],
 };
 
+const BRACKETED_PASTE_START = "\x1b[200~";
+const BRACKETED_PASTE_END = "\x1b[201~";
+const BRACKETED_IMAGE_PATH_REGEX = /\.(?:png|jpe?g|gif|webp)$/i;
+
+export function extractBracketedImagePastePath(data: string): string | undefined {
+	if (!data.startsWith(BRACKETED_PASTE_START)) return undefined;
+	const endIndex = data.indexOf(BRACKETED_PASTE_END, BRACKETED_PASTE_START.length);
+	if (endIndex === -1 || endIndex + BRACKETED_PASTE_END.length !== data.length) return undefined;
+
+	const pasted = data.slice(BRACKETED_PASTE_START.length, endIndex).trim();
+	if (!pasted || /[\r\n]/.test(pasted)) return undefined;
+	if (!BRACKETED_IMAGE_PATH_REGEX.test(pasted)) return undefined;
+	return pasted;
+}
+
 /**
  * Custom editor that handles configurable app-level shortcuts for coding-agent.
  */
@@ -82,6 +97,8 @@ export class CustomEditor extends Editor {
 	onCopyPrompt?: () => void;
 	/** Called when the configured image-paste shortcut is pressed. */
 	onPasteImage?: () => Promise<boolean>;
+	/** Called when a bracketed paste contains exactly one image-file path. */
+	onPasteImagePath?: (path: string) => void;
 	/** Called when the configured raw text-paste shortcut is pressed. */
 	onPasteTextRaw?: () => void;
 	/** Called when the configured dequeue shortcut is pressed. */
@@ -137,6 +154,12 @@ export class CustomEditor extends Editor {
 			return;
 		}
 
+		const pastedImagePath = extractBracketedImagePastePath(data);
+		if (pastedImagePath && this.onPasteImagePath) {
+			this.onPasteImagePath(pastedImagePath);
+			return;
+		}
+
 		// Intercept configured image paste (async - fires and handles result)
 		if (this.#matchesAction(data, "app.clipboard.pasteImage") && this.onPasteImage) {
 			void this.onPasteImage();

package/src/modes/components/custom-message.ts

@@ -1,5 +1,5 @@
 import type { Component } from "@oh-my-pi/pi-tui";
-import { Box, Container, Spacer } from "@oh-my-pi/pi-tui";
+import { Box, Container } from "@oh-my-pi/pi-tui";
 import type { MessageRenderer } from "../../extensibility/extensions/types";
 import { theme } from "../../modes/theme/theme";
 import type { CustomMessage } from "../../session/messages";
@@ -20,8 +20,6 @@ export class CustomMessageComponent extends Container {
 	) {
 		super();
 
-		this.addChild(new Spacer(1));
-
 		// Create box with custom background (used for default rendering)
 		this.#box = new Box(1, 1, t => theme.bg("customMessageBg", t));
 

package/src/modes/components/execution-shared.ts

@@ -7,7 +7,7 @@
  * stay in their respective files.
  */
 
-import { type Component, Container, Loader, Spacer, Text, type TUI } from "@oh-my-pi/pi-tui";
+import { type Component, Container, Loader, Text, type TUI } from "@oh-my-pi/pi-tui";
 import { getSymbolTheme, theme } from "../../modes/theme/theme";
 import { formatTruncationMetaNotice, type TruncationMeta } from "../../tools/output-meta";
 import { DynamicBorder } from "./dynamic-border";
@@ -31,7 +31,6 @@ export function buildExecutionFrame(
 ): { contentContainer: Container; loader: Loader } {
 	const borderColor = (str: string) => theme.fg(colorKey, str);
 
-	parent.addChild(new Spacer(1));
 	parent.addChild(new DynamicBorder(borderColor));
 
 	const contentContainer = new Container();

package/src/modes/components/hook-message.ts

@@ -1,5 +1,5 @@
 import type { Component } from "@oh-my-pi/pi-tui";
-import { Box, Container, Spacer } from "@oh-my-pi/pi-tui";
+import { Box, Container } from "@oh-my-pi/pi-tui";
 import type { HookMessageRenderer } from "../../extensibility/hooks/types";
 import { theme } from "../../modes/theme/theme";
 import type { HookMessage } from "../../session/messages";
@@ -23,8 +23,6 @@ export class HookMessageComponent extends Container {
 	) {
 		super();
 
-		this.addChild(new Spacer(1));
-
 		// Create box with purple background (used for default rendering)
 		this.#box = new Box(1, 1, t => theme.bg("customMessageBg", t));
 

package/src/modes/components/overlay-box.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared box-drawing chrome for fullscreen overlays (the `/copy` picker, the
+ * plan-review overlay, …). Every helper paints with `theme.boxSharp` glyphs and
+ * the `border`/`accent` theme colors so all outlined overlays read identically.
+ */
+import { padding, truncateToWidth, visibleWidth } from "@oh-my-pi/pi-tui";
+import { theme } from "../theme/theme";
+
+/** Pad or truncate a (possibly ANSI-styled) string to exactly `width` columns. */
+export function fit(text: string, width: number): string {
+	if (width <= 0) return "";
+	const w = visibleWidth(text);
+	if (w === width) return text;
+	if (w < width) return text + padding(width - w);
+	const cut = truncateToWidth(text, width);
+	const cw = visibleWidth(cut);
+	return cw < width ? cut + padding(width - cw) : cut;
+}
+
+function paint(s: string): string {
+	return theme.fg("border", s);
+}
+
+/** Top border with an optional accent-colored title inset into the rule. */
+export function topBorder(width: number, title: string): string {
+	const box = theme.boxSharp;
+	const inner = Math.max(0, width - 2);
+	if (!title) return paint(box.topLeft + box.horizontal.repeat(inner) + box.topRight);
+	const shown = truncateToWidth(` ${title} `, Math.max(0, inner - 2));
+	const fillWidth = Math.max(0, inner - 1 - visibleWidth(shown));
+	return (
+		paint(box.topLeft + box.horizontal) +
+		theme.bold(theme.fg("accent", shown)) +
+		paint(box.horizontal.repeat(fillWidth) + box.topRight)
+	);
+}
+
+/** A horizontal rule with left/right tees, splitting overlay sections. */
+export function divider(width: number): string {
+	const box = theme.boxSharp;
+	return paint(box.teeRight + box.horizontal.repeat(Math.max(0, width - 2)) + box.teeLeft);
+}
+
+export function bottomBorder(width: number): string {
+	const box = theme.boxSharp;
+	return paint(box.bottomLeft + box.horizontal.repeat(Math.max(0, width - 2)) + box.bottomRight);
+}
+
+/** Wrap pre-styled content in vertical borders with single-column insets. */
+export function row(content: string, width: number): string {
+	const box = theme.boxSharp;
+	return `${paint(box.vertical)} ${fit(content, Math.max(0, width - 4))} ${paint(box.vertical)}`;
+}
+
+/**
+ * Column index (0-based) of the inner divider for a two-column layout whose
+ * sidebar content area is `sidebarWidth` columns wide. The layout is
+ * `│ sidebar │ body │` with a single-column inset on every side, so the divider
+ * vertical sits at `sidebarWidth + 3` and the body content area is
+ * {@link splitBodyWidth} columns.
+ */
+function splitDividerCol(sidebarWidth: number): number {
+	return sidebarWidth + 3;
+}
+
+/** Body content width for a two-column overlay of total `width`. */
+export function splitBodyWidth(width: number, sidebarWidth: number): number {
+	return Math.max(0, width - sidebarWidth - 7);
+}
+
+/** Top border carrying the title, split by a `┬` over the column divider. */
+export function topBorderSplit(width: number, title: string, sidebarWidth: number): string {
+	const box = theme.boxSharp;
+	const dividerCol = splitDividerCol(sidebarWidth);
+	const leftLen = Math.max(0, dividerCol - 1);
+	const rightLen = Math.max(0, width - 2 - dividerCol);
+	let left: string;
+	if (!title) {
+		left = paint(box.topLeft + box.horizontal.repeat(leftLen));
+	} else {
+		const shown = truncateToWidth(` ${title} `, Math.max(0, leftLen - 1));
+		const fillWidth = Math.max(0, leftLen - 1 - visibleWidth(shown));
+		left =
+			paint(box.topLeft + box.horizontal) +
+			theme.bold(theme.fg("accent", shown)) +
+			paint(box.horizontal.repeat(fillWidth));
+	}
+	return left + paint(box.teeDown + box.horizontal.repeat(rightLen) + box.topRight);
+}
+
+/** Section rule that closes the sidebar column with a `┴` over the divider. */
+export function dividerSplit(width: number, sidebarWidth: number): string {
+	const box = theme.boxSharp;
+	const dividerCol = splitDividerCol(sidebarWidth);
+	const leftLen = Math.max(0, dividerCol - 1);
+	const rightLen = Math.max(0, width - 2 - dividerCol);
+	return paint(
+		box.teeRight + box.horizontal.repeat(leftLen) + box.teeUp + box.horizontal.repeat(rightLen) + box.teeLeft,
+	);
+}
+
+/** A two-column content row: `│ sidebar │ body │`, each inset by one column. */
+export function splitRow(sidebar: string, body: string, width: number, sidebarWidth: number): string {
+	const box = theme.boxSharp;
+	const bodyWidth = splitBodyWidth(width, sidebarWidth);
+	const bar = paint(box.vertical);
+	return `${bar} ${fit(sidebar, sidebarWidth)} ${bar} ${fit(body, bodyWidth)} ${bar}`;
+}