fix: harden qmd error diagnostics

Signed-off-by: Jay Zeng <jayzeng@users.noreply.github.com>

Author: jayzeng

README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/pi-memory?color=cb3837&logo=npm)](https://www.npmjs.com/package/pi-memory)
 [![license](https://img.shields.io/npm/l/pi-memory)](LICENSE)
 
-**The most popular memory extension for [pi](https://github.com/mariozechner/pi-mono)** — listed in the [official pi package directory](https://pi.dev/packages?name=pi-memory), with semantic search powered by [qmd](https://github.com/tobi/qmd).
+**The most popular memory extension for [pi](https://github.com/earendil-works/pi/)** — listed in the [official pi package directory](https://pi.dev/packages?name=pi-memory), with semantic search powered by [qmd](https://github.com/tobi/qmd).
 
 Thanks to https://github.com/skyfallsin/pi-mem for inspiration.
 

index.ts

@@ -858,6 +858,12 @@ export function buildQmdSpawn(
 	return { file: "node", args: [qmdJsPath, ...args] };
 }
 
+export function buildQmdEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+	const qmdEnv: NodeJS.ProcessEnv = { ...env, NO_COLOR: "1" };
+	delete qmdEnv.FORCE_COLOR;
+	return qmdEnv;
+}
+
 const execFileWithQmdOptions: ExecFileFn = ((
 	file: string,
 	args: readonly string[],
@@ -866,7 +872,8 @@ const execFileWithQmdOptions: ExecFileFn = ((
 ) => {
 	const qmdJs = process.platform === "win32" && isQmdCommand(file) ? resolveQmdJsPath() : null;
 	const spawn = buildQmdSpawn(file, args ?? [], process.platform, qmdJs);
-	return execFile(spawn.file, spawn.args, options, callback as any);
+	const execOptions = isQmdCommand(file) ? { ...options, env: buildQmdEnv(options.env ?? process.env) } : options;
+	return execFile(spawn.file, spawn.args, execOptions, callback as any);
 }) as ExecFileFn;
 
 let execFileFn: ExecFileFn = execFileWithQmdOptions;
@@ -1181,8 +1188,9 @@ function getQmdResultText(r: QmdSearchResult): string {
 function stripAnsi(text: string): string {
 	// qmd may emit spinners/progress bars even with --json, especially on first model download.
 	// Strip ANSI CSI/OSC sequences so we can reliably find and parse JSON payloads.
+	// CSI parameter bytes include private-mode sequences such as ESC[?25l / ESC[?25h.
 	// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping ANSI escape sequences
-	return text.replace(/\u001b\[[0-9;]*[A-Za-z]/g, "").replace(/\u001b\][^\u0007]*(\u0007|\u001b\\)/g, "");
+	return text.replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/\u001b\][^\u0007]*(\u0007|\u001b\\)/g, "");
 }
 
 function parseQmdJson(stdout: string): unknown {
@@ -1216,7 +1224,13 @@ export function runQmdSearch(
 	return new Promise((resolve, reject) => {
 		execFileFn("qmd", args, { timeout: 60_000 }, (err, stdout, stderr) => {
 			if (err) {
-				reject(new Error(stderr?.trim() || err.message));
+				const cleaned = stripAnsi(stderr ?? "").trim();
+				const cleanedMessage = stripAnsi(err.message).trim();
+				const timedOut = (err as NodeJS.ErrnoException & { killed?: boolean }).killed === true;
+				const hint = timedOut
+					? " (qmd timed out after 60s — first semantic/deep search may download or load models; retry shortly)"
+					: "";
+				reject(new Error(`${cleaned || cleanedMessage}${hint}`));
 				return;
 			}
 			try {

test/unit.test.ts

@@ -24,6 +24,7 @@ import {
 	_setExecFileForTest,
 	_setQmdAvailable,
 	buildMemoryContext,
+	buildQmdEnv,
 	buildQmdSpawn,
 	clampSearchLimit,
 	dailyPath,
@@ -37,6 +38,7 @@ import {
 	readFileSafe,
 	resolveMemoryDir,
 	resolveQmdJsPath,
+	runQmdSearch,
 	type ScratchpadItem,
 	scheduleQmdUpdate,
 	scratchpadAdd,
@@ -1121,6 +1123,61 @@ describe("memory_read tool", () => {
 // 8. Tool: memory_search
 // ==========================================================================
 
+describe("runQmdSearch qmd diagnostics", () => {
+	afterEach(() => {
+		_resetExecFileForTest();
+	});
+
+	test("strips qmd spinner control sequences from stderr failures", async () => {
+		_setExecFileForTest(((_file: string, _args: string[], _opts: any, cb: any) => {
+			cb(
+				new Error("Command failed: qmd vsearch"),
+				"",
+				"\u001b[?25l\u001b[?25h\u001b[2K\u001b[1A\u001b[Greal diagnostic",
+			);
+		}) as any);
+
+		await expect(runQmdSearch("semantic", "query", 5)).rejects.toThrow("real diagnostic");
+		await expect(runQmdSearch("semantic", "query", 5)).rejects.not.toThrow("[?25");
+	});
+
+	test("strips qmd spinner control sequences from the fallback error message", async () => {
+		const spinner = "\u001b[?25l\u001b[?25h";
+		const commandError = new Error(`Command failed: qmd vsearch\n${spinner}`);
+		_setExecFileForTest(((_file: string, _args: string[], _opts: any, cb: any) => {
+			cb(commandError, "", spinner);
+		}) as any);
+
+		let failure: unknown;
+		try {
+			await runQmdSearch("semantic", "query", 5);
+		} catch (err) {
+			failure = err;
+		}
+
+		expect(failure).toBeInstanceOf(Error);
+		expect((failure as Error).message).toContain("Command failed: qmd vsearch");
+		expect((failure as Error).message).not.toContain("\u001b");
+	});
+
+	test("annotates qmd timeouts with a retryable cold-start hint", async () => {
+		const timeoutErr = Object.assign(new Error("Command failed: qmd vsearch"), { killed: true });
+		_setExecFileForTest(((_file: string, _args: string[], _opts: any, cb: any) => {
+			cb(timeoutErr, "", "\u001b[?25l\u001b[?25h");
+		}) as any);
+
+		await expect(runQmdSearch("semantic", "query", 5)).rejects.toThrow("qmd timed out after 60s");
+	});
+
+	test("removes FORCE_COLOR and sets NO_COLOR for qmd child processes", () => {
+		const env = buildQmdEnv({ FORCE_COLOR: "3", NO_COLOR: undefined, PATH: "bin" });
+
+		expect(env.FORCE_COLOR).toBeUndefined();
+		expect(env.NO_COLOR).toBe("1");
+		expect(env.PATH).toBe("bin");
+	});
+});
+
 describe("memory_search tool", () => {
 	let tools: Record<string, any>;