@agentmemory/agentmemory 0.9.29 → 0.9.31

package/dist/cli.mjs

@@ -1,16 +1,20 @@
 #!/usr/bin/env node
-import { a as runAdapter, i as resolveAdapter, r as knownAgents, t as ADAPTERS } from "./connect-Qaeq15TQ.mjs";
-import { i as generateId } from "./schema-BFZhNTF7.mjs";
-import { r as setBootVerbose } from "./logger-BEB7pCI9.mjs";
-import { i as VERSION, n as getAllTools, p as hydrateProcessEnvFromFile, t as ESSENTIAL_TOOLS } from "./tools-registry-BV_2bu7z.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, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
-import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } 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([
@@ -30,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) => {
@@ -70,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"
@@ -79,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)
@@ -98,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 {
@@ -141,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,
@@ -225,11 +230,14 @@ function dryRunPlan(ctx, results) {
 }
 //#endregion
 //#region src/cli/remove-plan.ts
-function pidfilePath(home) {
-	return join(home, ".agentmemory", "iii.pid");
+function pidfilePath(runtimeDir) {
+	return join(runtimeDir, "iii.pid");
+}
+function workerPidfilePath$1(runtimeDir) {
+	return join(runtimeDir, "worker.pid");
 }
-function enginePath(home) {
-	return join(home, ".agentmemory", "engine-state.json");
+function enginePath(runtimeDir) {
+	return join(runtimeDir, "engine-state.json");
 }
 function envPath(home) {
 	return join(home, ".agentmemory", ".env");
@@ -240,9 +248,6 @@ function preferencesPath(home) {
 function backupsDir(home) {
 	return join(home, ".agentmemory", "backups");
 }
-function dataDir(home) {
-	return join(home, ".agentmemory", "data");
-}
 function iiiBinFile() {
 	return process.platform === "win32" ? "iii.exe" : "iii";
 }
@@ -274,31 +279,39 @@ function pathExists(path) {
 * the structure stable for tests.
 */
 function buildRemovePlan(ctx, options) {
-	const { home, pinnedVersion, localBinIiiVersion, connectManifest } = ctx;
+	const { home, runtimeDir, dataDir, pinnedVersion, localBinIiiVersion, connectManifest } = ctx;
 	const plan = [];
 	plan.push({
 		id: "stop-engine",
 		description: "Stop running iii-engine (if any) cleanly",
 		path: null,
 		alwaysAsk: false,
-		applicable: pathExists(pidfilePath(home)) || pathExists(enginePath(home)),
+		applicable: pathExists(pidfilePath(runtimeDir)) || pathExists(workerPidfilePath$1(runtimeDir)) || pathExists(enginePath(runtimeDir)),
 		sizeBytes: -1
 	});
 	plan.push({
 		id: "pidfile",
 		description: "Delete pidfile",
-		path: pidfilePath(home),
+		path: pidfilePath(runtimeDir),
 		alwaysAsk: false,
-		applicable: pathExists(pidfilePath(home)),
-		sizeBytes: safeSize(pidfilePath(home))
+		applicable: pathExists(pidfilePath(runtimeDir)),
+		sizeBytes: safeSize(pidfilePath(runtimeDir))
+	});
+	plan.push({
+		id: "worker-pidfile",
+		description: "Delete worker pidfile",
+		path: workerPidfilePath$1(runtimeDir),
+		alwaysAsk: false,
+		applicable: pathExists(workerPidfilePath$1(runtimeDir)),
+		sizeBytes: safeSize(workerPidfilePath$1(runtimeDir))
 	});
 	plan.push({
 		id: "engine-state",
 		description: "Delete engine-state.json",
-		path: enginePath(home),
+		path: enginePath(runtimeDir),
 		alwaysAsk: false,
-		applicable: pathExists(enginePath(home)),
-		sizeBytes: safeSize(enginePath(home))
+		applicable: !options.preserveRuntimeState && pathExists(enginePath(runtimeDir)),
+		sizeBytes: safeSize(enginePath(runtimeDir))
 	});
 	plan.push({
 		id: "env",
@@ -324,6 +337,14 @@ function buildRemovePlan(ctx, options) {
 		applicable: !options.keepData && pathExists(backupsDir(home)),
 		sizeBytes: -1
 	});
+	plan.push({
+		id: "runtime-config",
+		description: "Delete generated iii-config.runtime.yaml",
+		path: runtimeConfigPath(dataDir),
+		alwaysAsk: false,
+		applicable: pathExists(runtimeConfigPath(dataDir)),
+		sizeBytes: safeSize(runtimeConfigPath(dataDir))
+	});
 	if (connectManifest?.installed?.length) for (const entry of connectManifest.installed) plan.push({
 		id: `connect:${entry.target}`,
 		description: `Remove agent connection (${entry.agent ?? "unknown"})`,
@@ -355,10 +376,10 @@ function buildRemovePlan(ctx, options) {
 	}
 	plan.push({
 		id: "data-dir",
-		description: "Delete memory data directory (~/.agentmemory/data/) — will ask separately",
-		path: dataDir(home),
+		description: `Delete memory data directory (${dataDir}) — will ask separately`,
+		path: dataDir,
 		alwaysAsk: true,
-		applicable: !options.keepData && pathExists(dataDir(home)),
+		applicable: !options.keepData && pathExists(dataDir),
 		sizeBytes: -1
 	});
 	return plan;
@@ -377,6 +398,343 @@ function humanBytes(n) {
 	return `${(n / (1024 * 1024)).toFixed(1)} MB`;
 }
 //#endregion
+//#region src/cli/ready-hint.ts
+const DEFAULT_REST_PORT = 3111;
+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.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;
+}
+function sha256File(path) {
+	return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+function curlTimeoutFlags() {
+	return `--connect-timeout 15 --max-time 300`;
+}
+function iiiArchivePath(binDir) {
+	return join(binDir, ".iii-download.tar.gz");
+}
+function iiiDownloadShellCommand() {
+	return `mkdir -p "$2" && rm -f "$3" && if curl -fsSL ${curlTimeoutFlags()} -o "$3" "$1"; then :; else code=$?; rm -f "$3"; exit $code; fi`;
+}
+function iiiExtractShellCommand() {
+	return "if tar -xzf \"$1\" -C \"$2\"; then rm -f \"$1\"; else code=$?; rm -f \"$1\"; exit $code; fi && chmod +x \"$3\"";
+}
+function iiiManualInstallCommand(releaseUrl, binDir, binPath, sha256) {
+	return `mkdir -p "${binDir}" && archive="$(mktemp "${binDir}/.iii-download.XXXXXX")" && { curl -fL --connect-timeout 15 -o "$archive" "${releaseUrl}"${sha256 ? ` && printf '%s  %s\\n' "${sha256}" "$archive" | { sha256sum -c - 2>/dev/null || shasum -a 256 -c -; }` : ""} && tar -xzf "$archive" -C "${binDir}"; code=$?; rm -f "$archive"; (exit $code); } && chmod +x "${binPath}"`;
+}
+function describeInstallFailure(result) {
+	if (result.error?.code === "ETIMEDOUT") return `timed out after ${Math.round(III_INSTALL_SPAWN_TIMEOUT_MS / 1e3)} s`;
+	const output = (result.stderr || result.stdout || "").toString().trim();
+	if (output) return output;
+	if (result.status === 28) return `download timed out (no connection within 15 s or not finished within 300 s)`;
+	if (result.signal) return `installer stopped by ${result.signal}`;
+	if (result.error) return result.error.message;
+	return `installer exited with status ${result.status ?? "unknown"}`;
+}
+function installIiiArchive(opts) {
+	const expected = expectedIiiSha256(opts.version, opts.asset, opts.checksums);
+	if (!expected) return {
+		ok: false,
+		reason: "no-checksum",
+		detail: `no pinned SHA-256 for ${opts.asset} in iii v${opts.version}, so the download cannot be verified`
+	};
+	const run = (script, args) => spawnSync(opts.sh, [
+		"-c",
+		script,
+		"sh",
+		...args
+	], {
+		stdio: "pipe",
+		encoding: "utf-8",
+		timeout: III_INSTALL_SPAWN_TIMEOUT_MS,
+		env: opts.env ?? process.env
+	});
+	const archive = iiiArchivePath(opts.binDir);
+	const download = run(iiiDownloadShellCommand(), [
+		opts.releaseUrl,
+		opts.binDir,
+		archive
+	]);
+	if (download.status !== 0) return {
+		ok: false,
+		reason: "download",
+		detail: describeInstallFailure(download)
+	};
+	let actual;
+	try {
+		actual = sha256File(archive);
+	} catch (err) {
+		rmSync(archive, { force: true });
+		return {
+			ok: false,
+			reason: "download",
+			detail: err instanceof Error ? err.message : String(err)
+		};
+	}
+	if (actual !== expected) {
+		rmSync(archive, { force: true });
+		return {
+			ok: false,
+			reason: "checksum",
+			detail: `SHA-256 mismatch for ${opts.asset}: expected ${expected}, got ${actual}. The download was deleted and nothing was installed`
+		};
+	}
+	const extract = run(iiiExtractShellCommand(), [
+		archive,
+		opts.binDir,
+		opts.binPath
+	]);
+	if (extract.status !== 0) return {
+		ok: false,
+		reason: "extract",
+		detail: describeInstallFailure(extract)
+	};
+	return { ok: true };
+}
+//#endregion
+//#region src/cli/startup-stderr.ts
+function createStartupStderrCapture(maxBytes = 16 * 1024) {
+	const chunks = [];
+	let capturedBytes = 0;
+	return {
+		append(chunk) {
+			if (capturedBytes >= maxBytes) return;
+			const slice = chunk.subarray(0, maxBytes - capturedBytes);
+			chunks.push(slice);
+			capturedBytes += slice.length;
+		},
+		text() {
+			return Buffer.concat(chunks).toString("utf8");
+		}
+	};
+}
+//#endregion
+//#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 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 (/^\s*-\s+name:\s*(?:iii-exec|"iii-exec"|'iii-exec')(?:\s+#.*)?\s*$/.test(line)) {
+			workerIndent = indent;
+			continue;
+		}
+		if (workerIndent === void 0) continue;
+		if (execIndent !== void 0 && indent <= execIndent) execIndent = void 0;
+		if (/^\s*exec:\s*(?:#.*)?$/.test(line)) {
+			execIndent = indent;
+			continue;
+		}
+		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 false;
+}
+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
+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) {
@@ -436,7 +794,6 @@ const DEFAULTS = {
 	skipSplash: false,
 	skipNpxHint: false,
 	skipGlobalInstall: false,
-	skipConsoleInstall: false,
 	firstRunAt: null,
 	injectContextChosen: false
 };
@@ -765,86 +1122,811 @@ async function wireSelectedAgents(agents) {
 	p.note(summary.join("\n"), "wire summary");
 }
 //#endregion
-//#region src/cli-data-dir.ts
-function argValue(args, name) {
-	const equals = `${name}=`;
-	const inline = args.find((arg) => arg.startsWith(equals));
-	if (inline) return inline.slice(equals.length);
-	const idx = args.indexOf(name);
-	if (idx !== -1) return args[idx + 1];
-}
-function expandHome(pathValue, home) {
-	if (pathValue === "~") return home;
-	if (pathValue.startsWith("~/") || pathValue.startsWith("~\\")) return join(home, pathValue.slice(2));
-	return pathValue;
-}
-function absoluteDataDir(pathValue, cwd, home) {
-	const expanded = expandHome(pathValue, home);
-	return isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
-}
-function platformDefaultDataDir(env, home, nodePlatform, useXdg = true) {
-	if (nodePlatform === "darwin") return join(home, "Library", "Application Support", "agentmemory");
-	if (nodePlatform === "win32") {
-		const appData = env["APPDATA"];
-		return appData ? join(appData, "agentmemory") : join(home, ".agentmemory");
-	}
-	const xdgDataHome = env["XDG_DATA_HOME"];
-	if (useXdg && xdgDataHome && isAbsolute(xdgDataHome)) return join(xdgDataHome, "agentmemory");
-	return join(home, ".local", "share", "agentmemory");
-}
-function nearestGitParent(pathValue) {
-	let current = pathValue;
-	while (true) {
-		if (existsSync(join(current, ".git"))) return current;
-		const parent = dirname(current);
-		if (parent === current) return void 0;
-		current = parent;
-	}
-}
-function isWithin(parent, child) {
-	const pathFromParent = relative(parent, child);
-	return pathFromParent === "" || pathFromParent !== ".." && !pathFromParent.startsWith(`..${sep}`) && !isAbsolute(pathFromParent);
-}
-function resolveDataDir(options = {}) {
-	const args = options.args ?? process.argv.slice(2);
-	const env = options.env ?? process.env;
-	const cwd = options.cwd ?? process.cwd();
-	const home = options.home ?? homedir();
-	const nodePlatform = options.platform ?? platform();
-	const parsedInstance = parseInt(argValue(args, "--instance") ?? "0", 10);
-	const instance = parsedInstance > 0 && parsedInstance <= 50 ? parsedInstance : 0;
-	const forInstance = (dataDir) => instance ? join(dataDir, `instance-${instance}`) : dataDir;
-	const flagValue = argValue(args, "--data-dir");
-	if (flagValue) return {
-		dataDir: forInstance(absoluteDataDir(flagValue, cwd, home)),
-		source: "flag"
+//#region src/cli/capture.ts
+function headers(secret) {
+	const h = { "Content-Type": "application/json" };
+	if (secret) h["Authorization"] = `Bearer ${secret}`;
+	return h;
+}
+function classify(status) {
+	if (status === 200) return "duplicate";
+	if (status >= 200 && status < 300) return "delivered";
+	if (status === 408 || status === 429 || status >= 500) return "retry";
+	return "rejected";
+}
+async function serverCapture(base, secret) {
+	try {
+		const res = await fetch(`${base}/agentmemory/capture?limit=20`, {
+			headers: headers(secret),
+			signal: AbortSignal.timeout(5e3)
+		});
+		if (!res.ok) return { error: `HTTP ${res.status}` };
+		return await res.json();
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+}
+async function runCaptureCommand(options) {
+	const log = options.log ?? ((line) => console.log(line));
+	const json = options.args.includes("--json");
+	const drain = options.args.includes("--drain");
+	const output = {};
+	if (drain) output["drain"] = await drainSpool(options.base, async (record) => {
+		const res = await fetch(`${options.base}/agentmemory/observe`, {
+			method: "POST",
+			headers: headers(options.secret),
+			body: JSON.stringify({
+				...record.body,
+				eventId: record.eventId
+			}),
+			signal: AbortSignal.timeout(1e4)
+		});
+		const text = await res.text().catch(() => "");
+		const outcome = classify(res.status);
+		if (outcome === "delivered" || outcome === "duplicate") {
+			let mark = null;
+			try {
+				mark = parseSentMark(JSON.parse(text));
+			} catch {}
+			if (mark) retainSent(options.base, record.eventId, record.body, mark);
+		}
+		return outcome;
+	});
+	output["spool"] = spoolSummary(options.base);
+	output["server"] = await serverCapture(options.base, options.secret);
+	if (json) {
+		log(JSON.stringify(output, null, 2));
+		return 0;
+	}
+	const spool = output["spool"];
+	if (drain) {
+		const d = output["drain"];
+		log(d.skipped ? `Drain skipped: ${d.skipped === "locked" ? "another drain is running" : "nothing to send"}` : `Drained ${d.claimed}: ${d.delivered} stored, ${d.duplicates} already stored, ${d.rejected} rejected, ${d.expired} expired, ${d.remaining} still waiting${d.error ? ` (${d.error})` : ""}`);
+	}
+	log(`Local spool: ${spool.enabled ? `${spool.records} waiting, ${spool.bytes} bytes` : "off (AGENTMEMORY_CAPTURE_SPOOL=false)"}`);
+	log(`  file: ${spool.path}`);
+	log(`  limits: ${spool.maxBytes} bytes, ${spool.maxAgeHours} h`);
+	log(`  totals: ${spool.stats.spooled} spooled, ${spool.stats.delivered} delivered, ${spool.stats.duplicates} duplicates, ${spool.stats.dropped} dropped, ${spool.stats.expired} expired`);
+	if (spool.stats.lastDrainAt) log(`  last drain: ${spool.stats.lastDrainAt}`);
+	if (spool.stats.lastDropAt) log(`  last drop: ${spool.stats.lastDropAt} (${spool.stats.lastDropReason ?? "unknown"})`);
+	const server = output["server"];
+	if (server.error) {
+		log(`Server: unreachable at ${options.base} (${server.error})`);
+		return 0;
+	}
+	const inbox = server.capture?.inbox;
+	log(`Server inbox: ${inbox ? `${inbox.pending} pending, ${inbox.retrying} retrying, ${inbox.dead} dead letters` : "unknown"}`);
+	if (inbox?.lastError) log(`  last error: ${inbox.lastError}`);
+	for (const item of server.items ?? []) log(`  ${item.status.padEnd(8)} ${item.eventId} attempts=${item.attempts} ${item.preview ?? ""}`);
+	if (inbox && inbox.dead > 0) log(`Retry dead letters: curl -X POST ${options.base}/agentmemory/capture/retry ${CURL_AUTH_HEADER} -H "Content-Type: application/json" -d '{"all":true}'`);
+	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));
 	};
-	const envValue = env["AGENTMEMORY_DATA_DIR"];
-	if (envValue) return {
-		dataDir: forInstance(absoluteDataDir(envValue, cwd, home)),
-		source: "env"
+	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 legacyDir = resolve(cwd, "data");
-	const hasLegacyStore = existsSync(join(legacyDir, "state_store.db")) || existsSync(join(legacyDir, "iii-config.yaml"));
-	if (instance === 0 && hasLegacyStore) return {
-		dataDir: legacyDir,
-		source: "default"
+}
+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 defaultDir = platformDefaultDataDir(env, home, nodePlatform);
-	const gitParent = nearestGitParent(cwd);
-	if (gitParent && isWithin(gitParent, defaultDir)) {
-		const relocated = platformDefaultDataDir(env, home, nodePlatform, false);
-		if (relocated !== defaultDir) return {
-			dataDir: forInstance(relocated),
-			source: "default",
-			relocatedFrom: defaultDir
+	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 {
-		dataDir: forInstance(defaultDir),
-		source: "default"
+		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 = {
@@ -865,12 +1947,14 @@ 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);
 }
-const IIPINNED_VERSION = process.env["AGENTMEMORY_III_VERSION"] || "0.11.2";
+const IIPINNED_DEFAULT_VERSION = III_PINNED_VERSION;
+const IIPINNED_VERSION = process.env["AGENTMEMORY_III_VERSION"] || IIPINNED_DEFAULT_VERSION;
+const IIIENGINE_INSTALL_CMD = `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=${IIPINNED_VERSION} sh`;
 function iiiReleaseAsset() {
 	const p = platform();
 	const a = process.arch;
@@ -911,13 +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            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
@@ -928,11 +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)
@@ -943,27 +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_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
@@ -979,21 +2078,63 @@ if (toolsIdx !== -1 && args[toolsIdx + 1]) {
 	if (toolsMode !== "all" && toolsMode !== "core") p.log.warn(`Unknown --tools value "${toolsMode}" (valid: all, core); falling back to all.`);
 	process.env["AGENTMEMORY_TOOLS"] = toolsMode;
 }
-const portIdx = args.indexOf("--port");
-if (portIdx !== -1 && args[portIdx + 1]) process.env["III_REST_PORT"] = args[portIdx + 1];
-const instanceIdx = args.indexOf("--instance");
-if (instanceIdx !== -1 && args[instanceIdx + 1]) {
-	const n = parseInt(args[instanceIdx + 1] || "", 10);
-	if (Number.isFinite(n) && n >= 0 && n <= 50) {
-		const base = 3111 + n * 100;
-		if (!process.env["III_REST_PORT"]) process.env["III_REST_PORT"] = String(base);
+const URL_CLIENT_COMMANDS = new Set([
+	"status",
+	"doctor",
+	"mcp",
+	"capture",
+	"compression",
+	"graph-index"
+]);
+let hasExplicitLocalPortOverride = false;
+let selectedInstance = 0;
+function cliArgValue(name) {
+	const inline = args.find((arg) => arg.startsWith(`${name}=`));
+	if (inline) return inline.slice(name.length + 1);
+	const index = args.indexOf(name);
+	return index === -1 ? void 0 : args[index + 1];
+}
+const portValue = cliArgValue("--port");
+if (portValue) {
+	process.env["III_REST_PORT"] = portValue;
+	hasExplicitLocalPortOverride = true;
+}
+const instanceValue = cliArgValue("--instance");
+if (args.some((arg) => arg === "--instance" || arg.startsWith("--instance="))) {
+	if (instanceValue === void 0 || !/^\d+$/.test(instanceValue)) {
+		p.log.error("--instance must be an integer between 0 and 50.");
+		process.exit(1);
 	}
+	const n = Number(instanceValue);
+	if (!Number.isInteger(n) || n > 50) {
+		p.log.error("--instance must be an integer between 0 and 50.");
+		process.exit(1);
+	}
+	selectedInstance = n;
+	const base = 3111 + n * 100;
+	if (!hasExplicitLocalPortOverride) process.env["III_REST_PORT"] = String(base);
+	hasExplicitLocalPortOverride = true;
+}
+const restPort = parseInt(process.env["III_REST_PORT"] || "3111", 10);
+if (Number.isFinite(restPort) && restPort > 0) {
+	process.env["III_VIEWER_PORT"] ??= String(restPort + 2);
+	const configuredEngineUrl = process.env["III_ENGINE_URL"];
+	if (configuredEngineUrl) try {
+		const parsedEnginePort = new URL(configuredEngineUrl).port;
+		if (parsedEnginePort) process.env["III_ENGINE_PORT"] = parsedEnginePort;
+	} catch {}
+	else process.env["III_ENGINE_PORT"] ??= String(restPort + 46023);
+	process.env["AGENTMEMORY_METRICS_PORT"] ??= String(restPort + 6353);
 }
 const dataDirResolution = resolveDataDir({ args });
-if (dataDirResolution.source !== "default") process.env["AGENTMEMORY_DATA_DIR"] = dataDirResolution.dataDir;
+process.env["AGENTMEMORY_DATA_DIR"] = dataDirResolution.dataDir;
+process.env["AGENTMEMORY_RUNTIME_DIR"] = selectedInstance > 0 ? dataDirResolution.dataDir : join(homedir(), ".agentmemory");
 const skipEngine = args.includes("--no-engine");
+function shouldUseAgentmemoryUrl() {
+	return !hasExplicitLocalPortOverride && URL_CLIENT_COMMANDS.has(args[0] ?? "");
+}
 function getRestPort() {
-	const url = process.env["AGENTMEMORY_URL"];
+	const url = shouldUseAgentmemoryUrl() ? process.env["AGENTMEMORY_URL"] : void 0;
 	if (url) try {
 		const parsed = new URL(url).port;
 		if (parsed) return parseInt(parsed, 10);
@@ -1001,10 +2142,13 @@ function getRestPort() {
 	return parseInt(process.env["III_REST_PORT"] || "3111", 10) || 3111;
 }
 function getBaseUrl() {
-	const url = process.env["AGENTMEMORY_URL"];
+	const url = shouldUseAgentmemoryUrl() ? process.env["AGENTMEMORY_URL"] : void 0;
 	if (url) return url.replace(/\/+$/, "");
 	return `http://localhost:${getRestPort()}`;
 }
+function getConfiguredViewerPort() {
+	return parseInt(process.env["III_VIEWER_PORT"] || "", 10) || getRestPort() + 2;
+}
 let discoveredViewerPort = null;
 async function discoverViewerPort() {
 	if (discoveredViewerPort !== null) return;
@@ -1027,75 +2171,36 @@ function getViewerUrl() {
 	}
 	try {
 		const u = new URL(getBaseUrl());
-		const vPort = parseInt(process.env["III_VIEWER_PORT"] || "", 10) || (parseInt(u.port || "3111", 10) || 3111) + 2;
+		const vPort = getConfiguredViewerPort();
 		return `${u.protocol}//${u.hostname}:${vPort}`;
 	} catch {
-		return `http://localhost:${parseInt(process.env["III_VIEWER_PORT"] || "", 10) || getRestPort() + 2}`;
+		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 explicit = parseInt(process.env["III_ENGINE_PORT"] || "", 10);
-	if (explicit) return explicit;
 	const url = process.env["III_ENGINE_URL"];
 	if (url) try {
 		const parsed = new URL(url).port;
 		if (parsed) return parseInt(parsed, 10);
 	} catch {}
+	const explicit = parseInt(process.env["III_ENGINE_PORT"] || "", 10);
+	if (explicit) return explicit;
 	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 c;
-	return "";
-}
-function yamlSingleQuoted(value) {
-	return `'${value.replace(/'/g, "''")}'`;
-}
-function renderIiiConfig(template, dataDir) {
-	return template.replace("file_path: ./data/state_store.db", `file_path: ${yamlSingleQuoted(join(dataDir, "state_store.db"))}`).replace("file_path: ./data/stream_store", `file_path: ${yamlSingleQuoted(join(dataDir, "stream_store"))}`);
-}
-function writeRuntimeIiiConfig(configPath, dataDir) {
-	mkdirSync(dataDir, { recursive: true });
-	const runtimeConfigPath = join(dataDir, "iii-config.yaml");
-	writeFileSync(runtimeConfigPath, renderIiiConfig(readFileSync(configPath, "utf8"), dataDir));
-	return runtimeConfigPath;
+function workerReadinessProbe(signal) {
+	return probeWorker(getBaseUrl(), signal, (port) => {
+		discoveredViewerPort = port;
+	});
 }
 function warnIfRelocatedDataDir() {
 	if (!dataDirResolution.relocatedFrom) return;
@@ -1178,19 +2283,10 @@ function resolveCompatibleIii(iiiBinPath) {
 	return null;
 }
 function enginePidfilePath() {
-	return join(homedir(), ".agentmemory", "iii.pid");
+	return runtimeMetadataPath("iii.pid");
 }
 function engineStatePath() {
-	return join(homedir(), ".agentmemory", "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)}`);
-	}
+	return runtimeMetadataPath("engine-state.json");
 }
 function readEnginePidfile() {
 	try {
@@ -1207,7 +2303,7 @@ function clearEnginePidfile() {
 	} catch {}
 }
 function workerPidfilePath() {
-	return join(homedir(), ".agentmemory", "worker.pid");
+	return runtimeMetadataPath("worker.pid");
 }
 function readWorkerPidfile() {
 	try {
@@ -1223,20 +2319,11 @@ function clearWorkerPidfile() {
 		unlinkSync(workerPidfilePath());
 	} catch {}
 }
-function writeEngineState(state) {
-	try {
-		const statePath = engineStatePath();
-		mkdirSync(dirname(statePath), { recursive: true });
-		writeFileSync(statePath, `${JSON.stringify(state)}\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;
@@ -1247,12 +2334,154 @@ function clearEngineState() {
 		unlinkSync(engineStatePath());
 	} catch {}
 }
-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 engineStateRestPort(state) {
+	if (state.restPort && Number.isFinite(state.restPort)) return state.restPort;
+	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(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" || state.attached) return false;
+	try {
+		return configStartsAgentmemoryWorker(readFileSync(state.configPath, "utf-8"), join(__dirname, "index.mjs"), state.cwd);
+	} catch {
+		return false;
+	}
+}
+async function assertRuntimePortOwnership() {
+	const state = readEngineState();
+	if (!state) return;
+	if (state.kind === "docker") {
+		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));
+	if (!active) try {
+		await fetch(`http://127.0.0.1:${ownerPort}/`, { signal: AbortSignal.timeout(750) });
+		active = true;
+	} catch {}
+	if (active) {
+		p.log.error(`The canonical lifecycle state is owned by a live agentmemory 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);
+	}
+	clearEnginePidfile();
+	clearWorkerPidfile();
+	clearEngineState();
 }
 function isInvokedViaNpx() {
 	if (process.env["npm_lifecycle_event"] === "npx") return true;
@@ -1285,93 +2514,25 @@ async function maybeOfferGlobalInstall() {
 	if (runCommand(npmBin, [
 		"install",
 		"-g",
-		`@agentmemory/agentmemory@0.9.29`
-	], { label: `Installing @agentmemory/agentmemory@0.9.29 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 detectIiiConsole() {
-	const onPath = whichBinary("iii-console");
-	if (onPath) return {
-		kind: "installed",
-		binPath: onPath
-	};
-	const fallback = IS_WINDOWS ? join(process.env["USERPROFILE"] ?? "", ".local", "bin", "iii-console.exe") : join(homedir(), ".local", "bin", "iii-console");
-	if (fallback && existsSync(fallback)) return {
-		kind: "installed",
-		binPath: fallback
-	};
-	return { kind: "missing" };
-}
-const III_CONSOLE_INSTALL_CMD = `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=${IIPINNED_VERSION} sh`;
-function iiiConsoleInstallHint() {
-	if (!IS_WINDOWS) return III_CONSOLE_INSTALL_CMD;
-	return `# PowerShell:\n  $env:VERSION = "${IIPINNED_VERSION}"\n  iwr -useb https://install.iii.dev/iii/main/install.sh -OutFile install.sh\n  bash install.sh   # WSL or Git Bash required\n# Or grab the pinned release directly:\n  https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`;
-}
-async function ensureIiiConsole() {
-	const state = detectIiiConsole();
-	if (state.kind === "installed") return state;
-	if (!process.stdin.isTTY || process.env["CI"]) return state;
-	if (readPrefs().skipConsoleInstall) return state;
-	const answer = await p.confirm({
-		message: "iii console gives engine-level visibility (workers, functions, queues, traces). Install now?",
-		initialValue: true
-	});
-	if (p.isCancel(answer)) return state;
-	if (answer === false) {
-		writePrefs({ skipConsoleInstall: true });
-		return state;
-	}
-	const shBin = whichBinary("sh");
-	const curlBin = whichBinary("curl");
-	if (!shBin || !curlBin) {
-		p.log.warn(`curl or sh not found. Install manually:\n  ${iiiConsoleInstallHint()}`);
-		return state;
-	}
-	if (!runCommand(shBin, ["-c", III_CONSOLE_INSTALL_CMD], { label: "Installing iii console" })) {
-		p.log.warn(`iii console install failed. Re-run manually:\n  ${iiiConsoleInstallHint()}`);
-		return state;
-	}
-	return detectIiiConsole();
-}
-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  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
@@ -1379,8 +2540,14 @@ async function runIiiInstaller() {
 	}
 	const shBin = whichBinary("sh");
 	const curlBin = whichBinary("curl");
-	if (!shBin || !curlBin) {
-		p.log.warn("curl or sh not found. Cannot auto-install iii-engine.");
+	const tarBin = whichBinary("tar");
+	if (!shBin || !curlBin || !tarBin) {
+		const missing = [
+			!shBin && "sh",
+			!curlBin && "curl",
+			!tarBin && "tar"
+		].filter(Boolean).join(", ");
+		p.log.warn(`${missing} not found. Cannot auto-install iii-engine.`);
 		return {
 			ok: false,
 			binPath: null
@@ -1388,75 +2555,335 @@ async function runIiiInstaller() {
 	}
 	const binDir = agentmemoryBinDir();
 	const binPath = privateIiiPath();
-	if (!runCommand(shBin, ["-c", [
-		`mkdir -p "${binDir}"`,
-		`curl -fsSL "${releaseUrl}" | tar -xz -C "${binDir}"`,
-		`chmod +x "${binPath}"`
-	].join(" && ")], {
-		label: `Installing iii-engine v${IIPINNED_VERSION} (pinned)`,
-		optional: true
-	})) {
-		p.log.warn(`iii-engine installer failed. Fallbacks: Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`);
+	const label = `Installing iii-engine v${IIPINNED_VERSION} (pinned)`;
+	const spinner = p.spinner();
+	spinner.start(label);
+	const outcome = installIiiArchive({
+		sh: shBin,
+		releaseUrl,
+		version: IIPINNED_VERSION,
+		asset: asset ?? "",
+		binDir,
+		binPath
+	});
+	if (!outcome.ok) {
+		spinner.stop(`${label} ${pc.red("✗")}`);
+		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);
 		return {
 			ok: false,
 			binPath: null
 		};
 	}
+	spinner.stop(`${label} ${pc.green("✓")}`);
 	return {
 		ok: true,
 		binPath
 	};
-}
-let startupFailure = null;
-function spawnEngineBackground(bin, spawnArgs, label) {
-	vlog(`spawn: ${bin} ${spawnArgs.join(" ")}`);
-	const child = spawn(bin, spawnArgs, {
-		detached: true,
-		stdio: [
-			"ignore",
-			"ignore",
-			"pipe"
-		],
-		windowsHide: true
+}
+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 readComposeStartupLogs() {
+	const state = readEngineState();
+	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 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");
+		}
+		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 composeChildProcesses(state) {
+	if (IS_WINDOWS || !state.composePid) return [];
+	try {
+		const rows = execFileSync("ps", ["-eo", "pid=,ppid=,pgid=,command="], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).split(/\r?\n/).map((row) => {
+			const match = row.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/);
+			return match ? {
+				pid: Number(match[1]),
+				ppid: Number(match[2]),
+				pgid: Number(match[3]),
+				args: match[4]
+			} : null;
+		}).filter((row) => row !== null);
+		const descendants = new Set([state.composePid]);
+		let changed = true;
+		while (changed) {
+			changed = false;
+			for (const row of rows) if (!descendants.has(row.pid) && descendants.has(row.ppid)) {
+				descendants.add(row.pid);
+				changed = true;
+			}
+		}
+		return rows.filter((row) => row.pid !== state.composePid && descendants.has(row.pid)).map(({ pid, pgid, args }) => ({
+			pid,
+			pgid,
+			args
+		}));
+	} catch {
+		return [];
+	}
+}
+function composeChildPids(state) {
+	return [...new Set(composeChildProcesses(state).map((child) => child.pid))];
+}
+function composeEnginePid(state) {
+	return composeChildProcesses(state).find(({ args }) => args.includes(" --config ") && args.includes(state.namespace))?.pid;
+}
+async function terminateComposeChildren(state) {
+	if (IS_WINDOWS) return true;
+	const groups = [...new Set(composeChildProcesses(state).map((child) => child.pgid).filter((pgid) => pgid !== state.composePid))];
+	let stopped = true;
+	for (const pgid of groups) {
+		try {
+			process.kill(-pgid, "SIGTERM");
+		} catch (err) {
+			if (err.code !== "ESRCH") stopped = false;
+			continue;
+		}
+		const deadline = Date.now() + 5e3;
+		while (Date.now() < deadline) {
+			try {
+				process.kill(-pgid, 0);
+			} catch {
+				break;
+			}
+			await new Promise((resolve) => setTimeout(resolve, 100));
+		}
+		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;
+}
+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
 	});
-	const isDocker = label.includes("Docker");
-	if (!isDocker && typeof child.pid === "number") writeEnginePidfile(child.pid);
-	const stderrChunks = [];
-	let stderrBytes = 0;
-	const MAX_STDERR_CAPTURE = 16 * 1024;
-	child.stderr?.on("data", (chunk) => {
-		if (stderrBytes >= MAX_STDERR_CAPTURE) return;
-		const slice = chunk.subarray(0, MAX_STDERR_CAPTURE - stderrBytes);
-		stderrChunks.push(slice);
-		stderrBytes += slice.length;
+	engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);
+	compose.child.on("error", (error) => {
+		if (spawnedComposeDaemon === compose.child) startupFailure = {
+			kind: "engine-crashed",
+			stderr: redactCredentialUrls(error.message),
+			binary: iiiBin
+		};
 	});
-	child.on("exit", (code, signal) => {
-		if (code !== null && code !== 0 || code === null && signal !== null) {
-			const stderr = Buffer.concat(stderrChunks).toString("utf-8");
-			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();
-		}
+	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
+		};
 	});
-	child.unref();
-	return child;
-}
-function startIiiBin(iiiBin, configPath) {
 	const s = p.spinner();
-	s.start(`Starting iii-engine: ${iiiBin}`);
-	writeEngineState({
-		kind: "native",
-		configPath,
-		binPath: iiiBin
-	});
-	spawnEngineBackground(iiiBin, ["--config", configPath], "iii-engine");
-	s.stop(c.ok("iii-engine process started"));
+	s.start(`Starting iii Worker Compose: ${iiiBin}`);
+	s.stop(c.ok(`Compose daemon started (pid ${compose.child.pid})`));
 	return true;
 }
 function pickCompatibleIii(candidates) {
@@ -1468,41 +2895,56 @@ function pickCompatibleIii(candidates) {
 	return null;
 }
 async function startEngine() {
-	const configPath = findIiiConfig();
+	startupFailure = null;
+	engineReadinessDeadline = null;
+	let stateBackendKind;
+	try {
+		stateBackendKind = getStateBackend();
+	} catch (err) {
+		p.log.error(err instanceof Error ? err.message : String(err));
+		process.exit(1);
+	}
+	if (stateBackendKind === "redis" && !getRedisUrl()) {
+		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);
+	}
+	const persistedState = readEngineState();
+	if (persistedState?.kind === "docker") {
+		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();
+		}
+	}
 	warnIfRelocatedDataDir();
-	const runtimeConfigPath = configPath ? writeRuntimeIiiConfig(configPath, dataDirResolution.dataDir) : "";
 	const pathIii = whichBinary("iii");
-	vlog(`iii binary: ${pathIii ?? "(not on PATH)"}, config: ${runtimeConfigPath || "(not found)"}`);
+	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 && runtimeConfigPath) {
+	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, runtimeConfigPath);
+		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;
-	}
-	const dockerBin = whichBinary("docker");
-	vlog(`docker binary: ${dockerBin ?? "(not on PATH)"}`);
 	mkdirSync(dataDirResolution.dataDir, { recursive: true });
-	const composeFile = [
-		join(__dirname, "..", "docker-compose.yml"),
-		join(__dirname, "docker-compose.yml"),
-		join(process.cwd(), "docker-compose.yml")
-	].find((c) => existsSync(c));
-	vlog(`docker-compose.yml: ${composeFile ?? "(not found)"}`);
-	const dockerOptIn = process.env["AGENTMEMORY_USE_DOCKER"] === "1" || process.env["AGENTMEMORY_USE_DOCKER"] === "true";
 	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).`);
@@ -1516,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"
@@ -1545,80 +2982,59 @@ 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) {
-		const s = p.spinner();
-		s.start("Starting iii-engine via Docker...");
-		writeEngineState({
-			kind: "docker",
-			composeFile
-		});
-		spawnEngineBackground(dockerBin, [
-			"compose",
-			"-f",
-			composeFile,
-			"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 waitForPersistedNativeEngine() {
+	const state = readEngineState();
+	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() {
 	const releaseUrl = iiiReleaseUrl();
-	if (IS_WINDOWS) return [
-		`agentmemory needs iii-engine v${IIPINNED_VERSION}. Pick one:`,
-		"",
-		"  A) Download the prebuilt Windows binary:",
-		`     1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`,
-		`     2. Download iii-x86_64-pc-windows-msvc.zip (or iii-aarch64-pc-windows-msvc.zip on ARM)`,
-		"     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"
-	];
-	const linuxInstall = releaseUrl ? `  A) mkdir -p ~/.agentmemory/bin && curl -fsSL "${releaseUrl}" | tar -xz -C ~/.agentmemory/bin && chmod +x ~/.agentmemory/bin/iii` : `  A) Manual download: https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`;
+	if (IS_WINDOWS) {
+		const asset = iiiReleaseAsset() ?? "";
+		const sha256 = expectedIiiSha256(IIPINNED_VERSION, asset);
+		const verify = sha256 ? `     Verify before extracting: (Get-FileHash .\\${asset}).Hash must be ${sha256.toUpperCase()}` : `     Verify before extracting against the matching .sha256 file on the release page`;
+		return [
+			`agentmemory needs iii-engine v${IIPINNED_VERSION}. Pick one:`,
+			"",
+			"  A) Download the prebuilt Windows binary:",
+			`     1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`,
+			`     2. Download iii-x86_64-pc-windows-msvc.zip (or iii-aarch64-pc-windows-msvc.zip on ARM)`,
+			verify,
+			"     3. Extract iii.exe to %USERPROFILE%\\.local\\bin\\iii.exe (or add to PATH)",
+			"     4. Re-run: npx @agentmemory/agentmemory",
+			"",
+			"Or skip the engine entirely (standalone MCP):  npx @agentmemory/agentmemory mcp",
+			"",
+			"Docs: https://iii.dev/docs"
+		];
+	}
+	const linuxInstall = releaseUrl ? `  A) ${iiiManualInstallCommand(releaseUrl, agentmemoryBinDir(), privateIiiPath(), expectedIiiSha256(IIPINNED_VERSION, iiiReleaseAsset() ?? ""))}` : `  A) Manual download: https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`;
 	return [
 		`agentmemory needs iii-engine v${IIPINNED_VERSION}. Pick one:`,
 		"",
 		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"
@@ -1627,79 +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() {
-	for (const envKey of ["III_ENGINE_URL", "AGENTMEMORY_URL"]) {
-		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(consoleState) {
+function printReadyHint() {
 	const restUrl = getBaseUrl();
 	const viewerUrl = getViewerUrl();
-	const engineHost = getEngineHost();
-	const streamUrl = `ws://${engineHost}:${getStreamPort()}`;
-	const engineUrl = `ws://${engineHost}:${getEnginePort()}`;
-	const consoleLine = consoleState.kind === "installed" ? `${c.label("iii console")}  ${c.dim(consoleState.binPath)}  ${c.dim(`(run: ${consoleState.binPath} -p <port>)`)}` : `${c.label("iii console")}  ${c.dim(`(install: ${iiiConsoleInstallHint()})`)}`;
+	const engineUrl = process.env["III_ENGINE_URL"] || `ws://localhost:${getEnginePort()}`;
+	const invocation = isInvokedViaNpx() ? "npx @agentmemory/agentmemory" : "agentmemory";
+	const portFlags = portFlagSuffix(getRestPort(), selectedInstance);
 	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 = isInvokedViaNpx() ? "npx @agentmemory/agentmemory demo" : "agentmemory demo";
+	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-G7yt8gGm.mjs");
-		if (await waitForAgentmemoryReady(15e3)) {
-			const consoleState = await ensureIiiConsole();
-			await maybeOfferGlobalInstall();
-			printReadyHint(consoleState);
-		}
+		await startWorkerForEngineState();
+		await maybeOfferGlobalInstall();
+		printReadyHint();
+		return;
+	}
+	if (await reconcilePersistedComposeEngine()) {
+		await startWorkerForEngineState();
+		await maybeOfferGlobalInstall();
+		printReadyHint();
 		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 import("./src-G7yt8gGm.mjs");
-			if (await waitForAgentmemoryReady(15e3)) {
-				const consoleState = await ensureIiiConsole();
-				await maybeOfferGlobalInstall();
-				printReadyHint(consoleState);
-			}
-			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";
@@ -1718,7 +3156,7 @@ async function main() {
 			`       ${c.cmd(base)}`,
 			"",
 			c.dim(`Step 2 needs no manual install. To install iii v${IIPINNED_VERSION} yourself (replaces your global iii), curl:`),
-			`     ${c.cmd(III_CONSOLE_INSTALL_CMD)}`,
+			`     ${c.cmd(IIIENGINE_INSTALL_CMD)}`,
 			`     ${c.dim("or download the release:")} ${c.url(`https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`)}`
 		].join("\n"), "engine conflict");
 		process.exit(1);
@@ -1726,16 +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");
-		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");
@@ -1744,13 +3208,13 @@ 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."
 			].join("\n"), "Troubleshooting");
 		} else {
 			p.log.error("The engine process started but the REST API never responded.");
+			printCapturedStartupStderr();
 			p.note([
 				`Check whether port ${port} is already bound by another process:`,
 				portInUseDiagnostic(port),
@@ -1761,22 +3225,30 @@ 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 import("./src-G7yt8gGm.mjs");
-	if (await waitForAgentmemoryReady(15e3)) {
-		const consoleState = await ensureIiiConsole();
-		await maybeOfferGlobalInstall();
-		printReadyHint(consoleState);
+	await startWorkerForEngineState();
+	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 {
-		const headers = {};
-		const secret = process.env["AGENTMEMORY_SECRET"];
-		if (secret) headers["Authorization"] = `Bearer ${secret}`;
+		const headers = bearerHeaders(base);
 		return await (await fetch(`${base}/agentmemory/${path}`, {
 			signal: AbortSignal.timeout(timeoutMs),
 			headers
@@ -1786,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);
@@ -1809,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;
@@ -1840,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}`);
@@ -1855,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));
@@ -1900,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 {
@@ -1984,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) {
@@ -2014,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)
@@ -2052,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",
@@ -2065,7 +3599,7 @@ async function passiveServerChecks() {
 	}, {
 		name: "Embedding provider",
 		ok: hasEmbed,
-		hint: hasEmbed ? void 0 : "Running BM25-only. Add OPENAI_API_KEY / VOYAGE_API_KEY / COHERE_API_KEY / OLLAMA_HOST"
+		hint: hasEmbed ? void 0 : "Running BM25-only. Set EMBEDDING_PROVIDER=local for on-device semantic search, or add OPENAI_API_KEY / VOYAGE_API_KEY / COHERE_API_KEY / OLLAMA_HOST"
 	});
 	for (const f of flags?.flags || []) checks.push({
 		name: f.label,
@@ -2097,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;
 }
@@ -2279,7 +3813,10 @@ async function postJson(url, body, timeoutMs = 5e3) {
 	try {
 		const res = await fetch(url, {
 			method: "POST",
-			headers: { "Content-Type": "application/json" },
+			headers: {
+				"Content-Type": "application/json",
+				...bearerHeaders(url)
+			},
 			body: JSON.stringify(body),
 			signal: AbortSignal.timeout(timeoutMs)
 		});
@@ -2292,7 +3829,10 @@ async function postJson(url, body, timeoutMs = 5e3) {
 async function postJsonStrict(url, body, timeoutMs = 5e3) {
 	const res = await fetch(url, {
 		method: "POST",
-		headers: { "Content-Type": "application/json" },
+		headers: {
+			"Content-Type": "application/json",
+			...bearerHeaders(url)
+		},
 		body: JSON.stringify(body),
 		signal: AbortSignal.timeout(timeoutMs)
 	});
@@ -2327,7 +3867,10 @@ async function seedDemoSession(base, project, session) {
 		try {
 			const res = await fetch(url, {
 				method: "POST",
-				headers: { "Content-Type": "application/json" },
+				headers: {
+					"Content-Type": "application/json",
+					...bearerHeaders(url)
+				},
 				body: JSON.stringify(payload),
 				signal: AbortSignal.timeout(5e3)
 			});
@@ -2340,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) {
@@ -2399,39 +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)) {
-			p.log.error("iii-engine did not become ready within 15s.");
-			process.exit(1);
+		if (!await waitForEngine()) {
+			printCapturedStartupStderr();
+			throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));
 		}
 	}
-	await import("./src-G7yt8gGm.mjs");
-	if (!await waitForAgentmemoryReady(15e3)) {
-		p.log.error("agentmemory worker did not become ready within 15s.");
-		process.exit(1);
-	}
+	await startWorkerForEngineState();
 	return async () => {
-		if (!startedEngine) return;
-		const port = getRestPort();
-		const state = readEngineState();
-		if (state?.kind === "docker") {
-			await stopDockerEngine(state.composeFile, 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() {
@@ -2482,8 +4015,8 @@ async function runDemoBody(base) {
 		"",
 		...semanticHits > 0 ? [c.accent(`Notice: searching "database performance optimization"`), c.accent(`found the N+1 query fix — keyword matching can't do that.`)] : [
 			c.dim(`Note: "database performance optimization" found nothing —`),
-			c.dim(`semantic recall needs an embedding provider key (e.g.`),
-			c.dim(`OPENAI_API_KEY or GEMINI_API_KEY in ~/.agentmemory/.env).`)
+			c.dim(`set EMBEDDING_PROVIDER=local for on-device semantic recall,`),
+			c.dim(`or add an embedding API key in ~/.agentmemory/.env.`)
 		],
 		"",
 		`Viewer:        ${c.url(getViewerUrl())}`,
@@ -2498,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("✓")}`);
@@ -2523,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) {
@@ -2533,14 +4069,22 @@ async function runUpgrade() {
 	};
 	if (hasPackageJson) if (!!pnpmBin && hasPnpmLock && pnpmBin) {
 		requireSuccess(runCommand(pnpmBin, ["install"], { label: "Refreshing dependencies (pnpm install)" }), "pnpm install");
-		runCommand(pnpmBin, ["up", "iii-sdk@0.11.2"], {
-			label: "Pinning iii-sdk@0.11.2",
+		runCommand(pnpmBin, [
+			"up",
+			`iii-sdk@${IIPINNED_DEFAULT_VERSION}`,
+			`@iii-dev/helpers@${IIPINNED_DEFAULT_VERSION}`
+		], {
+			label: `Pinning iii-sdk and @iii-dev/helpers at ${IIPINNED_DEFAULT_VERSION}`,
 			optional: true
 		});
 	} else if (npmBin) {
 		requireSuccess(runCommand(npmBin, ["install"], { label: "Refreshing dependencies (npm install)" }), "npm install");
-		runCommand(npmBin, ["install", "iii-sdk@0.11.2"], {
-			label: "Pinning iii-sdk@0.11.2",
+		runCommand(npmBin, [
+			"install",
+			`iii-sdk@${IIPINNED_DEFAULT_VERSION}`,
+			`@iii-dev/helpers@${IIPINNED_DEFAULT_VERSION}`
+		], {
+			label: `Pinning iii-sdk and @iii-dev/helpers at ${IIPINNED_DEFAULT_VERSION}`,
 			optional: true
 		});
 	} else p.log.warn("No package manager found (pnpm/npm). Skipping JS dependency upgrade.");
@@ -2555,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.",
 		"",
@@ -2572,6 +4111,22 @@ async function runUpgrade() {
 function pidAlive(pid) {
 	try {
 		process.kill(pid, 0);
+		if (!IS_WINDOWS) try {
+			const stat = execFileSync("ps", [
+				"-p",
+				String(pid),
+				"-o",
+				"stat="
+			], {
+				encoding: "utf-8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			});
+			if (stat.trim() && !processStatIsRunning(stat)) return false;
+		} catch {}
 		return true;
 	} catch (err) {
 		return err?.code === "EPERM";
@@ -2606,6 +4161,28 @@ async function signalAndWait(pid, initialSignal, timeoutMs) {
 	await new Promise((r) => setTimeout(r, 200));
 	return !pidAlive(pid);
 }
+async function waitForEngineFlush() {
+	let stateBackend = "file";
+	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(dataDirResolution.dataDir, runtimePath)) try {
+		configTexts.push(readFileSync(path, "utf-8"));
+	} catch {}
+	const waitMs = engineFlushWaitMs(stateBackend, configTexts);
+	if (waitMs <= 0) return;
+	const s = p.spinner();
+	s.start(`Waiting ${(waitMs / 1e3).toFixed(1)}s for iii-engine to write state to disk...`);
+	await new Promise((r) => setTimeout(r, waitMs));
+	s.stop("iii-engine state flush window passed");
+}
 async function stopWorkerPid(pid, graceMs) {
 	const s = p.spinner();
 	s.start(`Stopping agentmemory worker (pid ${pid})... [flushing state]`);
@@ -2613,6 +4190,46 @@ async function stopWorkerPid(pid, graceMs) {
 	s.stop(ok ? `Stopped worker pid ${pid}` : `Failed to stop worker pid ${pid}`);
 	return ok;
 }
+async function stopNativeEngineForRemoval() {
+	const port = getRestPort();
+	const workerPid = readWorkerPidfile();
+	const enginePids = new Set(findEnginePidsByPort(port));
+	const pidfilePid = readEnginePidfile();
+	if (pidfilePid) enginePids.add(pidfilePid);
+	if (workerPid) enginePids.delete(workerPid);
+	const foreign = [...enginePids].map((pid) => ({
+		pid,
+		comm: pidCommand(pid)
+	})).filter(({ comm }) => isForeignPortHolder(comm));
+	if (foreign.length > 0) return {
+		ok: false,
+		reason: `refusing to signal non-iii process(es): ${foreign.map(({ pid, comm }) => `${pid} (${comm})`).join(", ")}`
+	};
+	if (workerPid) {
+		if (!await stopWorkerPid(workerPid, 5e3)) return {
+			ok: false,
+			reason: `worker pid ${workerPid} could not be stopped; no engine or files were removed`
+		};
+		clearWorkerPidfile();
+	}
+	for (const pid of enginePids) {
+		const s = p.spinner();
+		s.start(`Stopping iii-engine (pid ${pid})...`);
+		const ok = await signalAndWait(pid, "SIGTERM", 3e3);
+		s.stop(ok ? `Stopped pid ${pid}` : `Failed to stop pid ${pid}`);
+		if (!ok) return {
+			ok: false,
+			reason: `engine pid ${pid} survived shutdown; lifecycle state and files were preserved`
+		};
+	}
+	clearEnginePidfile();
+	clearEngineState();
+	clearWorkerPidfile();
+	return {
+		ok: true,
+		stoppedEnginePids: enginePids.size
+	};
+}
 function pidCommand(pid) {
 	if (IS_WINDOWS) return "";
 	try {
@@ -2662,65 +4279,64 @@ function findEnginePidsByPort(port) {
 		return [];
 	}
 }
-async function stopDockerEngine(composeFile, port) {
-	const dockerBin = whichBinary("docker");
-	if (!dockerBin) {
-		p.log.error(`Engine was started via Docker compose, but \`docker\` is no longer on PATH. Stop it manually:\n  docker compose -f ${composeFile} down`);
-		process.exit(1);
-	}
-	if (!existsSync(composeFile)) {
-		p.log.error(`Engine state references ${composeFile}, but the file is gone. Stop it manually:\n  docker compose down  (from the dir holding the original docker-compose.yml)`);
-		process.exit(1);
-	}
-	const workerPid = readWorkerPidfile();
-	let workerStopped = true;
-	if (workerPid) workerStopped = await stopWorkerPid(workerPid, 5e3);
-	let composeText = "";
-	try {
-		composeText = readFileSync(composeFile, "utf-8");
-	} catch {
-		composeText = "";
-	}
-	const ownServices = ["iii-engine", "iii-init"].filter((svc) => new RegExp(`^\\s+${svc}:`, "m").test(composeText));
-	if (ownServices.length === 0) {
-		p.log.error(`${composeFile} does not define the agentmemory services (iii-engine/iii-init). Refusing to run an unscoped \`docker compose down\` against it — that would tear down every service in the file.\n\nStop the engine service manually:\n  docker compose -f ${composeFile} stop <service>`);
+async function runStop() {
+	const savedState = readEngineState();
+	if (savedState?.kind === "docker") {
+		p.intro("agentmemory stop");
+		p.log.error(legacyDockerStateMessage(savedState));
 		process.exit(1);
 	}
-	const ok = runCommand(dockerBin, [
-		"compose",
-		"-f",
-		composeFile,
-		"rm",
-		"-s",
-		"-f",
-		...ownServices
-	], { label: `docker compose -f ${composeFile} rm -s -f ${ownServices.join(" ")}` });
-	if (workerStopped) clearWorkerPidfile();
-	if (ok) {
-		clearEnginePidfile();
-		clearEngineState();
-	} else {
-		p.log.error(`docker compose rm failed. The engine may still be running on :${port}. Inspect with:\n  docker compose -f ${composeFile} 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);
 	}
-	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}.`);
-			clearEnginePidfile();
-			clearEngineState();
-			clearWorkerPidfile();
-			p.outro("Nothing to stop.");
-			return;
+	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);
 		}
-		await stopDockerEngine(state.composeFile, port);
+		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);
@@ -2737,7 +4353,7 @@ async function runStop() {
 		if (workerPid !== null && portPids.length === 0 && pidfilePid === null) {
 			const s = p.spinner();
 			s.start(`Stopping orphaned agentmemory worker (pid ${workerPid})...`);
-			const ok = await signalAndWait(workerPid, "SIGTERM", 3e3);
+			const ok = await signalAndWait(workerPid, "SIGTERM", SHUTDOWN_HARD_EXIT_MS + 1e3);
 			s.stop(ok ? `Stopped worker pid ${workerPid}` : `Failed to stop worker pid ${workerPid}`);
 			clearEnginePidfile();
 			clearEngineState();
@@ -2756,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);
@@ -2774,7 +4382,8 @@ async function runStop() {
 		process.exit(1);
 	}
 	let allStopped = true;
-	for (const pid of workerCandidates) if (!await stopWorkerPid(pid, 5e3)) allStopped = false;
+	for (const pid of workerCandidates) if (!await stopWorkerPid(pid, 9e3)) allStopped = false;
+	if (workerCandidates.size > 0 && [...candidates].some((pid) => !workerCandidates.has(pid))) await waitForEngineFlush();
 	const skippedForeign = [];
 	for (const pid of candidates) {
 		if (workerCandidates.has(pid)) continue;
@@ -2797,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) {
@@ -2807,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-BqNJDJ04.mjs");
+	await import("./standalone-BlqshyZ5.mjs");
 }
 async function runConnectCmd() {
-	const { runConnect } = await import("./connect-Qaeq15TQ.mjs").then((n) => n.n);
+	const { runConnect } = await import("./connect-BSLIAMpw.mjs").then((n) => n.n);
 	await runConnect(args.slice(1));
 }
 async function runImportJsonl() {
@@ -2867,11 +4476,12 @@ async function runImportJsonl() {
 		process.exit(1);
 	}
 	const body = {};
-	if (pathArg) body["path"] = pathArg;
+	if (pathArg) body["path"] = resolve(pathArg.startsWith("~") ? join(homedir(), pathArg.slice(1)) : pathArg);
 	if (maxFiles !== void 0) body["maxFiles"] = maxFiles;
-	const headers = { "content-type": "application/json" };
-	const secret = process.env["AGENTMEMORY_SECRET"];
-	if (secret) headers["authorization"] = `Bearer ${secret}`;
+	const headers = {
+		"content-type": "application/json",
+		...bearerHeaders(base)
+	};
 	p.log.info(`Importing JSONL from ${pathArg || "~/.claude/projects"}…`);
 	const spinner = p.spinner();
 	spinner.start("scanning files");
@@ -2958,20 +4568,39 @@ function safeDelete(path) {
 	}
 }
 async function runRemove() {
+	if (selectedInstance !== 0) {
+		p.intro("agentmemory remove");
+		p.log.error(`remove is a global uninstall and cannot target instance ${selectedInstance}. Stop that daemon with \`agentmemory stop --instance ${selectedInstance}\`, then run \`agentmemory remove\` without --instance when you intend to uninstall shared assets.`);
+		process.exit(1);
+	}
+	await assertRuntimePortOwnership();
 	p.intro("agentmemory remove");
 	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") {
+		p.log.error(legacyDockerStateMessage(ownedState));
+		process.exit(1);
+	}
 	const home = homedir();
 	const connectManifest = loadConnectManifest(home);
+	const localBinIiiVersion = probeLocalBinIiiVersion(home);
+	const options = {
+		force,
+		keepData
+	};
 	const plan = buildRemovePlan({
 		home,
+		runtimeDir: dirname(engineStatePath()),
+		dataDir: dataDirResolution.dataDir,
 		pinnedVersion: IIPINNED_VERSION,
-		localBinIiiVersion: probeLocalBinIiiVersion(home),
+		localBinIiiVersion,
 		connectManifest
-	}, {
-		force,
-		keepData
-	});
+	}, options);
 	if (plan.filter((it) => it.applicable).length === 0) {
 		p.outro("Nothing to remove. agentmemory is already gone.");
 		return;
@@ -3008,19 +4637,12 @@ async function runRemove() {
 			}
 		}
 		if (item.id === "stop-engine") {
-			try {
-				const portPids = findEnginePidsByPort(getRestPort());
-				const pidfilePid = readEnginePidfile();
-				const cands = /* @__PURE__ */ new Set();
-				if (pidfilePid) cands.add(pidfilePid);
-				for (const pid of portPids) cands.add(pid);
-				for (const pid of cands) await signalAndWait(pid, "SIGTERM", 3e3);
-				clearEnginePidfile();
-				clearEngineState();
-				p.log.success(cands.size > 0 ? `stopped engine (${cands.size} pid${cands.size === 1 ? "" : "s"})` : "no engine running");
-			} catch (err) {
-				p.log.warn(`engine stop best-effort: ${err instanceof Error ? err.message : String(err)}`);
+			const stopped = await stopNativeEngineForRemoval();
+			if (!stopped.ok) {
+				p.log.error(`Removal aborted: ${stopped.reason}.`);
+				process.exit(1);
 			}
+			p.log.success(stopped.stoppedEnginePids > 0 ? `stopped engine (${stopped.stoppedEnginePids} pid${stopped.stoppedEnginePids === 1 ? "" : "s"})` : "no engine running");
 			continue;
 		}
 		if (!item.path) continue;
@@ -3030,26 +4652,65 @@ async function runRemove() {
 	}
 	p.outro("Done. agentmemory cleanly removed. The npm package itself: npm uninstall -g @agentmemory/agentmemory");
 }
+async function runConsole() {
+	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({
+		base: getBaseUrl(),
+		args: args.slice(1),
+		secret: resolveClientSecret(getBaseUrl())
+	});
+	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,
 	status: runStatus,
+	console: runConsole,
 	doctor: runDoctor,
 	demo: runDemo,
 	upgrade: runUpgrade,
 	stop: runStop,
 	remove: runRemove,
 	mcp: runMcp,
-	"import-jsonl": runImportJsonl
+	"import-jsonl": runImportJsonl,
+	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 };