@danielblomma/cortex-mcp 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -0,0 +1,226 @@
+# Changelog
+
+## 2.4.2 — 2026-07-30
+
+### Changed
+
+- Split the Cortex CLI into cohesive command modules behind the existing
+  executable, preserving command names, arguments, streams, exit behavior,
+  JSON envelopes, Enterprise trust resolution, and `.context/mcp`
+  compatibility.
+- Established `scaffold/scripts/lib/ingest/` as the single canonical ingest
+  implementation for development and packaged entrypoints. Deterministic
+  output, worker fallback, trace checkpoints, and bounded result retention
+  remain unchanged.
+- Added versioned scaffold ownership and installed fingerprints. Forced
+  upgrades remove only unmodified obsolete Cortex-managed files, reject
+  modified or unsafe collisions, and preserve unknown files, configuration,
+  rules, ontology changes, Enterprise secrets, and agent instructions.
+- Extended release synchronization to keep the shipped MCP registry package
+  and Node runtime requirement aligned with `package.json`.
+
+### Upgrade
+
+- Upgrade the npm package, then run `cortex init --force`, `cortex bootstrap`,
+  and `cortex update`. Projects created before ownership state existed are
+  migrated only from hash-verified Cortex 2.4.1 scaffold files.
+
+## 2.4.1 — 2026-07-28
+
+### Security
+
+- Validated remote enterprise skill names, blocked symlink targets, and
+  added Cortex ownership markers so personal skill directories cannot be
+  overwritten or recursively deleted. Deletion targets are derived from
+  managed CLI roots instead of trusting cached absolute paths.
+- Bound license-cache reuse to the normalized endpoint and a one-way API-key
+  fingerprint. Malformed, future-dated, and expired cache assertions fail
+  closed; HTTP 401/403 responses reject authorization without grace.
+- Changed enterprise onboarding to read API keys from stdin and atomically
+  create `.context/enterprise.yml` with mode `0600`. Remote endpoints require
+  HTTPS, with a loopback-only HTTP exception for local development.
+- Bound user-global organization artifacts and host process detection to one
+  opaque Enterprise credential identity per OS user. A conflicting endpoint
+  is rejected, same-endpoint API-key rotation safely purges old marker-owned
+  skills and caches, and only one host-wide process scanner runs.
+- Moved unattributed process findings into a credential-bound, mode-`0600`
+  user-global queue instead of the first project's audit directory.
+- Enterprise admin commands now execute only package-owned trusted code.
+  Repository runtime modules and project-local state writes never execute with
+  root authority; persisted govern paths are not deletion authority.
+- Suppressed shared-proxy project audit events when a connection has no
+  trustworthy project attribution.
+- Added verified socket-based daemon stop/restart. Bootstrap now restarts an
+  already-running daemon so the upgraded security code replaces the old
+  in-memory runtime, and init repairs preserved Enterprise configs to `0600`.
+- Updated the frontend and packaged MCP dependency trees to patched PostCSS,
+  SDK, Hono, archive, URI, YAML, protobuf, ONNX ZIP, and Sharp versions. All
+  committed npm lockfiles now have a zero-vulnerability audit target.
+
+### Changed
+
+- Replace `sudo cortex enterprise <api-key>` with:
+
+  ```bash
+  printf '%s\n' "$CORTEX_API_KEY" |
+    sudo cortex enterprise install --api-key-stdin
+  ```
+
+- After updating the npm package, run `cortex init --force` and
+  `cortex bootstrap`. The latter safely restarts a verified running daemon;
+  an npm update alone does not activate this fix in an existing process.
+- Existing Enterprise users must then rerun the stdin install to create the
+  durable host-identity marker. Confirm
+  `cortex enterprise status --json` reports
+  `enterprise.host_identity_bound: true`; Cortex never auto-enrolls from a
+  repository config.
+- The minimum supported runtime is Node.js 20.9 (the first Node 20 LTS
+  release), required by the patched native embedding dependency chain.
+- Before re-enrollment, review legacy `~/.cortex/skills.local.json` records
+  without `credential_id`, back up each exact matching Claude/Codex skill
+  directory outside the discovery roots, and back up the state file. Ambiguous
+  legacy directories are deliberately not adopted or deleted automatically.
+
+### Rollout and emergency containment
+
+- Do not downgrade to 2.4.0: that reopens the remote skill traversal boundary.
+  Use a forward fix.
+- Before rollout, back up `.context/enterprise.yml` with ownership and mode
+  preserved. After restore, verify the correct owner and run
+  `chmod 600 .context/enterprise.yml`.
+- If suspicious remote organization content is observed, run
+  `cortex daemon stop` and stop Enterprise AI sessions until a forward fix is
+  installed. Enforced hooks intentionally fail closed while the daemon is
+  unavailable.
+- After rollout, verify `cortex daemon status` reports a verified PID,
+  `cortex enterprise status` is healthy, the config mode is `0600`, and a
+  canary organization sync cannot overwrite an unmanaged personal skill.
+
+## 2.4.0 — 2026-07-13
+
+### Added
+
+- Added a native agent behavior layer: dual plugin manifests (Claude Code +
+  Codex), five Cortex skills with trigger descriptions, a cached
+  SessionStart bootstrap that survives clear/compaction, and a Claude Code
+  marketplace entry.
+
+### Changed
+
+- Upgraded the `cortex init` AGENTS.md section from an update reminder to a
+  compact using-cortex bootstrap.
+
+## 2.3.0 — 2026-07-13
+
+### Added
+
+- Added `cortex pattern-evidence <file-path|entity-id>` for cited, structured
+  review evidence ordered by same file, module, feature area, and repository
+  fallback.
+- Integrated bounded, non-blocking pattern context into enterprise
+  `context.review` without changing policy pass/fail or workflow trust.
+
+### Changed
+
+- Made equal-score search ordering deterministic with stable entity/path
+  tie-breaks.
+- Added strict numeric validation for CLI query limits.
+- Fixed the enterprise runtime package-version lookup so compiled enterprise
+  tools load from the packaged MCP runtime.
+- Made `context.review` scope=changed list staged and untracked files in
+  repositories without commits instead of falling back to a full project
+  walk that ignores `.gitignore`.
+- Made pattern review context load the Cortex index once per review instead
+  of once per target, and cached the ranking reference-time scan per loaded
+  index.
+- Unified review path canonicalization and text comparison on the shared
+  pattern-evidence and search helpers.
+
+## 2.2.5 — 2026-06-21
+
+### Changed
+
+- Made the default embedding token-budget `auto` mode memory-aware: Cortex
+  still starts from the embedding model's maximum context, but degrades to a
+  safe cap when local memory headroom is unlikely to fit the full context.
+
+## 2.2.4 — 2026-06-20
+
+### Changed
+
+- Added an explicit embedding token-budget profile and benchmark support for
+  `CORTEX_EMBED_MAX_TOKENS`.
+- Kept the default `auto` token budget quality-preserving: Cortex uses the
+  embedding model's own maximum context unless a numeric cap is explicitly set.
+- Reduced embedding memory overhead by avoiding full normalized-text copies for
+  cached entities before deciding what needs re-embedding.
+
+## 2.1.0 — 2026-06-11
+
+New features and behavior changes, no API breaks.
+
+### Changed
+
+- **Default embedding model is now `jinaai/jina-embeddings-v2-base-code`**
+  (was `Xenova/all-MiniLM-L6-v2`). The old model truncated input at 512
+  tokens, which clipped the majority of file-level embeddings in typical
+  repositories and made code-oriented queries miss implementation files.
+  The jina code model has an 8192-token window. Override with
+  `CORTEX_EMBED_MODEL` as before.
+- **Embedding input text is no longer character-capped.** The previous
+  7000-char entity cap and 2000-char chunk-body preview (and the
+  `CORTEX_EMBED_MAX_CHARS` env var) were calibrated for small models. The
+  tokenizer's own 8192-token truncation is now the only limit.
+  `CORTEX_EMBED_MAX_CHARS` is removed and silently ignored if set.
+- **`graph_score` now uses a midrank percentile of relation degree within
+  the entity's own type** instead of `min(1, degree/4)`, which saturated at
+  degree >= 4 and made the graph ranking weight a constant for nearly every
+  entity. Percentiles are type-neutral (every type averages ~0.5), so
+  hub-heavy types such as rules cannot drown out leaf code.
+- **Default ranking weights changed** to `semantic: 0.55, graph: 0.10,
+  trust: 0.20, recency: 0.15` (was `0.40 / 0.25 / 0.20 / 0.15`). Graph
+  degree mostly measures how many rules constrain an entity, so it gets low
+  weight; this reweighting and the percentile graph_score were benchmarked
+  as a pair. **Existing projects keep their per-project `config.yaml` —
+  ranking weights are NOT updated automatically.** To adopt the new
+  defaults, edit `.context/config.yaml`:
+
+  ```yaml
+  ranking:
+    semantic: 0.55
+    graph: 0.10
+    trust: 0.20
+    recency: 0.15
+  ```
+
+### Added
+
+- **Markdown chunking.** `.md`/`.mdx` files are now chunked into H1–H3
+  heading-bounded sections (headings inside fenced code blocks are ignored,
+  preamble before the first heading is captured, empty sections are
+  skipped). Long sections are window-split with overlap, so prose gets
+  overlap while code stays symbol-chunked without it. Queries that target a
+  specific document section now return that section chunk directly.
+- `rules.yaml` is now preserved on re-scaffold (`cortex init --force`),
+  alongside `config.yaml`, so project-specific rules survive upgrades.
+
+### Upgrading an existing project
+
+1. `npm i -g @danielblomma/cortex-mcp@2.1.0`
+2. In the project: `cortex init --force` (re-scaffolds `.context/mcp` and
+   `.context/scripts`; your `config.yaml`, `rules.yaml`, notes and
+   decisions are preserved), then `cortex bootstrap`.
+3. `cortex update` — the stored embedding-model id no longer matches, so
+   this triggers a **full re-embed automatically**. Cost: roughly 2 minutes
+   per 1000 entities plus a one-time download of the jina ONNX model. The
+   embeddings file grows (768-dim vectors vs 384).
+4. Restart the MCP server (e.g. restart your editor/agent session) — the
+   compiled search code only loads on process start.
+
+Known quirk: the MCP server lazy-loads the embeddings file, so the first
+search immediately after a re-embed can be served from a stale cache —
+re-run the query.
+
+## 2.0.19 and earlier
+
+See git history (`git log --oneline`) and GitHub releases.

