@agentmemory/agentmemory 0.9.28 → 0.9.30

package/dist/cli.mjs

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-import { a as runAdapter, i as resolveAdapter, r as knownAgents, t as ADAPTERS } from "./connect-JnsJXc68.mjs";
-import { i as generateId } from "./schema-CNiCWzV9.mjs";
-import { r as setBootVerbose } from "./logger-BEB7pCI9.mjs";
-import { i as VERSION, n as getAllTools, t as ESSENTIAL_TOOLS } from "./tools-registry-D3NEoe5m.mjs";
+import { a as runAdapter, i as resolveAdapter, r as knownAgents, t as ADAPTERS } from "./connect-B4_ca6BD.mjs";
+import { o as generateId } from "./keyed-mutex-DchXsyfP.mjs";
+import { I as hydrateProcessEnvFromFile, M as getStateSaveIntervalMs, O as getRedisUrl, _ as VERSION, at as isBundledConfig, ct as resolveEngineCwd, dt as runtimeConfigPath, g as III_PINNED_VERSION, gt as renderEngineConfig, ht as engineStateConfigPaths, i as resolveClientSecret, it as engineChildEnv, j as getStateBackend, lt as resolveLaunchRenderFailure, m as getAllTools, mt as engineFlushWaitMs, nt as dockerComposeArgs, ot as legacyDataMigrations, p as ESSENTIAL_TOOLS, pt as clearPersistedBuiltinConfig, rt as dockerProjectName, st as redactCredentialUrls, t as bearerHeaders, tt as setBootVerbose, ut as rewriteBundledConfig } from "./secret-store-BnY3A50C.mjs";
+import { A as SHUTDOWN_HARD_EXIT_MS, C as spoolSummary, M as runtimeMetadataPath, O as resolveDataDir, _ as drainSpool, b as retainSent, t as CURL_AUTH_HEADER, v as parseSentMark } from "./status-IRz7ta8-.mjs";
 import { 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, join } from "node:path";
