arkaos 4.3.6 → 4.4.0

package/core/shared/temp_paths.py

@@ -0,0 +1,40 @@
+"""Cross-platform base directory for ArkaOS inter-process coordination files.
+
+Several core modules and the bash hooks coordinate through small marker
+and cache files: workflow-required markers (``stop.sh`` ->
+``flow_enforcer``), the turn-scoped KB query cache
+(``user-prompt-submit.sh`` -> ``kb_cache``), hook metrics
+(``user-prompt-submit.sh`` -> ``dashboard-api``). The hooks write them
+under ``/tmp/arkaos-*``; the Python side MUST resolve to the *same*
+directory or the coordination silently breaks.
+
+Why this lives in ``core.shared``: every module that coordinates through
+these files (flow_enforcer, marker_cache, research_gate, kb_cache,
+forge.orchestrator, the consolidated hooks, native_usage, the synapse
+bridge, the dashboard API, …) used to hardcode the literal string
+``/tmp``. ``/tmp`` does not exist on Windows, so every one of those
+features failed there. A single helper keeps the resolution in one place.
+
+POSIX keeps the literal ``/tmp`` the bash hooks use (avoiding a
+``$TMPDIR`` divergence on macOS where ``tempfile.gettempdir()`` returns
+``/var/folders/...`` but the hooks still write ``/tmp``). On Windows
+there is no ``/tmp``: Git-for-Windows maps a hook's ``/tmp`` to
+``%TEMP%``, which is exactly what ``tempfile.gettempdir()`` returns, so
+both sides still meet.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def arkaos_temp_dir(*parts: str) -> Path:
+    """Return ``<coordination base>/<parts...>`` (the path is not created).
+
+    POSIX -> ``/tmp/<parts>`` (matches the bash hooks verbatim).
+    Windows -> ``<%TEMP%>/<parts>`` (matches Git-for-Windows ``/tmp``).
+    """
+    base = Path(tempfile.gettempdir()) if os.name == "nt" else Path("/tmp")
+    return base.joinpath(*parts)

package/core/synapse/kb_cache.py

@@ -30,11 +30,12 @@ from pathlib import Path
 from typing import Any, Optional
 
 from core.shared import safe_session_id as _safe_session_id_module
+from core.shared.temp_paths import arkaos_temp_dir
 
 
 # Re-export for backward compatibility with any external importers.
 SAFE_SESSION_ID_RE = _safe_session_id_module.SAFE_SESSION_ID_RE
-KB_QUERY_MARKER_DIR = Path("/tmp/arkaos-kb-query")
+KB_QUERY_MARKER_DIR = arkaos_temp_dir("arkaos-kb-query")
 _MAX_QUERIES_PER_TURN = 32
 _MAX_QUERY_LEN = 512
 
@@ -159,7 +160,7 @@ class KBSessionCache:
             self._cache_dir = Path(cache_dir)
         else:
             project_hash = self._hash_project(project_path or "")
-            self._cache_dir = Path("/tmp") / f"arkaos-kb-{project_hash}"
+            self._cache_dir = arkaos_temp_dir(f"arkaos-kb-{project_hash}")
 
         self._cache_file = self._cache_dir / f"{session_id}.json"
         self._ensure_dir()

package/core/sync/agent_provisioner.py

@@ -55,7 +55,7 @@ def _extend_from_file(path: Path, agents: set[str]) -> None:
     if not path.exists():
         return
     try:
-        data = yaml.safe_load(path.read_text()) or {}
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
     except yaml.YAMLError:
         return
     for name in data.get("baseline", []) or []:
@@ -95,10 +95,10 @@ def _apply_allowlist(
             continue
 
         target = agents_dir / f"{name}.md"
-        if target.exists() and target.read_text() == rendered:
+        if target.exists() and target.read_text(encoding="utf-8") == rendered:
             unchanged.append(name)
             continue
-        target.write_text(rendered)
+        target.write_text(rendered, encoding="utf-8")
         added.append(name)
 
     return added, unchanged, errored
@@ -124,10 +124,10 @@ def _render_agent(core: Path, name: str) -> str | None:
     parts: list[str] = []
     if yaml_path is not None:
         parts.append("---")
-        parts.append(yaml_path.read_text().strip())
+        parts.append(yaml_path.read_text(encoding="utf-8").strip())
         parts.append("---")
     if md_path is not None:
-        parts.append(md_path.read_text().rstrip())
+        parts.append(md_path.read_text(encoding="utf-8").rstrip())
 
     return "\n".join(parts) + "\n"
 

package/core/sync/ai_mcp_decider.py

@@ -76,11 +76,11 @@ def _load_cache(path: Path) -> dict[str, str]:
     if not path.exists():
         return {}
     try:
-        return json.loads(path.read_text())
+        return json.loads(path.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError):
         return {}
 
 
 def _save_cache(path: Path, data: dict[str, str]) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(data, indent=2, sort_keys=True))
+    path.write_text(json.dumps(data, indent=2, sort_keys=True), encoding="utf-8")

package/core/sync/content_syncer.py

@@ -36,7 +36,7 @@ def sync_project_content(project: Project) -> ContentSyncResult:
 
 def _do_sync(project: Project) -> ContentSyncResult:
     core = _core_root()
-    version = (core / "VERSION").read_text().strip()
+    version = (core / "VERSION").read_text(encoding="utf-8").strip()
     project_claude = Path(project.path) / ".claude"
     project_claude.mkdir(parents=True, exist_ok=True)
 
@@ -73,28 +73,28 @@ def _sync_claude_md(
     unchanged: list[str],
     errored: list[str],
 ) -> None:
-    base = (core / "config" / "user-claude.md").read_text()
+    base = (core / "config" / "user-claude.md").read_text(encoding="utf-8")
     overlays_dir = core / "config" / "standards" / "claude-md-overlays"
     overlays: list[str] = []
     for stack in project.stack:
         overlay = overlays_dir / f"{stack}.md"
         if overlay.exists():
-            overlays.append(overlay.read_text())
+            overlays.append(overlay.read_text(encoding="utf-8"))
 
     managed_content = "\n\n".join([base, *overlays]).strip()
     target_file = project_claude / "CLAUDE.md"
-    target_text = target_file.read_text() if target_file.exists() else ""
+    target_text = target_file.read_text(encoding="utf-8") if target_file.exists() else ""
 
     result = merge_managed_content(target_text, managed_content, version)
     if result.status == "error":
         errored.append(f"CLAUDE.md: {result.error}")
         sidecar = target_file.with_suffix(".md.arkaos-new")
-        sidecar.write_text(managed_content)
+        sidecar.write_text(managed_content, encoding="utf-8")
         return
     if result.status == "unchanged":
         unchanged.append("CLAUDE.md")
         return
-    target_file.write_text(result.new_text)
+    target_file.write_text(result.new_text, encoding="utf-8")
     updated.append("CLAUDE.md")
 
 
@@ -111,11 +111,11 @@ def _sync_rules(
     dst.mkdir(parents=True, exist_ok=True)
     for rule in src.glob("*.md"):
         target = dst / rule.name
-        src_text = rule.read_text()
-        if target.exists() and target.read_text() == src_text:
+        src_text = rule.read_text(encoding="utf-8")
+        if target.exists() and target.read_text(encoding="utf-8") == src_text:
             unchanged.append(f"rules/{rule.name}")
             continue
-        target.write_text(src_text)
+        target.write_text(src_text, encoding="utf-8")
         updated.append(f"rules/{rule.name}")
 
 
@@ -131,8 +131,8 @@ def _sync_hooks(
     dst.mkdir(parents=True, exist_ok=True)
     for hook in src.glob("*.sh"):
         target = dst / hook.name
-        src_text = hook.read_text()
-        if target.exists() and target.read_text() == src_text:
+        src_text = hook.read_text(encoding="utf-8")
+        if target.exists() and target.read_text(encoding="utf-8") == src_text:
             unchanged.append(f"hooks/{hook.name}")
             continue
         shutil.copy2(hook, target)
@@ -149,16 +149,16 @@ def _sync_constitution(
 ) -> None:
     src = core / "config" / "constitution.yaml"
     target = project_claude / "constitution-applicable.md"
-    data = yaml.safe_load(src.read_text()) or {}
+    data = yaml.safe_load(src.read_text(encoding="utf-8")) or {}
     rules = data.get("rules", [])
     lines = ["# ArkaOS Constitution — Applicable Rules", ""]
     for rule in rules:
         lines.append(f"- **{rule.get('name', '?')}** — {rule.get('level', '?')}")
     body = "\n".join(lines) + "\n"
-    if target.exists() and target.read_text() == body:
+    if target.exists() and target.read_text(encoding="utf-8") == body:
         unchanged.append("constitution-applicable.md")
         return
-    target.write_text(body)
+    target.write_text(body, encoding="utf-8")
     updated.append("constitution-applicable.md")
 
 

package/core/sync/descriptor_syncer.py

@@ -47,7 +47,7 @@ def sync_descriptor(project: Project) -> DescriptorSyncResult:
 def _do_sync(project: Project) -> DescriptorSyncResult:
     """Execute the descriptor sync logic for a single project."""
     desc_path = Path(project.descriptor_path)  # type: ignore[arg-type]
-    text = desc_path.read_text()
+    text = desc_path.read_text(encoding="utf-8")
     frontmatter, body = _split_frontmatter(text)
     changes: list[str] = []
 
@@ -193,4 +193,4 @@ def _get_last_commit_days(project_path: str) -> int | None:
 def _write_descriptor(desc_path: Path, frontmatter: dict, body: str) -> None:
     """Write updated frontmatter and preserved body back to the descriptor file."""
     fm_text = yaml.dump(frontmatter, default_flow_style=False, allow_unicode=True)
-    desc_path.write_text(f"---\n{fm_text}---{body}")
+    desc_path.write_text(f"---\n{fm_text}---{body}", encoding="utf-8")

package/core/sync/discovery.py

@@ -21,7 +21,7 @@ def _detect_from_composer(project_path: Path) -> list[str]:
     if not composer.exists():
         return []
     try:
-        data = json.loads(composer.read_text())
+        data = json.loads(composer.read_text(encoding="utf-8"))
         require = data.get("require", {})
         if "laravel/framework" in require:
             return ["php", "laravel"]
@@ -35,7 +35,7 @@ def _detect_from_package_json(project_path: Path) -> list[str]:
     if not pkg.exists():
         return []
     try:
-        data = json.loads(pkg.read_text())
+        data = json.loads(pkg.read_text(encoding="utf-8"))
         deps = {
             **data.get("dependencies", {}),
             **data.get("devDependencies", {}),
@@ -100,7 +100,7 @@ def _parse_descriptor_frontmatter(text: str) -> dict:
 def _read_descriptor_item(item: Path) -> dict:
     """Read a descriptor file and return its frontmatter as a dict."""
     try:
-        return _parse_descriptor_frontmatter(item.read_text())
+        return _parse_descriptor_frontmatter(item.read_text(encoding="utf-8"))
     except OSError:
         return {}
 
@@ -187,7 +187,7 @@ def discover_from_ecosystems(ecosystems_file: Path) -> list[Project]:
     if not ecosystems_file.exists():
         return []
     try:
-        data = json.loads(ecosystems_file.read_text())
+        data = json.loads(ecosystems_file.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError):
         return []
 

package/core/sync/engine.py

@@ -117,7 +117,7 @@ def _read_previous_version(arkaos_home: Path) -> str:
     if not state_file.exists():
         return "pending-sync"
     try:
-        data = json.loads(state_file.read_text())
+        data = json.loads(state_file.read_text(encoding="utf-8"))
         return data.get("version", "pending-sync") or "pending-sync"
     except (json.JSONDecodeError, OSError):
         return "pending-sync"
@@ -132,7 +132,7 @@ def _read_current_version(arkaos_home: Path) -> str:
     if not version_file.exists():
         return "unknown"
     try:
-        return version_file.read_text().strip()
+        return version_file.read_text(encoding="utf-8").strip()
     except OSError:
         return "unknown"
 
@@ -143,7 +143,7 @@ def _read_repo_path(arkaos_home: Path) -> Path | None:
     if not repo_path_file.exists():
         return None
     try:
-        raw = repo_path_file.read_text().strip()
+        raw = repo_path_file.read_text(encoding="utf-8").strip()
         return Path(raw) if raw else None
     except OSError:
         return None
@@ -204,7 +204,7 @@ def _load_scan_dirs_from_profile(arkaos_home: Path) -> list[Path]:
     if not profile_file.exists():
         return []
     try:
-        data = json.loads(profile_file.read_text())
+        data = json.loads(profile_file.read_text(encoding="utf-8"))
         projects_dir_str = data.get("projectsDir", "")
         if not projects_dir_str:
             return []

package/core/sync/manifest.py

@@ -18,7 +18,7 @@ def load_features(features_dir: Path) -> list[FeatureSpec]:
     for path in sorted(features_dir.iterdir()):
         if path.suffix != ".yaml":
             continue
-        data = yaml.safe_load(path.read_text())
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
         features.append(FeatureSpec(**data))
 
     return features

package/core/sync/mcp_optimizer.py

@@ -92,7 +92,7 @@ def _load_override(project_path: Path) -> tuple[dict, list[str]]:
     if not override.exists():
         return {}, []
     try:
-        return yaml.safe_load(override.read_text()) or {}, []
+        return yaml.safe_load(override.read_text(encoding="utf-8")) or {}, []
     except (yaml.YAMLError, OSError) as exc:
         return {}, [f"override YAML parse error: {exc}"]
 
@@ -123,7 +123,7 @@ def _inject_env_vars(project_path: Path, vault_path: Path | None, project_name:
         return []
 
     try:
-        data = json.loads(mcp_file.read_text())
+        data = json.loads(mcp_file.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError):
         return [".mcp.json malformed; skipped env injection"]
 
@@ -137,7 +137,7 @@ def _inject_env_vars(project_path: Path, vault_path: Path | None, project_name:
     changed, missing = _merge_env(servers, merged_env)
 
     if changed:
-        mcp_file.write_text(json.dumps(data, indent=2) + "\n")
+        mcp_file.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
 
     if missing:
         _write_env_example(project_path, missing)
@@ -157,7 +157,7 @@ def _load_vault(path: Path) -> tuple[dict, list[str]]:
     if st.st_mode & (stat.S_IRWXG | stat.S_IRWXO):
         return {}, ["vault permissions too permissive (group/world readable); secrets not injected"]
     try:
-        return json.loads(path.read_text()), []
+        return json.loads(path.read_text(encoding="utf-8")), []
     except (json.JSONDecodeError, OSError):
         return {}, ["vault JSON parse error; secrets not injected"]
 
@@ -167,7 +167,7 @@ def _write_env_example(project_path: Path, missing: dict[str, str]) -> None:
     for var, server in sorted(missing.items()):
         lines.append(f"# required by {server}")
         lines.append(f"{var}=")
-    (project_path / ".env.arkaos.example").write_text("\n".join(lines) + "\n")
+    (project_path / ".env.arkaos.example").write_text("\n".join(lines) + "\n", encoding="utf-8")
 
 
 def optimize_all_mcps(

package/core/sync/mcp_syncer.py

@@ -39,7 +39,7 @@ def load_registry(registry_path: Path) -> dict:
     if not registry_path.exists():
         return {}
     try:
-        data = json.loads(registry_path.read_text())
+        data = json.loads(registry_path.read_text(encoding="utf-8"))
         return data.get("mcpServers", {})
     except (json.JSONDecodeError, OSError):
         return {}
@@ -142,7 +142,7 @@ def _read_current_mcps(mcp_file: Path) -> dict:
     if not mcp_file.exists():
         return {}
     try:
-        data = json.loads(mcp_file.read_text())
+        data = json.loads(mcp_file.read_text(encoding="utf-8"))
         return data.get("mcpServers", {})
     except (json.JSONDecodeError, OSError):
         return {}
@@ -252,4 +252,4 @@ def _build_merged(
 def _write_mcp_json(mcp_file: Path, servers: dict) -> None:
     """Write the mcpServers dict to .mcp.json with 2-space indentation."""
     payload = {"mcpServers": servers}
-    mcp_file.write_text(json.dumps(payload, indent=2) + "\n")
+    mcp_file.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")

package/core/sync/policy_loader.py

@@ -30,7 +30,7 @@ class PolicyDecision:
 
 def load_policy(path: Path) -> Policy:
     """Load and parse an mcp-policy.yaml file."""
-    data = yaml.safe_load(path.read_text()) or {}
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
     rules = [
         PolicyRule(
             match=r.get("match", {}),

package/core/sync/reporter.py

@@ -74,7 +74,7 @@ def write_sync_state(state_file: Path, report: SyncReport) -> None:
         "skills_synced": len(report.skill_results),
         "errors": report.errors,
     }
-    state_file.write_text(json.dumps(state, indent=2))
+    state_file.write_text(json.dumps(state, indent=2), encoding="utf-8")
 
 
 def format_report(report: SyncReport) -> str:

package/core/sync/settings_syncer.py

@@ -82,7 +82,7 @@ def _read_current_settings(settings_file: Path) -> dict:
     if not settings_file.exists():
         return {}
     try:
-        return json.loads(settings_file.read_text())
+        return json.loads(settings_file.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError):
         return {}
 
@@ -118,4 +118,4 @@ def _build_merged_settings(current: dict, target_servers: list[str]) -> dict:
 def _write_settings(settings_file: Path, data: dict) -> None:
     """Create parent dirs if needed and write settings as 2-space JSON."""
     settings_file.parent.mkdir(parents=True, exist_ok=True)
-    settings_file.write_text(json.dumps(data, indent=2) + "\n")
+    settings_file.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")

package/core/terminal/session.py

@@ -21,16 +21,23 @@ Design notes
 from __future__ import annotations
 
 import errno
-import fcntl
 import os
-import pty
 import secrets
+import shutil
 import signal
 import struct
-import termios
 import time
 from typing import Any, Optional
 
+try:  # POSIX-only: the Windows backend lives in session_windows.py
+    import fcntl
+    import pty
+    import termios
+    _PTY_SUPPORTED = True
+except ModuleNotFoundError:
+    fcntl = pty = termios = None  # type: ignore[assignment]
+    _PTY_SUPPORTED = False
+
 from core.terminal import audit
 
 
@@ -39,10 +46,47 @@ class SessionCapacityError(RuntimeError):
 
 
 def _default_shell() -> str:
+    if os.name == "nt":
+        # Windows PowerShell renders reliably under ConPTY; bare cmd.exe can
+        # emit no prompt when the API is launched without an attached
+        # console, and the WindowsApps "pwsh" alias is a Store reparse point
+        # that misbehaves when spawned programmatically — so resolve the real
+        # System32 powershell.exe first.
+        return _resolve_windows_shell()
     return os.environ.get("SHELL") or "/bin/zsh"
 
 
+def _resolve_windows_shell() -> str:
+    """Pick a Windows shell that works under ConPTY, skipping Store aliases."""
+    candidates = []
+    pwsh = shutil.which("pwsh")
+    if pwsh and "windowsapps" not in pwsh.lower():
+        candidates.append(pwsh)
+    powershell = shutil.which("powershell")
+    if powershell:
+        candidates.append(powershell)
+    candidates.append(os.environ.get("COMSPEC") or "cmd.exe")
+    return candidates[0]
+
+
 def _default_cwd() -> str:
+    """Open new terminals in the user's configured projectsDir, else home.
+
+    The dashboard sends no cwd, so without this a terminal lands in the
+    home directory rather than where the operator actually works. Reads
+    the existing ~/.arkaos/profile.json projectsDir; falls back to home
+    when it is unset or missing (unchanged behaviour for that case).
+    """
+    try:
+        import json
+        profile = os.path.join(os.path.expanduser("~"), ".arkaos", "profile.json")
+        if os.path.isfile(profile):
+            with open(profile, encoding="utf-8") as fh:
+                projects_dir = json.load(fh).get("projectsDir")
+            if projects_dir and os.path.isdir(projects_dir):
+                return projects_dir
+    except Exception:
+        pass
     return os.path.expanduser("~")
 
 
@@ -251,14 +295,25 @@ class TerminalSessionManager:
         sid = secrets.token_urlsafe(8)
         chosen_shell = shell or _default_shell()
         chosen_cwd = cwd or _default_cwd()
-        session = TerminalSession(
-            session_id=sid,
-            shell=chosen_shell,
-            cwd=chosen_cwd,
-            cols=cols,
-            rows=rows,
-            scrollback_bytes=self.scrollback_bytes,
-        )
+        if not _PTY_SUPPORTED:
+            from core.terminal.session_windows import WindowsTerminalSession
+            session = WindowsTerminalSession(
+                session_id=sid,
+                shell=chosen_shell,
+                cwd=chosen_cwd,
+                cols=cols,
+                rows=rows,
+                scrollback_bytes=self.scrollback_bytes,
+            )
+        else:
+            session = TerminalSession(
+                session_id=sid,
+                shell=chosen_shell,
+                cwd=chosen_cwd,
+                cols=cols,
+                rows=rows,
+                scrollback_bytes=self.scrollback_bytes,
+            )
         self._sessions[sid] = session
         audit.log_start(sid, chosen_shell, chosen_cwd)
         return session