arkaos 3.73.0 → 3.73.1

package/VERSION

@@ -1 +1 @@
-3.73.0
+3.73.1

package/installer/cli.js

@@ -92,10 +92,12 @@ async function main() {
       break;
     }
 
-    case "doctor":
+    case "doctor": {
       const { doctor } = await import("./doctor.js");
-      await doctor();
+      const fixMode = positionals.slice(1).includes("--fix") || values.fix === true;
+      await doctor({ fix: fixMode });
       break;
+    }
 
     case "update":
       const { update } = await import("./update.js");

package/installer/doctor.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
-import { getArkaosPython, getVenvPython, canImportCore, getRepoRoot } from "./python-resolver.js";
+import { getArkaosPython, getVenvPython, canImportCore, getRepoRoot, diagnoseVenv, ensureVenvHealthy } from "./python-resolver.js";
 import { IS_WINDOWS, HOOK_EXT, CMD_FINDER } from "./platform.js";
 import { checkNode, checkObsidian, checkOllama } from "./system-tools.js";
 
@@ -54,10 +54,21 @@ const checks = [
   },
   {
     name: "venv",
-    description: "ArkaOS virtual environment exists",
-    severity: "warn",
-    check: () => existsSync(getVenvPython()),
-    fix: () => "Run: npx arkaos@latest update (creates venv automatically)",
+    // PR2 v3.73.1: promoted from "warn" to "fail" — without the venv, the
+    // dashboard cannot start at all (start-dashboard.{sh,ps1} now fail fast
+    // instead of falling back to ambient python3 with missing deps).
+    description: "ArkaOS virtual environment exists and is runnable",
+    severity: "fail",
+    check: () => {
+      const venvDir = join(INSTALL_DIR, "venv");
+      const d = diagnoseVenv(venvDir);
+      return d.healthy;
+    },
+    fix: () => {
+      const venvDir = join(INSTALL_DIR, "venv");
+      const d = diagnoseVenv(venvDir);
+      return `Run: npx arkaos doctor --fix  (current state: ${d.reason})`;
+    },
   },
   {
     name: "hooks-dir",
@@ -241,8 +252,33 @@ if (IS_WINDOWS) {
   );
 }
 
