arkaos 5.9.0 → 5.11.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v5.9.0 — 89 agents, 17 departments, 340 skills, 306 commands, 20 ADRs.
+> v5.10.0 — 89 agents, 17 departments, 340 skills, 306 commands, 20 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-5.9.0
+5.11.0

package/bin/arka-menubar.py

@@ -79,17 +79,23 @@ def read_state(home: Path | None = None) -> dict:
         "autoupdate_on": True,
     }
     try:
-        manifest = json.loads((home / "install-manifest.json").read_text())
+        manifest = json.loads(
+            (home / "install-manifest.json").read_text(encoding="utf-8")
+        )
         state["version"] = manifest.get("version") or None
     except Exception:
         pass
     try:
-        sync = json.loads((home / "sync-state.json").read_text())
+        sync = json.loads(
+            (home / "sync-state.json").read_text(encoding="utf-8")
+        )
         state["sync_pending"] = sync.get("version") == "pending-sync"
     except Exception:
         pass
     try:
-        profile = json.loads((home / "profile.json").read_text())
+        profile = json.loads(
+            (home / "profile.json").read_text(encoding="utf-8")
+        )
         value = str(profile.get("installProfile", "essential")).strip().lower()
         state["profile"] = value if value in VALID_PROFILES else "essential"
     except Exception:
@@ -154,7 +160,7 @@ def stable_script(name: str) -> Path | None:
     if lib.exists():
         return lib
     try:
-        repo = Path((home / ".repo-path").read_text().strip())
+        repo = Path((home / ".repo-path").read_text(encoding="utf-8").strip())
         candidate = repo / "scripts" / name
         if candidate.exists():
             return candidate
@@ -190,7 +196,8 @@ def action_open_dashboard() -> None:
             log_line(f"open_dashboard: ensure failed ({err})")
     ui_port = ""
     try:
-        for line in (arka_home() / "dashboard.ports").read_text().splitlines():
+        ports = (arka_home() / "dashboard.ports").read_text(encoding="utf-8")
+        for line in ports.splitlines():
             if line.startswith("UI_PORT="):
                 ui_port = line.split("=", 1)[1].strip()
     except Exception:

package/core/agents/loader.py

@@ -24,7 +24,7 @@ def load_agent(path: str | Path) -> Agent:
     if not path.exists():
         raise FileNotFoundError(f"Agent file not found: {path}")
 
-    with open(path) as f:
+    with open(path, encoding="utf-8") as f:
         data = yaml.safe_load(f)
 
     if data is None:

package/core/agents/registry_gen.py

@@ -126,7 +126,7 @@ def generate_registry(departments_dir: str | Path, output_path: str | Path) -> d
         registry["_meta"]["errors"] = errors
 
     output_path.parent.mkdir(parents=True, exist_ok=True)
-    with open(output_path, "w") as f:
+    with open(output_path, "w", encoding="utf-8") as f:
         json.dump(registry, f, indent=2, ensure_ascii=False)
 
     return registry

package/core/budget/manager.py

@@ -178,13 +178,13 @@ class BudgetManager:
             "counter": self._counter,
             "usages": [u.model_dump(mode="json") for u in self._usages],
         }
