arkaos 4.3.5 → 4.4.0

package/core/workflow/marker_cache.py

@@ -20,13 +20,14 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from core.shared import safe_session_id as _safe_session_id_module
+from core.shared.temp_paths import arkaos_temp_dir
 
 
 def _resolve_cache_dir() -> Path:
     override = os.environ.get("ARKA_MARKER_CACHE_DIR", "").strip()
     if override:
         return Path(override)
-    return Path("/tmp/arkaos-flow-marker")
+    return arkaos_temp_dir("arkaos-flow-marker")
 
 
 MARKER_CACHE_DIR = _resolve_cache_dir()

package/core/workflow/research_gate.py

@@ -29,6 +29,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from core.shared import safe_session_id as _safe_session_id_module
+from core.shared.temp_paths import arkaos_temp_dir
 from core.synapse import kb_cache
 
 try:
@@ -55,7 +56,7 @@ SAFE_SESSION_ID_RE = _safe_session_id_module.SAFE_SESSION_ID_RE
 CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
 BYPASS_AUDIT_PATH = Path.home() / ".arkaos" / "audit" / "kb_first_bypass.log"
 TELEMETRY_PATH = Path.home() / ".arkaos" / "telemetry" / "kb_first.jsonl"
-VIOLATION_DIR = Path("/tmp/arkaos-kb-violation")
+VIOLATION_DIR = arkaos_temp_dir("arkaos-kb-violation")
 
 
 def _violation_dir() -> Path:

package/dashboard/app/pages/index.vue

@@ -131,9 +131,14 @@ function formatIncidentTs(iso: string): string {
   }
 }
 
+const toast = useToast()
 function copyCommand(cmd: string) {
   if (typeof navigator !== 'undefined' && navigator.clipboard) {
-    navigator.clipboard.writeText(cmd).catch(() => { /* ignore */ })
+    navigator.clipboard.writeText(cmd)
+      .then(() => toast.add({ title: 'Copied to clipboard', description: cmd, icon: 'i-lucide-clipboard-check' }))
+      .catch(() => toast.add({ title: 'Copy failed', description: cmd, color: 'error', icon: 'i-lucide-clipboard-x' }))
+  } else {
+    toast.add({ title: 'Clipboard unavailable', description: cmd, color: 'warning' })
   }
 }
 </script>

package/installer/cli.js

