arkaos 4.1.1 → 4.2.0

package/VERSION

@@ -1 +1 @@
-4.1.1
+4.2.0

package/arka/skills/flow/SKILL.md

@@ -87,6 +87,21 @@ resumes at the right gate.
   coverage read from the report file, security grep, spell-check for
   copy. Reviewers (Quality Gate personas) interpret tool output; they do
   not replace it. APPROVED/REJECTED derives from evidence.
+- **Excellence check (`excellence-mandate`, mandatory):** before closing,
+  answer three questions with evidence, not narration:
+  1. What is **unfinished** in this delivery (trimmed scope, TODO left
+     behind, parity skipped)?
+  2. What is **default** (template look, boilerplate copy, unstyled
+     component, generic strategy)?
+  3. What would a **top-tier lead reject** here? Name the benchmark
+     (`reference_companies.application` — e.g. Linear/Stripe for
+     frontend) and judge against it.
+  A non-empty answer loops the work back into Gate 3 or is escalated to
+  the operator as an explicit open-items decision. Shipping with a
+  non-empty list and no operator decision is a constitution breach.
+  Time and token cost are not acceptable answers to any of the three.
+- Quality Gate REJECTED loops back at most twice; a third REJECTED
+  escalates to the operator with the full verdict.
 - Close with an honest summary: what changed, where, how it was
   verified (real commands + results), what remains open.
 

package/config/constitution.yaml

@@ -117,14 +117,18 @@ enforcement_levels:
         rule: "When a squad lead dispatches a specialist via the Agent tool, the lead MUST emit `[arka:dispatch] <from> -> <to>` on a line of its own immediately before the dispatch call. The marker identifies the specialist to the PreToolUse specialist-enforcer so writes from the specialist pass `owner-match` instead of falling through as `no-routing-tag` or blocking the lead. The format is identical to `[arka:routing]` but uses the verb `dispatch` and points from the calling persona to the receiving specialist (e.g., `[arka:dispatch] paulo -> frontend-dev`)."
         enforcement: "PreToolUse hook (config/hooks/pre-tool-use.sh) reads the dispatch marker via core.workflow.specialist_enforcer._resolve_persona. Dispatch tag overrides routing tag because it is more specific. Without it, lead writes to specialist-owned files are blocked when hooks.specialistEnforcement=true. See ADR docs/adr/2026-05-28-specialist-dispatch-subagent-blindspot.md for the architectural constraint this rule mitigates."
 
+      # ─── Rule added in Excellence Reform (2026-07-05, operator mandate) ──
+      - id: excellence-mandate
+        rule: "Every deliverable targets excellence, not acceptance. Supervisors (leads, C-Suite, Quality Gate) and specialists are REQUIRED to be maximally critical and meticulous: no default-looking output, no unfinished edges, no lazy implementations, no delivery-for-the-sake-of-delivering. Latency and token cost are NEVER arguments against quality work — the CostGovernor hard budget is the only ceiling. Before any gate closes, the closing agent answers with evidence: 'what is unfinished, what is default, what would a top-tier lead (see reference_companies.application) reject here?' — a non-empty answer loops the work back or escalates to the operator; it is never silently shipped. UI work MUST load the frontend design skills (frontend-design, ui-ux-pro-max, project design system) at maximum effort and pass visual review against a named benchmark before reaching the Quality Gate."
+        enforcement: "G4 excellence check in arka/skills/flow/SKILL.md; frontend gate core/workflow/frontend_gate.py (flag hooks.frontendGate); QG reviewers must cite the named benchmark and enumerate concrete rejections; REJECTED redo loop capped at 2 cycles then operator escalation. Operator mandate 2026-07-05: 'não interessa se demora — o goal é excelência'."
+
   quality_gate:
     description: "Mandatory pre-delivery review. Nothing ships without APPROVED verdict."
     trigger: "After the last execution phase, before delivery to user"
     frequency: "Once per workflow execution, not per phase"
     model_policy:
-      default: sonnet
-      opus_scope: "Tier 0 diffs only: constitution, security-relevant changes, release pipeline, installer auth — or deliverables explicitly security-flagged"
-      note: "Marta's veto is model-independent: the verdict derives from the evidence report (core.governance.evidence_checks), not from model size."
+      default: best-available
+      note: "Quality Gate reviews run the best model available (frontier tier) at maximum effort by default — the Excellence Reform (2026-07-05) inverted the former sonnet-default cost posture; review quality is never the place to save tokens. User overrides per role live in ~/.arkaos/models.yaml (Model Fabric). Marta's veto is model-independent: the verdict derives from the evidence report (core.governance.evidence_checks), not from model size."
     agents:
       orchestrator:
         id: cqo-marta
@@ -140,9 +144,10 @@ enforcement_levels:
     process:
       - "Evidence engine runs first: python -m core.governance.evidence_checks — the verdict derives from its report"
       - "Marta receives all output from execution phase plus the evidence report"
-      - "Marta dispatches Eduardo (text) and Francisca (technical) in parallel to interpret the report"
-      - "Each reviewer returns a structured QGVerdict (APPROVED or REJECTED) with specific issues; evidence overall=fail forces REJECTED"
+      - "Marta dispatches Eduardo (text) and Francisca (technical) in parallel, each in an INDEPENDENT subagent context (clean context, no stake in the work being approved)"
+      - "Each reviewer returns a structured QGVerdict (APPROVED or REJECTED) with specific issues; the verdict MUST name the benchmark used (reference_companies.application) and enumerate the concrete rejections a top-tier lead would raise; evidence overall=fail forces REJECTED"
       - "If ANY reviewer rejects: work loops back to execution with issue list"
+      - "Redo loop is capped at 2 cycles: a third REJECTED escalates to the operator with the full verdict instead of another silent retry (excellence-mandate)"
       - "If ALL approve: Marta issues final APPROVED verdict"
       - "Nothing reaches the user without APPROVED from all three"
 
