@oh-my-pi/pi-coding-agent 17.0.2 → 17.0.4

package/src/mcp/transports/stdio.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it, spyOn } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
 
-import { resolveStdioSpawnCommand, StdioTransport } from "./stdio";
+import { resolveStdioSpawnCommand, StdioTransport, terminateStdioProcess } from "./stdio";
 
 describe("resolveStdioSpawnCommand", () => {
 	it("hides Windows executable MCP servers when the host has no console", async () => {
@@ -149,3 +152,268 @@ describe.skipIf(process.platform === "win32")("StdioTransport request write stal
 		}
 	}, 8000);
 });
+
+function processExists(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+// Regression for #5578: `close()` used a bare `this.#process.kill()` (direct
+// SIGTERM, no wait, no escalate, no process-group signal), so a detached
+// session-leader child (or a grandchild it spawned) that ignores/traps
+// SIGTERM survived host exit and became an orphan pinned to PID 1 on Linux.
+// `sleep`/`bun`/POSIX signal semantics are exercised directly here rather
+// than through `StdioTransport.connect()`, because `connect()` derives
+// `detached` from `resolveStdioSpawnCommand()`, which is tied to the host's
+// real `process.platform` — a POSIX detached session cannot be reproduced
+// end-to-end through `connect()` on a non-Linux dev/CI host, but a real
+// detached process group can still be spawned directly on any POSIX host.
+describe.skipIf(process.platform === "win32")("terminateStdioProcess", () => {
+	it("escalates a detached child that traps SIGTERM to SIGKILL", async () => {
+		const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-stdio-kill-solo-"));
+		const scriptPath = path.join(tempDir, "child.mjs");
+		const readyPath = path.join(tempDir, "ready");
+		await fs.writeFile(
+			scriptPath,
+			[
+				"import { writeFileSync } from 'node:fs';",
+				"process.on('SIGTERM', () => {});",
+				`writeFileSync(${JSON.stringify(readyPath)}, '1');`,
+				"setInterval(() => {}, 60_000);",
+			].join("\n"),
+		);
+		const proc = Bun.spawn(["bun", "run", scriptPath], {
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+			detached: true,
+		});
+		try {
+			// Wait for the child to actually register its SIGTERM handler before
+			// signaling it: signaling too early races the child's startup and
+			// hits the default (terminate) action instead of exercising the trap.
+			for (let i = 0; i < 100; i++) {
+				try {
+					await fs.access(readyPath);
+					break;
+				} catch {
+					await Bun.sleep(20);
+				}
+			}
+
+			const started = performance.now();
+			await terminateStdioProcess(proc, true);
+			await proc.exited;
+			const elapsedMs = performance.now() - started;
+
+			expect(proc.signalCode).toBe("SIGKILL");
+			// Escalation only fires after the ~1s SIGTERM grace window elapses —
+			// a too-fast exit would mean SIGKILL fired without waiting.
+			expect(elapsedMs).toBeGreaterThanOrEqual(900);
+		} finally {
+			try {
+				process.kill(-proc.pid, "SIGKILL");
+			} catch {
+				// Already gone.
+			}
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	}, 5000);
+
+	it("reaches a SIGTERM-trapping grandchild through the group SIGKILL, not just the direct child", async () => {
+		const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-stdio-group-kill-"));
+		const grandchildScriptPath = path.join(tempDir, "grandchild.mjs");
+		const parentScriptPath = path.join(tempDir, "parent.mjs");
+		const grandchildPidPath = path.join(tempDir, "grandchild.pid");
+
+		// Grandchild also traps SIGTERM, so only an unrestricted SIGKILL to the
+		// whole group — not a signal to the direct (parent) child alone — can
+		// reach and stop it.
+		await fs.writeFile(
+			grandchildScriptPath,
+			[
+				"import { writeFileSync } from 'node:fs';",
+				"process.on('SIGTERM', () => {});",
+				`writeFileSync(${JSON.stringify(grandchildPidPath)}, String(process.pid));`,
+				"setInterval(() => {}, 60_000);",
+			].join("\n"),
+		);
+		await fs.writeFile(
+			parentScriptPath,
+			[
+				"process.on('SIGTERM', () => {});",
+				`Bun.spawn(["bun", "run", ${JSON.stringify(grandchildScriptPath)}], { stdout: "ignore", stderr: "ignore", stdin: "ignore" });`,
+				"setInterval(() => {}, 60_000);",
+			].join("\n"),
+		);
+
+		const proc = Bun.spawn(["bun", "run", parentScriptPath], {
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+			detached: true,
+		});
+
+		try {
+			// Polls real wall-clock time rather than an event/promise: the
+			// grandchild process is a real external OS process writing to a real
+			// file, with no in-process signal this test can `await` directly.
+			let grandchildPid: number | undefined;
+			for (let i = 0; i < 100 && grandchildPid === undefined; i++) {
+				try {
+					grandchildPid = Number.parseInt(await fs.readFile(grandchildPidPath, "utf8"), 10);
+				} catch {
+					await Bun.sleep(20);
+				}
+			}
+			if (grandchildPid === undefined) throw new Error("grandchild never reported its pid");
+			expect(processExists(grandchildPid)).toBe(true);
+
+			await terminateStdioProcess(proc, true);
+			await proc.exited;
+			expect(proc.signalCode).toBe("SIGKILL");
+
+			// The group SIGKILL is delivered to every member simultaneously, but
+			// give the kernel a brief window to finish reaping before asserting.
+			let grandchildAlive = processExists(grandchildPid);
+			for (let i = 0; i < 25 && grandchildAlive; i++) {
+				await Bun.sleep(20);
+				grandchildAlive = processExists(grandchildPid);
+			}
+			expect(grandchildAlive).toBe(false);
+		} finally {
+			try {
+				process.kill(-proc.pid, "SIGKILL");
+			} catch {
+				// Already gone.
+			}
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	}, 8000);
+
+	it("still reaps a SIGTERM-trapping grandchild after the detached leader exits cooperatively", async () => {
+		// Regression: the leader exiting within the SIGTERM grace window used to
+		// be treated as proof the whole process group was gone, so `close()`
+		// returned early and never delivered a group SIGKILL — leaving exactly
+		// the orphaned grandchild this change is meant to reap. Unlike the
+		// group-SIGKILL test above, the leader here does NOT trap SIGTERM, so
+		// it exits promptly on its own; only the grandchild ignores signals.
+		const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-stdio-leader-exit-group-kill-"));
+		const grandchildScriptPath = path.join(tempDir, "grandchild.mjs");
+		const parentScriptPath = path.join(tempDir, "parent.mjs");
+		const grandchildPidPath = path.join(tempDir, "grandchild.pid");
+
+		await fs.writeFile(
+			grandchildScriptPath,
+			[
+				"import { writeFileSync } from 'node:fs';",
+				"process.on('SIGTERM', () => {});",
+				`writeFileSync(${JSON.stringify(grandchildPidPath)}, String(process.pid));`,
+				"setInterval(() => {}, 60_000);",
+			].join("\n"),
+		);
+		// No SIGTERM handler here: the default action (terminate) fires as soon
+		// as the group SIGTERM lands, well inside TERM_GRACE_MS.
+		await fs.writeFile(
+			parentScriptPath,
+			[
+				`Bun.spawn(["bun", "run", ${JSON.stringify(grandchildScriptPath)}], { stdout: "ignore", stderr: "ignore", stdin: "ignore" });`,
+				"setInterval(() => {}, 60_000);",
+			].join("\n"),
+		);
+
+		const proc = Bun.spawn(["bun", "run", parentScriptPath], {
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+			detached: true,
+		});
+
+		try {
+			let grandchildPid: number | undefined;
+			for (let i = 0; i < 100 && grandchildPid === undefined; i++) {
+				try {
+					grandchildPid = Number.parseInt(await fs.readFile(grandchildPidPath, "utf8"), 10);
+				} catch {
+					await Bun.sleep(20);
+				}
+			}
+			if (grandchildPid === undefined) throw new Error("grandchild never reported its pid");
+			expect(processExists(grandchildPid)).toBe(true);
+
+			const started = performance.now();
+			await terminateStdioProcess(proc, true);
+			await proc.exited;
+			const elapsedMs = performance.now() - started;
+
+			// The leader exits on the initial SIGTERM (no trap), so this must not
+			// block for the ~1s TERM grace window before sweeping the group.
+			expect(elapsedMs).toBeLessThan(700);
+
+			let grandchildAlive = processExists(grandchildPid);
+			for (let i = 0; i < 25 && grandchildAlive; i++) {
+				await Bun.sleep(20);
+				grandchildAlive = processExists(grandchildPid);
+			}
+			expect(grandchildAlive).toBe(false);
+		} finally {
+			try {
+				process.kill(-proc.pid, "SIGKILL");
+			} catch {
+				// Already gone.
+			}
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	}, 8000);
+
+	it("never attempts a process-group signal when the transport did not spawn detached", async () => {
+		const proc = Bun.spawn(["bun", "-e", "await Bun.sleep(60_000)"], {
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+			detached: false,
+		});
+		const killSpy = spyOn(process, "kill");
+		try {
+			await terminateStdioProcess(proc, false);
+			await proc.exited;
+
+			// Only the direct-child `Subprocess.kill()` path may run; the global
+			// `process.kill()` (used exclusively for the negative-pid group
+			// signal) must never be reached.
+			expect(killSpy).not.toHaveBeenCalled();
+		} finally {
+			killSpy.mockRestore();
+			try {
+				proc.kill("SIGKILL");
+			} catch {
+				// Already gone.
+			}
+		}
+	}, 5000);
+});
+
+describe.skipIf(process.platform === "win32")("StdioTransport.close teardown", () => {
+	it("closes a well-behaved child promptly without escalating to SIGKILL", async () => {
+		const transport = new StdioTransport({
+			command: "bun",
+			args: ["-e", "await Bun.sleep(60_000)"],
+		});
+		try {
+			await transport.connect();
+			const started = performance.now();
+			await transport.close();
+			const elapsedMs = performance.now() - started;
+
+			// No SIGTERM trap => the child dies almost immediately; close() must
+			// not block for the full ~1s TERM grace window before returning.
+			expect(elapsedMs).toBeLessThan(700);
+		} finally {
+			await transport.close();
+		}
+	}, 5000);
+});

package/src/mcp/transports/stdio.ts

@@ -404,6 +404,132 @@ export function writeFrame(stdin: FrameSink, frame: string): boolean {
 	}
 }
 
+/** Grace window to observe a cooperative exit after SIGTERM before escalating to SIGKILL. */
+const TERM_GRACE_MS = 1000;
+/** Grace window to observe SIGKILL taking effect before `close()` gives up and returns. */
+const KILL_GRACE_MS = 500;
+
+/**
+ * The subset of `Subprocess` that termination needs. Decoupled from the
+ * `Subprocess<In, Out, Err>` stdio generics — `#process`'s pipes are
+ * irrelevant to signaling — so tests can exercise it against a plain
+ * `Bun.spawn(cmd, { stdio: "ignore" })` child without fighting the generics.
+ */
+interface KillableSubprocess {
+	readonly pid: number;
+	readonly exited: Promise<number>;
+	kill(signal?: number | NodeJS.Signals): void;
+}
+
+/**
+ * Race `exited` against a timer. Resolves `true` once the process has exited
+ * within `timeoutMs`, `false` if the timer wins first. `exited` resolving OR
+ * rejecting both count as "exited" — mirrors `waitForExit()` in
+ * `lsp/client.ts`, which treats the same ambiguity (Bun documents
+ * `Subprocess.exited` as resolve-only, but a settle either way means there is
+ * nothing left to wait on).
+ *
+ * The timer is always cleared before returning — win or lose — so a process
+ * that exits promptly never leaves a dangling `timeoutMs` timer holding the
+ * event loop open behind it.
+ */
+async function waitForProcessExit(exited: Promise<number>, timeoutMs: number): Promise<boolean> {
+	const { promise: timedOut, resolve: resolveTimedOut } = Promise.withResolvers<false>();
+	const timer = setTimeout(() => resolveTimedOut(false), timeoutMs);
+	try {
+		return await Promise.race([
+			exited.then(
+				() => true,
+				() => true,
+			),
+			timedOut,
+		]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/** `true` when `error` is a Node errno exception carrying the given `code`. */
+function isErrnoCode(error: unknown, code: string): boolean {
+	if (typeof error !== "object" || error === null || !("code" in error)) return false;
+	return error.code === code;
+}
+
+/**
+ * Signal `signal` to `proc`. When `detached` is true on a POSIX platform,
+ * targets the whole process group via the negative-pid convention
+ * (`process.kill(-pid, signal)`) so a detached session leader's descendants —
+ * not just the direct child — receive it too; a bare direct-child signal
+ * never reaches grandchildren the child itself spawned.
+ *
+ * `ESRCH` from the group signal means the group is already gone — that is a
+ * success (nothing left to signal), not a failure — so it does not fall
+ * through. Any other group-signal failure (e.g. `EPERM`) falls back to
+ * signaling the direct child as a last resort. Non-detached transports
+ * (macOS, Windows, or POSIX where detach did not apply) always signal the
+ * direct child only: a negative-pid signal outside a detached session could
+ * hit an unrelated process group.
+ */
+function signalStdioProcess(
+	proc: KillableSubprocess,
+	detached: boolean,
+	signal: NodeJS.Signals,
+	platform: NodeJS.Platform,
+): void {
+	if (detached && platform !== "win32") {
+		try {
+			process.kill(-proc.pid, signal);
+			return;
+		} catch (error) {
+			if (isErrnoCode(error, "ESRCH")) return;
+			// Fall through to the direct-child signal below.
+		}
+	}
+	try {
+		proc.kill(signal);
+	} catch {
+		// Already gone.
+	}
+}
+
+/**
+ * Terminate an MCP stdio subprocess: SIGTERM (process-group when `detached`
+ * on POSIX, direct child otherwise), wait up to `TERM_GRACE_MS` for a
+ * cooperative exit, then escalate to SIGKILL — waiting up to `KILL_GRACE_MS`
+ * more only when the leader itself hadn't already exited. A detached
+ * leader's cooperative exit does not prove the whole process group is gone
+ * (a grandchild can outlive it and ignore SIGTERM), so detached transports
+ * always fire the group SIGKILL sweep, even after a clean SIGTERM exit.
+ * Every step is a no-op-safe signal against an already-exited target, so
+ * repeat calls (idempotent `close()`) never throw.
+ *
+ * Exported so tests can exercise group-signal escalation with an explicit
+ * `detached`/`platform` pair: `StdioTransport.connect()` derives `detached`
+ * from `resolveStdioSpawnCommand()`, which is tied to the host's real
+ * `process.platform`, so a POSIX detached session cannot be reproduced
+ * end-to-end through `connect()` on a non-Linux dev/CI host.
+ */
+export async function terminateStdioProcess(
+	proc: KillableSubprocess,
+	detached: boolean,
+	platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+	signalStdioProcess(proc, detached, "SIGTERM", platform);
+	const exitedOnTerm = await waitForProcessExit(proc.exited, TERM_GRACE_MS);
+	// A non-detached transport has no process group beyond the leader itself:
+	// once it exits, there is nothing left to signal. A detached transport's
+	// leader exiting is NOT proof the group is empty — a grandchild it spawned
+	// can still be alive and ignoring SIGTERM — so detached transports always
+	// fall through to the group SIGKILL, even on a cooperative leader exit.
+	if (exitedOnTerm && !detached) return;
+	signalStdioProcess(proc, detached, "SIGKILL", platform);
+	// Once the leader has already exited there is no further `exited` signal
+	// to wait on for this call — the SIGKILL above is a fire-and-forget sweep
+	// for any surviving group members — so only block on the grace window
+	// when the leader itself is still the thing being escalated against.
+	if (!exitedOnTerm) await waitForProcessExit(proc.exited, KILL_GRACE_MS);
+}
+
 /**
  * Stdio transport for MCP servers.
  * Spawns a subprocess and communicates via stdin/stdout.
@@ -419,6 +545,12 @@ export class StdioTransport implements MCPTransport {
 	>();
 	#connected = false;
 	#readLoop: Promise<void> | null = null;
+	/**
+	 * Set from `resolveStdioSpawnCommand()`'s `detached` flag in `connect()`.
+	 * Gates process-group signaling in `close()` — only a transport that
+	 * actually spawned into its own session may target it.
+	 */
+	#detached = false;
 
 	onClose?: () => void;
 	onError?: (error: Error) => void;
@@ -469,6 +601,7 @@ export class StdioTransport implements MCPTransport {
 			detached: spawnCommand.detached,
 			windowsVerbatimArguments: spawnCommand.windowsVerbatimArguments,
 		});
+		this.#detached = spawnCommand.detached;
 
 		this.#connected = true;
 
@@ -730,8 +863,26 @@ export class StdioTransport implements MCPTransport {
 		}
 
 		if (this.#process) {
-			this.#process.kill();
+			// Grab the handle and null the field immediately (before any
+			// `await`) so a concurrent/repeat `close()` sees `#process` already
+			// cleared and skips straight past this block — no double-signal.
+			const proc = this.#process;
 			this.#process = null;
+
+			// 1. Cooperative EOF first: a well-behaved server sees stdin close
+			// and can exit on its own before any signal is sent. Guarded — the
+			// sink can throw if the pipe is already closed/dead (e.g. the child
+			// already exited and the read loop got there first).
+			try {
+				proc.stdin.end();
+			} catch {
+				// Already closed/dead.
+			}
+
+			// 2-3. Group-aware SIGTERM (when this transport actually spawned
+			// detached), bounded wait, then escalate to SIGKILL. See
+			// `terminateStdioProcess` for the exact signaling/escalation rules.
+			await terminateStdioProcess(proc, this.#detached);
 		}
 
 		if (this.#readLoop) {

package/src/mnemopi/backend.ts

@@ -145,7 +145,7 @@ export const mnemopiBackend: MemoryBackend = {
 				state = new MnemopiSessionState({ sessionId: session.sessionId, config, session });
 				setMnemopiSessionState(session, state);
 			}
-			await state?.consolidate();
+			await state?.consolidate({ full: true });
 		} catch (error) {
 			logger.warn("Mnemopi: enqueue failed.", { error: String(error) });
 		}

package/src/mnemopi/embed-worker.ts

@@ -9,8 +9,7 @@
  * in either process.
  */
 
-import type { StandardEmbeddingModel } from "@oh-my-pi/pi-mnemopi/core";
-import { loadFastembed } from "@oh-my-pi/pi-mnemopi/core/fastembed-runtime";
+import { defaultLocalModelInitializer, type StandardEmbeddingModel } from "@oh-my-pi/pi-mnemopi/core";
 import type { MnemopiEmbedModelId, MnemopiEmbedTransport, MnemopiEmbedWorkerInbound } from "./embed-protocol";
 
 interface LoadedModel {
@@ -25,12 +24,14 @@ let loaded: Promise<LoadedModel> | null = null;
 let loadedKey = "";
 
 async function loadModel(model: MnemopiEmbedModelId, cacheDir: string | undefined): Promise<LoadedModel> {
-	const { FlagEmbedding } = await loadFastembed();
+	// Route through mnemopi's shared initializer so the worker inherits BOTH
+	// cache heals (sidecar re-fetch AND corrupt-model quarantine/retry) —
+	// fastembed/onnxruntime still load only in this child address space, the
+	// initializer calls loadFastembed() itself.
 	// Cast: `model` arrives as a string from the parent (resolved by
-	// mnemopi's `fastembedModelName`). Cast to the non-CUSTOM overload's
-	// argument so TypeScript picks the standard-model branch — the parent
-	// only ever passes pre-vetted fast-* identifiers.
-	const instance = await FlagEmbedding.init({
+	// mnemopi's `fastembedModelName`); the parent only ever passes pre-vetted
+	// fast-* identifiers.
+	const instance = await defaultLocalModelInitializer({
 		model: model as StandardEmbeddingModel,
 		cacheDir,
 		showDownloadProgress: false,

package/src/mnemopi/state.ts

@@ -454,18 +454,23 @@ export class MnemopiSessionState {
 		this.lastRetainedTurn = userTurns;
 	}
 
-	async forceRetainCurrentSession(): Promise<void> {
+	async forceRetainCurrentSession(options: { extract?: boolean } = {}): Promise<void> {
 		if (this.aliasOf) return;
 		const flat = extractMessages(this.session.sessionManager);
-		await this.retainMessages(flat, this.sessionId);
+		await this.retainMessages(flat, this.sessionId, options);
 		this.lastRetainedTurn = flat.filter(message => message.role === "user").length;
 	}
 
-	async retainMessages(messages: Array<{ role: string; content: string }>, sourceId: string): Promise<void> {
+	async retainMessages(
+		messages: Array<{ role: string; content: string }>,
+		sourceId: string,
+		options: { extract?: boolean } = {},
+	): Promise<void> {
 		const { transcript, messageCount } = prepareRetentionTranscript(messages, true);
 		if (!transcript) return;
 		const { transcript: extractText } = prepareUserRetentionTranscript(messages);
 		const { transcript: embedText } = prepareEmbeddableRetentionTranscript(messages);
+		const shouldExtract = options.extract !== false && extractText !== null;
 		this.rememberInScope(transcript, {
 			source: "coding-agent-transcript",
 			importance: 0.65,
@@ -476,9 +481,9 @@ export class MnemopiSessionState {
 				cwd: this.session.sessionManager.getCwd(),
 			},
 			scope: "bank",
-			extract: extractText !== null,
-			extractEntities: extractText !== null,
-			extractText,
+			extract: shouldExtract,
+			extractEntities: shouldExtract,
+			extractText: shouldExtract ? extractText : null,
 			embedText,
 			veracity: "unknown",
 			memoryType: "episode",
@@ -530,22 +535,42 @@ export class MnemopiSessionState {
 	 * otherwise enqueue would report success while leaving the subagent's
 	 * retained memories unconsolidated until the parent eventually shuts down
 	 * (PR #2327 review).
+	 *
+	 * @param options.full - When true, run `sleepAllSessions` on every owned bank
+	 *  (the full cross-session consolidation used by `/memory enqueue`). When
+	 *  false (the default), run only `sleep` on the current session for a
+	 *  lighter, bounded shutdown pass.
+	 * @param options.sleep - When false, skips the bank sleep step entirely.
+	 *  Used on the interactive shutdown path so `dispose` does not block on
+	 *  synchronous consolidation of old working rows from previous sessions.
+	 * @param options.extract - When false, the retained transcript is stored but
+	 *  no LLM fact extraction is scheduled. Used on the interactive shutdown path
+	 *  so `dispose` does not block on a fresh LLM round-trip.
 	 */
-	async consolidate(): Promise<void> {
-		await this.forceRetainCurrentSession();
+	async consolidate(options: { full?: boolean; extract?: boolean; sleep?: boolean } = {}): Promise<void> {
+		await this.forceRetainCurrentSession({ extract: options.extract });
 		for (const memory of this.scoped.owned) {
 			await memory.flushExtractions();
-			memory.sleepAllSessions(false);
+			if (options.sleep === false) continue;
+			if (options.full) {
+				memory.sleepAllSessions(false);
+			} else {
+				memory.sleep(false);
+			}
 		}
 	}
 
 	/**
-	 * Release the per-session resources. Defaults to running {@link consolidate}
-	 * before closing handles so normal session shutdown promotes working memory
-	 * into long-term storage. Callers that are about to delete the DB files —
-	 * e.g. `mnemopiBackend.clear` — pass `{ consolidate: false }` to skip the
-	 * extraction/sleep pass, since spending tokens on memories that will be
-	 * wiped on the next line is wasted work (PR #2327 review).
+	 * Release the per-session resources. Defaults to running a lighter
+	 * {@link consolidate} pass before closing handles: it retains the current
+	 * transcript and flushes in-flight extractions, but skips the synchronous
+	 * bank sleep so normal session shutdown returns promptly. Full promotion of
+	 * working memory into long-term storage is still performed by the explicit
+	 * `/memory enqueue` and backend enqueue paths. Callers that are about to
+	 * delete the DB files — e.g. `mnemopiBackend.clear` — pass
+	 * `{ consolidate: false }` to skip the retain/flush pass, since spending
+	 * tokens on memories that will be wiped on the next line is wasted work
+	 * (PR #2327 review).
 	 *
 	 * `timeoutMs` caps how long the consolidate await blocks the caller
 	 * (the user-visible `/quit` / `/exit` shutdown path passes this so
@@ -569,9 +594,11 @@ export class MnemopiSessionState {
 			closeOwned();
 			return;
 		}
-		const consolidatePromise = this.consolidate().catch((error: unknown) => {
-			logger.warn("Mnemopi: consolidation on dispose failed.", { error: String(error) });
-		});
+		const consolidatePromise = this.consolidate({ full: false, extract: false, sleep: false }).catch(
+			(error: unknown) => {
+				logger.warn("Mnemopi: consolidation on dispose failed.", { error: String(error) });
+			},
+		);
 		const { timeoutMs } = options;
 		if (timeoutMs !== undefined && timeoutMs > 0) {
 			const TIMED_OUT = Symbol("mnemopi.dispose.timedOut");