+import { appendFileSync, closeSync, constants, cpSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { delimiter, dirname, join, resolve } from "node:path";
 import { 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";
 //#region src/cli/doctor-diagnostics.ts
 /** Common placeholder values shipped in .env.example. */
@@ -225,11 +226,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 enginePath(home) {
-	return join(home, ".agentmemory", "engine-state.json");
+function workerPidfilePath$1(runtimeDir) {
+	return join(runtimeDir, "worker.pid");
+}
+function enginePath(runtimeDir) {
+	return join(runtimeDir, "engine-state.json");
 }
 function envPath(home) {
 	return join(home, ".agentmemory", ".env");
@@ -240,9 +244,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 +275,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 +333,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 +372,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 +394,197 @@ 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}`;
+}
+const III_INSTALL_SPAWN_TIMEOUT_MS = 345 * 1e3;
+const III_RELEASE_SHA256 = { "0.22.1": {
+	"iii-aarch64-apple-darwin.tar.gz": "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4",
+	"iii-x86_64-apple-darwin.tar.gz": "6d33940db2d3ad6a9aef9837aa5b89bf5c5e4acd0679e8178fec258af229d7e1",
+	"iii-x86_64-unknown-linux-gnu.tar.gz": "34d4bd2ec1873e6114bb836be7db9cb3f410d0d63353d240917f0bc9c30df13b",
+	"iii-aarch64-unknown-linux-gnu.tar.gz": "87efc60210c1580ef2e11b13c679a4dad91917a9d80f737c5ba7e3475b3ca413",
+	"iii-armv7-unknown-linux-gnueabihf.tar.gz": "af5dfc45149678c647e5adaca55c055428eebfa73d65884b052c30c98abcfd19",
+	"iii-x86_64-pc-windows-msvc.zip": "d862bf7cf1e864f3290c8a6fc17c308c6ecac097cb2666e4a739efc0040aae96",
+	"iii-aarch64-pc-windows-msvc.zip": "4777a48cee3fc1a742daee929e3d943df09e4ddd3357d27a33d31c9dc9e520ac"
+} };
+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/console.ts
+const GLOBAL_VALUE_FLAGS = new Set([
+	"--port",
+	"--instance",
+	"--data-dir",
+	"--tools"
+]);
+const GLOBAL_BOOLEAN_FLAGS = new Set([
+	"--verbose",
+	"-v",
+	"--no-engine"
+]);
+function defaultConsolePort(viewerPort) {
+	return viewerPort + 1;
+}
+function readPort(raw, flag) {
+	const port = raw === void 0 ? NaN : Number(raw);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`${flag} needs a port between 1 and 65535`);
+	return port;
+}
+function parseConsoleArgs(tail, fallbackPort) {
+	let consolePort = fallbackPort;
+	const extraArgs = [];
+	for (let i = 0; i < tail.length; i++) {
+		const arg = tail[i];
+		if (arg === "--console-port") {
+			consolePort = readPort(tail[i + 1], arg);
+			i++;
+			continue;
+		}
+		if (arg.startsWith("--console-port=")) {
+			consolePort = readPort(arg.slice(15), "--console-port");
+			continue;
+		}
+		if (GLOBAL_VALUE_FLAGS.has(arg)) {
+			i++;
+			continue;
+		}
+		if ([...GLOBAL_VALUE_FLAGS].some((flag) => arg.startsWith(`${flag}=`))) continue;
+		if (GLOBAL_BOOLEAN_FLAGS.has(arg)) continue;
+		extraArgs.push(arg);
+	}
+	return {
+		consolePort,
+		extraArgs
+	};
+}
+function consoleArgs(launch) {
+	return [
+		"console",
+		"--port",
+		String(launch.consolePort),
+		"--engine-port",
+		String(launch.restPort),
+		"--ws-port",
+		String(launch.streamPort),
+		"--bridge-port",
+		String(launch.enginePort),
+		...launch.extraArgs
+	];
+}
+//#endregion
+//#region src/cli/process-state.ts
+function processStatIsRunning(stat) {
+	return !stat.trimStart().startsWith("Z");
+}
+//#endregion
 //#region src/cli/splash.ts
 const IS_COLOR_TTY = !!process.stdout.isTTY && !process.env["NO_COLOR"];
 function accent(s) {
@@ -436,7 +644,6 @@ const DEFAULTS = {
 	skipSplash: false,
 	skipNpxHint: false,
 	skipGlobalInstall: false,
-	skipConsoleInstall: false,
 	firstRunAt: null,
 	injectContextChosen: false
 };
@@ -525,7 +732,7 @@ const PROVIDERS = [
 	},
 	{
 		value: "minimax",
-		label: "MiniMax — minimax-m1",
+		label: "MiniMax — MiniMax-M3",
 		envKey: "MINIMAX_API_KEY"
 	},
 	{
@@ -765,6 +972,86 @@ async function wireSelectedAgents(agents) {
 	p.note(summary.join("\n"), "wire summary");
 }
 //#endregion
+//#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.ts
 const c = {
 	url: pc.cyan,
@@ -784,11 +1071,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();
 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;
@@ -836,6 +1126,8 @@ Commands:
                      No arg = interactive picker. --all wires every detected agent.
                      --dry-run shows what would change. --force re-installs.
   status             Show connection status, memory count, flags, and health
+  console            Launch the iii web console for this engine (workers, functions,
+                     triggers, queues, traces). --console-port N, default viewer+1
   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
@@ -851,6 +1143,9 @@ Commands:
                      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.
   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)
@@ -867,13 +1162,18 @@ Options:
   --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)
+  --data-dir <path>  Store iii-engine state outside the current repo
 
 Environment:
   AGENTMEMORY_URL              Full REST base URL (e.g. http://localhost:3111).
                                Honored by status, doctor, and MCP shim commands.
+  AGENTMEMORY_DATA_DIR         State directory fallback when --data-dir is not set.
   AGENTMEMORY_USE_DOCKER=1     Prefer the bundled docker-compose path over the
                                native iii-engine binary on first run.
   AGENTMEMORY_III_VERSION      Override pinned iii-engine version (default ${IIPINNED_VERSION}).
+  AGENTMEMORY_III_CONFIG       Engine config to start from (default: ./iii-config.yaml,
+                               then ~/.agentmemory/iii-config.yaml, then the bundled
+                               loopback-only config).
   AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS
                                Window (seconds) for the smart-search follow-up diagnostic
                                (default 30). Long values overcount, short values undercount.
@@ -895,19 +1195,62 @@ 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"
+]);
+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_STREAM_PORT"] ??= process.env["III_STREAMS_PORT"] ?? String(restPort + 1);
+	process.env["III_VIEWER_PORT"] ??= String(restPort + 2);
+	const configuredEngineUrl = process.env["III_ENGINE_URL"];
+	if (configuredEngineUrl) try {
+		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 });
+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);
@@ -915,10 +1258,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;
@@ -941,23 +1287,23 @@ 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() {
@@ -996,9 +1342,21 @@ function findIiiConfig() {
 		join(__dirname, "iii-config.yaml"),
 		join(__dirname, "..", "iii-config.yaml")
 	];
-	for (const c of candidates) if (existsSync(c)) return c;
+	for (const c of candidates) if (existsSync(c)) return resolve(c);
 	return "";
 }
+function warnIfRelocatedDataDir() {
+	if (!dataDirResolution.relocatedFrom) return;
+	try {
+		mkdirSync(dataDirResolution.dataDir, { recursive: true });
+		const marker = join(dataDirResolution.dataDir, ".cwd-relocation-warning");
+		if (existsSync(marker)) return;
+		p.log.warn(`Default data dir ${dataDirResolution.relocatedFrom} is inside a git worktree; using ${dataDirResolution.dataDir} instead.`);
+		writeFileSync(marker, (/* @__PURE__ */ new Date()).toISOString());
+	} catch {
+		p.log.warn(`Default data dir ${dataDirResolution.relocatedFrom} is inside a git worktree; using ${dataDirResolution.dataDir} instead.`);
+	}
+}
 function whichBinary(name) {
 	const cmd = IS_WINDOWS ? "where" : "which";
 	try {
@@ -1068,10 +1426,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");
+	return runtimeMetadataPath("engine-state.json");
 }
 function writeEnginePidfile(pid) {
 	try {
@@ -1097,7 +1455,7 @@ function clearEnginePidfile() {
 	} catch {}
 }
 function workerPidfilePath() {
-	return join(homedir(), ".agentmemory", "worker.pid");
+	return runtimeMetadataPath("worker.pid");
 }
 function readWorkerPidfile() {
 	try {
@@ -1117,7 +1475,15 @@ function writeEngineState(state) {
 	try {
 		const statePath = engineStatePath();
 		mkdirSync(dirname(statePath), { recursive: true });
-		writeFileSync(statePath, `${JSON.stringify(state)}\n`, { encoding: "utf-8" });
+		const normalized = state.kind === "docker" && state.schemaVersion === 2 ? {
+			...state,
+			restPort: state.restPort ?? getRestPort(),
+			dataDir: state.dataDir ?? dataDirResolution.dataDir
+		} : {
+			...state,
+			restPort: state.restPort ?? getRestPort()
+		};
+		writeFileSync(statePath, `${JSON.stringify(normalized)}\n`, { encoding: "utf-8" });
 	} catch (err) {
 		vlog(`writeEngineState: ${err instanceof Error ? err.message : String(err)}`);
 	}
@@ -1137,6 +1503,44 @@ function clearEngineState() {
 		unlinkSync(engineStatePath());
 	} catch {}
 }
+function engineStateRestPort(state) {
+	if (state.restPort && Number.isFinite(state.restPort)) return state.restPort;
+	if (state.kind === "docker") {
+		const projectPort = state.projectName?.match(/^agentmemory-(\d+)$/)?.[1];
+		if (projectPort) return parseInt(projectPort, 10);
+		return 3111;
+	}
+	try {
+		const configuredPort = (readFileSync(state.configPath, "utf-8").match(/- name:\s*(?:iii-)?http([\s\S]*?)(?=\n\s*- name:|$)/)?.[1])?.match(/\n\s*port:\s*(\d+)/)?.[1];
+		if (configuredPort) return parseInt(configuredPort, 10);
+	} catch {}
+	return 3111;
+}
+async function startWorkerForEngineState() {
+	const workerPid = readWorkerPidfile();
+	if (workerPid && pidAlive(workerPid)) return;
+	if (configuredEngineMayStartWorker() && await waitForConfiguredWorker(5e3)) return;
+	await import("./src-Jsq9LCeH.mjs");
+}
+function configuredEngineMayStartWorker() {
+	const state = readEngineState();
+	if (state?.kind !== "native") return false;
+	try {
+		return readFileSync(state.configPath, "utf-8").includes("- name: iii-exec");
+	} catch {
+		return false;
+	}
+}
+async function waitForConfiguredWorker(timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const workerPid = readWorkerPidfile();
+		if (workerPid && pidAlive(workerPid)) return true;
+		if (await isAgentmemoryReady()) return true;
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+	return false;
+}
 function discoverComposeFile() {
 	return [
 		join(__dirname, "..", "docker-compose.yml"),
@@ -1144,6 +1548,251 @@ function discoverComposeFile() {
 		join(process.cwd(), "docker-compose.yml")
 	].find((c) => existsSync(c)) ?? null;
 }
+function sameDockerMountSource(type, left, right) {
+	return type === "bind" ? resolve(left) === resolve(right) : left === right;
+}
+function inspectDockerContainer(dockerBin, containerId, state, ownerPort) {
+	const result = spawnSync(dockerBin, ["inspect", containerId], {
+		encoding: "utf-8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		],
+		maxBuffer: 1024 * 1024
+	});
+	if (result.status !== 0) return {
+		status: "unavailable",
+		reason: `docker inspect failed for ${containerId}`
+	};
+	let record;
+	try {
+		record = JSON.parse(result.stdout)[0] ?? {};
+	} catch {
+		return {
+			status: "unavailable",
+			reason: `docker inspect returned invalid JSON for ${containerId}`
+		};
+	}
+	const image = record.Config?.Image ?? "";
+	const expectedImage = `iiidev/iii:${state.engineVersion ?? IIPINNED_VERSION}`;
+	if (image !== expectedImage) return {
+		status: "unavailable",
+		reason: `saved container uses ${image || "an unknown image"}, expected ${expectedImage}`
+	};
+	const labels = record.Config?.Labels ?? {};
+	const projectName = labels["com.docker.compose.project"] ?? "";
+	if (labels["com.docker.compose.service"] !== "iii-engine" || !projectName) return {
+		status: "unavailable",
+		reason: "saved container is not the iii-engine service of a Compose project"
+	};
+	if (state.projectName && state.projectName !== projectName) return {
+		status: "unavailable",
+		reason: `saved Docker project ${state.projectName} does not match container project ${projectName}`
+	};
+	if (state.schemaVersion === 2 && projectName !== dockerProjectName(ownerPort)) return {
+		status: "unavailable",
+		reason: `Docker project ${projectName} does not match REST port ${ownerPort}`
+	};
+	if (!(record.HostConfig?.PortBindings?.[`${ownerPort}/tcp`] ?? []).some((binding) => binding.HostPort === String(ownerPort))) return {
+		status: "unavailable",
+		reason: `saved container does not publish REST port ${ownerPort}`
+	};
+	const dataMount = record.Mounts?.find((mount) => mount.Destination === "/data");
+	const dataMountType = dataMount?.Type;
+	const dataMountSource = dataMountType === "volume" ? dataMount?.Name ?? dataMount?.Source ?? "" : dataMount?.Source ?? "";
+	if (dataMountType !== "bind" && dataMountType !== "volume" || !dataMountSource) return {
+		status: "unavailable",
+		reason: "saved container has no verifiable /data bind or volume mount"
+	};
+	if (state.dataMountType && state.dataMountType !== dataMountType) return {
+		status: "unavailable",
+		reason: `saved /data mount type ${state.dataMountType} changed to ${dataMountType}`
+	};
+	if (state.dataMountSource && !sameDockerMountSource(dataMountType, state.dataMountSource, dataMountSource)) return {
+		status: "unavailable",
+		reason: "saved container /data mount source changed"
+	};
+	if (!state.dataMountSource) {
+		if (dataMountType === "bind" && resolve(dataMountSource) !== resolve(dataDirResolution.dataDir)) return {
+			status: "unavailable",
+			reason: `container /data bind ${dataMountSource} does not match ${dataDirResolution.dataDir}`
+		};
+		if (dataMountType === "volume" && dataDirResolution.source !== "default") return {
+			status: "unavailable",
+			reason: "legacy container uses a named volume but this invocation selects an explicit data directory"
+		};
+	}
+	if (state.dataDir && resolve(state.dataDir) !== resolve(dataDirResolution.dataDir)) return {
+		status: "unavailable",
+		reason: `saved data directory ${state.dataDir} does not match ${dataDirResolution.dataDir}`
+	};
+	return {
+		status: record.State?.Running ? "running" : "stopped",
+		composeFile: existsSync(state.composeFile) ? state.composeFile : discoverComposeFile() ?? state.composeFile,
+		projectName,
+		containerId: record.Id ?? containerId,
+		dataMountType,
+		dataMountSource,
+		preserveContainer: state.preserveContainer === true || state.schemaVersion !== 2 && dataMountType === "volume"
+	};
+}
+function inspectOwnedDockerEngine(state) {
+	if (state.kind !== "docker") return {
+		status: "unavailable",
+		reason: "engine state is not Docker"
+	};
+	const ownerPort = engineStateRestPort(state);
+	if (state.schemaVersion === 2 && state.projectName !== dockerProjectName(ownerPort)) return {
+		status: "unavailable",
+		reason: `saved Docker project ${state.projectName} does not match REST port ${ownerPort}`
+	};
+	const dockerBin = whichBinary("docker");
+	if (!dockerBin) return {
+		status: "unavailable",
+		reason: "docker is not on PATH"
+	};
+	const discoveryFailures = [];
+	if (state.containerId) {
+		const direct = inspectDockerContainer(dockerBin, state.containerId, state, ownerPort);
+		if (direct.status !== "unavailable") return direct;
+		if (state.preserveContainer) return direct;
+		discoveryFailures.push(direct.reason);
+	}
+	const composeFile = existsSync(state.composeFile) ? state.composeFile : discoverComposeFile() ?? state.composeFile;
+	const candidateIds = /* @__PURE__ */ new Set();
+	try {
+		if (existsSync(composeFile)) {
+			const composeText = readFileSync(composeFile, "utf-8");
+			if (!/^\s+iii-engine:/m.test(composeText)) return {
+				status: "unavailable",
+				reason: `${composeFile} does not define iii-engine`
+			};
+			const psResult = spawnSync(dockerBin, dockerComposeArgs(composeFile, state.projectName, [
+				"ps",
+				"-q",
+				"--all",
+				"iii-engine"
+			]), {
+				encoding: "utf-8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			});
+			if (psResult.status === 0) {
+				for (const id of (psResult.stdout ?? "").trim().split(/\s+/)) if (id) candidateIds.add(id);
+			} else discoveryFailures.push(`docker compose ps failed for project ${state.projectName ?? "<default>"}`);
+		}
+		const scanResult = spawnSync(dockerBin, [
+			"ps",
+			"-aq",
+			"--filter",
+			"label=com.docker.compose.service=iii-engine",
+			"--filter",
+			`ancestor=iiidev/iii:${state.engineVersion ?? IIPINNED_VERSION}`,
+			...state.projectName ? ["--filter", `label=com.docker.compose.project=${state.projectName}`] : []
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+		if (scanResult.status === 0) {
+			for (const id of (scanResult.stdout ?? "").trim().split(/\s+/)) if (id) candidateIds.add(id);
+		} else discoveryFailures.push("docker container scan failed");
+		const matches = [];
+		for (const containerId of candidateIds) {
+			const inspected = inspectDockerContainer(dockerBin, containerId, state, ownerPort);
+			if (inspected.status === "running" || inspected.status === "stopped") {
+				if (!matches.some((match) => (match.status === "running" || match.status === "stopped") && match.containerId === inspected.containerId)) matches.push(inspected);
+			} else if (inspected.status === "unavailable") discoveryFailures.push(inspected.reason);
+		}
+		if (matches.length === 1) return matches[0];
+		if (matches.length > 1) return {
+			status: "unavailable",
+			reason: `multiple Docker iii-engine containers match REST port ${ownerPort}`
+		};
+		if (discoveryFailures.length > 0) return {
+			status: "unavailable",
+			reason: [...new Set(discoveryFailures)].join("; ")
+		};
+		if (state.schemaVersion !== 2 || state.preserveContainer) return {
+			status: "unavailable",
+			reason: `legacy Docker ownership exists for REST port ${ownerPort}, but no unique container can be verified`
+		};
+		return {
+			status: "missing",
+			composeFile,
+			projectName: state.projectName
+		};
+	} catch (err) {
+		return {
+			status: "unavailable",
+			reason: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+function persistDockerInspection(state, inspection) {
+	if (inspection.status !== "running" && inspection.status !== "stopped") return state;
+	const resolved = {
+		...state,
+		composeFile: inspection.composeFile,
+		projectName: inspection.projectName,
+		containerId: inspection.containerId,
+		dataMountType: inspection.dataMountType,
+		dataMountSource: inspection.dataMountSource,
+		preserveContainer: inspection.preserveContainer
+	};
+	writeEngineState(resolved);
+	return resolved;
+}
+async function assertRuntimePortOwnership() {
+	const state = readEngineState();
+	if (!state) return;
+	const ownerPort = engineStateRestPort(state);
+	const requestedPort = getRestPort();
+	if (ownerPort === requestedPort) return;
+	if (state.kind === "docker") {
+		const inspection = inspectOwnedDockerEngine(state);
+		if (inspection.status === "unavailable") {
+			p.log.error(`The data directory contains Docker ownership for REST port ${ownerPort}, but it cannot be verified: ${inspection.reason}. Refusing to overwrite its lifecycle state.`);
+			process.exit(1);
+		}
+		if (inspection.status === "running" || inspection.status === "stopped") {
+			persistDockerInspection(state, inspection);
+			p.log.error(`The canonical lifecycle state is owned by a ${inspection.status} Docker engine on REST port ${ownerPort}. Refusing to reuse it for port ${requestedPort}. Use the original port, or use --instance <N> for an isolated daemon.`);
+			process.exit(1);
+		}
+		p.log.error(`The canonical lifecycle state still records a Docker engine for REST port ${ownerPort}, but its container is missing. Refusing to overwrite that ownership from port ${requestedPort}. Re-run \`agentmemory stop\` with the original port to reconcile it.`);
+		process.exit(1);
+	}
+	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 configureDockerHostUser() {
+	if (typeof process.getuid !== "function" || typeof process.getgid !== "function") return;
+	const hostUid = String(process.getuid());
+	const hostGid = String(process.getgid());
+	process.env["AGENTMEMORY_DOCKER_UID"] ??= hostUid;
+	process.env["AGENTMEMORY_DOCKER_GID"] ??= hostGid;
+	if (process.env["AGENTMEMORY_DOCKER_UID"] === hostUid && process.env["AGENTMEMORY_DOCKER_GID"] === hostGid) process.env["AGENTMEMORY_DOCKER_SKIP_CHOWN"] ??= "1";
+}
 function isInvokedViaNpx() {
 	if (process.env["npm_lifecycle_event"] === "npx") return true;
 	if ((process.argv[1] ?? "").includes("_npx")) return true;
@@ -1175,62 +1824,25 @@ async function maybeOfferGlobalInstall() {
 	if (runCommand(npmBin, [
 		"install",
 		"-g",
-		`@agentmemory/agentmemory@0.9.28`
-	], { label: `Installing @agentmemory/agentmemory@0.9.28 globally` })) {
+		`@agentmemory/agentmemory@0.9.30`
+	], { label: `Installing @agentmemory/agentmemory@0.9.30 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",
@@ -1254,7 +1866,7 @@ async function runIiiInstaller() {
 		};
 	}
 	if (IS_WINDOWS || isZipAsset) {
-		p.log.info(`Auto-install unavailable on ${platform()} — ${asset} isn't tar-compatible. Install manually:\n  1. Download ${releaseUrl}\n  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)\nOr use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`);
 		return {
 			ok: false,
 			binPath: null
@@ -1262,8 +1874,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
@@ -1271,28 +1889,68 @@ 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 + `Or use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`);
 		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(" ")}`);
+let activeStartupStderr = createStartupStderrCapture();
+function printCapturedStartupStderr() {
+	const stderr = redactCredentialUrls(activeStartupStderr.text().trim());
+	if (IS_VERBOSE && stderr) p.note(stderr, "engine stderr");
+}
+function printDockerStartupLogs() {
+	const state = readEngineState();
+	if (state?.kind !== "docker") return;
+	const inspection = inspectOwnedDockerEngine(state);
+	if (inspection.status !== "running" && inspection.status !== "stopped") return;
+	const dockerBin = whichBinary("docker");
+	if (!dockerBin) return;
+	const result = spawnSync(dockerBin, [
+		"logs",
+		"--tail",
+		"80",
+		inspection.containerId
+	], {
+		encoding: "utf-8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		timeout: 5e3,
+		maxBuffer: 64 * 1024
+	});
+	const output = redactCredentialUrls(`${result.stdout ?? ""}${result.stderr ?? ""}`.trim());
+	if (output) p.note(output.slice(-16 * 1024), "docker engine logs");
+}
+function spawnEngineBackground(bin, spawnArgs, label, cwd) {
+	vlog(`spawn: ${bin} ${spawnArgs.join(" ")}${cwd ? ` (cwd: ${cwd})` : ""}`);
+	activeStartupStderr = createStartupStderrCapture();
 	const child = spawn(bin, spawnArgs, {
 		detached: true,
 		stdio: [
@@ -1300,22 +1958,18 @@ function spawnEngineBackground(bin, spawnArgs, label) {
 			"ignore",
 			"pipe"
 		],
-		windowsHide: true
+		windowsHide: true,
+		env: engineChildEnv(process.env),
+		...cwd ? { cwd } : {}
 	});
 	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;
+		activeStartupStderr.append(chunk);
 	});
 	child.on("exit", (code, signal) => {
 		if (code !== null && code !== 0 || code === null && signal !== null) {
-			const stderr = Buffer.concat(stderrChunks).toString("utf-8");
+			const stderr = redactCredentialUrls(activeStartupStderr.text());
 			startupFailure = {
 				kind: isDocker ? "docker-crashed" : "engine-crashed",
 				stderr: stderr.trim() || (signal ? `process killed by signal ${signal}` : `process exited with code ${code}`),
@@ -1323,22 +1977,100 @@ function spawnEngineBackground(bin, spawnArgs, label) {
 			};
 			vlog(`engine exited early: code=${code} signal=${signal}`);
 			if (IS_VERBOSE && stderr.trim()) p.log.error(`engine stderr:\n${stderr}`);
-			if (!isDocker) clearEnginePidfile();
-			clearEngineState();
+			if (!isDocker) {
+				clearEnginePidfile();
+				clearEngineState();
+			}
 		}
 	});
 	child.unref();
 	return child;
 }
+function prepareEngineLaunch(configPath) {
+	const home = homedir();
+	const bundledConfig = isBundledConfig(configPath, __dirname);
+	const cwd = resolveEngineCwd(configPath, process.cwd(), home, bundledConfig);
+	const stateBackendKind = getStateBackend();
+	try {
+		mkdirSync(cwd, { recursive: true });
+	} catch (err) {
+		const failure = resolveLaunchRenderFailure(stateBackendKind, err);
+		if (failure.fatal) {
+			p.log.error(failure.message);
+			process.exit(1);
+		}
+		return {
+			configPath,
+			cwd: process.cwd()
+		};
+	}
+	try {
+		const rawConfig = readFileSync(configPath, "utf-8");
+		const options = {
+			dataDir: dataDirResolution.dataDir,
+			ports: {
+				restPort: getRestPort(),
+				streamPort: getStreamPort(),
+				viewerPort: getConfiguredViewerPort(),
+				enginePort: getEnginePort()
+			},
+			stateBackend: {
+				kind: stateBackendKind,
+				redisUrl: getRedisUrl()
+			},
+			saveIntervalMs: getStateSaveIntervalMs()
+		};
+		const rewritten = bundledConfig ? rewriteBundledConfig(rawConfig, home, process.execPath, join(__dirname, "index.mjs"), options) : renderEngineConfig(rawConfig, options);
+		const runtimePath = runtimeConfigPath(dataDirResolution.dataDir);
+		mkdirSync(dirname(runtimePath), { recursive: true });
+		writeFileSync(runtimePath, rewritten, "utf-8");
+		try {
+			const cleared = clearPersistedBuiltinConfig(cwd, runtimePath, rewritten);
+			if (cleared.length > 0) vlog(`cleared ${cleared.length} persisted builtin config entries so the rendered runtime config seeds the engine again`);
+		} catch (err) {
+			p.log.error(`${String(err instanceof Error ? err.message : err)}. The engine would ignore the rendered runtime config and keep its previously persisted ports and timeouts. Fix the permissions on that file and run agentmemory start again.`);
+			process.exit(1);
+		}
+		if (selectedInstance === 0 && dataDirResolution.source === "default") {
+			for (const m of legacyDataMigrations(process.cwd(), home, dataDirResolution.dataDir)) if (existsSync(m.from) && !existsSync(m.to)) try {
+				mkdirSync(dirname(m.to), { recursive: true });
+				cpSync(m.from, m.to, { recursive: true });
+				p.log.info(`Copied existing data: ${m.from} -> ${m.to}`);
+			} catch (err) {
+				vlog(`data copy failed for ${m.from}: ${String(err)}`);
+			}
+		}
+		return {
+			configPath: runtimePath,
+			cwd
+		};
+	} catch (err) {
+		const failure = resolveLaunchRenderFailure(stateBackendKind, err);
+		if (failure.fatal) {
+			p.log.error(failure.message);
+			process.exit(1);
+		}
+		vlog(`runtime config generation failed, using bundled config verbatim: ${String(err)}`);
+		return {
+			configPath,
+			cwd
+		};
+	}
+}
 function startIiiBin(iiiBin, configPath) {
 	const s = p.spinner();
 	s.start(`Starting iii-engine: ${iiiBin}`);
+	const launch = prepareEngineLaunch(configPath);
 	writeEngineState({
 		kind: "native",
-		configPath,
+		configPath: launch.configPath,
 		binPath: iiiBin
 	});
-	spawnEngineBackground(iiiBin, ["--config", configPath], "iii-engine");
+	spawnEngineBackground(iiiBin, [
+		"--config",
+		launch.configPath,
+		"--no-update-check"
+	], "iii-engine", launch.cwd);
 	s.stop(c.ok("iii-engine process started"));
 	return true;
 }
@@ -1350,14 +2082,52 @@ function pickCompatibleIii(candidates) {
 	}
 	return null;
 }
+function warnIfDockerIgnoresStateBackend(stateBackendKind) {
+	if (stateBackendKind !== "redis") return;
+	p.log.warn("AGENTMEMORY_STATE_BACKEND=redis is not applied on the Docker path: docker-compose.yml mounts iii-config.docker.yaml read-only, so this start will not render it. Edit iii-config.docker.yaml by hand to point iii-state/iii-stream at redis (see README \"Storage backend\"), or it keeps using the file store. docker-compose.yml passes AGENTMEMORY_REDIS_URL into the engine container, so redis_url: '${AGENTMEMORY_REDIS_URL}' works in that file.");
+}
 async function startEngine() {
+	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);
+	}
+	await assertRuntimePortOwnership();
+	const persistedState = readEngineState();
+	if (persistedState?.kind === "docker") {
+		warnIfDockerIgnoresStateBackend(stateBackendKind);
+		const inspection = inspectOwnedDockerEngine(persistedState);
+		if (inspection.status === "unavailable" || inspection.status === "missing") {
+			const detail = inspection.status === "unavailable" ? inspection.reason : "container is missing";
+			p.log.error(`A saved Docker engine owns this lifecycle state, but it cannot be resumed safely (${detail}). Run \`agentmemory stop\` to reconcile that project before starting another engine.`);
+			return false;
+		}
+		persistDockerInspection(persistedState, inspection);
+		if (inspection.status === "running") return true;
+		const dockerBin = whichBinary("docker");
+		return Boolean(dockerBin && runCommand(dockerBin, ["start", inspection.containerId], { label: `Restarting owned Docker container ${inspection.containerId}` }));
+	}
 	const configPath = findIiiConfig();
