arkaos 4.3.0 → 4.3.2

package/config/hooks/token-hygiene.sh

@@ -13,6 +13,10 @@
 
 set +e  # never fail
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
 _prompt="${ARKA_PROMPT:-}"
 _transcript="${ARKA_TRANSCRIPT_PATH:-}"
 _suggestions=""
@@ -64,7 +68,7 @@ if [ -n "$_transcript" ] && [ -f "$_transcript" ] && [ -n "$_prompt" ]; then
   _cur_kw=$(_kw "$_prompt" | head -20)
   # pull last 3 user messages from transcript jsonl
   _prior=$(tail -n 200 "$_transcript" 2>/dev/null \
-    | python3 -c "
+    | "$ARKA_PY" -c "
 import sys, json
 msgs=[]
 for line in sys.stdin:

package/config/hooks/user-prompt-submit-v2.sh

@@ -7,6 +7,10 @@
 
 input=$(cat)
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
 # ─── V1 Migration Detection ─────────────────────────────────────────────
 V1_PATHS=("$HOME/.claude/skills/arka-os" "$HOME/.claude/skills/arkaos")
 MIGRATION_MARKER="$HOME/.arkaos/migrated-from-v1"
@@ -27,12 +31,12 @@ if [ -f "$ARKAOS_VERSION_FILE" ]; then
   if [ -f "$_REPO_PATH/VERSION" ]; then
     _CURRENT_VERSION=$(cat "$_REPO_PATH/VERSION")
   elif [ -f "$_REPO_PATH/package.json" ]; then
-    _CURRENT_VERSION=$(python3 -c "import json; print(json.load(open('$_REPO_PATH/package.json'))['version'])" 2>/dev/null || echo "")
+    _CURRENT_VERSION=$("$ARKA_PY" -c "import json; print(json.load(open('$_REPO_PATH/package.json'))['version'])" 2>/dev/null || echo "")
   fi
 
   if [ -n "${_CURRENT_VERSION:-}" ]; then
     if [ -f "$SYNC_STATE" ]; then
-      _SYNCED_VERSION=$(python3 -c "import json; print(json.load(open('$SYNC_STATE'))['version'])" 2>/dev/null || echo "none")
+      _SYNCED_VERSION=$("$ARKA_PY" -c "import json; print(json.load(open('$SYNC_STATE'))['version'])" 2>/dev/null || echo "none")
     else
       _SYNCED_VERSION="none"
     fi
@@ -53,9 +57,9 @@ if [ ! -f "$_SESSION_MARKER" ] && [ ! -f "/tmp/arkaos-greeted-today" ]; then
   _GREETING_COMPANY=""
   _GREETING_VERSION=""
 
-  if [ -f "$HOME/.arkaos/profile.json" ] && command -v python3 &>/dev/null; then
-    _GREETING_NAME=$(python3 -c "import json; p=json.load(open('$HOME/.arkaos/profile.json')); print(p.get('name', p.get('role', 'founder')))" 2>/dev/null)
-    _GREETING_COMPANY=$(python3 -c "import json; print(json.load(open('$HOME/.arkaos/profile.json')).get('company', ''))" 2>/dev/null)
+  if [ -f "$HOME/.arkaos/profile.json" ] && command -v "$ARKA_PY" >/dev/null 2>&1; then
+    _GREETING_NAME=$("$ARKA_PY" -c "import json; p=json.load(open('$HOME/.arkaos/profile.json')); print(p.get('name', p.get('role', 'founder')))" 2>/dev/null)
+    _GREETING_COMPANY=$("$ARKA_PY" -c "import json; print(json.load(open('$HOME/.arkaos/profile.json')).get('company', ''))" 2>/dev/null)
   fi
 
   if [ -f "$HOME/.arkaos/.repo-path" ]; then
@@ -111,12 +115,12 @@ fi
 python_result=""
 BRIDGE_SCRIPT="${ARKAOS_ROOT}/scripts/synapse-bridge.py"
 
-if command -v python3 &>/dev/null && [ -f "$BRIDGE_SCRIPT" ]; then
-  bridge_output=$(echo "{\"user_input\":$(echo "$user_input" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))" 2>/dev/null || echo '""')}" \
-    | ARKAOS_ROOT="$ARKAOS_ROOT" python3 "$BRIDGE_SCRIPT" --root "$ARKAOS_ROOT" 2>/dev/null)
+if command -v "$ARKA_PY" >/dev/null 2>&1 && [ -f "$BRIDGE_SCRIPT" ]; then
+  bridge_output=$(echo "{\"user_input\":$(echo "$user_input" | "$ARKA_PY" -c "import sys,json; print(json.dumps(sys.stdin.read()))" 2>/dev/null || echo '""')}" \
+    | ARKAOS_ROOT="$ARKAOS_ROOT" "$ARKA_PY" "$BRIDGE_SCRIPT" --root "$ARKAOS_ROOT" 2>/dev/null)
 
   if [ -n "$bridge_output" ]; then
