@agentmemory/agentmemory 0.9.31 → 0.9.32

package/dist/cli.mjs

@@ -1,21 +1,27 @@
 #!/usr/bin/env node
-import { a as runAdapter, i as resolveAdapter, r as knownAgents, t as ADAPTERS } from "./connect-BSLIAMpw.mjs";
+import { a as runAdapter, i as resolveAdapter, r as knownAgents, t as ADAPTERS } from "./connect-BX3njQ3Y.mjs";
 import { s as generateId } from "./keyed-mutex-DCUh7PG-.mjs";
-import { A as engineFlushWaitMs, C as III_PINNED_VERSION, L as detectLlmProviderKind, M as redactCredentialUrls, N as runtimeConfigPath, O as setBootVerbose, X as getStateBackend, Z as getStateSaveIntervalMs, b as ESSENTIAL_TOOLS, et as hydrateProcessEnvFromFile, gt as parseEnvContent, i as resolveClientSecret, j as engineStateConfigPaths, q as getRedisUrl, t as bearerHeaders, w as VERSION, x as getAllTools } from "./secret-store-D9GwO0xp.mjs";
-import { $t as resolveDataDir, Gt as retainSent, Ht as drainSpool, Jt as spoolSummary, Ut as parseSentMark, an as runtimeMetadataPath, nn as registerStartupCleanup, nt as CURL_AUTH_HEADER, rn as runStartupCleanup, t as parseCompressionScope, tn as SHUTDOWN_HARD_EXIT_MS } from "./compression-recovery-CnhLQC6N.mjs";
+import { A as setBootVerbose, B as detectLlmProviderKind, C as getAllTools, E as VERSION, F as runtimeConfigPath, I as LLM_PROVIDER_KEYS, M as engineFlushWaitMs, N as engineStateConfigPaths, P as redactCredentialUrls, S as ESSENTIAL_TOOLS, T as III_PINNED_VERSION, V as embeddingOptInHint, Z as getRedisUrl, et as getStateBackend, i as resolveClientSecret, it as hydrateProcessEnvFromFile, mt as llmOptInHint, t as bearerHeaders, tt as getStateSaveIntervalMs, xt as parseEnvContent } from "./secret-store-iYXRcrO8.mjs";
+import { $t as resolveDataDir, Gt as retainSent, Ht as drainSpool, Jt as spoolSummary, Ut as parseSentMark, an as runtimeMetadataPath, nn as registerStartupCleanup, nt as CURL_AUTH_HEADER, rn as runStartupCleanup, t as parseCompressionScope, tn as SHUTDOWN_HARD_EXIT_MS } from "./compression-recovery-CZh63Jmz.mjs";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { appendFileSync, chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
-import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, delimiter, dirname, isAbsolute, join, resolve, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir, platform } from "node:os";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { copyFile, mkdir } from "node:fs/promises";
 import { parse, stringify } from "yaml";
 import { createConnection } from "node:net";
 import { registerWorker } from "iii-sdk";
 //#region src/cli/doctor-diagnostics.ts