-        with open(self._storage_path, "w") as f:
+        with open(self._storage_path, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
 
     def _load(self) -> None:
         if self._storage_path is None or not self._storage_path.exists():
             return
-        content = self._storage_path.read_text().strip()
+        content = self._storage_path.read_text(encoding="utf-8").strip()
         if not content:
             return
         data = json.loads(content)

package/core/cognition/scheduler/daemon.py

@@ -61,7 +61,7 @@ class ScheduleConfig:
     @classmethod
     def load(cls, config_path: str) -> "list[ScheduleConfig]":
         """Load schedules from YAML, returning only enabled entries."""
-        with open(config_path) as fh:
+        with open(config_path, encoding="utf-8") as fh:
             data = yaml.safe_load(fh)
 
         schedules = []
@@ -106,7 +106,7 @@ class ArkaScheduler:
         """Acquire an exclusive file lock. Returns False if already locked."""
         Path(self._lock_path).parent.mkdir(parents=True, exist_ok=True)
         try:
-            fd = open(self._lock_path, "w")  # noqa: WPS515
+            fd = open(self._lock_path, "w", encoding="utf-8")  # noqa: WPS515
             if sys.platform == "win32":
                 import msvcrt  # type: ignore[import]
 

package/core/conclave/persistence.py

@@ -22,7 +22,7 @@ def save_profile(board: ConclaveBoard, path: str | Path = "") -> None:
         "contrarian": [a.model_dump(mode="json") for a in board.contrarian],
     }
 
-    with open(path, "w") as f:
+    with open(path, "w", encoding="utf-8") as f:
         json.dump(data, f, indent=2, ensure_ascii=False)
 
 
@@ -33,7 +33,7 @@ def load_profile(path: str | Path = "") -> Optional[ConclaveBoard]:
     if not path.exists():
         return None
 
-    content = path.read_text().strip()
+    content = path.read_text(encoding="utf-8").strip()
     if not content:
         return None
 

package/core/forge/orchestrator.py

@@ -474,7 +474,11 @@ class ForgeOrchestrator:
             repo = Path.cwd().name
 
         version_file = Path(__file__).parent.parent.parent / "VERSION"
-        version = version_file.read_text().strip() if version_file.exists() else "unknown"
+        version = (
+            version_file.read_text(encoding="utf-8").strip()
+            if version_file.exists()
+            else "unknown"
+        )
 
         self._forge_context = ForgeContext(
             repo=repo,

package/core/governance/constitution.py

@@ -146,7 +146,7 @@ def load_constitution(path: str | Path) -> Constitution:
     if not path.exists():
         raise FileNotFoundError(f"Constitution file not found: {path}")
 
-    with open(path) as f:
+    with open(path, encoding="utf-8") as f:
         data = yaml.safe_load(f)
 
     return Constitution.model_validate(data)

package/core/governance/evidence_checks.py

@@ -35,7 +35,8 @@ import subprocess
 import sys
 import time
 from dataclasses import asdict, dataclass, field, replace
-from pathlib import Path
+from pathlib import Path, PurePosixPath
+from xml.etree import ElementTree
 
 from core.governance.qg_digest import evidence_digest
 from core.shared.test_evidence import coverage_percent_from_xml
@@ -553,30 +554,172 @@ def _junit_result(junit: Path) -> CheckResult:
     )
 
 
