Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

132 KB
Raw Blame
#!/usr/bin/env node

import {
  spawn,
  execFileSync,
  spawnSync,
  type ChildProcess,
} from "node:child_process";
import {
  existsSync,
  mkdirSync,
  readdirSync,
  readFileSync,
  readlinkSync,
  rmSync,
  statSync,
  unlinkSync,
  writeFileSync,
} from "node:fs";
import { join, dirname, resolve, delimiter as PATH_DELIMITER } from "node:path";
import { fileURLToPath } from "node:url";
import { homedir, platform } from "node:os";
import * as p from "@clack/prompts";
import pc from "picocolors";

// Semantic color helpers. clack strips ANSI for box-width math
// (stripVTControlCharacters + string-width), so coloring inside p.note
// keeps borders aligned. Centralized here so the palette stays consistent
// across every command's output.
const c = {
  url: pc.cyan,
  ok: pc.green,
  warn: pc.yellow,
  err: pc.red,
  cmd: (s: string) => pc.bold(pc.cyan(s)),
  label: pc.bold,
  dim: pc.dim,
  accent: (s: string) => pc.bold(pc.yellow(s)),
};
import { generateId } from "./state/schema.js";
import {
  buildDiagnostics,
  canAutoFix,
  dryRunPlan,
  parseEnvFile,
  type Diagnostic,
  type DiagnosticFixResult,
  type DoctorContext,
  type DoctorEffects,
} from "./cli/doctor-diagnostics.js";
import {
  buildRemovePlan,
  formatPlan,
  legacyLocalBinIii,
  type ConnectManifest,
  type RemoveOptions,
} from "./cli/remove-plan.js";
import { portFlagSuffix } from "./cli/ready-hint.js";
import { embeddingStatusLabel } from "./cli/embedding-status.js";
import { expectedIiiSha256, iiiManualInstallCommand, installIiiArchive } from "./cli/engine-install.js";
import {
  runtimeConfigPath,
  redactCredentialUrls,
} from "./cli/engine-launch.js";
import { runtimeMetadataPath } from "./runtime-paths.js";
import { createStartupStderrCapture } from "./cli/startup-stderr.js";
import {
  configStartsAgentmemoryWorker,
  probeEngine,
  probeWorker,
  startWorkerAndWait,
  startupDeadline,
  startupTimeoutMessage,
  startupTimeouts,
  managedComposeReadinessUrl,
  waitForReadiness,
  withinStartupDeadline,
  type StartupDeadline,
} from "./cli/readiness.js";
import {
  engineFlushWaitMs,
  engineStateConfigPaths,
} from "./cli/engine-config.js";
import { SHUTDOWN_HARD_EXIT_MS, registerStartupCleanup, runStartupCleanup } from "./shutdown.js";
import { processStatIsRunning } from "./cli/process-state.js";
import { readUnixProcessExecutable, sameResolvedExecutable } from "./cli/compose-process.js";
import { renderSplash } from "./cli/splash.js";
import { isFirstRun, readPrefs, resetPrefs, writePrefs } from "./cli/preferences.js";
import { runOnboarding } from "./cli/onboarding.js";
import { setBootVerbose } from "./logger.js";
import { getRedisUrl, getStateBackend, hydrateProcessEnvFromFile } from "./config.js";
import { III_PINNED_VERSION, VERSION } from "./version.js";
import { getAllTools, ESSENTIAL_TOOLS } from "./mcp/tools-registry.js";
import { knownAgents } from "./cli/connect/index.js";

const ALL_TOOLS_COUNT = getAllTools().length;
const CORE_TOOLS_COUNT = getAllTools().filter((t) => ESSENTIAL_TOOLS.has(t.name)).length;
import { resolveDataDir } from "./cli-data-dir.js";
import { runCaptureCommand } from "./cli/capture.js";
import { runCompressionCommand } from "./cli/compression.js";
import { runGraphIndexCommand } from "./cli/graph-index.js";
import { bearerHeaders, resolveClientSecret } from "./secret-store.js";
import { assertComposePortsFree, composeCall, composeRegistryFailureMessage, composeStateRegistryFailure, composeWorkerFailureSummary, ownedComposeProject, readComposeLogFromOffset, startComposeDaemon, writeComposeState, type ComposeStatus } from "./cli/compose-control.js";
import { COMPOSE_WORKER_VERSIONS, composeNamespace } from "./cli/compose-project.js";
import { legacyDockerStateMessage, type LegacyDockerEngineState } from "./cli/legacy-docker-state.js";

const __dirname = dirname(fileURLToPath(import.meta.url));
const args = process.argv.slice(2);
const IS_WINDOWS = platform() === "win32";
const IS_VERBOSE =
  args.includes("--verbose") ||
  args.includes("-v") ||
  process.env["AGENTMEMORY_VERBOSE"] === "1" ||
  process.env["AGENTMEMORY_VERBOSE"] === "true";

// Propagate the resolved verbosity to the worker's boot logger so the
// 25-line `[agentmemory] X registered` stream is either dropped or
// printed verbatim. Without this the worker's default (env-only) would
// disagree with the CLI flag.
setBootVerbose(IS_VERBOSE);

const IS_RESET = args.includes("--reset");

// Fold ~/.agentmemory/.env into process.env before any port/URL read
// (getRestPort/getBaseUrl/getEnginePort) or the --port /
// --instance / --tools handlers below. Only-if-unset, so a real
// process.env value — including one just set by a CLI flag — still wins.
const shellEnv = hydrateProcessEnvFromFile();

// --version / -V early exit. Print VERSION + exit before any side effects
// (engine boot, env load, dir mkdir). `-v` is taken by --verbose so we
// reserve `-V` (capital) for version per POSIX convention.
if (args.includes("--version") || args.includes("-V")) {
  process.stdout.write(`${VERSION}\n`);
  process.exit(0);
}

// Pinned iii-engine version. The engine, the iii-sdk and the @iii-dev/helpers
// packages in package.json must stay on the same release: the worker speaks
// that engine's wire protocol and the unpinned installer tracks `latest`.
// Worker Compose supervises registry workers `state` and `http` alongside
// the local agentmemory worker; the CLI relies on this lifecycle to keep
// HTTP routes owned by the reconnecting worker. Bump this constant and
// the two package.json dependencies together.
// AGENTMEMORY_III_VERSION overrides the pin for anyone running a
// self-managed engine.
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`;

// Map Node platform/arch → the asset name iii-hq/iii ships under
// https://github.com/iii-hq/iii/releases/download/iii/v<version>/<asset>
function iiiReleaseAsset(): string | null {
  const p = platform();
  const a = process.arch;
  if (p === "darwin" && a === "arm64")
    return "iii-aarch64-apple-darwin.tar.gz";
  if (p === "darwin" && a === "x64")
    return "iii-x86_64-apple-darwin.tar.gz";
  if (p === "linux" && a === "x64")
    return "iii-x86_64-unknown-linux-gnu.tar.gz";
  if (p === "linux" && a === "arm64")
    return "iii-aarch64-unknown-linux-gnu.tar.gz";
  if (p === "linux" && a === "arm")
    return "iii-armv7-unknown-linux-gnueabihf.tar.gz";
  if (p === "win32" && a === "x64")
    return "iii-x86_64-pc-windows-msvc.zip";
  if (p === "win32" && a === "arm64")
    return "iii-aarch64-pc-windows-msvc.zip";
  return null;
}

function iiiReleaseUrl(): string | null {
  const asset = iiiReleaseAsset();
  if (!asset) return null;
  // Tag names are monorepo-prefixed: `iii/v<version>`. Slash is URL-encoded
  // by GitHub when serving the download path, hence `iii/v...` not `iii%2Fv...`.
  return `https://github.com/iii-hq/iii/releases/download/iii/v${IIPINNED_VERSION}/${asset}`;
}

function vlog(msg: string): void {
  if (IS_VERBOSE) p.log.info(`[verbose] ${msg}`);
}

function wrapList(items: readonly string[], indent: number, width = 78): string {
  const lines: string[] = [];
  let line = "";
  for (const item of items) {
    const joined = line ? `${line}, ${item}` : item;
    if (line && indent + joined.length > width) {
      lines.push(`${line},`);
      line = item;
    } else {
      line = joined;
    }
  }
  lines.push(line);
  return lines.join(`\n${" ".repeat(indent)}`);
}

if (args.includes("--help") || args.includes("-h")) {
  console.log(`
agentmemory — persistent memory for AI coding agents

Usage: agentmemory [command] [options]

Commands:
  (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
  remove             Cleanly uninstall agentmemory (pidfile, state, .env, binaries).
                     --force: skip confirmations · --keep-data: keep memory data
  demo [--serve]     Seed sample sessions and show recall in action.
                     --serve boots the server, runs the demo, and stops it
                     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 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)

Options:
  --help, -h         Show this help
  --verbose, -v      Show engine stderr, boot log, and diagnostic info
  --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). 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/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_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 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
  npx @agentmemory/agentmemory upgrade  # upgrade agentmemory + iii runtime
  npx @agentmemory/agentmemory mcp      # standalone MCP server (no engine)
  npx @agentmemory/mcp                  # same as above (shim package)
`);
  process.exit(0);
}

const toolsIdx = args.indexOf("--tools");
if (toolsIdx !== -1 && args[toolsIdx + 1]) {
  const toolsMode = 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 URL_CLIENT_COMMANDS = new Set(["status", "doctor", "mcp", "capture", "compression", "graph-index"]);
let hasExplicitLocalPortOverride = false;
let selectedInstance = 0;

function cliArgValue(name: string): string | undefined {
  const inline = args.find((arg) => arg.startsWith(`${name}=`));
  if (inline) return inline.slice(name.length + 1);
  const index = args.indexOf(name);
  return index === -1 ? undefined : args[index + 1];
}

const portValue = cliArgValue("--port");
if (portValue) {
  process.env["III_REST_PORT"] = portValue;
  hasExplicitLocalPortOverride = true;
}

// `--instance N` picks a 100-port block off the 3111 base so multiple
// agentmemory daemons can coexist on one host without env-var
// gymnastics. `--instance 0` keeps the canonical 3111/3113/49134
// ports; `--instance 1` → 3211/3213/49234; etc. REST acts as the
// anchor — viewer and engine derive from it via fixed offsets below
// unless an env explicitly pins each one.
const instanceValue = cliArgValue("--instance");
const hasInstanceArgument = args.some(
  (arg) => arg === "--instance" || arg.startsWith("--instance="),
);
if (hasInstanceArgument) {
  if (instanceValue === undefined || !/^\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 });
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(): boolean {
  return !hasExplicitLocalPortOverride && URL_CLIENT_COMMANDS.has(args[0] ?? "");
}

function getRestPort(): number {
  const url = shouldUseAgentmemoryUrl()
    ? process.env["AGENTMEMORY_URL"]
    : undefined;
  if (url) {
    try {
      const parsed = new URL(url).port;
      if (parsed) return parseInt(parsed, 10);
    } catch {}
  }
  return parseInt(process.env["III_REST_PORT"] || "3111", 10) || 3111;
}

function getBaseUrl(): string {
  const url = shouldUseAgentmemoryUrl()
    ? process.env["AGENTMEMORY_URL"]
    : undefined;
  if (url) return url.replace(/\/+$/, "");
  return `http://localhost:${getRestPort()}`;
}

function getConfiguredViewerPort(): number {
  return (
    parseInt(process.env["III_VIEWER_PORT"] || "", 10) ||
    getRestPort() + 2
  );
}

let discoveredViewerPort: number | null = null;

export async function discoverViewerPort(): Promise<void> {
  if (discoveredViewerPort !== null) return;
  try {
    const res = await fetch(`${getBaseUrl()}/agentmemory/livez`, {
      signal: AbortSignal.timeout(1000),
    });
    if (res.ok) {
      const data = await res.json() as { viewerPort?: number | null };
      if (typeof data.viewerPort === "number") {
        discoveredViewerPort = data.viewerPort;
      }
    }
  } catch {}
}

function getViewerUrl(): string {
  const envUrl = process.env["AGENTMEMORY_VIEWER_URL"];
  if (envUrl) return envUrl.replace(/\/+$/, "");
  
  if (discoveredViewerPort !== null) {
    try {
      const u = new URL(getBaseUrl());
      return `${u.protocol}//${u.hostname}:${discoveredViewerPort}`;
    } catch {
      return `http://localhost:${discoveredViewerPort}`;
    }
  }
  
  try {
    const u = new URL(getBaseUrl());
    const vPort = getConfiguredViewerPort();
    return `${u.protocol}//${u.hostname}:${vPort}`;
  } catch {
    const vPort = getConfiguredViewerPort();
    return `http://localhost:${vPort}`;
  }
}

// Bridge WebSocket port — the iii engine's internal worker bus.
// Defaults derived from REST as REST+46023 so the canonical 3111
// anchor yields 49134 and `--port 3211` auto-picks 49234 without a
// second-instance collision. Overridable via
// `III_ENGINE_PORT` or the legacy `III_ENGINE_URL=ws://host:port`.
function getEnginePort(): number {
  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(): Promise<boolean> {
  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(2000), (signal) => probeEngine(endpoint, signal)).catch(() => null);
  return result?.completed === true && result.value;
}

async function isAgentmemoryReady(): Promise<boolean> {
  const result = await withinStartupDeadline(startupDeadline(2000), workerReadinessProbe).catch(() => null);
  return result?.completed === true && result.value;
}

function workerReadinessProbe(signal: AbortSignal): Promise<boolean> {
  return probeWorker(getBaseUrl(), signal, (port) => { discoveredViewerPort = port; });
}

function warnIfRelocatedDataDir(): void {
  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, new Date().toISOString());
  } catch {
    p.log.warn(
      `Default data dir ${dataDirResolution.relocatedFrom} is inside a git worktree; using ${dataDirResolution.dataDir} instead.`,
    );
  }
}

