arkaos 4.3.6 → 4.4.0

package/core/terminal/session_windows.py

@@ -0,0 +1,211 @@
+"""Windows PTY session backend (ConPTY via pywinpty).
+
+The POSIX backend in ``session.py`` builds on ``pty.fork`` + fcntl /
+termios, none of which exist on Windows. This module provides the same
+``TerminalSession`` surface on top of pywinpty's ConPTY wrapper, so the
+dashboard terminal works on Windows. ``TerminalSessionManager.create``
+selects it when ``os.name == "nt"``.
+
+IO model
+--------
+pywinpty's ``read`` is blocking and there is no pollable fd, so the POSIX
+approach (``loop.add_reader(master_fd)``) does not apply. Instead each
+session owns one daemon reader thread that drains the pty for the
+session's whole lifetime: it always appends to the bounded scrollback
+(so a client reconnecting after navigating away replays what it missed)
+and, when a WebSocket is attached, forwards each chunk to that single
+``listener``. Decoupling the reader from the connection avoids two
+readers racing on the same pty across a reload/supersede.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Callable, Optional
+
+from core.terminal import audit
+
+DEFAULT_SCROLLBACK_BYTES = 512 * 1024
+
+
+class WindowsTerminalSession:
+    """A ConPTY-backed shell + the bookkeeping the manager relies on.
+
+    Mirrors the public surface of ``session.TerminalSession``:
+    ``read``/``write``/``resize``/``scrollback``/``is_alive``/``kill``/
+    ``to_dict`` plus the ``session_id``/``shell``/``cwd``/``exit_code``
+    attributes. ``master_fd`` is always ``-1`` — the dashboard WebSocket
+    handler uses that to pick the thread-listener pump instead of
+    ``add_reader``.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        shell: str,
+        cwd: str,
+        cols: int = 120,
+        rows: int = 32,
+        scrollback_bytes: int = DEFAULT_SCROLLBACK_BYTES,
+    ) -> None:
+        import winpty  # lazy: the dependency is only needed on Windows
+
+        self.session_id = session_id
+        self.shell = shell
+        self.cwd = cwd
+        self.created_at = time.time()
+        self.last_activity = time.monotonic()
+        self.exit_code: Optional[int] = None
+        self.title = ""
+        self.scrollback_max = max(0, int(scrollback_bytes))
+        self._scrollback = bytearray()
+        self._closed = False
+        self.master_fd = -1  # no pollable fd on Windows
+
+        # ConPTY dimensions are (rows, cols).
+        self._proc = winpty.PtyProcess.spawn(
+            shell,
+            cwd=cwd,
+            dimensions=(max(1, int(rows)), max(1, int(cols))),
+        )
+        self.pid = self._proc.pid
+
+        self._listener: Optional[Callable[[bytes], None]] = None
+        self._lock = threading.Lock()
+        self._reader = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader.start()
+
+    # -- reader thread ------------------------------------------------------
+    def _read_loop(self) -> None:
+        """Drain the pty for the session lifetime; feed scrollback + listener."""
+        while not self._closed:
+            try:
+                chunk = self._proc.read(8192)
+            except EOFError:
+                break
+            except OSError:
+                break
+            if not chunk:
+                if not self._proc_alive():
+                    break
+                continue
+            raw = chunk.encode("utf-8", "replace") if isinstance(chunk, str) else bytes(chunk)
+            self.last_activity = time.monotonic()
+            # Record + capture the listener under the lock so attach() can
+            # snapshot scrollback and start receiving with no gap and no dup.
+            with self._lock:
+                self._record(raw)
+                listener = self._listener
+            if listener is not None:
+                try:
+                    listener(raw)
+                except Exception:
+                    pass
+        self._closed = True
+
+    def attach(self, listener: Callable[[bytes], None]) -> bytes:
+        """Atomically snapshot scrollback and register the live output sink.
+
+        Returns the scrollback to replay. Any chunk recorded after this
+        snapshot is delivered to ``listener`` (no gap, no duplicate).
+        """
+        with self._lock:
+            snapshot = bytes(self._scrollback)
+            self._listener = listener
+            return snapshot
+
+    def set_listener(self, listener: Optional[Callable[[bytes], None]]) -> None:
+        """Register (or clear with ``None``) the live output sink."""
+        with self._lock:
+            self._listener = listener
+
+    def _proc_alive(self) -> bool:
+        try:
+            return self._proc.isalive()
+        except OSError:
+            return False
+
+    # -- output -------------------------------------------------------------
+    def read(self, max_bytes: int = 4096) -> bytes:
+        """Compatibility shim: a session-owned thread does the real reading.
+
+        The POSIX backend is polled via ``read``; on Windows reading happens
+        in ``_read_loop``, so direct callers get an empty read.
+        """
+        return b""
+
+    def _record(self, data: bytes) -> None:
+        if self.scrollback_max <= 0:
+            return
+        self._scrollback += data
+        if len(self._scrollback) > self.scrollback_max:
+            del self._scrollback[: -self.scrollback_max]
+
+    def scrollback(self) -> bytes:
+        return bytes(self._scrollback)
+
+    # -- input / control ----------------------------------------------------
+    def write(self, data: bytes) -> int:
+        if self._closed or not data:
+            return 0
+        text = (
+            data.decode("utf-8", "replace")
+            if isinstance(data, (bytes, bytearray))
+            else str(data)
+        )
+        try:
+            self._proc.write(text)
+        except (OSError, EOFError):
+            self._closed = True
+            return 0
+        self.last_activity = time.monotonic()
+        return len(data)
+
+    def resize(self, cols: int, rows: int) -> None:
+        if self._closed:
+            return
+        try:
+            self._proc.setwinsize(max(1, int(rows)), max(1, int(cols)))
+        except OSError:
+            pass
+
+    def is_alive(self) -> bool:
+        if self._closed:
+            return False
+        if not self._proc_alive():
+            self.exit_code = getattr(self._proc, "exitstatus", None)
+            self._closed = True
+            return False
+        return True
+
+    def kill(self, sig: Optional[int] = None) -> None:
+        self._closed = True
+        self._listener = None
+        try:
+            self._proc.terminate(force=True)
+        except Exception:
+            pass
+
+    def _close_fd(self) -> None:
+        self._listener = None
+        if not self._closed:
+            try:
+                self._proc.terminate(force=True)
+            except Exception:
+                pass
+        self._scrollback.clear()
+        self._closed = True
+
+    def to_dict(self) -> dict[str, Any]:
+        idle_s = max(0.0, time.monotonic() - self.last_activity)
+        return {
+            "session_id": self.session_id,
+            "shell": self.shell,
+            "cwd": self.cwd,
+            "title": self.title or self.session_id,
+            "created_at": self.created_at,
+            "idle_seconds": round(idle_s, 1),
+            "alive": self.is_alive(),
+            "exit_code": self.exit_code,
+        }