@@ -152,7 +152,7 @@ async function main() {
       const repoRootDash = join(__dirname, "..");
       const dashCmd = IS_WINDOWS
         ? `powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "${join(repoRootDash, "scripts", "start-dashboard.ps1")}"`
-        : `bash "${repoRootDash}/scripts/start-dashboard.sh"`;
+        : `bash "${join(repoRootDash, "scripts", "start-dashboard.sh")}"`;
       try {
         execDash(dashCmd, {
           stdio: "inherit",
@@ -199,13 +199,14 @@ async function main() {
     }
 
     case "index": {
-      const { execSync } = await import("node:child_process");
-      const indexArgs = positionals.slice(1).join(" ");
+      const { execFileSync } = await import("node:child_process");
       const repoRoot = join(__dirname, "..");
       const pyIndex = getArkaosPython();
       if (!pyIndex) { console.error("No Python found. Run: npx arkaos install"); process.exit(1); }
       try {
-        execSync(`"${pyIndex}" "${join(repoRoot, "scripts", "knowledge-index.py")}" ${indexArgs || ""}`, {
+        // argv array, not a joined string: vault paths with spaces
+        // ("C:\Users\Ana Maria\vault") broke the quoted-string form.
+        execFileSync(pyIndex, [join(repoRoot, "scripts", "knowledge-index.py"), ...positionals.slice(1)], {
           stdio: "inherit",
           env: { ...process.env, ARKAOS_ROOT: repoRoot },
         });

package/installer/core-snapshot.js

@@ -0,0 +1,53 @@
+import {
+  existsSync,
+  cpSync,
+  mkdirSync,
+  rmSync,
+  renameSync,
+  copyFileSync,
+} from "node:fs";
+import { join, basename } from "node:path";
+
+// Deploys a stable snapshot of the Python core package (+ VERSION) into
+// ~/.arkaos/lib. `.repo-path` points at whichever npx cache last ran an
+// install/update — a location `npm cache clean` can purge at any time.
+// When that happens, every `arka-py -m core.*` entrypoint (hooks,
+// /arka update, telemetry CLIs) loses the core package unless it runs
+// from a dev checkout. The snapshot is the always-present fallback that
+// bin/arka-py and core/hooks/_shared.py validate against.
+//
+// core/sync/__init__.py is the validation marker: it distinguishes the
+// full package from the cognitive scheduler's minimal core/ copy in
+// ~/.arkaos/core (cognition + workflow only).
+//
+// Shared by installer/index.js (fresh install) and installer/update.js —
+// same single-implementation rationale as hook-lib.js: the v4.3.2
+// regression existed because two deploy loops drifted.
+export function deployCoreSnapshot(arkaosRoot, installDir) {
+  const srcCore = join(arkaosRoot, "core");
+  if (!existsSync(join(srcCore, "sync", "__init__.py"))) return false;
+
+  const libDir = join(installDir, "lib");
+  const destCore = join(libDir, "core");
+  const staging = join(libDir, ".core.staging");
+  const previous = join(libDir, ".core.previous");
+
+  // Stage + swap so a crash at any point never destroys the last good
+  // snapshot: the new tree is fully written to staging first, the old
+  // snapshot is only moved aside (not deleted) before the swap, and its
+  // removal is the final step.
+  rmSync(staging, { recursive: true, force: true });
+  rmSync(previous, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true });
+  cpSync(srcCore, staging, {
+    recursive: true,
+    filter: (src) => basename(src) !== "__pycache__",
+  });
+  if (existsSync(destCore)) renameSync(destCore, previous);
+  renameSync(staging, destCore);
+  rmSync(previous, { recursive: true, force: true });
+
+  const versionFile = join(arkaosRoot, "VERSION");
+  if (existsSync(versionFile)) copyFileSync(versionFile, join(libDir, "VERSION"));
+  return true;
+}

package/installer/doctor.js

@@ -99,15 +99,20 @@ const checks = [
   },
   {
     name: "repo-path",
-    description: "Repo path reference exists",
+    description: "Python core reachable (.repo-path or ~/.arkaos/lib snapshot)",
     severity: "warn",
     check: () => {
+      // The stable snapshot keeps arka-py working even after
+      // `npm cache clean` purges the npx dir .repo-path points at.
+      if (existsSync(join(INSTALL_DIR, "lib", "core", "sync", "__init__.py"))) {
+        return true;
+      }
       const p = join(INSTALL_DIR, ".repo-path");
       if (!existsSync(p)) return false;
       const root = readFileSync(p, "utf-8").trim();
-      return existsSync(root);
+      return existsSync(join(root, "core", "sync", "__init__.py"));
     },
-    fix: () => "Run: npx arkaos install --force",
+    fix: () => "Run: npx arkaos@latest update (recreates the ~/.arkaos/lib core snapshot)",
   },
   {
     name: "profile",

package/installer/index.js

@@ -7,6 +7,7 @@ import { getRuntimeConfig } from "./detect-runtime.js";
 import { findSystemPython, ensureVenv, getArkaosPython, getArkaosPip, pipInstall } from "./python-resolver.js";
 import { IS_WINDOWS, HOOK_EXT } from "./platform.js";
 import { copyHookLib } from "./hook-lib.js";
+import { deployCoreSnapshot } from "./core-snapshot.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -211,6 +212,17 @@ export async function install({ runtime, path, force, skipSystem, withOllama })
   // ═══ Step 11: Create references and profile ═══
   step(11, 14, "Creating references...");
   writeFileSync(join(installDir, ".repo-path"), ARKAOS_ROOT);
+  // .repo-path points at the npx cache, which `npm cache clean` can purge;
+  // the ~/.arkaos/lib snapshot is the validated fallback for arka-py and
+  // the Python hooks (see installer/core-snapshot.js). A failed snapshot
+  // must never fail the install — the resolvers degrade to .repo-path.
+  try {
+    if (deployCoreSnapshot(ARKAOS_ROOT, installDir)) {
+      ok("Core snapshot deployed to ~/.arkaos/lib (survives npx cache purges)");
+    }
+  } catch (err) {
+    console.log(`         ⚠ Core snapshot skipped (${err.message}) — arka-py falls back to .repo-path`);
+  }
   const skillsDir = join(config.skillsDir || join(homedir(), ".claude", "skills"), "arkaos");
   ensureDir(skillsDir);
   writeFileSync(join(skillsDir, ".arkaos-root"), ARKAOS_ROOT);
@@ -520,8 +532,12 @@ function installAllPythonDeps(userConfig = {}) {
   // a failure of one does not block the other.
   // Ingest (YouTube, PDF, web, audio)
   const ingestDeps = "yt-dlp pdfplumber beautifulsoup4 requests";
-  // Dashboard API
-  const dashboardDeps = "fastapi uvicorn";
+  // Dashboard API. python-multipart is required by FastAPI for the
+  // knowledge upload endpoint (its absence fails the API import on every
+  // platform). pywinpty backs the dashboard terminal on Windows (ConPTY).
+  const dashboardDeps = process.platform === "win32"
+    ? "fastapi uvicorn python-multipart pywinpty"
+    : "fastapi uvicorn python-multipart";
   // Transcription
   const transcriptionDeps = "faster-whisper";
 
@@ -563,8 +579,8 @@ function installAllPythonDeps(userConfig = {}) {
   // Dashboard deps (optional)
   if (userConfig.installDashboard !== false) {
     console.log("         Installing dashboard dependencies...");
-    if (pipInstall(dashboardDeps, { log, timeout: 60000 })) {
-      ok("Dashboard API installed (fastapi, uvicorn)");
+    if (pipInstall(dashboardDeps, { log, timeout: 120000 })) {
+      ok("Dashboard API installed (fastapi, uvicorn, python-multipart)");
     } else {
       warn("Dashboard API not installed (optional)");
     }
@@ -593,12 +609,19 @@ function copyConfigFiles(installDir) {
     ["config/constitution.yaml", "config/constitution.yaml"],
   ];
 
-  // Standards
+  // Standards — files copied individually; subdirectories (e.g. claude-md-overlays)
+  // use cpSync recursively because copyFileSync fails with EPERM on directories.
   const standardsDir = join(ARKAOS_ROOT, "config", "standards");
   if (existsSync(standardsDir)) {
     ensureDir(join(installDir, "config", "standards"));
     for (const f of readdirSync(standardsDir)) {
-      files.push([`config/standards/${f}`, `config/standards/${f}`]);
+      const srcEntry = join(standardsDir, f);
+      const destEntry = join(installDir, "config", "standards", f);
+      if (statSync(srcEntry).isDirectory()) {
+        cpSync(srcEntry, destEntry, { recursive: true });
+      } else {
+        files.push([`config/standards/${f}`, `config/standards/${f}`]);
+      }
     }
   }
 

package/installer/migrate.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, renameSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, mkdirSync, writeFileSync, cpSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
@@ -75,7 +75,7 @@ export async function migrate() {
   const v2Digests = join(V2_PATH, "session-digests");
   if (existsSync(v1Digests) && !existsSync(v2Digests)) {
     try {
-      execSync(`cp -r "${v1Digests}" "${v2Digests}"`, { stdio: "pipe" });
+      cpSync(v1Digests, v2Digests, { recursive: true });
       console.log("  Preserved session digests.");
     } catch {
       console.log("  Could not copy session digests.");
@@ -87,7 +87,7 @@ export async function migrate() {
   const v2Media = join(V2_PATH, "media");
   if (existsSync(v1Media) && !existsSync(v2Media)) {
     try {
-      execSync(`cp -r "${v1Media}" "${v2Media}"`, { stdio: "pipe" });
+      cpSync(v1Media, v2Media, { recursive: true });
       console.log("  Preserved media files.");
     } catch {
       console.log("  Could not copy media files.");
@@ -101,7 +101,10 @@ export async function migrate() {
   } catch (err) {
     console.error(`\n  Migration failed during install: ${err.message}`);
     console.error(`  Your v1 backup is at: ${backupDir}`);
-    console.error(`  To restore: mv "${backupDir}" "${v1Dir}"\n`);
+    const restoreHint = process.platform === "win32"
+      ? `Move-Item "${backupDir}" "${v1Dir}"`
+      : `mv "${backupDir}" "${v1Dir}"`;
+    console.error(`  To restore: ${restoreHint}\n`);
     process.exit(1);
   }
 

package/installer/update.js

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { execSync } from "node:child_process";
 import { ensureVenv, ensureVenvHealthy, getArkaosPython, pipInstall } from "./python-resolver.js";
 import { copyHookLib } from "./hook-lib.js";
+import { deployCoreSnapshot } from "./core-snapshot.js";
 import { getRuntimeConfig } from "./detect-runtime.js";
 import { loadAdapter } from "./index.js";
 import { migrateUserData, printMigrationReport } from "./migrate-user-data.js";
@@ -455,6 +456,18 @@ export async function update() {
   // different clone than the original install.
   console.log("  [7/8] Updating references...");
   writeFileSync(join(installDir, ".repo-path"), ARKAOS_ROOT);
+  // .repo-path points at the npx cache, which `npm cache clean` can purge;
+  // refresh the ~/.arkaos/lib snapshot so arka-py and the Python hooks
+  // always keep a validated fallback (see installer/core-snapshot.js).
+  // A failed snapshot must never fail the update — resolvers degrade to
+  // .repo-path (and any previous snapshot is preserved by the safe swap).
+  try {
+    if (deployCoreSnapshot(ARKAOS_ROOT, installDir)) {
+      console.log("         ✓ Core snapshot refreshed in ~/.arkaos/lib");
+    }
+  } catch (err) {
+    console.log(`         ⚠ Core snapshot skipped (${err.message}) — arka-py falls back to .repo-path`);
+  }
   const skillsArkaosDir = join(homedir(), ".claude", "skills", "arkaos");
   if (existsSync(skillsArkaosDir)) {
     writeFileSync(join(skillsArkaosDir, ".arkaos-root"), ARKAOS_ROOT);

package/package.json

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

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "4.3.5"
+version = "4.4.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}
@@ -37,6 +37,7 @@ dashboard = [
     "uvicorn>=0.32.0",
     "python-multipart>=0.0.9",
     "websockets>=12.0",
+    "pywinpty>=2.0.0; sys_platform == 'win32'",
 ]
 ingest = [
     "yt-dlp>=2024.0",
@@ -45,6 +46,12 @@ ingest = [
     "beautifulsoup4>=4.12.0",
     "requests>=2.31.0",
 ]
+gateway = [
+    # LiteLLM proxy: the Anthropic-compatible fan-out endpoint that makes
+    # per-role mixed-provider routing (execution→Ollama, quality→Anthropic)
+    # take effect. Only needed when launching with ARKA_GATEWAY=1.
+    "litellm[proxy]>=1.50.0",
+]
 dev = [
     "pytest>=8.0",
     "pytest-cov>=5.0",

package/scripts/dashboard-api.py

@@ -20,6 +20,8 @@ from typing import Optional
 ARKAOS_ROOT = Path(os.environ.get("ARKAOS_ROOT", Path(__file__).resolve().parent.parent))
 sys.path.insert(0, str(ARKAOS_ROOT))
 
+from core.shared.temp_paths import arkaos_temp_dir
+
 from fastapi import FastAPI, Query, Request, WebSocket, WebSocketDisconnect
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse, JSONResponse
@@ -158,10 +160,10 @@ def overview():
 
     skills_count = 0
     try:
-        skills_count = int(subprocess.run(
-            ["find", str(ARKAOS_ROOT / "departments"), "-name", "SKILL.md", "-path", "*/skills/*/SKILL.md"],
-            capture_output=True, text=True, timeout=5,
-        ).stdout.strip().count("\n")) + 1
+        skills_count = sum(
+            1 for p in (ARKAOS_ROOT / "departments").rglob("SKILL.md")
+            if "skills" in p.parts
+        )
     except Exception:
         skills_count = 250
 
@@ -1733,7 +1735,7 @@ def health():
           "npx arkaos install")
 
     try:
-        subprocess.run(["python3", "--version"], capture_output=True, timeout=2)
+        subprocess.run([sys.executable, "--version"], capture_output=True, timeout=2)
         check("python", True)
     except Exception:
         check("python", False, "Install Python 3.11+")
@@ -2794,6 +2796,18 @@ def _current_version() -> str:
         return "0.0.0"
 
 
+def _win_shim(cmd: list) -> list:
+    """Wrap npm/npx-style commands so Windows can execute them.
+
+    npm and npx are ``.cmd`` shims; ``subprocess`` (CreateProcess) cannot
+    run them directly ("%1 is not a valid Win32 application"), so route
+    through ``cmd /c`` on Windows. No-op on POSIX.
+    """
+    if os.name == "nt":
+        return ["cmd", "/c", *cmd]
+    return cmd
+
+
 def _npm_latest_version():
     import subprocess
     import time
@@ -2802,7 +2816,7 @@ def _npm_latest_version():
         return _npm_latest_cache["version"]
     try:
         out = subprocess.run(
-            ["npm", "view", "arkaos", "version"],
+            _win_shim(["npm", "view", "arkaos", "version"]),
             capture_output=True, text=True, timeout=20,
         )
         latest = (out.stdout or "").strip() or None
@@ -2829,7 +2843,7 @@ def _run_core_update() -> dict:
     import subprocess
     try:
         out = subprocess.run(
-            ["npx", "arkaos@latest", "update"],
+            _win_shim(["npx", "arkaos@latest", "update"]),
             capture_output=True, text=True, timeout=600,
         )
         tail = ((out.stdout or "") + (out.stderr or ""))[-2000:]
@@ -2994,30 +3008,49 @@ async def ws_terminal(ws: WebSocket, session_id: str, token: str = Query("")):
     # left it. Sent before the live reader is attached, so the historical
     # prefix always precedes any new output (no interleave, no dup — these
     # bytes were already consumed from the kernel buffer when first read).
-    replay = session.scrollback()
-    if replay:
-        try:
-            await ws.send_bytes(replay)
-        except Exception:
-            await ws.close(code=1011, reason="replay failed")
-            return
-
     loop = asyncio.get_event_loop()
     output_queue: asyncio.Queue = asyncio.Queue()
 
-    def _on_readable():
+    # POSIX exposes a pollable master fd (add_reader); the Windows ConPTY
+    # backend has none (master_fd == -1) and instead pushes output from its
+    # own reader thread into a registered listener.
+    use_fd_reader = getattr(session, "master_fd", -1) >= 0
+
+    if use_fd_reader:
+        replay = session.scrollback()
+        if replay:
+            try:
+                await ws.send_bytes(replay)
+            except Exception:
+                await ws.close(code=1011, reason="replay failed")
+                return
+
+        def _on_readable():
+            try:
+                data = session.read(8192)
+            except OSError:
+                data = b""
+            if data:
+                output_queue.put_nowait(data)
+
         try:
-            data = session.read(8192)
-        except OSError:
-            data = b""
-        if data:
-            output_queue.put_nowait(data)
+            loop.add_reader(session.master_fd, _on_readable)
+        except (ValueError, OSError):
+            await ws.close(code=1011, reason="pty unavailable")
+            return
+    else:
+        def _emit(data: bytes):
+            loop.call_soon_threadsafe(output_queue.put_nowait, data)
 
-    try:
-        loop.add_reader(session.master_fd, _on_readable)
-    except (ValueError, OSError):
-        await ws.close(code=1011, reason="pty unavailable")
-        return
+        # Atomic: snapshot scrollback and start the live feed with no gap.
+        replay = session.attach(_emit)
+        if replay:
+            try:
+                await ws.send_bytes(replay)
+            except Exception:
+                session.set_listener(None)
+                await ws.close(code=1011, reason="replay failed")
+                return
 
     async def pump_to_client():
         while True:
@@ -3060,13 +3093,16 @@ async def ws_terminal(ws: WebSocket, session_id: str, token: str = Query("")):
         pass
     finally:
         pump_task.cancel()
-        # Only the still-active connection owns the fd reader — a superseded
-        # connection tearing down must not remove its replacement's reader.
+        # Only the still-active connection owns the reader — a superseded
+        # connection tearing down must not detach its replacement's reader.
         if _terminal_conns.release(session_id, ws):
-            try:
-                loop.remove_reader(session.master_fd)
-            except (ValueError, OSError):
-                pass
+            if use_fd_reader:
+                try:
+                    loop.remove_reader(session.master_fd)
+                except (ValueError, OSError):
+                    pass
+            else:
+                session.set_listener(None)
 
 
 @app.on_event("startup")
@@ -4233,7 +4269,7 @@ def keys_delete(key_name: str):
 
 @app.get("/api/metrics")
 def metrics():
-    metrics_file = Path("/tmp/arkaos-context-cache/hook-metrics.jsonl")
+    metrics_file = arkaos_temp_dir("arkaos-context-cache", "hook-metrics.jsonl")
     if not metrics_file.exists():
         return {"entries": [], "avg_ms": 0}
     entries = []

package/scripts/gateway-ensure.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ArkaOS — Model-routing gateway ensure
+#
+# Renders the LiteLLM proxy config from ~/.arkaos/models.yaml, ensures the
+# proxy is running, and writes the Claude Code launch env to a file the
+# caller sources. Best-effort: any failure returns non-zero so arka-claude
+# degrades to a plain `claude` launch — a broken gateway never blocks work.
+#
+# Contract:
+#   in : $ARKA_PY (interpreter), $ARKAOS_ROOT (repo), env ARKA_GATEWAY_PORT
+#   out: writes $ARKAOS_HOME/gateway/launch.env on success; exit 0
+#        exit non-zero on any failure (caller must degrade)
+# ============================================================================
+set -uo pipefail
+
+ARKAOS_HOME="${ARKAOS_HOME:-$HOME/.arkaos}"
+PORT="${ARKA_GATEWAY_PORT:-4000}"
+GW_DIR="$ARKAOS_HOME/gateway"
+CONFIG="$GW_DIR/config.yaml"
+ENV_FILE="$GW_DIR/launch.env"
+LOG="$GW_DIR/litellm.log"
+LITELLM="$ARKAOS_HOME/venv/bin/litellm"
+
+warn() { printf '  \033[1;33m⚠  gateway: %s\033[0m\n' "$1" >&2; }
+
+# ─── Preconditions ────────────────────────────────────────────────────────
+[ -n "${ARKA_PY:-}" ] || { warn "ARKA_PY unset"; exit 1; }
+[ -n "${ARKAOS_ROOT:-}" ] || { warn "ARKAOS_ROOT unset"; exit 1; }
+if [ ! -x "$LITELLM" ]; then
+  warn "LiteLLM not installed in the ArkaOS venv — run: ~/.arkaos/venv/bin/pip install 'litellm[proxy]'"
+  exit 1
+fi
+
+# Mode: with an API key -> mixed (quality→Anthropic, execution→Ollama).
+# Without one (subscription users) -> local-only: every route runs on the
+# local Ollama model, keyless. The main arka-claude keeps the subscription.
+LOCAL_FLAG=""
+if [ -z "${ANTHROPIC_API_KEY:-}" ]; then
+  LOCAL_FLAG="--local"
+  warn "no ANTHROPIC_API_KEY — local-only mode: the whole session runs on the local Ollama model (use plain arka-claude for subscription/quality work)"
+fi
+
+mkdir -p "$GW_DIR"
+health() { curl -fsS -m 2 "http://127.0.0.1:$PORT/health/liveliness" >/dev/null 2>&1; }
+
+# ─── Reuse a healthy proxy WITHOUT rotating its key ───────────────────────
+# The running proxy validates the ARKA_GATEWAY_KEY it started with; the
+# client reads that same value from the existing launch.env. Minting a new
+# key on reuse would 401 every request, so the reuse path touches neither
+# the key nor launch.env. Changing models.yaml needs ARKA_GATEWAY_RESTART=1.
+if [ "${ARKA_GATEWAY_RESTART:-0}" != "1" ] && health && [ -f "$ENV_FILE" ]; then
+  exit 0
+fi
+if health; then                      # RESTART path — old proxy must go
+  pkill -f "litellm .*--port $PORT" 2>/dev/null || true
+  sleep 1
+fi
+
+# ─── Render config from models.yaml ───────────────────────────────────────
+# shellcheck disable=SC2086  # LOCAL_FLAG is a single controlled token
+if ! PYTHONPATH="$ARKAOS_ROOT" "$ARKA_PY" -m core.runtime.gateway $LOCAL_FLAG > "$CONFIG" 2>/dev/null; then
+  if [ -n "$LOCAL_FLAG" ]; then
+    warn "could not render gateway config — local-only needs at least one ollama route in models.yaml"
+  else
+    warn "could not render gateway config from models.yaml"
+  fi
+  exit 1
+fi
+
+# ─── Fresh master key + client launch env (created for THIS proxy) ────────
+MASTER_KEY="$("$ARKA_PY" -c 'import secrets; print("sk-arka-" + secrets.token_hex(16))')"
+export ARKA_GATEWAY_KEY="$MASTER_KEY"
+
+if ! PYTHONPATH="$ARKAOS_ROOT" "$ARKA_PY" -m core.runtime.gateway --env "$MASTER_KEY" > "$ENV_FILE" 2>/dev/null; then
+  warn "could not render launch env"
+  exit 1
+fi
+# The proxy reads ANTHROPIC_API_KEY + ARKA_GATEWAY_KEY from its own env.
+printf 'ARKA_GATEWAY_KEY=%s\n' "$MASTER_KEY" >> "$ENV_FILE"
+chmod 600 "$ENV_FILE" 2>/dev/null || true   # bearer token — owner-only
+
+# Start in the background; ARKA_GATEWAY_KEY + ANTHROPIC_API_KEY inherited.
+( ARKA_GATEWAY_KEY="$MASTER_KEY" nohup "$LITELLM" --config "$CONFIG" --port "$PORT" \
+    >> "$LOG" 2>&1 & disown 2>/dev/null || true )
+
+# ─── Health-wait (bounded) ────────────────────────────────────────────────
+for _ in $(seq 1 30); do
+  if health; then exit 0; fi
+  sleep 1
+done
+warn "gateway did not become healthy within 30s (see $LOG)"
+exit 1

package/scripts/knowledge-index.py

@@ -14,6 +14,12 @@ import os
 import sys
 from pathlib import Path
 
+# Windows consoles default to cp1252; progress lines with non-ASCII vault
+# names would raise UnicodeEncodeError and kill the index run silently.
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+
 ARKAOS_ROOT = Path(os.environ.get("ARKAOS_ROOT", Path(__file__).resolve().parent.parent))
 sys.path.insert(0, str(ARKAOS_ROOT))
 
@@ -77,13 +83,40 @@ def main() -> int:
     # Index mode
     directory = args.vault or args.dir
     if not directory:
-        # Auto-detect vault from config
+        # Auto-detect vault from config. vault_path may be a template like
+        # "${VAULT_PATH}" — resolve it through the canonical path resolver
+        # (ARKAOS_VAULT_PATH env / profile.json vaultPath) before testing.
         config_path = ARKAOS_ROOT / "knowledge" / "obsidian-config.json"
         if config_path.exists():
-            config = json.loads(config_path.read_text())
+            config = json.loads(config_path.read_text(encoding="utf-8"))
             vault = config.get("vault_path", "")
+            if vault and "${" in vault:
+                try:
+                    from core.runtime.path_resolver import resolve
+
+                    vault = resolve(vault)
+                except Exception:
+                    vault = ""
+            if vault and Path(vault).exists():
+                directory = vault
+                if not args.json_output:
+                    print(f"Vault from config: {directory}", file=sys.stderr)
+
+    if not directory:
+        # profile.json vaultPath — set by `npx arkaos install` and the
+        # authoritative answer to "where is the user's vault".
+        profile_path = Path.home() / ".arkaos" / "profile.json"
+        if profile_path.exists():
+            try:
+                vault = json.loads(
+                    profile_path.read_text(encoding="utf-8")
+                ).get("vaultPath", "")
+            except (json.JSONDecodeError, OSError):
+                vault = ""
             if vault and Path(vault).exists():
                 directory = vault
+                if not args.json_output:
+                    print(f"Vault from profile: {directory}", file=sys.stderr)
 
     if not directory:
         # Try common vault locations