function whichBinary(name: string): string | null {
  const cmd = IS_WINDOWS ? "where" : "which";
  try {
    const out = execFileSync(cmd, [name], {
      encoding: "utf-8",
      stdio: ["ignore", "pipe", "pipe"],
    });
    const first = out
      .split(/\r?\n/)
      .map((line) => line.trim())
      .find((line) => line.length > 0);
    return first ?? null;
  } catch {
    return null;
  }
}

// Private install location agentmemory manages itself. Sits under the
// agentmemory state dir (~/.agentmemory/bin) so the pinned engine stays
// isolated from a user-managed iii on PATH or in ~/.local/bin. A
// fresh box with iii 0.16.1 already on PATH refused to boot because the
// hard-pin enforcer told users to overwrite their global install with
// the pinned version. Private install resolves the conflict without touching their
// existing iii.
function agentmemoryBinDir(): string {
  if (IS_WINDOWS) {
    const userProfile = process.env["USERPROFILE"];
    if (!userProfile) return join(homedir(), ".agentmemory", "bin");
    return join(userProfile, ".agentmemory", "bin");
  }
  return join(homedir(), ".agentmemory", "bin");
}

function privateIiiPath(): string {
  return join(agentmemoryBinDir(), IS_WINDOWS ? "iii.exe" : "iii");
}

function fallbackIiiPaths(): string[] {
  if (IS_WINDOWS) {
    const userProfile = process.env["USERPROFILE"];
    const paths = [privateIiiPath()];
    if (userProfile) {
      paths.push(
        join(userProfile, ".local", "bin", "iii.exe"),
        join(userProfile, "bin", "iii.exe"),
      );
    }
    return paths;
  }
  const home = process.env["HOME"];
  const paths = [privateIiiPath()];
  if (home) {
    paths.push(join(home, ".local", "bin", "iii"));
  }
  paths.push("/usr/local/bin/iii");
  return paths;
}

function iiiBinVersion(binPath: string): string | null {
  try {
    const out = execFileSync(binPath, ["--version"], {
      encoding: "utf-8",
      stdio: ["ignore", "pipe", "ignore"],
      timeout: 3000,
    });
    const match = out.match(/(\d+\.\d+\.\d+(?:[-+][\w.]+)?)/);
    return match ? match[1]! : null;
  } catch {
    return null;
  }
}

// Resolve a compatible iii binary for the pinned engine version.
//
// Soft-warn lets the worker boot against a mismatched engine and crash at
// runtime (the SDK and engine wire protocol move together; 0.20+ renamed the
// SDK surface entirely). Hard-pin without a fallback leaves the user stuck — they
// either downgrade their global iii (breaking other consumers) or set
// AGENTMEMORY_III_VERSION and hope it works.
//
// Instead: when the candidate iii on PATH is the wrong version, prefer
// the private install under ~/.agentmemory/bin/iii. If the private copy
// is missing or also mismatched, the caller installs the pinned version
// there before retrying. AGENTMEMORY_III_VERSION still overrides
// IIPINNED_VERSION upstream so users who knowingly want a different
// engine can opt in.
function resolveCompatibleIii(iiiBinPath: string | null | undefined): string | null {
  if (!iiiBinPath) return null;
  const detected = iiiBinVersion(iiiBinPath);
  if (detected && detected === IIPINNED_VERSION) return iiiBinPath;

  const privatePath = privateIiiPath();
  if (iiiBinPath !== privatePath && existsSync(privatePath)) {
    const privateVersion = iiiBinVersion(privatePath);
    if (privateVersion === IIPINNED_VERSION) {
      const reason = detected ? `v${detected} mismatches pin` : "probe failed";
      vlog(
        `iii at ${iiiBinPath} ${reason} v${IIPINNED_VERSION}; using private install at ${privatePath}.`,
      );
      return privatePath;
    }
  }

  return null;
}

function enginePidfilePath(): string {
  return runtimeMetadataPath("iii.pid");
}

function engineStatePath(): string {
  return runtimeMetadataPath("engine-state.json");
}

type ComposeEngineState = {
  kind: "compose";
  restPort: number;
  viewerPort: number;
  enginePort: number;
  engineUrl: string;
  namespace: string;
  file: string;
  stateDir: string;
  logFile: string;
  logStartOffset?: number;
  binPath: string;
  composePid?: number;
  enginePid?: number;
  workerBinDir?: string;
  workerFailure?: string;
  workerVersions?: typeof COMPOSE_WORKER_VERSIONS | { local: true };
};

type NativeEngineState = {
  kind: "native";
  configPath: string;
  cwd?: string;
  attached?: boolean;
  binPath?: string;
  restPort?: number;
};


type EngineState = NativeEngineState | LegacyDockerEngineState | ComposeEngineState;

function readEnginePidfile(): number | null {
  try {
    const pidStr = readFileSync(enginePidfilePath(), "utf-8").trim();
    const pid = parseInt(pidStr, 10);
    return Number.isFinite(pid) && pid > 0 ? pid : null;
  } catch {
    return null;
  }
}

function clearEnginePidfile(): void {
  try {
    unlinkSync(enginePidfilePath());
  } catch {}
}

function workerPidfilePath(): string {
  return runtimeMetadataPath("worker.pid");
}

function readWorkerPidfile(): number | null {
  try {
    const pidStr = readFileSync(workerPidfilePath(), "utf-8").trim();
    const pid = parseInt(pidStr, 10);
    return Number.isFinite(pid) && pid > 0 ? pid : null;
  } catch {
    return null;
  }
}

function clearWorkerPidfile(): void {
  try {
    unlinkSync(workerPidfilePath());
  } catch {}
}

function readEngineState(): EngineState | null {
  try {
    const raw = readFileSync(engineStatePath(), "utf-8");
    const parsed = JSON.parse(raw) as Partial<EngineState>;
    if (parsed && (parsed.kind === "native" || parsed.kind === "docker" || parsed.kind === "compose")) {
      return parsed as EngineState;
    }
    return null;
  } catch {
    return null;
  }
}

function clearEngineState(): void {
  try {
    unlinkSync(engineStatePath());
  } catch {}
}

function engineStateRestPort(state: NativeEngineState | ComposeEngineState): number {
  if (state.restPort && Number.isFinite(state.restPort)) return state.restPort;
  if (state.kind === "compose") return 3111;
  try {
    const raw = readFileSync(state.configPath, "utf-8");
    const httpBlock = raw.match(
      /- name:\s*(?:iii-)?http([\s\S]*?)(?=\n\s*- name:|$)/,
    )?.[1];
    const configuredPort = httpBlock?.match(/\n\s*port:\s*(\d+)/)?.[1];
    if (configuredPort) return parseInt(configuredPort, 10);
  } catch {}
  return 3111;
}

async function startWorkerForEngineState(background = false): Promise<void> {
  if (readEngineState()?.kind === "compose") {
    const timeoutMs = startupTimeouts().workerMs;
    const ready = 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"));
      },
    });
    if (!ready) {
      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 status = await composeCall<ComposeStatus>({ engineUrl: state.engineUrl, namespace: state.namespace, functionId: "compose::status", file: state.file });
          const project = ownedComposeProject(status, state.file);
          const failures = (project?.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;
  const ready = 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 = new Error(`agentmemory worker exited during startup (${signal ?? code}).`);
        });
        child.unref();
      } else {
        importedStartupWorker = true;
        await import("./index.js");
      }
    },
    probe: workerReadinessProbe,
    stopped: () => startupInterrupted || engineStartupFailed() || startupWorkerFailure !== null,
  });
  if (!ready) {
    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(): boolean {
  const explicit = startupTimeouts().engineManagesWorker;
  if (explicit !== undefined) return explicit;
  const state = readEngineState();
  if (state?.kind !== "native" || state.attached) return false;
  try {
    const raw = readFileSync(state.configPath, "utf-8");
    return configStartsAgentmemoryWorker(raw, join(__dirname, "index.mjs"), state.cwd);
  } catch {
    return false;
  }
}


async function assertRuntimePortOwnership(): Promise<void> {
  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(): boolean {
  if (process.env["npm_lifecycle_event"] === "npx") return true;
  const argv1 = process.argv[1] ?? "";
  if (argv1.includes("_npx")) return true;
  const ua = process.env["npm_config_user_agent"] ?? "";
  if (ua.startsWith("npm/") || ua.includes(" npm/")) return true;
  return false;
}

// First-run global-install prompt. Replaces the previous passive
// `p.log.info` hint that users ignored — typing `agentmemory stop`
// in a new shell would then 404 with `command not found`. We now
// ask once, persist the answer in preferences, and never ask again.
async function maybeOfferGlobalInstall(): Promise<void> {
  if (!isInvokedViaNpx()) return;
  if (!process.stdin.isTTY) return;
  if (process.env["CI"]) return;
  const prefs = readPrefs();
  if (prefs.skipGlobalInstall || prefs.skipNpxHint) return;

  const answer = await p.confirm({
    message:
      "Install agentmemory globally so the bare `agentmemory` command works in any shell? [Y/n]",
    initialValue: true,
  });
  if (p.isCancel(answer)) {
    // Treat Ctrl+C as "not now" rather than "never". Don't persist.
    return;
  }
  if (answer === false) {
    writePrefs({ skipGlobalInstall: true });
    p.log.info(
      "Skipped. Re-run via `npx @agentmemory/agentmemory` or install later with: npm install -g @agentmemory/agentmemory",
    );
    return;
  }

  const npmBin = whichBinary("npm");
  if (!npmBin) {
    p.log.warn(
      "npm not found on PATH. Install manually: npm install -g @agentmemory/agentmemory",
    );
    return;
  }
  const ok = runCommand(
    npmBin,
    ["install", "-g", `@agentmemory/agentmemory@${VERSION}`],
    { label: `Installing @agentmemory/agentmemory@${VERSION} globally` },
  );
  if (ok) {
    p.log.success(
      "Installed globally. `agentmemory stop` etc. will now work in new shells.",
    );
    // Persist so we never re-prompt even if the user happens to npx
    // again from a CI-less TTY.
    writePrefs({ skipGlobalInstall: true });
  } else {
    p.log.warn(
      "Global install failed. Try manually: npm install -g @agentmemory/agentmemory",
    );
  }
}

async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null }> {
  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}. Download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`,
    );
    return { ok: false, binPath: null };
  }

  if (IS_WINDOWS || isZipAsset) {
    p.log.info(
      `Auto-install unavailable on ${platform()} — ${asset} isn't tar-compatible. Install manually:\n` +
        `  1. Download ${releaseUrl}\n` +
        `     Its SHA-256 must be ${expectedIiiSha256(IIPINNED_VERSION, asset ?? "") ?? `the value in ${releaseUrl.replace(/\.zip$/, ".sha256")}`}\n` +
        `  2. Extract iii.exe and place it on PATH (e.g. %USERPROFILE%\\.local\\bin)\n` +
        `Install the pinned iii binary from ${releaseUrl}`,
    );
    return { ok: false, binPath: null };
  }

  const shBin = whichBinary("sh");
  const curlBin = whichBinary("curl");
  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 };
  }

  const binDir = agentmemoryBinDir();
  const binPath = privateIiiPath();
  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)}\n` +
        `Install 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 };
}