-export async function doctor() {
-  console.log("\n  ArkaOS Doctor — Health Checks\n");
+export async function doctor(options = {}) {
+  const fixMode = !!options.fix;
+  console.log(`\n  ArkaOS Doctor — Health Checks${fixMode ? " (--fix)" : ""}\n`);
+
+  // ─── --fix: repair the venv before reporting checks (PR2 v3.73.1) ────
+  // Targeted, idempotent self-heal: detects broken symlinks / version
+  // drift / missing bin/python and recreates the venv with --clear so
+  // the subsequent venv check has a chance of passing.
+  if (fixMode) {
+    const venvDir = join(INSTALL_DIR, "venv");
+    const before = diagnoseVenv(venvDir);
+    if (before.healthy) {
+      console.log("  ℹ Venv already healthy — no repair needed");
+    } else {
+      console.log(`  → Repairing venv (current state: ${before.reason})`);
+      const result = ensureVenvHealthy({
+        venvDir,
+        log: (msg) => console.log("    " + msg.trim()),
+      });
+      if (result.healthy && result.repaired) {
+        console.log("  ✓ Venv repaired");
+      } else if (!result.healthy) {
+        console.log(`  ✗ Venv repair failed (${result.reason})`);
+      }
+    }
+    console.log("");
+  }
 
   let passed = 0;
   let warned = 0;

package/installer/python-resolver.js

@@ -6,7 +6,7 @@
  * and guarantees the doctor checks the same interpreter the installer uses.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir, platform } from "node:os";
 import { execSync } from "node:child_process";
@@ -94,6 +94,134 @@ export function findSystemPython() {
   return null;
 }
 
+/**
+ * Diagnose a venv directory. Pure read-only — does not modify anything.
+ * Returns { healthy: bool, reason: string, pythonPath?: string }.
+ *
+ * Reasons:
+ *  - "missing"        — venv dir absent OR bin/python absent (no symlink)
+ *  - "broken-symlink" — bin/python is a symlink to a missing target
+ *                       (typical after Homebrew rotates Python patch versions)
+ *  - "version-failed" — python --version exec failed (corrupt binary)
+ *  - "ok"             — venv healthy, python runs
+ */
+export function diagnoseVenv(venvDir) {
+  const isWin = platform() === "win32";
+  const pythonPath = isWin
+    ? join(venvDir, "Scripts", "python.exe")
+    : join(venvDir, "bin", "python");
+
+  // existsSync FOLLOWS symlinks, so a broken symlink returns false here
+  // even when the symlink itself is present on disk. Distinguish via lstat.
+  if (!existsSync(pythonPath)) {
+    let isBroken = false;
+    try {
+      const stat = lstatSync(pythonPath);
+      if (stat.isSymbolicLink()) isBroken = true;
+    } catch {
+      // pythonPath doesn't exist at all — fall through as "missing"
+    }
+    return {
+      healthy: false,
+      reason: isBroken ? "broken-symlink" : "missing",
+    };
+  }
+
+  // pythonPath exists. Try to run it — guards against corrupt-but-present
+  // binaries (e.g., a non-executable file placed at bin/python by accident).
+  try {
+    const out = execSync(`"${pythonPath}" --version 2>&1`, {
+      stdio: "pipe",
+      timeout: 5000,
+    }).toString();
+    if (!/Python 3/.test(out)) {
+      return { healthy: false, reason: "version-failed", pythonPath };
+    }
+    return { healthy: true, reason: "ok", pythonPath };
+  } catch {
+    return { healthy: false, reason: "version-failed", pythonPath };
+  }
+}
+
+
+/**
+ * Ensure the venv is healthy, repairing if needed.
+ * Returns { healthy: bool, repaired: bool, reason: string }.
+ *
+ * Repair strategy: `python -m venv --clear` removes the stale bin/ Scripts
+ * directories (closing the broken-symlink and version-failed cases) and
+ * recreates them against the currently resolvable system Python. The
+ * post-repair venv is re-diagnosed to confirm health before returning.
+ *
+ * Options:
+ *  - venvDir  (default: ~/.arkaos/venv)
+ *  - log      (default: console.log)
+ *  - skipDeps (default: false) — when true, do not attempt pip upgrades
+ *             after repair. Used by tests to keep them fast/offline.
+ */
+export function ensureVenvHealthy(options = {}) {
+  const venvDir = options.venvDir || join(INSTALL_DIR, "venv");
+  const log = options.log || console.log;
+  const skipDeps = !!options.skipDeps;
+
+  const diagnosis = diagnoseVenv(venvDir);
+  if (diagnosis.healthy) {
+    log(`         ✓ Venv healthy at ${venvDir}`);
+    return { healthy: true, repaired: false, reason: "already-healthy" };
+  }
+
+  log(`         ⚠ Venv ${diagnosis.reason} at ${venvDir} — repairing`);
+
+  const systemPython = findSystemPython();
+  if (!systemPython) {
+    return {
+      healthy: false,
+      repaired: false,
+      reason: `${diagnosis.reason}-and-no-system-python`,
+    };
+  }
+
+  try {
+    execSync(`"${systemPython}" -m venv --clear "${venvDir}"`, {
+      stdio: "pipe",
+      timeout: 60000,
+    });
+    log(`         ✓ Venv recreated at ${venvDir}`);
+  } catch (err) {
+    const msg = (err && err.message ? err.message : String(err)).slice(0, 100);
+    return {
+      healthy: false,
+      repaired: false,
+      reason: `recreate-failed: ${msg}`,
+    };
+  }
+
+  const post = diagnoseVenv(venvDir);
+  if (!post.healthy) {
+    return {
+      healthy: false,
+      repaired: true,
+      reason: `repaired-but-still-unhealthy: ${post.reason}`,
+    };
+  }
+
+  if (!skipDeps) {
+    try {
+      execSync(`"${post.pythonPath}" -m pip install --upgrade pip --quiet`, {
+        stdio: "pipe",
+        timeout: 60000,
+      });
+    } catch { /* pip upgrade is non-critical */ }
+  }
+
+  return {
+    healthy: true,
+    repaired: true,
+    reason: `repaired-from-${diagnosis.reason}`,
+  };
+}
+
+
 /**
  * Create the ArkaOS venv if it doesn't exist.
  * Returns true on success, false on failure.

package/installer/update.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, writeFileSync, copyFileSync, chmodSync, mkdir
 import { join, dirname, resolve } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
-import { ensureVenv, getArkaosPython, pipInstall } from "./python-resolver.js";
+import { ensureVenv, ensureVenvHealthy, getArkaosPython, pipInstall } from "./python-resolver.js";
 import { getRuntimeConfig } from "./detect-runtime.js";
 import { loadAdapter } from "./index.js";
 import { migrateUserData, printMigrationReport } from "./migrate-user-data.js";
@@ -103,10 +103,15 @@ export async function update() {
   // ── 1. Update Python deps (using venv) ──
   console.log("  [1/8] Updating Python dependencies...");
 
-  // Ensure venv exists (creates one if missing — fixes PEP 668)
-  const venvOk = ensureVenv((msg) => console.log(msg));
-  if (!venvOk) {
-    console.log("         \u26a0 Could not create venv — trying system Python with PEP 668 handling");
+  // Ensure venv is healthy (creates, repairs broken symlinks, or no-ops).
+  // PR2 v3.73.1 — previously a stale broken-symlink venv could pass the
+  // existence check, and the dashboard would silently fall back to ambient
+  // python3 without sqlite-vec/fastembed.
+  const venvHealth = ensureVenvHealthy({ log: (msg) => console.log(msg) });
+  if (!venvHealth.healthy) {
+    console.log(`         \u26a0 Venv unhealthy (${venvHealth.reason}) - falling back to system Python with PEP 668 handling`);
+  } else if (venvHealth.repaired) {
+    console.log(`         \u2713 Venv repaired (${venvHealth.reason})`);
   }
 
   const pythonCmd = getArkaosPython();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "3.73.0",
+  "version": "3.73.1",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "3.73.0"
+version = "3.73.1"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/start-dashboard.ps1

@@ -82,10 +82,13 @@ Write-Host ''
 Write-Host '  ArkaOS Dashboard'
 Write-Host '  -----------------'
 
-# --- Locate Python ---------------------------------------------------------
-# Prefer the ArkaOS venv python recorded in the install manifest so the
-# dashboard API runs against the same interpreter the installer uses.
-function Find-Python {
+# --- Locate ArkaOS venv Python (PR2 v3.73.1 — no ambient fallback) --------
+# Previously this function fell back to system python/python3/py when the
+# venv wasn't available. That hid broken-venv conditions and produced
+# half-working dashboards without sqlite-vec/fastembed. Now we look only at
+# the manifest pythonCmd and the venv path, and fail fast with actionable
+# remediation otherwise.
+function Find-VenvPython {
     $manifest = Join-Path $arkaosHome 'install-manifest.json'
     if (Test-Path -LiteralPath $manifest) {
         try {
@@ -97,17 +100,22 @@ function Find-Python {
     }
     $venvPy = Join-Path $arkaosHome 'venv\Scripts\python.exe'
     if (Test-Path -LiteralPath $venvPy) { return $venvPy }
-    foreach ($cmd in 'python','python3','py') {
-        $found = Get-Command $cmd -ErrorAction SilentlyContinue
-        if ($found) { return $found.Source }
-    }
     return $null
 }
 
-$python = Find-Python
+$python = Find-VenvPython
 if (-not $python) {
-    Write-Host '  Error: no usable Python interpreter found.' -ForegroundColor Red
-    Write-Host '  Install Python 3.11+ and rerun.'             -ForegroundColor DarkGray
+    Write-Host ''
+    Write-Host "  X ArkaOS venv unavailable at $arkaosHome\venv\Scripts\python.exe" -ForegroundColor Red
+    Write-Host ''
+    Write-Host '    The dashboard must run from the ArkaOS venv so that'      -ForegroundColor DarkGray
+    Write-Host '    sqlite-vec, fastembed, fastapi, and uvicorn are present.' -ForegroundColor DarkGray
+    Write-Host '    The ambient python fallback was removed in v3.73.1.'      -ForegroundColor DarkGray
+    Write-Host ''
+    Write-Host '    Fix:' -ForegroundColor DarkGray
+    Write-Host '      npx arkaos doctor --fix       (repairs broken venv in place)'    -ForegroundColor DarkGray
+    Write-Host '      npx arkaos@latest update      (full reinstall, slower)'          -ForegroundColor DarkGray
+    Write-Host ''
     exit 1
 }
 

package/scripts/start-dashboard.sh

@@ -6,9 +6,31 @@ ARKAOS_ROOT="${ARKAOS_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
 DASHBOARD_DIR="${ARKAOS_ROOT}/dashboard"
 PID_FILE="$HOME/.arkaos/dashboard.pid"
 PORT_FILE="$HOME/.arkaos/dashboard.ports"
+VENV_PYTHON="$HOME/.arkaos/venv/bin/python"
 
 mkdir -p "$HOME/.arkaos"
 
+# ── Venv guard (PR2 v3.73.1 — Force Specialist Dispatch dogfood) ──
+# Previously the dashboard fell back to ambient `python3` when the venv
+# wasn't available. That hid broken-venv conditions (Homebrew patch
+# rotations leaving dangling symlinks) and produced half-working dashboards
+# without sqlite-vec / fastembed. Now we fail fast with a clear remediation.
+# `[ -x ]` follows symlinks, so a broken symlink correctly fails the test.
+if [ ! -x "$VENV_PYTHON" ]; then
+  echo ""
+  echo "  ✗ ArkaOS venv unavailable at $VENV_PYTHON"
+  echo ""
+  echo "    The dashboard must run from the ArkaOS venv so that"
+  echo "    sqlite-vec, fastembed, fastapi, and uvicorn are present."
+  echo "    The ambient python3 fallback was removed in v3.73.1."
+  echo ""
+  echo "    Fix:"
+  echo "      npx arkaos doctor --fix       (repairs broken venv in place)"
+  echo "      npx arkaos@latest update      (full reinstall, slower)"
+  echo ""
+  exit 1
+fi
+
 # ── Kill existing if running ──
 if [ -f "$PID_FILE" ]; then
   while read -r pid; do
@@ -38,7 +60,7 @@ echo "  ─────────────────"
 # ── Start FastAPI backend ──
 API_LOG="$HOME/.arkaos/api.log"
 echo "  Starting API on :${API_PORT}..."
-ARKAOS_ROOT="$ARKAOS_ROOT" python3 "${ARKAOS_ROOT}/scripts/dashboard-api.py" --port "$API_PORT" > "$API_LOG" 2>&1 &
+ARKAOS_ROOT="$ARKAOS_ROOT" "$VENV_PYTHON" "${ARKAOS_ROOT}/scripts/dashboard-api.py" --port "$API_PORT" > "$API_LOG" 2>&1 &
 API_PID=$!
 
 # Wait for API with health check (up to 10 seconds)