@@ -182,11 +187,11 @@ enforcement_levels:
         enforcement: "persistence.py exports on status change; audit detects missing exports"
 
       - id: model-routing
-        rule: "Per-tier model assignment enforced: Tier 0 opus, Tier 1/2 sonnet, mechanical haiku. Quality Gate reviewers run sonnet by default; opus ONLY for Tier 0/security-scope diffs (constitution, security, release pipeline, installer auth). Marta keeps her veto regardless of model tier."
+        rule: "Quality-first model routing: design, review, architecture, strategy, and Quality Gate phases run the BEST model available for the task (frontier tier) at maximum effort BY DEFAULT. Cheaper/smaller models (haiku, local) are reserved for genuinely mechanical work: commit messages, keyword extraction, data fetching, formatting. Cost optimisation NEVER downgrades a quality-critical phase — the CostGovernor hard budget is the only ceiling. User-owned overrides live in ~/.arkaos/models.yaml (Model Fabric): the user decides which provider/model serves each role; this rule sets the default posture, not a fixed vendor table. Replaced the cost-optimised per-tier table in the Excellence Reform (2026-07-05)."
         enforcement: "warning"
 
       - id: subagent-discipline
-        rule: "Dispatch subagents only when task requires >3 Reads or >5 Greps or isolated context. Never parallel subagents sharing state. Prefer main thread for trivial tasks."
+        rule: "Dispatch subagents only when task requires >3 Reads or >5 Greps or isolated context. Never parallel subagents sharing state. Prefer main thread for trivial tasks. EXEMPT: quality dispatches (Quality Gate reviewers, adversarial verification, design review) are never suppressed by this rule — independent review context is a correctness requirement under excellence-mandate, not an optimisation choice."
         enforcement: "warning"
 
       # ─── Rule added in PR3 Squad Intelligence Upgrade (2026-05-28) ───────
@@ -436,3 +441,6 @@ amendments:
     - version: "2.32.0"
       date: "2026-05-13"
       changes: "PR10 Conclave Phase 5 — added 7 NON-NEGOTIABLE rules (quality-over-speed, always-research, project-design-system-prerequisite, definition-of-done-per-domain, arkaos-not-yes-man, inter-agent-checkpoints, hybrid-learning) and 3 new top-level sections (definition_of_done per domain, reference_companies, tone_guide)."
+    - version: "4.2.0"
+      date: "2026-07-05"
+      changes: "Excellence Reform (operator mandate) — added excellence-mandate NON-NEGOTIABLE rule; inverted model-routing from cost-optimised tiers to quality-first (best model for design/review/architecture/strategy, user overrides in ~/.arkaos/models.yaml); QG model_policy sonnet-default → best-available; QG reviewers independent + benchmark-cited verdicts + redo loop capped at 2; subagent-discipline exempts quality dispatches."

package/config/hooks/session-start.sh

@@ -120,6 +120,28 @@ if [ -n "$REPO" ] && command -v python3 &>/dev/null; then
   fi
 fi
 