type StartupFailure = {
  kind: "no-engine" | "engine-crashed";
  stderr?: string;
  binary?: string;
};

let startupFailure: StartupFailure | null = null;
let activeStartupStderr = createStartupStderrCapture();
let spawnedNativeEngine: ChildProcess | null = null;
let spawnedComposeDaemon: ChildProcess | null = null;
let composeStartupCompleted = false;
let importedStartupWorker = false;
let spawnedStartupWorker: ChildProcess | null = null;
let startupWorkerFailure: Error | null = null;
let engineReadinessDeadline: StartupDeadline | null = null;
let startupInterrupted = false;
let finishStartup = (): void => {};

function beginStartup(): void {
  finishStartup();
  startupInterrupted = false;
  const unregister = registerStartupCleanup(cleanupFailedStartup);
  const interrupt = async (exitCode: number): Promise<void> => {
    startupInterrupted = true;
    process.exit(await runStartupCleanup(exitCode).catch(() => exitCode));
  };
  const onInterrupt = () => { void interrupt(130); };
  const onTerminate = () => { void interrupt(143); };
  process.on("SIGINT", onInterrupt);
  process.on("SIGTERM", onTerminate);
  finishStartup = () => {
    process.off("SIGINT", onInterrupt);
    process.off("SIGTERM", onTerminate);
    unregister();
    finishStartup = () => {};
  };
}

function engineStartupFailed(): boolean {
  return startupFailure?.kind === "engine-crashed";
}

async function cleanupFailedStartup(): Promise<void> {
  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", 3000))) {
      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") {
    const stopped = await signalAndWait(composeChild.pid, "SIGTERM", 20_000);
    if (!stopped) 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) {
    const stopped = await signalAndWait(child.pid, "SIGTERM", 3000);
    if (!stopped) {
      p.log.warn(`Started engine pid ${child.pid} survived shutdown; lifecycle state was preserved.`);
      return;
    }
  }
  if (readEnginePidfile() === child.pid) {
    clearEnginePidfile();
    clearEngineState();
  }
}

function printCapturedStartupStderr(): void {
  const stderr = redactCredentialUrls(activeStartupStderr.text().trim());
  if (IS_VERBOSE && stderr) {
    p.note(stderr, "engine stderr");
  }
}

function readComposeStartupLogs(): { path: string; text: string } | null {
  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(): void {
  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: number, state: ComposeEngineState): boolean {
  try {
    let command = "";
    let executable = "";
    if (IS_WINDOWS) {
      // Preserve the existing PowerShell CIM ExecutablePath check on Windows;
      // if CIM does not provide a path, the process is not considered owned.
      const script = `$process = Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}'; if ($process) { @{ command = $process.CommandLine; executable = $process.ExecutablePath } | ConvertTo-Json -Compress }`;
      const result = execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
      const processInfo = JSON.parse(result) as { command?: string; executable?: string };
      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");
    }
    const expectedCommand = command.includes("compose") &&
      command.includes("compose --namespace") &&
      command.includes(state.namespace) &&
      command.includes(state.file);
    if (!expectedCommand) return false;
    if (!executable) return false;
    return sameResolvedExecutable(executable, state.binPath, IS_WINDOWS);
  } catch {
    return false;
  }
}

function composeChildProcesses(state: ComposeEngineState): Array<{ pid: number; pgid: number; args: string }> {
  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 is { pid: number; ppid: number; pgid: number; args: string } => 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: ComposeEngineState): number[] {
  return [...new Set(composeChildProcesses(state).map((child) => child.pid))];
}

function composeEnginePid(state: ComposeEngineState): number | undefined {
  return composeChildProcesses(state).find(({ args }) => args.includes(" --config ") && args.includes(state.namespace))?.pid;
}

async function terminateComposeChildren(state: ComposeEngineState): Promise<boolean> {
  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 as NodeJS.ErrnoException).code !== "ESRCH") stopped = false;
      continue;
    }
    const deadline = Date.now() + 5_000;
    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", 1000))) stopped = false;
  }
  return stopped;
}

async function startIiiBin(iiiBin: string): Promise<boolean> {
  const workerBinDir = process.env["AGENTMEMORY_WORKER_BIN_DIR"]?.trim() || undefined;
  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() };
  // Fast, actionable diagnosis before Compose attempts to bind its managed listeners.
  // Only reachable local TCP listeners count; failures to connect mean free/closed.
  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" as const,
    restPort: getRestPort(),
    viewerPort: getConfiguredViewerPort(),
    enginePort: getEnginePort(),
    engineUrl: `ws://127.0.0.1:${getEnginePort()}`,
    namespace,
    file: compose.file,
    stateDir: compose.stateDir,
    logFile: compose.logFile,
    logStartOffset: compose.logStartOffset,
    binPath: iiiBin,
    composePid: compose.child.pid,
    ...(workerBinDir ? { workerBinDir: resolve(process.cwd(), workerBinDir) } : {}),
  };
  writeComposeState(engineStatePath(), {
    ...state,
    workerVersions: workerBinDir ? { local: true } : COMPOSE_WORKER_VERSIONS,
  });
  engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);
  compose.child.on("error", (error) => {
    if (spawnedComposeDaemon === compose.child) {
      startupFailure = { kind: "engine-crashed", stderr: redactCredentialUrls(error.message), binary: iiiBin };
    }
  });
  compose.child.on("exit", (code, signal) => {
    if (spawnedComposeDaemon === compose.child && !composeStartupCompleted && (code !== 0 || signal !== null)) {
      startupFailure = {
        kind: "engine-crashed",
        stderr: signal ? `Compose exited from ${signal}` : `Compose exited with code ${code}`,
        binary: iiiBin,
      };
    }
  });
  const s = p.spinner();
  s.start(`Starting iii Worker Compose: ${iiiBin}`);
  s.stop(c.ok(`Compose daemon started (pid ${compose.child.pid})`));
  return true;
}

// Find a pinned-compatible iii path from a list of candidates. Returns
// the first candidate whose --version matches the pin, OR returns the
// private install path if it exists and matches, OR null if no candidate
// is compatible. Caller (startEngine) auto-installs the pin to the
// private path when this returns null.
function pickCompatibleIii(candidates: Array<string | null | undefined>): string | null {
  for (const c of candidates) {
    if (!c) continue;
    const resolved = resolveCompatibleIii(c);
    if (resolved) return resolved;
  }
  return null;
}

async function startEngine(): Promise<boolean> {
  startupFailure = null;
  engineReadinessDeadline = null;
  let stateBackendKind: "file" | "redis";
  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 pathIii = whichBinary("iii");
  vlog(`iii binary: ${pathIii ?? "(not on PATH)"}`);

  const fallbacks = fallbackIiiPaths().filter((p) => existsSync(p));
  for (const f of fallbacks) {
    const v = iiiBinVersion(f);
    vlog(`fallback iii at ${f} reports version: ${v ?? "unknown"}`);
  }

  let iiiBin = pickCompatibleIii([pathIii, ...fallbacks]);

  if (iiiBin) {
    if (iiiBin !== pathIii) {
      p.log.info(`Using iii at: ${c.dim(iiiBin)} (v${c.accent(IIPINNED_VERSION)})`);
      process.env["PATH"] = `${dirname(iiiBin)}${PATH_DELIMITER}${process.env["PATH"] ?? ""}`;
    }
    return startIiiBin(iiiBin);
  }

  if (pathIii && !iiiBin) {
    const detected = iiiBinVersion(pathIii);
    vlog(
      `iii on PATH is v${detected ?? "unknown"}, pin is v${IIPINNED_VERSION}. ` +
        `Will install pinned engine to ${privateIiiPath()}.`,
    );
  }

  mkdirSync(dataDirResolution.dataDir, { recursive: true });
  const interactive = !!process.stdin.isTTY && !process.env["CI"];

  type Choice = "install" | "manual";
  let choice: Choice;

  // Wrong-version iii on PATH is a configuration trap: any prompt would
  // confuse the user since they already "have iii installed". Skip the
  // prompt and auto-install pinned engine to the private location.
  const pathIiiMismatch = pathIii !== null && resolveCompatibleIii(pathIii) === null;

  if (pathIiiMismatch) {
    choice = "install";
    const detected = iiiBinVersion(pathIii!);
    p.log.info(
      `iii on PATH is v${detected ?? "unknown"} but agentmemory pins v${IIPINNED_VERSION}. ` +
        `Installing pinned engine to ~/.agentmemory/bin (leaves your existing iii untouched).`,
    );
  } else if (!interactive) {
    choice = "install";
    p.log.info("Non-interactive environment detected — auto-installing iii-engine.");
  } else {
    p.log.warn(`iii-engine binary not found locally.`);
    const options: { value: Choice; label: string; hint?: string }[] = [
      {
        value: "install",
        label: `Install iii v${IIPINNED_VERSION} to ~/.agentmemory/bin (~6MB, ~5s)`,
        hint: "recommended",
      },
    ];
    options.push({ value: "manual", label: "Show manual install steps and exit" });

    const picked = await p.select<Choice>({
      message: "How would you like to start iii-engine?",
      options,
      initialValue: "install",
    });
    if (p.isCancel(picked)) {
      startupFailure = { kind: "no-engine" };
      return false;
    }
    choice = picked;
  }

  if (choice === "manual") {
    startupFailure = { kind: "no-engine" };
    return false;
  }

  if (choice === "install") {
    const result = await runIiiInstaller();
    if (result.ok && result.binPath) {
      process.env["PATH"] = `${dirname(result.binPath)}${PATH_DELIMITER}${process.env["PATH"] ?? ""}`;
      iiiBin = result.binPath;
      return startIiiBin(iiiBin);
    }
    startupFailure = { kind: "no-engine" };
    return false;
  }

  startupFailure = { kind: "no-engine" };
  return false;
}

async function waitForEngine(timeoutMs = startupTimeouts().engineMs): Promise<boolean> {
  const state = readEngineState();
  // A composed engine's websocket port is internal control-plane detail and
  // may be unavailable while its HTTP workers are still binding. The owned
  // loopback REST listener is the readiness contract consumed by the CLI and
  // does not depend on AGENTMEMORY_URL (which is for client commands only).
  const endpoint = state?.kind === "compose"
    ? managedComposeReadinessUrl(state.restPort)
    : getBaseUrl();
  const probe = state?.kind === "compose"
    ? (signal: AbortSignal) => probeEngine(endpoint, signal)
    : (signal: AbortSignal) => probeEngine(endpoint, signal);
  return waitForReadiness(engineReadinessDeadline ?? startupDeadline(timeoutMs), probe, {
    intervalMs: 250,
    probeTimeoutMs: 750,
    stopped: () => startupInterrupted || engineStartupFailed(),
  });
}