-    python_result=$(echo "$bridge_output" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('context_string',''))" 2>/dev/null)
+    python_result=$(echo "$bridge_output" | "$ARKA_PY" -c "import sys,json; print(json.loads(sys.stdin.read()).get('context_string',''))" 2>/dev/null)
   fi
 fi
 

package/config/hooks/user-prompt-submit.sh

@@ -34,9 +34,13 @@ if [ -z "${ARKAOS_ROOT:-}" ]; then
 fi
 export ARKAOS_ROOT
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
 _ARKA_L0_FALLBACK='{"additionalContext": "[Constitution] NON-NEGOTIABLE: branch-isolation, obsidian-output, authority-boundaries, security-gate, context-first, solid-clean-code, spec-driven, human-writing, squad-routing, full-visibility, sequential-validation, mandatory-qa, arka-supremacy | QUALITY-GATE: marta-cqo, eduardo-copy, francisca-tech-ux | MUST: conventional-commits, test-coverage, pattern-matching, actionable-output, memory-persistence"}'
 
-if ! command -v python3 &>/dev/null; then
+if ! command -v "$ARKA_PY" >/dev/null 2>&1; then
   echo "$_ARKA_L0_FALLBACK"
   exit 0
 fi
@@ -54,20 +58,7 @@ if [ ! -f "$ARKAOS_ROOT/core/hooks/user_prompt_submit.py" ]; then
   fi
 fi
 
-# Interpreter resolution: prefer the ArkaOS venv (has pyyaml/pydantic);
-# otherwise probe — an unrelated project venv first on PATH would give a
-# python3 without yaml and silently degrade every gate.
-_PY=""
-for _cand in "$HOME/.arkaos/venv/bin/python3" "$HOME/.arkaos/.venv/bin/python3"; do
-  if [ -x "$_cand" ]; then _PY="$_cand"; break; fi
-done
-if [ -z "$_PY" ]; then
-  _PY="python3"
-  if ! "$_PY" -c "import yaml" 2>/dev/null; then
-    for _cand in /opt/homebrew/bin/python3 /usr/local/bin/python3 /usr/bin/python3; do
-      if [ -x "$_cand" ] && "$_cand" -c "import yaml" 2>/dev/null; then _PY="$_cand"; break; fi
-    done
-  fi
-fi
+# Interpreter resolution handled by the shared resolver (ARKA_PY): prefers
+# the ArkaOS venv (has pyyaml/pydantic), falls back to a yaml-capable python3.
 PYTHONPATH="$ARKAOS_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-  exec "$_PY" -m core.hooks.user_prompt_submit
+  exec "$ARKA_PY" -m core.hooks.user_prompt_submit

package/core/fusion/cli.py

@@ -1,8 +1,15 @@
-"""Fusion CLI — smoke path for the panel → judge pipeline.
+"""Fusion CLI — run the panel → judge → synthesis pipeline.
 
 Usage::
 
     python -m core.fusion.cli "your question"