+def _coverage_from_xml(
+    coverage_xml: Path, project_dir: Path, changed: list[str] | None,
+) -> CheckResult:
+    """Coverage verdict from an artefact, refusing one that cannot describe the diff."""
+    stale = _stale_coverage_reason(coverage_xml, project_dir, changed)
+    if stale is not None:
+        return CheckResult(
+            check="coverage", ran=True, passed=False,
+            command="parse:coverage.xml", exit_code=None,
+            summary=stale, details_path=str(coverage_xml),
+        )
+    percent = coverage_percent_from_xml(coverage_xml)
+    if percent is None:
+        return CheckResult(
+            check="coverage", ran=True, passed=None,
+            command="parse:coverage.xml", exit_code=None,
+            summary="coverage.xml present but unparseable",
+            details_path=str(coverage_xml),
+        )
+    return CheckResult(
+        check="coverage", ran=True,
+        passed=percent >= COVERAGE_THRESHOLD,
+        command="parse:coverage.xml", exit_code=None,
+        summary=f"coverage {percent:.1f}% (threshold {COVERAGE_THRESHOLD:.0f}%)",
+        details_path=str(coverage_xml),
+    )
+
+
+def _stale_coverage_reason(
+    coverage_xml: Path, project_dir: Path, changed: list[str] | None,
+) -> str | None:
+    """Reason the artefact cannot describe this diff, or None if it can.
+
+    A coverage.xml older than the newest changed source measured a different
+    codebase, and a green number then vouches for code it never executed.
+    """
+    try:
+        artefact_mtime = coverage_xml.stat().st_mtime
+    except OSError:
+        return "coverage.xml unreadable"
+
+    newest_name = _newest_changed_after(project_dir, changed, artefact_mtime)
+    if newest_name is not None:
+        return (
+            f"coverage.xml predates changed source ({newest_name}) — "
+            "regenerate it; it cannot describe this diff"
+        )
+    return _missing_module_reason(coverage_xml, changed, project_dir)
+
+
+def _missing_module_reason(
+    coverage_xml: Path, changed: list[str] | None, project_dir: Path,
+) -> str | None:
+    """Reason a changed module is absent from the artefact, or None."""
+    covered = _covered_paths(coverage_xml, project_dir)
+    missing = [
+        rel for rel in (changed or [])
+        if rel.endswith(".py")
+        and not rel.startswith("tests/")
+        and not _is_covered(rel, covered)
+    ]
+    if not missing:
+        return None
+    return (
+        f"coverage.xml has no entry for {len(missing)} changed module(s), "
+        f"first: {missing[0]}"
+    )
+
+
+def _newest_changed_after(
+    project_dir: Path, changed: list[str] | None, cutoff: float,
+) -> str | None:
+    """Name of the newest changed .py file modified after cutoff, else None.
+
+    Only executable source can invalidate a coverage artefact — treating
+    CHANGELOG.md as "changed source" forced a full regeneration for edits no
+    test could ever execute (same filter the module-presence check applies).
+    """
+    newest = cutoff
+    newest_name: str | None = None
+    for rel in changed or []:
+        if not rel.endswith(".py"):
+            continue
+        try:
+            mtime = (project_dir / rel).stat().st_mtime
+        except OSError:
+            continue
+        if mtime > newest:
+            newest, newest_name = mtime, rel
+    return newest_name
+
+
+def _covered_paths(coverage_xml: Path, project_dir: Path) -> set[str]:
+    """Covered files as paths relative to project_dir, exactly.
+
+    A ``class/@filename`` is relative to one of the ``sources/source``
+    roots, which are usually absolute and which the changed-file list never
+    carries. Each candidate is therefore rebuilt against every source and
+    re-expressed relative to the project, so comparison can be equality.
+
+    Suffix or stem matching is not good enough here: `core/` alone carries
+    14 colliding stems, this repo's own artefact yields five bare basenames,
+    and a suffix rule cannot tell `core/sync/engine.py` from
+    `vendor/core/sync/engine.py`. Equality can.
+    """
+    try:
+        root = ElementTree.parse(coverage_xml).getroot()
+    except (ElementTree.ParseError, OSError):
+        return set()
+    sources = [(el.text or "").strip() for el in root.iterfind("sources/source")]
+    try:
+        base = project_dir.resolve()
+    except OSError:
+        base = project_dir
+    return {
+        candidate
+        for cls in root.iter("class")
+        if cls.get("filename")
+        for candidate in _source_candidates(cls.get("filename", ""), sources, base)
+    }
+
+
+def _source_candidates(
+    filename: str, sources: list[str], base: Path,
+) -> set[str]:
+    """Project-relative spellings of one covered file, anchored.
+
+    With ``<source>`` roots declared, every candidate must resolve through
+    one of them into the project — the unanchored raw filename let another
+    checkout's artefact vouch for this project's files. The raw spelling is
+    a fallback only when no sources exist; a relative source resolves
+    against the project, never the CWD.
+    """
+    if not sources:
+        raw = PurePosixPath(filename)
+        return set() if raw.is_absolute() else {raw.as_posix()}
+
+    # Candidates must exist on disk; existence under more than one source
+    # is ambiguous — vouch for neither (fail closed).
+    found: set[str] = set()
+    for source in sources:
+        src = Path(source)
+        if not src.is_absolute():
+            src = base / src
+        try:
+            resolved = (src / filename).resolve()
+            if not resolved.is_file():
+                continue
+            found.add(PurePosixPath(resolved.relative_to(base)).as_posix())
+        except (OSError, ValueError):
+            continue
+    return found if len(found) == 1 else set()
+
+
+def _is_covered(rel: str, covered: set[str]) -> bool:
+    """True only when the artefact names exactly this project-relative path."""
+    return PurePosixPath(rel).as_posix() in covered
+
+
 def _check_coverage(
     project_dir: Path, changed: list[str] | None,
     test_command: str | None, timeout: int,
 ) -> CheckResult:
     coverage_xml = project_dir / "coverage.xml"
     if coverage_xml.is_file():