async function waitForPersistedNativeEngine(): Promise<boolean> {
  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(): string[] {
  const releaseUrl = iiiReleaseUrl();
  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",
    "",
    "Or skip the engine entirely (standalone MCP):  npx @agentmemory/agentmemory mcp",
    "",
    "Docs: https://iii.dev/docs",
  ];
}

function portInUseDiagnostic(port: number): string {
  return IS_WINDOWS
    ? `  netstat -ano | findstr :${port}`
    : `  lsof -i :${port}   # or: ss -tlnp | grep :${port}`;
}

function printReadyHint(): void {
  const restUrl = getBaseUrl();
  const viewerUrl = getViewerUrl();
  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("Engine")}       ${c.url(engineUrl)}`,
  ];
  // p.note renders a bordered panel with a title — same affordance
  // used elsewhere in this CLI for "Troubleshooting" / "Setup
  // required" blocks, so the visual language stays consistent.
  p.note(lines.join("\n"), `agentmemory v${c.accent(VERSION)}`);

  // Pick a runnable form for the suggested next-step. Users invoked
  // via `npx` don't have the bare `agentmemory` command on PATH yet
  // (unless they accepted the global-install prompt and the npm bin
  // dir was already on PATH in this shell), so we suggest the npx
  // form for them; everyone else gets the global form.
  const demoCommand = `${invocation} demo${portFlags}`;
  process.stdout.write(`\n${c.dim("Try:")} ${c.cmd(demoCommand)}\n`);
}

async function reconcilePersistedComposeEngine(): Promise<boolean> {
  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 {
    const status = await composeCall<ComposeStatus>({ engineUrl: state.engineUrl, namespace: state.namespace, functionId: "compose::status", file: state.file });
    if (!ownedComposeProject(status, 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();
  // Booting a second instance next to a live daemon registers a duplicate
  // worker on the running engine, and before iii 0.19.2 the second instance's
  // shutdown tore down the daemon's HTTP trigger routing (every
  // /agentmemory/* route 404s until a full engine restart). Refuse instead.
  // A different --instance resolves to a different port, so multi-instance
  // setups are unaffected.
  try {
    const probe = await fetch(`${getBaseUrl()}/agentmemory/livez`, {
      signal: AbortSignal.timeout(1500),
    });
    if (probe.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 {
    // no live daemon on this port; boot normally
  }

  const legacyState = readEngineState();
  if (legacyState?.kind === "docker") {
    p.intro("agentmemory");
    p.log.error(legacyDockerStateMessage(legacyState));
    process.exit(1);
  }

  // `--reset` wipes preferences before anything else so the onboarding
  // flow below always runs fresh.
  if (IS_RESET) {
    resetPrefs();
  }

  const firstRun = isFirstRun();
  const prefs = readPrefs();
  // Show the splash on the first run, on --reset, or whenever the user
  // hasn't yet opted out via the schema (we set `skipSplash: true`
  // after onboarding completes). Verbose runs always splash since the
  // user explicitly asked for the chatty experience.
  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 startWorkerForEngineState();
    await maybeOfferGlobalInstall();
    printReadyHint();
    return;
  }

  if (await reconcilePersistedComposeEngine()) {
    await startWorkerForEngineState();
    await maybeOfferGlobalInstall();
    printReadyHint();
    return;
  }

  if (await isEngineRunning() || await waitForPersistedNativeEngine()) {
    if (IS_VERBOSE) p.log.success("iii-engine is running");
    // Prefer the binary path persisted at launch time over whatever's on
    // PATH now. PATH lookups misfire when a global iii install gets added
    // after agentmemory started (or when the running engine was launched
    // from a path that's no longer first on PATH).
    const persisted = readEngineState();
    const persistedBin =
      persisted?.kind === "native" && persisted.binPath && existsSync(persisted.binPath)
        ? persisted.binPath
        : null;
    const attachedBin =
      persistedBin ??
      whichBinary("iii") ??
      fallbackIiiPaths().find((p) => existsSync(p)) ??
      null;
    const detected = persisted?.kind === "compose" ? iiiBinVersion(persisted.binPath) : attachedBin ? iiiBinVersion(attachedBin) : null;

    // Fail closed: only adopt the running engine when we can positively
    // confirm it is the pinned version. An unknown version (detected === null,
    // e.g. the binary can't be version-probed) is treated as incompatible —
    // adopting a foreign or unverifiable engine hangs the worker in a
    // WebSocket reconnect loop. Worst case here is a re-run that reinstalls
    // the pinned engine, never a silent loop.
    if (detected === IIPINNED_VERSION) {
      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";

    // An incompatible engine owns the port. Adopting it hangs the worker in a
    // WebSocket reconnect loop (it can't speak that engine's protocol), so stop
    // with the simplest honest remedy. A normal user has no other engine and
    // never sees this; only someone running their own iii does, and for them
    // "stop it, then run normally" is the fix. We do not suggest a different
    // engine version: agentmemory only supports v${IIPINNED_VERSION}.
    const base = isInvokedViaNpx() ? "npx @agentmemory/agentmemory" : "agentmemory";
    p.log.error(
      `Another iii-engine (${detectedLabel}) is running on port ${getEnginePort()}, and agentmemory needs its own pinned v${IIPINNED_VERSION}.`,
    );
    p.note(
      [
        `agentmemory only supports iii-engine v${IIPINNED_VERSION}. It will not adopt or change the running engine (${detectedLabel}).`,
        "",
        c.label("Switch to the pinned engine in two steps:"),
        "",
        `  1. Stop the running engine:`,
        `       ${c.cmd(`${base} stop --force`)}`,
        `     ${c.dim(`(or stop your own iii however you started it — agentmemory leaves your global iii untouched)`)}`,
        "",
        `  2. Start agentmemory. It downloads and runs the pinned`,
        `     v${IIPINNED_VERSION} into ~/.agentmemory/bin automatically:`,
        `       ${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(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);
  }

  const started = await startEngine();
  if (!started) {
    p.log.error("Could not start iii-engine.");
    const lines = installInstructions();
    p.note(lines.join("\n"), "Setup required");
    throw new Error("iii-engine could not be started.");
  }

  const s = p.spinner();
  s.start("Waiting for iii-engine to be ready...");

  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();
    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: string | null = 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");
      } else {
        p.log.info("No stderr was captured. Re-run with --verbose for more detail.");
      }
      p.note(
        [
          "Common causes:",
          `  - iii-engine version mismatch — reinstall the pinned v${IIPINNED_VERSION} binary`,
          "    (sh script on macOS/Linux, GitHub release zip on Windows)",
          "  - 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),
          "",
          "If it is, free the port or override: agentmemory --port <N>",
          "",
          "If it isn't, a firewall may be blocking 127.0.0.1:" + port + ".",
          "Re-run with --verbose to see engine stderr.",
        ].join("\n"),
        "Troubleshooting",
      );
    }
    if (composeLog?.text) p.log.error(`Compose log: ${composeLog.path}`);
    throw new Error(shortFailure);
  }

  s.stop(c.ok("iii-engine is ready"));
  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();
  // Mark splash as something to skip on subsequent runs. This is a
  // no-op if onboarding already flipped the flag (idempotent merge).
  writePrefs({ skipSplash: true });
  // Worker Compose owns the service lifecycle independently of this startup
  // launcher. Do not leave readiness-probe keep-alive sockets referenced after
  // printing the ready hint; the daemon and its worker remain detached.
  if (managedCompose?.kind === "compose") {
    await new Promise<void>((resolve) => process.stdout.write("", () => resolve()));
    process.exit(0);
  }
}

async function apiFetch<T = unknown>(base: string, path: string, timeoutMs = 5000): Promise<T | null> {
  try {
    const headers: Record<string, string> = bearerHeaders(base);
    const res = await fetch(`${base}/agentmemory/${path}`, {
      signal: AbortSignal.timeout(timeoutMs),
      headers,
    });
    return (await res.json()) as T;
  } catch {
    return null;
  }
}

async function runStatus() {
  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));
  }

  const up = await isEngineRunning();
  if (!up) {
    if (savedState?.kind === "compose" && savedState.composePid && pidAlive(savedState.composePid)) {
      try {
        const composeStatus = await composeCall<ComposeStatus>({
          engineUrl: savedState.engineUrl,
          namespace: savedState.namespace,
          functionId: "compose::status",
          file: savedState.file,
        });
        const project = ownedComposeProject(composeStatus, savedState.file);
        const failure = composeWorkerFailureSummary(project);
        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);
  }

  try {
    const [healthRes, sessionsRes, graphRes, memoriesRes, flagsRes, followupRes] = await Promise.all([
      apiFetch<any>(base, "health"),
      apiFetch<any>(base, "sessions"),
      apiFetch<any>(base, "graph/stats"),
      apiFetch<any>(base, "memories?count=true"),
      apiFetch<any>(base, "config/flags"),
      apiFetch<any>(base, "diagnostics/followup"),
    ]);

    if (typeof healthRes?.viewerPort === "number") {
      discoveredViewerPort = healthRes.viewerPort;
    }
    const h = healthRes?.health;
    const status = healthRes?.status || "unknown";
    const version = healthRes?.version || "?";
    const sessionList = Array.isArray(sessionsRes?.sessions) ? sessionsRes.sessions : [];
    const sessions = sessionList.length;
    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;

    const obsCount = sessionList.reduce(
      (sum: number, s: any) => sum + (Number(s?.observationCount) || 0),
      0,
    );
    const memCount = Number(memoriesRes?.latestCount ?? memoriesRes?.total ?? 0) || 0;
    const estFullTokens = obsCount * 80;
    const estInjectedTokens = Math.min(obsCount, 50) * 38;
    const tokensSaved = estFullTokens - estInjectedTokens;
    const pctSaved = estFullTokens > 0 ? Math.round((tokensSaved / estFullTokens) * 100) : 0;

    p.log.success(`Connected — v${version} at ${base}`);

    const lines = [
      `Health:       ${status === "healthy" ? pc.green("✓ healthy") : pc.yellow(status)}`,
      `Sessions:     ${sessions}`,
      `Observations: ${obsCount}`,
      `Memories:     ${memCount}`,
      `Graph:        ${nodes} nodes, ${edges} edges`,
      `Circuit:      ${cb}`,
      `Heap:         ${heapMB} MB`,
      `Uptime:       ${uptime}s`,
      `Viewer:       ${c.url(getViewerUrl())}`,
    ];

    if (obsCount > 0) {
      lines.push("");
      lines.push(`Token savings: ~${tokensSaved.toLocaleString()} tokens saved (${pctSaved}% reduction)`);
      lines.push(`  Full context: ~${estFullTokens.toLocaleString()} tokens`);
      lines.push(`  Injected:     ~${estInjectedTokens.toLocaleString()} tokens`);
    }

    if (flagsRes) {
      const provider = flagsRes.provider === "llm" ? pc.green("✓ llm") : pc.yellow("✗ noop (no key)");
      const embedding = embeddingStatusLabel(flagsRes.embeddingProvider);
      const embed = embedding ? pc.green(`✓ ${embedding}`) : pc.dim("bm25-only");
      const flagRows = (flagsRes.flags || []).map((f: { key: string; enabled: boolean; label: string }) =>
        `  ${f.enabled ? pc.green("✓") : pc.dim("✗")} ${pc.bold(f.key.padEnd(32))} ${f.label}`
      );
      lines.push("");
      lines.push(`Provider:     ${provider}`);
      lines.push(`Embeddings:   ${embed}`);
      lines.push(`Flags:`);
      flagRows.forEach((r: string) => lines.push(r));
    }

    if (followupRes && Number.isFinite(followupRes.agentInitiatedSearches)) {
      const total = Number(followupRes.agentInitiatedSearches) || 0;
      const hits = Number(followupRes.followupWithinWindow) || 0;
      const pct = total > 0 ? Math.round((hits / total) * 100) : 0;
      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 composeStatus = await composeCall<ComposeStatus>({ engineUrl: managed.engineUrl, namespace: managed.namespace, functionId: "compose::status", file: managed.file });
        const composeProject = ownedComposeProject(composeStatus, 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));
    process.exit(1);
  }
}

