@agentmemory/agentmemory 0.9.30 → 0.9.31

package/dist/cli.mjs

@@ -1,17 +1,20 @@
 #!/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-BSLIAMpw.mjs";
+import { s as generateId } from "./keyed-mutex-DCUh7PG-.mjs";
+import { A as engineFlushWaitMs, C as III_PINNED_VERSION, L as detectLlmProviderKind, M as redactCredentialUrls, N as runtimeConfigPath, O as setBootVerbose, X as getStateBackend, Z as getStateSaveIntervalMs, b as ESSENTIAL_TOOLS, et as hydrateProcessEnvFromFile, gt as parseEnvContent, i as resolveClientSecret, j as engineStateConfigPaths, q as getRedisUrl, t as bearerHeaders, w as VERSION, x as getAllTools } from "./secret-store-D9GwO0xp.mjs";
+import { $t as resolveDataDir, Gt as retainSent, Ht as drainSpool, Jt as spoolSummary, Ut as parseSentMark, an as runtimeMetadataPath, nn as registerStartupCleanup, nt as CURL_AUTH_HEADER, rn as runStartupCleanup, t as parseCompressionScope, tn as SHUTDOWN_HARD_EXIT_MS } from "./compression-recovery-CnhLQC6N.mjs";
 import { 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 { delimiter, dirname, isAbsolute, join, resolve } 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 { 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
 /** Common placeholder values shipped in .env.example. */
 const PLACEHOLDER_VALUES = new Set([
@@ -31,20 +34,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 +61,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,18 +70,32 @@ function buildDiagnostics(effects) {
 		},
 		{
 			id: "no-llm-provider-key",
-			message: "No LLM provider API key found in ~/.agentmemory/.env.",
+			message: "No LLM provider API key found in ~/.agentmemory/.env or the environment.",
 			fixPreview: "Open ~/.agentmemory/.env in $EDITOR and paste your key, then re-check.",
-			moreInfo: "Set at least one of: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, MINIMAX_API_KEY. The daemon picks the first that resolves to a real (non-placeholder) value at startup.",
+			moreInfo: "Set at least one of: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY, MINIMAX_API_KEY. Placeholder values count as missing. OPENAI_API_KEY counts only while OPENAI_API_KEY_FOR_LLM is not false, and AGENTMEMORY_ALLOW_AGENT_SDK=true needs no key. A value exported in the environment wins over the file, but only for a daemon started from that environment, and counts even when the file is absent.",
 			check: async () => {
-				if (!effects.envFileExists()) return {
+				const file = effects.readEnvFile();
+				const env = { ...file };
+				for (const [k, v] of Object.entries(effects.processEnv())) if (v !== void 0) env[k] = v;
+				for (const k of placeholderProviderKeys(env)) delete env[k];
+				if (detectLlmProviderKind(env) !== "llm") return {
 					ok: false,
-					detail: "env file missing (run env-missing fix first)"
+					detail: effects.envFileExists() ? "no provider key set" : "no provider key set (run env-missing fix first)"
+				};
+				const real = realProviderKeys(env).filter((k) => detectLlmProviderKind({
+					[k]: env[k],
+					OPENAI_API_KEY_FOR_LLM: env.OPENAI_API_KEY_FOR_LLM
+				}) === "llm");
+				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)
@@ -99,8 +103,8 @@ function buildDiagnostics(effects) {
 		{
 			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.",
+			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.",
 			check: async (ctx) => {
 				const bin = effects.findIiiBinary();
 				if (!bin) return {
@@ -142,8 +146,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,
@@ -400,15 +404,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;
@@ -518,66 +529,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 +677,64 @@ 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 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) {
@@ -1052,6 +1202,732 @@ async function runCaptureCommand(options) {
 	return 0;
 }
 //#endregion
+//#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;
+	}
+}
+//#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"
+};
+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",
+	"OPENAI_API_KEY",
+	"OPENAI_API_KEY_FOR_LLM",
+	"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, windows) {
+	if (/[\u0000-\u001f\u007f]/.test(value)) throw new Error("A shell command argument contains an unsupported control character.");
+	if (windows) {
+		if (value.includes("\"")) throw new Error("Windows shell arguments cannot contain a double quote.");
+		return `"${value.replace(/%/g, "%%")}"`;
+	}
+	return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function shellCommand(program, args, windows) {
+	const command = [program, ...args].map((part) => shellQuote$1(part, windows)).join(" ");
+	return windows ? `"${command}"` : command;
+}
+function 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 workerBinDir = options.workerBinDir ? options.workerBinDirIsAbsolute ? resolve(options.workerBinDir) : localWorkerDirectory(options.workerBinDir, options.cwd ?? process.cwd(), options.projectRoot) : null;
+	const startupSeconds = Math.ceil((options.startupTimeoutMs ?? 3e5) / 1e3);
+	const restartEnabled = !options.disableRestartPolicy;
+	if (!Number.isSafeInteger(startupSeconds) || startupSeconds < 1 || startupSeconds * 1e3 > 3600999) throw new Error("Compose worker startup timeout must be between 1 and 3600000 milliseconds.");
+	const workerSource = (name) => workerBinDir ? `path://${localWorkerProjectDir(paths, name)}` : `package://api.workers.iii.dev/${name}`;
+	const workerScript = (name) => workerBinDir ? join(workerBinDir, name) : "";
+	const 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(shellCommand(stateScript, [], options.windows ?? process.platform === "win32"))}`] : [], "    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(shellCommand(httpScript, [], options.windows ?? process.platform === "win32"))}`] : [], "    config_override:", "      host: 127.0.0.1", `      port: ${restPort}`, "      default_timeout: 180000", "      cors:", "        allowed_origins:", `          - ${yamlString(`http://localhost:${restPort}`)}`, `          - ${yamlString(`http://localhost:${viewerPort}`)}`, `          - ${yamlString(`http://127.0.0.1:${restPort}`)}`, `          - ${yamlString(`http://127.0.0.1:${viewerPort}`)}`, "        allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]");
+	lines.push("  agentmemory:", `    worker: ${yamlString(`path://${options.projectRoot}`)}`, "    start_after: [state, http]", `    startup_timeout: ${startupSeconds}s`, "    config_name: agentmemory", ...restartPolicyLines("    ", restartEnabled), "    scripts:", `      run: ${yamlString(shellCommand(options.nodeBin, ["dist/index.mjs"], options.windows ?? process.platform === "win32"))}`);
+	if (filteredEnvFile) lines.push(`    env_file: [${yamlString(filteredEnvFile)}]`);
+	const explicitWorkerEnvironment = Object.entries(options.workerEnvironment ?? {}).filter(([key, value]) => value !== void 0 && AGENTMEMORY_WORKER_ENV_ALLOWLIST.has(key) && !COMPOSE_RESERVED_ENV.has(key)).sort(([left], [right]) => left.localeCompare(right));
+	lines.push("    environment:", ...explicitWorkerEnvironment.map(([key, value]) => `      ${key}: ${yamlString(value)}`), `      HOME: ${yamlString(options.homeDir)}`, `      PATH: ${yamlString(`${dirname(options.nodeBin)}:/usr/local/bin:/usr/bin:/bin`)}`, `      AGENTMEMORY_DATA_DIR: ${yamlString(options.dataDir)}`, `      AGENTMEMORY_RUNTIME_DIR: ${yamlString(options.dataDir)}`, ...filteredEnvFile ? [`      AGENTMEMORY_ENV_FILE: ${yamlString(filteredEnvFile)}`] : [], ...options.stateBackend?.kind === "redis" && options.redisUrl ? [`      AGENTMEMORY_REDIS_URL: ${yamlString(options.redisUrl)}`, "      AGENTMEMORY_STATE_BACKEND: 'redis'"] : [], `      III_ENGINE_PORT: ${yamlString(String(enginePort))}`, `      III_REST_PORT: ${yamlString(String(restPort))}`, `      III_VIEWER_PORT: ${yamlString(String(viewerPort))}`, "      III_TELEMETRY_ENABLED: 'false'", ...options.linux ?? process.platform === "linux" ? ["      MALLOC_ARENA_MAX: '2'"] : [], "");
+	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 (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 ownedComposeProject(status, file) {
+	return status.file === file ? status : status.projects?.find((item) => item.file === file) ?? 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" } : {}
+	};
+}
+async function composeCall(options) {
+	const client = registerWorker(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,
@@ -1071,7 +1947,7 @@ 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();
+const shellEnv = hydrateProcessEnvFromFile();
 if (args.includes("--version") || args.includes("-V")) {
 	process.stdout.write(`${VERSION}\n`);
 	process.exit(0);
@@ -1119,15 +1995,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 +2013,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 +2037,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 +2082,9 @@ const URL_CLIENT_COMMANDS = new Set([
 	"status",
 	"doctor",
 	"mcp",
-	"capture"
+	"capture",
+	"compression",
+	"graph-index"
 ]);
 let hasExplicitLocalPortOverride = false;
 let selectedInstance = 0;
@@ -1232,7 +2117,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 +2177,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 +2188,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;
@@ -1431,15 +2288,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 +2319,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 +2336,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-DaMtDzt_.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 +2483,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 +2514,25 @@ 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.31`
+	], { label: `Installing @agentmemory/agentmemory@0.9.31 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}`);
+		p.log.info(`Auto-install unavailable on ${platform()} — ${asset} isn't tar-compatible. Install manually:\n  1. Download ${releaseUrl}\n     Its SHA-256 must be ${expectedIiiSha256(IIPINNED_VERSION, asset ?? "") ?? `the value in ${releaseUrl.replace(/\.zip$/, ".sha256")}`}\n  2. Extract iii.exe and place it on PATH (e.g. %USERPROFILE%\\.local\\bin)\nInstall the pinned iii binary from ${releaseUrl}`);
 		return {
 			ok: false,
 			binPath: null
@@ -1905,7 +2571,7 @@ 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
@@ -1919,159 +2585,305 @@ 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();
-			}
+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 composePidMatches(pid, state) {
+	try {
+		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");
 		}
-	});
-	child.unref();
-	return child;
+		if (!(command.includes("compose") && command.includes("compose --namespace") && command.includes(state.namespace) && command.includes(state.file))) return false;
+		if (!executable) return false;
+		return sameResolvedExecutable(executable, state.binPath, IS_WINDOWS);
+	} catch {
+		return false;
+	}
 }
-function prepareEngineLaunch(configPath) {
-	const home = homedir();
-	const bundledConfig = isBundledConfig(configPath, __dirname);
-	const cwd = resolveEngineCwd(configPath, process.cwd(), home, bundledConfig);
-	const stateBackendKind = getStateBackend();
+function composeChildProcesses(state) {
+	if (IS_WINDOWS || !state.composePid) return [];
 	try {
-		mkdirSync(cwd, { recursive: true });
-	} catch (err) {
-		const failure = resolveLaunchRenderFailure(stateBackendKind, err);
-		if (failure.fatal) {
-			p.log.error(failure.message);
-			process.exit(1);
+		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 {
-			configPath,
-			cwd: process.cwd()
-		};
+		return rows.filter((row) => row.pid !== state.composePid && descendants.has(row.pid)).map(({ pid, pgid, args }) => ({
+			pid,
+			pgid,
+			args
+		}));
+	} catch {
+		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");
+}
+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 +2894,9 @@ 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() {
+	startupFailure = null;
+	engineReadinessDeadline = null;
 	let stateBackendKind;
 	try {
 		stateBackendKind = getStateBackend();
@@ -2098,55 +2908,43 @@ 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"}`);
 	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).`);
@@ -2160,11 +2958,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 +2982,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() {
@@ -2288,9 +3023,6 @@ function installInstructions() {
 			"     3. Extract iii.exe to %USERPROFILE%\\.local\\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 +3035,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 +3043,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)) {
+			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 +3164,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 +3208,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 +3225,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 +3258,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 +3300,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;
@@ -2534,7 +3331,8 @@ async function runStatus() {
 		}
 		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 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}`);
@@ -2549,6 +3347,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,34 +3407,50 @@ 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),
 		viewerReachable: async (timeoutMs = 2e3) => {
 			try {
@@ -2678,6 +3507,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 +3545,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 +3585,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",
@@ -2791,7 +3631,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;
 }
@@ -3043,7 +3883,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) {
@@ -3102,42 +3945,26 @@ async function runInit() {
 	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() {
@@ -3204,7 +4031,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 +4060,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 +4099,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 +4166,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 +4279,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: 6e4
+			});
+		} 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 +4372,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 +4406,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 +4416,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-BlqshyZ5.mjs");
 }
 async function runConnectCmd() {
-	const { runConnect } = await import("./connect-B4_ca6BD.mjs").then((n) => n.n);
+	const { runConnect } = await import("./connect-BSLIAMpw.mjs").then((n) => n.n);
 	await runConnect(args.slice(1));
 }
 async function runImportJsonl() {
@@ -3772,27 +4578,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 +4637,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 +4653,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 +4669,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 +4698,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 };