package/core/workflow/flow_authorization.py

@@ -42,6 +42,7 @@ 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
 
 _safe_session_id = _safe_session_id_module.safe_session_id
 
@@ -63,7 +64,7 @@ class GraceState:
 
 def _base_dir() -> Path:
     override = os.environ.get("ARKA_FLOW_AUTH_DIR", "").strip()
-    return Path(override) if override else Path("/tmp/arkaos-flow-auth")
+    return Path(override) if override else arkaos_temp_dir("arkaos-flow-auth")
 
 
 def _auth_path(session_id: str) -> Path | None:

package/core/workflow/flow_enforcer.py

@@ -25,6 +25,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.workflow import flow_authorization, marker_cache
 
 try:
@@ -210,7 +211,7 @@ ASSISTANT_WINDOW = 20
 CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
 BYPASS_AUDIT_PATH = Path.home() / ".arkaos" / "audit" / "bypass.log"
 TELEMETRY_PATH = Path.home() / ".arkaos" / "telemetry" / "enforcement.jsonl"
-FLOW_REQUIRED_DIR = Path("/tmp/arkaos-wf-required")
+FLOW_REQUIRED_DIR = arkaos_temp_dir("arkaos-wf-required")
 
 
 @dataclass

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.6",
+  "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.6"
+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",