+# ─── Dashboard ensure (v4.1.2) ──────────────────────────────────────────
+# Safety net for the login autostart (`npx arkaos autostart enable`): if the
+# dashboard is healthy this is two curl health checks (~50ms); if not, it
+# starts API+UI. Background + disown so it never touches the 5s budget.
+# Toggle off: ~/.arkaos/config.json -> {"dashboard": {"ensure_on_session": false}}
+if [ -n "$REPO" ] && [ -f "$REPO/scripts/start-dashboard.sh" ]; then
+  _DASH_ENSURE=$(python3 -c "import json; print(json.load(open('$HOME/.arkaos/config.json')).get('dashboard',{}).get('ensure_on_session', True))" 2>/dev/null || echo "True")
+  if [ "$_DASH_ENSURE" = "True" ] || [ "$_DASH_ENSURE" = "true" ]; then
+    mkdir -p "$HOME/.arkaos/logs"
+    (
+      # GNU `timeout` is absent on stock macOS — degrade to an unbounded
+      # run; the launcher itself is bounded (health wait + start).
+      if command -v timeout >/dev/null 2>&1; then
+        ARKAOS_NO_BROWSER=1 timeout 90s bash "$REPO/scripts/start-dashboard.sh" ensure >> "$HOME/.arkaos/logs/dashboard-ensure.log" 2>&1
+      else
+        ARKAOS_NO_BROWSER=1 bash "$REPO/scripts/start-dashboard.sh" ensure >> "$HOME/.arkaos/logs/dashboard-ensure.log" 2>&1
+      fi
+    ) &
+    disown 2>/dev/null || true
+  fi
+fi
+
 # --- Session Memory Resume Context ---
 if command -v python3 &>/dev/null && [ -n "$REPO" ]; then
   _SESSION_CTX=$(cd "$REPO" && python3 -c "

package/config/models.yaml

@@ -0,0 +1,70 @@
+# ═══════════════════════════════════════════════════════════════════════
+# ArkaOS Model Fabric — who runs what.
+#
+# Your copy lives at ~/.arkaos/models.yaml (created by `npx arkaos models
+# init`; this file is the packaged default). Edit it directly or use:
+#
+#   npx arkaos models                 show every role and what it resolves to
+#   npx arkaos models set review anthropic/best
+#   npx arkaos models set mechanical ollama/qwen3:8b
+#
+# The interactive runtime (Claude Code, Codex, Gemini, Cursor) keeps its
+# own main-loop model — roles govern everything ArkaOS itself dispatches:
+# subagents, Quality Gate, Forge, fusion, cognition, daemons.
+#
+# Constitution `model-routing` (Excellence Reform 2026-07-05): quality-
+# critical roles run the BEST model available by default; only genuinely
+# mechanical work economises. Change the mapping, not the posture.
+# ═══════════════════════════════════════════════════════════════════════
+version: 1
+
+# ─── Providers ──────────────────────────────────────────────────────────
+# type must match a provider in core/runtime/llm_provider.py.
+providers:
+  runtime:
+    type: subagent          # shell out to the active runtime CLI
+  anthropic:
+    type: anthropic-direct  # SDK; needs ANTHROPIC_API_KEY
+  ollama:
+    type: ollama            # local models, http://localhost:11434
+  # openrouter:             # one key -> hundreds of models (Model Fabric PR-B)
+  #   type: openrouter
+
+# ─── Aliases ────────────────────────────────────────────────────────────
+# `best` / `default` / `fast` resolve per provider, so roles stay readable.
+aliases:
+  runtime:
+    best: opus
+    default: sonnet
+    fast: haiku
+  anthropic:
+    best: claude-opus-4-8
+    default: claude-sonnet-5
+    fast: claude-haiku-4-5-20251001
+  ollama:
+    best: ""                # set your strongest local model, e.g. kimi-k2.6
+    default: ""
+    fast: ""
+
+# ─── Roles ──────────────────────────────────────────────────────────────
+# provider/model per kind of work. `model` is an alias above or a literal
+# model id. `effort`: low | medium | high | max.
+roles:
+  design:       {provider: runtime, model: best,    effort: max}
+  review:       {provider: runtime, model: best,    effort: max}
+  architecture: {provider: runtime, model: best,    effort: max}
+  strategy:     {provider: runtime, model: best,    effort: max}
+  quality_gate: {provider: runtime, model: best,    effort: max}
+  execution:    {provider: runtime, model: default, effort: high}
+  mechanical:   {provider: runtime, model: fast,    effort: low}
+
+# ─── Fusion (Model Fabric PR-D) ─────────────────────────────────────────
+# Panel answers in parallel; the judge analyses consensus, contradictions
+# and blind spots, then synthesises. Empty panel = fusion disabled.
+fusion:
+  judge: {provider: runtime, model: best, effort: max}
+  panel: []
+  # panel:
+  #   - {provider: ollama, model: kimi-k2.6}
+  #   - {provider: openrouter, model: deepseek/deepseek-v4-pro}
+  #   - {provider: anthropic, model: best}

package/core/hooks/pre_tool_use.py

@@ -5,10 +5,12 @@ with ONE python process. Gate order is preserved exactly:
 
     1. KB-first research gate  (core/workflow/research_gate.py)
     2. Specialist-dispatch gate (core/workflow/specialist_enforcer.py)
-    3. Fast allow for non-flow-gated tools
-    4. CostGovernor budget check (stdlib-only — MUST run even when the
+    3. Frontend excellence gate (core/workflow/frontend_gate.py — v4.2.0
+       excellence-mandate: UI edits require [arka:design] evidence)
+    4. Fast allow for non-flow-gated tools
+    5. CostGovernor budget check (stdlib-only — MUST run even when the
        yaml-needing enforcers degrade; see ADR 2026-07-04-cost-governor)
-    5. Evidence-flow gate (core/workflow/flow_enforcer.py)
+    6. Evidence-flow gate (core/workflow/flow_enforcer.py)
 
 Behavior contract (unchanged from the bash version):
     - allow  → no stdout, exit 0 (nudges/warnings on stderr)
@@ -165,6 +167,50 @@ def _specialist_gate(
     return None
 
 
+def _frontend_gate(
+    root: str,
+    tool_name: str,
+    transcript_path: str,
+    session_id: str,
+    cwd: str,
+    tool_input: dict,
+    messages: _MessagesOnce,
+) -> int | None:
+    """Frontend excellence gate (excellence-mandate). 2 on deny, None to continue."""
+    if tool_name not in _SPECIALIST_TOOLS:
+        return None
+    if not (Path(root) / "core" / "workflow" / "frontend_gate.py").is_file():
+        return None
+    try:
+        from core.workflow.frontend_gate import (
+            evaluate,
+            is_ui_file,
+            record_telemetry,
+        )
+    except Exception:
+        return None  # frontend-gate-import-failed → allow
+    # Zero-read fast path: only UI files ever need the transcript.
+    if not is_ui_file(str(tool_input.get("file_path", ""))):
+        return None
+    decision = evaluate(
+        tool_name=tool_name,
+        transcript_path=transcript_path,
+        session_id=session_id,
+        cwd=cwd,
+        tool_input=tool_input,
+        messages=messages.load(),
+    )
+    try:
+        record_telemetry(session_id=session_id, tool=tool_name, decision=decision)
+    except Exception:
+        pass
+    if not decision.allow:
+        return _deny(decision.to_stderr_message())
+    if decision.to_stderr_message():
+        print(decision.to_stderr_message(), file=sys.stderr)
+    return None
+
+
 def _budget_check(session_id: str) -> tuple[bool, str]:
     """CostGovernor gate (stdlib-only). Returns (allow, warning)."""
     try:
@@ -244,6 +290,12 @@ def main(stdin_json: dict | None = None) -> int:
     if code is not None:
         return code
 
+    code = _frontend_gate(
+        root, tool_name, transcript_path, session_id, cwd, tool_input, messages
+    )
+    if code is not None:
+        return code
+
     # Fast allow: not a flow-gated tool (Bash stays — classified per-command
     # by the enforcer via bash_is_effect()).
     if tool_name not in _FLOW_GATED_TOOLS:

package/core/runtime/llm_provider.py

@@ -32,7 +32,9 @@ from core.runtime.pricing import estimate_cost_usd
 
 
 _DEFAULT_CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
-_FALLBACK_ORDER: tuple[str, ...] = ("subagent", "ollama", "anthropic-direct", "stub")
+_FALLBACK_ORDER: tuple[str, ...] = (
+    "subagent", "ollama", "openrouter", "anthropic-direct", "stub"
+)
 
 
 # ─── Public dataclass ─────────────────────────────────────────────────
@@ -330,9 +332,16 @@ def _import_ollama_provider() -> type:
     return OllamaProvider
 
 
+def _import_openrouter_provider() -> type:
+    """Lazy import to keep the OpenRouter provider optional at runtime."""
+    from core.runtime.openrouter_provider import OpenRouterProvider
+    return OpenRouterProvider
+
+
 _PROVIDERS: dict[str, type] = {
     "subagent": SubagentProvider,
     "ollama": _import_ollama_provider(),
+    "openrouter": _import_openrouter_provider(),
     "anthropic-direct": AnthropicDirectProvider,
     "stub": StubProvider,
 }

package/core/runtime/model_router.py

@@ -0,0 +1,204 @@
+"""Model Fabric router — resolve a work role to (provider, model, effort).
+
+The user owns ``~/.arkaos/models.yaml``; the packaged default ships at
+``config/models.yaml``. Roles govern everything ArkaOS dispatches
+(subagents, Quality Gate, Forge, fusion, cognition, daemons) — the
+interactive runtime keeps its own main-loop model.
+
+Constitution ``model-routing`` (Excellence Reform 2026-07-05): quality-
+critical roles (design, review, architecture, strategy, quality_gate)
+default to the best model available at maximum effort; only genuinely
+mechanical work economises. The built-in fallback used when no YAML can
+be read encodes the same posture — a missing file never silently
+downgrades a quality role.
+
+Public API::
+
+    resolve("review")          -> ResolvedModel(provider, model, effort)
+    load_config()              -> ModelsConfig
+    ensure_user_config()       -> Path (creates ~/.arkaos/models.yaml)
+    set_role("review", "anthropic/best", effort="max")
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+USER_CONFIG_PATH = Path.home() / ".arkaos" / "models.yaml"
+
+QUALITY_ROLES = frozenset({
+    "design", "review", "architecture", "strategy", "quality_gate",
+})
+KNOWN_EFFORTS = ("low", "medium", "high", "max")
+
+_ALIAS_NAMES = frozenset({"best", "default", "fast"})
+
+
+class RoleChoice(BaseModel):
+    """One role entry as written in models.yaml."""
+
+    provider: str = "runtime"
+    model: str = "best"
+    effort: str = "high"
+
+    @field_validator("effort")
+    @classmethod
+    def _known_effort(cls, value: str) -> str:
+        if value not in KNOWN_EFFORTS:
+            raise ValueError(
+                f"effort must be one of {KNOWN_EFFORTS}, got {value!r}"
+            )
+        return value
+
+
+class FusionConfig(BaseModel):
+    """Judge + panel for the fusion engine (PR-D consumes this)."""
+
+    judge: RoleChoice = Field(default_factory=lambda: RoleChoice(effort="max"))
+    panel: list[RoleChoice] = Field(default_factory=list)
+
+
+class ModelsConfig(BaseModel):
+    """Validated shape of models.yaml."""
+
+    version: int = 1
+    providers: dict[str, dict] = Field(default_factory=dict)
+    aliases: dict[str, dict[str, str]] = Field(default_factory=dict)
+    roles: dict[str, RoleChoice] = Field(default_factory=dict)
+    fusion: FusionConfig = Field(default_factory=FusionConfig)
+
+
+class ResolvedModel(BaseModel):
+    """A role after alias resolution — what a dispatcher actually uses."""
+
+    role: str
+    provider: str
+    model: str
+    effort: str
+    source: str  # "user" | "packaged" | "builtin"
+
+
+def _packaged_config_path() -> Path:
+    return Path(__file__).resolve().parents[2] / "config" / "models.yaml"
+
+
+def _builtin_config() -> ModelsConfig:
+    """Quality-first posture used when no YAML is readable at all."""
+    roles = {
+        role: RoleChoice(model="best", effort="max") for role in QUALITY_ROLES
+    }
+    roles["execution"] = RoleChoice(model="default", effort="high")
+    roles["mechanical"] = RoleChoice(model="fast", effort="low")
+    return ModelsConfig(
+        providers={"runtime": {"type": "subagent"}},
+        aliases={"runtime": {"best": "opus", "default": "sonnet", "fast": "haiku"}},
+        roles=roles,
+    )
+
+
+def _read_yaml(path: Path) -> ModelsConfig | None:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    try:
+        return ModelsConfig.model_validate(data)
+    except ValueError:
+        return None
+
+
+def load_config(user_path: Path | None = None) -> tuple[ModelsConfig, str]:
+    """Load config with provenance: user file, packaged default, builtin."""
+    path = user_path or USER_CONFIG_PATH
+    config = _read_yaml(path) if path.is_file() else None
+    if config is not None:
+        return config, "user"
+    packaged = _packaged_config_path()
+    config = _read_yaml(packaged) if packaged.is_file() else None
+    if config is not None:
+        return config, "packaged"
+    return _builtin_config(), "builtin"
+
+
+def _resolve_alias(config: ModelsConfig, provider: str, model: str) -> str:
+    if model not in _ALIAS_NAMES:
+        return model
+    return config.aliases.get(provider, {}).get(model, "") or model
+
+
+def resolve(role: str, user_path: Path | None = None) -> ResolvedModel:
+    """Resolve a role name to a concrete (provider, model, effort).
+
+    Unknown roles resolve conservatively: quality posture, not economy —
+    a typo must never silently land on the cheap tier
+    (``excellence-mandate``).
+    """
+    config, source = load_config(user_path)
+    choice = config.roles.get(role)
+    if choice is None:
+        fallback = "execution" if role not in QUALITY_ROLES else role
+        choice = config.roles.get(fallback, RoleChoice(model="best", effort="max"))
+    return ResolvedModel(
+        role=role,
+        provider=choice.provider,
+        model=_resolve_alias(config, choice.provider, choice.model),
+        effort=choice.effort,
+        source=source,
+    )
+
+
+def resolve_all(user_path: Path | None = None) -> list[ResolvedModel]:
+    """Resolve every configured role — the CLI table."""
+    config, _ = load_config(user_path)
+    return [resolve(role, user_path) for role in sorted(config.roles)]
+
+
+def ensure_user_config(user_path: Path | None = None) -> Path:
+    """Create ~/.arkaos/models.yaml from the packaged default if absent."""
+    path = user_path or USER_CONFIG_PATH
+    if path.is_file():
+        return path
+    path.parent.mkdir(parents=True, exist_ok=True)
+    packaged = _packaged_config_path()
+    if packaged.is_file():
+        shutil.copy(packaged, path)
+    else:
+        path.write_text(
+            yaml.safe_dump(_builtin_config().model_dump(), sort_keys=False),
+            encoding="utf-8",
+        )
+    return path
+
+
+def set_role(
+    role: str,
+    target: str,
+    effort: str | None = None,
+    user_path: Path | None = None,
+) -> ResolvedModel:
+    """Point a role at ``provider/model`` (e.g. ``anthropic/best``).
+
+    Writes the user file (creating it first when needed) and returns the
+    new resolution. Raises ValueError on a malformed target or effort.
+    """
+    if "/" not in target:
+        raise ValueError(
+            f"target must be provider/model (e.g. runtime/best), got {target!r}"
+        )
+    provider, model = target.split("/", 1)
+    path = ensure_user_config(user_path)
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    entry = {"provider": provider, "model": model}
+    entry["effort"] = effort or data.get("roles", {}).get(role, {}).get(
+        "effort", "max" if role in QUALITY_ROLES else "high"
+    )
+    RoleChoice.model_validate(entry)  # fail before writing anything
+    data.setdefault("roles", {})[role] = entry
+    path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+    return resolve(role, path)

package/core/runtime/model_router_cli.py

@@ -0,0 +1,82 @@
+"""CLI for the Model Fabric router — `npx arkaos models` delegates here.
+
+Usage::
+
+    python -m core.runtime.model_router_cli               # table of roles
+    python -m core.runtime.model_router_cli --json        # machine-readable
+    python -m core.runtime.model_router_cli init          # create user file
+    python -m core.runtime.model_router_cli set review anthropic/best --effort max
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from core.runtime.model_router import (
+    USER_CONFIG_PATH,
+    ensure_user_config,
+    load_config,
+    resolve_all,
+    set_role,
+)
+
+
+def _print_table() -> None:
+    resolved = resolve_all()
+    _, source = load_config()
+    print()
+    print("  ArkaOS Model Fabric — role routing")
+    print(f"  config: {USER_CONFIG_PATH if source == 'user' else source}")
+    print()
+    header = f"  {'ROLE':<14} {'PROVIDER':<12} {'MODEL':<34} EFFORT"
+    print(header)
+    print("  " + "─" * (len(header) - 2))
+    for item in resolved:
+        model = item.model or "(unset — configure alias)"
+        print(f"  {item.role:<14} {item.provider:<12} {model:<34} {item.effort}")
+    print()
+    print("  Change: npx arkaos models set <role> <provider>/<model> [--effort max]")
+    print()
+
+
+def _print_json() -> None:
+    payload = [item.model_dump() for item in resolve_all()]
+    print(json.dumps(payload, indent=2))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="arkaos models")
+    parser.add_argument("action", nargs="?", default="list",
+                        choices=["list", "init", "set"])
+    parser.add_argument("role", nargs="?")
+    parser.add_argument("target", nargs="?")
+    parser.add_argument("--effort", choices=["low", "medium", "high", "max"])
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    if args.action == "init":
+        path = ensure_user_config()
+        print(f"  ✓ Model Fabric config: {path}")
+        return 0
+    if args.action == "set":
+        if not args.role or not args.target:
+            parser.error("set requires: <role> <provider>/<model>")
+        try:
+            item = set_role(args.role, args.target, effort=args.effort)
+        except ValueError as exc:
+            print(f"  ✗ {exc}", file=sys.stderr)
+            return 1
+        print(f"  ✓ {item.role} -> {item.provider}/{item.model} "
+              f"(effort {item.effort})")
+        return 0
+    if args.as_json:
+        _print_json()
+    else:
+        _print_table()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/core/runtime/openrouter_provider.py

@@ -0,0 +1,172 @@
+"""OpenRouter provider — one API key, hundreds of models.
+
+Model Fabric PR-B. One of the backends behind the ``LLMProvider``
+Protocol in ``core/runtime/llm_provider.py``; callers go through
+``get_llm_provider()`` or pass an explicit model resolved by
+``core/runtime/model_router.py`` (e.g. role ``review`` →
+``openrouter/deepseek/deepseek-v4-pro``).
+
+OpenAI-compatible ``/api/v1/chat/completions`` via stdlib ``urllib`` —
+no extra dependencies, mirroring ``ollama_provider.py``. Key resolution:
+``OPENROUTER_API_KEY`` env, then ``~/.arkaos/keys.json``. Model from
+constructor, then ``OPENROUTER_MODEL`` env, then
+``models.yaml`` alias ``openrouter.default``.
+
+OpenRouter returns token usage (and native cached-token counts for
+providers that support caching) in the ``usage`` block; both are
+forwarded so cost telemetry stays accurate.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from core.runtime.llm_provider import LLMResponse, LLMUnavailable
+
+_API_BASE = "https://openrouter.ai/api/v1"
+_TIMEOUT_S = 180  # frontier models on long prompts; fusion panels wait
+_KEYS_PATH = Path.home() / ".arkaos" / "keys.json"
+
+# Attribution headers — OpenRouter ranks apps by these; harmless otherwise.
+_APP_HEADERS = {
+    "HTTP-Referer": "https://github.com/andreagroferreira/arka-os",
+    "X-Title": "ArkaOS",
+}
+
+
+def _read_key_from_keys_json() -> str:
+    try:
+        data = json.loads(_KEYS_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return ""
+    value = data.get("OPENROUTER_API_KEY", "")
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _default_model_from_fabric() -> str:
+    """Resolve the `openrouter.default` alias from models.yaml, if set."""
+    try:
+        from core.runtime.model_router import load_config
+        config, _ = load_config()
+    except Exception:
+        return ""
+    return config.aliases.get("openrouter", {}).get("default", "")
+
+
+class OpenRouterProvider:
+    """Provider that hits the OpenRouter chat-completions API."""
+
+    ENV_KEY = "OPENROUTER_API_KEY"
+    ENV_MODEL = "OPENROUTER_MODEL"
+
+    def __init__(self, model: str | None = None, api_base: str | None = None) -> None:
+        self._model_override = model
+        self._api_base = (api_base or _API_BASE).rstrip("/")
+
+    def name(self) -> str:
+        return "openrouter"
+
+    def _resolve_key(self) -> str:
+        env_value = os.environ.get(self.ENV_KEY, "").strip()
+        return env_value or _read_key_from_keys_json()
+
+    def _resolve_model(self) -> str:
+        if self._model_override:
+            return self._model_override
+        env_value = os.environ.get(self.ENV_MODEL, "").strip()
+        return env_value or _default_model_from_fabric()
+
+    def is_available(self) -> bool:
+        """Static capability check: a key and a model are configured.
+
+        No network probe — OpenRouter is a paid remote API and this is
+        called on every provider-chain walk; a dead network surfaces as
+        ``LLMUnavailable`` at call time and the chain moves on.
+        """
+        return bool(self._resolve_key() and self._resolve_model())
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        max_tokens: int = 2000,
+        system: str = "",
+    ) -> LLMResponse:
+        key = self._resolve_key()
+        if not key:
+            raise LLMUnavailable(
+                "OpenRouter key not configured (set OPENROUTER_API_KEY or "
+                "add it via `npx arkaos keys`)"
+            )
+        model = self._resolve_model()
+        if not model:
+            raise LLMUnavailable(
+                "OpenRouter model not configured (set OPENROUTER_MODEL, pass "
+                "model=, or set aliases.openrouter.default in models.yaml)"
+            )
+        data = self._post_chat(key, self._build_payload(model, prompt, system, max_tokens))
+        return self._to_response(data, model)
+
+    def _build_payload(
+        self, model: str, prompt: str, system: str, max_tokens: int
+    ) -> dict:
+        messages: list[dict] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        return {
+            "model": model,
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "stream": False,
+            "usage": {"include": True},  # cost + cached tokens in response
+        }
+
+    def _post_chat(self, key: str, payload: dict) -> dict:
+        request = urllib.request.Request(
+            f"{self._api_base}/chat/completions",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {key}",
+                **_APP_HEADERS,
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=_TIMEOUT_S) as response:
+                raw = response.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[:300]
+            raise LLMUnavailable(
+                f"OpenRouter HTTP {exc.code}: {detail}"
+            ) from exc
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise LLMUnavailable(f"OpenRouter request failed: {exc}") from exc
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise LLMUnavailable(f"OpenRouter returned invalid JSON: {exc}") from exc
+
+    def _to_response(self, data: dict, model: str) -> LLMResponse:
+        if data.get("error"):
+            message = data["error"].get("message", "unknown error")
+            raise LLMUnavailable(f"OpenRouter error: {message}")
+        choices = data.get("choices") or []
+        text = ""
+        if choices:
+            text = ((choices[0].get("message") or {}).get("content") or "").strip()
+        usage = data.get("usage") or {}
+        cached = int(
+            (usage.get("prompt_tokens_details") or {}).get("cached_tokens", 0) or 0
+        )
+        return LLMResponse(
+            text=text,
+            tokens_in=int(usage.get("prompt_tokens", 0) or 0),
+            tokens_out=int(usage.get("completion_tokens", 0) or 0),
+            cached_tokens=cached,
+            model=str(data.get("model") or model),
+        )

package/core/workflow/frontend_gate.py

@@ -0,0 +1,162 @@
+"""Frontend excellence gate — PreToolUse enforcement for UI file edits.
+
+Constitution: ``excellence-mandate`` (NON-NEGOTIABLE, Excellence Reform
+2026-07-05). UI work must load the frontend design skills and judge
+against a named benchmark BEFORE code is written. This gate makes that
+duty mechanical: a Write/Edit/MultiEdit touching a UI file requires an
+``[arka:design] <skills/benchmark>`` marker in the recent assistant
+messages — the same ceremony contract as ``[arka:routing]``
+(flow_enforcer) and ``[arka:dispatch]`` (specialist_enforcer).
+
+Modes via ``hooks.frontendGate`` in ``~/.arkaos/config.json``:
+
+    absent / "warn"   → nudge on stderr, allow (rollout default)
+    true / "hard"     → deny UI edits without the marker
+    false / "off"     → gate disabled
+
+Bypasses: ``[arka:trivial] <reason>`` marker (same contract as the
+evidence flow — single-file edits under 10 lines) and
+``ARKA_BYPASS_DESIGN=1`` env (logged for accountability).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from core.shared import safe_session_id as _safe_session_id_module
+from core.workflow.flow_enforcer import (
+    TRIVIAL_RE,
+    _load_last_assistant_messages,
+)
+from core.workflow.specialist_enforcer import _locked_append
+
+CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
+TELEMETRY_PATH = Path.home() / ".arkaos" / "telemetry" / "frontend-gate.jsonl"
+
+ASSISTANT_WINDOW = 20
+
+DESIGN_RE = re.compile(r"\[arka:design\]\s*\S+", re.IGNORECASE)
+
+_GATED_TOOLS = frozenset({"Write", "Edit", "MultiEdit"})
+
+# Component + stylesheet extensions. Plain .ts/.js are excluded: they are
+# ambiguous (stores, utils, configs) and would flood the gate with false
+# positives — the component file is where the visual decision lands.
+UI_SUFFIXES = frozenset({
+    ".vue", ".tsx", ".jsx", ".svelte", ".astro",
+    ".css", ".scss", ".sass", ".less",
+})
+
+
+@dataclass
+class Decision:
+    """Outcome of frontend-gate evaluation."""
+
+    allow: bool
+    reason: str
+    mode: str = "warn"
+    target_file: str = ""
+    marker_found: str | None = None
+
+    def to_stderr_message(self) -> str:
+        if self.reason not in ("no-design-marker",):
+            return ""
+        head = "[arka:suggest]" if self.allow else "[ARKA:DESIGN]"
+        verb = "should" if self.allow else "MUST"
+        return (
+            f"{head} UI edit to {self.target_file or 'this file'} without "
+            f"design evidence. Frontend work {verb} load the design skills "
+            f"(frontend-design, ui-ux-pro-max, project design system) at "
+            f"maximum effort and judge against a named benchmark FIRST "
+            f"(constitution `excellence-mandate`). Emit "
+            f"`[arka:design] <skills> benchmark=<name>` before UI edits, "
+            f"or `[arka:trivial] <reason>` for sub-10-line fixes."
+        )
+
+
+def _mode() -> str:
+    """Resolve ``hooks.frontendGate`` to 'off' | 'warn' | 'hard'."""
+    if not CONFIG_PATH.exists():
+        return "warn"
+    try:
+        data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return "warn"
+    raw = data.get("hooks", {}).get("frontendGate", "warn")
+    if raw in (False, "off", "false"):
+        return "off"
+    if raw in (True, "hard", "true"):
+        return "hard"
+    return "warn"
+
+
+def is_ui_file(file_path: str) -> bool:
+    """True when the path carries a gated UI extension."""
+    return Path(file_path).suffix.lower() in UI_SUFFIXES
+
+
+def _scan(messages: list[str]) -> str | None:
+    """Return the matched evidence marker, or None."""
+    for message in messages:
+        match = DESIGN_RE.search(message) or TRIVIAL_RE.search(message)
+        if match:
+            return match.group(0)
+    return None
+
+
+def evaluate(
+    tool_name: str,
+    transcript_path: str,
+    session_id: str,
+    cwd: str,
+    tool_input: dict,
+    messages: list[str] | None = None,
+) -> Decision:
+    """Evaluate one tool call against the frontend excellence gate."""
+    file_path = str(tool_input.get("file_path", ""))
+    if tool_name not in _GATED_TOOLS or not is_ui_file(file_path):
+        return Decision(allow=True, reason="not-ui-scope", target_file=file_path)
+    mode = _mode()
+    if mode == "off":
+        return Decision(allow=True, reason="flag-off", mode=mode,
+                        target_file=file_path)
+    if os.environ.get("ARKA_BYPASS_DESIGN") == "1":
+        return Decision(allow=True, reason="env-bypass", mode=mode,
+                        target_file=file_path)
+    if messages is None:
+        messages = _load_last_assistant_messages(
+            transcript_path, ASSISTANT_WINDOW
+        )
+    marker = _scan(messages)
+    if marker is not None:
+        return Decision(allow=True, reason="design-evidence", mode=mode,
+                        target_file=file_path, marker_found=marker)
+    return Decision(allow=(mode != "hard"), reason="no-design-marker",
+                    mode=mode, target_file=file_path)
+
+
+def record_telemetry(session_id: str, tool: str, decision: Decision) -> None:
+    """Append a structured record to the frontend-gate telemetry log.
+
+    Drops the record silently when session_id fails the safe-id check
+    (path-traversal mitigation, CWE-22). Never blocks the hook.
+    """
+    safe = _safe_session_id_module.safe_session_id(session_id)
+    if safe is None:
+        return
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "session_id": safe,
+        "tool": tool,
+        **asdict(decision),
+    }
+    try:
+        with _locked_append(TELEMETRY_PATH) as fh:
+            fh.write(json.dumps(entry) + "\n")
+    except OSError:
+        pass

package/installer/autostart.js

@@ -29,6 +29,9 @@ export function unitFor(os, { repoRoot, home }) {
   if (os === "darwin") {
     const startScript = `${repoRoot}/scripts/start-dashboard.sh`;
     const log = `${home}/.arkaos/logs/dashboard-autostart.log`;
+    // AbandonProcessGroup: the launcher backgrounds the API/UI and exits;
+    // without it launchd kills the whole process group on exit and the
+    // dashboard dies seconds after boot. `ensure` keeps re-loads idempotent.
     const content = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -39,14 +42,19 @@ export function unitFor(os, { repoRoot, home }) {
   <array>
     <string>/bin/bash</string>
     <string>${startScript}</string>
+    <string>ensure</string>
   </array>
   <key>EnvironmentVariables</key>
   <dict>
     <key>ARKAOS_ROOT</key>
     <string>${repoRoot}</string>
+    <key>ARKAOS_NO_BROWSER</key>
+    <string>1</string>
   </dict>
   <key>RunAtLoad</key>
   <true/>
+  <key>AbandonProcessGroup</key>
+  <true/>
   <key>StandardOutPath</key>
   <string>${log}</string>
   <key>StandardErrorPath</key>
@@ -63,14 +71,19 @@ export function unitFor(os, { repoRoot, home }) {
 
   if (os === "linux") {
     const startScript = `${repoRoot}/scripts/start-dashboard.sh`;
+    // oneshot + RemainAfterExit: the launcher backgrounds the API/UI and
+    // exits; Type=simple would mark the unit dead on exit and systemd would
+    // reap the children with the cgroup. `ensure` keeps restarts idempotent.
     const content = `[Unit]
 Description=ArkaOS Dashboard (Python API + UI)
 After=network.target
 
 [Service]
-Type=simple
+Type=oneshot
+RemainAfterExit=yes
 Environment=ARKAOS_ROOT=${repoRoot}
-ExecStart=/bin/bash ${startScript}
+Environment=ARKAOS_NO_BROWSER=1
+ExecStart=/bin/bash ${startScript} ensure
 Restart=on-failure
 
 [Install]
@@ -87,6 +100,7 @@ WantedBy=default.target
     const ps1 = join(repoRoot, "scripts", "start-dashboard.ps1");
     const content = `@echo off
 rem ArkaOS dashboard autostart (login).
+set ARKAOS_NO_BROWSER=1
 powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "${ps1}"
 `;
     return {

package/installer/cli.js

@@ -25,6 +25,9 @@ const { values, positionals } = parseArgs({
     // `values.fix` rather than as a free positional under strict:false.
     // Eliminates the dead-branch fallback flagged by Marta in PR2's QG.
     fix: { type: "boolean" },
+    // Model Fabric PR-A — `npx arkaos models [--json] [set ... --effort max]`
+    json: { type: "boolean" },
+    effort: { type: "string" },
   },
   allowPositionals: true,
   strict: false,
@@ -51,6 +54,8 @@ Usage:
   npx arkaos dashboard        Start monitoring dashboard
   npx arkaos autostart <enable|disable|status>  Start dashboard on boot
   npx arkaos keys             Manage API keys (OpenAI, fal.ai, etc.)
+  npx arkaos models           Model Fabric: which model runs each role
+  npx arkaos models set <role> <provider>/<model>  Re-route a role
   npx arkaos doctor           Run health checks
   npx arkaos uninstall        Remove ArkaOS
 
@@ -154,6 +159,24 @@ async function main() {
       break;
     }
 
+    case "models": {
+      const { execSync } = await import("node:child_process");
+      const repoRootModels = join(__dirname, "..");
+      const pyModels = getArkaosPython();
+      if (!pyModels) { console.error("No Python found. Run: npx arkaos install"); process.exit(1); }
+      const modelArgs = positionals.slice(1).map((a) => `"${a}"`).join(" ");
+      const effortFlag = values.effort ? ` --effort "${values.effort}"` : "";
+      const jsonFlag = values.json ? " --json" : "";
+      try {
+        execSync(`"${pyModels}" -m core.runtime.model_router_cli ${modelArgs}${effortFlag}${jsonFlag}`, {
+          stdio: "inherit",
+          cwd: repoRootModels,
+          env: { ...process.env, ARKAOS_ROOT: repoRootModels, PYTHONPATH: repoRootModels },
+        });
+      } catch { process.exit(1); }
+      break;
+    }
+
     case "index": {
       const { execSync } = await import("node:child_process");
       const indexArgs = positionals.slice(1).join(" ");

package/installer/keys.js

@@ -6,6 +6,7 @@ const KEYS_PATH = join(homedir(), ".arkaos", "keys.json");
 
 const PROVIDERS = {
   OPENAI_API_KEY: { name: "OpenAI", used_for: "Whisper transcription, embeddings, GPT" },
+  OPENROUTER_API_KEY: { name: "OpenRouter", used_for: "Model Fabric: one key, hundreds of models (Kimi, DeepSeek, GPT, Gemini) for roles + fusion" },
   GOOGLE_API_KEY: { name: "Google", used_for: "Gemini API, Nano Banana, Google Cloud AI" },
   FAL_API_KEY: { name: "fal.ai", used_for: "Image generation, video generation" },
   MAGIC_API_KEY: { name: "21st.dev Magic", used_for: "Frontend UI/UX component generation (Magic MCP)" },

package/package.json

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

package/pyproject.toml

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

package/scripts/start-dashboard.sh

@@ -10,6 +10,30 @@ VENV_PYTHON="$HOME/.arkaos/venv/bin/python"
 
 mkdir -p "$HOME/.arkaos"
 
+# ── Args ──
+# `ensure`       — idempotent mode: exit 0 if API+UI already healthy,
+#                  otherwise fall through to a full start. Safe to call from
+#                  SessionStart hooks and launchd/systemd boot units.
+# `--no-browser` — do not open the browser after start (also via
+#                  ARKAOS_NO_BROWSER=1 env, for boot/hook contexts).
+MODE="start"
+for arg in "$@"; do
+  case "$arg" in
+    ensure) MODE="ensure" ;;
+    --no-browser) ARKAOS_NO_BROWSER=1 ;;
+  esac
+done
+
+if [ "$MODE" = "ensure" ] && [ -f "$PORT_FILE" ]; then
+  # shellcheck disable=SC1090
+  source "$PORT_FILE"
+  if curl -sf --max-time 2 "http://localhost:${API_PORT:-0}/api/overview" >/dev/null 2>&1 \
+     && curl -sf --max-time 2 "http://localhost:${UI_PORT:-0}/" >/dev/null 2>&1; then
+    echo "  ✓ Dashboard already running (API :${API_PORT}, UI :${UI_PORT})"
+    exit 0
+  fi
+fi
+
 # ── Venv guard (PR2 v3.73.1 — Force Specialist Dispatch dogfood) ──
 # Previously the dashboard fell back to ambient `python3` when the venv
 # wasn't available. That hid broken-venv conditions (Homebrew patch
@@ -133,7 +157,7 @@ echo "        or kill \$(cat $PID_FILE)"
 echo ""
 
 # Wait for UI to be ready
-if [ -n "$UI_PID" ]; then
+if [ -n "$UI_PID" ] && [ -z "${ARKAOS_NO_BROWSER:-}" ]; then
   sleep 5
   # Open browser
   if command -v open >/dev/null 2>&1; then