+    python -m core.fusion.cli --save "your question"   # persist the panel
+    python -m core.fusion.cli --show                   # show the panel only
+
+When ``models.yaml`` has no ``fusion.panel``, a default is built from the
+machine's models (runtime + local Ollama) so fusion works out of the box.
+``--save`` writes that panel into ``~/.arkaos/models.yaml`` so every
+fusion consumer (and the dashboard) sees it.
 """
 
 from __future__ import annotations
@@ -10,16 +17,60 @@ from __future__ import annotations
 import sys
 
 from core.fusion.engine import FusionUnavailable, fuse
+from core.fusion.panel_builder import default_panel, describe_panel
+from core.runtime.model_router import load_config
+
+
+def _save_panel(panel, judge) -> str:
+    import yaml
+    from core.runtime.model_router import USER_CONFIG_PATH, ensure_user_config
+    path = ensure_user_config()
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    data.setdefault("fusion", {})
+    data["fusion"]["judge"] = judge.model_dump()
+    data["fusion"]["panel"] = [c.model_dump() for c in panel]
+    path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+    return str(USER_CONFIG_PATH)
 
 
 def main(argv: list[str] | None = None) -> int:
-    args = argv if argv is not None else sys.argv[1:]
-    if not args:
-        print("usage: python -m core.fusion.cli \"question\"", file=sys.stderr)
+    args = list(argv if argv is not None else sys.argv[1:])
+    save = "--save" in args
+    show = "--show" in args
+    args = [a for a in args if a not in ("--save", "--show")]
+
+    config, _ = load_config()
+    panel, judge = default_panel(config)
+
+    if show:
+        print(f"\n  Fusion panel — {describe_panel(panel, judge)}")
+        if not config.fusion.panel:
+            print("  (default built from the machine; run --save to persist)")
+        print()
+        return 0
+
+    if len(panel) < 2:
+        print("  ✗ No panel available — configure fusion.panel in "
+              "models.yaml (try /arka-fusion) or start Ollama with 2+ "
+              "models for a local panel.", file=sys.stderr)
         return 1
-    prompt = " ".join(args)
+
+    if save:
+        where = _save_panel(panel, judge)
+        print(f"  ✓ Fusion panel saved to {where}")
+        config, _ = load_config()  # reload so fuse() uses the saved panel
+
+    prompt = " ".join(args).strip()
+    if not prompt:
+        print("usage: python -m core.fusion.cli [--save] \"question\"",
+              file=sys.stderr)
+        return 1
+
+    # Build an effective config carrying the (possibly default) panel.
+    config.fusion.panel = panel
+    config.fusion.judge = judge
     try:
-        result = fuse(prompt)
+        result = fuse(prompt, config=config)
     except FusionUnavailable as exc:
         print(f"  ✗ {exc}", file=sys.stderr)
         return 1

package/core/fusion/panel_builder.py

@@ -0,0 +1,58 @@
+"""Build a fusion panel from what the machine can actually run.
+
+Fusion needs a diverse panel + a judge. The user's ``models.yaml`` may
+have an explicit ``fusion.panel`` (configured via ``/arka-fusion``); when
+it is empty, this builds a sensible default from discovered models so
+``npx arkaos fusion "question"`` does something out of the box instead of
+failing with FusionUnavailable.
+
+Diversity is the point (OpenRouter's result: a diverse panel beats a
+single model): pair the runtime model with up to two large, distinct
+local Ollama models. The judge stays the configured frontier model.
+"""
+
+from __future__ import annotations
+
+from core.runtime.model_router import ModelsConfig, RoleChoice, load_config
+
+
+def default_panel(
+    config: ModelsConfig | None = None,
+) -> tuple[list[RoleChoice], RoleChoice]:
+    """Return (panel, judge). Respects an explicit panel; else builds one.
+
+    An empty return panel means the machine offers nothing to fuse (no
+    local models and no explicit config) — the caller reports that rather
+    than fanning out to a single seat.
+    """
+    if config is None:
+        config, _ = load_config()
+    judge = config.fusion.judge
+    if config.fusion.panel:
+        return list(config.fusion.panel), judge
+
+    panel: list[RoleChoice] = [
+        RoleChoice(provider="runtime", model="default", effort="high"),
+    ]
+    try:
+        from core.runtime.ollama_discovery import discover
+        status = discover()
+    except Exception:
+        status = None
+    if status and status.running:
+        # Panel-grade locals: >= 4GB, or cloud-proxied (size 0). Sort by
+        # size desc so the strongest come first; take two distinct ones.
+        candidates = sorted(
+            (m for m in status.models if m.size_gb >= 4 or m.size_gb == 0),
+            key=lambda m: m.size_gb,
+            reverse=True,
+        )
+        for m in candidates[:2]:
+            panel.append(RoleChoice(provider="ollama", model=m.name, effort="high"))
+    return panel, judge
+
+
+def describe_panel(panel: list[RoleChoice], judge: RoleChoice) -> str:
+    """Human summary of a panel for CLI output."""
+    seats = ", ".join(f"{c.provider}/{c.model}" for c in panel)
+    return f"judge {judge.provider}/{judge.model} | panel: {seats}"

package/core/hooks/post_tool_use.py

@@ -111,19 +111,29 @@ def _unlocked(fh) -> None:
 # ─── Section 1: flow marker cache ────────────────────────────────────────
 
 
-def _write_flow_marker(session_id: str, assistant_msg: str) -> None:
-    if not session_id or not assistant_msg:
+def _confirm_flow_authorization(session_id: str, transcript_path: str) -> None:
+    """Confirm persistent flow authorization from the transcript.
+
+    Replaces the dead ``_write_flow_marker`` that read a non-existent
+    ``assistant_message`` payload field. Reads the same transcript the
+    enforcer trusts and, when a flow marker is present, writes a confirmed
+    authorization that survives compaction and the 20-message window.
+    """
+    if not session_id:
         return
-    routing = _ROUTING_RE.search(assistant_msg)
-    if routing:
-        kind, dept, lead = "routing", routing.group(1), routing.group(2)
-    elif _TRIVIAL_RE.search(assistant_msg):
-        kind, dept, lead = "trivial", "", ""
-    else:
+    try:
+        from core.workflow.flow_authorization import confirm
+        from core.workflow.flow_enforcer import (
+            _load_last_assistant_messages,
+            _scan_markers,
+        )
+    except Exception:
         return
     try:
-        from core.workflow.marker_cache import write_marker
-        write_marker(session_id, kind, dept, lead)
+        messages = _load_last_assistant_messages(transcript_path, 20)
+        marker_found, _ = _scan_markers(messages)
+        if marker_found is not None:
+            confirm(session_id, marker_found)
     except Exception:
         pass
 
@@ -614,9 +624,13 @@ def main(stdin_json: dict | None = None) -> int:
     exit_code = get_str(stdin_json, "exit_code") or "0"
     cwd = get_str(stdin_json, "cwd")
     session_id = get_str(stdin_json, "session_id")
-    assistant_msg = get_str(stdin_json, "assistant_message")
+    transcript_path = get_str(stdin_json, "transcript_path")
 
-    _write_flow_marker(session_id, assistant_msg)
+    # Claude Code sends no `assistant_message` field (confirmed against the
+    # hook docs, 2026-07-05) — the old read was dead and the marker cache
+    # was never written. Scan the transcript (the only source hooks have)
+    # and confirm persistent authorization when a marker is present.
+    _confirm_flow_authorization(session_id, transcript_path)
 
     if tool_name in ("Task", "Agent"):
         subagent_type = get_str(stdin_json, "tool_input", "subagent_type")

package/core/hooks/pre_tool_use.py

@@ -260,6 +260,10 @@ def _flow_gate(
     except Exception:
         pass
     if decision.allow:
+        # Grace path: allow, but surface the non-blocking warning so the
+        # operator sees the routing nudge instead of a silent pass.
+        if decision.warning:
+            print(decision.warning, file=sys.stderr)
         return 0
     return _deny(decision.to_stderr_message())
 

package/core/hooks/user_prompt_submit.py

@@ -171,6 +171,13 @@ def _invalidate_turn_caches(session_id: str) -> None:
         invalidate_marker(session_id)
     except Exception:
         pass
+    try:
+        # Reset only the per-turn grace flag; confirmed authorization and
+        # the grace counter persist across turns (enforcer resilience).
+        from core.workflow.flow_authorization import reset_turn
+        reset_turn(session_id)
+    except Exception:
+        pass
     try:
         from core.synapse.kb_cache import invalidate_obsidian_query
         invalidate_obsidian_query(session_id)

package/core/runtime/model_router.py

@@ -33,6 +33,23 @@ USER_CONFIG_PATH = Path.home() / ".arkaos" / "models.yaml"
 QUALITY_ROLES = frozenset({
     "design", "review", "architecture", "strategy", "quality_gate",
 })
+
+# Plain-language explanation of each role, surfaced in the dashboard and
+# `npx arkaos models` so the operator knows what "execution" etc. drive.
+ROLE_DESCRIPTIONS: dict[str, str] = {
+    "design": "UI/UX and visual design — layout, typography, aesthetics.",
+    "review": "Code review, Quality Gate reviewers, adversarial verification.",
+    "architecture": "System design, API contracts, ADRs, technical decisions.",
+    "strategy": "Business and product strategy, market analysis, planning.",
+    "quality_gate": "The mandatory Quality Gate (Marta, Eduardo, Francisca).",
+    "execution": "Implementation — specialists writing code and running build tasks.",
+    "mechanical": "Rote work — commit messages, changelog, formatting, data fetch.",
+}
+
+
+def role_description(role: str) -> str:
+    """Human-readable description of a role, or empty if unknown."""
+    return ROLE_DESCRIPTIONS.get(role, "")
 KNOWN_EFFORTS = ("low", "medium", "high", "max")
 
 _ALIAS_NAMES = frozenset({"best", "default", "fast"})

package/core/runtime/model_routing_context.py

@@ -0,0 +1,82 @@
+"""Model Fabric → orchestrator bridge (the consumption layer).
+
+The dashboard and ``npx arkaos models`` write ``~/.arkaos/models.yaml``.
+Until now nothing fed that config back to the Claude Code orchestrator,
+so changing a role's model changed nothing at dispatch time. This module
+turns the config into a compact directive the SessionStart hook injects,
+so the orchestrator resolves an agent's model from the user's config
+instead of only the agent YAML default.
+
+It is context injection — the same control surface ArkaOS uses for the
+constitution, routing, and evidence flow — not a hard rewrite of the Task
+`model` param (Claude Code exposes no hook for that). The PostToolUse
+telemetry already records the model actually requested per dispatch, so
+mismatches are observable (see model_routing_check).
+"""
+
+from __future__ import annotations
+
+# Which Model Fabric role governs each kind of agent work. Agents are a
+# different taxonomy from roles, so we map by what the agent DOES. The
+# orchestrator uses this to pick the role, then resolves the model.
+AGENT_ROLE_HINTS: dict[str, str] = {
+    # quality-critical
+    "architect": "architecture",
+    "cto": "architecture",
+    "strategist": "strategy",
+    "brand-strategist": "strategy",
+    "creative-director": "design",
+    "visual-designer": "design",
+    "frontend-dev": "design",
+    "marta-cqo": "quality_gate",
+    "eduardo-copy": "quality_gate",
+    "francisca-tech": "quality_gate",
+    "code-reviewer": "review",
+    "security": "review",
+    "qa": "review",
+    # execution
+    "senior-dev": "execution",
+    "paulo-tech-lead": "execution",
+    "devops": "execution",
+    # mechanical
+    "analyst": "mechanical",
+}
+
+
+def routing_summary() -> str:
+    """One-line role→provider/model@effort summary, or '' if unavailable."""
+    try:
+        from core.runtime.model_router import resolve_all
+        items = resolve_all()
+    except Exception:
+        return ""
+    parts = [
+        f"{i.role}={i.provider}/{i.model or '?'}@{i.effort}" for i in items
+    ]
+    return " ".join(parts)
+
+
+def routing_directive() -> str:
+    """Full SessionStart block: the config plus how to honor it.
+
+    Returns '' when the config cannot be read, so the hook can skip the
+    block entirely rather than inject an empty directive.
+    """
+    summary = routing_summary()
+    if not summary:
+        return ""
+    # No backticks: this string is embedded in session-start.sh which
+    # passes it through $(echo -e "$MSG") — backticks would trigger shell
+    # command substitution. Use plain quotes.
+    return (
+        "[ARKA:MODEL-FABRIC] The operator's model routing (from "
+        "~/.arkaos/models.yaml — dashboard / npx arkaos models):\n"
+        f"  {summary}\n"
+        "When dispatching a subagent via the Task tool, set its model "
+        "param from this table by the KIND of work it does (design, "
+        "review, architecture, strategy, quality_gate, execution, "
+        "mechanical) — this is the user's explicit choice and OVERRIDES "
+        "the agent YAML default. Quality roles never downgrade below the "
+        "configured model (excellence-mandate). Genuinely mechanical "
+        "dispatches (commit messages, formatting) use the mechanical role."
+    )

package/core/runtime/runtime_models.py

@@ -0,0 +1,51 @@
+"""Known models per runtime, for the Model Fabric UI + advisor.
+
+The Model Fabric ``runtime`` provider shells out to the active CLI. This
+module lists the concrete models that CLI accepts, with human labels and
+tier, so the dashboard dropdown and ``/arka-fusion`` can offer real
+choices (Fable 5, Opus, Sonnet, Haiku) instead of only the abstract
+best/default/fast aliases.
+
+Model IDs verified against the Claude API reference (2026-07). This is
+the single place they are hand-listed — update HERE when the runtime
+ships new models; the dashboard and CLI read from this module. Codex /
+Gemini / Cursor models are left empty on purpose: we do not hardcode
+another vendor's catalogue, and the UI falls back to a free-text field
+so the user types the exact id their runtime accepts.
+"""
+
+from __future__ import annotations
+
+
+# Claude Code accepts the short aliases opus/sonnet/haiku and full model
+# IDs. `value` is what gets written to models.yaml as the role's model.
+CLAUDE_CODE_MODELS: list[dict[str, str]] = [
+    {"value": "claude-fable-5", "label": "Fable 5", "tier": "frontier",
+     "note": "most capable"},
+    {"value": "opus", "label": "Opus 4.8", "tier": "frontier",
+     "note": "frontier"},
+    {"value": "sonnet", "label": "Sonnet 5", "tier": "balanced",
+     "note": "balanced speed/quality"},
+    {"value": "haiku", "label": "Haiku 4.5", "tier": "fast",
+     "note": "fast + cheap"},
+]
+
+_MODELS_BY_RUNTIME: dict[str, list[dict[str, str]]] = {
+    "claude-code": CLAUDE_CODE_MODELS,
+    # codex / gemini / cursor intentionally omitted — free-text in the UI.
+}
+
+
+def models_for_runtime(runtime_id: str) -> list[dict[str, str]]:
+    """Return the known runtime models for the given runtime id."""
+    return _MODELS_BY_RUNTIME.get(runtime_id, [])
+
+
+def detect_runtime_models() -> tuple[str, list[dict[str, str]]]:
+    """Best-effort (runtime_id, models) for the active runtime."""
+    try:
+        from core.runtime.registry import detect_runtime
+        runtime_id = detect_runtime()
+    except Exception:
+        runtime_id = "claude-code"
+    return runtime_id, models_for_runtime(runtime_id)