type DoctorCheck = { name: string; ok: boolean; hint?: string };

function formatChecks(checks: DoctorCheck[]): string {
  return checks
    .map((c) => `${c.ok ? pc.green("✓") : pc.red("✗")} ${c.name}${c.hint ? `\n   ${c.hint}` : ""}`)
    .join("\n");
}

type CCHooksCheck =
  | { state: "loaded"; manifestPath?: string }
  | { state: "not-loaded" }
  | { state: "no-debug-log" }
  | { state: "no-cc-dir" };

function findLatestDebugLog(debugDir: string): string | undefined {
  const latestLink = join(debugDir, "latest");
  try {
    if (existsSync(latestLink)) {
      const target = readlinkSync(latestLink);
      const resolved = target.startsWith("/") ? target : join(debugDir, target);
      if (existsSync(resolved)) return resolved;
    }
  } catch {}

  try {
    const newest = readdirSync(debugDir)
      .filter((f) => f.endsWith(".txt"))
      .map((f) => ({ f, m: statSync(join(debugDir, f)).mtimeMs }))
      .sort((a, b) => b.m - a.m)[0];
    if (newest) return join(debugDir, newest.f);
  } catch {}

  return undefined;
}

function checkClaudeCodeHooks(): CCHooksCheck {
  const debugDir = join(homedir(), ".claude", "debug");
  if (!existsSync(debugDir)) return { state: "no-cc-dir" };

  const logPath = findLatestDebugLog(debugDir);
  if (!logPath) return { state: "no-debug-log" };

  let content: string;
  try {
    content = readFileSync(logPath, "utf8");
  } catch {
    return { state: "no-debug-log" };
  }

  const match = content.match(
    /Loaded hooks from standard location for plugin agentmemory:\s*(\S+)/
  );
  if (match) return { state: "loaded", manifestPath: match[1] };
  if (content.includes("Loading hooks from plugin: agentmemory")) return { state: "loaded" };
  return { state: "not-loaded" };
}

// ---------------------------------------------------------------------------
// Doctor v2 — interactive fixer.
//
// The legacy passive check-list (server reachable, flags, knowledge-graph,
// Claude Code hooks) still runs first as an informational summary because
// those checks need a live engine and don't have a one-shot inline fix.
// Then we drive the new diagnostic catalog (see src/cli/doctor-diagnostics.ts)
// which prompts Fix/Skip/More/Quit per failing check, applies the fix
// inline, and re-checks only the affected diagnostic.

function doctorEnvPath(): string {
  return process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env");
}

function buildDoctorContext(): DoctorContext {
  return {
    baseUrl: getBaseUrl(),
    viewerUrl: getViewerUrl(),
    envPath: doctorEnvPath(),
    pidfilePath: readEngineState()?.kind === "compose" ? engineStatePath() : enginePidfilePath(),
    enginePath: engineStatePath(),
    pinnedVersion: IIPINNED_VERSION,
  };
}

function buildDoctorEffects(): DoctorEffects {
  return {
    envFileExists: () => existsSync(doctorEnvPath()),
    readEnvFile: () => {
      try {
        return parseEnvFile(
          readFileSync(doctorEnvPath(), "utf-8"),
        );
      } catch {
        return {};
      }
    },
    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: () => {
      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: string) => iiiBinVersion(binPath),
    externalEngineRunning: async () => {
      const state = readEngineState();
      const remoteTarget = shouldUseAgentmemoryUrl() && process.env["AGENTMEMORY_URL"];
      const managed = state?.kind === "compose" && state.restPort === getRestPort() && !remoteTarget;
      return !managed && await isEngineRunning();
    },
    viewerReachable: async (timeoutMs = 2000) => {
      try {
        await discoverViewerPort();
        const res = await fetch(getViewerUrl(), {
          signal: AbortSignal.timeout(timeoutMs),
        });
        return res.ok;
      } catch {
        return false;
      }
    },
    runInit: async () => {
      try {
        await runInit();
        return { ok: true, message: "Wrote ~/.agentmemory/.env" };
      } catch (err) {
        return {
          ok: false,
          message: err instanceof Error ? err.message : String(err),
        };
      }
    },
    openEditor: async (path: string) => {
      const editor = process.env["EDITOR"] || process.env["VISUAL"] || "nano";
      p.log.info(`Opening ${path} in ${editor}…`);
      try {
        // Inherit stdio so the user actually sees the editor.
        const result = spawnSync(editor, [path], { stdio: "inherit" });
        if (result.error) {
          return {
            ok: false,
            message: `Failed to launch ${editor}: ${result.error.message}`,
          };
        }
        if ((result.status ?? 0) !== 0) {
          return {
            ok: false,
            message: `${editor} exited with code ${result.status}`,
          };
        }
        return { ok: true, message: `Saved ${path}` };
      } catch (err) {
        return {
          ok: false,
          message: err instanceof Error ? err.message : String(err),
        };
      }
    },
    runIiiInstaller: async () => {
      const r = await runIiiInstaller();
      return {
        ok: r.ok,
        message: r.ok
          ? `Installed iii v${IIPINNED_VERSION} to ${r.binPath}`
          : "iii installer failed (see warnings above)",
      };
    },
    runStop: async () => {
      try {
        startupTimeouts();
        if (readEngineState()?.kind === "compose") {
          await runStop();
          return { ok: true, message: "Worker Compose project stopped." };
        }
        // runStop calls process.exit on its own — guard against that here
        // by short-circuiting when there's nothing to stop.
        const port = getRestPort();
        const portPids = findEnginePidsByPort(port);
        const pidfilePid = readEnginePidfile();
        if (portPids.length === 0 && pidfilePid === null) {
          clearEnginePidfile();
          clearEngineState();
          return { ok: true, message: "Nothing to stop." };
        }
        const candidates = new Set<number>();
        if (pidfilePid) candidates.add(pidfilePid);
        for (const pid of portPids) candidates.add(pid);
        let allStopped = true;
        for (const pid of candidates) {
          const ok = await signalAndWait(pid, "SIGTERM", 3000);
          if (!ok) allStopped = false;
        }
        clearEnginePidfile();
        clearEngineState();
        return {
          ok: allStopped,
          message: allStopped ? "Engine stopped." : "Some engine pids survived.",
        };
      } catch (err) {
        return {
          ok: false,
          message: err instanceof Error ? err.message : String(err),
        };
      }
    },
    runStart: async () => {
      try {
        startupTimeouts();
        beginStartup();
        const started = await startEngine();
        if (!started) throw new Error("iii-engine could not be started.");
        if (!(await waitForEngine())) throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));
        await startWorkerForEngineState(true);
        return { 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),
        };
      }
    },
    clearEnginePidAndState: () => {
      clearEnginePidfile();
      clearEngineState();
    },
  };
}

async function passiveServerChecks(): Promise<DoctorCheck[]> {
  const base = getBaseUrl();
  const checks: DoctorCheck[] = [];

  const serverUp = await isEngineRunning();
  checks.push({
    name: "Server reachable",
    ok: serverUp,
    hint: serverUp
      ? undefined
      : `Start with: npx @agentmemory/agentmemory (tried ${base})`,
  });
  if (!serverUp) return checks;

  const [health, flags, graph] = await Promise.all([
    apiFetch<any>(base, "health", 3000),
    apiFetch<any>(base, "config/flags", 3000),
    apiFetch<any>(base, "graph/stats", 3000),
  ]);

  const hasLlm = flags?.provider === "llm";
  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",
      hint:
        health?.status === "healthy"
          ? undefined
          : `Status: ${health?.status || "unknown"}`,
    },
    {
      name: "LLM provider",
      ok: hasLlm,
      hint: hasLlm ? undefined : "set ANTHROPIC_API_KEY (or GEMINI/OPENROUTER/MINIMAX) in ~/.agentmemory/.env",
    },
    {
      name: "Embedding provider",
      ok: hasEmbed,
      hint: hasEmbed
        ? undefined
        : "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 || []) as {
    label: string;
    enabled: boolean;
    enableHow: string;
  }[]) {
    checks.push({
      name: f.label,
      ok: f.enabled,
      hint: f.enabled ? undefined : f.enableHow,
    });
  }

  const cc = checkClaudeCodeHooks();
  const ccCheck = (() => {
    switch (cc.state) {
      case "loaded":
        return {
          ok: true,
          hint: cc.manifestPath ? `manifest: ${cc.manifestPath}` : undefined,
        };
      case "not-loaded":
        return {
          ok: false,
          hint:
            "Plugin enabled but hooks not loaded by Claude Code. Try: /plugin uninstall agentmemory@agentmemory && /plugin install agentmemory@agentmemory, then restart the session.",
        };
      case "no-debug-log":
        return {
          ok: false,
          hint:
            'Cannot verify — no Claude Code debug log found. Run once with `claude --debug -p "x"`, then re-run doctor.',
        };
      case "no-cc-dir":
        return undefined;
    }
  })();
  if (ccCheck) checks.push({ name: "Claude Code plugin hooks registered", ...ccCheck });

  checks.push({
    name: "Knowledge graph populated",
    ok: graphHas,
    hint: graphHas
      ? undefined
      : graphNodeCount === null
        ? "Graph counts are unavailable. Run agentmemory graph-index status."
        : "Graph is empty. Run a session with GRAPH_EXTRACTION_ENABLED=true.",
  });

  return checks;
}

type DoctorAction = "fix" | "skip" | "more" | "quit";

async function askFixAction(d: Diagnostic): Promise<DoctorAction> {
  const choice = await p.select<DoctorAction>({
    message: `[${d.id}] ${d.message}`,
    options: [
      { value: "fix", label: "F  Fix", hint: d.fixPreview },
      { value: "skip", label: "S  Skip" },
      { value: "more", label: "?  More info" },
      { value: "quit", label: "Q  Quit doctor" },
    ],
    initialValue: "fix",
  });
  if (p.isCancel(choice)) return "quit";
  return choice;
}

async function applyFixWithReport(
  d: Diagnostic,
  ctx: DoctorContext,
  dryRun: boolean,
): Promise<DiagnosticFixResult> {
  if (dryRun) {
    p.log.info(`[dry-run] would: ${d.fixPreview}`);
    return { ok: true, message: "(dry-run)" };
  }
  const result = await d.fix(ctx);
  if (result.ok) {
    p.log.success(result.message ?? `${d.id} fixed.`);
  } else {
    p.log.error(result.message ?? `${d.id} fix failed.`);
  }
  return result;
}

