arkaos 4.3.0 → 4.3.1

package/VERSION

@@ -1 +1 @@
-4.3.0
+4.3.1

package/arka/skills/fusion/SKILL.md

@@ -75,11 +75,18 @@ Produce a table: role → provider/model + ONE-line rationale each. Rules:
 
 ```bash
 npx arkaos models set <role> <provider>/<model> --effort <effort>
+npx arkaos fusion --save "<a first question>"   # persist a panel + run it
 ```
 
-For fusion panel/judge and aliases, edit `~/.arkaos/models.yaml` directly
-(keep comments). Show the final `npx arkaos models` table as proof and
-remind: the dashboard Models page shows the same state + live usage.
+`npx arkaos fusion --show` prints the panel that would run (a sensible
+default is built from the machine's models when none is configured);
+`npx arkaos fusion --save "question"` writes the panel into
+`~/.arkaos/models.yaml` and runs it; `npx arkaos fusion "question"` runs
+without persisting. For fine-grained panel/judge edits, edit
+`~/.arkaos/models.yaml` directly (keep comments). Show the final
+`npx arkaos models` table as proof and remind: the dashboard Models page
+shows the same state + live usage, and the SessionStart hook now injects
+the routing so it governs agent dispatch.
 
 ## Hard rules
 

package/config/hooks/session-start.sh

@@ -105,6 +105,29 @@ MSG+="\\nFields: kb=N (Obsidian/KB notes consulted), research=X (MCPs invoked: p
 MSG+="\\nMandatory after: EFFECT tool calls, plan/recommendation outputs, QG verdicts. Optional for pure read-only status replies."
 MSG+="\\nAbsence is measured by the Stop hook (warn-only in v2.34.0) before promotion to hard enforcement."
 
+# ─── Model Fabric routing (consumption layer) ───────────────────────────
+# Feed the operator's ~/.arkaos/models.yaml back to the orchestrator so
+# dashboard/CLI model choices actually govern agent dispatch. Cheap
+# (single python read); skipped silently if the config can't be resolved.
+if [ -n "$REPO" ]; then
+  # Prefer the ArkaOS venv python (has pydantic + yaml); the ambient
+  # python3 usually lacks them and routing_directive() would return "".
+  _MF_PY="python3"
+  [ -x "$HOME/.arkaos/venv/bin/python3" ] && _MF_PY="$HOME/.arkaos/venv/bin/python3"
+  if command -v "$_MF_PY" &>/dev/null || [ -x "$_MF_PY" ]; then
+    _MF_DIRECTIVE=$(cd "$REPO" && PYTHONPATH="$REPO" "$_MF_PY" -c "
+try:
+    from core.runtime.model_routing_context import routing_directive
+    print(routing_directive())
+except Exception:
+    pass
+" 2>/dev/null)
+    if [ -n "$_MF_DIRECTIVE" ]; then
+      MSG+="\\n\\n${_MF_DIRECTIVE}"
+    fi
+  fi
+fi
+
 # ─── Stale-aware reorganizer trigger (PR24 v2.46.0) ─────────────────────
 # If today's proposal file is missing, fire the reorganizer in the
 # background with a 30s timeout. Best-effort, never blocks session

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)

package/core/workflow/flow_authorization.py

@@ -0,0 +1,181 @@
+"""Persistent per-session flow authorization — enforcer resilience.
+
+Claude Code exposes NO hook access to the current assistant message
+(confirmed against the hook docs, 2026-07-05: neither PreToolUse nor
+PostToolUse carries the message text, and the transcript at
+``transcript_path`` does not yet include the in-progress turn). So the
+current turn's ``[arka:routing]`` marker is structurally invisible to
+that turn's own tool calls, and the old PostToolUse marker cache read a
+non-existent ``assistant_message`` field — it was never written, leaving
+the enforcer with only a 20-message transcript window that a long
+session or a context compaction empties (652 false-positive blocks
+observed in one session).
+
+This module rebuilds resilience on what hooks CAN see: markers observed
+in the transcript (past turns) plus persistent ``/tmp`` state that
+survives compaction and window-rolling.
+
+Two tiers:
+
+- **CONFIRMED** — written whenever a flow marker is actually observed in
+  the transcript. Valid for a session TTL, survives compaction. Grants
+  a silent allow. This is the normal steady state: route once, then
+  every subsequent turn is authorised.
+- **TURN GRACE** — the current turn's marker cannot be seen, so the very
+  first turn of a session (before any marker reaches the transcript) has
+  no confirmed auth. Rather than a false-positive block, the turn is
+  allowed WITH A WARNING and a per-turn grace flag so the rest of the
+  turn proceeds. A never-routing session is warned every turn and, after
+  ``GRACE_CAP`` consecutive graced turns with no confirmation, escalates
+  to a hard block — a normally-routing session confirms by turn 2 and
+  never reaches the cap.
+
+State dir: ``/tmp/arkaos-flow-auth`` (override via ``ARKA_FLOW_AUTH_DIR``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from core.shared import safe_session_id as _safe_session_id_module
+
+_safe_session_id = _safe_session_id_module.safe_session_id
+
+# A working session; after this a stale /tmp record expires on its own.
+DEFAULT_TTL_SECONDS = 12 * 60 * 60
+# Consecutive graced turns with no confirmation before a hard block.
+GRACE_CAP = 3
+
+VALID_MARKER_TYPES: frozenset[str] = frozenset(
+    {"routing", "trivial", "gate", "phase"}
+)
+
+
+@dataclass(frozen=True)
+class GraceState:
+    count: int
+    escalate: bool
+
+
+def _base_dir() -> Path:
+    override = os.environ.get("ARKA_FLOW_AUTH_DIR", "").strip()
+    return Path(override) if override else Path("/tmp/arkaos-flow-auth")
+
+
+def _auth_path(session_id: str) -> Path | None:
+    safe = _safe_session_id(session_id)
+    return (_base_dir() / f"{safe}.json") if safe else None
+
+
+def _read(path: Path | None) -> dict:
+    if path is None or not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _write(path: Path | None, data: dict) -> None:
+    if path is None:
+        return
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data), encoding="utf-8")
+    except OSError:
+        pass  # authorization state must never block the hook
+
+
+def confirm(session_id: str, marker_type: str) -> None:
+    """Persist a confirmed authorization (a marker was observed)."""
+    if marker_type not in VALID_MARKER_TYPES:
+        return
+    path = _auth_path(session_id)
+    if path is None:
+        return
+    _write(path, {
+        "marker_type": marker_type,
+        "confirmed_ts": time.time(),
+        "grace_count": 0,  # confirmation clears accumulated grace
+        "turn_grace": False,
+    })
+
+
+def confirmed_record(
+    session_id: str, ttl_seconds: int = DEFAULT_TTL_SECONDS
+) -> dict | None:
+    """Return the confirmed record if present and within TTL, else None."""
+    data = _read(_auth_path(session_id))
+    ts = data.get("confirmed_ts")
+    if ts is None:
+        return None
+    if time.time() - float(ts) > ttl_seconds:
+        return None
+    return data
+
+
+def is_confirmed(
+    session_id: str, ttl_seconds: int = DEFAULT_TTL_SECONDS
+) -> bool:
+    return confirmed_record(session_id, ttl_seconds) is not None
+
+
+def grant_turn_grace(session_id: str) -> None:
+    """Flag the current turn as graced so its remaining tools pass."""
+    path = _auth_path(session_id)
+    if path is None:
+        return
+    data = _read(path)
+    data["turn_grace"] = True
+    _write(path, data)
+
+
+def has_turn_grace(session_id: str) -> bool:
+    return bool(_read(_auth_path(session_id)).get("turn_grace"))
+
+
+def reset_turn(session_id: str) -> None:
+    """Clear the per-turn grace flag (called at each new user prompt).
+
+    Confirmed authorization and the grace counter are preserved — only
+    the within-turn flag resets, so the next turn re-evaluates.
+    """
+    path = _auth_path(session_id)
+    if path is None:
+        return
+    data = _read(path)
+    if data.get("turn_grace"):
+        data["turn_grace"] = False
+        _write(path, data)
+
+
+def grace_count(session_id: str) -> int:
+    return int(_read(_auth_path(session_id)).get("grace_count", 0) or 0)
+
+
+def register_grace(session_id: str) -> GraceState:
+    """Increment the consecutive-grace counter; escalate past the cap."""
+    path = _auth_path(session_id)
+    if path is None:
+        return GraceState(count=0, escalate=False)
+    data = _read(path)
+    count = int(data.get("grace_count", 0) or 0) + 1
+    data["grace_count"] = count
+    _write(path, data)
+    return GraceState(count=count, escalate=count > GRACE_CAP)
+
+
+def clear(session_id: str) -> None:
+    """Remove all authorization state for a session (tests / session end)."""
+    path = _auth_path(session_id)
+    if path is None:
+        return
+    try:
+        path.unlink()
+    except (FileNotFoundError, OSError):
+        pass

package/core/workflow/flow_enforcer.py

@@ -25,7 +25,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from core.shared import safe_session_id as _safe_session_id_module
-from core.workflow import marker_cache
+from core.workflow import flow_authorization, marker_cache
 
 try:
     import fcntl  # POSIX only
@@ -222,15 +222,24 @@ class Decision:
     marker_found: str | None = None
     phase_observed: str | None = None
     bypass_used: bool = False
+    warning: str = ""
 
     def to_stderr_message(self) -> str:
         if self.allow:
-            return ""
+            return self.warning
+        # Recovery that actually works, given Claude Code exposes no
+        # current-message text to hooks (the inline `ARKA_BYPASS_FLOW=1`
+        # never reached this separate hook process — a documented trap).
         return (
-            f"[ARKA:ENFORCEMENT] Missing `[arka:routing] <dept> -> <lead>` or "
-            f"`[arka:trivial] <reason>` before "
-            f"Write/Edit/MultiEdit/NotebookEdit/Task/Skill/Bash-effect. "
-            f"Bypass once with `ARKA_BYPASS_FLOW=1`. Reason: {self.reason}."
+            f"[ARKA:ENFORCEMENT] No routing marker for "
+            f"{flow_authorization.GRACE_CAP}+ turns. Emit "
+            f"`[arka:routing] <dept> -> <lead>` (or `[arka:trivial] "
+            f"<reason>`) at the START of your reply — it authorises this "
+            f"turn and every turn after. To turn enforcement off set "
+            f"hooks.hardEnforcement=false in ~/.arkaos/config.json; to "
+            f"bypass programmatically export ARKA_BYPASS_FLOW=1 in Claude "
+            f"Code's own environment (settings.json env), not inline on a "
+            f"command. Reason: {self.reason}."
         )
 
 
@@ -414,18 +423,54 @@ def evaluate(
         )
     marker_found, phase_observed = _scan_markers(messages)
 
-    if marker_found is None:
+    if marker_found is not None:
+        # Persist a confirmed authorization so this survives compaction and
+        # the 20-message window rolling — the fix for the 652 false blocks.
+        flow_authorization.confirm(session_id, marker_found)
         return Decision(
-            allow=False,
-            reason=f"no-flow-marker-in-last-{ASSISTANT_WINDOW}-assistant-messages",
+            allow=True,
+            reason=f"marker-found:{marker_found}",
+            marker_found=marker_found,
             phase_observed=phase_observed,
         )
 
+    # No marker in the transcript window. The current turn's marker is
+    # structurally invisible to hooks, so fall back to persistent auth
+    # before ever blocking.
+    if flow_authorization.is_confirmed(session_id):
+        return Decision(
+            allow=True, reason="session-authorized", phase_observed=phase_observed
+        )
+
+    # Same turn, already graced: let the rest of the turn's tools through.
+    if flow_authorization.has_turn_grace(session_id):
+        return Decision(
+            allow=True, reason="turn-grace", phase_observed=phase_observed
+        )
+
+    # First effect-tool of a turn with no confirmed auth. A hard deny here
+    # is a false positive (the assistant may have routed in this very
+    # message — invisible to us). Grace it with a warning; escalate to a
+    # real block only after GRACE_CAP consecutive graced turns without any
+    # confirmation (a normally-routing session confirms by turn 2).
+    grace = flow_authorization.register_grace(session_id)
+    if grace.escalate:
+        return Decision(
+            allow=False,
+            reason=f"no-marker-and-grace-exhausted-after-{grace.count}-turns",
+            phase_observed=phase_observed,
+        )
+    flow_authorization.grant_turn_grace(session_id)
     return Decision(
         allow=True,
-        reason=f"marker-found:{marker_found}",
-        marker_found=marker_found,
+        reason=f"first-tool-grace:{grace.count}",
         phase_observed=phase_observed,
+        warning=(
+            f"[arka:suggest] Effect tool allowed without an observable "
+            f"routing marker (grace {grace.count}/{flow_authorization.GRACE_CAP}). "
+            f"Emit `[arka:routing] <dept> -> <lead>` at the start of your "
+            f"reply to authorise this session."
+        ),
     )
 
 

package/dashboard/app/pages/models.vue

@@ -8,6 +8,14 @@ interface ResolvedRole {
   model: string
   effort: string
   source: string
+  description?: string
+}
+
+interface RuntimeModel {
+  value: string
+  label: string
+  tier: string
+  note: string
 }
 
 interface OllamaModel {
@@ -24,6 +32,7 @@ interface ModelsOverview {
   providers: Record<string, { type: string }>
   aliases: Record<string, Record<string, string>>
   fusion: { judge: Record<string, string>, panel: Array<Record<string, string>> }
+  runtime: { id: string, models: RuntimeModel[] }
   ollama: { installed: boolean, running: boolean, host: string, models: OllamaModel[] }
   keys: { openrouter: boolean, anthropic: boolean }
 }
@@ -119,8 +128,13 @@ const targetOptions = computed(() => {
   const o = overview.value
   if (!o) return []
   const options: { label: string, value: string }[] = []
+  // Concrete runtime models first (Fable 5, Opus, Sonnet, Haiku) so the
+  // operator picks a real model, not just an abstract alias.
+  for (const m of o.runtime?.models ?? []) {
+    options.push({ label: `runtime / ${m.label} · ${m.note}`, value: `runtime/${m.value}` })
+  }
   for (const alias of ['best', 'default', 'fast']) {
-    options.push({ label: `runtime / ${alias}`, value: `runtime/${alias}` })
+    options.push({ label: `runtime / ${alias} (alias)`, value: `runtime/${alias}` })
   }
   for (const m of o.ollama?.models ?? []) {
     options.push({ label: `ollama / ${m.name}`, value: `ollama/${m.name}` })
@@ -148,7 +162,7 @@ async function saveEdit(role: string) {
   }
   saving.value = true
   try {
-    await $fetch(`${apiBase.value}/api/models/role`, {
+    await $fetch(`${apiBase}/api/models/role`, {
       method: 'POST',
       body: { role, target: editTarget.value },
     })
@@ -269,10 +283,15 @@ function formatCost(value: number | null): string {
               >
                 <UIcon
                   :name="QUALITY_ROLES.has(row.role) ? 'i-lucide-gem' : 'i-lucide-cog'"
-                  class="size-4 shrink-0"
+                  class="size-4 shrink-0 mt-0.5 self-start"
                   :class="QUALITY_ROLES.has(row.role) ? 'text-primary' : 'text-muted'"
                 />
-                <span class="w-32 shrink-0 text-sm font-medium">{{ row.role }}</span>
+                <div class="w-56 shrink-0">
+                  <p class="text-sm font-medium">{{ row.role }}</p>
+                  <p v-if="row.description" class="text-xs text-muted leading-snug">
+                    {{ row.description }}
+                  </p>
+                </div>
                 <template v-if="editingRole === row.role">
                   <UInputMenu
                     v-model="editTarget"

package/installer/cli.js

@@ -28,6 +28,9 @@ const { values, positionals } = parseArgs({
     // Model Fabric PR-A — `npx arkaos models [--json] [set ... --effort max]`
     json: { type: "boolean" },
     effort: { type: "string" },
+    // Fusion — `npx arkaos fusion [--save|--show] "question"`
+    save: { type: "boolean" },
+    show: { type: "boolean" },
   },
   allowPositionals: true,
   strict: false,
@@ -177,6 +180,24 @@ async function main() {
       break;
     }
 
+    case "fusion": {
+      const { execSync } = await import("node:child_process");
+      const repoRootFusion = join(__dirname, "..");
+      const pyFusion = getArkaosPython();
+      if (!pyFusion) { console.error("No Python found. Run: npx arkaos install"); process.exit(1); }
+      const fusionArgs = positionals.slice(1).map((a) => `"${a}"`).join(" ");
+      const saveFlag = values.save ? " --save" : "";
+      const showFlag = values.show ? " --show" : "";
+      try {
+        execSync(`"${pyFusion}" -m core.fusion.cli${saveFlag}${showFlag} ${fusionArgs}`, {
+          stdio: "inherit",
+          cwd: repoRootFusion,
+          env: { ...process.env, ARKAOS_ROOT: repoRootFusion, PYTHONPATH: repoRootFusion },
+        });
+      } catch { process.exit(1); }
+      break;
+    }
+
     case "index": {
       const { execSync } = await import("node:child_process");
       const indexArgs = positionals.slice(1).join(" ");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "4.3.0"
+version = "4.3.1"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/dashboard-api.py

@@ -867,8 +867,14 @@ def commands(dept: Optional[str] = Query(None), q: Optional[str] = Query(None)):
 @app.get("/api/models")
 def models_overview():
     """Model Fabric: roles, providers, Ollama discovery, key presence."""
-    from core.runtime.model_router import USER_CONFIG_PATH, load_config, resolve_all
+    from core.runtime.model_router import (
+        USER_CONFIG_PATH,
+        load_config,
+        resolve_all,
+        role_description,
+    )
     from core.runtime.ollama_discovery import discover
+    from core.runtime.runtime_models import detect_runtime_models
 
     config, source = load_config()
     keys_path = Path.home() / ".arkaos" / "keys.json"
@@ -876,16 +882,21 @@ def models_overview():
         keys = json.loads(keys_path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):
         keys = {}
+    runtime_id, runtime_models = detect_runtime_models()
     return {
         "source": source,
         "config_path": str(USER_CONFIG_PATH),
-        "roles": [item.model_dump() for item in resolve_all()],
+        "roles": [
+            {**item.model_dump(), "description": role_description(item.role)}
+            for item in resolve_all()
+        ],
         "providers": {
             name: {"type": spec.get("type", "")}
             for name, spec in config.providers.items()
         },
         "aliases": config.aliases,
         "fusion": config.fusion.model_dump(),
+        "runtime": {"id": runtime_id, "models": runtime_models},
         "ollama": discover().to_dict(),
         "keys": {
             "openrouter": bool(