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

package/src/memory-backend/types.ts

@@ -1,7 +1,7 @@
 /**
  * Memory backend abstraction.
  *
- * Backends are mutually exclusive — `await resolveMemoryBackend(settings)` resolves
+ * Backends are mutually exclusive — `await resolveMemoryBackend(settings)` returns
  * exactly one. Implementations MUST be self-contained: they own the per-session
  * state they create in `start()` and tear it down on `clear()`.
  */
@@ -15,6 +15,73 @@ import type { AgentSession } from "../session/agent-session";
 
 export type MemoryBackendId = "off" | "local" | "hindsight" | "mnemopi";
 
+export interface MemoryBackendStatus {
+	backend: MemoryBackendId;
+	active: boolean;
+	writable: boolean;
+	searchable: boolean;
+	scope?: string;
+	retainBank?: string;
+	recallBanks?: string[];
+	workingCount?: number;
+	episodicCount?: number;
+	tripleCount?: number;
+	lastMemory?: string;
+	lastRecall?: boolean;
+	database?: string;
+	message?: string;
+	error?: string;
+}
+
+export interface MemoryBackendSearchOptions {
+	limit?: number;
+	/** Best-effort abort signal. Backends may only observe it before/after an underlying recall call. */
+	signal?: AbortSignal;
+}
+
+export interface MemoryBackendSearchItem {
+	id?: string;
+	content: string;
+	source?: string;
+	timestamp?: string;
+	score?: number;
+}
+
+export interface MemoryBackendSearchResult {
+	backend: MemoryBackendId;
+	query: string;
+	count: number;
+	items: MemoryBackendSearchItem[];
+	message?: string;
+}
+
+export interface MemoryBackendSaveInput {
+	content: string;
+	context?: string;
+	source?: string;
+	importance?: number;
+}
+
+export interface MemoryBackendSaveResult {
+	backend: MemoryBackendId;
+	stored: number;
+	ids?: string[];
+	queued?: boolean;
+	message?: string;
+}
+
+export interface MemoryBackendOperationContext {
+	agentDir: string;
+	cwd: string;
+	session?: AgentSession;
+}
+
+export interface MemoryRuntimeContext {
+	status(): Promise<MemoryBackendStatus>;
+	search(query: string, options?: MemoryBackendSearchOptions): Promise<MemoryBackendSearchResult>;
+	save(input: string | MemoryBackendSaveInput): Promise<MemoryBackendSaveResult>;
+}
+
 export interface MemoryBackendStartOptions {
 	session: AgentSession;
 	settings: Settings;
@@ -53,6 +120,19 @@ export interface MemoryBackend {
 	/** Force consolidation/retain to happen now (slash `/memory enqueue`). */
 	enqueue(agentDir: string, cwd: string, session?: AgentSession): Promise<void>;
 
+	/** Structured state for UI, slash commands, and extensions. */
+	status?(context: MemoryBackendOperationContext): Promise<MemoryBackendStatus>;
+
+	/** Explicit user-facing semantic/lexical search. */
+	search?(
+		context: MemoryBackendOperationContext,
+		query: string,
+		options?: MemoryBackendSearchOptions,
+	): Promise<MemoryBackendSearchResult>;
+
+	/** Explicit user-facing save operation. */
+	save?(context: MemoryBackendOperationContext, input: MemoryBackendSaveInput): Promise<MemoryBackendSaveResult>;
+
 	/** Render backend-specific memory statistics as markdown (`/memory stats`). */
 	stats?(agentDir: string, cwd: string, session?: AgentSession): Promise<string | undefined>;
 

package/src/mnemopi/backend.ts

@@ -1,14 +1,19 @@
 import { rm } from "node:fs/promises";
 import * as path from "node:path";
 import { completeSimple } from "@oh-my-pi/pi-ai";
-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 type { Mnemopi } from "@oh-my-pi/pi-mnemopi";
+import type * as MnemopiDiagnoseNs from "@oh-my-pi/pi-mnemopi/diagnose";
+import type { DiagnosticSummary } 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";
+import type {
+	MemoryBackend,
+	MemoryBackendSaveInput,
+	MemoryBackendSearchItem,
+	MemoryBackendStartOptions,
+	MemoryBackendStatus,
+} from "../memory-backend/types";
 import memoryConsolidationPrompt from "../prompts/system/memory-consolidation-system.md" with { type: "text" };
 import memoryExtractionPrompt from "../prompts/system/memory-extraction-system.md" with { type: "text" };
 import type { AgentSession } from "../session/agent-session";
@@ -25,10 +30,25 @@ import {
 	getMnemopiScopedBanks,
 	getMnemopiScopedDbPaths,
 	getMnemopiSessionState,
+	loadMnemopi,
+	loadMnemopiCore,
 	MnemopiSessionState,
+	requireMnemopi,
+	requireMnemopiCore,
 	setMnemopiSessionState,
 } from "./state";
 
+// `/diagnose` is the only user of this subpath; load it lazily alongside the
+// loaders in ./state to keep mnemopi off the CLI startup module graph.
+let mnemopiDiagnoseMod: typeof MnemopiDiagnoseNs | undefined;
+
+async function loadMnemopiDiagnose(): Promise<typeof MnemopiDiagnoseNs> {
+	if (!mnemopiDiagnoseMod) {
+		mnemopiDiagnoseMod = await import("@oh-my-pi/pi-mnemopi/diagnose");
+	}
+	return mnemopiDiagnoseMod;
+}
+
 const STATIC_INSTRUCTIONS = [
 	"# Memory",
 	"This agent has local Mnemopi long-term memory.",
@@ -68,6 +88,7 @@ export const mnemopiBackend: MemoryBackend = {
 
 		try {
 			const config = await loadMnemopiConfigWithProviders(settings, agentDir, modelRegistry, sessionId);
+			await Promise.all([loadMnemopi(), loadMnemopiCore()]);
 			const state = new MnemopiSessionState({ sessionId, config, session });
 			const previous = setMnemopiSessionState(session, state);
 			previous?.dispose();
@@ -97,6 +118,7 @@ export const mnemopiBackend: MemoryBackend = {
 		previous?.dispose();
 		const config = previous?.config ?? (session ? loadMnemopiConfig(session.settings, agentDir) : undefined);
 		if (!config) return;
+		await loadMnemopiCore();
 		await removeDbFiles(getMnemopiScopedDbPaths(config));
 	},
 
@@ -110,6 +132,7 @@ export const mnemopiBackend: MemoryBackend = {
 					session.modelRegistry,
 					session.sessionId,
 				);
+				await Promise.all([loadMnemopi(), loadMnemopiCore()]);
 				state = new MnemopiSessionState({ sessionId: session.sessionId, config, session });
 				setMnemopiSessionState(session, state);
 			}
@@ -124,6 +147,7 @@ export const mnemopiBackend: MemoryBackend = {
 	},
 
 	async stats(agentDir, _cwd, session): Promise<string | undefined> {
+		await Promise.all([loadMnemopi(), loadMnemopiCore()]);
 		const { targets, owned } = createStatsTargets(agentDir, session);
 		try {
 			if (targets.length === 0) return undefined;
@@ -137,6 +161,7 @@ export const mnemopiBackend: MemoryBackend = {
 		const state = getMnemopiSessionState(session);
 		const config = state?.config ?? (session ? loadMnemopiConfig(session.settings, agentDir) : undefined);
 		if (!config) return undefined;
+		const [{ inspectDatabase }] = await Promise.all([loadMnemopiDiagnose(), loadMnemopiCore()]);
 		const banks = getMnemopiScopedBanks(config);
 		const dbPaths = getMnemopiScopedDbPaths(config);
 		const summaries = dbPaths.map((dbPath, index) => ({
@@ -146,6 +171,101 @@ export const mnemopiBackend: MemoryBackend = {
 		return renderMnemopiDiagnostics(summaries);
 	},
 
+	async status({ agentDir, session }): Promise<MemoryBackendStatus> {
+		const state = getMnemopiSessionState(session);
+		const primary = state?.aliasOf ?? state;
+		if (!primary) {
+			return {
+				backend: "mnemopi",
+				active: false,
+				writable: false,
+				searchable: false,
+				message: "Mnemopi backend is not initialised for this session.",
+			};
+		}
+
+		const { targets, owned } = createStatsTargets(agentDir, session);
+		try {
+			if (targets.length === 0) {
+				return {
+					backend: "mnemopi",
+					active: false,
+					writable: false,
+					searchable: false,
+					message: "Mnemopi backend is configured but not initialised for this session.",
+				};
+			}
+			return summarizeMnemopiStatus(targets, session);
+		} finally {
+			for (const memory of owned) memory.close();
+		}
+	},
+
+	async search({ session }, query, options) {
+		const state = getMnemopiSessionState(session);
+		const primary = state?.aliasOf ?? state;
+		if (!primary) {
+			return {
+				backend: "mnemopi",
+				query,
+				count: 0,
+				items: [],
+				message: "Mnemopi backend is not initialised for this session.",
+			};
+		}
+		if (options?.signal?.aborted) {
+			return { backend: "mnemopi", query, count: 0, items: [], message: "Search aborted." };
+		}
+		const limit = clampLimit(options?.limit);
+		const results = (await primary.recallResultsScoped(query)).slice(0, limit);
+		if (options?.signal?.aborted) {
+			return { backend: "mnemopi", query, count: 0, items: [], message: "Search aborted." };
+		}
+		const items: MemoryBackendSearchItem[] = results.map(result => ({
+			id: result.id,
+			content: result.content,
+			source: result.source ?? undefined,
+			timestamp: result.timestamp ?? undefined,
+			score: result.score,
+		}));
+		return { backend: "mnemopi", query, count: items.length, items };
+	},
+
+	async save({ cwd, session }, input: MemoryBackendSaveInput) {
+		const state = getMnemopiSessionState(session);
+		const primary = state?.aliasOf ?? state;
+		if (!primary) {
+			return {
+				backend: "mnemopi",
+				stored: 0,
+				message: "Mnemopi backend is not initialised for this session.",
+			};
+		}
+		const content = input.content.trim();
+		if (!content) return { backend: "mnemopi", stored: 0, message: "Memory content is empty." };
+		const id = primary.rememberScoped(content, {
+			source: input.source || "coding-agent-memory-command",
+			importance: normalizeImportance(input.importance),
+			metadata: {
+				session_id: primary.sessionId,
+				cwd,
+				context: input.context ?? null,
+				operation: "memory.save",
+			},
+			scope: "bank",
+			extract: true,
+			extractEntities: true,
+			veracity: "user",
+			memoryType: "fact",
+		});
+		return {
+			backend: "mnemopi",
+			stored: id ? 1 : 0,
+			ids: id ? [id] : [],
+			message: id ? undefined : "Mnemopi did not return a stored memory id.",
+		};
+	},
+
 	async preCompactionContext(messages, _settings, session): Promise<string | undefined> {
 		const state = getMnemopiSessionState(session);
 		return await state?.recallForCompaction(messages);
@@ -179,6 +299,7 @@ function createStatsTargets(
 
 function createStatsMemory(config: MnemopiBackendConfig, bank: string): Mnemopi {
 	const providerOptions = config.providerOptions as Record<string, unknown>;
+	const { Mnemopi } = requireMnemopi();
 	return new Mnemopi({
 		dbPath: resolveBankDbPath(config, bank),
 		bank,
@@ -193,6 +314,7 @@ function createStatsMemory(config: MnemopiBackendConfig, bank: string): Mnemopi
 function resolveBankDbPath(config: MnemopiBackendConfig, bank: string): string {
 	const sharedBank = config.globalBank ?? config.baseBank ?? "default";
 	if (bank === sharedBank) return config.dbPath;
+	const { BankManager } = requireMnemopiCore();
 	return new BankManager(path.dirname(config.dbPath)).getBankDbPath(bank);
 }
 
@@ -225,6 +347,52 @@ function renderMnemopiStats(targets: readonly MnemopiStatsTarget[]): string {
 	return lines.join("\n");
 }
 
+function summarizeMnemopiStatus(
+	targets: readonly MnemopiStatsTarget[],
+	session: AgentSession | undefined,
+): MemoryBackendStatus {
+	let workingCount = 0;
+	let episodicCount = 0;
+	let tripleCount = 0;
+	let lastMemory: string | undefined;
+	let database: string | undefined;
+	for (const target of targets) {
+		const stats = target.memory.getStats();
+		workingCount += statCount(stats.beam.working_memory);
+		episodicCount += statCount(stats.beam.episodic_memory);
+		tripleCount += stats.beam.triples.total;
+		lastMemory ??= stats.last_memory ?? undefined;
+		database ??= stats.database ? shortenPath(stats.database) : undefined;
+	}
+	const state = getMnemopiSessionState(session);
+	const primary = state?.aliasOf ?? state;
+	return {
+		backend: "mnemopi",
+		active: true,
+		writable: true,
+		searchable: true,
+		scope: primary?.config.scoping,
+		retainBank: primary?.getScopedRetainTarget().bank ?? targets[0]?.bank,
+		recallBanks: primary?.getScopedRecallTargets().map(target => target.bank) ?? targets.map(target => target.bank),
+		workingCount,
+		episodicCount,
+		tripleCount,
+		lastMemory,
+		lastRecall: Boolean(primary?.lastRecallSnippet),
+		database,
+	};
+}
+
+function clampLimit(limit: number | undefined): number {
+	if (!Number.isFinite(limit)) return 10;
+	return Math.max(1, Math.min(50, Math.trunc(limit ?? 10)));
+}
+
+function normalizeImportance(value: number | undefined): number {
+	if (!Number.isFinite(value)) return 0.75;
+	return Math.max(0, Math.min(1, value ?? 0.75));
+}
+
 function renderMnemopiDiagnostics(entries: readonly { bank: string; summary: DiagnosticSummary }[]): string {
 	const lines = [
 		"# Mnemopi Memory Diagnostics",
@@ -321,8 +489,8 @@ async function resolveMnemopiProviderOptions(
 		return {
 			...base,
 			llm: async (prompt, opts) => {
-				const apiKey = await modelRegistry.getApiKey(model, sessionId);
-				if (!apiKey) {
+				const hasApiKey = await modelRegistry.getApiKey(model, sessionId);
+				if (!hasApiKey) {
 					logger.warn("Mnemopi: smol completion requested but no current API key is available.", {
 						provider: model.provider,
 						model: model.id,
@@ -338,6 +506,7 @@ async function resolveMnemopiProviderOptions(
 						apiKey: modelRegistry.resolver(model.provider, {
 							sessionId,
 							baseUrl: model.baseUrl,
+							modelId: model.id,
 						}),
 						maxTokens: opts?.maxTokens,
 						temperature: opts?.temperature,

package/src/mnemopi/state.ts

@@ -1,7 +1,8 @@
 import { dirname } from "node:path";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
-import { Mnemopi, type RecallResult } from "@oh-my-pi/pi-mnemopi";
-import { BankManager } from "@oh-my-pi/pi-mnemopi/core";
+import type * as MnemopiNs from "@oh-my-pi/pi-mnemopi";
+import type { Mnemopi, RecallResult } from "@oh-my-pi/pi-mnemopi";
+import type * as MnemopiCoreNs from "@oh-my-pi/pi-mnemopi/core";
 import { logger } from "@oh-my-pi/pi-utils";
 import {
 	composeRecallQuery,
@@ -13,6 +14,39 @@ import { extractMessages } from "../hindsight/transcript";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import type { MnemopiBackendConfig, MnemopiScoping } from "./config";
 
+// The mnemopi package pulls the embeddings stack; keep it off the CLI startup
+// module graph by loading it lazily at the async boundaries that need it.
+let mnemopiMod: typeof MnemopiNs | undefined;
+let mnemopiCoreMod: typeof MnemopiCoreNs | undefined;
+
+/** Lazily load `@oh-my-pi/pi-mnemopi` (memoized). */
+export async function loadMnemopi(): Promise<typeof MnemopiNs> {
+	if (!mnemopiMod) {
+		mnemopiMod = await import("@oh-my-pi/pi-mnemopi");
+	}
+	return mnemopiMod;
+}
+
+/** Lazily load `@oh-my-pi/pi-mnemopi/core` (memoized). */
+export async function loadMnemopiCore(): Promise<typeof MnemopiCoreNs> {
+	if (!mnemopiCoreMod) {
+		mnemopiCoreMod = await import("@oh-my-pi/pi-mnemopi/core");
+	}
+	return mnemopiCoreMod;
+}
+
+/** Sync access for code below an async boundary that already awaited {@link loadMnemopi}. */
+export function requireMnemopi(): typeof MnemopiNs {
+	if (!mnemopiMod) throw new Error("Mnemopi module not loaded; await loadMnemopi() first.");
+	return mnemopiMod;
+}
+
+/** Sync access for code below an async boundary that already awaited {@link loadMnemopiCore}. */
+export function requireMnemopiCore(): typeof MnemopiCoreNs {
+	if (!mnemopiCoreMod) throw new Error("Mnemopi core module not loaded; await loadMnemopiCore() first.");
+	return mnemopiCoreMod;
+}
+
 const kMnemopiSessionState = Symbol("mnemopi.sessionState");
 
 interface AgentSessionWithMnemopiState extends AgentSession {
@@ -460,6 +494,7 @@ function escapeRegExp(text: string): string {
 }
 function createMemory(config: MnemopiBackendConfig, bank: string): Mnemopi {
 	const providerOptions = config.providerOptions as Record<string, unknown>;
+	const { Mnemopi } = requireMnemopi();
 	return new Mnemopi({
 		dbPath: resolveBankDbPath(config, bank),
 		bank,
@@ -474,6 +509,7 @@ function createMemory(config: MnemopiBackendConfig, bank: string): Mnemopi {
 function resolveBankDbPath(config: MnemopiBackendConfig, bank: string): string {
 	const sharedBank = config.globalBank ?? config.baseBank ?? "default";
 	if (bank === sharedBank) return config.dbPath;
+	const { BankManager } = requireMnemopiCore();
 	return new BankManager(dirname(config.dbPath)).getBankDbPath(bank);
 }
 

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

@@ -71,7 +71,12 @@ import {
 	type SessionInfo as StoredSessionInfo,
 	type UsageStatistics,
 } from "../../session/session-manager";
-import { ACP_BUILTIN_SLASH_COMMANDS, executeAcpBuiltinSlashCommand } from "../../slash-commands/acp-builtins";
+import {
+	ACP_BUILTIN_RESERVED_NAMES,
+	ACP_BUILTIN_SLASH_COMMANDS,
+	executeAcpBuiltinSlashCommand,
+	isAcpBuiltinShadowedName,
+} from "../../slash-commands/acp-builtins";
 import { AUTO_THINKING, parseConfiguredThinkingLevel } from "../../thinking";
 import { normalizeLocalScheme } from "../../tools/path-utils";
 import { runResolveInvocation } from "../../tools/resolve";
@@ -117,6 +122,7 @@ type PromptQueueState = {
 	promise: Promise<void>;
 	release: (() => void) | undefined;
 };
+type PromptLifecycleError = Error & { readonly code: "ACP_SESSION_CLOSED" };
 
 type PromptTurnState = {
 	userMessageId: string;
@@ -158,6 +164,9 @@ type ManagedSessionRecord = {
 	// Installed inside `#scheduleBootstrapUpdates` (post-race-guard); released
 	// in `#disposeSessionRecord`. Lives independent of any prompt turn.
 	lifetimeUnsubscribe: (() => void) | undefined;
+	closedError: PromptLifecycleError | undefined;
+	promptEventHandlers: Set<Promise<void>>;
+	extensionUserMessageTasks: Set<Promise<void>>;
 };
 
 type ReplayableMessage = {
@@ -594,7 +603,23 @@ export class AcpAgent implements Agent {
 		const record = this.#getSessionRecord(params.sessionId);
 		const activeTurn = record.promptTurn;
 		if (activeTurn && !activeTurn.settled && record.session.isStreaming) {
-			throw new Error("ACP prompt already in progress for this session");
+			// New prompt arrived while the previous turn is still in-flight (e.g. the
+			// client sent a message immediately after pressing stop, before or without
+			// a preceding session/cancel notification). Implicitly cancel the running
+			// turn so the new prompt can queue behind the abort cleanup — identical to
+			// what cancel() does when called explicitly. #beginCancelCleanup is
+			// idempotent, so a concurrent session/cancel notification is harmless.
+			// Mirror cancel()'s timeout handling: if abort() hangs past the cleanup
+			// timeout, close the managed session instead of leaving it registered
+			// with a still-streaming AgentSession. The queued prompt below observes
+			// the same cleanup rejection and fails accordingly.
+			this.#beginCancelCleanup(record, activeTurn).catch(async (error: unknown) => {
+				logger.warn("ACP cancel cleanup timed out; closing session", {
+					sessionId: record.session.sessionId,
+					error,
+				});
+				await this.#closeManagedSession(params.sessionId, record);
+			});
 		}
 		return await this.#queuePrompt(record, async () => {
 			const previousTurn = record.promptTurn;
@@ -607,6 +632,7 @@ export class AcpAgent implements Agent {
 				await previousTurn.promise.catch(() => undefined);
 				await previousTurn.cleanup;
 			}
+			this.#throwIfRecordClosed(record);
 
 			const converted = this.#convertPromptBlocks(params.prompt);
 			const pendingPrompt = Promise.withResolvers<PromptResponse>();
@@ -623,7 +649,7 @@ export class AcpAgent implements Agent {
 			};
 
 			record.promptTurn.unsubscribe = record.session.subscribe(event => {
-				void this.#handlePromptEvent(record, event);
+				this.#trackPromptEvent(record, event);
 			});
 
 			this.#runPromptOrCommand(record, converted.text, converted.images).catch((error: unknown) => {
@@ -643,6 +669,7 @@ export class AcpAgent implements Agent {
 			release: releaseQueue,
 		};
 		await previousQueue.promise;
+		this.#throwIfRecordClosed(record);
 		try {
 			return await run();
 		} finally {
@@ -653,6 +680,55 @@ export class AcpAgent implements Agent {
 		}
 	}
 
+	#throwIfRecordClosed(record: ManagedSessionRecord): void {
+		if (record.closedError) {
+			throw record.closedError;
+		}
+	}
+
+	#createPromptLifecycleError(message: string): PromptLifecycleError {
+		return Object.assign(new Error(message), { code: "ACP_SESSION_CLOSED" as const });
+	}
+
+	#trackPromptEvent(record: ManagedSessionRecord, event: AgentSessionEvent): void {
+		const handling = this.#handlePromptEvent(record, event).catch((error: unknown) => {
+			logger.warn("ACP prompt event handler failed", { error });
+		});
+		record.promptEventHandlers.add(handling);
+		void handling.finally(() => {
+			record.promptEventHandlers.delete(handling);
+		});
+	}
+
+	async #waitForPromptEventHandlers(record: ManagedSessionRecord): Promise<void> {
+		while (record.promptEventHandlers.size > 0) {
+			await Promise.allSettled(Array.from(record.promptEventHandlers));
+		}
+	}
+
+	#trackExtensionUserMessage(record: ManagedSessionRecord, task: Promise<void>): void {
+		const tracked = task.catch((error: unknown) => {
+			logger.warn("ACP extension sendUserMessage failed", { error });
+		});
+		record.extensionUserMessageTasks.add(tracked);
+		void tracked.finally(() => {
+			record.extensionUserMessageTasks.delete(tracked);
+		});
+	}
+
+	async #waitForExtensionUserMessages(
+		record: ManagedSessionRecord,
+		baseline: ReadonlySet<Promise<void>>,
+	): Promise<void> {
+		while (true) {
+			const pending = Array.from(record.extensionUserMessageTasks).filter(task => !baseline.has(task));
+			if (pending.length === 0) {
+				return;
+			}
+			await Promise.allSettled(pending);
+		}
+	}
+
 	async #runPromptOrCommand(record: ManagedSessionRecord, text: string, images: AgentImageContent[]): Promise<void> {
 		const skillResult = await this.#tryRunSkillCommand(record, text);
 		if (skillResult) {
@@ -699,7 +775,18 @@ export class AcpAgent implements Agent {
 			return;
 		}
 
-		await record.session.prompt(text, { images });
+		const extensionPromptBaseline = new Set(record.extensionUserMessageTasks);
+		const agentInvoked = await record.session.prompt(text, { images });
+		// Extension and custom-TS commands are handled locally inside session.prompt().
+		// An ACP extension command can still call pi.sendUserMessage(), which starts
+		// an async nested prompt through the extension runtime. Keep the ACP turn
+		// subscribed until those scheduled prompts and their event handlers drain;
+		// only then is `false` proof that the slash command was purely local.
+		if (!agentInvoked) {
+			await this.#waitForExtensionUserMessages(record, extensionPromptBaseline);
+			await this.#waitForPromptEventHandlers(record);
+			this.#finishPrompt(record, { stopReason: "end_turn" });
+		}
 	}
 
 	async #tryRunSkillCommand(record: ManagedSessionRecord, text: string): Promise<boolean> {
@@ -991,6 +1078,9 @@ export class AcpAgent implements Agent {
 			liveMessageProgress: undefined,
 			toolArgsById: new Map(),
 			extensionsConfigured: false,
+			closedError: undefined,
+			promptEventHandlers: new Set(),
+			extensionUserMessageTasks: new Set(),
 			lifetimeUnsubscribe: undefined,
 		};
 	}
@@ -1582,10 +1672,12 @@ export class AcpAgent implements Agent {
 			commands.push(command);
 		};
 
-		// Advertise in the order dispatch resolves them: ACP builtins first
-		// (so core commands like `/model`, `/mcp`, `/todo` cannot be shadowed),
-		// then skills, then custom/user commands, then file-based slash
-		// commands. `appendCommand` dedupes by name so earlier entries win.
+		// Advertise in the order dispatch resolves them (mirrors AgentSession
+		// dispatch: builtins → skills → extensions → custom TS → file-based).
+		// `appendCommand` dedupes by name so earlier entries win; extension
+		// commands therefore correctly shadow custom TS commands of the same
+		// name, matching the runtime behaviour of #tryExecuteExtensionCommand
+		// running before #tryExecuteCustomCommand.
 		for (const command of ACP_BUILTIN_SLASH_COMMANDS) {
 			appendCommand(command);
 		}
@@ -1600,6 +1692,20 @@ export class AcpAgent implements Agent {
 			}
 		}
 
+		for (const command of session.extensionRunner?.getRegisteredCommands(ACP_BUILTIN_RESERVED_NAMES) ?? []) {
+			// Reserved-set filtering in getRegisteredCommands only covers exact
+			// names; colon-namespaced names whose prefix is a builtin (e.g.
+			// `model:foo`) would still dispatch to the builtin in ACP.
+			if (isAcpBuiltinShadowedName(command.name)) {
+				continue;
+			}
+			appendCommand({
+				name: command.name,
+				description: command.description ?? "(extension command)",
+				input: { hint: "arguments" },
+			});
+		}
+
 		for (const command of session.customCommands) {
 			appendCommand({
 				name: command.command.name,
@@ -2069,9 +2175,7 @@ export class AcpAgent implements Agent {
 					});
 				},
 				sendUserMessage: (content, options) => {
-					record.session.sendUserMessage(content, options).catch((error: unknown) => {
-						logger.warn("ACP extension sendUserMessage failed", { error });
-					});
+					this.#trackExtensionUserMessage(record, record.session.sendUserMessage(content, options));
 				},
 				appendEntry: (customType, data) => {
 					record.session.sessionManager.appendCustomEntry(customType, data);
@@ -2224,6 +2328,7 @@ export class AcpAgent implements Agent {
 	}
 
 	async #closeManagedSession(sessionId: string, record: ManagedSessionRecord): Promise<void> {
+		record.closedError ??= this.#createPromptLifecycleError("ACP session closed before queued prompt could run");
 		this.#sessions.delete(sessionId);
 		await this.#cancelPromptForClose(record);
 		await this.#disposeSessionRecord(record);
@@ -2279,6 +2384,9 @@ export class AcpAgent implements Agent {
 			await Promise.all(
 				records.map(async ([sessionId, record]) => {
 					try {
+						record.closedError ??= this.#createPromptLifecycleError(
+							"ACP agent disposed before queued prompt could run",
+						);
 						await this.#cancelPromptForClose(record);
 						await this.#disposeSessionRecord(record);
 					} catch (error) {