@agentmemory/agentmemory 0.9.30 → 0.9.32

package/dist/cli.mjs

@@ -1,18 +1,27 @@
 #!/usr/bin/env node
-import { a as runAdapter, i as resolveAdapter, r as knownAgents, t as ADAPTERS } from "./connect-B4_ca6BD.mjs";
-import { o as generateId } from "./keyed-mutex-DchXsyfP.mjs";
-import { I as hydrateProcessEnvFromFile, M as getStateSaveIntervalMs, O as getRedisUrl, _ as VERSION, at as isBundledConfig, ct as resolveEngineCwd, dt as runtimeConfigPath, g as III_PINNED_VERSION, gt as renderEngineConfig, ht as engineStateConfigPaths, i as resolveClientSecret, it as engineChildEnv, j as getStateBackend, lt as resolveLaunchRenderFailure, m as getAllTools, mt as engineFlushWaitMs, nt as dockerComposeArgs, ot as legacyDataMigrations, p as ESSENTIAL_TOOLS, pt as clearPersistedBuiltinConfig, rt as dockerProjectName, st as redactCredentialUrls, t as bearerHeaders, tt as setBootVerbose, ut as rewriteBundledConfig } from "./secret-store-BnY3A50C.mjs";
-import { A as SHUTDOWN_HARD_EXIT_MS, C as spoolSummary, M as runtimeMetadataPath, O as resolveDataDir, _ as drainSpool, b as retainSent, t as CURL_AUTH_HEADER, v as parseSentMark } from "./status-IRz7ta8-.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 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, closeSync, constants, cpSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
-import { delimiter, dirname, join, resolve } from "node:path";
+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 { 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([
 	"",
@@ -31,20 +40,7 @@ const PROVIDER_KEY_NAMES = [
 	"OPENROUTER_API_KEY",
 	"MINIMAX_API_KEY"
 ];
-function parseEnvFile(content) {
-	const out = {};
-	for (const rawLine of content.split(/\r?\n/)) {
-		const line = rawLine.trim();
-		if (!line || line.startsWith("#")) continue;
-		const eq = line.indexOf("=");
-		if (eq < 0) continue;
-		const key = line.slice(0, eq).trim();
-		let value = line.slice(eq + 1).trim();
-		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
-		out[key] = value;
-	}
-	return out;
-}
+const parseEnvFile = parseEnvContent;
 /** Returns the list of provider keys that look real (non-placeholder). */
 function realProviderKeys(env) {
 	return PROVIDER_KEY_NAMES.filter((k) => {
@@ -71,7 +67,7 @@ function buildDiagnostics(effects) {
 			id: "env-missing",
 			message: "~/.agentmemory/.env is missing.",
 			fixPreview: "Copy .env.example into ~/.agentmemory/.env (your keys file).",
-			moreInfo: "agentmemory reads provider API keys (Anthropic, OpenAI, Gemini, …) from ~/.agentmemory/.env. Without this file the daemon falls back to BM25-only search and no LLM-backed enrichment runs.",
+			moreInfo: "agentmemory reads provider API keys (Anthropic, OpenAI, Gemini, …) from ~/.agentmemory/.env. Without this file, and without a provider key exported in the environment, the daemon falls back to BM25-only search and no LLM-backed enrichment runs.",
 			check: async () => ({
 				ok: effects.envFileExists(),
 				detail: effects.envFileExists() ? void 0 : "no env file"
@@ -80,44 +76,97 @@ function buildDiagnostics(effects) {
 		},
 		{
 			id: "no-llm-provider-key",
-			message: "No LLM provider API key found in ~/.agentmemory/.env.",
-			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, OPENROUTER_API_KEY, MINIMAX_API_KEY. The daemon picks the first that resolves to a real (non-placeholder) value at startup.",
+			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 () => {
-				if (!effects.envFileExists()) return {
-					ok: false,
-					detail: "env file missing (run env-missing fix first)"
+				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") {
+					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 {
+					ok: true,
+					detail: "agent-sdk fallback, no API key"
 				};
-				const real = realProviderKeys(effects.readEnvFile());
+				const caveat = fromEnv.length > 0 ? "; a daemon started elsewhere will not see it" : "";
 				return {
-					ok: real.length > 0,
-					detail: real.length > 0 ? `found: ${real.join(", ")}` : "no provider key set"
+					ok: true,
+					detail: `found: ${named.join(", ")}${caveat}`
 				};
 			},
 			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.",
-			fixPreview: "Re-run the iii installer for the pinned version and restart the engine.",
-			moreInfo: "agentmemory pins the iii engine to a specific release because newer engines use a different worker model. Running a mismatched binary surfaces as EPIPE reconnect loops and empty search results.",
+			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. 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();
@@ -142,8 +191,8 @@ function buildDiagnostics(effects) {
 		{
 			id: "stale-pidfile",
 			message: "Stale pidfile: pid recorded but the process is gone.",
-			fixPreview: "Clear ~/.agentmemory/iii.pid + engine-state.json, then restart.",
-			moreInfo: "When the engine crashes hard (kill -9, OOM, host reboot) the pidfile sticks around. agentmemory refuses to start a second engine on top of a stale pid, so this state must be cleared explicitly.",
+			fixPreview: "Verify the Compose daemon ownership record and restart only the managed project.",
+			moreInfo: "When a managed Compose daemon crashes hard (kill -9, OOM, host reboot), its ownership PID can stick around. The check uses the saved Compose process, never a legacy iii.pid from a previous lifecycle.",
 			check: async () => {
 				if (!effects.pidfileExists()) return {
 					ok: true,
@@ -184,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) => ({
@@ -218,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.`);
@@ -400,15 +454,22 @@ function portFlagSuffix(restPort, instance) {
 	if (instance > 0 && restPort === DEFAULT_REST_PORT + instance * 100) return ` --instance ${instance}`;
 	return restPort === DEFAULT_REST_PORT ? "" : ` --port ${restPort}`;
 }
+//#endregion
+//#region src/cli/embedding-status.ts
+function embeddingStatusLabel(provider) {
+	if (typeof provider !== "string") return null;
+	const value = provider.trim();
+	return value && value !== "none" ? value : null;
+}
 const III_INSTALL_SPAWN_TIMEOUT_MS = 345 * 1e3;
-const III_RELEASE_SHA256 = { "0.22.1": {
-	"iii-aarch64-apple-darwin.tar.gz": "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4",
-	"iii-x86_64-apple-darwin.tar.gz": "6d33940db2d3ad6a9aef9837aa5b89bf5c5e4acd0679e8178fec258af229d7e1",
-	"iii-x86_64-unknown-linux-gnu.tar.gz": "34d4bd2ec1873e6114bb836be7db9cb3f410d0d63353d240917f0bc9c30df13b",
-	"iii-aarch64-unknown-linux-gnu.tar.gz": "87efc60210c1580ef2e11b13c679a4dad91917a9d80f737c5ba7e3475b3ca413",
-	"iii-armv7-unknown-linux-gnueabihf.tar.gz": "af5dfc45149678c647e5adaca55c055428eebfa73d65884b052c30c98abcfd19",
-	"iii-x86_64-pc-windows-msvc.zip": "d862bf7cf1e864f3290c8a6fc17c308c6ecac097cb2666e4a739efc0040aae96",
-	"iii-aarch64-pc-windows-msvc.zip": "4777a48cee3fc1a742daee929e3d943df09e4ddd3357d27a33d31c9dc9e520ac"
+const III_RELEASE_SHA256 = { "0.25.0": {
+	"iii-aarch64-apple-darwin.tar.gz": "5f23087a41ce1cf86f9859d2f430d1809a1e048094e69b1df0cdf1ebefc2a985",
+	"iii-x86_64-apple-darwin.tar.gz": "e2ac4ef109ddbf459b4683171c6b5b9c8366b16dac2e1f8c4fe08b4a4e19d49a",
+	"iii-x86_64-unknown-linux-gnu.tar.gz": "4c4d14063eb55d79663db553e960497731420df6d78eca3aafe670e2fbaba8e2",
+	"iii-aarch64-unknown-linux-gnu.tar.gz": "5e52d4738a0beb609f4d32970d37be7c00d4848ee9d06300248498a00ea4bf0e",
+	"iii-armv7-unknown-linux-gnueabihf.tar.gz": "9ee840351ff62c889b929b618f8cbb2d66d616cecf82cde7c26d4618aa137508",
+	"iii-x86_64-pc-windows-msvc.zip": "b80ea5c3408879380b6ce95f7b2855ce161d68642aeec8f7b54f104794cbb322",
+	"iii-aarch64-pc-windows-msvc.zip": "2b1e222b90ee18ed143186e8b307d8ad2076f44ea00fa7a7d071bd3c87cde002"
 } };
 function expectedIiiSha256(version, asset, checksums = III_RELEASE_SHA256) {
 	return checksums[version]?.[asset] ?? null;
@@ -500,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) {
@@ -518,66 +824,147 @@ function createStartupStderrCapture(maxBytes = 16 * 1024) {
 	};
 }
 //#endregion
-//#region src/cli/console.ts
-const GLOBAL_VALUE_FLAGS = new Set([
-	"--port",
-	"--instance",
-	"--data-dir",
-	"--tools"
-]);
-const GLOBAL_BOOLEAN_FLAGS = new Set([
-	"--verbose",
-	"-v",
-	"--no-engine"
-]);
-function defaultConsolePort(viewerPort) {
-	return viewerPort + 1;
-}
-function readPort(raw, flag) {
-	const port = raw === void 0 ? NaN : Number(raw);
-	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`${flag} needs a port between 1 and 65535`);
-	return port;
+//#region src/cli/readiness.ts
+const DEFAULT_ENGINE_TIMEOUT_MS = 12e4;
+const DEFAULT_WORKER_TIMEOUT_MS = 3e5;
+const MAX_STARTUP_TIMEOUT_MS = 36e5;
+function startupTimeouts(env = process.env) {
+	const parse = (key, fallback) => {
+		const raw = env[key];
+		if (raw === void 0) return fallback;
+		const value = Number(raw);
+		if (!/^\d+$/.test(raw) || !Number.isSafeInteger(value) || value < 1 || value > 36e5) throw new Error(`${key} must be an integer between 1 and ${MAX_STARTUP_TIMEOUT_MS} milliseconds.`);
+		return value;
+	};
+	const ownership = env.AGENTMEMORY_ENGINE_MANAGES_WORKER;
+	if (ownership !== void 0 && ownership !== "true" && ownership !== "false") throw new Error("AGENTMEMORY_ENGINE_MANAGES_WORKER must be true or false.");
+	return {
+		engineMs: parse("AGENTMEMORY_ENGINE_READY_TIMEOUT_MS", DEFAULT_ENGINE_TIMEOUT_MS),
+		workerMs: parse("AGENTMEMORY_READY_TIMEOUT_MS", DEFAULT_WORKER_TIMEOUT_MS),
+		engineManagesWorker: ownership === void 0 ? void 0 : ownership === "true"
+	};
 }
-function parseConsoleArgs(tail, fallbackPort) {
-	let consolePort = fallbackPort;
-	const extraArgs = [];
-	for (let i = 0; i < tail.length; i++) {
-		const arg = tail[i];
-		if (arg === "--console-port") {
-			consolePort = readPort(tail[i + 1], arg);
-			i++;
-			continue;
+function configStartsAgentmemoryWorker(raw, workerEntry, engineCwd) {
+	const lines = raw.split(/\r?\n/);
+	let workerIndent;
+	let execIndent;
+	for (const line of lines) {
+		if (!line.trim() || line.trimStart().startsWith("#")) continue;
+		const indent = line.length - line.trimStart().length;
+		if (workerIndent !== void 0 && indent <= workerIndent) {
+			workerIndent = void 0;
+			execIndent = void 0;
 		}
-		if (arg.startsWith("--console-port=")) {
-			consolePort = readPort(arg.slice(15), "--console-port");
+		if (/^\s*-\s+name:\s*(?:iii-exec|"iii-exec"|'iii-exec')(?:\s+#.*)?\s*$/.test(line)) {
+			workerIndent = indent;
 			continue;
 		}
-		if (GLOBAL_VALUE_FLAGS.has(arg)) {
-			i++;
+		if (workerIndent === void 0) continue;
+		if (execIndent !== void 0 && indent <= execIndent) execIndent = void 0;
+		if (/^\s*exec:\s*(?:#.*)?$/.test(line)) {
+			execIndent = indent;
 			continue;
 		}
-		if ([...GLOBAL_VALUE_FLAGS].some((flag) => arg.startsWith(`${flag}=`))) continue;
-		if (GLOBAL_BOOLEAN_FLAGS.has(arg)) continue;
-		extraArgs.push(arg);
+		if (execIndent === void 0) continue;
+		const scalar = line.match(/^\s*-\s+(.+)$/)?.[1]?.trim();
+		if (!scalar) continue;
+		const quoted = scalar.match(/^(["'])(.*?)\1(?:\s+#.*)?$/);
+		const tokens = (quoted ? quoted[2] : scalar).match(/"[^"]*"|'[^']*'|[^\s]+/g)?.map((token) => token.replace(/^("|')(.*)\1$/, "$2").replaceAll("\\", "/"));
+		if (!tokens) continue;
+		const comment = tokens.findIndex((token) => token.startsWith("#"));
+		if (comment !== -1) tokens.splice(comment);
+		const runtime = tokens[0]?.split("/").at(-1);
+		if (runtime !== "node" && runtime !== "node.exe" && runtime !== "tsx") continue;
+		if (runtime !== "tsx") while (tokens[1] && /^(?:--max[-_]old[-_]space[-_]size=\d+|--enable-source-maps|--no-warnings)$/.test(tokens[1])) tokens.splice(1, 1);
+		const entry = tokens.length === 2 ? tokens[1] : tokens.length === 4 && tokens[1] === "--import" && tokens[2] === "tsx" ? tokens[3] : void 0;
+		if (entry === workerEntry.replaceAll("\\", "/")) return true;
+		if (entry === "dist/index.mjs" || entry === "./dist/index.mjs" || entry === "src/index.ts" || entry === "./src/index.ts") {
+			if (engineCwd === void 0) return true;
+			try {
+				if (statSync(join(engineCwd, entry)).isFile()) return true;
+			} catch {}
+		}
 	}
-	return {
-		consolePort,
-		extraArgs
-	};
+	return false;
 }
-function consoleArgs(launch) {
-	return [
-		"console",
-		"--port",
-		String(launch.consolePort),
-		"--engine-port",
-		String(launch.restPort),
-		"--ws-port",
-		String(launch.streamPort),
-		"--bridge-port",
-		String(launch.enginePort),
-		...launch.extraArgs
-	];
+function startupTimeoutMessage(kind, timeoutMs) {
+	const name = kind === "engine" ? "iii-engine" : "agentmemory worker";
+	const variable = kind === "engine" ? "AGENTMEMORY_ENGINE_READY_TIMEOUT_MS" : "AGENTMEMORY_READY_TIMEOUT_MS";
+	return `${name} did not become ready within ${timeoutMs / 1e3}s. Set ${variable} to allow more startup time.`;
+}
+function startupDeadline(timeoutMs) {
+	const deadline = performance.now() + timeoutMs;
+	return { remaining: () => Math.max(0, deadline - performance.now()) };
+}
+/** Probe the loopback REST listener owned by this managed Compose instance.
+* Client commands may honor AGENTMEMORY_URL, but startup readiness must always
+* target the endpoint that this process asked Compose to create. */
+function managedComposeReadinessUrl(restPort) {
+	if (!Number.isInteger(restPort) || restPort < 1 || restPort > 65535) throw new Error(`Invalid managed Compose REST port: ${restPort}`);
+	return `http://127.0.0.1:${restPort}`;
+}
+async function withinStartupDeadline(deadline, work, maximumMs = Infinity) {
+	const remaining = Math.min(deadline.remaining(), maximumMs);
+	if (remaining <= 0) return { completed: false };
+	const controller = new AbortController();
+	let timer;
+	const expired = new Promise((resolve) => {
+		timer = setTimeout(() => {
+			controller.abort();
+			resolve({ completed: false });
+		}, Math.ceil(remaining));
+	});
+	try {
+		const result = await Promise.race([Promise.resolve().then(() => work(controller.signal)).then((value) => ({
+			completed: true,
+			value
+		})), expired]);
+		return deadline.remaining() > 0 ? result : { completed: false };
+	} finally {
+		clearTimeout(timer);
+		controller.abort();
+	}
+}
+async function waitForReadiness(deadline, probe, options = {}) {
+	while (deadline.remaining() > 0 && !options.stopped?.()) {
+		const result = await withinStartupDeadline(deadline, probe, options.probeTimeoutMs ?? 1e3).catch(() => ({ completed: false }));
+		if (options.stopped?.()) return false;
+		if (result.completed && result.value) return true;
+		const remaining = deadline.remaining();
+		if (remaining <= 0) break;
+		const pause = Math.min(options.intervalMs ?? 250, remaining);
+		if (pause > 0) await new Promise((resolve) => setTimeout(resolve, pause));
+	}
+	return false;
+}
+async function probeEngine(base, signal) {
+	if (signal.aborted) return false;
+	(await fetch(`${base}/`, { signal })).body?.cancel().catch(() => {});
+	return true;
+}
+async function probeWorker(base, signal, onViewerPort) {
+	if (signal.aborted) return false;
+	const response = await fetch(`${base}/agentmemory/livez`, { signal });
+	if (!response.ok) {
+		response.body?.cancel().catch(() => {});
+		return false;
+	}
+	const data = await response.json();
+	if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+	const { viewerPort, viewerSkipped } = data;
+	if (typeof viewerPort === "number" && Number.isInteger(viewerPort) && viewerPort > 0 && viewerPort <= 65535) {
+		onViewerPort?.(viewerPort);
+		return true;
+	}
+	return viewerSkipped === true;
+}
+async function startWorkerAndWait(options) {
+	const deadline = startupDeadline(options.timeoutMs);
+	if (options.stopped?.()) return false;
+	if (!options.hasLiveWorker() && !options.engineStartsWorker()) {
+		if (!(await withinStartupDeadline(deadline, () => options.startWorker())).completed) return false;
+	}
+	return waitForReadiness(deadline, options.probe, { stopped: options.stopped });
 }
 //#endregion
 //#region src/cli/process-state.ts
@@ -585,6 +972,70 @@ function processStatIsRunning(stat) {
 	return !stat.trimStart().startsWith("Z");
 }
 //#endregion
+//#region src/cli/compose-process.ts
+/**
+* On macOS, ask lsof for the process's text executable and accept only a
+* response explicitly associated with this PID. The `-d txt` filter limits
+* names to text descriptors (the process executable).
+*/
+function readMacProcessExecutable(pid) {
+	if (!Number.isSafeInteger(pid) || pid <= 0) return "";
+	try {
+		const output = execFileSync("lsof", [
+			"-a",
+			"-p",
+			String(pid),
+			"-d",
+			"txt",
+			"-Fpn"
+		], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+		let matchedPid = false;
+		for (const line of output.split(/\r?\n/)) {
+			if (line.startsWith("p")) {
+				if (line !== `p${pid}`) return "";
+				matchedPid = true;
+				continue;
+			}
+			if (matchedPid && line.startsWith("n")) {
+				const path = line.slice(1);
+				if (isAbsolute(path)) return path;
+			}
+		}
+	} catch {}
+	return "";
+}
+function sameResolvedExecutable(actual, expected, windows = false) {
+	try {
+		const actualPath = realpathSync(actual);
+		const expectedPath = realpathSync(expected);
+		return windows ? actualPath.toLowerCase() === expectedPath.toLowerCase() : actualPath === expectedPath;
+	} catch {
+		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);
+	try {
+		return readlinkSync(`/proc/${pid}/exe`);
+	} catch {
+		return "";
+	}
+}
+//#endregion
 //#region src/cli/splash.ts
 const IS_COLOR_TTY = !!process.stdout.isTTY && !process.env["NO_COLOR"];
 function accent(s) {
@@ -852,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,
@@ -865,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 {
@@ -874,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 {
@@ -1052,43 +1518,833 @@ async function runCaptureCommand(options) {
 	return 0;
 }
 //#endregion
-//#region src/cli.ts
-const c = {
-	url: pc.cyan,
-	ok: pc.green,
-	warn: pc.yellow,
-	err: pc.red,
-	cmd: (s) => pc.bold(pc.cyan(s)),
-	label: pc.bold,
-	dim: pc.dim,
-	accent: (s) => pc.bold(pc.yellow(s))
-};
-const ALL_TOOLS_COUNT = getAllTools().length;
-const CORE_TOOLS_COUNT = getAllTools().filter((t) => ESSENTIAL_TOOLS.has(t.name)).length;
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const args = process.argv.slice(2);
-const IS_WINDOWS = platform() === "win32";
-const IS_VERBOSE = args.includes("--verbose") || args.includes("-v") || process.env["AGENTMEMORY_VERBOSE"] === "1" || process.env["AGENTMEMORY_VERBOSE"] === "true";
-setBootVerbose(IS_VERBOSE);
-const IS_RESET = args.includes("--reset");
-hydrateProcessEnvFromFile();
-if (args.includes("--version") || args.includes("-V")) {
-	process.stdout.write(`${VERSION}\n`);
-	process.exit(0);
+//#region src/cli/compression.ts
+async function runCompressionCommand(options) {
+	const log = options.log ?? console.log;
+	const json = options.args.includes("--json");
+	try {
+		const input = {};
+		let retry = false;
+		let dryRun = false;
+		const valueFlags = {
+			"--session": "sessionId",
+			"--project": "project",
+			"--agent-id": "agentId",
+			"--limit": "limit",
+			"--cursor": "cursor"
+		};
+		for (let i = 0; i < options.args.length; i++) {
+			const flag = options.args[i];
+			if (flag === "--json") continue;
+			if (flag === "--retry") {
+				retry = true;
+				continue;
+			}
+			if (flag === "--dry-run") {
+				dryRun = true;
+				continue;
+			}
+			if (flag.startsWith("--port=") || flag.startsWith("--instance=")) {
+				if (!flag.slice(flag.indexOf("=") + 1)) throw new Error(`Missing value for ${flag.split("=")[0]}`);
+				continue;
+			}
+			if (flag === "--port" || flag === "--instance") {
+				if (!options.args[++i] || options.args[i].startsWith("--")) throw new Error(`Missing value for ${flag}`);
+				continue;
+			}
+			const name = valueFlags[flag];
+			if (!name) throw new Error(`Unknown compression option: ${flag}`);
+			if (input[name] !== void 0) throw new Error(`Duplicate option: ${flag}`);
+			const value = options.args[++i];
+			if (value === void 0 || value.startsWith("--")) throw new Error(`Missing value for ${flag}`);
+			input[name] = value;
+		}
+		if (retry && dryRun) throw new Error("Use either --retry or --dry-run");
+		const scope = parseCompressionScope(input);
+		const headers = { "Content-Type": "application/json" };
+		if (options.secret) headers.Authorization = `Bearer ${options.secret}`;
+		const query = new URLSearchParams(Object.entries(scope).filter(([, value]) => value !== void 0).map(([key, value]) => [key, String(value)]));
+		const response = await fetch(`${options.base}/agentmemory/compression${retry ? "/retry" : `?${query}`}`, {
+			method: retry ? "POST" : "GET",
+			headers,
+			...retry ? { body: JSON.stringify(scope) } : {},
+			signal: AbortSignal.timeout(retry ? 12e4 : 1e4)
+		});
+		if (!response.ok) throw new Error(`Compression endpoint returned HTTP ${response.status}`);
+		const result = await response.json();
+		if (typeof result.success !== "boolean" || !Array.isArray(result.items)) throw new Error("Invalid compression response");
+		if (json) log(JSON.stringify(result, null, 2));
+		else {
+			log(retry ? `Compression: ${result.recovered ?? 0} recovered, ${result.failed ?? 0} failed, ${result.attempted ?? 0} attempted` : `Compression: ${result.items.length} pending or failed observations (inspection only)`);
+			if (result.error === "cursor_stale") log("Compression cursor changed. Restart without --cursor.");
+			for (const item of result.items) log(`${item.sessionId}/${item.observationId}: ${item.outcome ?? item.status}${item.error ? ` (${item.error})` : ""}${item.error === "source_unavailable" ? " [source unavailable]" : ""}`);
+			if (result.nextCursor) log(`Continue with --cursor ${result.nextCursor}`);
+			if (!retry && result.items.some((item) => item.retryable)) log("Use --retry to send retained, privacy-filtered source to the configured model. Model usage may incur costs.");
+		}
+		return result.success ? 0 : 1;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Compression request failed";
+		log(json ? JSON.stringify({
+			success: false,
+			error: message
+		}) : `Compression: ${message}`);
+		return 1;
+	}
 }
-const IIPINNED_DEFAULT_VERSION = III_PINNED_VERSION;
-const IIPINNED_VERSION = process.env["AGENTMEMORY_III_VERSION"] || IIPINNED_DEFAULT_VERSION;
-const IIIENGINE_INSTALL_CMD = `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=${IIPINNED_VERSION} sh`;
-function iiiReleaseAsset() {
-	const p = platform();
-	const a = process.arch;
-	if (p === "darwin" && a === "arm64") return "iii-aarch64-apple-darwin.tar.gz";
-	if (p === "darwin" && a === "x64") return "iii-x86_64-apple-darwin.tar.gz";
-	if (p === "linux" && a === "x64") return "iii-x86_64-unknown-linux-gnu.tar.gz";
-	if (p === "linux" && a === "arm64") return "iii-aarch64-unknown-linux-gnu.tar.gz";
-	if (p === "linux" && a === "arm") return "iii-armv7-unknown-linux-gnueabihf.tar.gz";
-	if (p === "win32" && a === "x64") return "iii-x86_64-pc-windows-msvc.zip";
-	if (p === "win32" && a === "arm64") return "iii-aarch64-pc-windows-msvc.zip";
+//#endregion
+//#region src/cli/graph-index.ts
+const VALUE_FLAGS = new Set([
+	"--port",
+	"--instance",
+	"--data-dir",
+	"--tools"
+]);
+async function runGraphIndexCommand(options) {
+	const log = options.log ?? console.log;
+	const json = options.args.includes("--json");
+	const output = (value) => {
+		if (json) {
+			log(JSON.stringify(value, null, 2));
+			return;
+		}
+		if (value.error) {
+			log(String(value.error));
+			return;
+		}
+		log(`Graph index: ${value.state ?? "unknown"}`);
+		if (value.jobId) log(`Job: ${value.jobId}, processed ${value.processed ?? 0} of ${value.total ?? "unknown"}`);
+		if (value.action) log(String(value.action));
+	};
+	let command;
+	let allowLegacyScan = false;
+	try {
+		for (let i = 0; i < options.args.length; i++) {
+			const arg = options.args[i];
+			if (arg === "--json") continue;
+			if (arg === "--allow-legacy-scan") {
+				allowLegacyScan = true;
+				continue;
+			}
+			if (VALUE_FLAGS.has(arg)) {
+				if (!options.args[++i] || options.args[i].startsWith("--")) throw new Error(`Missing value for ${arg}`);
+				continue;
+			}
+			if ([...VALUE_FLAGS].some((flag) => arg.startsWith(`${flag}=`) && arg.length > flag.length + 1)) continue;
+			if (arg === "--verbose" || arg === "-v") continue;
+			if (!command && [
+				"status",
+				"migrate",
+				"resume"
+			].includes(arg)) {
+				command = arg;
+				continue;
+			}
+			throw new Error(`Unknown graph-index argument: ${arg}`);
+		}
+		command ??= "status";
+		if (command === "status" && allowLegacyScan) throw new Error("status does not accept --allow-legacy-scan");
+		if (command === "migrate" && !allowLegacyScan) throw new Error("Migration requires --allow-legacy-scan. Initial discovery reads each complete legacy graph scope and can use substantial memory; run it during maintenance.");
+	} catch (error) {
+		output({ error: error instanceof Error ? error.message : String(error) });
+		return 2;
+	}
+	try {
+		const headers = { Accept: "application/json" };
+		if (options.secret) headers.Authorization = `Bearer ${options.secret}`;
+		if (command !== "status") headers["Content-Type"] = "application/json";
+		const response = await fetch(`${options.base}/agentmemory/graph/index${command === "status" ? "" : `/${command}`}`, {
+			method: command === "status" ? "GET" : "POST",
+			headers,
+			...command === "status" ? {} : { body: JSON.stringify({ allowLegacyScan }) },
+			signal: AbortSignal.timeout(1e4)
+		});
+		const value = await response.json();
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Server returned an invalid graph-index response");
+		output({
+			...value,
+			...!response.ok ? { httpStatus: response.status } : {}
+		});
+		return response.ok ? 0 : 1;
+	} catch (error) {
+		output({ error: error instanceof Error ? error.message : String(error) });
+		return 1;
+	}
+}
+//#endregion
+//#region src/cli/compose-project.ts
+/** Registry versions are pinned here so every generated project uses one reviewed set. */
+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}`;
+}
+function composeProjectPaths(dataDir) {
+	const directory = join(dataDir, "compose");
+	return {
+		directory,
+		file: join(directory, "worker-compose.yaml"),
+		stateDir: join(dataDir, "compose-state"),
+		logFile: join(directory, "compose-daemon.log"),
+		configDir: join(directory, "config")
+	};
+}
+const AGENTMEMORY_WORKER_ENV_ALLOWLIST = new Set([
+	"EMBEDDING_PROVIDER",
+	"AGENTMEMORY_LLM_PROVIDER",
+	"OPENAI_API_KEY",
+	"OPENAI_BASE_URL",
+	"OPENAI_MODEL",
+	"OPENAI_EMBEDDING_API_KEY",
+	"OPENAI_EMBEDDING_BASE_URL",
+	"OPENAI_EMBEDDING_MODEL",
+	"OPENAI_EMBEDDING_DIMENSIONS",
+	"ANTHROPIC_API_KEY",
+	"ANTHROPIC_BASE_URL",
+	"ANTHROPIC_MODEL",
+	"GEMINI_API_KEY",
+	"GEMINI_MODEL",
+	"GOOGLE_API_KEY",
+	"VOYAGE_API_KEY",
+	"VOYAGE_MODEL",
+	"COHERE_API_KEY",
+	"COHERE_MODEL",
+	"OPENROUTER_API_KEY",
+	"OPENROUTER_MODEL",
+	"MINIMAX_API_KEY",
+	"MINIMAX_MODEL",
+	"OLLAMA_HOST",
+	"LLM_PROVIDER",
+	"BM25_WEIGHT",
+	"VECTOR_WEIGHT",
+	"MAX_TOKENS",
+	"TOKEN_BUDGET",
+	"MAX_OBS_PER_SESSION",
+	"CONSOLIDATION_ENABLED",
+	"GRAPH_EXTRACTION_ENABLED",
+	"AGENTMEMORY_AUTO_COMPRESS",
+	"AGENTMEMORY_INJECT_CONTEXT",
+	"AGENTMEMORY_ALLOW_AGENT_SDK",
+	"AGENTMEMORY_SESSION_SWEEP_ENABLED",
+	"AGENTMEMORY_SESSION_SWEEP_STALE_HOURS",
+	"AGENTMEMORY_FINALIZE_IDLE_MS",
+	"AGENTMEMORY_GRAPH_COMPACT_ON_BOOT",
+	"AGENTMEMORY_DROP_STALE_INDEX",
+	"AGENTMEMORY_AUDIT_RETENTION_MONTHS",
+	"AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES",
+	"AGENTMEMORY_STATE_SAVE_INTERVAL_MS",
+	"AGENTMEMORY_TOOLS",
+	"AGENTMEMORY_VIEWER_HOST",
+	"VIEWER_ALLOWED_HOSTS",
+	"VIEWER_ALLOWED_ORIGINS",
+	"AGENTMEMORY_SECRET",
+	"AGENT_ID",
+	"TEAM_ID",
+	"TEAM_MODE",
+	"USER_ID",
+	"AGENTMEMORY_AGENT_SCOPE",
+	"SNAPSHOT_DIR",
+	"SNAPSHOT_ENABLED",
+	"SNAPSHOT_INTERVAL",
+	"STANDALONE_PERSIST_PATH",
+	"CLAUDE_MEMORY_BRIDGE",
+	"CLAUDE_MEMORY_LINE_BUDGET",
+	"CLAUDE_PROJECT_PATH",
+	"AGENTMEMORY_SUPPRESS_COST_WARNING",
+	"FALLBACK_PROVIDERS",
+	"OPENAI_API_VERSION",
+	"OPENAI_REASONING_EFFORT",
+	"OPENAI_TIMEOUT_MS",
+	"MINIMAX_BASE_URL",
+	"OPENROUTER_EMBEDDING_MODEL",
+	"OPENROUTER_EMBEDDING_DIMENSIONS",
+	"AGENTMEMORY_LLM_TIMEOUT_MS",
+	"AGENTMEMORY_CAPTURE_MAX_ATTEMPTS",
+	"AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS",
+	"AGENTMEMORY_CAPTURE_DEDUP_HOURS",
+	"AGENTMEMORY_CAPTURE_INBOX_MAX",
+	"AGENTMEMORY_CAPTURE_DEAD_MAX",
+	"AGENTMEMORY_CAPTURE_EVENTS_MAX",
+	"AGENTMEMORY_CAPTURE_SPOOL",
+	"AGENTMEMORY_CAPTURE_SPOOL_DIR",
+	"AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES",
+	"AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS",
+	"AGENTMEMORY_IMPORT_ROOT",
+	"AGENTMEMORY_EXPORT_ROOT",
+	"AGENTMEMORY_GRAPH_WEIGHT",
+	"SUMMARIZE_CHUNK_SIZE",
+	"SUMMARIZE_CHUNK_CONCURRENCY",
+	"CONSOLIDATION_DECAY_DAYS",
+	"CONSOLIDATION_INTERVAL_MS",
+	"AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS",
+	"AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS",
+	"GRAPH_EXTRACTION_BATCH_SIZE",
+	"AGENTMEMORY_LLM_NOTHINK",
+	"AGENTMEMORY_REFLECT",
+	"AGENTMEMORY_IMAGE_EMBEDDINGS",
+	"AGENTMEMORY_IMAGE_STORE_MAX_BYTES",
+	"AGENTMEMORY_AUDIT_INDEX_PERSIST",
+	"AGENTMEMORY_INDEX_SAVE_INTERVAL_MS",
+	"AGENTMEMORY_VECTOR_BUCKET_SIZE",
+	"AGENTMEMORY_VECTOR_BACKFILL_MAX",
+	"AGENTMEMORY_VECTOR_BACKFILL",
+	"AGENTMEMORY_SLOTS",
+	"AGENTMEMORY_PROVIDER",
+	"AGENTMEMORY_VERBOSE",
+	"OBSIDIAN_AUTO_EXPORT",
+	"AUTO_FORGET_ENABLED",
+	"AUTO_FORGET_INTERVAL_MS",
+	"LESSON_DECAY_ENABLED",
+	"INSIGHT_DECAY_ENABLED",
+	"REBUILD_EMBED_BATCH_SIZE",
+	"RERANK_ENABLED"
+]);
+const COMPOSE_RESERVED_ENV = new Set([
+	"III_URL",
+	"III_ENGINE_URL",
+	"III_ENGINE_PORT",
+	"III_REST_PORT",
+	"III_VIEWER_PORT",
+	"III_NAMESPACE",
+	"III_COMPOSE_NAMESPACE",
+	"III_COMPOSE_FILE",
+	"III_COMPOSE_DIR",
+	"III_CONFIG_NAME",
+	"III_WORKER_NAME"
+]);
+function stateSaveInterval(value) {
+	if (value === void 0 || value.trim() === "") return getStateSaveIntervalMs();
+	if (!/^\d+$/.test(value.trim())) throw new Error("AGENTMEMORY_STATE_SAVE_INTERVAL_MS must be an integer between 100 and 3600000.");
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed) || parsed < 100 || parsed > 36e5) throw new Error("AGENTMEMORY_STATE_SAVE_INTERVAL_MS must be an integer between 100 and 3600000.");
+	return parsed;
+}
+function restartPolicyLines(indent, enabled) {
+	if (!enabled) return [`${indent}restart: no`];
+	return [
+		`${indent}restart:`,
+		`${indent}  condition: on-failure`,
+		`${indent}  delay: 500ms`,
+		`${indent}  max_delay: 30s`,
+		`${indent}  max_attempts: 5`,
+		`${indent}  window: 60s`
+	];
+}
+function shellQuote$1(value) {
+	if (/[\u0000-\u001f\u007f]/.test(value)) throw new Error("A shell command argument contains an unsupported control character.");
+	return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+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.");
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function localWorkerDirectory(value, cwd, projectRoot) {
+	if (isAbsolute(value)) return resolve(value);
+	const fromCwd = resolve(cwd, value);
+	const fromProject = resolve(projectRoot, value);
+	if (fromCwd === fromProject) return fromCwd;
+	if (!fromCwd.startsWith(`${resolve(projectRoot)}/`)) return fromCwd;
+	return fromProject;
+}
+function localWorkerProjectDir(paths, name) {
+	return join(paths.directory, "local-workers", name);
+}
+function ensureEngineTraceStorageConfig(configDir, dataDir) {
+	const configFile = join(configDir, "iii-observability.yaml");
+	const traceDirectory = resolve(dataDir, "observability", "traces");
+	const defaultTraceDirectory = "./data/observability/traces";
+	let entry;
+	if (existsSync(configFile)) {
+		const parsed = parse(readFileSync(configFile, "utf8"));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Invalid persisted iii-observability configuration at ${configFile}.`);
+		entry = parsed;
+		if (entry.id !== "iii-observability") throw new Error(`Unexpected configuration id in ${configFile}; refusing to replace it.`);
+	} else entry = {
+		id: "iii-observability",
+		name: "Observability",
+		description: "",
+		schema: {},
+		value: {
+			sampling_ratio: .1,
+			logs_console_output: false
+		}
+	};
+	const value = entry.value && typeof entry.value === "object" && !Array.isArray(entry.value) ? entry.value : {};
+	let changed = false;
+	if (value.sampling_ratio === void 0) {
+		value.sampling_ratio = .1;
+		changed = true;
+	}
+	if (value.logs_console_output === void 0) {
+		value.logs_console_output = false;
+		changed = true;
+	}
+	const existingStorage = value.trace_storage;
+	const storage = existingStorage && typeof existingStorage === "object" && !Array.isArray(existingStorage) ? existingStorage : {};
+	const existingDirectory = storage.directory;
+	if (typeof existingDirectory === "string" && existingDirectory.trim() !== "" && existingDirectory !== defaultTraceDirectory) {
+		if (!changed) return;
+	} else {
+		storage.directory = traceDirectory;
+		changed = true;
+	}
+	if (!changed) return;
+	if (existingDirectory === void 0 || existingDirectory === defaultTraceDirectory || existingDirectory === "") value.trace_storage = storage;
+	entry.value = value;
+	const temporaryFile = `${configFile}.tmp`;
+	writeFileSync(temporaryFile, stringify(entry), {
+		encoding: "utf8",
+		mode: 384
+	});
+	chmodSync(temporaryFile, 384);
+	renameSync(temporaryFile, configFile);
+	chmodSync(configFile, 384);
+}
+function renderWorkerCompose(options) {
+	const { restPort, viewerPort, enginePort } = options.ports;
+	const paths = composeProjectPaths(options.dataDir);
+	const namespace = composeNamespace(restPort);
+	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 ? 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`,
+		"required_default: true",
+		"engine:",
+		`  url: ws://127.0.0.1:${enginePort}`,
+		"  workers:",
+		"    configuration:",
+		"      adapter:",
+		"        name: fs",
+		"        config:",
+		`          directory: ${yamlString(paths.configDir)}`,
+		"    iii-worker-manager:",
+		"      host: 127.0.0.1",
+		`      port: ${enginePort}`,
+		"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(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).");
+		if (/[\u0000-\u001f\u007f]/.test(redisUrl)) throw new Error("AGENTMEMORY_REDIS_URL contains a control character; percent-encode it before using Redis.");
+		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(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)}`), ...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) {
+	const paths = composeProjectPaths(options.dataDir);
+	mkdirSync(paths.directory, {
+		recursive: true,
+		mode: 448
+	});
+	mkdirSync(paths.configDir, {
+		recursive: true,
+		mode: 448
+	});
+	mkdirSync(paths.stateDir, {
+		recursive: true,
+		mode: 448
+	});
+	ensureEngineTraceStorageConfig(paths.configDir, options.dataDir);
+	mkdirSync(join(options.dataDir, "observability", "traces"), {
+		recursive: true,
+		mode: 448
+	});
+	if (options.workerBinDir) {
+		const binDir = options.workerBinDirIsAbsolute ? resolve(options.workerBinDir) : localWorkerDirectory(options.workerBinDir, options.cwd ?? process.cwd(), options.projectRoot);
+		for (const name of Object.keys(COMPOSE_WORKER_VERSIONS)) {
+			const projectDir = localWorkerProjectDir(paths, name);
+			mkdirSync(projectDir, {
+				recursive: true,
+				mode: 448
+			});
+			const manifest = [
+				"iii: v1",
+				`name: ${name}`,
+				"language: rust",
+				"scripts:",
+				`  start: ${yamlString(join(binDir, name))}`,
+				""
+			].join("\n");
+			writeFileSync(join(projectDir, "iii.worker.yaml"), manifest, {
+				encoding: "utf8",
+				mode: 384
+			});
+			chmodSync(join(projectDir, "iii.worker.yaml"), 384);
+		}
+	}
+	const text = renderWorkerCompose(options);
+	if (options.envFile) {
+		const filteredPath = join(paths.directory, ".agentmemory-filtered.env");
+		writeFileSync(filteredPath, `${readFileSync(options.envFile, "utf8").split(/\r?\n/).filter((line) => {
+			const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+			return !match || !COMPOSE_RESERVED_ENV.has(match[1]);
+		}).join("\n")}\n`, {
+			encoding: "utf8",
+			mode: 384
+		});
+		chmodSync(filteredPath, 384);
+	}
+	writeFileSync(paths.file, text, {
+		encoding: "utf8",
+		mode: 384
+	});
+	chmodSync(paths.file, 384);
+	return {
+		file: paths.file,
+		stateDir: paths.stateDir,
+		logFile: paths.logFile,
+		text
+	};
+}
+//#endregion
+//#region src/cli/compose-control.ts
+function composeRegistryFailureMessage(logText, workerBinDir) {
+	if (![
+		/REGISTRY_UNREACHABLE|REGISTRY_ERROR|PACKAGE_DOWNLOAD_FAILED/i,
+		/cannot reach the registry/i,
+		/registry (?:returned|responded|response)[^\n]*HTTP 5\d\d|HTTP 5\d\d[^\n]*registry/i,
+		/failed to resolve (?:a )?package|package resolution (?:failed|unavailable)|could not resolve .*registry/i,
+		/could not download https:\/\/api\.workers\.iii\.dev\/download\//i
+	].some((pattern) => pattern.test(logText))) return null;
+	return `Worker registry unavailable while resolving state/http; retry later or set AGENTMEMORY_WORKER_BIN_DIR.${workerBinDir ? ` Configured local workers directory: ${workerBinDir}.` : ""}`;
+}
+function composeStateRegistryFailure(dataDir, file) {
+	const stateRoot = join(dataDir, "compose-state");
+	try {
+		const files = [];
+		const walk = (dir) => {
+			for (const entry of readdirSync(dir, { withFileTypes: true })) {
+				const path = join(dir, entry.name);
+				if (entry.isDirectory()) walk(path);
+				else if (entry.name === "state.json") files.push(path);
+			}
+		};
+		walk(stateRoot);
+		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 (!sameComposeFile(state.compose_path, file)) continue;
+			if (message && composeRegistryFailureMessage(message)) return message;
+		}
+	} catch {}
+	return null;
+}
+function composeWorkerFailureSummary(project) {
+	if (!project) return null;
+	const failed = (project.containers ?? []).filter((container) => container.state === "failed");
+	if (!failed.length) return null;
+	return failed.map((container) => `${container.container ?? "worker"}: ${container.last_error ?? "failed after restart attempts were exhausted"}`).join("\n");
+}
+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 = {};
+	for (const key of [
+		"HOME",
+		"PATH",
+		"LANG",
+		"LC_ALL",
+		"TERM",
+		"NO_COLOR",
+		"III_TELEMETRY_ENABLED",
+		"MALLOC_ARENA_MAX",
+		"III_BUNDLE_WORKERS_DISABLED",
+		"III_COMPOSE_MAX_PARALLEL_WORKERS",
+		"AGENTMEMORY_TOOLS",
+		"AGENTMEMORY_VIEWER_HOST",
+		"VIEWER_ALLOWED_HOSTS",
+		"VIEWER_ALLOWED_ORIGINS"
+	]) {
+		const value = env[key];
+		if (value !== void 0) out[key] = value;
+	}
+	return out;
+}
+async function assertComposePortsFree(ports) {
+	for (const port of [...new Set(ports)]) if (await new Promise((resolve) => {
+		const socket = createConnection({
+			host: "127.0.0.1",
+			port
+		});
+		const done = (value) => {
+			socket.destroy();
+			resolve(value);
+		};
+		socket.setTimeout(350);
+		socket.once("connect", () => done(true));
+		socket.once("timeout", () => done(false));
+		socket.once("error", () => done(false));
+	})) throw new Error(`Port ${port} is already in use on 127.0.0.1. Stop the process that owns it or choose another --port/--instance before starting agentmemory.`);
+}
+function composeEnvironment(env, stateDir) {
+	return {
+		...cleanDaemonEnv(env),
+		III_COMPOSE_STATE_DIR: stateDir,
+		III_TELEMETRY_ENABLED: "false",
+		...process.platform === "linux" ? { MALLOC_ARENA_MAX: "2" } : {},
+		...env.AGENTMEMORY_DISABLE_COMPOSE_RESTART === "1" ? { AGENTMEMORY_DISABLE_COMPOSE_RESTART: "1" } : {}
+	};
+}
+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,
+		otel: { enabled: false },
+		enableMetricsReporting: false
+	});
+	try {
+		const connectionDeadline = Date.now() + 8e3;
+		while (client.getConnectionState() !== "connected" && Date.now() < connectionDeadline) {
+			const fatal = client.getFatalError();
+			if (fatal) throw fatal;
+			await new Promise((resolve) => setTimeout(resolve, 50));
+		}
+		if (client.getConnectionState() !== "connected") throw new Error("Could not connect the Compose control client to its instance engine.");
+		const deadline = Date.now() + 8e3;
+		let lastError;
+		while (Date.now() < deadline) try {
+			const result = await client.trigger({
+				function_id: options.functionId,
+				payload: { file: options.file },
+				timeoutMs: options.timeoutMs ?? 3e4
+			});
+			if (result && typeof result === "object" && result.status === "failed") {
+				const detail = result.error?.message ?? result.error?.code ?? "unknown Compose failure";
+				throw Object.assign(/* @__PURE__ */ new Error(`${result.error?.code ? `${result.error.code}: ` : ""}${detail}`), { retryable: false });
+			}
+			return result;
+		} catch (err) {
+			lastError = err;
+			if (err && typeof err === "object" && "retryable" in err && err.retryable === false) throw err;
+			await new Promise((resolve) => setTimeout(resolve, 150));
+		}
+		throw lastError ?? /* @__PURE__ */ new Error("Compose daemon did not accept the control connection.");
+	} finally {
+		await client.shutdown().catch(() => {});
+	}
+}
+function startComposeDaemon(runtime) {
+	const project = writeWorkerCompose({
+		...runtime,
+		envFile: runtime.envFile
+	});
+	const logFile = runtime.logFile;
+	mkdirSync(dirname(logFile), {
+		recursive: true,
+		mode: 448
+	});
+	chmodSync(dirname(logFile), 448);
+	const fd = openSync(logFile, "a", 384);
+	const logStartOffset = fstatSync(fd).size;
+	writeFileSync(fd, `\n[${(/* @__PURE__ */ new Date()).toISOString()}] Starting Worker Compose\n`);
+	const environment = composeEnvironment(runtime.env, project.stateDir);
+	const child = spawn(runtime.iiiBin, [
+		"compose",
+		"--namespace",
+		composeNamespace(runtime.ports.restPort),
+		"--up",
+		"--file",
+		project.file
+	], {
+		cwd: runtime.projectRoot,
+		detached: true,
+		stdio: [
+			"ignore",
+			fd,
+			fd
+		],
+		windowsHide: true,
+		env: environment
+	});
+	closeSync(fd);
+	child.unref();
+	return {
+		child,
+		file: project.file,
+		namespace: composeNamespace(runtime.ports.restPort),
+		stateDir: project.stateDir,
+		logFile,
+		logStartOffset
+	};
+}
+function readComposeLogFromOffset(file, offset) {
+	const fd = openSync(file, "r");
+	try {
+		const size = fstatSync(fd).size;
+		let position = Math.min(Math.max(0, offset), size);
+		const chunks = [];
+		while (position < size) {
+			const chunk = Buffer.allocUnsafe(Math.min(16 * 1024, size - position));
+			const count = readSync(fd, chunk, 0, chunk.length, position);
+			if (count === 0) break;
+			chunks.push(chunk.subarray(0, count));
+			position += count;
+		}
+		return Buffer.concat(chunks).toString("utf8");
+	} finally {
+		closeSync(fd);
+	}
+}
+function writeComposeState(path, state) {
+	mkdirSync(dirname(path), {
+		recursive: true,
+		mode: 448
+	});
+	writeFileSync(path, `${JSON.stringify(state)}\n`, {
+		encoding: "utf8",
+		mode: 384
+	});
+	chmodSync(path, 384);
+}
+//#endregion
+//#region src/cli/legacy-docker-state.ts
+function shellQuote(value) {
+	return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+function legacyDockerStopCommand(state) {
+	const project = state.projectName?.trim();
+	const composeFile = state.composeFile?.trim();
+	if (composeFile) return `docker compose${project ? ` -p ${shellQuote(project)}` : ""} -f ${shellQuote(composeFile)} stop`;
+	if (project) return `docker compose -p ${shellQuote(project)} stop`;
+	if (state.containerId?.trim()) return `docker stop ${shellQuote(state.containerId.trim())}`;
+	return "Cannot construct a stop command: legacy lifecycle state has no Compose file, project, or container ID.";
+}
+function legacyDockerStateMessage(state) {
+	return [
+		`This installation was started by an older Docker-based agentmemory CLI (REST port ${state.restPort && Number.isFinite(state.restPort) ? state.restPort : Number(state.projectName?.match(/^agentmemory-(\d+)$/)?.[1] ?? 3111)}); Docker lifecycle management is no longer part of this CLI.`,
+		"Stop the old container explicitly before switching to Worker Compose:",
+		`  ${legacyDockerStopCommand(state)}`,
+		"The legacy lifecycle state is preserved; no container or data was changed."
+	].join("\n");
+}
+//#endregion
+//#region src/cli.ts
+const c = {
+	url: pc.cyan,
+	ok: pc.green,
+	warn: pc.yellow,
+	err: pc.red,
+	cmd: (s) => pc.bold(pc.cyan(s)),
+	label: pc.bold,
+	dim: pc.dim,
+	accent: (s) => pc.bold(pc.yellow(s))
+};
+const ALL_TOOLS_COUNT = getAllTools().length;
+const CORE_TOOLS_COUNT = getAllTools().filter((t) => ESSENTIAL_TOOLS.has(t.name)).length;
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const IS_WINDOWS = platform() === "win32";
+const IS_VERBOSE = args.includes("--verbose") || args.includes("-v") || process.env["AGENTMEMORY_VERBOSE"] === "1" || process.env["AGENTMEMORY_VERBOSE"] === "true";
+setBootVerbose(IS_VERBOSE);
+const IS_RESET = args.includes("--reset");
+const shellEnv = hydrateProcessEnvFromFile();
+if (args.includes("--version") || args.includes("-V")) {
+	process.stdout.write(`${VERSION}\n`);
+	process.exit(0);
+}
+const IIPINNED_DEFAULT_VERSION = III_PINNED_VERSION;
+const IIPINNED_VERSION = process.env["AGENTMEMORY_III_VERSION"] || IIPINNED_DEFAULT_VERSION;
+const IIIENGINE_INSTALL_CMD = `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=${IIPINNED_VERSION} sh`;
+function iiiReleaseAsset() {
+	const p = platform();
+	const a = process.arch;
+	if (p === "darwin" && a === "arm64") return "iii-aarch64-apple-darwin.tar.gz";
+	if (p === "darwin" && a === "x64") return "iii-x86_64-apple-darwin.tar.gz";
+	if (p === "linux" && a === "x64") return "iii-x86_64-unknown-linux-gnu.tar.gz";
+	if (p === "linux" && a === "arm64") return "iii-aarch64-unknown-linux-gnu.tar.gz";
+	if (p === "linux" && a === "arm") return "iii-armv7-unknown-linux-gnueabihf.tar.gz";
+	if (p === "win32" && a === "x64") return "iii-x86_64-pc-windows-msvc.zip";
+	if (p === "win32" && a === "arm64") return "iii-aarch64-pc-windows-msvc.zip";
 	return null;
 }
 function iiiReleaseUrl() {
@@ -1119,15 +2375,14 @@ agentmemory — persistent memory for AI coding agents
 Usage: agentmemory [command] [options]
 
 Commands:
-  (default)          Start agentmemory worker
+  (default)          Start agentmemory via a per-instance Worker Compose project
   init               Copy bundled .env.example to ~/.agentmemory/.env if absent
   connect [agent]    Wire agentmemory into an installed agent
                      (${wrapList(knownAgents(), 21)}).
                      No arg = interactive picker. --all wires every detected agent.
                      --dry-run shows what would change. --force re-installs.
   status             Show connection status, memory count, flags, and health
-  console            Launch the iii web console for this engine (workers, functions,
-                     triggers, queues, traces). --console-port N, default viewer+1
+  console            Show migration guidance for the retired iii console
   doctor             Interactive diagnostic + fixer. [F]ix · [S]kip · [?]more · [Q]uit
                      --all: apply every fix without prompting (CI)
                      --dry-run: show what each fix would do, don't execute
@@ -1138,14 +2393,20 @@ Commands:
                      in one command (no second terminal).
   upgrade            Upgrade local deps + iii runtime (best effort)
   stop [--force]     Stop the running iii-engine started by this CLI.
-                     --force bypasses the Docker-heuristic guard and signals
-                     whatever pidfile+lsof report on the REST port (use when
-                     the engine was started natively but state file is missing).
+                     --force bypasses the native engine PID identity guard
+                     (use when the engine was started natively but state file is missing).
   mcp                Start standalone MCP shim — opt-in surface for MCP-only clients
                      (Cursor, Gemini CLI, etc). REST always available at :3111.
   capture [--drain]  Show capture health: the local offline spool and the server
                      inbox (pending, retrying, dead letters). --drain sends
                      spooled observations now. --json for machine output.
+  compression        Inspect pending or failed observation compression.
+                     --session <id> or --project <name> selects the scope.
+                     --agent-id <id> narrows it; --limit <N> bounds the batch.
+                     --retry explicitly retries compression; --json for machine output.
+  graph-index       Inspect bounded graph index status. --json for machine output.
+                     migrate --allow-legacy-scan explicitly scans legacy graph data.
+                     resume continues a sealed migration without another full scan.
   import-jsonl [p]   Import Claude Code JSONL transcripts (default: ~/.claude/projects)
                      --max-files <N> | --max-files=<N>: override scan cap (default 200, max 1000;
                      out-of-range is rejected; for trees >1000 files, batch by subdirectory)
@@ -1156,30 +2417,32 @@ Options:
   --reset            Wipe ~/.agentmemory/preferences.json and re-run onboarding
   --tools all|core   Tool visibility (default: all = ${ALL_TOOLS_COUNT} tools; core = ${CORE_TOOLS_COUNT} essentials)
   --no-engine        Skip auto-starting iii-engine
-  --port <N>         Override REST port (default: 3111). Streams (N+1), viewer
-                     (N+2), and iii engine (N+46023) auto-derive from N so a
-                     single flag relocates the whole quartet.
+  --port <N>         Override REST port (default: 3111). Viewer (N+2) and
+                     iii engine (N+46023) derive from N for side-by-side instances.
   --instance <N>     Shortcut for --port (3111 + N*100) to run multiple
                      daemons side-by-side without env gymnastics.
-                     --instance 1 -> 3211/3212/3213/49234, etc. (max N=50)
+                     --instance 1 -> 3211/3213/49234, etc. (max N=50)
   --data-dir <path>  Store iii-engine state outside the current repo
 
 Environment:
   AGENTMEMORY_URL              Full REST base URL (e.g. http://localhost:3111).
                                Honored by status, doctor, and MCP shim commands.
   AGENTMEMORY_DATA_DIR         State directory fallback when --data-dir is not set.
-  AGENTMEMORY_USE_DOCKER=1     Prefer the bundled docker-compose path over the
-                               native iii-engine binary on first run.
   AGENTMEMORY_III_VERSION      Override pinned iii-engine version (default ${IIPINNED_VERSION}).
-  AGENTMEMORY_III_CONFIG       Engine config to start from (default: ./iii-config.yaml,
-                               then ~/.agentmemory/iii-config.yaml, then the bundled
-                               loopback-only config).
+  AGENTMEMORY_ENGINE_READY_TIMEOUT_MS
+                               Engine readiness deadline in milliseconds (default 120000).
+  AGENTMEMORY_READY_TIMEOUT_MS
+                               Worker readiness deadline in milliseconds (default 300000).
+                               Both deadlines accept integers from 1 through 3600000.
+  AGENTMEMORY_ENGINE_MANAGES_WORKER
+                               true for custom engine-managed worker wrappers; false
+                               for CLI-managed workers. Unset detects direct worker commands.
   AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS
                                Window (seconds) for the smart-search follow-up diagnostic
                                (default 30). Long values overcount, short values undercount.
 
 Quick start:
-  npx @agentmemory/agentmemory          # start with local iii-engine or Docker
+  npx @agentmemory/agentmemory          # start pinned iii Worker Compose runtime
   npx @agentmemory/agentmemory demo     # see semantic recall in 30 seconds
   npx @agentmemory/agentmemory doctor   # diagnose config + feature flags
   npx @agentmemory/agentmemory status   # health + memory count + flags
@@ -1199,7 +2462,9 @@ const URL_CLIENT_COMMANDS = new Set([
 	"status",
 	"doctor",
 	"mcp",
-	"capture"
+	"capture",
+	"compression",
+	"graph-index"
 ]);
 let hasExplicitLocalPortOverride = false;
 let selectedInstance = 0;
@@ -1232,7 +2497,6 @@ if (args.some((arg) => arg === "--instance" || arg.startsWith("--instance="))) {
 }
 const restPort = parseInt(process.env["III_REST_PORT"] || "3111", 10);
 if (Number.isFinite(restPort) && restPort > 0) {
-	process.env["III_STREAM_PORT"] ??= process.env["III_STREAMS_PORT"] ?? String(restPort + 1);
 	process.env["III_VIEWER_PORT"] ??= String(restPort + 2);
 	const configuredEngineUrl = process.env["III_ENGINE_URL"];
 	if (configuredEngineUrl) try {
@@ -1293,9 +2557,6 @@ function getViewerUrl() {
 		return `http://localhost:${getConfiguredViewerPort()}`;
 	}
 }
-function getStreamPort() {
-	return parseInt(process.env["III_STREAM_PORT"] || "", 10) || parseInt(process.env["III_STREAMS_PORT"] || "", 10) || getRestPort() + 1;
-}
 function getEnginePort() {
 	const url = process.env["III_ENGINE_URL"];
 	if (url) try {
@@ -1307,43 +2568,19 @@ function getEnginePort() {
 	return getRestPort() + 46023;
 }
 async function isEngineRunning() {
-	try {
-		await fetch(`${getBaseUrl()}/`, { signal: AbortSignal.timeout(2e3) });
-		return true;
-	} catch {
-		return false;
-	}
+	const state = readEngineState();
+	const endpoint = state?.kind === "compose" && state.restPort === getRestPort() && !shouldUseAgentmemoryUrl() ? `http://127.0.0.1:${state.restPort}` : getBaseUrl();
+	const result = await withinStartupDeadline(startupDeadline(2e3), (signal) => probeEngine(endpoint, signal)).catch(() => null);
+	return result?.completed === true && result.value;
 }
 async function isAgentmemoryReady() {
-	try {
-		const res = await fetch(`${getBaseUrl()}/agentmemory/livez`, { signal: AbortSignal.timeout(2e3) });
-		if (!res.ok) return false;
-		try {
-			const data = await res.json();
-			if (typeof data.viewerPort === "number") {
-				discoveredViewerPort = data.viewerPort;
-				return true;
-			}
-			if (data.viewerSkipped) return true;
-			return false;
-		} catch {
-			return false;
-		}
-	} catch {
-		return false;
-	}
+	const result = await withinStartupDeadline(startupDeadline(2e3), workerReadinessProbe).catch(() => null);
+	return result?.completed === true && result.value;
 }
-function findIiiConfig() {
-	const envPath = process.env["AGENTMEMORY_III_CONFIG"];
-	const candidates = [
-		...envPath ? [envPath] : [],
-		join(process.cwd(), "iii-config.yaml"),
-		join(homedir(), ".agentmemory", "iii-config.yaml"),
-		join(__dirname, "iii-config.yaml"),
-		join(__dirname, "..", "iii-config.yaml")
-	];
-	for (const c of candidates) if (existsSync(c)) return resolve(c);
-	return "";
+function workerReadinessProbe(signal) {
+	return probeWorker(getBaseUrl(), signal, (port) => {
+		discoveredViewerPort = port;
+	});
 }
 function warnIfRelocatedDataDir() {
 	if (!dataDirResolution.relocatedFrom) return;
@@ -1396,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: [
@@ -1405,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;
@@ -1431,15 +2682,6 @@ function enginePidfilePath() {
 function engineStatePath() {
 	return runtimeMetadataPath("engine-state.json");
 }
-function writeEnginePidfile(pid) {
-	try {
-		const pidPath = enginePidfilePath();
-		mkdirSync(dirname(pidPath), { recursive: true });
-		writeFileSync(pidPath, `${pid}\n`, { encoding: "utf-8" });
-	} catch (err) {
-		vlog(`writeEnginePidfile: ${err instanceof Error ? err.message : String(err)}`);
-	}
-}
 function readEnginePidfile() {
 	try {
 		const pidStr = readFileSync(enginePidfilePath(), "utf-8").trim();
@@ -1471,28 +2713,11 @@ function clearWorkerPidfile() {
 		unlinkSync(workerPidfilePath());
 	} catch {}
 }
-function writeEngineState(state) {
-	try {
-		const statePath = engineStatePath();
-		mkdirSync(dirname(statePath), { recursive: true });
-		const normalized = state.kind === "docker" && state.schemaVersion === 2 ? {
-			...state,
-			restPort: state.restPort ?? getRestPort(),
-			dataDir: state.dataDir ?? dataDirResolution.dataDir
-		} : {
-			...state,
-			restPort: state.restPort ?? getRestPort()
-		};
-		writeFileSync(statePath, `${JSON.stringify(normalized)}\n`, { encoding: "utf-8" });
-	} catch (err) {
-		vlog(`writeEngineState: ${err instanceof Error ? err.message : String(err)}`);
-	}
-}
 function readEngineState() {
 	try {
 		const raw = readFileSync(engineStatePath(), "utf-8");
 		const parsed = JSON.parse(raw);
-		if (parsed && (parsed.kind === "native" || parsed.kind === "docker")) return parsed;
+		if (parsed && (parsed.kind === "native" || parsed.kind === "docker" || parsed.kind === "compose")) return parsed;
 		return null;
 	} catch {
 		return null;
@@ -1505,271 +2730,138 @@ function clearEngineState() {
 }
 function engineStateRestPort(state) {
 	if (state.restPort && Number.isFinite(state.restPort)) return state.restPort;
-	if (state.kind === "docker") {
-		const projectPort = state.projectName?.match(/^agentmemory-(\d+)$/)?.[1];
-		if (projectPort) return parseInt(projectPort, 10);
-		return 3111;
-	}
+	if (state.kind === "compose") return 3111;
 	try {
 		const configuredPort = (readFileSync(state.configPath, "utf-8").match(/- name:\s*(?:iii-)?http([\s\S]*?)(?=\n\s*- name:|$)/)?.[1])?.match(/\n\s*port:\s*(\d+)/)?.[1];
 		if (configuredPort) return parseInt(configuredPort, 10);
 	} catch {}
 	return 3111;
 }
-async function startWorkerForEngineState() {
-	const workerPid = readWorkerPidfile();
-	if (workerPid && pidAlive(workerPid)) return;
-	if (configuredEngineMayStartWorker() && await waitForConfiguredWorker(5e3)) return;
-	await import("./src-Jsq9LCeH.mjs");
+async function startWorkerForEngineState(background = false) {
+	if (readEngineState()?.kind === "compose") {
+		const timeoutMs = startupTimeouts().workerMs;
+		if (!await waitForReadiness(startupDeadline(timeoutMs), workerReadinessProbe, { stopped: () => {
+			const state = readEngineState();
+			if (state?.kind === "compose") try {
+				const failure = composeRegistryFailureMessage(readComposeLogFromOffset(state.logFile, state.logStartOffset ?? 0), state.workerBinDir);
+				if (failure) startupFailure = {
+					kind: "engine-crashed",
+					stderr: failure
+				};
+			} catch {}
+			return startupInterrupted || engineStartupFailed() || Boolean(startupFailure?.stderr?.startsWith("Worker registry unavailable"));
+		} })) {
+			printComposeStartupLogs();
+			const state = readEngineState();
+			let registryFailure = state?.kind === "compose" ? composeStateRegistryFailure(dataDirResolution.dataDir, state.file) : null;
+			if (state?.kind === "compose" && !registryFailure) registryFailure = (() => {
+				try {
+					return composeRegistryFailureMessage(readComposeLogFromOffset(state.logFile, state.logStartOffset ?? 0), state.workerBinDir);
+				} catch {
+					return null;
+				}
+			})();
+			if (state?.kind === "compose" && await isEngineRunning()) try {
+				const failures = (ownedComposeProject(await composeCall({
+					engineUrl: state.engineUrl,
+					namespace: state.namespace,
+					functionId: "compose::status",
+					file: state.file
+				}), state.file)?.containers ?? []).filter((container) => container.state === "failed" || container.last_error).map((container) => {
+					let detail = container.last_error ?? container.state ?? "failed";
+					if (container.log_path) try {
+						const log = readFileSync(container.log_path, "utf8").trim();
+						if (log) detail += `\n${log.split(/\r?\n/).slice(-12).join("\n")}`;
+					} catch {}
+					return `${container.container ?? "worker"}: ${detail}`;
+				});
+				if (failures.length) {
+					state.workerFailure = failures.join("\n");
+					writeComposeState(engineStatePath(), {
+						...state,
+						workerVersions: state.workerVersions ?? (state.workerBinDir ? { local: true } : COMPOSE_WORKER_VERSIONS)
+					});
+					const aggregate = composeRegistryFailureMessage(state.workerFailure, state.workerBinDir);
+					if (aggregate) registryFailure = `${aggregate} Compose reported: ${state.workerFailure}`;
+					else {
+						const logTail = readComposeLogFromOffset(state.logFile, state.logStartOffset ?? 0).trim().split(/\r?\n/).slice(-12).join("\n");
+						registryFailure = `Worker Compose failed: ${state.workerFailure}${logTail ? `\nRecent Compose output:\n${logTail}` : ""}`;
+					}
+				}
+			} catch {}
+			throw new Error(registryFailure || startupFailure?.stderr || startupTimeoutMessage("worker", timeoutMs));
+		}
+		composeStartupCompleted = true;
+		finishStartup();
+		return;
+	}
+	const timeoutMs = startupTimeouts().workerMs;
+	startupWorkerFailure = null;
+	if (!await startWorkerAndWait({
+		timeoutMs,
+		hasLiveWorker: () => {
+			const workerPid = readWorkerPidfile();
+			return Boolean(workerPid && pidAlive(workerPid));
+		},
+		engineStartsWorker: configuredEngineMayStartWorker,
+		startWorker: async () => {
+			if (background) {
+				const builtEntry = join(__dirname, "index.mjs");
+				const workerArgs = existsSync(builtEntry) ? [builtEntry] : [
+					"--import",
+					"tsx",
+					join(__dirname, "index.ts")
+				];
+				const child = spawn(process.execPath, workerArgs, {
+					detached: true,
+					stdio: "ignore",
+					windowsHide: true,
+					env: { ...process.env }
+				});
+				spawnedStartupWorker = child;
+				child.on("error", (error) => {
+					if (spawnedStartupWorker === child) startupWorkerFailure = error;
+				});
+				child.on("exit", (code, signal) => {
+					if (spawnedStartupWorker === child) startupWorkerFailure = /* @__PURE__ */ new Error(`agentmemory worker exited during startup (${signal ?? code}).`);
+				});
+				child.unref();
+			} else {
+				importedStartupWorker = true;
+				await import("./src-C23nMpda.mjs");
+			}
+		},
+		probe: workerReadinessProbe,
+		stopped: () => startupInterrupted || engineStartupFailed() || startupWorkerFailure !== null
+	})) {
+		if (startupWorkerFailure) throw startupWorkerFailure;
+		if (engineStartupFailed()) throw new Error("iii-engine exited before the agentmemory worker became ready.");
+		throw new Error(startupTimeoutMessage("worker", timeoutMs));
+	}
+	finishStartup();
 }
 function configuredEngineMayStartWorker() {
+	const explicit = startupTimeouts().engineManagesWorker;
+	if (explicit !== void 0) return explicit;
 	const state = readEngineState();
-	if (state?.kind !== "native") return false;
+	if (state?.kind !== "native" || state.attached) return false;
 	try {
-		return readFileSync(state.configPath, "utf-8").includes("- name: iii-exec");
+		return configStartsAgentmemoryWorker(readFileSync(state.configPath, "utf-8"), join(__dirname, "index.mjs"), state.cwd);
 	} catch {
 		return false;
 	}
 }
-async function waitForConfiguredWorker(timeoutMs) {
-	const deadline = Date.now() + timeoutMs;
-	while (Date.now() < deadline) {
-		const workerPid = readWorkerPidfile();
-		if (workerPid && pidAlive(workerPid)) return true;
-		if (await isAgentmemoryReady()) return true;
-		await new Promise((resolve) => setTimeout(resolve, 100));
-	}
-	return false;
-}
-function discoverComposeFile() {
-	return [
-		join(__dirname, "..", "docker-compose.yml"),
-		join(__dirname, "docker-compose.yml"),
-		join(process.cwd(), "docker-compose.yml")
-	].find((c) => existsSync(c)) ?? null;
-}
-function sameDockerMountSource(type, left, right) {
-	return type === "bind" ? resolve(left) === resolve(right) : left === right;
-}
-function inspectDockerContainer(dockerBin, containerId, state, ownerPort) {
-	const result = spawnSync(dockerBin, ["inspect", containerId], {
-		encoding: "utf-8",
-		stdio: [
-			"ignore",
-			"pipe",
-			"ignore"
-		],
-		maxBuffer: 1024 * 1024
-	});
-	if (result.status !== 0) return {
-		status: "unavailable",
-		reason: `docker inspect failed for ${containerId}`
-	};
-	let record;
-	try {
-		record = JSON.parse(result.stdout)[0] ?? {};
-	} catch {
-		return {
-			status: "unavailable",
-			reason: `docker inspect returned invalid JSON for ${containerId}`
-		};
-	}
-	const image = record.Config?.Image ?? "";
-	const expectedImage = `iiidev/iii:${state.engineVersion ?? IIPINNED_VERSION}`;
-	if (image !== expectedImage) return {
-		status: "unavailable",
-		reason: `saved container uses ${image || "an unknown image"}, expected ${expectedImage}`
-	};
-	const labels = record.Config?.Labels ?? {};
-	const projectName = labels["com.docker.compose.project"] ?? "";
-	if (labels["com.docker.compose.service"] !== "iii-engine" || !projectName) return {
-		status: "unavailable",
-		reason: "saved container is not the iii-engine service of a Compose project"
-	};
-	if (state.projectName && state.projectName !== projectName) return {
-		status: "unavailable",
-		reason: `saved Docker project ${state.projectName} does not match container project ${projectName}`
-	};
-	if (state.schemaVersion === 2 && projectName !== dockerProjectName(ownerPort)) return {
-		status: "unavailable",
-		reason: `Docker project ${projectName} does not match REST port ${ownerPort}`
-	};
-	if (!(record.HostConfig?.PortBindings?.[`${ownerPort}/tcp`] ?? []).some((binding) => binding.HostPort === String(ownerPort))) return {
-		status: "unavailable",
-		reason: `saved container does not publish REST port ${ownerPort}`
-	};
-	const dataMount = record.Mounts?.find((mount) => mount.Destination === "/data");
-	const dataMountType = dataMount?.Type;
-	const dataMountSource = dataMountType === "volume" ? dataMount?.Name ?? dataMount?.Source ?? "" : dataMount?.Source ?? "";
-	if (dataMountType !== "bind" && dataMountType !== "volume" || !dataMountSource) return {
-		status: "unavailable",
-		reason: "saved container has no verifiable /data bind or volume mount"
-	};
-	if (state.dataMountType && state.dataMountType !== dataMountType) return {
-		status: "unavailable",
-		reason: `saved /data mount type ${state.dataMountType} changed to ${dataMountType}`
-	};
-	if (state.dataMountSource && !sameDockerMountSource(dataMountType, state.dataMountSource, dataMountSource)) return {
-		status: "unavailable",
-		reason: "saved container /data mount source changed"
-	};
-	if (!state.dataMountSource) {
-		if (dataMountType === "bind" && resolve(dataMountSource) !== resolve(dataDirResolution.dataDir)) return {
-			status: "unavailable",
-			reason: `container /data bind ${dataMountSource} does not match ${dataDirResolution.dataDir}`
-		};
-		if (dataMountType === "volume" && dataDirResolution.source !== "default") return {
-			status: "unavailable",
-			reason: "legacy container uses a named volume but this invocation selects an explicit data directory"
-		};
-	}
-	if (state.dataDir && resolve(state.dataDir) !== resolve(dataDirResolution.dataDir)) return {
-		status: "unavailable",
-		reason: `saved data directory ${state.dataDir} does not match ${dataDirResolution.dataDir}`
-	};
-	return {
-		status: record.State?.Running ? "running" : "stopped",
-		composeFile: existsSync(state.composeFile) ? state.composeFile : discoverComposeFile() ?? state.composeFile,
-		projectName,
-		containerId: record.Id ?? containerId,
-		dataMountType,
-		dataMountSource,
-		preserveContainer: state.preserveContainer === true || state.schemaVersion !== 2 && dataMountType === "volume"
-	};
-}
-function inspectOwnedDockerEngine(state) {
-	if (state.kind !== "docker") return {
-		status: "unavailable",
-		reason: "engine state is not Docker"
-	};
-	const ownerPort = engineStateRestPort(state);
-	if (state.schemaVersion === 2 && state.projectName !== dockerProjectName(ownerPort)) return {
-		status: "unavailable",
-		reason: `saved Docker project ${state.projectName} does not match REST port ${ownerPort}`
-	};
-	const dockerBin = whichBinary("docker");
-	if (!dockerBin) return {
-		status: "unavailable",
-		reason: "docker is not on PATH"
-	};
-	const discoveryFailures = [];
-	if (state.containerId) {
-		const direct = inspectDockerContainer(dockerBin, state.containerId, state, ownerPort);
-		if (direct.status !== "unavailable") return direct;
-		if (state.preserveContainer) return direct;
-		discoveryFailures.push(direct.reason);
-	}
-	const composeFile = existsSync(state.composeFile) ? state.composeFile : discoverComposeFile() ?? state.composeFile;
-	const candidateIds = /* @__PURE__ */ new Set();
-	try {
-		if (existsSync(composeFile)) {
-			const composeText = readFileSync(composeFile, "utf-8");
-			if (!/^\s+iii-engine:/m.test(composeText)) return {
-				status: "unavailable",
-				reason: `${composeFile} does not define iii-engine`
-			};
-			const psResult = spawnSync(dockerBin, dockerComposeArgs(composeFile, state.projectName, [
-				"ps",
-				"-q",
-				"--all",
-				"iii-engine"
-			]), {
-				encoding: "utf-8",
-				stdio: [
-					"ignore",
-					"pipe",
-					"ignore"
-				]
-			});
-			if (psResult.status === 0) {
-				for (const id of (psResult.stdout ?? "").trim().split(/\s+/)) if (id) candidateIds.add(id);
-			} else discoveryFailures.push(`docker compose ps failed for project ${state.projectName ?? "<default>"}`);
-		}
-		const scanResult = spawnSync(dockerBin, [
-			"ps",
-			"-aq",
-			"--filter",
-			"label=com.docker.compose.service=iii-engine",
-			"--filter",
-			`ancestor=iiidev/iii:${state.engineVersion ?? IIPINNED_VERSION}`,
-			...state.projectName ? ["--filter", `label=com.docker.compose.project=${state.projectName}`] : []
-		], {
-			encoding: "utf-8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			]
-		});
-		if (scanResult.status === 0) {
-			for (const id of (scanResult.stdout ?? "").trim().split(/\s+/)) if (id) candidateIds.add(id);
-		} else discoveryFailures.push("docker container scan failed");
-		const matches = [];
-		for (const containerId of candidateIds) {
-			const inspected = inspectDockerContainer(dockerBin, containerId, state, ownerPort);
-			if (inspected.status === "running" || inspected.status === "stopped") {
-				if (!matches.some((match) => (match.status === "running" || match.status === "stopped") && match.containerId === inspected.containerId)) matches.push(inspected);
-			} else if (inspected.status === "unavailable") discoveryFailures.push(inspected.reason);
-		}
-		if (matches.length === 1) return matches[0];
-		if (matches.length > 1) return {
-			status: "unavailable",
-			reason: `multiple Docker iii-engine containers match REST port ${ownerPort}`
-		};
-		if (discoveryFailures.length > 0) return {
-			status: "unavailable",
-			reason: [...new Set(discoveryFailures)].join("; ")
-		};
-		if (state.schemaVersion !== 2 || state.preserveContainer) return {
-			status: "unavailable",
-			reason: `legacy Docker ownership exists for REST port ${ownerPort}, but no unique container can be verified`
-		};
-		return {
-			status: "missing",
-			composeFile,
-			projectName: state.projectName
-		};
-	} catch (err) {
-		return {
-			status: "unavailable",
-			reason: err instanceof Error ? err.message : String(err)
-		};
-	}
-}
-function persistDockerInspection(state, inspection) {
-	if (inspection.status !== "running" && inspection.status !== "stopped") return state;
-	const resolved = {
-		...state,
-		composeFile: inspection.composeFile,
-		projectName: inspection.projectName,
-		containerId: inspection.containerId,
-		dataMountType: inspection.dataMountType,
-		dataMountSource: inspection.dataMountSource,
-		preserveContainer: inspection.preserveContainer
-	};
-	writeEngineState(resolved);
-	return resolved;
-}
 async function assertRuntimePortOwnership() {
 	const state = readEngineState();
 	if (!state) return;
-	const ownerPort = engineStateRestPort(state);
-	const requestedPort = getRestPort();
-	if (ownerPort === requestedPort) return;
 	if (state.kind === "docker") {
-		const inspection = inspectOwnedDockerEngine(state);
-		if (inspection.status === "unavailable") {
-			p.log.error(`The data directory contains Docker ownership for REST port ${ownerPort}, but it cannot be verified: ${inspection.reason}. Refusing to overwrite its lifecycle state.`);
-			process.exit(1);
-		}
-		if (inspection.status === "running" || inspection.status === "stopped") {
-			persistDockerInspection(state, inspection);
-			p.log.error(`The canonical lifecycle state is owned by a ${inspection.status} Docker engine on REST port ${ownerPort}. Refusing to reuse it for port ${requestedPort}. Use the original port, or use --instance <N> for an isolated daemon.`);
-			process.exit(1);
-		}
-		p.log.error(`The canonical lifecycle state still records a Docker engine for REST port ${ownerPort}, but its container is missing. Refusing to overwrite that ownership from port ${requestedPort}. Re-run \`agentmemory stop\` with the original port to reconcile it.`);
+		p.log.error(legacyDockerStateMessage(state));
 		process.exit(1);
 	}
+	const ownerPort = engineStateRestPort(state);
+	if (state.kind === "compose" && ownerPort !== getRestPort()) return;
+	const requestedPort = getRestPort();
+	if (ownerPort === requestedPort) return;
 	const enginePid = readEnginePidfile();
 	const workerPid = readWorkerPidfile();
 	let active = Boolean(enginePid && pidAlive(enginePid) && !isForeignPortHolder(pidCommand(enginePid)) || workerPid && pidAlive(workerPid));
@@ -1785,14 +2877,6 @@ async function assertRuntimePortOwnership() {
 	clearWorkerPidfile();
 	clearEngineState();
 }
-function configureDockerHostUser() {
-	if (typeof process.getuid !== "function" || typeof process.getgid !== "function") return;
-	const hostUid = String(process.getuid());
-	const hostGid = String(process.getgid());
-	process.env["AGENTMEMORY_DOCKER_UID"] ??= hostUid;
-	process.env["AGENTMEMORY_DOCKER_GID"] ??= hostGid;
-	if (process.env["AGENTMEMORY_DOCKER_UID"] === hostUid && process.env["AGENTMEMORY_DOCKER_GID"] === hostGid) process.env["AGENTMEMORY_DOCKER_SKIP_CHOWN"] ??= "1";
-}
 function isInvokedViaNpx() {
 	if (process.env["npm_lifecycle_event"] === "npx") return true;
 	if ((process.argv[1] ?? "").includes("_npx")) return true;
@@ -1824,49 +2908,46 @@ async function maybeOfferGlobalInstall() {
 	if (runCommand(npmBin, [
 		"install",
 		"-g",
-		`@agentmemory/agentmemory@0.9.30`
-	], { label: `Installing @agentmemory/agentmemory@0.9.30 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");
 }
-function adoptRunningEngine() {
-	try {
-		const existingState = readEngineState();
-		const existingPid = readEnginePidfile();
-		if (existingState && existingPid) return;
-		const enginePid = findEnginePidsByPort(getRestPort())[0];
-		if (enginePid) {
-			const comm = pidCommand(enginePid);
-			if (isForeignPortHolder(comm)) {
-				vlog(`adoptRunningEngine: refusing to adopt pid ${enginePid} (${comm}) — not the iii engine binary`);
-				return;
-			}
-		}
-		if (enginePid && !existingPid) writeEnginePidfile(enginePid);
-		if (!existingState) writeEngineState({
-			kind: "native",
-			configPath: findIiiConfig() || "",
-			attached: true
-		});
-		if (enginePid && !existingPid) p.log.info(c.ok(`Attached to existing iii-engine (pid ${enginePid})`));
-	} catch (err) {
-		vlog(`adoptRunningEngine: ${err instanceof Error ? err.message : String(err)}`);
-	}
-}
 async function runIiiInstaller() {
 	const releaseUrl = iiiReleaseUrl();
 	const asset = iiiReleaseAsset();
 	const isZipAsset = asset?.endsWith(".zip") === true;
 	if (!releaseUrl) {
-		p.log.warn(`iii-engine binary not available for ${platform()}/${process.arch}. Use Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`);
+		p.log.warn(`iii-engine binary not available for ${platform()}/${process.arch}. Download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`);
 		return {
 			ok: false,
 			binPath: null
 		};
 	}
 	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)\nOr use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`);
+		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
@@ -1905,13 +2986,14 @@ async function runIiiInstaller() {
 		const sha256 = expectedIiiSha256(IIPINNED_VERSION, asset ?? "");
 		const heading = outcome.reason === "checksum" ? "iii-engine download failed verification" : outcome.reason === "no-checksum" ? "iii-engine auto-install skipped" : "iii-engine download failed";
 		const checksumHint = sha256 ? "" : `Compare the archive against ${releaseUrl.replace(/\.(tar\.gz|zip)$/, ".sha256")} before extracting.\n`;
-		p.log.warn(`${heading}: ${outcome.detail.slice(0, 300)}\nInstall it manually, then re-run agentmemory:\n  ${iiiManualInstallCommand(releaseUrl, binDir, binPath, sha256)}\n` + checksumHint + `Or use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`);
+		p.log.warn(`${heading}: ${outcome.detail.slice(0, 300)}\nInstall it manually, then re-run agentmemory:\n  ${iiiManualInstallCommand(releaseUrl, binDir, binPath, sha256)}\n` + checksumHint);
 		return {
 			ok: false,
 			binPath: null
 		};
 	}
 	spinner.stop(`${label} ${pc.green("✓")}`);
+	iiiProbeScan?.delete(binPath);
 	return {
 		ok: true,
 		binPath
@@ -1919,159 +3001,312 @@ async function runIiiInstaller() {
 }
 let startupFailure = null;
 let activeStartupStderr = createStartupStderrCapture();
+let spawnedNativeEngine = null;
+let spawnedComposeDaemon = null;
+let composeStartupCompleted = false;
+let importedStartupWorker = false;
+let spawnedStartupWorker = null;
+let startupWorkerFailure = null;
+let engineReadinessDeadline = null;
+let startupInterrupted = false;
+let finishStartup = () => {};
+function beginStartup() {
+	finishStartup();
+	startupInterrupted = false;
+	const unregister = registerStartupCleanup(cleanupFailedStartup);
+	const interrupt = async (exitCode) => {
+		startupInterrupted = true;
+		process.exit(await runStartupCleanup(exitCode).catch(() => exitCode));
+	};
+	const onInterrupt = () => {
+		interrupt(130);
+	};
+	const onTerminate = () => {
+		interrupt(143);
+	};
+	process.on("SIGINT", onInterrupt);
+	process.on("SIGTERM", onTerminate);
+	finishStartup = () => {
+		process.off("SIGINT", onInterrupt);
+		process.off("SIGTERM", onTerminate);
+		unregister();
+		finishStartup = () => {};
+	};
+}
+function engineStartupFailed() {
+	return startupFailure?.kind === "engine-crashed";
+}
+async function cleanupFailedStartup() {
+	engineReadinessDeadline = null;
+	if (importedStartupWorker && readWorkerPidfile() === process.pid) clearWorkerPidfile();
+	const worker = spawnedStartupWorker;
+	spawnedStartupWorker = null;
+	if (worker && typeof worker.pid === "number") {
+		if (worker.exitCode === null && worker.signalCode === null && !await signalAndWait(worker.pid, "SIGTERM", 3e3)) {
+			p.log.warn(`Started worker pid ${worker.pid} survived shutdown; lifecycle state was preserved.`);
+			return;
+		}
+		if (readWorkerPidfile() === worker.pid) clearWorkerPidfile();
+	}
+	const composeChild = spawnedComposeDaemon;
+	spawnedComposeDaemon = null;
+	if (composeChild && typeof composeChild.pid === "number") if (!await signalAndWait(composeChild.pid, "SIGTERM", 2e4)) p.log.warn(`Compose daemon pid ${composeChild.pid} survived shutdown; lifecycle state was preserved.`);
+	else clearEngineState();
+	const child = spawnedNativeEngine;
+	spawnedNativeEngine = null;
+	if (!child || typeof child.pid !== "number") return;
+	if (!IS_WINDOWS) try {
+		process.kill(-child.pid, "SIGTERM");
+	} catch {}
+	if (child.exitCode === null && child.signalCode === null) {
+		if (!await signalAndWait(child.pid, "SIGTERM", 3e3)) {
+			p.log.warn(`Started engine pid ${child.pid} survived shutdown; lifecycle state was preserved.`);
+			return;
+		}
+	}
+	if (readEnginePidfile() === child.pid) {
+		clearEnginePidfile();
+		clearEngineState();
+	}
+}
 function printCapturedStartupStderr() {
 	const stderr = redactCredentialUrls(activeStartupStderr.text().trim());
 	if (IS_VERBOSE && stderr) p.note(stderr, "engine stderr");
 }
-function printDockerStartupLogs() {
+function readComposeStartupLogs() {
 	const state = readEngineState();
-	if (state?.kind !== "docker") return;
-	const inspection = inspectOwnedDockerEngine(state);
-	if (inspection.status !== "running" && inspection.status !== "stopped") return;
-	const dockerBin = whichBinary("docker");
-	if (!dockerBin) return;
-	const result = spawnSync(dockerBin, [
-		"logs",
-		"--tail",
-		"80",
-		inspection.containerId
-	], {
-		encoding: "utf-8",
-		stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		],
-		timeout: 5e3,
-		maxBuffer: 64 * 1024
-	});
-	const output = redactCredentialUrls(`${result.stdout ?? ""}${result.stderr ?? ""}`.trim());
-	if (output) p.note(output.slice(-16 * 1024), "docker engine logs");
+	if (state?.kind !== "compose") return null;
+	try {
+		const text = readComposeLogFromOffset(state.logFile, state.logStartOffset ?? 0).trim();
+		return {
+			path: state.logFile,
+			text: redactCredentialUrls(text.slice(-16 * 1024))
+		};
+	} catch {
+		return {
+			path: state.logFile,
+			text: "(Compose log file could not be read.)"
+		};
+	}
 }
-function spawnEngineBackground(bin, spawnArgs, label, cwd) {
-	vlog(`spawn: ${bin} ${spawnArgs.join(" ")}${cwd ? ` (cwd: ${cwd})` : ""}`);
-	activeStartupStderr = createStartupStderrCapture();
-	const child = spawn(bin, spawnArgs, {
-		detached: true,
-		stdio: [
-			"ignore",
-			"ignore",
-			"pipe"
-		],
-		windowsHide: true,
-		env: engineChildEnv(process.env),
-		...cwd ? { cwd } : {}
-	});
-	const isDocker = label.includes("Docker");
-	if (!isDocker && typeof child.pid === "number") writeEnginePidfile(child.pid);
-	child.stderr?.on("data", (chunk) => {
-		activeStartupStderr.append(chunk);
-	});
-	child.on("exit", (code, signal) => {
-		if (code !== null && code !== 0 || code === null && signal !== null) {
-			const stderr = redactCredentialUrls(activeStartupStderr.text());
-			startupFailure = {
-				kind: isDocker ? "docker-crashed" : "engine-crashed",
-				stderr: stderr.trim() || (signal ? `process killed by signal ${signal}` : `process exited with code ${code}`),
-				binary: bin
-			};
-			vlog(`engine exited early: code=${code} signal=${signal}`);
-			if (IS_VERBOSE && stderr.trim()) p.log.error(`engine stderr:\n${stderr}`);
-			if (!isDocker) {
-				clearEnginePidfile();
-				clearEngineState();
-			}
-		}
-	});
-	child.unref();
-	return child;
+function printComposeStartupLogs() {
+	const logs = readComposeStartupLogs();
+	if (!logs) return;
+	if (logs.text) p.note(`Log file: ${logs.path}\n\n${logs.text}`, "Recent Worker Compose output");
 }
-function prepareEngineLaunch(configPath) {
-	const home = homedir();
-	const bundledConfig = isBundledConfig(configPath, __dirname);
-	const cwd = resolveEngineCwd(configPath, process.cwd(), home, bundledConfig);
-	const stateBackendKind = getStateBackend();
+function composePidMatches(pid, state) {
+	return composePidIdentity(pid, state) === "match";
+}
+function composePidIdentity(pid, state) {
+	return classifyComposeProcess(inspectComposeProcess(pid), state, IS_WINDOWS);
+}
+function inspectComposeProcess(pid) {
 	try {
-		mkdirSync(cwd, { recursive: true });
-	} catch (err) {
-		const failure = resolveLaunchRenderFailure(stateBackendKind, err);
-		if (failure.fatal) {
-			p.log.error(failure.message);
-			process.exit(1);
+		let command = "";
+		let executable = "";
+		if (IS_WINDOWS) {
+			const result = execFileSync("powershell.exe", [
+				"-NoProfile",
+				"-NonInteractive",
+				"-Command",
+				`$process = Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}'; if ($process) { @{ command = $process.CommandLine; executable = $process.ExecutablePath } | ConvertTo-Json -Compress }`
+			], {
+				encoding: "utf8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			}).trim();
+			const processInfo = JSON.parse(result);
+			command = processInfo.command ?? "";
+			executable = processInfo.executable ?? "";
+		} else if (platform() === "darwin") {
+			command = execFileSync("ps", [
+				"-p",
+				String(pid),
+				"-o",
+				"command="
+			], {
+				encoding: "utf8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			}).trim();
+			executable = readUnixProcessExecutable(pid, "darwin");
+		} else {
+			command = execFileSync("ps", [
+				"-p",
+				String(pid),
+				"-o",
+				"command="
+			], {
+				encoding: "utf8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			}).trim();
+			executable = readUnixProcessExecutable(pid, "linux");
 		}
 		return {
-			configPath,
-			cwd: process.cwd()
+			command,
+			executable
 		};
+	} catch {
+		return null;
 	}
+}
+function composeChildProcesses(state) {
+	if (IS_WINDOWS || !state.composePid) return [];
 	try {
-		const rawConfig = readFileSync(configPath, "utf-8");
-		const options = {
-			dataDir: dataDirResolution.dataDir,
-			ports: {
-				restPort: getRestPort(),
-				streamPort: getStreamPort(),
-				viewerPort: getConfiguredViewerPort(),
-				enginePort: getEnginePort()
-			},
-			stateBackend: {
-				kind: stateBackendKind,
-				redisUrl: getRedisUrl()
-			},
-			saveIntervalMs: getStateSaveIntervalMs()
-		};
-		const rewritten = bundledConfig ? rewriteBundledConfig(rawConfig, home, process.execPath, join(__dirname, "index.mjs"), options) : renderEngineConfig(rawConfig, options);
-		const runtimePath = runtimeConfigPath(dataDirResolution.dataDir);
-		mkdirSync(dirname(runtimePath), { recursive: true });
-		writeFileSync(runtimePath, rewritten, "utf-8");
+		const rows = execFileSync("ps", ["-eo", "pid=,ppid=,pgid=,command="], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).split(/\r?\n/).map((row) => {
+			const match = row.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/);
+			return match ? {
+				pid: Number(match[1]),
+				ppid: Number(match[2]),
+				pgid: Number(match[3]),
+				args: match[4]
+			} : null;
+		}).filter((row) => row !== null);
+		const descendants = new Set([state.composePid]);
+		let changed = true;
+		while (changed) {
+			changed = false;
+			for (const row of rows) if (!descendants.has(row.pid) && descendants.has(row.ppid)) {
+				descendants.add(row.pid);
+				changed = true;
+			}
+		}
+		return rows.filter((row) => row.pid !== state.composePid && descendants.has(row.pid)).map(({ pid, pgid, args }) => ({
+			pid,
+			pgid,
+			args
+		}));
+	} catch {
+		return [];
+	}
+}
+function composeChildPids(state) {
+	return [...new Set(composeChildProcesses(state).map((child) => child.pid))];
+}
+function composeEnginePid(state) {
+	return composeChildProcesses(state).find(({ args }) => args.includes(" --config ") && args.includes(state.namespace))?.pid;
+}
+async function terminateComposeChildren(state) {
+	if (IS_WINDOWS) return true;
+	const groups = [...new Set(composeChildProcesses(state).map((child) => child.pgid).filter((pgid) => pgid !== state.composePid))];
+	let stopped = true;
+	for (const pgid of groups) {
 		try {
-			const cleared = clearPersistedBuiltinConfig(cwd, runtimePath, rewritten);
-			if (cleared.length > 0) vlog(`cleared ${cleared.length} persisted builtin config entries so the rendered runtime config seeds the engine again`);
+			process.kill(-pgid, "SIGTERM");
 		} catch (err) {
-			p.log.error(`${String(err instanceof Error ? err.message : err)}. The engine would ignore the rendered runtime config and keep its previously persisted ports and timeouts. Fix the permissions on that file and run agentmemory start again.`);
-			process.exit(1);
+			if (err.code !== "ESRCH") stopped = false;
+			continue;
 		}
-		if (selectedInstance === 0 && dataDirResolution.source === "default") {
-			for (const m of legacyDataMigrations(process.cwd(), home, dataDirResolution.dataDir)) if (existsSync(m.from) && !existsSync(m.to)) try {
-				mkdirSync(dirname(m.to), { recursive: true });
-				cpSync(m.from, m.to, { recursive: true });
-				p.log.info(`Copied existing data: ${m.from} -> ${m.to}`);
-			} catch (err) {
-				vlog(`data copy failed for ${m.from}: ${String(err)}`);
+		const deadline = Date.now() + 5e3;
+		while (Date.now() < deadline) {
+			try {
+				process.kill(-pgid, 0);
+			} catch {
+				break;
 			}
+			await new Promise((resolve) => setTimeout(resolve, 100));
 		}
-		return {
-			configPath: runtimePath,
-			cwd
-		};
-	} catch (err) {
-		const failure = resolveLaunchRenderFailure(stateBackendKind, err);
-		if (failure.fatal) {
-			p.log.error(failure.message);
-			process.exit(1);
-		}
-		vlog(`runtime config generation failed, using bundled config verbatim: ${String(err)}`);
-		return {
-			configPath,
-			cwd
-		};
+		try {
+			process.kill(-pgid, 0);
+			process.kill(-pgid, "SIGKILL");
+		} catch {}
 	}
+	for (const pid of composeChildPids(state)) if (pidAlive(pid) && !await signalAndWait(pid, "SIGTERM", 1e3)) stopped = false;
+	return stopped;
 }
-function startIiiBin(iiiBin, configPath) {
-	const s = p.spinner();
-	s.start(`Starting iii-engine: ${iiiBin}`);
-	const launch = prepareEngineLaunch(configPath);
-	writeEngineState({
-		kind: "native",
-		configPath: launch.configPath,
-		binPath: iiiBin
+async function startIiiBin(iiiBin) {
+	const workerBinDir = process.env["AGENTMEMORY_WORKER_BIN_DIR"]?.trim() || void 0;
+	if (workerBinDir && (!existsSync(resolve(process.cwd(), workerBinDir)) || !["state", "http"].every((name) => existsSync(join(resolve(process.cwd(), workerBinDir), name))))) throw new Error(`AGENTMEMORY_WORKER_BIN_DIR must contain executable state and http binaries: ${workerBinDir}`);
+	const envPath = process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env");
+	const namespace = composeNamespace(getRestPort());
+	const projectRoot = resolve(__dirname, "..");
+	const ports = {
+		restPort: getRestPort(),
+		viewerPort: getConfiguredViewerPort(),
+		enginePort: getEnginePort()
+	};
+	await assertComposePortsFree([
+		ports.restPort,
+		ports.viewerPort,
+		ports.enginePort
+	]);
+	const compose = startComposeDaemon({
+		ports,
+		dataDir: dataDirResolution.dataDir,
+		projectRoot,
+		nodeBin: process.execPath,
+		homeDir: homedir(),
+		...existsSync(envPath) ? { envFile: envPath } : {},
+		...workerBinDir ? { workerBinDir } : {},
+		cwd: process.cwd(),
+		stateBackend: { kind: getStateBackend() },
+		...getStateBackend() === "redis" && getRedisUrl() ? { redisUrl: getRedisUrl() } : {},
+		workerEnvironment: process.env,
+		disableRestartPolicy: process.env["AGENTMEMORY_DISABLE_COMPOSE_RESTART"] === "1",
+		startupTimeoutMs: startupTimeouts().workerMs,
+		linux: process.platform === "linux",
+		stateDir: join(dataDirResolution.dataDir, "compose-state"),
+		logFile: join(homedir(), ".agentmemory", `compose-${getRestPort()}.log`),
+		iiiBin,
+		env: process.env
+	});
+	spawnedComposeDaemon = compose.child;
+	composeStartupCompleted = false;
+	if (typeof compose.child.pid !== "number") throw new Error("Failed to spawn the iii Compose daemon.");
+	const state = {
+		kind: "compose",
+		restPort: getRestPort(),
+		viewerPort: getConfiguredViewerPort(),
+		enginePort: getEnginePort(),
+		engineUrl: `ws://127.0.0.1:${getEnginePort()}`,
+		namespace,
+		file: compose.file,
+		stateDir: compose.stateDir,
+		logFile: compose.logFile,
+		logStartOffset: compose.logStartOffset,
+		binPath: iiiBin,
+		composePid: compose.child.pid,
+		...workerBinDir ? { workerBinDir: resolve(process.cwd(), workerBinDir) } : {}
+	};
+	writeComposeState(engineStatePath(), {
+		...state,
+		workerVersions: workerBinDir ? { local: true } : COMPOSE_WORKER_VERSIONS
+	});
+	engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);
+	compose.child.on("error", (error) => {
+		if (spawnedComposeDaemon === compose.child) startupFailure = {
+			kind: "engine-crashed",
+			stderr: redactCredentialUrls(error.message),
+			binary: iiiBin
+		};
+	});
+	compose.child.on("exit", (code, signal) => {
+		if (spawnedComposeDaemon === compose.child && !composeStartupCompleted && (code !== 0 || signal !== null)) startupFailure = {
+			kind: "engine-crashed",
+			stderr: signal ? `Compose exited from ${signal}` : `Compose exited with code ${code}`,
+			binary: iiiBin
+		};
 	});
-	spawnEngineBackground(iiiBin, [
-		"--config",
-		launch.configPath,
-		"--no-update-check"
-	], "iii-engine", launch.cwd);
-	s.stop(c.ok("iii-engine process started"));
+	const s = p.spinner();
+	s.start(`Starting iii Worker Compose: ${iiiBin}`);
+	s.stop(c.ok(`Compose daemon started (pid ${compose.child.pid})`));
 	return true;
 }
 function pickCompatibleIii(candidates) {
@@ -2082,11 +3317,17 @@ function pickCompatibleIii(candidates) {
 	}
 	return null;
 }
-function warnIfDockerIgnoresStateBackend(stateBackendKind) {
-	if (stateBackendKind !== "redis") return;
-	p.log.warn("AGENTMEMORY_STATE_BACKEND=redis is not applied on the Docker path: docker-compose.yml mounts iii-config.docker.yaml read-only, so this start will not render it. Edit iii-config.docker.yaml by hand to point iii-state/iii-stream at redis (see README \"Storage backend\"), or it keeps using the file store. docker-compose.yml passes AGENTMEMORY_REDIS_URL into the engine container, so redis_url: '${AGENTMEMORY_REDIS_URL}' works in that file.");
-}
 async function startEngine() {
+	iiiProbeScan = /* @__PURE__ */ new Map();
+	try {
+		return await scanAndStartEngine();
+	} finally {
+		iiiProbeScan = null;
+	}
+}
+async function scanAndStartEngine() {
+	startupFailure = null;
+	engineReadinessDeadline = null;
 	let stateBackendKind;
 	try {
 		stateBackendKind = getStateBackend();
@@ -2098,58 +3339,49 @@ async function startEngine() {
 		p.log.error("AGENTMEMORY_STATE_BACKEND=redis requires AGENTMEMORY_REDIS_URL to be set (e.g. redis://localhost:6379). Set both in ~/.agentmemory/.env, or unset AGENTMEMORY_STATE_BACKEND to keep the default file store.");
 		process.exit(1);
 	}
-	await assertRuntimePortOwnership();
 	const persistedState = readEngineState();
 	if (persistedState?.kind === "docker") {
-		warnIfDockerIgnoresStateBackend(stateBackendKind);
-		const inspection = inspectOwnedDockerEngine(persistedState);
-		if (inspection.status === "unavailable" || inspection.status === "missing") {
-			const detail = inspection.status === "unavailable" ? inspection.reason : "container is missing";
-			p.log.error(`A saved Docker engine owns this lifecycle state, but it cannot be resumed safely (${detail}). Run \`agentmemory stop\` to reconcile that project before starting another engine.`);
-			return false;
+		p.log.error(legacyDockerStateMessage(persistedState));
+		return false;
+	}
+	await assertRuntimePortOwnership();
+	if (persistedState?.kind === "compose") {
+		if (await isEngineRunning()) {
+			p.log.error("The managed Worker Compose engine is already running; it should have been reconciled before attempting a fresh start.");
+			process.exit(1);
+		}
+		if (persistedState.restPort === getRestPort()) {
+			if (persistedState.composePid && pidAlive(persistedState.composePid)) {
+				p.log.error(`Worker Compose daemon ${persistedState.composePid} is still alive. Stop it before retrying.`);
+				process.exit(1);
+			}
+			clearEngineState();
 		}
-		persistDockerInspection(persistedState, inspection);
-		if (inspection.status === "running") return true;
-		const dockerBin = whichBinary("docker");
-		return Boolean(dockerBin && runCommand(dockerBin, ["start", inspection.containerId], { label: `Restarting owned Docker container ${inspection.containerId}` }));
 	}
-	const configPath = findIiiConfig();
 	warnIfRelocatedDataDir();
 	const pathIii = whichBinary("iii");
-	vlog(`iii binary: ${pathIii ?? "(not on PATH)"}, config: ${configPath || "(not found)"}`);
-	const dockerBin = whichBinary("docker");
-	const composeFile = [
-		join(__dirname, "..", "docker-compose.yml"),
-		join(__dirname, "docker-compose.yml"),
-		join(process.cwd(), "docker-compose.yml")
-	].find((c) => existsSync(c));
-	const dockerOptIn = process.env["AGENTMEMORY_USE_DOCKER"] === "1" || process.env["AGENTMEMORY_USE_DOCKER"] === "true";
+	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 && configPath && !(dockerOptIn && dockerBin && composeFile)) {
+	if (iiiBin) {
 		if (iiiBin !== pathIii) {
 			p.log.info(`Using iii at: ${c.dim(iiiBin)} (v${c.accent(IIPINNED_VERSION)})`);
 			process.env["PATH"] = `${dirname(iiiBin)}${delimiter}${process.env["PATH"] ?? ""}`;
 		}
-		return startIiiBin(iiiBin, configPath);
+		return startIiiBin(iiiBin);
 	}
 	if (pathIii && !iiiBin) vlog(`iii on PATH is v${iiiBinVersion(pathIii) ?? "unknown"}, pin is v${IIPINNED_VERSION}. Will install pinned engine to ${privateIiiPath()}.`);
-	if (!configPath) {
-		startupFailure = { kind: "no-engine" };
-		return false;
-	}
-	vlog(`docker binary: ${dockerBin ?? "(not on PATH)"}`);
 	mkdirSync(dataDirResolution.dataDir, { recursive: true });
-	vlog(`docker-compose.yml: ${composeFile ?? "(not found)"}`);
 	const interactive = !!process.stdin.isTTY && !process.env["CI"];
 	let choice;
-	const pathIiiMismatch = pathIii !== null && resolveCompatibleIii(pathIii) === null;
-	if (dockerOptIn && dockerBin && composeFile) choice = "docker";
-	else if (pathIiiMismatch) {
+	if (pathIii !== null && resolveCompatibleIii(pathIii) === null) {
 		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.");
@@ -2160,11 +3392,6 @@ async function startEngine() {
 			label: `Install iii v${IIPINNED_VERSION} to ~/.agentmemory/bin (~6MB, ~5s)`,
 			hint: "recommended"
 		}];
-		if (dockerBin && composeFile) options.push({
-			value: "docker",
-			label: "Use Docker compose",
-			hint: "advanced"
-		});
 		options.push({
 			value: "manual",
 			label: "Show manual install steps and exit"
@@ -2189,87 +3416,29 @@ async function startEngine() {
 		if (result.ok && result.binPath) {
 			process.env["PATH"] = `${dirname(result.binPath)}${delimiter}${process.env["PATH"] ?? ""}`;
 			iiiBin = result.binPath;
-			return startIiiBin(iiiBin, configPath);
-		}
-		if (dockerBin && composeFile && interactive) {
-			const fallback = await p.confirm({
-				message: "Auto-install failed. Try Docker compose instead?",
-				initialValue: true
-			});
-			if (p.isCancel(fallback) || fallback !== true) {
-				startupFailure = { kind: "no-engine" };
-				return false;
-			}
-			choice = "docker";
-		} else {
-			startupFailure = { kind: "no-engine" };
-			return false;
+			return startIiiBin(iiiBin);
 		}
+		startupFailure = { kind: "no-engine" };
+		return false;
 	}
-	if (choice === "docker" && dockerBin && composeFile) {
-		warnIfDockerIgnoresStateBackend(stateBackendKind);
-		const s = p.spinner();
-		s.start("Starting iii-engine via Docker...");
-		configureDockerHostUser();
-		const projectName = dockerProjectName(getRestPort());
-		writeEngineState({
-			kind: "docker",
-			schemaVersion: 2,
-			composeFile,
-			projectName,
-			engineVersion: IIPINNED_VERSION,
-			dataMountType: "bind",
-			dataMountSource: dataDirResolution.dataDir,
-			preserveContainer: false
-		});
-		spawnEngineBackground(dockerBin, dockerComposeArgs(composeFile, projectName, ["up", "-d"]), "iii-engine via Docker");
-		s.stop("Docker compose started");
-		return true;
-	}
-	if (!composeFile && dockerBin) startupFailure = { kind: "no-docker-compose" };
-	else startupFailure = { kind: "no-engine" };
+	startupFailure = { kind: "no-engine" };
 	return false;
 }
-async function waitForEngine(timeoutMs) {
-	const start = Date.now();
-	while (Date.now() - start < timeoutMs) {
-		if (await isEngineRunning()) return true;
-		await new Promise((r) => setTimeout(r, 500));
-	}
-	return false;
+async function waitForEngine(timeoutMs = startupTimeouts().engineMs) {
+	const state = readEngineState();
+	const endpoint = state?.kind === "compose" ? managedComposeReadinessUrl(state.restPort) : getBaseUrl();
+	const probe = state?.kind === "compose" ? (signal) => probeEngine(endpoint, signal) : (signal) => probeEngine(endpoint, signal);
+	return waitForReadiness(engineReadinessDeadline ?? startupDeadline(timeoutMs), probe, {
+		intervalMs: 250,
+		probeTimeoutMs: 750,
+		stopped: () => startupInterrupted || engineStartupFailed()
+	});
 }
-async function reconcilePersistedDockerEngine() {
+async function waitForPersistedNativeEngine() {
 	const state = readEngineState();
-	if (state?.kind !== "docker") return false;
-	const inspection = inspectOwnedDockerEngine(state);
-	if (inspection.status === "unavailable") {
-		p.log.error(`The saved Docker engine cannot be verified: ${inspection.reason}. Refusing to overwrite its lifecycle state. Run \`agentmemory stop\` after restoring Docker/compose access.`);
-		process.exit(1);
-	}
-	if (inspection.status === "missing") {
-		p.log.error("The saved Docker project no longer has an iii-engine container. Run `agentmemory stop` to remove its stale project state, then start agentmemory again.");
-		process.exit(1);
-	}
-	persistDockerInspection(state, inspection);
-	if (inspection.status === "stopped") {
-		const dockerBin = whichBinary("docker");
-		if (!dockerBin || !runCommand(dockerBin, ["start", inspection.containerId], { label: `Restarting owned Docker container ${inspection.containerId}` })) {
-			p.log.error("The owned Docker container could not be restarted; lifecycle state was preserved.");
-			process.exit(1);
-		}
-	}
-	if (!await waitForEngine(5e3)) {
-		printDockerStartupLogs();
-		p.log.error(`The owned Docker container is running, but its REST API on port ${getRestPort()} is unhealthy. The saved project was preserved; inspect the Docker logs above or run \`agentmemory stop\`.`);
-		process.exit(1);
-	}
-	await startWorkerForEngineState();
-	if (!await waitForAgentmemoryReady(15e3)) {
-		p.log.error("agentmemory worker did not become ready within 15s.");
-		process.exit(1);
-	}
-	await maybeOfferGlobalInstall();
-	printReadyHint();
+	const pid = readEnginePidfile();
+	if (state?.kind !== "native" || !pid || !pidAlive(pid) || isForeignPortHolder(pidCommand(pid))) return false;
+	if (!await waitForEngine()) throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));
 	return true;
 }
 function installInstructions() {
@@ -2285,12 +3454,9 @@ 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",
 			"",
-			`  B) Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
-			"     Re-run with AGENTMEMORY_USE_DOCKER=1 npx @agentmemory/agentmemory",
-			"",
 			"Or skip the engine entirely (standalone MCP):  npx @agentmemory/agentmemory mcp",
 			"",
 			"Docs: https://iii.dev/docs"
@@ -2303,9 +3469,6 @@ function installInstructions() {
 		linuxInstall,
 		"     Then re-run: npx @agentmemory/agentmemory",
 		"",
-		`  B) Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
-		"     Re-run with AGENTMEMORY_USE_DOCKER=1 npx @agentmemory/agentmemory",
-		"",
 		"Or skip the engine entirely (standalone MCP):  npx @agentmemory/agentmemory mcp",
 		"",
 		"Docs: https://iii.dev/docs"
@@ -2314,85 +3477,101 @@ function installInstructions() {
 function portInUseDiagnostic(port) {
 	return IS_WINDOWS ? `  netstat -ano | findstr :${port}` : `  lsof -i :${port}   # or: ss -tlnp | grep :${port}`;
 }
-async function waitForAgentmemoryReady(timeoutMs) {
-	const start = Date.now();
-	while (Date.now() - start < timeoutMs) {
-		if (await isAgentmemoryReady()) return true;
-		await new Promise((r) => setTimeout(r, 250));
-	}
-	return false;
-}
-function getEngineHost() {
-	const envKeys = shouldUseAgentmemoryUrl() ? ["III_ENGINE_URL", "AGENTMEMORY_URL"] : ["III_ENGINE_URL"];
-	for (const envKey of envKeys) {
-		const raw = process.env[envKey];
-		if (!raw) continue;
-		try {
-			const parsed = new URL(raw);
-			if (parsed.hostname) return parsed.hostname;
-		} catch {}
-	}
-	return "localhost";
-}
 function printReadyHint() {
 	const restUrl = getBaseUrl();
 	const viewerUrl = getViewerUrl();
-	const engineHost = getEngineHost();
-	const streamUrl = `ws://${engineHost}:${getStreamPort()}`;
-	const engineUrl = `ws://${engineHost}:${getEnginePort()}`;
+	const engineUrl = process.env["III_ENGINE_URL"] || `ws://localhost:${getEnginePort()}`;
 	const invocation = isInvokedViaNpx() ? "npx @agentmemory/agentmemory" : "agentmemory";
-	const consolePort = defaultConsolePort(getConfiguredViewerPort());
 	const portFlags = portFlagSuffix(getRestPort(), selectedInstance);
-	const consoleLine = `${c.label("iii console")}  ${c.cmd(`${invocation} console${portFlags}`)}  ${c.dim(`(serves on :${consolePort}; first run downloads the console next to the pinned iii)`)}`;
 	const lines = [
 		`${c.label("REST API")}     ${c.url(restUrl)}`,
 		`${c.label("Viewer")}       ${c.url(viewerUrl)}`,
-		`${c.label("Streams")}      ${c.url(streamUrl)}`,
-		`${c.label("Engine")}       ${c.url(engineUrl)}`,
-		consoleLine
+		`${c.label("Engine")}       ${c.url(engineUrl)}`
 	];
 	p.note(lines.join("\n"), `agentmemory v${c.accent(VERSION)}`);
 	const demoCommand = `${invocation} demo${portFlags}`;
 	process.stdout.write(`\n${c.dim("Try:")} ${c.cmd(demoCommand)}\n`);
 }
+async function reconcilePersistedComposeEngine() {
+	const state = readEngineState();
+	if (state?.kind !== "compose") return false;
+	if (!await isEngineRunning()) {
+		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);
+		}
+		if (await isEngineRunning()) {
+			p.log.error(`An engine is responding on :${state.restPort}, but the recorded Compose daemon is gone. Refusing to adopt or clear this endpoint automatically.`);
+			process.exit(1);
+		}
+		clearEngineState();
+		p.log.info("Found stale Worker Compose lifecycle state; starting a fresh managed instance.");
+		return false;
+	}
+	const version = iiiBinVersion(state.binPath);
+	if (state.composePid && !composePidMatches(state.composePid, state)) {
+		p.log.error(`Compose metadata points to PID ${state.composePid}, but its process identity does not match the saved engine/file/namespace.`);
+		process.exit(1);
+	}
+	if (version !== IIPINNED_VERSION) {
+		p.log.error(`Managed Compose engine is ${version ?? "unverified"}; expected ${IIPINNED_VERSION}. Run agentmemory stop before changing the runtime.`);
+		process.exit(1);
+	}
+	try {
+		if (!ownedComposeProject(await composeCall({
+			engineUrl: state.engineUrl,
+			namespace: state.namespace,
+			functionId: "compose::status",
+			file: state.file
+		}), state.file)) throw new Error("Compose daemon does not report the owned worker-compose.yaml project.");
+	} catch (err) {
+		p.log.error(`Could not verify the managed Compose project: ${err instanceof Error ? err.message : String(err)}. See ${state.logFile}.`);
+		process.exit(1);
+	}
+	return true;
+}
 async function main() {
+	startupTimeouts();
 	await assertRuntimePortOwnership();
 	try {
-		if ((await fetch(`${getBaseUrl()}/agentmemory/livez`, { signal: AbortSignal.timeout(1500) })).ok) {
+		if ((await fetch(`${getBaseUrl()}/agentmemory/livez`, { signal: AbortSignal.timeout(1500) })).ok && readEngineState()?.kind !== "compose") {
 			p.log.error(`agentmemory is already running on port ${getRestPort()}. Starting a second instance here would corrupt the running daemon's REST routing. Use the REST API (or the MCP tools) against the running instance, run a different --instance, or stop it first with \`agentmemory stop\`.`);
 			process.exit(1);
 		}
 	} catch {}
+	const legacyState = readEngineState();
+	if (legacyState?.kind === "docker") {
+		p.intro("agentmemory");
+		p.log.error(legacyDockerStateMessage(legacyState));
+		process.exit(1);
+	}
 	if (IS_RESET) resetPrefs();
 	const firstRun = isFirstRun();
 	const prefs = readPrefs();
 	if (firstRun || IS_RESET || IS_VERBOSE || !prefs.skipSplash) renderSplash(VERSION);
 	if (firstRun || IS_RESET) await runOnboarding();
+	beginStartup();
 	if (skipEngine) {
 		if (IS_VERBOSE) p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-Jsq9LCeH.mjs");
-		if (await waitForAgentmemoryReady(15e3)) {
-			await maybeOfferGlobalInstall();
-			printReadyHint();
-		}
+		await startWorkerForEngineState();
+		await maybeOfferGlobalInstall();
+		printReadyHint();
+		return;
+	}
+	if (await reconcilePersistedComposeEngine()) {
+		await startWorkerForEngineState();
+		await maybeOfferGlobalInstall();
+		printReadyHint();
 		return;
 	}
-	if (await reconcilePersistedDockerEngine()) return;
-	if (await isEngineRunning()) {
+	if (await isEngineRunning() || await waitForPersistedNativeEngine()) {
 		if (IS_VERBOSE) p.log.success("iii-engine is running");
 		const persisted = readEngineState();
 		const attachedBin = (persisted?.kind === "native" && persisted.binPath && existsSync(persisted.binPath) ? persisted.binPath : null) ?? whichBinary("iii") ?? fallbackIiiPaths().find((p) => existsSync(p)) ?? null;
-		const detected = attachedBin ? iiiBinVersion(attachedBin) : null;
+		const detected = persisted?.kind === "compose" ? iiiBinVersion(persisted.binPath) : attachedBin ? iiiBinVersion(attachedBin) : null;
 		if (detected === IIPINNED_VERSION) {
-			adoptRunningEngine();
-			await startWorkerForEngineState();
-			if (!await waitForAgentmemoryReady(15e3)) {
-				p.log.error("agentmemory worker did not become ready within 15s.");
-				process.exit(1);
-			}
-			await maybeOfferGlobalInstall();
-			printReadyHint();
-			return;
+			p.log.error(`An unmanaged iii engine is already listening on ${getEnginePort()}. Agentmemory will not attach to it; stop that engine explicitly or select another --instance/--port.`);
+			process.exit(1);
 		}
 		const detectedLabel = detected ? `v${detected}` : "an unverified version";
 		const base = isInvokedViaNpx() ? "npx @agentmemory/agentmemory" : "agentmemory";
@@ -2419,17 +3598,42 @@ async function main() {
 	if (!await startEngine()) {
 		p.log.error("Could not start iii-engine.");
 		const lines = installInstructions();
-		if (startupFailure?.kind === "no-docker-compose") lines.unshift("Docker is installed but docker-compose.yml is missing from this", "install. Re-install with: npm install -g @agentmemory/agentmemory", "");
 		p.note(lines.join("\n"), "Setup required");
-		process.exit(1);
+		throw new Error("iii-engine could not be started.");
 	}
 	const s = p.spinner();
 	s.start("Waiting for iii-engine to be ready...");
-	if (!await waitForEngine(15e3)) {
+	const ready = await waitForEngine();
+	if (ready) {
+		const composeState = readEngineState();
+		if (composeState?.kind === "compose") {
+			composeState.enginePid = composeEnginePid(composeState);
+			writeComposeState(engineStatePath(), {
+				...composeState,
+				workerVersions: composeState.workerVersions ?? COMPOSE_WORKER_VERSIONS
+			});
+		}
+	}
+	if (!ready) {
 		const port = getRestPort();
-		s.stop("iii-engine did not become ready within 15s");
-		printDockerStartupLogs();
-		if (startupFailure?.kind === "engine-crashed" || startupFailure?.kind === "docker-crashed") {
+		let composeState = readEngineState();
+		let composeLog = composeState?.kind === "compose" ? readComposeStartupLogs() : null;
+		if (composeState?.kind === "compose" && spawnedComposeDaemon?.exitCode !== null) {
+			await new Promise((resolve) => setTimeout(resolve, 150));
+			composeLog = readComposeStartupLogs() ?? composeLog;
+		}
+		let registryFailure = null;
+		if (composeState?.kind === "compose") {
+			const stateFailure = composeState.workerFailure ?? composeStateRegistryFailure(dataDirResolution.dataDir, composeState.file);
+			const logFailure = composeLog ? composeRegistryFailureMessage(composeLog.text, composeState.workerBinDir) : null;
+			if (stateFailure) registryFailure = `Worker registry unavailable while resolving state/http; retry later or set AGENTMEMORY_WORKER_BIN_DIR. Compose reported: ${stateFailure}`;
+			else registryFailure = logFailure;
+		}
+		const composeLogTail = composeLog?.text.trim().split(/\r?\n/).slice(-12).join("\n");
+		const shortFailure = registryFailure || startupFailure?.stderr || (composeState?.kind === "compose" && composeLogTail ? `Worker Compose startup failed. Recent Compose output:\n${composeLogTail}` : startupTimeoutMessage("engine", startupTimeouts().engineMs));
+		s.stop(shortFailure);
+		printComposeStartupLogs();
+		if (startupFailure?.kind === "engine-crashed") {
 			p.log.error("The iii-engine process crashed on startup.");
 			if (startupFailure.binary) p.log.info(`Binary: ${startupFailure.binary}`);
 			if (startupFailure.stderr) p.note(startupFailure.stderr, "engine stderr");
@@ -2438,7 +3642,6 @@ async function main() {
 				"Common causes:",
 				`  - iii-engine version mismatch — reinstall the pinned v${IIPINNED_VERSION} binary`,
 				"    (sh script on macOS/Linux, GitHub release zip on Windows)",
-				"  - Docker Desktop not running (if you're using the Docker path)",
 				"  - Port already in use (see below)",
 				"",
 				"See https://iii.dev/docs for current install instructions."
@@ -2456,17 +3659,26 @@ async function main() {
 				"Re-run with --verbose to see engine stderr."
 			].join("\n"), "Troubleshooting");
 		}
-		process.exit(1);
+		if (composeLog?.text) p.log.error(`Compose log: ${composeLog.path}`);
+		throw new Error(shortFailure);
 	}
 	s.stop(c.ok("iii-engine is ready"));
 	await startWorkerForEngineState();
-	if (!await waitForAgentmemoryReady(15e3)) {
-		p.log.error("agentmemory worker did not become ready within 15s.");
-		process.exit(1);
+	const managedCompose = readEngineState();
+	if (managedCompose?.kind === "compose" && !managedCompose.enginePid) {
+		managedCompose.enginePid = composeChildPids(managedCompose)[0];
+		writeComposeState(engineStatePath(), {
+			...managedCompose,
+			workerVersions: managedCompose.workerVersions ?? COMPOSE_WORKER_VERSIONS
+		});
 	}
 	await maybeOfferGlobalInstall();
 	printReadyHint();
 	writePrefs({ skipSplash: true });
+	if (managedCompose?.kind === "compose") {
+		await new Promise((resolve) => process.stdout.write("", () => resolve()));
+		process.exit(0);
+	}
 }
 async function apiFetch(base, path, timeoutMs = 5e3) {
 	try {
@@ -2480,10 +3692,29 @@ async function apiFetch(base, path, timeoutMs = 5e3) {
 	}
 }
 async function runStatus() {
-	getRestPort();
 	const base = getBaseUrl();
 	p.intro("agentmemory status");
+	const state = readEngineState();
+	const savedState = !(shouldUseAgentmemoryUrl() && process.env["AGENTMEMORY_URL"]) && (state?.kind !== "compose" || state.restPort === getRestPort()) ? state : null;
+	if (savedState?.kind === "docker") p.log.warn(legacyDockerStateMessage(savedState));
 	if (!await isEngineRunning()) {
+		if (savedState?.kind === "compose" && savedState.composePid && pidAlive(savedState.composePid)) try {
+			const failure = composeWorkerFailureSummary(ownedComposeProject(await composeCall({
+				engineUrl: savedState.engineUrl,
+				namespace: savedState.namespace,
+				functionId: "compose::status",
+				file: savedState.file
+			}), savedState.file));
+			if (failure) {
+				p.log.error(`Worker Compose failed after exhausting restart attempts; REST is unavailable at ${base}.`);
+				p.log.error(failure);
+				p.log.info(`Inspect ${savedState.logFile}, then run agentmemory stop before retrying.`);
+				process.exit(1);
+			}
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			p.log.warn(`Worker Compose status unavailable: ${message}`);
+		}
 		p.log.error(`Not running — no response at ${base}`);
 		p.log.info("Start with: npx @agentmemory/agentmemory");
 		process.exit(1);
@@ -2503,8 +3734,8 @@ async function runStatus() {
 		const version = healthRes?.version || "?";
 		const sessionList = Array.isArray(sessionsRes?.sessions) ? sessionsRes.sessions : [];
 		const sessions = sessionList.length;
-		const nodes = Number(graphRes?.totalNodes ?? graphRes?.nodes ?? graphRes?.nodeCount ?? 0);
-		const edges = Number(graphRes?.totalEdges ?? graphRes?.edges ?? graphRes?.edgeCount ?? 0);
+		const nodes = graphRes?.available === false ? "unknown" : graphRes?.totalNodes ?? graphRes?.nodes ?? graphRes?.nodeCount ?? "unknown";
+		const edges = graphRes?.available === false ? "unknown" : graphRes?.totalEdges ?? graphRes?.edges ?? graphRes?.edgeCount ?? "unknown";
 		const cb = healthRes?.circuitBreaker?.state || "closed";
 		const heapMB = h?.memory ? Math.round(h.memory.heapUsed / 1048576) : 0;
 		const uptime = h?.uptimeSeconds ? Math.round(h.uptimeSeconds) : 0;
@@ -2533,12 +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 embed = flagsRes.embeddingProvider === "embeddings" ? pc.green("✓ embeddings") : pc.dim("bm25-only");
+			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));
 		}
@@ -2549,6 +3783,21 @@ async function runStatus() {
 			lines.push("");
 			lines.push(`Followup rate: ${hits}/${total} (${pct}%) within ${followupRes.windowSeconds}s — directional, may overcount on refinement`);
 		}
+		const managed = savedState;
+		if (managed?.kind === "compose") try {
+			const composeProject = ownedComposeProject(await composeCall({
+				engineUrl: managed.engineUrl,
+				namespace: managed.namespace,
+				functionId: "compose::status",
+				file: managed.file
+			}), managed.file);
+			const containers = composeProject?.containers ?? [];
+			const failed = composeWorkerFailureSummary(composeProject ?? null);
+			if (failed) lines.push("", "Worker Compose failure (restart attempts exhausted):", ...failed.split("\n").map((line) => `  ${line}`));
+			lines.push("", "Compose workers:", ...containers.map((container) => `  ${container.container ?? "?"}: ${container.state ?? "unknown"}${container.last_error ? ` — ${container.last_error}` : ""}`));
+		} catch (error) {
+			lines.push("", `Compose status unavailable: ${error instanceof Error ? error.message : String(error)}`);
+		}
 		p.note(lines.join("\n"), "agentmemory");
 	} catch (err) {
 		p.log.error(err instanceof Error ? err.message : String(err));
@@ -2594,35 +3843,56 @@ function checkClaudeCodeHooks() {
 	if (content.includes("Loading hooks from plugin: agentmemory")) return { state: "loaded" };
 	return { state: "not-loaded" };
 }
+function doctorEnvPath() {
+	return process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env");
+}
 function buildDoctorContext() {
 	return {
 		baseUrl: getBaseUrl(),
 		viewerUrl: getViewerUrl(),
-		envPath: join(homedir(), ".agentmemory", ".env"),
-		pidfilePath: enginePidfilePath(),
+		envPath: doctorEnvPath(),
+		pidfilePath: readEngineState()?.kind === "compose" ? engineStatePath() : enginePidfilePath(),
 		enginePath: engineStatePath(),
 		pinnedVersion: IIPINNED_VERSION
 	};
 }
 function buildDoctorEffects() {
 	return {
-		envFileExists: () => existsSync(join(homedir(), ".agentmemory", ".env")),
+		envFileExists: () => existsSync(doctorEnvPath()),
 		readEnvFile: () => {
 			try {
-				return parseEnvFile(readFileSync(join(homedir(), ".agentmemory", ".env"), "utf-8"));
+				return parseEnvFile(readFileSync(doctorEnvPath(), "utf-8"));
 			} catch {
 				return {};
 			}
 		},
-		pidfileExists: () => existsSync(enginePidfilePath()),
+		processEnv: () => shellEnv,
+		pidfileExists: () => {
+			const state = readEngineState();
+			return state?.kind === "compose" ? Boolean(state.composePid) : existsSync(enginePidfilePath());
+		},
 		pidfilePidIsAlive: () => {
+			const state = readEngineState();
+			if (state?.kind === "compose") return state.composePid ? pidAlive(state.composePid) : null;
 			const pid = readEnginePidfile();
 			if (pid === null) return null;
 			return pidAlive(pid);
 		},
-		findIiiBinary: () => whichBinary("iii"),
-		localBinIiiPath: () => privateIiiPath(),
+		findIiiBinary: () => {
+			const state = readEngineState();
+			if (state?.kind === "compose") return existsSync(state.binPath) ? state.binPath : null;
+			return whichBinary("iii");
+		},
+		localBinIiiPath: () => {
+			const state = readEngineState();
+			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();
@@ -2678,6 +3948,14 @@ function buildDoctorEffects() {
 		},
 		runStop: async () => {
 			try {
+				startupTimeouts();
+				if (readEngineState()?.kind === "compose") {
+					await runStop();
+					return {
+						ok: true,
+						message: "Worker Compose project stopped."
+					};
+				}
 				const portPids = findEnginePidsByPort(getRestPort());
 				const pidfilePid = readEnginePidfile();
 				if (portPids.length === 0 && pidfilePid === null) {
@@ -2708,16 +3986,18 @@ function buildDoctorEffects() {
 		},
 		runStart: async () => {
 			try {
-				if (!await startEngine()) return {
-					ok: false,
-					message: "startEngine() returned false"
-				};
-				const ready = await waitForEngine(15e3);
+				startupTimeouts();
+				beginStartup();
+				if (!await startEngine()) throw new Error("iii-engine could not be started.");
+				if (!await waitForEngine()) throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));
+				await startWorkerForEngineState(true);
 				return {
-					ok: ready,
-					message: ready ? "Engine ready" : "Engine did not become ready within 15s"
+					ok: true,
+					message: "Engine and agentmemory worker ready"
 				};
 			} catch (err) {
+				await runStartupCleanup(1);
+				finishStartup();
 				return {
 					ok: false,
 					message: err instanceof Error ? err.message : String(err)
@@ -2746,8 +4026,9 @@ async function passiveServerChecks() {
 		apiFetch(base, "graph/stats", 3e3)
 	]);
 	const hasLlm = flags?.provider === "llm";
-	const hasEmbed = flags?.embeddingProvider === "embeddings";
-	const graphHas = Number(graph?.totalNodes ?? graph?.nodes ?? graph?.nodeCount ?? 0) > 0;
+	const hasEmbed = embeddingStatusLabel(flags?.embeddingProvider) !== null;
+	const graphNodeCount = graph?.available === false ? null : graph?.totalNodes ?? graph?.nodes ?? graph?.nodeCount ?? null;
+	const graphHas = typeof graphNodeCount === "number" && graphNodeCount > 0;
 	checks.push({
 		name: "Health status",
 		ok: health?.status === "healthy",
@@ -2755,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,
@@ -2791,7 +4072,7 @@ async function passiveServerChecks() {
 	checks.push({
 		name: "Knowledge graph populated",
 		ok: graphHas,
-		hint: graphHas ? void 0 : "Graph is empty. Run a session with GRAPH_EXTRACTION_ENABLED=true."
+		hint: graphHas ? void 0 : graphNodeCount === null ? "Graph counts are unavailable. Run agentmemory graph-index status." : "Graph is empty. Run a session with GRAPH_EXTRACTION_ENABLED=true."
 	});
 	return checks;
 }
@@ -2863,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++;
@@ -2875,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") {
@@ -3043,7 +4338,10 @@ async function seedDemoSession(base, project, session) {
 			p.log.warn(`observe request failed for ${obs.toolName}: ${err instanceof Error ? err.message : String(err)}`);
 		}
 	}
-	await postJsonStrict(`${base}/agentmemory/session/end`, { sessionId: session.id });
+	await postJsonStrict(`${base}/agentmemory/session/end`, {
+		sessionId: session.id,
+		final: true
+	});
 	return stored;
 }
 async function runDemoSearch(base, query) {
@@ -3095,49 +4393,33 @@ 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");
 	p.outro(`Edit ${target} and you're set.`);
 }
 async function startServerForDemo() {
+	startupTimeouts();
 	await assertRuntimePortOwnership();
 	if (await isAgentmemoryReady()) return async () => {};
-	const startedEngine = !await isEngineRunning();
+	beginStartup();
+	const startedEngine = !skipEngine && !(await isEngineRunning() || await waitForPersistedNativeEngine());
 	if (startedEngine) {
 		if (!await startEngine()) {
 			p.log.error("Could not start iii-engine for the demo.");
 			p.note(installInstructions().join("\n"), "Setup required");
-			process.exit(1);
+			throw new Error("iii-engine could not be started for the demo.");
 		}
-		if (!await waitForEngine(15e3)) {
+		if (!await waitForEngine()) {
 			printCapturedStartupStderr();
-			printDockerStartupLogs();
-			p.log.error("iii-engine did not become ready within 15s.");
-			process.exit(1);
+			throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));
 		}
 	}
 	await startWorkerForEngineState();
-	if (!await waitForAgentmemoryReady(15e3)) {
-		p.log.error("agentmemory worker did not become ready within 15s.");
-		process.exit(1);
-	}
 	return async () => {
-		if (!startedEngine) return;
-		const port = getRestPort();
-		const state = readEngineState();
-		if (state?.kind === "docker") {
-			await stopDockerEngine(state, port).catch(() => {});
-			return;
-		}
-		const pids = new Set(findEnginePidsByPort(port));
-		const pidfilePid = readEnginePidfile();
-		if (pidfilePid) pids.add(pidfilePid);
-		for (const pid of pids) await signalAndWait(pid, "SIGTERM", 3e3).catch(() => {});
-		clearEnginePidfile();
-		clearEngineState();
-		clearWorkerPidfile();
+		if (importedStartupWorker && readWorkerPidfile() === process.pid) clearWorkerPidfile();
+		if (startedEngine) await cleanupFailedStartup();
 	};
 }
 async function runDemo() {
@@ -3189,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())}`,
@@ -3204,7 +4486,11 @@ function runCommand(command, commandArgs, options = { label: "command" }) {
 	const result = spawnSync(command, commandArgs, {
 		cwd: options.cwd || process.cwd(),
 		stdio: "pipe",
-		encoding: "utf-8"
+		encoding: "utf-8",
+		...options.timeoutMs !== void 0 ? {
+			timeout: options.timeoutMs,
+			killSignal: "SIGKILL"
+		} : {}
 	});
 	if (result.status === 0) {
 		spinner.stop(`${options.label} ${pc.green("✓")}`);
@@ -3229,7 +4515,6 @@ async function runUpgrade() {
 	const hasPnpmLock = existsSync(join(cwd, "pnpm-lock.yaml"));
 	const pnpmBin = whichBinary("pnpm");
 	const npmBin = whichBinary("npm");
-	const dockerBin = whichBinary("docker");
 	p.log.info(`Working directory: ${cwd}`);
 	const requireSuccess = (ok, label) => {
 		if (!ok) {
@@ -3269,11 +4554,6 @@ async function runUpgrade() {
 	}
 	if (upgradeEngine === true) await runIiiInstaller();
 	else p.log.info("Skipped iii-engine installer.");
-	if (dockerBin) runCommand(dockerBin, ["pull", `iiidev/iii:${IIPINNED_VERSION}`], {
-		label: `Pulling iii Docker image v${IIPINNED_VERSION} (pinned)`,
-		optional: true
-	});
-	else p.log.info("Docker not found. Skipping Docker image refresh.");
 	p.note([
 		"Upgrade flow completed.",
 		"",
@@ -3341,9 +4621,14 @@ async function waitForEngineFlush() {
 	try {
 		stateBackend = getStateBackend();
 	} catch {}
+	if (readEngineState()?.kind === "compose") {
+		const isolatedRuntime = dataDirResolution.dataDir !== join(homedir(), ".agentmemory");
+		await new Promise((resolve) => setTimeout(resolve, getStateBackend() === "redis" || isolatedRuntime ? 0 : 3500));
+		return;
+	}
 	const runtimePath = runtimeConfigPath(dataDirResolution.dataDir);
 	const configTexts = [];
-	for (const path of engineStateConfigPaths(join(homedir(), ".agentmemory"), runtimePath)) try {
+	for (const path of engineStateConfigPaths(dataDirResolution.dataDir, runtimePath)) try {
 		configTexts.push(readFileSync(path, "utf-8"));
 	} catch {}
 	const waitMs = engineFlushWaitMs(stateBackend, configTexts);
@@ -3449,80 +4734,64 @@ function findEnginePidsByPort(port) {
 		return [];
 	}
 }
-async function stopDockerEngine(state, port, suppressOutro = false) {
-	const dockerBin = whichBinary("docker");
-	if (!dockerBin) {
-		p.log.error("Engine was started via Docker, but `docker` is no longer on PATH. Lifecycle state was preserved.");
-		process.exit(1);
-	}
-	const inspection = inspectOwnedDockerEngine(state);
-	if (inspection.status === "unavailable") {
-		p.log.error(`The saved Docker engine cannot be verified: ${inspection.reason}. Refusing to stop or clear ownership state.`);
-		process.exit(1);
-	}
-	const resolvedState = persistDockerInspection(state, inspection);
-	const workerPid = readWorkerPidfile();
-	if (workerPid && !await stopWorkerPid(workerPid, 5e3)) {
-		p.log.error("The agentmemory worker could not be stopped; Docker ownership state was preserved.");
-		process.exit(1);
-	}
-	clearWorkerPidfile();
-	if (inspection.status === "running" || inspection.status === "stopped") {
-		if (inspection.status === "running" && !runCommand(dockerBin, [
-			"stop",
-			"--time",
-			"10",
-			inspection.containerId
-		], { label: `Stopping preserved Docker container ${inspection.containerId}` })) {
-			p.log.error("The Docker container could not be stopped; ownership state was preserved.");
-			process.exit(1);
-		}
-		clearEnginePidfile();
-		writeEngineState(resolvedState);
-		if (!suppressOutro) p.outro("Stopped. The validated Docker container and data mount were preserved for a lossless restart.");
-		return;
-	}
-	const projectName = inspection.projectName ?? resolvedState.projectName;
-	if (!projectName) {
-		p.log.error("No verified Docker Compose project name is available. Refusing an unscoped stop.");
-		process.exit(1);
-	}
-	const effectiveComposeFile = existsSync(inspection.composeFile) ? inspection.composeFile : discoverComposeFile();
-	if (!effectiveComposeFile) {
-		p.log.error("No agentmemory compose file is available. Docker ownership state was preserved.");
-		process.exit(1);
-	}
-	const composeText = readFileSync(effectiveComposeFile, "utf-8");
-	const ownServices = ["iii-engine", "iii-init"].filter((service) => new RegExp(`^\\s+${service}:`, "m").test(composeText));
-	if (ownServices.length === 0) {
-		p.log.error(`${effectiveComposeFile} does not define iii-engine or iii-init. Refusing an unscoped stop.`);
+async function runStop() {
+	const savedState = readEngineState();
+	if (savedState?.kind === "docker") {
+		p.intro("agentmemory stop");
+		p.log.error(legacyDockerStateMessage(savedState));
 		process.exit(1);
 	}
-	const composeCommand = ["docker", ...dockerComposeArgs(effectiveComposeFile, projectName, [])].join(" ");
-	if (runCommand(dockerBin, dockerComposeArgs(effectiveComposeFile, projectName, [
-		"rm",
-		"-s",
-		"-f",
-		...ownServices
-	]), { label: `${composeCommand} rm -s -f ${ownServices.join(" ")}` })) {
-		clearEnginePidfile();
-		clearEngineState();
-	} else {
-		p.log.error(`docker compose rm failed. The engine may still be running on :${port}. Inspect with:\n  ${composeCommand} ps`);
+	if (savedState?.kind === "compose" && engineStateRestPort(savedState) !== getRestPort()) {
+		p.intro("agentmemory stop");
+		p.log.error(`Saved Compose lifecycle state belongs to REST port ${engineStateRestPort(savedState)}, not requested port ${getRestPort()}. Refusing to signal processes or clear metadata.`);
 		process.exit(1);
 	}
-	if (!suppressOutro) p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
-}
-async function runStop() {
 	await assertRuntimePortOwnership();
 	p.intro("agentmemory stop");
 	const port = getRestPort();
 	const state = readEngineState();
 	const running = await isEngineRunning();
 	const force = args.includes("--force");
-	if (state?.kind === "docker") {
-		if (!running) p.log.info(`No engine responding on port ${port}.`);
-		await stopDockerEngine(state, port);
+	if (state?.kind === "compose") {
+		const ownedDaemonAlive = Boolean(state.composePid && pidAlive(state.composePid));
+		if (ownedDaemonAlive && !composePidMatches(state.composePid, state)) {
+			p.log.error(`Recorded Compose pid ${state.composePid} does not match the saved daemon identity; refusing to invoke Compose control or signal it. Lifecycle state was preserved.`);
+			process.exit(1);
+		}
+		if (running && !ownedDaemonAlive) {
+			p.log.error("The REST endpoint is responding, but the recorded Compose daemon is not alive. Refusing to stop or clear an engine that may be unrelated; restore the owning daemon or inspect the endpoint manually.");
+			process.exit(1);
+		}
+		if (running && ownedDaemonAlive) try {
+			await composeCall({
+				engineUrl: state.engineUrl,
+				namespace: state.namespace,
+				functionId: "compose::down",
+				file: state.file,
+				timeoutMs: composeDownTimeoutMs()
+			});
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			if (!message.includes("ENGINE_RESTART_REQUIRED")) {
+				p.log.error(`compose::down failed for ${state.file}: ${message}. Lifecycle state was preserved.`);
+				process.exit(1);
+			}
+			p.log.warn("Compose requested an engine restart while stopping; terminating its verified owning daemon to finish shutdown.");
+		}
+		if (ownedDaemonAlive) {
+			if (!await terminateComposeChildren(state)) {
+				p.log.error(`One or more child workers of Compose ${state.composePid} did not stop; lifecycle state was preserved.`);
+				process.exit(1);
+			}
+			if (!await signalAndWait(state.composePid, "SIGTERM", 2e4)) {
+				p.log.error(`Worker Compose daemon pid ${state.composePid} did not stop; lifecycle state was preserved. Inspect ${state.logFile}.`);
+				process.exit(1);
+			}
+		}
+		clearEnginePidfile();
+		clearWorkerPidfile();
+		clearEngineState();
+		p.outro("Stopped Worker Compose, engine, and agentmemory workers. Data was preserved.");
 		return;
 	}
 	const portPids = findEnginePidsByPort(port);
@@ -3558,14 +4827,6 @@ async function runStop() {
 		p.log.info(`Preserving ~/.agentmemory/iii.pid + worker.pid. Investigate before manual cleanup:\n  ps -p ${[...survivors].join(",")} -o pid,ppid,comm,etime\n  ${IS_WINDOWS ? "netstat -ano | findstr :" + port : "lsof -i :" + port}`);
 		process.exit(1);
 	}
-	if (!state) {
-		const compose = discoverComposeFile();
-		if (compose && pidfilePid === null) if (force) p.log.warn(`--force: bypassing Docker-heuristic guard. Falling back to native pidfile + lsof on :${port}.`);
-		else {
-			p.log.error(`Engine is running on :${port} but no pidfile or state file is present. It may have been started via Docker compose by a different shell. Refusing to signal host PIDs.\n\nStop it with:\n  docker compose -f ${compose} down\n\nOr re-run with --force to signal whatever lsof finds on :${port}, or AGENTMEMORY_USE_DOCKER=1 to record state next time.`);
-			process.exit(1);
-		}
-	}
 	const candidates = /* @__PURE__ */ new Set();
 	if (pidfilePid) candidates.add(pidfilePid);
 	for (const pid of portPids) candidates.add(pid);
@@ -3600,7 +4861,7 @@ async function runStop() {
 	clearWorkerPidfile();
 	if (skippedForeign.length > 0) {
 		const list = skippedForeign.map((sf) => `  pid ${sf.pid}  ${sf.comm}`).join("\n");
-		p.log.error(`Refused to signal process(es) holding :${port} that are not the iii engine:\n${list}\n\nIf the engine runs in Docker, stop it there:\n  docker compose ps && docker compose rm -s -f <service>\n\nOr re-run with --force to signal them anyway.`);
+		p.log.error(`Refused to signal process(es) holding :${port} that are not the iii engine:\n${list}\n\nInspect those processes and stop the engine with its owning runtime.\nOr re-run with --force to signal them anyway.`);
 		process.exit(1);
 	}
 	if (!allStopped) {
@@ -3610,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-DKCdrf1d.mjs");
+	await import("./standalone-BYo5USDb.mjs");
 }
 async function runConnectCmd() {
-	const { runConnect } = await import("./connect-B4_ca6BD.mjs").then((n) => n.n);
+	const { runConnect } = await import("./connect-BX3njQ3Y.mjs").then((n) => n.n);
 	await runConnect(args.slice(1));
 }
 async function runImportJsonl() {
@@ -3772,27 +5033,20 @@ async function runRemove() {
 	const force = args.includes("--force");
 	const keepData = args.includes("--keep-data");
 	const ownedState = readEngineState();
+	if (ownedState?.kind === "compose") {
+		p.log.error("Stop the Worker Compose project with `agentmemory stop` before removing agentmemory; its data and daemon ownership are preserved.");
+		process.exit(1);
+	}
 	if (ownedState?.kind === "docker") {
-		const inspection = inspectOwnedDockerEngine(ownedState);
-		if (inspection.status === "running" || inspection.status === "stopped") {
-			persistDockerInspection(ownedState, inspection);
-			if (!keepData) {
-				p.log.error(`Docker-backed removal requires --keep-data so the validated ${inspection.dataMountType} data mount (${inspection.dataMountSource}) and its recovery metadata remain usable. Re-run \`agentmemory remove --keep-data\`; destructive Docker data deletion is intentionally not automated.`);
-				process.exit(1);
-			}
-		} else {
-			const detail = inspection.status === "unavailable" ? inspection.reason : "the owned container is missing";
-			p.log.error(`remove cannot safely reconcile the saved Docker ownership (${detail}). Lifecycle state was preserved for manual recovery.`);
-			process.exit(1);
-		}
+		p.log.error(legacyDockerStateMessage(ownedState));
+		process.exit(1);
 	}
 	const home = homedir();
 	const connectManifest = loadConnectManifest(home);
 	const localBinIiiVersion = probeLocalBinIiiVersion(home);
 	const options = {
 		force,
-		keepData,
-		preserveRuntimeState: ownedState?.kind === "docker"
+		keepData
 	};
 	const plan = buildRemovePlan({
 		home,
@@ -3838,11 +5092,6 @@ async function runRemove() {
 			}
 		}
 		if (item.id === "stop-engine") {
-			if (ownedState?.kind === "docker") {
-				await stopDockerEngine(ownedState, getRestPort(), true);
-				p.log.success("stopped Docker engine; container, data mount, and recovery state preserved");
-				continue;
-			}
 			const stopped = await stopNativeEngineForRemoval();
 			if (!stopped.ok) {
 				p.log.error(`Removal aborted: ${stopped.reason}.`);
@@ -3859,52 +5108,13 @@ async function runRemove() {
 	p.outro("Done. agentmemory cleanly removed. The npm package itself: npm uninstall -g @agentmemory/agentmemory");
 }
 async function runConsole() {
-	const iiiBin = pickCompatibleIii([whichBinary("iii"), ...fallbackIiiPaths().filter((candidate) => existsSync(candidate))]);
-	if (!iiiBin) {
-		p.log.error(`No iii v${IIPINNED_VERSION} found. Start agentmemory once so it installs the pinned engine into ${privateIiiPath()}, then run this again.`);
-		process.exit(1);
-	}
-	let parsed;
-	try {
-		parsed = parseConsoleArgs(args.slice(1), defaultConsolePort(getConfiguredViewerPort()));
-	} catch (err) {
-		p.log.error(err instanceof Error ? err.message : String(err));
-		process.exit(1);
-	}
-	const launch = {
-		iiiBin,
-		consolePort: parsed.consolePort,
-		restPort: getRestPort(),
-		streamPort: getStreamPort(),
-		enginePort: getEnginePort(),
-		extraArgs: parsed.extraArgs
-	};
-	if (!await isEngineRunning()) p.log.warn(`No engine responding on port ${launch.restPort}. The console starts anyway and connects once agentmemory is up.`);
-	p.log.info(`iii console: http://127.0.0.1:${launch.consolePort} (engine REST ${launch.restPort}, streams ${launch.streamPort}, bridge ${launch.enginePort}). The first run downloads the console binary next to the pinned iii.`);
-	const child = spawn(iiiBin, consoleArgs(launch), {
-		stdio: "inherit",
-		detached: true
-	});
-	const forward = (signal) => {
-		try {
-			process.kill(-child.pid, signal);
-		} catch {
-			child.kill(signal);
-		}
-	};
-	for (const signal of [
-		"SIGINT",
-		"SIGTERM",
-		"SIGHUP"
-	]) process.on(signal, () => forward(signal));
-	const code = await new Promise((resolve) => {
-		child.on("exit", (status, signal) => resolve(status ?? (signal ? 1 : 0)));
-		child.on("error", (err) => {
-			p.log.error(err.message);
-			resolve(1);
-		});
-	});
-	process.exit(code);
+	await discoverViewerPort();
+	p.log.warn("iii 0.25 retired the bundled engine console; --console-port and console launch flags no longer apply.");
+	p.note([
+		`AgentMemory viewer: ${getViewerUrl()} (start agentmemory first if it is offline).`,
+		"Use agentmemory status for runtime health and worker status.",
+		"Engine console migration: https://github.com/iii-hq/iii/blob/iii/v0.25.0/docs/using-iii/console.mdx"
+	].join("\n"), "Console migration");
 }
 async function runCapture() {
 	const code = await runCaptureCommand({
@@ -3914,6 +5124,23 @@ async function runCapture() {
 	});
 	process.exit(code);
 }
+async function runCompression() {
+	const base = getBaseUrl();
+	const code = await runCompressionCommand({
+		base,
+		args: args.slice(1),
+		secret: resolveClientSecret(base)
+	});
+	process.exit(code);
+}
+async function runGraphIndex() {
+	const base = getBaseUrl();
+	process.exit(await runGraphIndexCommand({
+		base,
+		args: args.slice(1),
+		secret: resolveClientSecret(base)
+	}));
+}
 const commands = {
 	init: runInit,
 	connect: runConnectCmd,
@@ -3926,16 +5153,19 @@ const commands = {
 	remove: runRemove,
 	mcp: runMcp,
 	"import-jsonl": runImportJsonl,
-	capture: runCapture
+	capture: runCapture,
+	compression: runCompression,
+	"graph-index": runGraphIndex
 };
 const first = args[0] ?? "";
 async function unknownCommand() {
 	p.log.error(`Unknown command: ${first}. Supported: ${Object.keys(commands).join(", ")}. Run \`agentmemory\` with no arguments to start the memory server, or \`agentmemory --help\` for usage.`);
 	process.exit(1);
 }
-(commands[first] ?? (first && !first.startsWith("-") ? unknownCommand : main))().catch((err) => {
+(commands[first] ?? (first && !first.startsWith("-") ? unknownCommand : main))().catch(async (err) => {
 	p.log.error(err instanceof Error ? err.message : String(err));
-	process.exit(1);
+	const exitCode = await runStartupCleanup(1).catch(() => 1);
+	process.exit(exitCode);
 });
 //#endregion
 export { discoverViewerPort };