async function runDoctor() {
  p.intro("agentmemory doctor");
  const applyAll = args.includes("--all");
  const dryRun = args.includes("--dry-run");
  if (applyAll && dryRun) {
    p.log.error("Cannot combine --all and --dry-run.");
    process.exit(2);
  }

  // Passive server checks (informational).
  const passive = await passiveServerChecks();
  const passivePassed = passive.filter((c) => c.ok).length;
  p.note(formatChecks(passive), `server: ${passivePassed}/${passive.length} passing`);

  // Doctor v2 interactive catalog.
  const ctx = buildDoctorContext();
  const effects = buildDoctorEffects();
  const diagnostics = buildDiagnostics(effects);

  if (dryRun) {
    const results: Array<{ diagnostic: Diagnostic; status: { ok: boolean; detail?: string } }> = [];
    for (const d of diagnostics) results.push({ diagnostic: d, status: await d.check(ctx) });
    const lines = dryRunPlan(ctx, results);
    p.note(lines.join("\n"), "dry-run plan");
    p.outro("Dry-run complete. Re-run without --dry-run to apply.");
    return;
  }

  let failed = 0;
  let fixed = 0;
  let skipped = 0;
  let quit = false;

  for (const d of diagnostics) {
    if (quit) {
      skipped++;
      continue;
    }
    const status = await d.check(ctx);
    if (status.ok) {
      p.log.success(`${d.id} ✓${status.detail ? ` (${status.detail})` : ""}`);
      continue;
    }
    failed++;
    p.log.warn(`${d.id} ✗ ${status.detail ?? ""}`.trim());

    if (!canAutoFix(d, status)) {
      p.log.info(`manual fix: ${status.manualFix ?? d.fixPreview}`);
      skipped++;
      continue;
    }

    p.log.info(`why: ${d.fixPreview}`);

    if (applyAll) {
      const r = await applyFixWithReport(d, ctx, false);
      if (r.ok) fixed++;
      // Re-check only this diagnostic.
      const after = await d.check(ctx);
      if (!after.ok) p.log.warn(`${d.id} still failing after fix.`);
      continue;
    }

    // Interactive prompt loop — allow [?] More info without leaving the check.
    while (true) {
      const action = await askFixAction(d);
      if (action === "fix") {
        const r = await applyFixWithReport(d, ctx, false);
        if (r.ok) {
          const after = await d.check(ctx);
          if (after.ok) {
            fixed++;
          } else {
            p.log.warn(`${d.id} still failing after fix: ${after.detail ?? ""}`);
          }
        }
        break;
      }
      if (action === "skip") {
        skipped++;
        break;
      }
      if (action === "more") {
        p.note(d.moreInfo, `[${d.id}] more info`);
        continue;
      }
      if (action === "quit") {
        quit = true;
        break;
      }
    }
  }

  const summary = `${diagnostics.length} checks · ${failed} failing · ${fixed} fixed · ${skipped} skipped`;
  if (quit) {
    p.outro(`Quit early. ${summary}`);
    process.exit(1);
  }
  if (failed === 0) {
    p.outro("All diagnostics passing. agentmemory is healthy.");
    return;
  }
  if (failed - fixed === 0) {
    p.outro(`All fixes applied. ${summary}`);
    return;
  }
  p.outro(summary);
  process.exit(1);
}

type DemoObservation = {
  toolName: string;
  toolInput: Record<string, string>;
  toolOutput: string;
};

type DemoSession = {
  id: string;
  title: string;
  observations: DemoObservation[];
};

type SearchResult = { query: string; hits: number; topTitle: string };

function buildDemoSessions(): DemoSession[] {
  return [
    {
      id: generateId("demo"),
      title: "Session 1: JWT auth setup",
      observations: [
        {
          toolName: "Write",
          toolInput: { file_path: "src/middleware/auth.ts" },
          toolOutput:
            "Created JWT middleware using jose library. Tokens expire after 30 days. Chose jose over jsonwebtoken for Edge compatibility.",
        },
        {
          toolName: "Write",
          toolInput: { file_path: "test/auth.test.ts" },
          toolOutput:
            "Added token validation tests covering expired, malformed, and valid cases.",
        },
        {
          toolName: "Bash",
          toolInput: { command: "npm test" },
          toolOutput: "All 12 auth tests passing.",
        },
      ],
    },
    {
      id: generateId("demo"),
      title: "Session 2: Database migration debugging",
      observations: [
        {
          toolName: "Read",
          toolInput: { file_path: "prisma/schema.prisma" },
          toolOutput:
            "Found N+1 query issue in user relations. Need to add include on posts query.",
        },
        {
          toolName: "Edit",
          toolInput: { file_path: "src/api/users.ts" },
          toolOutput:
            "Fixed N+1 by adding Prisma include. Query time dropped from 450ms to 28ms.",
        },
      ],
    },
    {
      id: generateId("demo"),
      title: "Session 3: Rate limiting",
      observations: [
        {
          toolName: "Write",
          toolInput: { file_path: "src/middleware/ratelimit.ts" },
          toolOutput:
            "Added rate limiting middleware with 100 req/min default. Uses in-memory store for dev, Redis for prod.",
        },
      ],
    },
  ];
}

async function postJson<T = unknown>(
  url: string,
  body: unknown,
  timeoutMs = 5000,
): Promise<T | null> {
  try {
    const res = await fetch(url, {
      method: "POST",
      headers: { "Content-Type": "application/json", ...bearerHeaders(url) },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(timeoutMs),
    });
    if (!res.ok) return null;
    return (await res.json().catch(() => null)) as T | null;
  } catch {
    return null;
  }
}

async function postJsonStrict<T = unknown>(
  url: string,
  body: unknown,
  timeoutMs = 5000,
): Promise<T | null> {
  const res = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json", ...bearerHeaders(url) },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(timeoutMs),
  });
  if (!res.ok) {
    const errBody = await res.text().catch(() => "");
    const suffix = errBody ? ` — ${errBody.slice(0, 200)}` : "";
    throw new Error(`POST ${url} failed: ${res.status} ${res.statusText}${suffix}`);
  }
  return (await res.json().catch(() => null)) as T | null;
}

async function seedDemoSession(
  base: string,
  project: string,
  session: DemoSession,
): Promise<number> {
  await postJsonStrict(`${base}/agentmemory/session/start`, {
    sessionId: session.id,
    project,
    cwd: project,
  });

  let stored = 0;
  for (const obs of session.observations) {
    const url = `${base}/agentmemory/observe`;
    const payload = {
      hookType: "post_tool_use",
      sessionId: session.id,
      project,
      cwd: project,
      timestamp: new Date().toISOString(),
      data: {
        tool_name: obs.toolName,
        tool_input: obs.toolInput,
        tool_output: obs.toolOutput,
      },
    };

    try {
      const res = await fetch(url, {
        method: "POST",
        headers: { "Content-Type": "application/json", ...bearerHeaders(url) },
        body: JSON.stringify(payload),
        signal: AbortSignal.timeout(5000),
      });
      if (res.ok) {
        stored++;
      } else {
        const body = await res.text().catch(() => "");
        p.log.warn(
          `observe failed for ${obs.toolName}: ${res.status} ${res.statusText}${body ? ` — ${body.slice(0, 160)}` : ""}`,
        );
      }
    } catch (err) {
      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, final: true });
  return stored;
}

async function runDemoSearch(base: string, query: string): Promise<SearchResult> {
  const data = await postJson<{ results?: Array<{ title?: string }> }>(
    `${base}/agentmemory/smart-search`,
    { query, limit: 5 },
    10000,
  );
  const items = data?.results ?? [];
  return {
    query,
    hits: items.length,
    topTitle: items[0]?.title ?? "(no results)",
  };
}

// Prefer the packaged `.env.example` (next to `dist/cli.mjs`); fall back to
// the repo root when running from a source checkout.
function findEnvExample(): string | null {
  const candidates = [
    join(__dirname, "..", ".env.example"),
    join(__dirname, ".env.example"),
    join(process.cwd(), ".env.example"),
  ];
  for (const c of candidates) {
    if (existsSync(c)) return c;
  }
  return null;
}

async function runInit() {
  p.intro("agentmemory init");
  const target = join(homedir(), ".agentmemory", ".env");
  const template = findEnvExample();
  if (!template) {
    p.log.error(
      "Could not locate .env.example in the package. Re-install with: npm i -g @agentmemory/agentmemory",
    );
    process.exit(1);
  }
  const dir = dirname(target);
  const { mkdir, copyFile } = await import("node:fs/promises");
  const { constants: fsConstants } = await import("node:fs");
  try {
    await mkdir(dir, { recursive: true });
    // COPYFILE_EXCL collapses the exists-check + copy into one syscall —
    // an existsSync(target) + copyFile() pair races with a parallel init
    // (or any other process touching ~/.agentmemory/.env between the two
    // calls) and would silently overwrite a config the operator just
    // wrote. EEXIST out of copyFile is the only "already configured"
    // signal we trust.
    await copyFile(template, target, fsConstants.COPYFILE_EXCL);
  } catch (err) {
    if ((err as NodeJS.ErrnoException)?.code === "EEXIST") {
      p.log.warn(`${target} already exists — leaving it untouched.`);
      p.log.info(
        `Compare against the latest template: diff ${target} ${template}`,
      );
      p.outro("Nothing changed.");
      return;
    }
    p.log.error(
      `Failed to copy template: ${err instanceof Error ? err.message : String(err)}`,
    );
    process.exit(1);
  }
  p.log.success(`Wrote ${target}`);
  p.note(
    [
      "All keys are commented out by default. Uncomment the ones you want.",
      "",
      "Common next steps:",
      "  1. Pick an LLM provider key (ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / etc.)",
      "  2. Run `npx @agentmemory/agentmemory doctor` to verify the daemon sees them",
      "  3. Run `npx @agentmemory/agentmemory` to start the worker",
    ].join("\n"),
    "Next steps",
  );
  p.outro(`Edit ${target} and you're set.`);
}

async function startServerForDemo(): Promise<() => Promise<void>> {
  startupTimeouts();
  await assertRuntimePortOwnership();
  if (await isAgentmemoryReady()) {
    return async () => {};
  }

  beginStartup();

  const startedEngine = !skipEngine && !(await isEngineRunning() || await waitForPersistedNativeEngine());
  if (startedEngine) {
    const ok = await startEngine();
    if (!ok) {
      p.log.error("Could not start iii-engine for the demo.");
      p.note(installInstructions().join("\n"), "Setup required");
      throw new Error("iii-engine could not be started for the demo.");
    }
    if (!(await waitForEngine())) {
      printCapturedStartupStderr();
      throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));
    }
  }

  await startWorkerForEngineState();

  return async () => {
    if (importedStartupWorker && readWorkerPidfile() === process.pid) clearWorkerPidfile();
    if (startedEngine) await cleanupFailedStartup();
  };
}

async function runDemo() {
  const port = getRestPort();
  const base = `http://localhost:${port}`;
  p.intro("agentmemory demo");

  const serve = args.includes("--serve");
  let teardown: () => Promise<void> = async () => {};

  if (serve) {
    teardown = await startServerForDemo();
  } else if (!(await isAgentmemoryReady())) {
    p.log.error(
      `agentmemory worker not reachable on port ${port} (livez probe failed). Something may be on the port but it isn't serving /agentmemory/*.`,
    );
    p.log.info("Start it with: npx @agentmemory/agentmemory");
    p.log.info("Or run a one-command demo with: npx @agentmemory/agentmemory demo --serve");
    process.exit(1);
  }

  try {
    await runDemoBody(base);
  } finally {
    await teardown();
  }

  if (serve) {
    process.exit(0);
  }
}