package/README.md

@@ -79,7 +79,7 @@ The result is an assistant that behaves as if it already knows your codebase, be
 
 ## Requirements
 
-- Node.js 20+
+- Node.js 20.9+ (Node 20 LTS or newer)
 - Git repository
 - Optional for MCP registration: `claude` and/or `codex` CLI in `PATH`
 
@@ -96,15 +96,36 @@ To upgrade an already-scaffolded project to a new Cortex version:
 ```bash
 npm i -g @danielblomma/cortex-mcp
 cortex init --force   # re-scaffolds .context runtime + .context/scripts
-cortex bootstrap
+cortex bootstrap     # rebuilds and safely restarts a verified running daemon
 cortex update
 ```
 
 `cortex init --force` preserves per-project files: `.context/config.yaml`,
-`.context/rules.yaml`, and your notes/decisions.
+`.context/rules.yaml`, `.context/enterprise.yml`, and your notes/decisions.
+It repairs existing Enterprise config permissions to `0600` without rewriting
+the file. An npm update alone does not replace code already loaded by the
+per-user daemon; `cortex bootstrap` performs the verified restart.
 
 Version-specific notes (see [CHANGELOG.md](CHANGELOG.md) for details):
 
+- **2.4.2**: `cortex init --force` now uses versioned ownership metadata to
+  remove only unmodified obsolete Cortex-managed files. Unknown files and
+  protected configuration, rules, ontology, Enterprise, and agent-instruction
+  content remain user-owned; modified obsolete files and unsafe collisions
+  fail the upgrade instead of being overwritten or deleted.
+- **2.4.1**: enterprise onboarding no longer accepts API keys as positional
+  arguments. Pipe the key to
+  `sudo cortex enterprise install --api-key-stdin`. Enterprise endpoints must
+  use HTTPS (loopback HTTP remains available for local development). Existing
+  Enterprise users must rerun that stdin install after `cortex bootstrap`;
+  enrollment is deliberately not inferred from repository config. Verify
+  `cortex enterprise status --json` reports
+  `enterprise.host_identity_bound: true`. One Enterprise endpoint is supported
+  per OS user because organization skills and host process detection are
+  user-global; an explicit install may rotate its API key. Before upgrading
+  legacy organization skills without Cortex ownership markers, back up and
+  move the exact reviewed directories listed by
+  `~/.cortex/skills.local.json` out of the Claude/Codex discovery roots.
 - **2.1.0**: the default embedding model changed, so the first
   `cortex update` after upgrading triggers a full re-embed automatically
   (~2 min per 1000 entities plus a one-time model download). The

