arkaos 4.3.6 → 4.5.0

package/core/hooks/user_prompt_submit.py

@@ -36,6 +36,7 @@ import subprocess
 import time
 from pathlib import Path
 
+from core.shared.temp_paths import arkaos_temp_dir
 from core.hooks._shared import (
     ensure_root_on_path,
     get_str,
@@ -45,7 +46,7 @@ from core.hooks._shared import (
     safe_session_id,
 )
 
-_CACHE_DIR = Path("/tmp/arkaos-context-cache")
+_CACHE_DIR = arkaos_temp_dir("arkaos-context-cache")
 _CACHE_TTL = 300  # Constitution cache: 5 minutes
 
 _L0_FALLBACK = (
@@ -282,7 +283,7 @@ def _kb_auto_inject(root: str, user_input: str) -> str:
     project_hash = hashlib.md5(
         root.encode(), usedforsecurity=False
     ).hexdigest()[:12]
-    cache_dir = Path("/tmp") / f"arkaos-kb-{project_hash}"
+    cache_dir = arkaos_temp_dir(f"arkaos-kb-{project_hash}")
     if not cache_dir.is_dir():
         return ""
     try:
@@ -439,7 +440,7 @@ def _wf_mark_required(session_id: str) -> None:
     if safe_session_id(session_id) is None:
         return
     marker_dir = Path(
-        os.environ.get("ARKA_WF_REQUIRED_DIR", "/tmp/arkaos-wf-required")
+        os.environ.get("ARKA_WF_REQUIRED_DIR", str(arkaos_temp_dir("arkaos-wf-required")))
     )
     try:
         marker_dir.mkdir(parents=True, exist_ok=True)
@@ -469,7 +470,7 @@ def _cognitive_hits(session_id: str) -> str:
 
 def _one_shot_nudge(subdir: str, session_id: str) -> str:
     """Read + delete a /tmp/<subdir>/<session>.json nudge state file."""
-    nudge_file = Path("/tmp") / subdir / f"{session_id}.json"
+    nudge_file = arkaos_temp_dir(subdir) / f"{session_id}.json"
     if not nudge_file.is_file():
         return ""
     nudge = ""

package/core/knowledge/indexer.py

@@ -56,7 +56,7 @@ def index_directory(
 
         fhash = file_hash(filepath)
 
-        if skip_indexed and store.is_file_indexed(fhash):
+        if skip_indexed and store.is_file_indexed(str(filepath), fhash):
             skipped += 1
             continue
 

package/core/knowledge/vector_store.py

@@ -347,10 +347,17 @@ class VectorStore:
             for r in rows
         ]
 
-    def is_file_indexed(self, file_hash: str) -> bool:
-        """Check if a file has already been indexed."""
+    def is_file_indexed(self, source: str, file_hash: str) -> bool:
+        """Check if a file (identified by source path + content hash) is indexed.
+
+        The source path is part of the key so identical content in two
+        different locations (e.g. two npx cache directories) each gets
+        indexed — a hash-only check would skip every subsequent cache
+        and leave the new location unsearchable.
+        """
         row = self._db.execute(
-            "SELECT COUNT(*) as cnt FROM chunks WHERE file_hash = ?", (file_hash,)
+            "SELECT COUNT(*) as cnt FROM chunks WHERE source = ? AND file_hash = ?",
+            (source, file_hash),
         ).fetchone()
         return row["cnt"] > 0
 

package/core/runtime/native_usage.py

@@ -33,9 +33,10 @@ from typing import Any
 from core.runtime.llm_cost_telemetry import record_cost
 from core.runtime.pricing import estimate_cost_usd
 from core.shared.safe_session_id import safe_session_id
+from core.shared.temp_paths import arkaos_temp_dir
 
 
-DEFAULT_CURSOR_DIR = Path("/tmp/arkaos-native-cost")
+DEFAULT_CURSOR_DIR = arkaos_temp_dir("arkaos-native-cost")
 
 _USAGE_KEYS = (
     "input_tokens",

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 {}
@@ -60,6 +60,10 @@ def resolve_mcps_for_stack(
 
     result: list[tuple[str, dict]] = []
     for name, config in registry.items():
+        if "managed" in config:
+            # Runtime-managed servers (extension/plugin) are registered for
+            # governance and telemetry — they have no launchable command to write.
+            continue
         if config.get("category") in allowed:
             result.append((name, config))
     return result
@@ -142,7 +146,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 +256,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")