-        percent = coverage_percent_from_xml(coverage_xml)
-        if percent is None:
-            return CheckResult(
-                check="coverage", ran=True, passed=None,
-                command="parse:coverage.xml", exit_code=None,
-                summary="coverage.xml present but unparseable",
-                details_path=str(coverage_xml),
-            )
-        return CheckResult(
-            check="coverage", ran=True,
-            passed=percent >= COVERAGE_THRESHOLD,
-            command="parse:coverage.xml", exit_code=None,
-            summary=(
-                f"coverage {percent:.1f}% "
-                f"(threshold {COVERAGE_THRESHOLD:.0f}%)"
-            ),
-            details_path=str(coverage_xml),
-        )
+        return _coverage_from_xml(coverage_xml, project_dir, changed)
     junit = project_dir / "junit.xml"
     if junit.is_file():
         return _junit_result(junit)
@@ -767,9 +910,10 @@ def _check_spellcheck(
 def _spellcheck_inspected_count(project_dir: Path, md_files: list[str]) -> int:
     """How many of ``md_files`` codespell actually reads after `skip`.
 
-    Asks codespell itself (``--count`` on a per-file basis is too slow; a
-    skipped file simply produces no output for any planted probe), so instead
-    we replay its own glob semantics from the config.
+    Replays the config's skip globs with fnmatch rather than asking codespell
+    itself — per-file ``--count`` probing is too slow, and a skipped file
+    simply produces no output, so codespell cannot be asked which files it
+    ignored.
     """
     patterns = _codespell_skip_globs(project_dir)
     if not patterns:

package/core/governance/quality_api.py

@@ -31,14 +31,14 @@ def _load_queue() -> list[dict]:
     if not _QUEUE_FILE.exists():
         return []
     try:
-        return json.loads(_QUEUE_FILE.read_text())
+        return json.loads(_QUEUE_FILE.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError):
         return []
 
 
 def _save_queue(queue: list[dict]) -> None:
     _ensure_state_dir()
-    _QUEUE_FILE.write_text(json.dumps(queue, indent=2))
+    _QUEUE_FILE.write_text(json.dumps(queue, indent=2), encoding="utf-8")
 
 
 def _load_workflows() -> list[dict]:
@@ -46,14 +46,14 @@ def _load_workflows() -> list[dict]:
     if not _WORKFLOWS_FILE.exists():
         return []
     try:
-        return json.loads(_WORKFLOWS_FILE.read_text())
+        return json.loads(_WORKFLOWS_FILE.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError):
         return []
 
 
 def _save_workflows(workflows: list[dict]) -> None:
     _ensure_state_dir()
-    _WORKFLOWS_FILE.write_text(json.dumps(workflows, indent=2))
+    _WORKFLOWS_FILE.write_text(json.dumps(workflows, indent=2), encoding="utf-8")
 
 
 def submit(

package/core/governance/skill_proposer.py

@@ -9,9 +9,10 @@ Mirror of the PR20 reorganizer pattern but focused on capability-capture.
 
 from __future__ import annotations
 
+import hashlib
 import re
 from dataclasses import dataclass
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 
 _COMPLETION_PATTERNS: tuple[re.Pattern[str], ...] = (
@@ -41,7 +42,14 @@ _DEFAULT_OUTPUT_DIR: Path = Path.home() / ".arkaos" / "skill-proposals"
 
 @dataclass(frozen=True)
 class SkillProposal:
-    """Outcome of a skill-evaluation pass."""
+    """Outcome of a skill-evaluation pass.
+
+    ``proposal_path`` is set only when a file was actually written. It is
+    ``None`` both when no proposal was warranted and when one was
+    rendered but had nowhere safe to go (reason ``no-safe-filename``) —
+    in that second case ``proposal_markdown`` still carries the capture,
+    so a caller can route it somewhere else.
+    """
     should_propose: bool
     reason: str
     suggested_slug: str | None
@@ -75,12 +83,81 @@ def evaluate(
     markdown = _render_proposal(text, slug, today=today)
     out_dir = output_dir or _DEFAULT_OUTPUT_DIR
     out_dir.mkdir(parents=True, exist_ok=True)
-    iso_today = today or datetime.now(timezone.utc).strftime("%Y-%m-%d")
-    path = out_dir / f"{iso_today}-{slug}.md"
+    iso_today = today or datetime.now(UTC).strftime("%Y-%m-%d")
+    path = _collision_free_path(out_dir, iso_today, slug, markdown)
+    if path is None:
+        return SkillProposal(False, "no-safe-filename", slug, None, markdown)
     path.write_text(markdown, encoding="utf-8")
     return SkillProposal(True, "proposed", slug, path, markdown)
 
 
+def _collision_free_path(
+    out_dir: Path, iso_today: str, slug: str, markdown: str
+) -> Path | None:
+    """Return a path for today's proposal, or ``None`` if none is safe.
+
+    ``_suggest_slug`` anchors on the first matching skill-worthy hint, so
+    same-day slug collisions are the norm: the six word hints plus the
+    fallback yield seven fixed names, and the numeric ``N-phase`` hint
+    mints a fresh one per number it matches (until ``_slugify``'s 60-char
+    cap truncates the extremes back together). The space is small in
+    practice, but it is not the fixed handful this docstring once
+    claimed. Every proposal after the first with the same slug used to
+    overwrite its predecessor, silently: distinct captured capabilities
+    were lost with no error and no trace.
+
+    Disambiguates by content digest rather than a counter, so re-running
+    the hook over the same closing message stays idempotent (same content
+    -> same path -> one file) while genuinely different proposals get
+    their own. One invariant holds every branch honest: never return a
+    path unless it is free or provably holds this exact proposal.
+
+    A name built from our digest proves nothing about the bytes inside
+    the file — any file can carry any name, no hash collision required.
+    So when the plain name and both digest names are all occupied by
+    content we cannot account for, this returns ``None`` and the caller
+    writes nothing: losing one capture is honest, overwriting somebody
+    else's is not.
+
+    The digest names are checked before the plain one, so a re-fire after
+    the operator deleted the plain twin lands back on the file it already
+    wrote instead of duplicating it.
+    """
+    digest = hashlib.sha256(markdown.encode("utf-8")).hexdigest()
+    plain = out_dir / f"{iso_today}-{slug}.md"
+    # 8 hex chars keep the filename readable; the full digest is the
+    # tie-breaker for the day those 32 bits meet a different proposal.
+    digest_paths = (
+        out_dir / f"{iso_today}-{slug}-{digest[:8]}.md",
+        out_dir / f"{iso_today}-{slug}-{digest}.md",
+    )
+    for candidate in digest_paths:
+        if _already_holds(candidate, markdown):
+            return candidate
+    if not plain.exists() or _already_holds(plain, markdown):
+        return plain
+    for candidate in digest_paths:
+        if not candidate.exists():
+            return candidate
+    return None
+
+
+def _already_holds(path: Path, markdown: str) -> bool:
+    """True only when ``path`` provably contains exactly ``markdown``.
+
+    Content we cannot read back is not "equal": a missing, unreadable, or
+    non-UTF-8 file is unknown content, and the caller must treat unknown
+    as another proposal rather than write over it. ``UnicodeDecodeError``
+    is a ``ValueError``, not an ``OSError`` — both belong in the same
+    branch, or the exception escapes ``evaluate`` into the Stop hook's
+    blanket ``except Exception: pass`` and the proposal is lost silently.
+    """
+    try:
+        return path.read_text(encoding="utf-8") == markdown
+    except (OSError, ValueError):
+        return False
+
+
 def _has_completion_signal(text: str) -> bool:
     return any(p.search(text) for p in _COMPLETION_PATTERNS)
 
@@ -108,7 +185,7 @@ def _slugify(value: str) -> str:
 
 
 def _render_proposal(text: str, slug: str, *, today: str | None) -> str:
-    iso = today or datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    iso = today or datetime.now(UTC).strftime("%Y-%m-%d")
     excerpt = text.strip()
     if len(excerpt) > 1000:
         excerpt = excerpt[:1000].rstrip() + "..."

package/core/hooks/session_start.py

@@ -24,6 +24,7 @@ module; with no usable venv it emits a static banner (fail-open).
 
 from __future__ import annotations
 
+import contextlib
 import json
 import os
 import re
@@ -247,13 +248,46 @@ def _marker_safe(value: str) -> str:
     return _CONTROL_RE.sub("", value.splitlines()[0]) if value else value
 
 
+def _spawning_suppressed() -> bool:
+    """Whether this process may launch the operator's background daemons.
+
+    SessionStart spawns two long-lived side processes: the dashboard
+    (`_ensure_dashboard`) and the reorganizer. Both take the *resolved repo
+    root* as their working tree, and `start-dashboard` kills the PIDs
+    recorded in `~/.arkaos/dashboard.pid` — one shared file for every
+    checkout on the machine — before registering its own. (`ensure` leaves
+    a healthy instance alone; `find_port` steps past occupied ports.)
+
+    Run the hook from a test and that is a live-fire action on the machine
+    running the tests: the operator's dashboard is killed through that
+    global PID file and replaced by one served out of the test tree — a
+    checkout that legitimately lacks whatever local state the real install
+    has. It looks like the dashboard broke, not like a test ran.
+    (Observed 2026-07-27: two separate pytest invocations silently took
+    over ports 3333/3334 and served a blank UI.)
+
+    ARKA_HOOK_NO_SPAWN=1 is the explicit switch. PYTEST_CURRENT_TEST is
+    honored as well, deliberately: a test author who forgets the switch
+    should lose a background process they never wanted, not the dashboard
+    they were using. pytest exports it into the environment every child
+    process inherits, so the safety net costs nothing in production, where
+    the variable is simply absent.
+    """
+    return bool(
+        os.environ.get("ARKA_HOOK_NO_SPAWN") == "1"
+        or os.environ.get("PYTEST_CURRENT_TEST")
+    )
+
+
 def _spawn_detached(cmd: list[str], repo: str, log_path: Path | None = None) -> None:
+    if _spawning_suppressed():
+        return
     stdout = subprocess.DEVNULL
     handle = None
     try:
         if log_path is not None:
             log_path.parent.mkdir(parents=True, exist_ok=True)
-            handle = log_path.open("a")
+            handle = log_path.open("a", encoding="utf-8")
             stdout = handle
         subprocess.Popen(
             cmd,
@@ -436,6 +470,47 @@ def build_recap(cwd: str, budget_ms: int = _BUDGET_MS) -> str:
         return ""
 
 
+_CONTRACT_FAILURE_LOG = (
+    Path.home() / ".arkaos" / "telemetry" / "session-start-failures.jsonl"
+)
+
+
+def _contracts_unavailable_notice(exc: BaseException) -> str:
+    """Say the contracts are missing instead of returning an empty string.
+
+    build_context() produces [ARKA:EVIDENCE-FLOW], [ARKA:SKILL-CONTRACT],
+    [ARKA:META-TAG], [ARKA:AUTHORITY] and [ARKA:MODEL-FABRIC], plus the
+    resume and root lines and, when present, the [SESSION-MEMORY] recap —
+    the rules the session is supposed to run under. Swallowing a failure here returns the exact
+    state those blocks exist to prevent: a session with no idea the rules
+    exist, behaving like a generic assistant, with nothing anywhere saying
+    why. That is indistinguishable from the hook never having run, which
+    is precisely how the Windows delivery gap survived unnoticed for
+    months (PR #408).
+
+    Same principle `_authority_brief` already applies: one honest line
+    beats a silent void. The greeting still never breaks
+    and the hook still exits 0.
+    """
+    with contextlib.suppress(Exception):  # telemetry must never be the thing that breaks
+        _CONTRACT_FAILURE_LOG.parent.mkdir(parents=True, exist_ok=True)
+        with _CONTRACT_FAILURE_LOG.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps({
+                "ts": datetime.now(UTC).isoformat(),
+                "event": "build_context_failed",
+                "error_type": type(exc).__name__,
+                "error": str(exc)[:500],
+            }) + "\n")
+    return (
+        f"\n[ARKA:CONTRACTS] unavailable ({type(exc).__name__}) — the evidence "
+        f"flow, skill-routing, meta-tag, authority and model-routing contracts "
+        f"could not be built for this session. Treat their absence as a fault, not as "
+        f"permission: keep routing and gating as if they were present, and "
+        f"report the failure. Detail in "
+        f"~/.arkaos/telemetry/session-start-failures.jsonl"
+    )
+
+
 def main(stdin_json: dict | None = None) -> int:
     if stdin_json is None:
         stdin_json, _ = read_stdin_json()
@@ -450,8 +525,8 @@ def main(stdin_json: dict | None = None) -> int:
         visible = _FALLBACK_BANNER + "\n  Olá, founder\n"
     try:
         context = build_context(cwd)
-    except Exception:  # contracts are best-effort; greeting never breaks
-        context = ""
+    except Exception as exc:  # greeting never breaks — but never lie either
+        context = _contracts_unavailable_notice(exc)
     payload: dict = {"systemMessage": visible}
     if context:
         # Assign the sub-dict key explicitly — SessionStart's wrapper also

package/core/keys.py

@@ -34,12 +34,12 @@ PROVIDERS = {
 def _load() -> dict[str, str]:
     if not KEYS_PATH.exists():
         return {}
-    return json.loads(KEYS_PATH.read_text())
+    return json.loads(KEYS_PATH.read_text(encoding="utf-8"))
 
 
 def _save(keys: dict[str, str]) -> None:
     KEYS_PATH.parent.mkdir(parents=True, exist_ok=True)
-    KEYS_PATH.write_text(json.dumps(keys, indent=2))
+    KEYS_PATH.write_text(json.dumps(keys, indent=2), encoding="utf-8")
     os.chmod(KEYS_PATH, stat.S_IRUSR | stat.S_IWUSR)  # 600
 
 

package/core/obsidian/writer.py

@@ -131,7 +131,7 @@ class ObsidianWriter:
         if config_path.exists():
             try:
                 from core.runtime.path_resolver import resolve
-                config = json.loads(config_path.read_text())
+                config = json.loads(config_path.read_text(encoding="utf-8"))
                 vault = resolve(config.get("vault_path", ""))
                 if vault and not vault.startswith("${") and Path(vault).exists():
                     return Path(vault)