async function runDemoBody(base: string) {
  const demoProject = "/tmp/agentmemory-demo";
  const sessions = buildDemoSessions();

  const sSeed = p.spinner();
  sSeed.start("Seeding 3 demo sessions with realistic observations...");

  let totalObs = 0;
  for (const session of sessions) {
    totalObs += await seedDemoSession(base, demoProject, session);
  }

  sSeed.stop(`Seeded ${totalObs} observations across ${sessions.length} sessions`);

  const queries = [
    "jwt auth middleware",
    "database performance optimization",
    "rate limiting",
  ];

  const sQuery = p.spinner();
  sQuery.start(`Running ${queries.length} smart-search queries...`);

  const results: SearchResult[] = [];
  for (const query of queries) {
    results.push(await runDemoSearch(base, query));
  }

  sQuery.stop("Search complete");

  // Only claim the semantic-recall win when the search actually hit.
  // Without an embedding key this query returns 0 hits, and asserting
  // success over a visibly failed search reads as a lie.
  const semanticHits =
    results.find((r) => r.query === "database performance optimization")
      ?.hits ?? 0;
  const lines = [
    `Project:       ${demoProject}`,
    `Sessions:      ${sessions.length} seeded (${totalObs} observations)`,
    "",
    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)}`,
    ]),
    "",
    ...(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}"`)}`,
  ];

  p.note(lines.join("\n"), "demo complete");
  p.log.success("agentmemory is working. Point your agent at it and get back to coding.");
}

function runCommand(
  command: string,
  commandArgs: string[],
  options: { cwd?: string; label: string; optional?: boolean; timeoutMs?: number } = { label: "command" },
): boolean {
  const spinner = p.spinner();
  spinner.start(options.label);
  const result = spawnSync(command, commandArgs, {
    cwd: options.cwd || process.cwd(),
    stdio: "pipe",
    encoding: "utf-8",
    ...(options.timeoutMs !== undefined ? { timeout: options.timeoutMs, killSignal: "SIGKILL" as const } : {}),
  });

  if (result.status === 0) {
    spinner.stop(`${options.label} ${pc.green("✓")}`);
    return true;
  }

  const stderr = (result.stderr || "").toString().trim();
  const stdout = (result.stdout || "").toString().trim();
  const msg = stderr || stdout || "unknown error";

  if (options.optional) {
    spinner.stop(`${options.label} (skipped)`);
    p.log.warn(msg.slice(0, 300));
    return false;
  }

  spinner.stop(`${options.label} ${pc.red("✗")}`);
  p.log.error(msg.slice(0, 300));
  return false;
}

async function runUpgrade() {
  p.intro("agentmemory upgrade");

  const cwd = process.cwd();
  const hasPackageJson = existsSync(join(cwd, "package.json"));
  const hasPnpmLock = existsSync(join(cwd, "pnpm-lock.yaml"));

  const pnpmBin = whichBinary("pnpm");
  const npmBin = whichBinary("npm");

  p.log.info(`Working directory: ${cwd}`);
  const requireSuccess = (ok: boolean, label: string): void => {
    if (!ok) {
      p.log.error(`Upgrade aborted: ${label} failed.`);
      process.exit(1);
    }
  };

  if (hasPackageJson) {
    const usePnpm = !!pnpmBin && hasPnpmLock;
    if (usePnpm && pnpmBin) {
      const installOk = runCommand(pnpmBin, ["install"], {
        label: "Refreshing dependencies (pnpm install)",
      });
      requireSuccess(installOk, "pnpm install");
      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) {
      const installOk = runCommand(npmBin, ["install"], {
        label: "Refreshing dependencies (npm install)",
      });
      requireSuccess(installOk, "npm install");
      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.");
    }
  } else {
    p.log.warn("No package.json in current directory. Skipping JS dependency upgrade.");
  }

  const upgradeEngine = await p.confirm({
    message: "Re-run the iii-engine install script (curl | sh)?",
    initialValue: true,
  });
  if (p.isCancel(upgradeEngine)) {
    p.cancel("Cancelled.");
    return process.exit(0);
  }
  if (upgradeEngine === true) {
    await runIiiInstaller();
  } else {
    p.log.info("Skipped iii-engine installer.");
  }

  p.note(
    [
      "Upgrade flow completed.",
      "",
      "Recommended next steps:",
      "  1) agentmemory status",
      "  2) npm/pnpm test",
      "  3) restart agentmemory process",
    ].join("\n"),
    "agentmemory upgrade",
  );
}

function pidAlive(pid: number): boolean {
  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 as NodeJS.ErrnoException)?.code === "EPERM";
  }
}

async function signalAndWait(
  pid: number,
  initialSignal: NodeJS.Signals,
  timeoutMs: number,
): Promise<boolean> {
  try {
    process.kill(pid, initialSignal);
  } catch (err) {
    const code = (err as NodeJS.ErrnoException)?.code;
    if (code === "ESRCH") return true;
    if (code === "EPERM") {
      p.log.warn(`No permission to signal pid ${pid}. Try: kill ${pid}`);
      return false;
    }
    vlog(`${initialSignal} ${pid}: ${err instanceof Error ? err.message : String(err)}`);
    return false;
  }
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    if (!pidAlive(pid)) return true;
    await new Promise((r) => setTimeout(r, 200));
  }
  if (!pidAlive(pid)) return true;
  try {
    process.kill(pid, "SIGKILL");
  } catch (err) {
    if ((err as NodeJS.ErrnoException)?.code === "ESRCH") return true;
    vlog(`SIGKILL ${pid}: ${err instanceof Error ? err.message : String(err)}`);
    return false;
  }
  await new Promise((r) => setTimeout(r, 200));
  return !pidAlive(pid);
}

// Shared worker-reap: SIGTERM with a grace window sized for the worker's
// shutdown flush (index snapshots land via the engine, so the worker must
// die before the engine does, with time to commit).
async function waitForEngineFlush(): Promise<void> {
  let stateBackend: "file" | "redis" = "file";
  try {
    stateBackend = getStateBackend();
  } catch {}
  const composeState = readEngineState();
  if (composeState?.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: string[] = [];
  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 / 1000).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: number, graceMs: number): Promise<boolean> {
  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;
}

type NativeRemovalStopResult =
  | { ok: true; stoppedEnginePids: number }
  | { ok: false; reason: string };

async function stopNativeEngineForRemoval(): Promise<NativeRemovalStopResult> {
  const port = getRestPort();
  const workerPid = readWorkerPidfile();
  const enginePids = new Set<number>(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, 5000))) {
      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", 3000);
    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: number): string {
  if (IS_WINDOWS) return "";
  try {
    return execFileSync("ps", ["-p", String(pid), "-o", "comm="], {
      encoding: "utf-8",
      stdio: ["ignore", "pipe", "ignore"],
    }).trim();
  } catch {
    return "";
  }
}

// Positive identity beats a denylist: the engine is always the `iii`
// binary (spawned from PATH or ~/.agentmemory/bin), so any other process
// holding the port — an SSH forward or a stray dev server, for example —
// must not be adopted or signaled. A denylist failed open for every name
// it did not know.
function isForeignPortHolder(comm: string): boolean {
  if (!comm) return false;
  const base = comm.split("/").pop() || comm;
  return base !== "iii" && !base.startsWith("iii-");
}

function findEnginePidsByPort(port: number): number[] {
  if (IS_WINDOWS) return [];
  const lsof = whichBinary("lsof");
  if (!lsof) return [];
  // -sTCP:LISTEN restricts to listening server sockets only. Without
  // this, lsof also returns client-side PIDs (any process with an
  // active TCP connection to :port), which includes the agentmemory
  // CLI itself thanks to the keep-alive fetch in isEngineRunning().
  // signalAndWait would then SIGKILL its own parent — exit code 137.
  const selfPid = process.pid;
  try {
    const out = execFileSync(lsof, ["-i", `:${port}`, "-sTCP:LISTEN", "-t"], {
      encoding: "utf-8",
      stdio: ["ignore", "pipe", "ignore"],
    });
    return out
      .split(/\s+/)
      .map((s) => parseInt(s, 10))
      .filter((n) => Number.isFinite(n) && n > 0 && n !== selfPid);
  } catch (err) {
    vlog(`lsof :${port}: ${err instanceof Error ? err.message : String(err)}`);
    return [];
  }
}

async function runStop(): Promise<void> {
  const savedState = readEngineState();
  if (savedState?.kind === "docker") {
    p.intro("agentmemory stop");
    p.log.error(legacyDockerStateMessage(savedState));
    process.exit(1);
  }
  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);
  }
  await assertRuntimePortOwnership();
  p.intro("agentmemory stop");
  const port = getRestPort();
  const state = readEngineState();
  const running = await isEngineRunning();
  const force = args.includes("--force");

  if (state?.kind === "compose") {
    const ownedDaemonAlive = Boolean(state.composePid && pidAlive(state.composePid));
    if (ownedDaemonAlive && !composePidMatches(state.composePid!, state)) {
      p.log.error(`Recorded Compose pid ${state.composePid} does not match the saved daemon identity; refusing to invoke Compose control or signal it. Lifecycle state was preserved.`);
      process.exit(1);
    }
    if (running && !ownedDaemonAlive) {
      p.log.error("The REST endpoint is responding, but the recorded Compose daemon is not alive. Refusing to stop or clear an engine that may be unrelated; restore the owning daemon or inspect the endpoint manually.");
      process.exit(1);
    }
    if (running && ownedDaemonAlive) {
      try {
        await composeCall({ engineUrl: state.engineUrl, namespace: state.namespace, functionId: "compose::down", file: state.file, timeoutMs: 60_000 });
      } 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) {
      const childrenStopped = await terminateComposeChildren(state);
      if (!childrenStopped) {
        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", 20_000))) {
        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);
  const pidfilePid = readEnginePidfile();
  // read the worker pid up front so the engine-down branch
  // can still reap an orphaned worker process (the common failure mode
  // where a wrapper script kept the worker alive across engine restarts).
  const workerPid = readWorkerPidfile();

  if (!running) {
    if (portPids.length === 0 && pidfilePid === null && workerPid === null) {
      clearEnginePidfile();
      clearEngineState();
      clearWorkerPidfile();
      p.outro("Nothing to stop.");
      return;
    }
    if (workerPid !== null && portPids.length === 0 && pidfilePid === null) {
      // Engine already gone but worker is lingering — reap it directly
      // instead of preserving for manual cleanup.
      const s = p.spinner();
      s.start(`Stopping orphaned agentmemory worker (pid ${workerPid})...`);
      const ok = await signalAndWait(workerPid, "SIGTERM", SHUTDOWN_HARD_EXIT_MS + 1000);
      s.stop(ok ? `Stopped worker pid ${workerPid}` : `Failed to stop worker pid ${workerPid}`);
      clearEnginePidfile();
      clearEngineState();
      clearWorkerPidfile();
      if (!ok) {
        p.log.error(`Worker pid ${workerPid} survived SIGKILL. Investigate with \`ps\`.`);
        process.exit(1);
      }
      p.outro("Stopped orphaned worker. Memories persisted to disk.");
      return;
    }
    const survivors = new Set<number>(portPids);
    if (pidfilePid) survivors.add(pidfilePid);
    if (workerPid) survivors.add(workerPid);
    p.log.warn(
      `Engine not responding on :${port}, but ${survivors.size} process(es) still hold the port or pidfile: ${[...survivors].join(", ")}`,
    );
    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);
  }

  const candidates = new Set<number>();
  if (pidfilePid) candidates.add(pidfilePid);
  for (const pid of portPids) candidates.add(pid);

  // stop must also reap the agentmemory worker process
  // (`node dist/index.mjs`). If only the engine is killed, the worker can
  // survive (detached spawn / signal not propagated) and reconnect to the
  // next engine as a duplicate registration. workerPid was read above so
  // the engine-down branch could also reap orphans.
  const workerCandidates = new Set<number>();
  if (workerPid) workerCandidates.add(workerPid);

  if (candidates.size === 0 && workerCandidates.size === 0) {
    p.log.error(
      `Could not locate engine process. Try:\n  ${IS_WINDOWS ? "netstat -ano | findstr :" + port : "lsof -i :" + port + " -t | xargs kill -9"}`,
    );
    process.exit(1);
  }

  let allStopped = true;
  // stop worker first, then engine. The worker's shutdown
  // handler calls indexPersistence.save() -> kv.set() -> iii state::set
  // to flush BM25/vector snapshots + audit rows. Killing iii first
  // leaves those writes with no engine to land on, and the index +
  // observations end up as in-memory state the iii process never
  // persists. Worker SIGTERM grace bumped 3s -> 5s to give a large
  // index a real chance to commit before the engine goes away.
  for (const pid of workerCandidates) {
    if (!(await stopWorkerPid(pid, SHUTDOWN_HARD_EXIT_MS + 1000))) allStopped = false;
  }
  if (workerCandidates.size > 0 && [...candidates].some((pid) => !workerCandidates.has(pid))) {
    await waitForEngineFlush();
  }
  const skippedForeign: Array<{ pid: number; comm: string }> = [];
  for (const pid of candidates) {
    if (workerCandidates.has(pid)) continue;
    // Last-line guard against a stale/poisoned pidfile or a port-forward
    // holding :port — signaling its process could stop unrelated services.
    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", 3000);
    s.stop(ok ? `Stopped pid ${pid}` : `Failed to stop pid ${pid}`);
    if (!ok) allStopped = false;
  }

  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\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) {
    p.log.error("One or more processes survived SIGKILL. Investigate with `ps`.");
    process.exit(1);
  }
  p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
}