+function canAutoFix(d, status) {
+	return !d.manualOnly && !status?.manualFix;
+}
+function doctorPromptsAllowed(env, stdinIsTTY, stdoutIsTTY) {
+	return Boolean(stdinIsTTY) && Boolean(stdoutIsTTY) && !env["CI"];
+}
 /** Common placeholder values shipped in .env.example. */
 const PLACEHOLDER_VALUES = new Set([
 	"",
@@ -70,22 +76,28 @@ function buildDiagnostics(effects) {
 		},
 		{
 			id: "no-llm-provider-key",
-			message: "No LLM provider API key found in ~/.agentmemory/.env or the environment.",
-			fixPreview: "Open ~/.agentmemory/.env in $EDITOR and paste your key, then re-check.",
-			moreInfo: "Set at least one of: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY, MINIMAX_API_KEY. Placeholder values count as missing. OPENAI_API_KEY counts only while OPENAI_API_KEY_FOR_LLM is not false, and AGENTMEMORY_ALLOW_AGENT_SDK=true needs no key. A value exported in the environment wins over the file, but only for a daemon started from that environment, and counts even when the file is absent.",
+			message: "No LLM provider chosen for agentmemory in ~/.agentmemory/.env or the environment.",
+			fixPreview: "Open ~/.agentmemory/.env in $EDITOR, set AGENTMEMORY_LLM_PROVIDER and that provider's key, then re-check.",
+			moreInfo: "agentmemory sends session content to an LLM provider only after you choose one: set AGENTMEMORY_LLM_PROVIDER to anthropic, openai, gemini, openrouter or minimax, and set that provider's key (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY or GOOGLE_API_KEY, OPENROUTER_API_KEY, MINIMAX_API_KEY). A key alone never turns LLM use on. Placeholder values count as missing. AGENTMEMORY_ALLOW_AGENT_SDK=true needs no key. A value exported in the environment wins over the file, but only for a daemon started from that environment.",
 			check: async () => {
 				const file = effects.readEnvFile();
 				const env = { ...file };
 				for (const [k, v] of Object.entries(effects.processEnv())) if (v !== void 0) env[k] = v;
 				for (const k of placeholderProviderKeys(env)) delete env[k];
-				if (detectLlmProviderKind(env) !== "llm") return {
-					ok: false,
-					detail: effects.envFileExists() ? "no provider key set" : "no provider key set (run env-missing fix first)"
-				};
-				const real = realProviderKeys(env).filter((k) => detectLlmProviderKind({
-					[k]: env[k],
-					OPENAI_API_KEY_FOR_LLM: env.OPENAI_API_KEY_FOR_LLM
-				}) === "llm");
+				if (detectLlmProviderKind(env) !== "llm") {
+					const hint = llmOptInHint(env);
+					if (hint) return {
+						ok: false,
+						detail: hint
+					};
+					return {
+						ok: false,
+						detail: effects.envFileExists() ? "no provider chosen" : "no provider chosen (run env-missing fix first)"
+					};
+				}
+				const selected = (env.AGENTMEMORY_LLM_PROVIDER ?? "").trim().toLowerCase();
+				const selectedKeys = selected in LLM_PROVIDER_KEYS ? LLM_PROVIDER_KEYS[selected] : [];
+				const real = realProviderKeys(env).filter((k) => selectedKeys.includes(k));
 				const fromEnv = real.filter((k) => file[k] !== env[k]);
 				const named = real.map((k) => fromEnv.includes(k) ? `${k} (environment)` : k);
 				if (named.length === 0) return {
@@ -100,28 +112,61 @@ function buildDiagnostics(effects) {
 			},
 			fix: (ctx) => effects.openEditor(ctx.envPath)
 		},
+		{
+			id: "embedding-provider-not-chosen",
+			message: "Cloud embeddings are not set up: EMBEDDING_PROVIDER does not choose a present key, or names a provider whose key is missing.",
+			fixPreview: "Open ~/.agentmemory/.env in $EDITOR and set EMBEDDING_PROVIDER (local, openai, voyage, cohere, gemini or openrouter).",
+			moreInfo: "Cloud embeddings send memory text to that provider, so agentmemory uses them only when EMBEDDING_PROVIDER names the provider. A key alone never turns them on. EMBEDDING_PROVIDER=local runs on-device. Without a provider, search is keyword and graph only.",
+			check: async () => {
+				const env = { ...effects.readEnvFile() };
+				for (const [k, v] of Object.entries(effects.processEnv())) if (v !== void 0) env[k] = v;
+				const hint = embeddingOptInHint(env);
+				return hint ? {
+					ok: false,
+					detail: hint
+				} : { ok: true };
+			},
+			fix: (ctx) => effects.openEditor(ctx.envPath)
+		},
 		{
 			id: "engine-version-mismatch",
-			message: "iii binary on PATH doesn't match the version agentmemory pins to.",
+			message: "No iii binary matches the version agentmemory pins to.",
 			fixPreview: "Reinstall the pinned iii-engine and restart the managed Worker Compose project.",
-			moreInfo: "agentmemory manages its pinned iii engine and workers through Worker Compose; a foreign process on PATH is not the instance binary. Running a mismatched binary surfaces as EPIPE reconnect loops and empty search results.",
+			moreInfo: "agentmemory manages its pinned iii engine and workers through Worker Compose; a foreign process on PATH is not the instance binary. Running a mismatched binary surfaces as EPIPE reconnect loops and empty search results. Before an instance is configured, a matching private install at ~/.agentmemory/bin/iii can satisfy the pin.",
 			check: async (ctx) => {
+				if (await effects.externalEngineRunning()) return {
+					ok: false,
+					detail: "external engine version is unknown",
+					manualFix: "Verify the external engine version, or stop it before starting a managed instance."
+				};
+				const privateVersion = effects.iiiBinaryVersion(effects.localBinIiiPath());
 				const bin = effects.findIiiBinary();
+				const pathVersion = bin ? effects.iiiBinaryVersion(bin) : null;
+				if (privateVersion === ctx.pinnedVersion) {
+					const note = pathVersion && pathVersion !== ctx.pinnedVersion ? `; PATH iii is ${pathVersion}; the pinned private install is available for startup` : "";
+					return {
+						ok: true,
+						detail: `private install ${privateVersion} (pinned ${ctx.pinnedVersion})${note}`
+					};
+				}
 				if (!bin) return {
 					ok: false,
-					detail: "iii not on PATH"
+					detail: "iii not on PATH and no private install"
 				};
-				const v = effects.iiiBinaryVersion(bin);
-				if (!v) return {
+				if (!pathVersion) return {
 					ok: false,
 					detail: "iii on PATH but --version failed"
 				};
 				return {
-					ok: v === ctx.pinnedVersion,
-					detail: `${v} (pinned ${ctx.pinnedVersion})`
+					ok: pathVersion === ctx.pinnedVersion,
+					detail: `${pathVersion} (pinned ${ctx.pinnedVersion})`
 				};
 			},
 			fix: async () => {
+				if (await effects.externalEngineRunning()) return {
+					ok: false,
+					message: "Verify or stop the external engine manually."
+				};
 				const r = await effects.runIiiInstaller();
 				if (!r.ok) return r;
 				await effects.runStop();
@@ -188,20 +233,25 @@ function buildDiagnostics(effects) {
 		},
 		{
 			id: "iii-on-path-not-local-bin",
-			message: "iii is on PATH but not at agentmemory's private install path.",
+			message: "iii is on PATH but agentmemory's private install is absent or mismatched.",
 			fixPreview: "Install the pinned version to ~/.agentmemory/bin — won't touch your PATH.",
 			moreInfo: "agentmemory installs its pinned engine to ~/.agentmemory/bin/iii so a user-managed iii on PATH (homebrew, cargo, manual install) stays untouched. When agentmemory needs the pin and PATH doesn't have it, it falls back to the private install. If neither exists, run the installer.",
 			manualOnly: true,
-			check: async () => {
+			check: async (ctx) => {
 				const bin = effects.findIiiBinary();
 				if (!bin) return {
 					ok: true,
 					detail: "iii not on PATH (handled elsewhere)"
 				};
 				const localBin = effects.localBinIiiPath();
+				if (bin === localBin) return { ok: true };
+				if (effects.iiiBinaryVersion(localBin) === ctx.pinnedVersion) return {
+					ok: true,
+					detail: `private install pinned; PATH iii at ${bin} stays untouched`
+				};
 				return {
-					ok: bin === localBin,
-					detail: bin === localBin ? void 0 : `iii at: ${bin}`
+					ok: false,
+					detail: `iii at: ${bin}`
 				};
 			},
 			fix: async () => effects.runIiiInstaller().then((r) => ({
@@ -222,7 +272,7 @@ function dryRunPlan(ctx, results) {
 		if (status.ok) continue;
 		n++;
 		lines.push(`${n}. [${diagnostic.id}] ${diagnostic.message}`);
-		lines.push(`   would fix: ${diagnostic.fixPreview}`);
+		lines.push(`   ${canAutoFix(diagnostic, status) ? "would fix" : "manual fix"}: ${status.manualFix ?? diagnostic.fixPreview}`);
 		if (status.detail) lines.push(`   detail: ${status.detail}`);
 	}
 	if (lines.length === 0) lines.push(`All checks passing for ${ctx.baseUrl} — no fixes to run.`);
@@ -511,6 +561,251 @@ function installIiiArchive(opts) {
 	};
 	return { ok: true };
 }
+function iiiZipArchivePath(binDir) {
+	return join(binDir, `.iii-download-${process.pid}-${randomBytes(4).toString("hex")}.zip`);
+}
+function removeQuietly(path) {
+	try {
+		rmSync(path, {
+			force: true,
+			recursive: true
+		});
+	} catch {}
+}
+function removeStaleInstallFiles(binDir, now = Date.now()) {
+	const removed = [];
+	let entries;
+	try {
+		entries = readdirSync(binDir);
+	} catch {
+		return removed;
+	}
+	for (const name of entries) {
+		if (!name.startsWith(".iii-download-") && !name.startsWith(".iii-staging-")) continue;
+		const path = join(binDir, name);
+		try {
+			if (now - statSync(path).mtimeMs < 9e5) continue;
+		} catch {
+			continue;
+		}
+		removeQuietly(path);
+		if (!existsSync(path)) removed.push(name);
+	}
+	return removed;
+}
+const PROXY_ENV_KEYS = [
+	"HTTPS_PROXY",
+	"https_proxy",
+	"HTTP_PROXY",
+	"http_proxy",
+	"ALL_PROXY",
+	"all_proxy"
+];
+function proxyConfigured(env) {
+	return PROXY_ENV_KEYS.some((key) => Boolean(env[key]?.trim()));
+}
+function windowsCurlDownloadCommand(url, dest, env = process.env) {
+	return {
+		command: join(env["SystemRoot"] || env["SYSTEMROOT"] || "C:\\Windows", "System32", "curl.exe"),
+		args: [
+			"-fsSL",
+			"--connect-timeout",
+			String(15),
+			"--max-time",
+			String(300),
+			"-o",
+			dest,
+			url
+		]
+	};
+}
+function powershellLiteral(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function windowsZipExtractCommands(archive, binDir, env = process.env) {
+	const system32 = join(env["SystemRoot"] || env["SYSTEMROOT"] || "C:\\Windows", "System32");
+	return [{
+		command: join(system32, "tar.exe"),
+		args: [
+			"-xf",
+			archive,
+			"-C",
+			binDir
+		]
+	}, {
+		command: join(system32, "WindowsPowerShell", "v1.0", "powershell.exe"),
+		args: [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			`Expand-Archive -LiteralPath ${powershellLiteral(archive)} -DestinationPath ${powershellLiteral(binDir)} -Force`
+		]
+	}];
+}
+async function downloadToFile(url, dest, env = process.env, run = runInstallCommand) {
+	if (proxyConfigured(env)) {
+		const step = windowsCurlDownloadCommand(url, dest, env);
+		const result = await run(step.command, step.args);
+		if (result.status !== 0) throw new Error(describeInstallFailure(result));
+		return;
+	}
+	const res = await fetch(url, {
+		redirect: "follow",
+		signal: AbortSignal.timeout(300 * 1e3)
+	});
+	if (!res.ok) throw new Error(`download failed with HTTP ${res.status} ${res.statusText}`.trim());
+	writeFileSync(dest, Buffer.from(await res.arrayBuffer()));
+}
+function runInstallCommand(command, args) {
+	return new Promise((done) => {
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		const child = spawn(command, args, {
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			windowsHide: true,
+			shell: false
+		});
+		const killOnExit = () => {
+			try {
+				child.kill();
+			} catch {}
+		};
+		process.once("exit", killOnExit);
+		const timer = setTimeout(() => {
+			timedOut = true;
+			child.kill();
+		}, III_INSTALL_SPAWN_TIMEOUT_MS);
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk;
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk;
+		});
+		let spawnError;
+		child.on("error", (error) => {
+			spawnError = error;
+			if (child.pid !== void 0) return;
+			clearTimeout(timer);
+			process.off("exit", killOnExit);
+			done({
+				status: null,
+				stdout,
+				stderr,
+				error
+			});
+		});
+		child.on("close", (status, signal) => {
+			clearTimeout(timer);
+			process.off("exit", killOnExit);
+			if (spawnError && status === null && !timedOut) {
+				done({
+					status: null,
+					stdout,
+					stderr,
+					signal,
+					error: spawnError
+				});
+				return;
+			}
+			if (timedOut) {
+				done({
+					status: null,
+					stdout,
+					stderr,
+					signal,
+					error: Object.assign(/* @__PURE__ */ new Error("timed out"), { code: "ETIMEDOUT" })
+				});
+				return;
+			}
+			done({
+				status,
+				stdout,
+				stderr,
+				signal
+			});
+		});
+	});
+}
+async function installIiiZip(opts) {
+	const expected = expectedIiiSha256(opts.version, opts.asset, opts.checksums);
+	if (!expected) return {
+		ok: false,
+		reason: "no-checksum",
+		detail: `no pinned SHA-256 for ${opts.asset} in iii v${opts.version}, so the download cannot be verified`
+	};
+	const run = opts.run ?? runInstallCommand;
+	const download = opts.download ?? ((url, dest) => downloadToFile(url, dest, opts.env ?? process.env, run));
+	const archive = iiiZipArchivePath(opts.binDir);
+	try {
+		mkdirSync(opts.binDir, { recursive: true });
+		removeStaleInstallFiles(opts.binDir);
+		await download(opts.releaseUrl, archive);
+	} catch (err) {
+		removeQuietly(archive);
+		return {
+			ok: false,
+			reason: "download",
+			detail: err instanceof Error ? err.message : String(err)
+		};
+	}
+	let actual;
+	try {
+		actual = sha256File(archive);
+	} catch (err) {
+		removeQuietly(archive);
+		return {
+			ok: false,
+			reason: "download",
+			detail: err instanceof Error ? err.message : String(err)
+		};
+	}
+	if (actual !== expected) {
+		removeQuietly(archive);
+		return {
+			ok: false,
+			reason: "checksum",
+			detail: `SHA-256 mismatch for ${opts.asset}: expected ${expected}, got ${actual}. The download was deleted and nothing was installed`
+		};
+	}
+	const staging = join(opts.binDir, `.iii-staging-${process.pid}-${randomBytes(4).toString("hex")}`);
+	const staged = join(staging, basename(opts.binPath));
+	const failures = [];
+	try {
+		for (const step of windowsZipExtractCommands(archive, staging, opts.env)) {
+			removeQuietly(staging);
+			mkdirSync(staging, { recursive: true });
+			const result = await run(step.command, step.args);
+			if (result.status === 0 && existsSync(staged)) try {
+				renameSync(staged, opts.binPath);
+				return { ok: true };
+			} catch (err) {
+				failures.push(`could not move ${staged} to ${opts.binPath}: ${err instanceof Error ? err.message : String(err)}`);
+				break;
+			}
+			failures.push(`${step.command}: ${result.status === 0 ? `finished but ${basename(opts.binPath)} is missing from the archive` : describeInstallFailure(result)}`);
+		}
+		return {
+			ok: false,
+			reason: "extract",
+			detail: failures.join("; ")
+		};
+	} catch (err) {
+		failures.push(err instanceof Error ? err.message : String(err));
+		return {
+			ok: false,
+			reason: "extract",
+			detail: failures.join("; ")
+		};
+	} finally {
+		removeQuietly(staging);
+		removeQuietly(archive);
+	}
+}
 //#endregion
 //#region src/cli/startup-stderr.ts
 function createStartupStderrCapture(maxBytes = 16 * 1024) {
@@ -725,6 +1020,12 @@ function sameResolvedExecutable(actual, expected, windows = false) {
 		return false;
 	}
 }
+function classifyComposeProcess(inspected, expected, windows = false) {
+	if (!inspected || !inspected.command) return "unknown";
+	if (!(inspected.command.includes("compose --namespace") && inspected.command.includes(expected.namespace) && inspected.command.includes(expected.file))) return "foreign";
+	if (inspected.executable && sameResolvedExecutable(inspected.executable, expected.binPath, windows)) return "match";
+	return "unknown";
+}
 function readUnixProcessExecutable(pid, os) {
 	if (!Number.isSafeInteger(pid) || pid <= 0) return "";
 	if (os === "darwin") return readMacProcessExecutable(pid);
@@ -1002,6 +1303,7 @@ async function runOnboarding() {
 		if (hint) p.log.info(hint);
 	}
 	const envPath = await seedEnvFile(provider);
+	const providerWritten = setLlmProviderInEnv(envPath, provider);
 	await maybePromptContextInjection(envPath);
 	writePrefs({
 		lastAgent: agents[0] ?? null,
@@ -1015,8 +1317,9 @@ async function runOnboarding() {
 	else lines.push(`! Could not write ~/.agentmemory/.env — run \`agentmemory init\` after this completes.`);
 	if (provider) {
 		const envKey = PROVIDERS.find((x) => x.value === provider)?.envKey;
-		if (envKey) lines.push(`  Uncomment ${envKey}= in that file to enable ${provider}.`);
-	} else lines.push("  No provider chosen — agentmemory will run in BM25-only mode.");
+		if (envKey) lines.push(providerWritten ? `  Set AGENTMEMORY_LLM_PROVIDER=${provider}. Add ${envKey}= to that file to enable ${provider}.` : `  Add AGENTMEMORY_LLM_PROVIDER=${provider} and ${envKey}= to that file to enable ${provider}.`);
+	} else if (providerWritten) lines.push("  No LLM provider chosen. LLM summaries and compression stay off.");
+	else lines.push(`  ! Could not remove AGENTMEMORY_LLM_PROVIDER from ${envPath}. Delete that line to keep LLM features off.`);
 	p.note(lines.join("\n"), "ready");
 	if (agents.length > 0) await wireSelectedAgents(agents);
 	return {
@@ -1024,6 +1327,19 @@ async function runOnboarding() {
 		provider
 	};
 }
+function setLlmProviderInEnv(envPath, provider) {
+	if (provider === null) delete process.env["AGENTMEMORY_LLM_PROVIDER"];
+	if (!envPath || !existsSync(envPath)) return provider === null;
+	try {
+		const current = readFileSync(envPath, "utf-8");
+		const kept = current.split("\n").filter((entry) => !/^\s*AGENTMEMORY_LLM_PROVIDER\s*=/.test(entry)).join("\n");
+		const next = provider === null ? kept : `${kept}${kept.length > 0 && !kept.endsWith("\n") ? "\n" : ""}AGENTMEMORY_LLM_PROVIDER=${provider}\n`;
+		if (next !== current) writeFileSync(envPath, next, { mode: 384 });
+		return true;
+	} catch {
+		return false;
+	}
+}
 function enableInjectContextInEnv(envPath) {
 	if (!envPath || !existsSync(envPath)) return false;
 	try {
@@ -1361,6 +1677,10 @@ const COMPOSE_WORKER_VERSIONS = {
 	state: "0.22.20",
 	http: "0.22.7"
 };
+const COMPOSE_CONTAINER_COUNT = Object.keys(COMPOSE_WORKER_VERSIONS).length + 1;
+function composeDownTimeoutMs() {
+	return (20 * COMPOSE_CONTAINER_COUNT + 30) * 1e3;
+}
 function composeNamespace(restPort) {
 	return `agentmemory-${restPort}`;
 }
@@ -1376,8 +1696,8 @@ function composeProjectPaths(dataDir) {
 }
 const AGENTMEMORY_WORKER_ENV_ALLOWLIST = new Set([
 	"EMBEDDING_PROVIDER",
+	"AGENTMEMORY_LLM_PROVIDER",
 	"OPENAI_API_KEY",
-	"OPENAI_API_KEY_FOR_LLM",
 	"OPENAI_BASE_URL",
 	"OPENAI_MODEL",
 	"OPENAI_EMBEDDING_API_KEY",
@@ -1515,17 +1835,33 @@ function restartPolicyLines(indent, enabled) {
 		`${indent}  window: 60s`
 	];
 }
-function shellQuote$1(value, windows) {
+function shellQuote$1(value) {
 	if (/[\u0000-\u001f\u007f]/.test(value)) throw new Error("A shell command argument contains an unsupported control character.");
-	if (windows) {
-		if (value.includes("\"")) throw new Error("Windows shell arguments cannot contain a double quote.");
-		return `"${value.replace(/%/g, "%%")}"`;
-	}
 	return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
-function shellCommand(program, args, windows) {
-	const command = [program, ...args].map((part) => shellQuote$1(part, windows)).join(" ");
-	return windows ? `"${command}"` : command;
+function shellCommand(program, args) {
+	return [program, ...args].map((part) => shellQuote$1(part)).join(" ");
+}
+const WINDOWS_RUN_SAFE = /^[A-Za-z0-9._:\\/-]+$/;
+const WINDOWS_EXE_SAFE = /^[A-Za-z0-9._-]+$/;
+function windowsWorkerScript(script) {
+	if (!WINDOWS_RUN_SAFE.test(script)) throw new Error(`On Windows, AGENTMEMORY_WORKER_BIN_DIR must be a path without spaces or cmd metacharacters; got ${JSON.stringify(script)}.`);
+	return script;
+}
+function windowsNodeRun(nodeBin) {
+	const base = win32.basename(nodeBin);
+	if (!WINDOWS_EXE_SAFE.test(base)) throw new Error(`The Node executable name must not contain spaces or cmd metacharacters on Windows; got ${JSON.stringify(nodeBin)}.`);
+	return `${base} dist/index.mjs`;
+}
+function windowsWorkerPath(nodeBin, inherited) {
+	const entries = [win32.dirname(nodeBin), ...(inherited ?? "").split(";")].map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+	const seen = /* @__PURE__ */ new Set();
+	return entries.filter((entry) => {
+		const key = entry.toLowerCase();
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	}).join(";");
 }
 function yamlString(value) {
 	if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(value)) throw new Error("A Compose path or configuration value contains an unsupported control character.");
@@ -1597,17 +1933,18 @@ function renderWorkerCompose(options) {
 	const { restPort, viewerPort, enginePort } = options.ports;
 	const paths = composeProjectPaths(options.dataDir);
 	const namespace = composeNamespace(restPort);
-	const workerBinDir = options.workerBinDir ? options.workerBinDirIsAbsolute ? resolve(options.workerBinDir) : localWorkerDirectory(options.workerBinDir, options.cwd ?? process.cwd(), options.projectRoot) : null;
+	const windows = options.windows ?? process.platform === "win32";
+	const workerBinDir = options.workerBinDir ? options.workerBinDirIsAbsolute ? windows ? win32.resolve(options.workerBinDir) : resolve(options.workerBinDir) : localWorkerDirectory(options.workerBinDir, options.cwd ?? process.cwd(), options.projectRoot) : null;
 	const startupSeconds = Math.ceil((options.startupTimeoutMs ?? 3e5) / 1e3);
 	const restartEnabled = !options.disableRestartPolicy;
 	if (!Number.isSafeInteger(startupSeconds) || startupSeconds < 1 || startupSeconds * 1e3 > 3600999) throw new Error("Compose worker startup timeout must be between 1 and 3600000 milliseconds.");
 	const workerSource = (name) => workerBinDir ? `path://${localWorkerProjectDir(paths, name)}` : `package://api.workers.iii.dev/${name}`;
-	const workerScript = (name) => workerBinDir ? join(workerBinDir, name) : "";
+	const workerScript = (name) => workerBinDir ? windows ? win32.join(workerBinDir, name) : join(workerBinDir, name) : "";
 	const filteredEnvFile = options.envFile ? join(paths.directory, ".agentmemory-filtered.env") : void 0;
 	const lines = [
 		`namespace: ${namespace}`,
 		"startup_timeout: 60s",
-		"stop_timeout: 20s",
+		`stop_timeout: 20s`,
 		"required_default: true",
 		"engine:",
 		`  url: ws://127.0.0.1:${enginePort}`,
@@ -1623,7 +1960,7 @@ function renderWorkerCompose(options) {
 		"containers:"
 	];
 	const stateScript = workerScript("state");
-	lines.push("  state:", `    worker: ${yamlString(workerSource("state"))}`, ...!workerBinDir ? [`    version: ${yamlString(COMPOSE_WORKER_VERSIONS.state)}`] : [], "    config_name: state", ...restartPolicyLines("    ", restartEnabled), ...workerBinDir ? [`    scripts:`, `      run: ${yamlString(shellCommand(stateScript, [], options.windows ?? process.platform === "win32"))}`] : [], "    config_override:", "      adapter:", "        name: kv", "        config:");
+	lines.push("  state:", `    worker: ${yamlString(workerSource("state"))}`, ...!workerBinDir ? [`    version: ${yamlString(COMPOSE_WORKER_VERSIONS.state)}`] : [], "    config_name: state", ...restartPolicyLines("    ", restartEnabled), ...workerBinDir ? [`    scripts:`, `      run: ${yamlString(windows ? windowsWorkerScript(stateScript) : shellCommand(stateScript, []))}`] : [], "    config_override:", "      adapter:", "        name: kv", "        config:");
 	if (options.stateBackend?.kind === "redis") {
 		const redisUrl = options.redisUrl ?? options.stateBackend.redisUrl;
 		if (!redisUrl) throw new Error("AGENTMEMORY_STATE_BACKEND=redis requires AGENTMEMORY_REDIS_URL to be set (e.g. redis://localhost:6379).");
@@ -1631,11 +1968,11 @@ function renderWorkerCompose(options) {
 		lines.splice(lines.length - 2, 2, "        name: redis", "        config:", `          redis_url: ${yamlString(redisUrl)}`);
 	} else lines.push("          store_method: file_based", `          file_path: ${yamlString(join(options.dataDir, "state_store.db"))}`, `          save_interval_ms: ${stateSaveInterval(options.workerEnvironment?.AGENTMEMORY_STATE_SAVE_INTERVAL_MS)}`);
 	const httpScript = workerScript("http");
-	lines.push("  http:", `    worker: ${yamlString(workerSource("http"))}`, ...!workerBinDir ? [`    version: ${yamlString(COMPOSE_WORKER_VERSIONS.http)}`] : [], "    config_name: http", ...restartPolicyLines("    ", restartEnabled), ...workerBinDir ? [`    scripts:`, `      run: ${yamlString(shellCommand(httpScript, [], options.windows ?? process.platform === "win32"))}`] : [], "    config_override:", "      host: 127.0.0.1", `      port: ${restPort}`, "      default_timeout: 180000", "      cors:", "        allowed_origins:", `          - ${yamlString(`http://localhost:${restPort}`)}`, `          - ${yamlString(`http://localhost:${viewerPort}`)}`, `          - ${yamlString(`http://127.0.0.1:${restPort}`)}`, `          - ${yamlString(`http://127.0.0.1:${viewerPort}`)}`, "        allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]");
-	lines.push("  agentmemory:", `    worker: ${yamlString(`path://${options.projectRoot}`)}`, "    start_after: [state, http]", `    startup_timeout: ${startupSeconds}s`, "    config_name: agentmemory", ...restartPolicyLines("    ", restartEnabled), "    scripts:", `      run: ${yamlString(shellCommand(options.nodeBin, ["dist/index.mjs"], options.windows ?? process.platform === "win32"))}`);
+	lines.push("  http:", `    worker: ${yamlString(workerSource("http"))}`, ...!workerBinDir ? [`    version: ${yamlString(COMPOSE_WORKER_VERSIONS.http)}`] : [], "    config_name: http", ...restartPolicyLines("    ", restartEnabled), ...workerBinDir ? [`    scripts:`, `      run: ${yamlString(windows ? windowsWorkerScript(httpScript) : shellCommand(httpScript, []))}`] : [], "    config_override:", "      host: 127.0.0.1", `      port: ${restPort}`, "      default_timeout: 180000", "      cors:", "        allowed_origins:", `          - ${yamlString(`http://localhost:${restPort}`)}`, `          - ${yamlString(`http://localhost:${viewerPort}`)}`, `          - ${yamlString(`http://127.0.0.1:${restPort}`)}`, `          - ${yamlString(`http://127.0.0.1:${viewerPort}`)}`, "        allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]");
+	lines.push("  agentmemory:", `    worker: ${yamlString(`path://${options.projectRoot}`)}`, "    start_after: [state, http]", `    startup_timeout: ${startupSeconds}s`, "    config_name: agentmemory", ...restartPolicyLines("    ", restartEnabled), "    scripts:", `      run: ${yamlString(windows ? windowsNodeRun(options.nodeBin) : shellCommand(options.nodeBin, ["dist/index.mjs"]))}`);
 	if (filteredEnvFile) lines.push(`    env_file: [${yamlString(filteredEnvFile)}]`);
 	const explicitWorkerEnvironment = Object.entries(options.workerEnvironment ?? {}).filter(([key, value]) => value !== void 0 && AGENTMEMORY_WORKER_ENV_ALLOWLIST.has(key) && !COMPOSE_RESERVED_ENV.has(key)).sort(([left], [right]) => left.localeCompare(right));
-	lines.push("    environment:", ...explicitWorkerEnvironment.map(([key, value]) => `      ${key}: ${yamlString(value)}`), `      HOME: ${yamlString(options.homeDir)}`, `      PATH: ${yamlString(`${dirname(options.nodeBin)}:/usr/local/bin:/usr/bin:/bin`)}`, `      AGENTMEMORY_DATA_DIR: ${yamlString(options.dataDir)}`, `      AGENTMEMORY_RUNTIME_DIR: ${yamlString(options.dataDir)}`, ...filteredEnvFile ? [`      AGENTMEMORY_ENV_FILE: ${yamlString(filteredEnvFile)}`] : [], ...options.stateBackend?.kind === "redis" && options.redisUrl ? [`      AGENTMEMORY_REDIS_URL: ${yamlString(options.redisUrl)}`, "      AGENTMEMORY_STATE_BACKEND: 'redis'"] : [], `      III_ENGINE_PORT: ${yamlString(String(enginePort))}`, `      III_REST_PORT: ${yamlString(String(restPort))}`, `      III_VIEWER_PORT: ${yamlString(String(viewerPort))}`, "      III_TELEMETRY_ENABLED: 'false'", ...options.linux ?? process.platform === "linux" ? ["      MALLOC_ARENA_MAX: '2'"] : [], "");
+	lines.push("    environment:", ...explicitWorkerEnvironment.map(([key, value]) => `      ${key}: ${yamlString(value)}`), ...windows ? [`      NoDefaultCurrentDirectoryInExePath: ${yamlString("1")}`] : [], `      HOME: ${yamlString(options.homeDir)}`, `      PATH: ${yamlString(windows ? windowsWorkerPath(options.nodeBin, options.workerEnvironment?.PATH ?? process.env.PATH) : `${dirname(options.nodeBin)}:/usr/local/bin:/usr/bin:/bin`)}`, `      AGENTMEMORY_DATA_DIR: ${yamlString(options.dataDir)}`, `      AGENTMEMORY_RUNTIME_DIR: ${yamlString(options.dataDir)}`, ...filteredEnvFile ? [`      AGENTMEMORY_ENV_FILE: ${yamlString(filteredEnvFile)}`] : [], ...options.stateBackend?.kind === "redis" && options.redisUrl ? [`      AGENTMEMORY_REDIS_URL: ${yamlString(options.redisUrl)}`, "      AGENTMEMORY_STATE_BACKEND: 'redis'"] : [], `      III_ENGINE_PORT: ${yamlString(String(enginePort))}`, `      III_REST_PORT: ${yamlString(String(restPort))}`, `      III_VIEWER_PORT: ${yamlString(String(viewerPort))}`, "      III_TELEMETRY_ENABLED: 'false'", ...options.linux ?? process.platform === "linux" ? ["      MALLOC_ARENA_MAX: '2'"] : [], "");
 	return lines.join("\n");
 }
 function writeWorkerCompose(options) {
@@ -1731,7 +2068,7 @@ function composeStateRegistryFailure(dataDir, file) {
 		for (const stateFile of files) {
 			const state = JSON.parse(readFileSync(stateFile, "utf8"));
 			const message = Object.entries(state.containers ?? {}).filter(([, value]) => value.status === "failed").map(([name, value]) => `${name}: ${value.last_error ?? "failed"}`).join("\n");
-			if (state.compose_path !== file) continue;
+			if (!sameComposeFile(state.compose_path, file)) continue;
 			if (message && composeRegistryFailureMessage(message)) return message;
 		}
 	} catch {}
@@ -1743,8 +2080,30 @@ function composeWorkerFailureSummary(project) {
 	if (!failed.length) return null;
 	return failed.map((container) => `${container.container ?? "worker"}: ${container.last_error ?? "failed after restart attempts were exhausted"}`).join("\n");
 }
-function ownedComposeProject(status, file) {
-	return status.file === file ? status : status.projects?.find((item) => item.file === file) ?? null;
+function defaultCanonicalizer(windows) {
+	return (value) => {
+		try {
+			return windows ? realpathSync.native(value) : realpathSync(value);
+		} catch {
+			return value;
+		}
+	};
+}
+function normalizeWindowsPath(value) {
+	let out = value;
+	if (out.startsWith("\\\\?\\UNC\\")) out = `\\\\${out.slice(8)}`;
+	else if (out.startsWith("\\\\?\\")) out = out.slice(4);
+	return out.replace(/\//g, "\\").toLowerCase();
+}
+function sameComposeFile(left, right, windows = process.platform === "win32", canonicalize = defaultCanonicalizer(windows)) {
+	if (!left) return false;
+	if (!windows) return left === right || canonicalize(left) === canonicalize(right);
+	if (normalizeWindowsPath(left) === normalizeWindowsPath(right)) return true;
+	return normalizeWindowsPath(canonicalize(left)) === normalizeWindowsPath(canonicalize(right));
+}
+function ownedComposeProject(status, file, windows = process.platform === "win32", canonicalize = defaultCanonicalizer(windows)) {
+	if (sameComposeFile(status.file, file, windows, canonicalize)) return status;
+	return status.projects?.find((item) => sameComposeFile(item.file, file, windows, canonicalize)) ?? null;
 }
 function cleanDaemonEnv(env) {
 	const out = {};
@@ -1794,8 +2153,29 @@ function composeEnvironment(env, stateDir) {
 		...env.AGENTMEMORY_DISABLE_COMPOSE_RESTART === "1" ? { AGENTMEMORY_DISABLE_COMPOSE_RESTART: "1" } : {}
 	};
 }
-async function composeCall(options) {
-	const client = registerWorker(options.engineUrl, {
+let quietDepth = 0;
+let savedDebug = null;
+async function withQuietSdkDebug(run) {
+	if (quietDepth === 0) {
+		savedDebug = console.debug;
+		console.debug = () => {};
+	}
+	quietDepth++;
+	try {
+		return await run();
+	} finally {
+		quietDepth--;
+		if (quietDepth === 0 && savedDebug) {
+			console.debug = savedDebug;
+			savedDebug = null;
+		}
+	}
+}
+async function composeCall(options, register = registerWorker) {
+	return withQuietSdkDebug(() => composeCallWithClient(options, register));
+}
+async function composeCallWithClient(options, register) {
+	const client = register(options.engineUrl, {
 		workerName: "agentmemory-cli",
 		namespace: options.namespace,
 		invocationTimeoutMs: options.timeoutMs ?? 3e4,
@@ -2253,8 +2633,20 @@ function fallbackIiiPaths() {
 	paths.push("/usr/local/bin/iii");
 	return paths;
 }
+const III_VERSION_PROBE_TIMEOUTS_MS = [3e3, 3e4];
+function isProbeTimeout(err) {
+	const e = err;
+	return e?.code === "ETIMEDOUT" || e?.signal === "SIGTERM";
+}
+let iiiProbeScan = null;
 function iiiBinVersion(binPath) {
-	try {
+	if (iiiProbeScan?.has(binPath)) return iiiProbeScan.get(binPath);
+	const version = probeIiiVersion(binPath);
+	iiiProbeScan?.set(binPath, version);
+	return version;
+}
+function probeIiiVersion(binPath) {
+	for (const timeout of III_VERSION_PROBE_TIMEOUTS_MS) try {
 		const match = execFileSync(binPath, ["--version"], {
 			encoding: "utf-8",
 			stdio: [
@@ -2262,12 +2654,14 @@ function iiiBinVersion(binPath) {
 				"pipe",
 				"ignore"
 			],
-			timeout: 3e3
+			timeout
 		}).match(/(\d+\.\d+\.\d+(?:[-+][\w.]+)?)/);
 		return match ? match[1] : null;
-	} catch {
-		return null;
+	} catch (err) {
+		if (!isProbeTimeout(err)) return null;
+		vlog(`iii --version at ${binPath} timed out after ${timeout}ms`);
 	}
+	return null;
 }
 function resolveCompatibleIii(iiiBinPath) {
 	if (!iiiBinPath) return null;
@@ -2434,7 +2828,7 @@ async function startWorkerForEngineState(background = false) {
 				child.unref();
 			} else {
 				importedStartupWorker = true;
-				await import("./src-DaMtDzt_.mjs");
+				await import("./src-C23nMpda.mjs");
 			}
 		},
 		probe: workerReadinessProbe,
@@ -2514,8 +2908,8 @@ async function maybeOfferGlobalInstall() {
 	if (runCommand(npmBin, [
 		"install",
 		"-g",
-		`@agentmemory/agentmemory@0.9.31`
-	], { label: `Installing @agentmemory/agentmemory@0.9.31 globally` })) {
+		`@agentmemory/agentmemory@0.9.32`
+	], { label: `Installing @agentmemory/agentmemory@0.9.32 globally` })) {
 		p.log.success("Installed globally. `agentmemory stop` etc. will now work in new shells.");
 		writePrefs({ skipGlobalInstall: true });
 	} else p.log.warn("Global install failed. Try manually: npm install -g @agentmemory/agentmemory");
@@ -2532,7 +2926,28 @@ async function runIiiInstaller() {
 		};
 	}
 	if (IS_WINDOWS || isZipAsset) {
-		p.log.info(`Auto-install unavailable on ${platform()} — ${asset} isn't tar-compatible. Install manually:\n  1. Download ${releaseUrl}\n     Its SHA-256 must be ${expectedIiiSha256(IIPINNED_VERSION, asset ?? "") ?? `the value in ${releaseUrl.replace(/\.zip$/, ".sha256")}`}\n  2. Extract iii.exe and place it on PATH (e.g. %USERPROFILE%\\.local\\bin)\nInstall the pinned iii binary from ${releaseUrl}`);
+		const binDir = agentmemoryBinDir();
+		const binPath = privateIiiPath();
+		const label = `Installing iii-engine v${IIPINNED_VERSION} (pinned)`;
+		const spinner = p.spinner();
+		spinner.start(label);
+		const outcome = await installIiiZip({
+			releaseUrl,
+			version: IIPINNED_VERSION,
+			asset: asset ?? "",
+			binDir,
+			binPath
+		});
+		if (outcome.ok) {
+			spinner.stop(`${label} ${pc.green("✓")}`);
+			iiiProbeScan?.delete(binPath);
+			return {
+				ok: true,
+				binPath
+			};
+		}
+		spinner.stop(`${label} ${pc.red("✗")}`);
+		p.log.warn(`iii-engine auto-install failed: ${outcome.detail.slice(0, 300)}\nInstall it manually, then re-run agentmemory:\n  1. Download ${releaseUrl}\n     Its SHA-256 must be ${expectedIiiSha256(IIPINNED_VERSION, asset ?? "") ?? `the value in ${releaseUrl.replace(/\.zip$/, ".sha256")}`}\n  2. Extract iii.exe into ${binDir}`);
 		return {
 			ok: false,
 			binPath: null
@@ -2578,6 +2993,7 @@ async function runIiiInstaller() {
 		};
 	}
 	spinner.stop(`${label} ${pc.green("✓")}`);
+	iiiProbeScan?.delete(binPath);
 	return {
 		ok: true,
 		binPath
@@ -2679,6 +3095,12 @@ function printComposeStartupLogs() {
 	if (logs.text) p.note(`Log file: ${logs.path}\n\n${logs.text}`, "Recent Worker Compose output");
 }
 function composePidMatches(pid, state) {
+	return composePidIdentity(pid, state) === "match";
+}
+function composePidIdentity(pid, state) {
+	return classifyComposeProcess(inspectComposeProcess(pid), state, IS_WINDOWS);
+}
+function inspectComposeProcess(pid) {
 	try {
 		let command = "";
 		let executable = "";
@@ -2730,11 +3152,12 @@ function composePidMatches(pid, state) {
 			}).trim();
 			executable = readUnixProcessExecutable(pid, "linux");
 		}
-		if (!(command.includes("compose") && command.includes("compose --namespace") && command.includes(state.namespace) && command.includes(state.file))) return false;
-		if (!executable) return false;
-		return sameResolvedExecutable(executable, state.binPath, IS_WINDOWS);
+		return {
+			command,
+			executable
+		};
 	} catch {
-		return false;
+		return null;
 	}
 }
 function composeChildProcesses(state) {
@@ -2895,6 +3318,14 @@ function pickCompatibleIii(candidates) {
 	return null;
 }
 async function startEngine() {
+	iiiProbeScan = /* @__PURE__ */ new Map();
+	try {
+		return await scanAndStartEngine();
+	} finally {
+		iiiProbeScan = null;
+	}
+}
+async function scanAndStartEngine() {
 	startupFailure = null;
 	engineReadinessDeadline = null;
 	let stateBackendKind;
@@ -2931,7 +3362,7 @@ async function startEngine() {
 	const pathIii = whichBinary("iii");
 	vlog(`iii binary: ${pathIii ?? "(not on PATH)"}`);
 	const fallbacks = fallbackIiiPaths().filter((p) => existsSync(p));
-	for (const f of fallbacks) vlog(`fallback iii at ${f} reports version: ${iiiBinVersion(f) ?? "unknown"}`);
+	vlog(`fallback iii candidates: ${fallbacks.length > 0 ? fallbacks.join(", ") : "(none)"}`);
 	let iiiBin = pickCompatibleIii([pathIii, ...fallbacks]);
 	if (iiiBin) {
 		if (iiiBin !== pathIii) {
@@ -2948,6 +3379,9 @@ async function startEngine() {
 		choice = "install";
 		const detected = iiiBinVersion(pathIii);
 		p.log.info(`iii on PATH is v${detected ?? "unknown"} but agentmemory pins v${IIPINNED_VERSION}. Installing pinned engine to ~/.agentmemory/bin (leaves your existing iii untouched).`);
+	} else if (IS_WINDOWS) {
+		choice = "install";
+		p.log.warn("iii-engine binary not found locally.");
 	} else if (!interactive) {
 		choice = "install";
 		p.log.info("Non-interactive environment detected — auto-installing iii-engine.");
@@ -3020,7 +3454,7 @@ function installInstructions() {
 			`     1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`,
 			`     2. Download iii-x86_64-pc-windows-msvc.zip (or iii-aarch64-pc-windows-msvc.zip on ARM)`,
 			verify,
-			"     3. Extract iii.exe to %USERPROFILE%\\.local\\bin\\iii.exe (or add to PATH)",
+			"     3. Extract iii.exe to %USERPROFILE%\\.agentmemory\\bin\\iii.exe (or add to PATH)",
 			"     4. Re-run: npx @agentmemory/agentmemory",
 			"",
 			"Or skip the engine entirely (standalone MCP):  npx @agentmemory/agentmemory mcp",
@@ -3062,7 +3496,7 @@ async function reconcilePersistedComposeEngine() {
 	const state = readEngineState();
 	if (state?.kind !== "compose") return false;
 	if (!await isEngineRunning()) {
-		if (state.composePid && pidAlive(state.composePid)) {
+		if (state.composePid && pidAlive(state.composePid) && composePidIdentity(state.composePid, state) !== "foreign") {
 			p.log.error(`Worker Compose daemon ${state.composePid} is alive but REST ${state.restPort} is not ready. Inspect ${state.logFile}; use agentmemory stop to reconcile.`);
 			process.exit(1);
 		}
@@ -3330,13 +3764,15 @@ async function runStatus() {
 			lines.push(`  Injected:     ~${estInjectedTokens.toLocaleString()} tokens`);
 		}
 		if (flagsRes) {
-			const provider = flagsRes.provider === "llm" ? pc.green("✓ llm") : pc.yellow("✗ noop (no key)");
+			const provider = flagsRes.provider === "llm" ? pc.green("✓ llm") : pc.yellow("✗ noop (LLM features off)");
 			const embedding = embeddingStatusLabel(flagsRes.embeddingProvider);
 			const embed = embedding ? pc.green(`✓ ${embedding}`) : pc.dim("bm25-only");
 			const flagRows = (flagsRes.flags || []).map((f) => `  ${f.enabled ? pc.green("✓") : pc.dim("✗")} ${pc.bold(f.key.padEnd(32))} ${f.label}`);
 			lines.push("");
 			lines.push(`Provider:     ${provider}`);
 			lines.push(`Embeddings:   ${embed}`);
+			if (typeof flagsRes.providerHint === "string") lines.push(pc.yellow(`  ${flagsRes.providerHint}`));
+			if (typeof flagsRes.embeddingHint === "string") lines.push(pc.yellow(`  ${flagsRes.embeddingHint}`));
 			lines.push(`Flags:`);
 			flagRows.forEach((r) => lines.push(r));
 		}
@@ -3452,6 +3888,11 @@ function buildDoctorEffects() {
 			return state?.kind === "compose" ? state.binPath : privateIiiPath();
 		},
 		iiiBinaryVersion: (binPath) => iiiBinVersion(binPath),
+		externalEngineRunning: async () => {
+			const state = readEngineState();
+			const remoteTarget = shouldUseAgentmemoryUrl() && process.env["AGENTMEMORY_URL"];
+			return !(state?.kind === "compose" && state.restPort === getRestPort() && !remoteTarget) && await isEngineRunning();
+		},
 		viewerReachable: async (timeoutMs = 2e3) => {
 			try {
 				await discoverViewerPort();
@@ -3595,11 +4036,11 @@ async function passiveServerChecks() {
 	}, {
 		name: "LLM provider",
 		ok: hasLlm,
-		hint: hasLlm ? void 0 : "set ANTHROPIC_API_KEY (or GEMINI/OPENROUTER/MINIMAX) in ~/.agentmemory/.env"
+		hint: hasLlm ? void 0 : typeof flags?.providerHint === "string" ? flags.providerHint : "set AGENTMEMORY_LLM_PROVIDER and that provider's key (for example ANTHROPIC_API_KEY) in ~/.agentmemory/.env"
 	}, {
 		name: "Embedding provider",
 		ok: hasEmbed,
-		hint: hasEmbed ? void 0 : "Running BM25-only. Set EMBEDDING_PROVIDER=local for on-device semantic search, or add OPENAI_API_KEY / VOYAGE_API_KEY / COHERE_API_KEY / OLLAMA_HOST"
+		hint: hasEmbed ? void 0 : typeof flags?.embeddingHint === "string" ? flags.embeddingHint : "Running BM25-only. Set EMBEDDING_PROVIDER=local for on-device semantic search, or EMBEDDING_PROVIDER=openai, voyage, cohere, gemini or openrouter with that provider's key"
 	});
 	for (const f of flags?.flags || []) checks.push({
 		name: f.label,
@@ -3703,6 +4144,8 @@ async function runDoctor() {
 	let fixed = 0;
 	let skipped = 0;
 	let quit = false;
+	const promptsAllowed = doctorPromptsAllowed(process.env, process.stdin.isTTY, process.stdout.isTTY);
+	let autoFixHintShown = false;
 	for (const d of diagnostics) {
 		if (quit) {
 			skipped++;
@@ -3715,13 +4158,25 @@ async function runDoctor() {
 		}
 		failed++;
 		p.log.warn(`${d.id} ✗ ${status.detail ?? ""}`.trim());
+		if (!canAutoFix(d, status)) {
+			p.log.info(`manual fix: ${status.manualFix ?? d.fixPreview}`);
+			skipped++;
+			continue;
+		}
 		p.log.info(`why: ${d.fixPreview}`);
-		if (d.manualOnly) p.log.info(`(manual fix only — see "${d.id}" docs)`);
 		if (applyAll) {
 			if ((await applyFixWithReport(d, ctx, false)).ok) fixed++;
 			if (!(await d.check(ctx)).ok) p.log.warn(`${d.id} still failing after fix.`);
 			continue;
 		}
+		if (!promptsAllowed) {
+			skipped++;
+			if (!autoFixHintShown) {
+				autoFixHintShown = true;
+				p.log.info("Not prompting in a non-interactive shell. Run `agentmemory doctor --all` to apply the fixes.");
+			}
+			continue;
+		}
 		while (true) {
 			const action = await askFixAction(d);
 			if (action === "fix") {
@@ -3938,7 +4393,7 @@ async function runInit() {
 		"All keys are commented out by default. Uncomment the ones you want.",
 		"",
 		"Common next steps:",
-		"  1. Pick an LLM provider key (ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / etc.)",
+		"  1. Optional: to send session content to an LLM for summaries, set AGENTMEMORY_LLM_PROVIDER and that provider's key (for example ANTHROPIC_API_KEY)",
 		"  2. Run `npx @agentmemory/agentmemory doctor` to verify the daemon sees them",
 		"  3. Run `npx @agentmemory/agentmemory` to start the worker"
 	].join("\n"), "Next steps");
@@ -4016,7 +4471,7 @@ async function runDemoBody(base) {
 		...semanticHits > 0 ? [c.accent(`Notice: searching "database performance optimization"`), c.accent(`found the N+1 query fix — keyword matching can't do that.`)] : [
 			c.dim(`Note: "database performance optimization" found nothing —`),
 			c.dim(`set EMBEDDING_PROVIDER=local for on-device semantic recall,`),
-			c.dim(`or add an embedding API key in ~/.agentmemory/.env.`)
+			c.dim(`or set EMBEDDING_PROVIDER and its API key in ~/.agentmemory/.env.`)
 		],
 		"",
 		`Viewer:        ${c.url(getViewerUrl())}`,
@@ -4313,7 +4768,7 @@ async function runStop() {
 				namespace: state.namespace,
 				functionId: "compose::down",
 				file: state.file,
-				timeoutMs: 6e4
+				timeoutMs: composeDownTimeoutMs()
 			});
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
@@ -4416,10 +4871,10 @@ async function runStop() {
 	p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
 }
 async function runMcp() {
-	await import("./standalone-BlqshyZ5.mjs");
+	await import("./standalone-BYo5USDb.mjs");
 }
 async function runConnectCmd() {
-	const { runConnect } = await import("./connect-BSLIAMpw.mjs").then((n) => n.n);
+	const { runConnect } = await import("./connect-BX3njQ3Y.mjs").then((n) => n.n);
 	await runConnect(args.slice(1));
 }
 async function runImportJsonl() {