+	warnIfRelocatedDataDir();
 	const pathIii = whichBinary("iii");
 	vlog(`iii binary: ${pathIii ?? "(not on PATH)"}, config: ${configPath || "(not found)"}`);
+	const dockerBin = whichBinary("docker");
+	const composeFile = [
+		join(__dirname, "..", "docker-compose.yml"),
+		join(__dirname, "docker-compose.yml"),
+		join(process.cwd(), "docker-compose.yml")
+	].find((c) => existsSync(c));
+	const dockerOptIn = process.env["AGENTMEMORY_USE_DOCKER"] === "1" || process.env["AGENTMEMORY_USE_DOCKER"] === "true";
 	const fallbacks = fallbackIiiPaths().filter((p) => existsSync(p));
 	for (const f of fallbacks) vlog(`fallback iii at ${f} reports version: ${iiiBinVersion(f) ?? "unknown"}`);
 	let iiiBin = pickCompatibleIii([pathIii, ...fallbacks]);
-	if (iiiBin && configPath) {
+	if (iiiBin && configPath && !(dockerOptIn && dockerBin && composeFile)) {
 		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"] ?? ""}`;
@@ -1369,15 +2139,9 @@ async function startEngine() {
 		startupFailure = { kind: "no-engine" };
 		return false;
 	}
-	const dockerBin = whichBinary("docker");
 	vlog(`docker binary: ${dockerBin ?? "(not on PATH)"}`);
-	const composeFile = [
-		join(__dirname, "..", "docker-compose.yml"),
-		join(__dirname, "docker-compose.yml"),
-		join(process.cwd(), "docker-compose.yml")
-	].find((c) => existsSync(c));
+	mkdirSync(dataDirResolution.dataDir, { recursive: true });
 	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;
@@ -1443,19 +2207,22 @@ async function startEngine() {
 		}
 	}
 	if (choice === "docker" && dockerBin && composeFile) {
+		warnIfDockerIgnoresStateBackend(stateBackendKind);
 		const s = p.spinner();
 		s.start("Starting iii-engine via Docker...");
+		configureDockerHostUser();
+		const projectName = dockerProjectName(getRestPort());
 		writeEngineState({
 			kind: "docker",
-			composeFile
-		});
-		spawnEngineBackground(dockerBin, [
-			"compose",
-			"-f",
+			schemaVersion: 2,
 			composeFile,
-			"up",
-			"-d"
-		], "iii-engine via Docker");
+			projectName,
+			engineVersion: IIPINNED_VERSION,
+			dataMountType: "bind",
+			dataMountSource: dataDirResolution.dataDir,
+			preserveContainer: false
+		});
+		spawnEngineBackground(dockerBin, dockerComposeArgs(composeFile, projectName, ["up", "-d"]), "iii-engine via Docker");
 		s.stop("Docker compose started");
 		return true;
 	}