async function runMcp(): Promise<void> {
  await import("./mcp/standalone.js");
}

async function runConnectCmd(): Promise<void> {
  const { runConnect } = await import("./cli/connect/index.js");
  await runConnect(args.slice(1));
}

async function runImportJsonl(): Promise<void> {
  // Long-form flags that take a value. Their value tokens must be
  // consumed alongside the flag so they don't leak into positional
  // args (e.g. `--port 3114 import-jsonl` would otherwise turn
  // 3114 into pathArg).
  const VALUE_FLAGS = new Set(["--port", "--tools", "--data-dir"]);
  let maxFiles: number | undefined;
  const tail = args.slice(1);
  const positional: string[] = [];
  for (let i = 0; i < tail.length; i++) {
    const a = tail[i]!;
    if (a === "--max-files") {
      const raw = tail[i + 1];
      const parsed = raw !== undefined ? parseInt(raw, 10) : NaN;
      if (Number.isInteger(parsed) && parsed > 0) {
        maxFiles = parsed;
      } else if (raw !== undefined) {
        p.log.warn(`Ignoring --max-files ${raw}: expected a positive integer.`);
      }
      i++;
      continue;
    }
    if (a.startsWith("--max-files=")) {
      const raw = a.slice("--max-files=".length);
      const parsed = parseInt(raw, 10);
      if (Number.isInteger(parsed) && parsed > 0) {
        maxFiles = parsed;
      } else {
        p.log.warn(`Ignoring --max-files=${raw}: expected a positive integer.`);
      }
      continue;
    }
    if (VALUE_FLAGS.has(a)) {
      i++;
      continue;
    }
    if (a.startsWith("-")) continue;
    positional.push(a);
  }
  const pathArg = positional[0];

  const port = getRestPort();
  const base = `http://localhost:${port}`;

  let probeOk = false;
  let probeDetail = "";
  try {
    const probe = await fetch(`${base}/agentmemory/livez`, {
      signal: AbortSignal.timeout(2000),
    });
    probeOk = probe.ok;
    if (!probeOk) {
      const probeBody = await probe.text().catch(() => "");
      probeDetail = `reachable but unhealthy (HTTP ${probe.status}${probeBody ? `: ${probeBody.slice(0, 200)}` : ""})`;
    }
  } catch (err) {
    probeOk = false;
    const msg = err instanceof Error ? err.message : String(err);
    probeDetail = `unreachable (${msg})`;
  }
  if (!probeOk) {
    p.log.error(
      `agentmemory livez probe failed on port ${port}: ${probeDetail}. Start it with \`npx @agentmemory/agentmemory\` in another terminal, then re-run this command.`,
    );
    process.exit(1);
  }

  const body: Record<string, unknown> = {};
  if (pathArg) body["path"] = resolve(pathArg.startsWith("~") ? join(homedir(), pathArg.slice(1)) : pathArg);
  if (maxFiles !== undefined) body["maxFiles"] = maxFiles;

  const headers: Record<string, string> = { "content-type": "application/json", ...bearerHeaders(base) };

  p.log.info(`Importing JSONL from ${pathArg || "~/.claude/projects"}…`);
  const spinner = p.spinner();
  spinner.start("scanning files");

  try {
    const res = await fetch(`${base}/agentmemory/replay/import-jsonl`, {
      method: "POST",
      headers,
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(120_000),
    });
    const text = await res.text();
    let json: {
      success?: boolean;
      error?: string;
      imported?: number;
      sessionIds?: string[];
      observations?: number;
      discovered?: number;
      truncated?: boolean;
      traversalCapped?: boolean;
      maxFiles?: number;
      maxFilesUpperBound?: number;
    } = {};
    if (text.length > 0) {
      try {
        json = JSON.parse(text);
      } catch {
        spinner.stop("failed");
        p.log.error(
          `server returned non-JSON response (HTTP ${res.status}): ${text.slice(0, 200)}`,
        );
        process.exit(1);
      }
    }
    if (!res.ok || json.success !== true) {
      spinner.stop("failed");
      const detail =
        json.error ||
        (text.length === 0
          ? "empty response body"
          : json.success === undefined
            ? `HTTP ${res.status} (response missing success field)`
            : `HTTP ${res.status}`);
      if (res.status === 401) {
        p.log.error(
          `${detail}. Set AGENTMEMORY_SECRET to match the server's secret and re-run.`,
        );
      } else if (res.status === 404) {
        p.log.error(
          `${detail}. The running agentmemory server does not expose /agentmemory/replay/import-jsonl — upgrade to v0.8.13 or later.`,
        );
      } else {
        p.log.error(detail);
      }
      process.exit(1);
    }
    spinner.stop(
      `imported ${json.imported ?? 0} file(s), ${json.observations ?? 0} observation(s) across ${json.sessionIds?.length || 0} session(s)`,
    );
    if (json.truncated) {
      const cap = json.maxFiles ?? 200;
      const upper = json.maxFilesUpperBound ?? 1000;
      const discovered = json.discovered ?? 0;
      const skipped = discovered - (json.imported ?? 0);
      const discoveredLabel = json.traversalCapped
        ? `${discovered}+ (traversal halted at safety cap)`
        : String(discovered);
      const baseMsg = `Hit the ${cap}-file scan cap; ${skipped} of ${discoveredLabel} discovered file(s) were skipped.`;
      // If we already saw more than the server's hard cap (or the
      // walker stopped early), bumping --max-files won't help on its
      // own — recommend batching by subdirectory.
      if (discovered > upper || json.traversalCapped) {
        p.log.warn(
          `${baseMsg} Tree exceeds the server's --max-files limit of ${upper}; ` +
            `batch by subdirectory (run import-jsonl once per project under ~/.claude/projects).`,
        );
      } else {
        const suggested = Math.min(
          Math.max((discovered || cap) + 100, cap * 2),
          upper,
        );
        p.log.warn(
          `${baseMsg} Re-run with --max-files=${suggested} (max ${upper}) or batch by subdirectory.`,
        );
      }
    }
    if (json.sessionIds && json.sessionIds.length > 0) {
      p.log.info(`View at ${getViewerUrl()} → Replay tab`);
    }
  } catch (err) {
    spinner.stop("failed");
    if (err instanceof Error && err.name === "TimeoutError") {
      p.log.error("import timed out after 2 minutes");
    } else {
      p.log.error(err instanceof Error ? err.message : String(err));
    }
    process.exit(1);
  }
}

// ---------------------------------------------------------------------------
// `agentmemory remove` — clean uninstall.
//
// Planning logic lives in src/cli/remove-plan.ts so it's testable without
// touching $HOME. This function loads the manifest, builds the plan,
// double-confirms, then executes step by step.

function loadConnectManifest(home: string): ConnectManifest | null {
  const path = join(home, ".agentmemory", "backups", "connect-manifest.json");
  try {
    const raw = readFileSync(path, "utf-8");
    const parsed = JSON.parse(raw) as Partial<ConnectManifest>;
    if (Array.isArray(parsed?.installed)) {
      return { installed: parsed.installed };
    }
    return null;
  } catch {
    return null;
  }
}

function probeLocalBinIiiVersion(home: string): string | null {
  const path = legacyLocalBinIii(home);
  if (!existsSync(path)) return null;
  return iiiBinVersion(path);
}

function safeDelete(path: string): { ok: boolean; message: string } {
  try {
    if (!existsSync(path)) return { ok: true, message: `not present (${path})` };
    const st = statSync(path);
    if (st.isDirectory()) {
      rmSync(path, { recursive: true, force: true });
    } else {
      unlinkSync(path);
    }
    return { ok: true, message: `deleted ${path}` };
  } catch (err) {
    return {
      ok: false,
      message: `failed ${path}: ${err instanceof Error ? err.message : String(err)}`,
    };
  }
}

async function runRemove(): Promise<void> {
  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: RemoveOptions = {
    force,
    keepData,
  };
  const plan = buildRemovePlan(
    {
      home,
      runtimeDir: dirname(engineStatePath()),
      dataDir: dataDirResolution.dataDir,
      pinnedVersion: IIPINNED_VERSION,
      localBinIiiVersion,
      connectManifest,
    },
    options,
  );

  const applicable = plan.filter((it) => it.applicable);
  if (applicable.length === 0) {
    p.outro("Nothing to remove. agentmemory is already gone.");
    return;
  }

  p.note(formatPlan(plan), "destruction plan");

  if (!force) {
    const proceed = await p.confirm({
      message: "Proceed with these deletions?",
      initialValue: false,
    });
    if (p.isCancel(proceed) || proceed !== true) {
      p.cancel("Cancelled. Nothing was deleted.");
      return;
    }
    const sure = await p.confirm({
      message: "This is irreversible. Continue?",
      initialValue: false,
    });
    if (p.isCancel(sure) || sure !== true) {
      p.cancel("Cancelled. Nothing was deleted.");
      return;
    }
  }

  for (const item of plan) {
    if (!item.applicable) continue;

    // alwaysAsk items get a per-item confirmation even with --force.
    if (item.alwaysAsk) {
      const ok = await p.confirm({
        message: `${item.description} — really delete${item.path ? ` ${item.path}` : ""}?`,
        initialValue: false,
      });
      if (p.isCancel(ok) || ok !== true) {
        p.log.info(`skipped: ${item.id}`);
        continue;
      }
    }

    if (item.id === "stop-engine") {
      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;
    const r = safeDelete(item.path);
    if (r.ok) p.log.success(r.message);
    else p.log.error(r.message);
  }

  p.outro(
    "Done. agentmemory cleanly removed. The npm package itself: npm uninstall -g @agentmemory/agentmemory",
  );
}

async function runConsole(): Promise<void> {
  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(): Promise<void> {
  const code = await runCaptureCommand({
    base: getBaseUrl(),
    args: args.slice(1),
    secret: resolveClientSecret(getBaseUrl()),
  });
  process.exit(code);
}

async function runCompression(): Promise<void> {
  const base = getBaseUrl();
  const code = await runCompressionCommand({
    base,
    args: args.slice(1),
    secret: resolveClientSecret(base),
  });
  process.exit(code);
}

async function runGraphIndex(): Promise<void> {
  const base = getBaseUrl();
  process.exit(await runGraphIndexCommand({ base, args: args.slice(1), secret: resolveClientSecret(base) }));
}

const commands: Record<string, () => Promise<void>> = {
  init: runInit,
  connect: runConnectCmd,
  status: runStatus,
  console: runConsole,
  doctor: runDoctor,
  demo: runDemo,
  upgrade: runUpgrade,
  stop: runStop,
  remove: runRemove,
  mcp: runMcp,
  "import-jsonl": runImportJsonl,
  capture: runCapture,
  compression: runCompression,
  "graph-index": runGraphIndex,
};

const first = args[0] ?? "";
async function unknownCommand(): Promise<void> {
  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);
}
// Only a bare invocation or flag-style args boot the server; an unrecognized
// word is an error. Previously any typo (or a guessed subcommand like
// `agentmemory consolidate`) fell through to the full server boot and could
// break a running daemon.
const handler = commands[first] ?? (first && !first.startsWith("-") ? unknownCommand : main);
handler().catch(async (err) => {
  p.log.error(err instanceof Error ? err.message : String(err));
  const exitCode = await runStartupCleanup(1).catch(() => 1);
  process.exit(exitCode);
});