@danielblomma/cortex-mcp 2.2.5 → 2.4.1

package/scaffold/mcp/tests/ungoverned-scanner.test.mjs

@@ -5,6 +5,8 @@ import os from "node:os";
 import path from "node:path";
 
 import { runScanOnce, writeHostAuditEvent, startUngovernedScanner } from "../dist/daemon/ungoverned-scanner.js";
+import { claimEnterpriseHostIdentity } from "../dist/core/enterprise-host-identity.js";
+import { enterpriseCredentialId } from "../dist/core/license.js";
 
 function makeWorkspace(governMode, installs = null) {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "cortex-ungoverned-"));
@@ -41,7 +43,7 @@ test("writeHostAuditEvent appends one JSONL line per call", async () => {
   }
 });
 
-test("runScanOnce: writes audit event with action=logged in advisory mode", async () => {
+test("runScanOnce: does not write unattributed host process metadata into project audit", async () => {
   const { root } = makeWorkspace("advisory");
   try {
     const fakeProcs = [
@@ -54,20 +56,64 @@ test("runScanOnce: writes audit event with action=logged in advisory mode", asyn
     });
     assert.equal(findings.length, 1);
 
-    const date = new Date().toISOString().slice(0, 10);
-    const file = path.join(root, ".context", "audit", `host-events-${date}.jsonl`);
-    const events = fs.readFileSync(file, "utf8").trim().split("\n").map(JSON.parse);
-    assert.equal(events.length, 1);
-    assert.equal(events[0].event_type, "ungoverned_ai_session_detected");
-    assert.equal(events[0].cli, "claude");
-    assert.equal(events[0].mode, "advisory");
-    assert.equal(events[0].action, "logged");
-    assert.equal(events[0].host_id, "test-host");
+    assert.equal(
+      fs.existsSync(path.join(root, ".context", "audit")),
+      false,
+    );
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }
 });
 
+test("runScanOnce: writes detections only to the credential-bound user-global queue", async () => {
+  const { root } = makeWorkspace("advisory");
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "cortex-global-events-"));
+  const endpoint = "https://events.example.com";
+  const apiKey = "ent_global_events_12345678";
+  const credentialId = enterpriseCredentialId(endpoint, apiKey);
+  process.env.HOME = homeDir;
+  try {
+    assert.equal(
+      claimEnterpriseHostIdentity(credentialId, endpoint),
+      true,
+    );
+    await runScanOnce({
+      cwd: root,
+      credentialId,
+      detectorOptions: {
+        hostId: "host-global",
+        processes: [
+          {
+            pid: 4321,
+            ppid: 1,
+            user: os.userInfo().username,
+            comm: "claude",
+            args: "claude --prompt private",
+          },
+        ],
+      },
+    });
+
+    assert.equal(fs.existsSync(path.join(root, ".context", "audit")), false);
+    const queueDir = path.join(homeDir, ".cortex", "host-events");
+    const queueFile = fs.readdirSync(queueDir).find((name) =>
+      name.startsWith("ungoverned-")
+    );
+    assert.ok(queueFile);
+    assert.equal(fs.statSync(path.join(queueDir, queueFile)).mode & 0o777, 0o600);
+    const event = JSON.parse(
+      fs.readFileSync(path.join(queueDir, queueFile), "utf8").trim(),
+    );
+    assert.equal(event.credential_id, credentialId);
+    assert.equal(event.pid, 4321);
+    assert.match(event.args, /private/);
+  } finally {
+    delete process.env.HOME;
+    fs.rmSync(root, { recursive: true, force: true });
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});
+
 test("runScanOnce: enforced mode marks action=sigterm but our mock doesn't actually signal real procs", async () => {
   const { root } = makeWorkspace("enforced");
   try {
@@ -91,12 +137,11 @@ test("runScanOnce: enforced mode marks action=sigterm but our mock doesn't actua
       process.kill = origKill;
     }
 
-    const date = new Date().toISOString().slice(0, 10);
-    const file = path.join(root, ".context", "audit", `host-events-${date}.jsonl`);
-    const events = fs.readFileSync(file, "utf8").trim().split("\n").map(JSON.parse);
-    assert.equal(events[0].mode, "enforced");
-    assert.equal(events[0].action, "sigterm");
     assert.deepEqual(killed, [99999, "SIGTERM"]);
+    assert.equal(
+      fs.existsSync(path.join(root, ".context", "audit")),
+      false,
+    );
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }
@@ -127,9 +172,15 @@ test("runScanOnce: emits onFinding callback per detection", async () => {
 test("runScanOnce: skips Tier 1 CLIs that already have managed installs", async () => {
   const { root } = makeWorkspace("enforced");
   const managedClaudePath = path.join(root, "managed-settings.json");
-  fs.writeFileSync(managedClaudePath, "{}\n");
+  fs.writeFileSync(
+    managedClaudePath,
+    JSON.stringify({ allowManagedHooksOnly: true }) + "\n",
+  );
   const managedCodexPath = path.join(root, "requirements.toml");
-  fs.writeFileSync(managedCodexPath, "# managed\n");
+  fs.writeFileSync(
+    managedCodexPath,
+    "# Cortex govern — codex requirements (test).\n",
+  );
   fs.writeFileSync(
     path.join(root, ".context", "govern.local.json"),
     JSON.stringify({
@@ -160,16 +211,47 @@ test("runScanOnce: skips Tier 1 CLIs that already have managed installs", async
     const findings = await runScanOnce({
       cwd: root,
       mode: "enforced",
+      managedPathOverrides: {
+        claude: managedClaudePath,
+        codex: managedCodexPath,
+      },
       detectorOptions: { processes: fakeProcs, hostId: "test-host" },
     });
     assert.equal(findings.length, 1);
     assert.equal(findings[0].cli, "copilot");
 
-    const date = new Date().toISOString().slice(0, 10);
-    const file = path.join(root, ".context", "audit", `host-events-${date}.jsonl`);
-    const events = fs.readFileSync(file, "utf8").trim().split("\n").map(JSON.parse);
-    assert.equal(events.length, 1);
-    assert.equal(events[0].cli, "copilot");
+    assert.equal(fs.existsSync(path.join(root, ".context", "audit")), false);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("runScanOnce: forged persisted paths cannot suppress Tier 1 findings", async () => {
+  const { root } = makeWorkspace("advisory", {
+    claude: {
+      mode: "advisory",
+      path: "/bin/sh",
+      version: "forged",
+      frameworks: [],
+      installed_at: "now",
+    },
+  });
+  try {
+    const findings = await runScanOnce({
+      cwd: root,
+      mode: "advisory",
+      detectorOptions: {
+        processes: [{
+          pid: 7654,
+          ppid: 1,
+          user: os.userInfo().username,
+          comm: "claude",
+          args: "claude --prompt hi",
+        }],
+      },
+    });
+    assert.equal(findings.length, 1);
+    assert.equal(findings[0].cli, "claude");
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }

package/scaffold/mcp/tests/workflow-cli.test.mjs

@@ -5,6 +5,10 @@ import os from "node:os";
 import path from "node:path";
 
 import { runStageCommand } from "../dist/cli/stage.js";
+import { enterpriseCredentialId } from "../dist/core/license.js";
+
+const ENTERPRISE_ENDPOINT = "https://licenses.example.com";
+const ENTERPRISE_KEY = "ent_workflow_cli_12345678";
 
 const TINY_WORKFLOW = {
   id: "tiny",
@@ -41,7 +45,12 @@ function makeWorkspace() {
   fs.mkdirSync(path.join(dir, ".context"), { recursive: true });
   fs.writeFileSync(
     path.join(dir, ".context", "enterprise.yml"),
-    "enterprise:\n  api_key: test-key-for-cli-tests\n",
+    [
+      "enterprise:",
+      `  api_key: ${ENTERPRISE_KEY}`,
+      `  endpoint: ${ENTERPRISE_ENDPOINT}`,
+      "",
+    ].join("\n"),
     "utf8",
   );
   return dir;
@@ -53,6 +62,10 @@ function writeSyncedWorkflow(homeDir, workflowId, definition) {
   fs.writeFileSync(
     path.join(cortexDir, "workflows.local.json"),
     JSON.stringify({
+      credential_id: enterpriseCredentialId(
+        ENTERPRISE_ENDPOINT,
+        ENTERPRISE_KEY,
+      ),
       workflows: {
         [workflowId]: {
           workflow_id: workflowId,

package/scaffold/mcp/tests/workflow-synced-capabilities.test.mjs

@@ -10,6 +10,7 @@ import {
 } from "../dist/core/workflow/synced-capability-registry.js";
 import { evaluateToolCall } from "../dist/core/workflow/enforcement.js";
 import { createRun } from "../dist/core/workflow/run-lifecycle.js";
+import { enterpriseCredentialId } from "../dist/core/license.js";
 
 function makeWorkspace() {
   return fs.mkdtempSync(path.join(os.tmpdir(), "cortex-synced-caps-"));
@@ -49,6 +50,23 @@ function writeCache(dir, payload) {
   );
 }
 
+function configureEnterprise(cwd) {
+  const endpoint = "https://licenses.example.com";
+  const apiKey = "ent_capability_12345678";
+  fs.mkdirSync(path.join(cwd, ".context"), { recursive: true });
+  fs.writeFileSync(
+    path.join(cwd, ".context", "enterprise.yml"),
+    [
+      "enterprise:",
+      `  api_key: ${apiKey}`,
+      `  endpoint: ${endpoint}`,
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  return enterpriseCredentialId(endpoint, apiKey);
+}
+
 test("syncedCapabilitiesCachePath: defaults to ~/.cortex/capabilities.local.json", () => {
   const expected = path.join(os.homedir(), ".cortex", "capabilities.local.json");
   assert.equal(syncedCapabilitiesCachePath(), expected);
@@ -107,16 +125,33 @@ test("loadSyncedCapabilities: returns valid capability definitions", () => {
   assert.deepEqual(loaded["frontend-builder"].write_globs, ["src/components/**"]);
 });
 
+test("loadSyncedCapabilities: rejects a cache bound to another Enterprise identity", () => {
+  const dir = makeWorkspace();
+  writeCache(dir, {
+    credential_id: "identity-a",
+    capabilities: {
+      "frontend-builder": {
+        capability_name: "frontend-builder",
+        updated_at: "2026-05-07T12:00:00.000Z",
+        definition: FRONTEND_BUILDER,
+      },
+    },
+  });
+  assert.deepEqual(loadSyncedCapabilities(dir, "identity-b"), {});
+});
+
 test("evaluateToolCall integration: synced capability is consulted via merged registry", () => {
   const cwd = makeWorkspace();
   // Sandbox the home-dir-based loader.
   const fakeHome = makeWorkspace();
   process.env.HOME = fakeHome;
   try {
+    const credentialId = configureEnterprise(cwd);
     fs.mkdirSync(path.join(fakeHome, ".cortex"), { recursive: true });
     fs.writeFileSync(
       path.join(fakeHome, ".cortex", "capabilities.local.json"),
       JSON.stringify({
+        credential_id: credentialId,
         capabilities: {
           "frontend-builder": {
             capability_name: "frontend-builder",
@@ -163,6 +198,7 @@ test("evaluateToolCall integration: synced capability with same name as bundled
   const fakeHome = makeWorkspace();
   process.env.HOME = fakeHome;
   try {
+    const credentialId = configureEnterprise(cwd);
     // Override the bundled "builder" capability with a much stricter version
     // — only test files writable.
     const stricterBuilder = {
@@ -176,6 +212,7 @@ test("evaluateToolCall integration: synced capability with same name as bundled
     fs.writeFileSync(
       path.join(fakeHome, ".cortex", "capabilities.local.json"),
       JSON.stringify({
+        credential_id: credentialId,
         capabilities: {
           builder: {
             capability_name: "builder",

package/scaffold/mcp/tests/workflow-synced-registry.test.mjs

@@ -11,6 +11,7 @@ import {
 import { resolveWorkflowDefinition } from "../dist/core/workflow/resolution.js";
 import { runWorkflowStart } from "../dist/core/workflow/mcp-tools.js";
 import { SECURE_BUILD_WORKFLOW } from "../dist/core/workflow/default-workflows.js";
+import { enterpriseCredentialId } from "../dist/core/license.js";
 
 function makeWorkspace() {
   return fs.mkdtempSync(path.join(os.tmpdir(), "cortex-synced-registry-"));
@@ -49,6 +50,23 @@ function writeCache(dir, payload) {
   );
 }
 
+function configureEnterprise(cwd) {
+  const endpoint = "https://licenses.example.com";
+  const apiKey = "ent_workflow_12345678";
+  fs.mkdirSync(path.join(cwd, ".context"), { recursive: true });
+  fs.writeFileSync(
+    path.join(cwd, ".context", "enterprise.yml"),
+    [
+      "enterprise:",
+      `  api_key: ${apiKey}`,
+      `  endpoint: ${endpoint}`,
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  return enterpriseCredentialId(endpoint, apiKey);
+}
+
 test("syncedWorkflowsCachePath: defaults to ~/.cortex/workflows.local.json", () => {
   const expected = path.join(os.homedir(), ".cortex", "workflows.local.json");
   assert.equal(syncedWorkflowsCachePath(), expected);
@@ -110,6 +128,22 @@ test("loadSyncedWorkflows: returns valid workflow definitions keyed by workflow_
   assert.equal(loaded.tiny.stages.length, 2);
 });
 
+test("loadSyncedWorkflows: rejects a cache bound to another Enterprise identity", () => {
+  const dir = makeWorkspace();
+  writeCache(dir, {
+    credential_id: "identity-a",
+    workflows: {
+      tiny: {
+        workflow_id: "tiny",
+        version: 1,
+        updated_at: "2026-05-06T12:00:00.000Z",
+        definition: TINY_WORKFLOW,
+      },
+    },
+  });
+  assert.deepEqual(loadSyncedWorkflows(dir, "identity-b"), {});
+});
+
 test("resolveWorkflow integration: synced workflow takes precedence over bundled default", () => {
   // We can't easily intercept loadSyncedWorkflows() from inside
   // mcp-tools.ts (it reads from a fixed home-dir path). Instead, exercise
@@ -148,10 +182,12 @@ test("resolveWorkflow integration: synced cache adds new workflow_ids beyond def
   const fakeHome = makeWorkspace();
   process.env.HOME = fakeHome;
   try {
+    const credentialId = configureEnterprise(cwd);
     fs.mkdirSync(path.join(fakeHome, ".cortex"), { recursive: true });
     fs.writeFileSync(
       path.join(fakeHome, ".cortex", "workflows.local.json"),
       JSON.stringify({
+        credential_id: credentialId,
         workflows: {
           tiny: {
             workflow_id: "tiny",
@@ -215,7 +251,10 @@ test("resolveWorkflowDefinition: unknown workflow errors list bundled and synced
   const fakeHome = makeWorkspace();
   process.env.HOME = fakeHome;
   try {
+    const cwd = makeWorkspace();
+    const credentialId = configureEnterprise(cwd);
     writeCache(path.join(fakeHome, ".cortex"), {
+      credential_id: credentialId,
       workflows: {
         tiny: {
           workflow_id: "tiny",
@@ -226,7 +265,7 @@ test("resolveWorkflowDefinition: unknown workflow errors list bundled and synced
       },
     });
     assert.throws(
-      () => resolveWorkflowDefinition("missing-workflow"),
+      () => resolveWorkflowDefinition("missing-workflow", { cwd }),
       /Available bundled: secure-build\. Available synced: tiny\./,
     );
   } finally {

package/scaffold/scripts/dashboard.mjs

@@ -2,7 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -286,12 +286,11 @@ function getLocalCliVersion() {
   }
 
   try {
-    const output = execSync("cortex --version", {
+    const output = execFileSync("cortex", ["--version"], {
       cwd: REPO_ROOT,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf8",
       timeout: 1500,
-      shell: true,
     }).trim();
     if (parseVersion(output)) {
       return output;
@@ -331,13 +330,12 @@ function getVersionStatus() {
     } else {
       try {
         const npmCache = path.join(CACHE_DIR, "npm-cache");
-        const latestRaw = execSync("npm view github:DanielBlomma/cortex version --json", {
+        const latestRaw = execFileSync("npm", ["view", "github:DanielBlomma/cortex", "version", "--json"], {
           cwd: REPO_ROOT,
           stdio: ["ignore", "pipe", "pipe"],
           encoding: "utf8",
           timeout: VERSION_LOOKUP_TIMEOUT_MS,
           env: { ...process.env, NPM_CONFIG_CACHE: npmCache },
-          shell: true,
         }).trim();
         const parsedLatest = JSON.parse(latestRaw);
         const latest = Array.isArray(parsedLatest)
@@ -352,20 +350,30 @@ function getVersionStatus() {
             latest,
             message: "unsupported latest version format",
           };
-        } else if (compareVersions(latestParsed, localParsed) > 0) {
-          value = {
-            state: "update-available",
-            local,
-            latest,
-            message: null,
-          };
         } else {
-          value = {
-            state: "current",
-            local,
-            latest,
-            message: null,
-          };
+          const comparison = compareVersions(latestParsed, localParsed);
+          if (comparison > 0) {
+            value = {
+              state: "update-available",
+              local,
+              latest,
+              message: null,
+            };
+          } else if (comparison < 0) {
+            value = {
+              state: "local-newer",
+              local,
+              latest,
+              message: "local build is newer than published version",
+            };
+          } else {
+            value = {
+              state: "current",
+              local,
+              latest,
+              message: null,
+            };
+          }
         }
       } catch (error) {
         value = {
@@ -690,6 +698,9 @@ function render(data, isTTY) {
   if (data.version.state === "update-available") {
     lines.push(sideBorder(
       `Version: ${bold(col("UPDATE AVAILABLE", C.red))} ${col(`${data.version.local} -> ${data.version.latest}`, C.red)}`, w));
+  } else if (data.version.state === "local-newer") {
+    lines.push(sideBorder(
+      `Version: ${col(data.version.local, C.yellow)} ${dim(`Published: ${data.version.latest} local newer`)}`, w));
   } else if (data.version.state === "current") {
     lines.push(sideBorder(
       `Version: ${col(data.version.local, C.green)} ${dim(`Latest: ${data.version.latest}`)}`, w));

package/scaffold/scripts/doctor.sh

@@ -180,15 +180,33 @@ fi
 
 # Quick runtime import check
 if [[ -f "$MCP_DIR/dist/server.js" ]] && [[ -d "$MCP_DIR/node_modules" ]]; then
-  MCP_CHECK=$(cd "$REPO_ROOT" && timeout 10 node -e '
-    const start = Date.now();
-    try {
-      require("./.context/mcp/dist/graph.js");
-      console.log("ok " + (Date.now() - start));
-    } catch(e) {
-      console.log("fail " + e.message);
+  MCP_CHECK=$(cd "$REPO_ROOT" && node -e '
+    const { spawnSync } = require("node:child_process");
+    const timeoutMs = Number(process.env.CORTEX_DOCTOR_GRAPH_TIMEOUT_MS || 30000);
+    const probe = [
+      "const start = Date.now();",
+      "try {",
+      "  require(\"./.context/mcp/dist/graph.js\");",
+      "  console.log(\"ok \" + (Date.now() - start));",
+      "} catch (e) {",
+      "  console.log(\"fail \" + (e && e.message ? e.message : String(e)));",
+      "  process.exitCode = 1;",
+      "}"
+    ].join("\n");
+    const result = spawnSync(process.execPath, ["-e", probe], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: timeoutMs
+    });
+    if (result.error && result.error.code === "ETIMEDOUT") {
+      console.log("fail timeout after " + timeoutMs + "ms");
+    } else if (result.error) {
+      console.log("fail " + result.error.message);
+    } else {
+      const lines = String(result.stdout || "").trim().split(/\r?\n/).filter(Boolean);
+      console.log(lines[lines.length - 1] || ("fail exit " + (result.status ?? "unknown")));
     }
-  ' 2>/dev/null || echo "fail timeout")
+  ' 2>/dev/null || echo "fail graph check crashed")
   if [[ "$MCP_CHECK" == ok* ]]; then
     MS="${MCP_CHECK#ok }"
     pass "Graph module loads (${MS}ms)"

package/scaffold/scripts/ingest.mjs

@@ -457,11 +457,11 @@ function parseRules(rulesText) {
 function walkDirectory(directoryPath, files) {
   const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
   for (const entry of entries) {
-    if (entry.isDirectory() && SKIP_DIRECTORIES.has(entry.name)) {
+    const absolutePath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory() && shouldSkipDirectory(absolutePath, entry.name)) {
       continue;
     }
 
-    const absolutePath = path.join(directoryPath, entry.name);
     if (entry.isDirectory()) {
       walkDirectory(absolutePath, files);
       continue;
@@ -473,10 +473,40 @@ function walkDirectory(directoryPath, files) {
   }
 }
 
+function shouldSkipDirectory(absolutePath, entryName) {
+  if (entryName === "bin" && path.resolve(path.dirname(absolutePath)) === REPO_ROOT) {
+    return false;
+  }
+  return SKIP_DIRECTORIES.has(entryName);
+}
+
+function normalizeSourcePrefix(sourcePath) {
+  const source = toPosixPath(sourcePath).replace(/^\.\/+/, "").replace(/\/+$/, "");
+  return source === "." ? "" : source;
+}
+
+function normalizeRelativePath(relPath) {
+  return toPosixPath(relPath).replace(/^\.\/+/, "").replace(/\/+$/, "");
+}
+
+function hasSkippedDirectorySegment(relPath) {
+  const parts = normalizeRelativePath(relPath).split("/").filter(Boolean);
+  return parts.some((part, index) => {
+    if (part === "bin" && index === 0) {
+      return false;
+    }
+    return SKIP_DIRECTORIES.has(part);
+  });
+}
+
 function hasSourcePrefix(relPath, sourcePaths) {
+  const normalizedRelPath = normalizeRelativePath(relPath);
+  if (!normalizedRelPath || hasSkippedDirectorySegment(normalizedRelPath)) {
+    return false;
+  }
   return sourcePaths.some((sourcePath) => {
-    const source = toPosixPath(sourcePath).replace(/\/+$/, "");
-    return relPath === source || relPath.startsWith(`${source}/`);
+    const source = normalizeSourcePrefix(sourcePath);
+    return source === "" || normalizedRelPath === source || normalizedRelPath.startsWith(`${source}/`);
   });
 }
 
@@ -627,6 +657,9 @@ function collectCandidateFiles(sourcePaths, mode) {
   }
 
   for (const sourcePath of sourcePaths) {
+    if (hasSkippedDirectorySegment(sourcePath)) {
+      continue;
+    }
     const absoluteSourcePath = path.resolve(REPO_ROOT, sourcePath);
     if (!fs.existsSync(absoluteSourcePath)) {
       continue;

package/scaffold/scripts/status.sh

@@ -198,11 +198,12 @@ try {
 
 node -e '
 const path = require("node:path");
-const { execSync } = require("node:child_process");
+const { execFileSync, execSync } = require("node:child_process");
 
 const repoRoot = process.argv[1];
 const cacheDir = process.argv[2];
 const localVersionEnv = process.argv[3] || "";
+const VERSION_LOOKUP_TIMEOUT_MS = Number(process.env.CORTEX_VERSION_LOOKUP_TIMEOUT_MS || 8000);
 
 function parseVersion(value) {
   const match = String(value || "").trim().match(/^v?(\d+)\.(\d+)\.(\d+)$/);
@@ -225,7 +226,7 @@ function getLocalVersion() {
   }
 
   try {
-    const output = execSync("cortex --version", {
+    const output = execFileSync("cortex", ["--version"], {
       cwd: repoRoot,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf8",
@@ -282,11 +283,11 @@ try {
     const npmCache = path.join(cacheDir, "npm-cache");
     let latestRaw = "";
     try {
-      latestRaw = execSync("npm view github:DanielBlomma/cortex version --json", {
+      latestRaw = execFileSync("npm", ["view", "github:DanielBlomma/cortex", "version", "--json"], {
         cwd: repoRoot,
         stdio: ["ignore", "pipe", "pipe"],
         encoding: "utf8",
-        timeout: 2500,
+        timeout: VERSION_LOOKUP_TIMEOUT_MS,
         env: { ...process.env, NPM_CONFIG_CACHE: npmCache }
       }).trim();
     } catch (error) {
@@ -317,13 +318,19 @@ try {
     process.exit(0);
   }
 
-  const hasUpdate = compareVersions(latestParsed, localParsed) > 0;
+  const comparison = compareVersions(latestParsed, localParsed);
   console.log(`[status] cortex_latest_version=${latestVersion}`);
 
-  if (hasUpdate) {
+  if (comparison > 0) {
+    console.log("[status] cortex_version_state=update-available");
     console.log("[status] cortex_update_available=yes");
     console.log("[status] run: npm i -g github:DanielBlomma/cortex");
+  } else if (comparison < 0) {
+    console.log("[status] cortex_version_state=local-newer");
+    console.log("[status] cortex_update_available=no");
+    console.log("[status] note: local Cortex is newer than the published version");
   } else {
+    console.log("[status] cortex_version_state=current");
     console.log("[status] cortex_update_available=no");
   }
 } catch (error) {