package/bin/cli/arguments.mjs

@@ -0,0 +1,60 @@
+import path from "node:path";
+
+export function parseInitArgs(args) {
+  let target = process.cwd();
+  let force = false;
+  let bootstrap = false;
+  let connect = false;
+  let watch = true;
+
+  for (const arg of args) {
+    if (arg === "--force") {
+      force = true;
+      continue;
+    }
+    if (arg === "--bootstrap") {
+      bootstrap = true;
+      continue;
+    }
+    if (arg === "--connect") {
+      connect = true;
+      continue;
+    }
+    if (arg === "--no-connect") {
+      connect = false;
+      continue;
+    }
+    if (arg === "--watch") {
+      watch = true;
+      continue;
+    }
+    if (arg === "--no-watch") {
+      watch = false;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown init option: ${arg}`);
+    }
+    target = path.resolve(arg);
+  }
+
+  return { target, force, bootstrap, connect, watch };
+}
+
+export function parseConnectArgs(args) {
+  let target = process.cwd();
+  let skipBuild = false;
+
+  for (const arg of args) {
+    if (arg === "--skip-build") {
+      skipBuild = true;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown connect option: ${arg}`);
+    }
+    target = path.resolve(arg);
+  }
+
+  return { target, skipBuild };
+}

package/bin/cli/context-passthrough.mjs

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { restartDaemonAfterRuntimeUpgrade } from "./daemon.mjs";
+import { CONTEXT_SCRIPTS_REL } from "./paths.mjs";
+import { runCommand } from "./process.mjs";
+import {
+  ensureScaffoldExists,
+  hardenEnterpriseConfigPermissions,
+  initializeScaffold,
+  installAssistantHelpers,
+  isScaffoldOutOfDate,
+  isTruthyEnv,
+  maybeInstallGitHooks,
+} from "./scaffold.mjs";
+
+export const PASSTHROUGH_COMMANDS = new Set([
+  "bootstrap",
+  "update",
+  "status",
+  "ingest",
+  "embed",
+  "graph-load",
+  "dashboard",
+  "watch",
+  "refresh",
+  "memory-compile",
+  "memory-lint",
+  "doctor",
+]);
+
+const INDEX_MUTATING_COMMANDS = new Set([
+  "bootstrap",
+  "update",
+  "refresh",
+  "ingest",
+  "embed",
+  "graph-load",
+]);
+
+function invalidateSessionStatusCache(cwd) {
+  try {
+    fs.rmSync(
+      path.join(cwd, ".context", "cache", "session-status.json"),
+      { force: true },
+    );
+  } catch {
+    // Best effort: a stale cache only delays the status refresh.
+  }
+}
+
+export async function runContextCommand(cwd, contextArgs) {
+  const contextScript = path.join(cwd, CONTEXT_SCRIPTS_REL, "context.sh");
+  if (!fs.existsSync(contextScript)) {
+    throw new Error(`Missing ${contextScript}. Run 'cortex init' first.`);
+  }
+  try {
+    await runCommand("bash", [contextScript, ...contextArgs], cwd);
+  } finally {
+    if (INDEX_MUTATING_COMMANDS.has(contextArgs[0])) {
+      invalidateSessionStatusCache(cwd);
+    }
+  }
+}
+
+async function confirmPrompt(message) {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+  try {
+    const answer = (await rl.question(message)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+export async function maybeMigrateScaffold(targetDir, command) {
+  if (!isScaffoldOutOfDate(targetDir)) return;
+
+  const autoYes = isTruthyEnv(process.env.CORTEX_AUTO_MIGRATE);
+  const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+
+  console.error(
+    `[cortex] scaffold in ${targetDir} is out of date ` +
+      `(missing .context/scripts/doctor.sh, context runtime package.json, doctor subcommand in context.sh, ` +
+      `or carries a legacy mcp/ directory at the project root).`,
+  );
+
+  let proceed = autoYes;
+  if (!autoYes) {
+    if (!interactive) {
+      throw new Error(
+        `Cortex CLI ${process.env.CORTEX_CLI_VERSION ?? ""} needs an updated scaffold to run '${command}'. ` +
+          `Run 'cortex init --bootstrap' to upgrade, or re-run with CORTEX_AUTO_MIGRATE=true.`,
+      );
+    }
+    proceed = await confirmPrompt(
+      "[cortex] Upgrade scaffold now (runs 'cortex init --bootstrap')? [y/N] ",
+    );
+  }
+
+  if (!proceed) {
+    throw new Error(
+      "Scaffold upgrade declined. Run 'cortex init --bootstrap' manually to continue.",
+    );
+  }
+
+  console.error(`[cortex] migrating scaffold in ${targetDir}`);
+  ensureScaffoldExists();
+  initializeScaffold(targetDir, true);
+  installAssistantHelpers(targetDir);
+  await maybeInstallGitHooks(targetDir);
+  await runContextCommand(targetDir, ["bootstrap"]);
+  console.error(`[cortex] scaffold upgraded; continuing with '${command}'`);
+}
+
+export async function runPassthroughCommand(command, rest) {
+  const cwd = process.cwd();
+  await maybeMigrateScaffold(cwd, command);
+  if (command === "bootstrap") {
+    hardenEnterpriseConfigPermissions(cwd);
+  }
+  await runContextCommand(cwd, [command, ...rest]);
+  if (command === "bootstrap") {
+    await restartDaemonAfterRuntimeUpgrade(cwd);
+  }
+}

package/bin/cli/daemon.mjs

@@ -0,0 +1,157 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import {
+  callDaemon,
+  probeVerifiedDaemon,
+  stopVerifiedDaemon,
+} from "../daemon-control.mjs";
+import { resolveDaemonEntry } from "./project-runtime.mjs";
+
+function daemonDirPath() {
+  return path.join(process.env.HOME || os.homedir(), ".cortex");
+}
+
+function daemonPidFilePath() {
+  return path.join(daemonDirPath(), "daemon.pid");
+}
+
+function pidFileExists() {
+  return fs.existsSync(daemonPidFilePath());
+}
+
+function readPid() {
+  try {
+    const raw = fs.readFileSync(daemonPidFilePath(), "utf8").trim();
+    const pid = Number.parseInt(raw, 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPidAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "EPERM") {
+      return true;
+    }
+    return false;
+  }
+}
+
+async function daemonControlDeps() {
+  return {
+    readPid,
+    isPidAlive,
+    call: callDaemon,
+  };
+}
+
+async function waitForVerifiedDaemon(deps, timeoutMs = 5_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const probe = await probeVerifiedDaemon(deps, 250);
+    if (probe.verified) return probe;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return probeVerifiedDaemon(deps, 250);
+}
+
+export async function runDaemonCommand(args, options = {}) {
+  const sub = args[0] || "status";
+  const projectRoot = options.projectRoot || process.cwd();
+  const deps = await daemonControlDeps();
+  if (sub === "start") {
+    const existing = await probeVerifiedDaemon(deps);
+    if (existing.verified) {
+      console.log("Daemon already running.");
+      return;
+    }
+    if (existing.running) {
+      throw new Error(
+        `Refusing to replace unverified live pid ${existing.pid} (${existing.reason}).`,
+      );
+    }
+    const daemonDir = daemonDirPath();
+    fs.mkdirSync(daemonDir, { recursive: true });
+    const entry = resolveDaemonEntry(projectRoot);
+    if (!fs.existsSync(entry)) {
+      throw new Error(`Daemon entry not found: ${entry}. Build cortex first.`);
+    }
+    const logFd = fs.openSync(path.join(daemonDir, "daemon.log"), "a");
+    const child = spawn(process.execPath, [entry], {
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      cwd: projectRoot,
+      env: { ...process.env, CORTEX_PROJECT_ROOT: projectRoot },
+    });
+    child.unref();
+    fs.closeSync(logFd);
+    const started = await waitForVerifiedDaemon(deps);
+    if (!started.verified) {
+      throw new Error(
+        `Daemon did not complete its verified socket handshake (${started.reason}).`,
+      );
+    }
+    console.log(
+      `Daemon started (pid=${started.pid}). Log: ${path.join(daemonDir, "daemon.log")}`,
+    );
+    return;
+  }
+  if (sub === "stop") {
+    const result = await stopVerifiedDaemon(deps);
+    if (!result.stopped) {
+      console.log("Daemon not running.");
+      return;
+    }
+    console.log(`Daemon stopped (verified pid=${result.pid}).`);
+    return;
+  }
+  if (sub === "restart") {
+    await stopVerifiedDaemon(deps);
+    await runDaemonCommand(["start"], { projectRoot });
+    return;
+  }
+  if (sub === "status") {
+    const probe = await probeVerifiedDaemon(deps);
+    if (probe.verified) {
+      console.log(`Daemon running (verified pid=${probe.pid})`);
+    } else if (probe.running) {
+      console.log(
+        `Daemon state unsafe: live pid=${probe.pid}, identity not verified (${probe.reason}).`,
+      );
+    } else {
+      console.log("Daemon not running.");
+      if (pidFileExists()) {
+        console.log(`(stale pid file at ${daemonPidFilePath()})`);
+      }
+    }
+    return;
+  }
+  throw new Error(
+    `Unknown daemon subcommand: ${sub}. Try start|stop|restart|status`,
+  );
+}
+
+export async function restartDaemonAfterRuntimeUpgrade(projectRoot) {
+  const daemonEntry = resolveDaemonEntry(projectRoot);
+  if (!fs.existsSync(daemonEntry)) return;
+  const deps = await daemonControlDeps();
+  const probe = await probeVerifiedDaemon(deps);
+  if (!probe.running) return;
+  if (!probe.verified) {
+    throw new Error(
+      `Runtime upgraded, but live pid ${probe.pid} could not be verified. ` +
+        "Refusing to signal it; stop it manually after confirming ownership.",
+    );
+  }
+  console.log(
+    `[cortex] restarting verified daemon pid=${probe.pid} to activate the upgraded runtime`,
+  );
+  await runDaemonCommand(["restart"], { projectRoot });
+}