@@ -1471,25 +2238,65 @@ async function waitForEngine(timeoutMs) {
 	}
 	return false;
 }
+async function reconcilePersistedDockerEngine() {
+	const state = readEngineState();
+	if (state?.kind !== "docker") return false;
+	const inspection = inspectOwnedDockerEngine(state);
+	if (inspection.status === "unavailable") {
+		p.log.error(`The saved Docker engine cannot be verified: ${inspection.reason}. Refusing to overwrite its lifecycle state. Run \`agentmemory stop\` after restoring Docker/compose access.`);
+		process.exit(1);
+	}
+	if (inspection.status === "missing") {
+		p.log.error("The saved Docker project no longer has an iii-engine container. Run `agentmemory stop` to remove its stale project state, then start agentmemory again.");
+		process.exit(1);
+	}
+	persistDockerInspection(state, inspection);
+	if (inspection.status === "stopped") {
+		const dockerBin = whichBinary("docker");
+		if (!dockerBin || !runCommand(dockerBin, ["start", inspection.containerId], { label: `Restarting owned Docker container ${inspection.containerId}` })) {
+			p.log.error("The owned Docker container could not be restarted; lifecycle state was preserved.");
+			process.exit(1);
+		}
+	}
+	if (!await waitForEngine(5e3)) {
+		printDockerStartupLogs();
+		p.log.error(`The owned Docker container is running, but its REST API on port ${getRestPort()} is unhealthy. The saved project was preserved; inspect the Docker logs above or run \`agentmemory stop\`.`);
+		process.exit(1);
+	}
+	await startWorkerForEngineState();
+	if (!await waitForAgentmemoryReady(15e3)) {
+		p.log.error("agentmemory worker did not become ready within 15s.");
+		process.exit(1);
+	}
+	await maybeOfferGlobalInstall();
+	printReadyHint();
+	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",
+			"",
+			`  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) ${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:`,
 		"",
@@ -1516,7 +2323,8 @@ async function waitForAgentmemoryReady(timeoutMs) {
 	return false;
 }
 function getEngineHost() {
-	for (const envKey of ["III_ENGINE_URL", "AGENTMEMORY_URL"]) {
+	const envKeys = shouldUseAgentmemoryUrl() ? ["III_ENGINE_URL", "AGENTMEMORY_URL"] : ["III_ENGINE_URL"];
+	for (const envKey of envKeys) {
 		const raw = process.env[envKey];
 		if (!raw) continue;
 		try {
@@ -1526,13 +2334,16 @@ function getEngineHost() {
 	}
 	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 invocation = isInvokedViaNpx() ? "npx @agentmemory/agentmemory" : "agentmemory";
+	const consolePort = defaultConsolePort(getConfiguredViewerPort());
+	const portFlags = portFlagSuffix(getRestPort(), selectedInstance);
+	const consoleLine = `${c.label("iii console")}  ${c.cmd(`${invocation} console${portFlags}`)}  ${c.dim(`(serves on :${consolePort}; first run downloads the console next to the pinned iii)`)}`;
 	const lines = [
 		`${c.label("REST API")}     ${c.url(restUrl)}`,
 		`${c.label("Viewer")}       ${c.url(viewerUrl)}`,
@@ -1541,10 +2352,17 @@ function printReadyHint(consoleState) {
 		consoleLine
 	];
 	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 main() {
+	await assertRuntimePortOwnership();
+	try {
+		if ((await fetch(`${getBaseUrl()}/agentmemory/livez`, { signal: AbortSignal.timeout(1500) })).ok) {
+			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 {}
 	if (IS_RESET) resetPrefs();
 	const firstRun = isFirstRun();
 	const prefs = readPrefs();
@@ -1552,14 +2370,14 @@ async function main() {
 	if (firstRun || IS_RESET) await runOnboarding();
 	if (skipEngine) {
 		if (IS_VERBOSE) p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-CzgoepGU.mjs");
+		await import("./src-Jsq9LCeH.mjs");
 		if (await waitForAgentmemoryReady(15e3)) {
-			const consoleState = await ensureIiiConsole();
 			await maybeOfferGlobalInstall();
-			printReadyHint(consoleState);
+			printReadyHint();
 		}
 		return;
 	}
+	if (await reconcilePersistedDockerEngine()) return;
 	if (await isEngineRunning()) {
 		if (IS_VERBOSE) p.log.success("iii-engine is running");
 		const persisted = readEngineState();
@@ -1567,12 +2385,13 @@ async function main() {
 		const detected = attachedBin ? iiiBinVersion(attachedBin) : null;
 		if (detected === IIPINNED_VERSION) {
 			adoptRunningEngine();
-			await import("./src-CzgoepGU.mjs");
-			if (await waitForAgentmemoryReady(15e3)) {
-				const consoleState = await ensureIiiConsole();
-				await maybeOfferGlobalInstall();
-				printReadyHint(consoleState);
+			await startWorkerForEngineState();
+			if (!await waitForAgentmemoryReady(15e3)) {
+				p.log.error("agentmemory worker did not become ready within 15s.");
+				process.exit(1);
 			}
+			await maybeOfferGlobalInstall();
+			printReadyHint();
 			return;
 		}
 		const detectedLabel = detected ? `v${detected}` : "an unverified version";
@@ -1592,7 +2411,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);
@@ -1609,6 +2428,7 @@ async function main() {
 	if (!await waitForEngine(15e3)) {
 		const port = getRestPort();
 		s.stop("iii-engine did not become ready within 15s");
+		printDockerStartupLogs();
 		if (startupFailure?.kind === "engine-crashed" || startupFailure?.kind === "docker-crashed") {
 			p.log.error("The iii-engine process crashed on startup.");
 			if (startupFailure.binary) p.log.info(`Binary: ${startupFailure.binary}`);
@@ -1625,6 +2445,7 @@ async function main() {
 			].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),
@@ -1638,19 +2459,18 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop(c.ok("iii-engine is ready"));
-	await import("./src-CzgoepGU.mjs");
-	if (await waitForAgentmemoryReady(15e3)) {
-		const consoleState = await ensureIiiConsole();
-		await maybeOfferGlobalInstall();
-		printReadyHint(consoleState);
+	await startWorkerForEngineState();
+	if (!await waitForAgentmemoryReady(15e3)) {
+		p.log.error("agentmemory worker did not become ready within 15s.");
+		process.exit(1);
 	}
+	await maybeOfferGlobalInstall();
+	printReadyHint();
 	writePrefs({ skipSplash: true });
 }
 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
@@ -1939,7 +2759,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,
@@ -2153,7 +2973,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)
 		});
@@ -2166,7 +2989,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)
 	});
@@ -2201,7 +3027,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)
 			});
@@ -2273,6 +3102,7 @@ async function runInit() {
 	p.outro(`Edit ${target} and you're set.`);
 }
 async function startServerForDemo() {
+	await assertRuntimePortOwnership();
 	if (await isAgentmemoryReady()) return async () => {};
 	const startedEngine = !await isEngineRunning();
 	if (startedEngine) {
@@ -2282,11 +3112,13 @@ async function startServerForDemo() {
 			process.exit(1);
 		}
 		if (!await waitForEngine(15e3)) {
+			printCapturedStartupStderr();
+			printDockerStartupLogs();
 			p.log.error("iii-engine did not become ready within 15s.");
 			process.exit(1);
 		}
 	}
-	await import("./src-CzgoepGU.mjs");
+	await startWorkerForEngineState();
 	if (!await waitForAgentmemoryReady(15e3)) {
 		p.log.error("agentmemory worker did not become ready within 15s.");
 		process.exit(1);
@@ -2296,7 +3128,7 @@ async function startServerForDemo() {
 		const port = getRestPort();
 		const state = readEngineState();
 		if (state?.kind === "docker") {
-			await stopDockerEngine(state.composeFile, port).catch(() => {});
+			await stopDockerEngine(state, port).catch(() => {});
 			return;
 		}
 		const pids = new Set(findEnginePidsByPort(port));
@@ -2346,6 +3178,7 @@ async function runDemoBody(base) {
 	const results = [];
 	for (const query of queries) results.push(await runDemoSearch(base, query));
 	sQuery.stop("Search complete");
+	const semanticHits = results.find((r) => r.query === "database performance optimization")?.hits ?? 0;
 	const lines = [
 		`Project:       ${demoProject}`,
 		`Sessions:      ${sessions.length} seeded (${totalObs} observations)`,
@@ -2353,8 +3186,11 @@ async function runDemoBody(base) {
 		c.label("Search results:"),
 		...results.flatMap((r) => [`  ${c.label(`"${r.query}"`)}`, `    ${c.dim("→")} ${c.ok(`${r.hits} hit(s)`)}, top: ${r.topTitle.slice(0, 60)}`]),
 		"",
-		c.accent(`Notice: searching "database performance optimization"`),
-		c.accent(`found the N+1 query fix — keyword matching can't do that.`),
+		...semanticHits > 0 ? [c.accent(`Notice: searching "database performance optimization"`), c.accent(`found the N+1 query fix — keyword matching can't do that.`)] : [
+			c.dim(`Note: "database performance optimization" found nothing —`),
+			c.dim(`set EMBEDDING_PROVIDER=local for on-device semantic recall,`),
+			c.dim(`or add an embedding API key in ~/.agentmemory/.env.`)
+		],
 		"",
 		`Viewer:        ${c.url(getViewerUrl())}`,
 		`Clean up with: ${c.dim(`curl -X DELETE "${base}/agentmemory/sessions?project=${demoProject}"`)}`
@@ -2403,14 +3239,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.");
@@ -2442,6 +3286,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";
@@ -2476,6 +3336,95 @@ 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 {}
+	const runtimePath = runtimeConfigPath(dataDirResolution.dataDir);
+	const configTexts = [];
+	for (const path of engineStateConfigPaths(join(homedir(), ".agentmemory"), 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]`);
+	const ok = await signalAndWait(pid, "SIGTERM", 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 {
+		return execFileSync("ps", [
+			"-p",
+			String(pid),
+			"-o",
+			"comm="
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return "";
+	}
+}
+function isForeignPortHolder(comm) {
+	if (!comm) return false;
+	const base = comm.split("/").pop() || comm;
+	return base !== "iii" && !base.startsWith("iii-");
+}
 function findEnginePidsByPort(port) {
 	if (IS_WINDOWS) return [];
 	const lsof = whichBinary("lsof");
@@ -2500,47 +3449,80 @@ function findEnginePidsByPort(port) {
 		return [];
 	}
 }
-async function stopDockerEngine(composeFile, port) {
+async function stopDockerEngine(state, port, suppressOutro = false) {
 	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`);
+		p.log.error("Engine was started via Docker, but `docker` is no longer on PATH. Lifecycle state was preserved.");
 		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)`);
+	const inspection = inspectOwnedDockerEngine(state);
+	if (inspection.status === "unavailable") {
+		p.log.error(`The saved Docker engine cannot be verified: ${inspection.reason}. Refusing to stop or clear ownership state.`);
+		process.exit(1);
+	}
+	const resolvedState = persistDockerInspection(state, inspection);
+	const workerPid = readWorkerPidfile();
+	if (workerPid && !await stopWorkerPid(workerPid, 5e3)) {
+		p.log.error("The agentmemory worker could not be stopped; Docker ownership state was preserved.");
 		process.exit(1);
 	}
-	const ok = runCommand(dockerBin, [
-		"compose",
-		"-f",
-		composeFile,
-		"down"
-	], { label: `docker compose -f ${composeFile} down` });
-	clearEnginePidfile();
-	clearEngineState();
 	clearWorkerPidfile();
-	if (!ok) {
-		p.log.error(`docker compose down failed. The engine may still be running on :${port}. Inspect with:\n  docker compose -f ${composeFile} ps`);
+	if (inspection.status === "running" || inspection.status === "stopped") {
+		if (inspection.status === "running" && !runCommand(dockerBin, [
+			"stop",
+			"--time",
+			"10",
+			inspection.containerId
+		], { label: `Stopping preserved Docker container ${inspection.containerId}` })) {
+			p.log.error("The Docker container could not be stopped; ownership state was preserved.");
+			process.exit(1);
+		}
+		clearEnginePidfile();
+		writeEngineState(resolvedState);
+		if (!suppressOutro) p.outro("Stopped. The validated Docker container and data mount were preserved for a lossless restart.");
+		return;
+	}
+	const projectName = inspection.projectName ?? resolvedState.projectName;
+	if (!projectName) {
+		p.log.error("No verified Docker Compose project name is available. Refusing an unscoped stop.");
 		process.exit(1);
 	}
-	p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
+	const effectiveComposeFile = existsSync(inspection.composeFile) ? inspection.composeFile : discoverComposeFile();
+	if (!effectiveComposeFile) {
+		p.log.error("No agentmemory compose file is available. Docker ownership state was preserved.");
+		process.exit(1);
+	}
+	const composeText = readFileSync(effectiveComposeFile, "utf-8");
+	const ownServices = ["iii-engine", "iii-init"].filter((service) => new RegExp(`^\\s+${service}:`, "m").test(composeText));
+	if (ownServices.length === 0) {
+		p.log.error(`${effectiveComposeFile} does not define iii-engine or iii-init. Refusing an unscoped stop.`);
+		process.exit(1);
+	}
+	const composeCommand = ["docker", ...dockerComposeArgs(effectiveComposeFile, projectName, [])].join(" ");
+	if (runCommand(dockerBin, dockerComposeArgs(effectiveComposeFile, projectName, [
+		"rm",
+		"-s",
+		"-f",
+		...ownServices
+	]), { label: `${composeCommand} rm -s -f ${ownServices.join(" ")}` })) {
+		clearEnginePidfile();
+		clearEngineState();
+	} else {
+		p.log.error(`docker compose rm failed. The engine may still be running on :${port}. Inspect with:\n  ${composeCommand} ps`);
+		process.exit(1);
+	}
+	if (!suppressOutro) p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
 }
 async function runStop() {
+	await assertRuntimePortOwnership();
 	p.intro("agentmemory stop");
 	const port = getRestPort();
 	const state = readEngineState();
 	const running = await isEngineRunning();
 	const force = args.includes("--force");
 	if (state?.kind === "docker") {
-		if (!running) {
-			p.log.info(`No engine responding on port ${port}.`);
-			clearEnginePidfile();
-			clearEngineState();
-			clearWorkerPidfile();
-			p.outro("Nothing to stop.");
-			return;
-		}
-		await stopDockerEngine(state.composeFile, port);
+		if (!running) p.log.info(`No engine responding on port ${port}.`);
+		await stopDockerEngine(state, port);
 		return;
 	}
 	const portPids = findEnginePidsByPort(port);
@@ -2557,7 +3539,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();
@@ -2594,15 +3576,19 @@ async function runStop() {
 		process.exit(1);
 	}
 	let allStopped = true;
-	for (const pid of workerCandidates) {
-		const s = p.spinner();
-		s.start(`Stopping agentmemory worker (pid ${pid})... [flushing state]`);
-		const ok = await signalAndWait(pid, "SIGTERM", 5e3);
-		s.stop(ok ? `Stopped worker pid ${pid}` : `Failed to stop worker pid ${pid}`);
-		if (!ok) 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;
+		const comm = pidCommand(pid);
+		if (!force && isForeignPortHolder(comm)) {
+			skippedForeign.push({
+				pid,
+				comm
+			});
+			continue;
+		}
 		const s = p.spinner();
 		s.start(`Stopping iii-engine (pid ${pid})...`);
 		const ok = await signalAndWait(pid, "SIGTERM", 3e3);
@@ -2612,6 +3598,11 @@ async function runStop() {
 	clearEnginePidfile();
 	clearEngineState();
 	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.`);
+		process.exit(1);
+	}
 	if (!allStopped) {
 		p.log.error("One or more processes survived SIGKILL. Investigate with `ps`.");
 		process.exit(1);
@@ -2619,14 +3610,18 @@ async function runStop() {
 	p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
 }
 async function runMcp() {
-	await import("./standalone-YsZFFQBM.mjs");
+	await import("./standalone-DKCdrf1d.mjs");
 }
 async function runConnectCmd() {
-	const { runConnect } = await import("./connect-JnsJXc68.mjs").then((n) => n.n);
+	const { runConnect } = await import("./connect-B4_ca6BD.mjs").then((n) => n.n);
 	await runConnect(args.slice(1));
 }
 async function runImportJsonl() {
-	const VALUE_FLAGS = new Set(["--port", "--tools"]);
+	const VALUE_FLAGS = new Set([
+		"--port",
+		"--tools",
+		"--data-dir"
+	]);
 	let maxFiles;
 	const tail = args.slice(1);
 	const positional = [];
@@ -2675,11 +3670,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");
@@ -2766,20 +3762,46 @@ 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 === "docker") {
+		const inspection = inspectOwnedDockerEngine(ownedState);
+		if (inspection.status === "running" || inspection.status === "stopped") {
+			persistDockerInspection(ownedState, inspection);
+			if (!keepData) {
+				p.log.error(`Docker-backed removal requires --keep-data so the validated ${inspection.dataMountType} data mount (${inspection.dataMountSource}) and its recovery metadata remain usable. Re-run \`agentmemory remove --keep-data\`; destructive Docker data deletion is intentionally not automated.`);
+				process.exit(1);
+			}
+		} else {
+			const detail = inspection.status === "unavailable" ? inspection.reason : "the owned container is missing";
+			p.log.error(`remove cannot safely reconcile the saved Docker ownership (${detail}). Lifecycle state was preserved for manual recovery.`);
+			process.exit(1);
+		}
+	}
 	const home = homedir();
 	const connectManifest = loadConnectManifest(home);
+	const localBinIiiVersion = probeLocalBinIiiVersion(home);
+	const options = {
+		force,
+		keepData,
+		preserveRuntimeState: ownedState?.kind === "docker"
+	};
 	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;
@@ -2816,19 +3838,17 @@ 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)}`);
+			if (ownedState?.kind === "docker") {
+				await stopDockerEngine(ownedState, getRestPort(), true);
+				p.log.success("stopped Docker engine; container, data mount, and recovery state preserved");
+				continue;
 			}
+			const stopped = await stopNativeEngineForRemoval();
+			if (!stopped.ok) {
+				p.log.error(`Removal aborted: ${stopped.reason}.`);
+				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;
@@ -2838,18 +3858,82 @@ async function runRemove() {
 	}
 	p.outro("Done. agentmemory cleanly removed. The npm package itself: npm uninstall -g @agentmemory/agentmemory");
 }
-({
+async function runConsole() {
+	const iiiBin = pickCompatibleIii([whichBinary("iii"), ...fallbackIiiPaths().filter((candidate) => existsSync(candidate))]);
+	if (!iiiBin) {
+		p.log.error(`No iii v${IIPINNED_VERSION} found. Start agentmemory once so it installs the pinned engine into ${privateIiiPath()}, then run this again.`);
+		process.exit(1);
+	}
+	let parsed;
+	try {
+		parsed = parseConsoleArgs(args.slice(1), defaultConsolePort(getConfiguredViewerPort()));
+	} catch (err) {
+		p.log.error(err instanceof Error ? err.message : String(err));
+		process.exit(1);
+	}
+	const launch = {
+		iiiBin,
+		consolePort: parsed.consolePort,
+		restPort: getRestPort(),
+		streamPort: getStreamPort(),
+		enginePort: getEnginePort(),
+		extraArgs: parsed.extraArgs
+	};
+	if (!await isEngineRunning()) p.log.warn(`No engine responding on port ${launch.restPort}. The console starts anyway and connects once agentmemory is up.`);
+	p.log.info(`iii console: http://127.0.0.1:${launch.consolePort} (engine REST ${launch.restPort}, streams ${launch.streamPort}, bridge ${launch.enginePort}). The first run downloads the console binary next to the pinned iii.`);
+	const child = spawn(iiiBin, consoleArgs(launch), {
+		stdio: "inherit",
+		detached: true
+	});
+	const forward = (signal) => {
+		try {
+			process.kill(-child.pid, signal);
+		} catch {
+			child.kill(signal);
+		}
+	};
+	for (const signal of [
+		"SIGINT",
+		"SIGTERM",
+		"SIGHUP"
+	]) process.on(signal, () => forward(signal));
+	const code = await new Promise((resolve) => {
+		child.on("exit", (status, signal) => resolve(status ?? (signal ? 1 : 0)));
+		child.on("error", (err) => {
+			p.log.error(err.message);
+			resolve(1);
+		});
+	});
+	process.exit(code);
+}
+async function runCapture() {
+	const code = await runCaptureCommand({
+		base: getBaseUrl(),
+		args: args.slice(1),
+		secret: resolveClientSecret(getBaseUrl())
+	});
+	process.exit(code);
+}
+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
-}[args[0] ?? ""] ?? main)().catch((err) => {
+	"import-jsonl": runImportJsonl,
+	capture: runCapture
+};
+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) => {
 	p.log.error(err instanceof Error ? err.message : String(err));
 	process.exit(1);
 });