arkaos 4.3.5 → 4.3.6

package/VERSION

@@ -1 +1 @@
-4.3.5
+4.3.6

package/arka/SKILL.md

@@ -179,7 +179,7 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 
 | Command | Description |
 |---------|-------------|
-| `/arka status` | System status (version, departments, agents, active projects). Includes **LLM costs (24h)** section: top-line cost + cache hit rate + call count from `core.runtime.llm_cost_telemetry.summarise(period="today")`. Also includes **Enforcement (24h)** section: total calls, block rate, top blocked tools/reasons from `core.governance.enforcement_telemetry.summarise(period="today")` (PR19 v2.41.0). Plus **Reorganization (today)** section: today's proposal path + artifact count from `core.cognition.reorganizer_scheduler.status_summary()` (PR24 v2.46.0). |
+| `/arka status` | System status (version, departments, agents, active projects). Includes **LLM costs (24h)** section: top-line cost + cache hit rate + call count from `core.runtime.llm_cost_telemetry.summarise(period="today")`. Also includes **Enforcement (24h)** section: total calls, block rate, top blocked tools/reasons from `core.governance.enforcement_telemetry.summarise(period="today")` (PR19 v2.41.0). Plus **Reorganization (today)** section: today's proposal path + artifact count from `core.cognition.reorganizer_scheduler.status_summary()` (PR24 v2.46.0). Plus **Model routing** section: gateway live/off + resolved per-slot routes + served counts from `core.runtime.model_routing_check.status_summary()`. |
 | `/arka costs [period]` | LLM cost visibility — aggregates telemetry by day/week/month/all, with top expensive sessions. See `arka/skills/costs/SKILL.md`. Shells out to `~/.arkaos/bin/arka-py -m core.runtime.llm_cost_telemetry_cli <period>`. |
 | `/arka enforcement [period]` | Enforcement compliance — aggregates flow-marker enforcement telemetry by day/week/month/all. Shows block rate, top blocked tools, top reasons. Shells out to `~/.arkaos/bin/arka-py -m core.governance.enforcement_telemetry_cli <period>`. |
 | `/arka compliance [period]` | Behavior compliance summary (PR29 v2.48.0) — aggregates stop-hook telemetry by day/week/month/all. Shows rates for the four contracts: closing marker, `[arka:meta]` tag, KB citation pass, sycophancy clean. Shells out to `~/.arkaos/bin/arka-py -m core.governance.compliance_telemetry_cli <period>`. |

package/bin/arka-claude

@@ -13,14 +13,24 @@ CYAN='\033[0;36m'
 YELLOW='\033[1;33m'
 RESET='\033[0m'
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_self="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+for _lib in \
+    "$_self/../config/hooks/_lib/arka_python.sh" \
+    "$HOME/.arkaos/config/hooks/_lib/arka_python.sh"; do
+  # shellcheck source=/dev/null
+  [ -f "$_lib" ] && { . "$_lib"; break; }
+done
+: "${ARKA_PY:=python3}"
+
 # ─── Profile ───────────────────────────────────────────────────────────
 NAME="founder"
 COMPANY="WizardingCode"
 VERSION="2.x"
 
-if [ -f "$HOME/.arkaos/profile.json" ] && command -v python3 &>/dev/null; then
-  NAME=$(python3 -c "import json; p=json.load(open('$HOME/.arkaos/profile.json')); print(p.get('name', p.get('role', 'founder')))" 2>/dev/null || echo "founder")
-  COMPANY=$(python3 -c "import json; print(json.load(open('$HOME/.arkaos/profile.json')).get('company', 'WizardingCode'))" 2>/dev/null || echo "WizardingCode")
+if [ -f "$HOME/.arkaos/profile.json" ]; then
+  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 || echo "founder")
+  COMPANY=$("$ARKA_PY" -c "import json; print(json.load(open('$HOME/.arkaos/profile.json')).get('company', 'WizardingCode'))" 2>/dev/null || echo "WizardingCode")
 fi
 
 if [ -f "$HOME/.arkaos/.repo-path" ]; then
@@ -38,7 +48,7 @@ else GREETING="Boa noite"; fi
 DRIFT_MSG=""
 SYNC_STATE="$HOME/.arkaos/sync-state.json"
 if [ -f "$SYNC_STATE" ]; then
-  SYNCED=$(python3 -c "import json; print(json.load(open('$SYNC_STATE'))['version'])" 2>/dev/null || echo "none")
+  SYNCED=$("$ARKA_PY" -c "import json; print(json.load(open('$SYNC_STATE'))['version'])" 2>/dev/null || echo "none")
   if [ "$SYNCED" != "$VERSION" ]; then
     DRIFT_MSG="\n  ${YELLOW}⚠  Update available: run /arka update to sync${RESET}"
   fi
@@ -60,5 +70,26 @@ echo -e "  ${DIM}ArkaOS v${VERSION} │ 65 agents │ 17 departments │ 244+ sk
 echo -e "${DRIFT_MSG}"
 echo ""
 
+# ─── Model-routing gateway (opt-in: ARKA_GATEWAY=1) ────────────────────
+# Renders the LiteLLM proxy from ~/.arkaos/models.yaml and launches Claude
+# Code against it, so per-role model choices (execution→Ollama, quality→
+# Anthropic) actually take effect. Any failure degrades to a plain launch.
+if [ "${ARKA_GATEWAY:-0}" = "1" ] && [ -n "${REPO:-}" ]; then
+  _GW="$REPO/scripts/gateway-ensure.sh"
+  _ENV_FILE="$HOME/.arkaos/gateway/launch.env"
+  if [ -f "$_GW" ] && ARKAOS_ROOT="$REPO" ARKAOS_HOME="$HOME/.arkaos" bash "$_GW"; then
+    # Source the generated env without eval (values are ArkaOS-controlled).
+    set -a
+    # shellcheck source=/dev/null
+    . "$_ENV_FILE"
+    set +a
+    echo -e "  ${GREEN}⚡ Model Fabric gateway active${RESET} ${DIM}(models.yaml per-role routing)${RESET}"
+    echo ""
+  else
+    echo -e "  ${DIM}(gateway off — plain Claude launch)${RESET}"
+    echo ""
+  fi
+fi
+
 # ─── Launch Claude ─────────────────────────────────────────────────────
 exec claude "$@"

package/core/runtime/gateway/__init__.py

@@ -0,0 +1,28 @@
+"""ArkaOS model-routing gateway.
+
+Turns the operator's ``~/.arkaos/models.yaml`` role routing into a running
+LiteLLM proxy so per-role model choices actually take effect at dispatch
+time. Claude Code points ``ANTHROPIC_BASE_URL`` at the proxy; the proxy
+fans each request out to the right upstream (Anthropic-direct or local
+Ollama) by the model name the alias slot carries.
+
+See ``docs/adr`` and the plan for why a gateway is required: Claude Code's
+``ANTHROPIC_BASE_URL`` is one endpoint per process, so honouring mixed
+providers per role in a single session needs a fan-out proxy.
+"""
+
+from core.runtime.gateway.litellm_config import (
+    GatewayPlan,
+    build_gateway_plan,
+    build_launch_env,
+    build_litellm_config,
+    role_alias,
+)
+
+__all__ = [
+    "GatewayPlan",
+    "build_gateway_plan",
+    "build_launch_env",
+    "build_litellm_config",
+    "role_alias",
+]

package/core/runtime/gateway/__main__.py

@@ -0,0 +1,30 @@
+"""CLI: render the LiteLLM gateway config from models.yaml.
+
+    arka-py -m core.runtime.gateway [--local]            # print config.yaml
+    arka-py -m core.runtime.gateway [--local] --env KEY  # print launch env
+
+``--local`` renders the keyless local-only variant (every route → local
+Ollama) for subscription users with no ANTHROPIC_API_KEY.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from core.runtime.gateway.litellm_config import build_launch_env, render_config_yaml
+
+
+def main(argv: list[str]) -> int:
+    local_only = "--local" in argv
+    argv = [a for a in argv if a != "--local"]
+    if len(argv) >= 2 and argv[0] == "--env":
+        env = build_launch_env(master_key=argv[1])
+        for key, value in env.items():
+            print(f"{key}={value}")
+        return 0
+    sys.stdout.write(render_config_yaml(local_only=local_only))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/core/runtime/gateway/litellm_config.py

@@ -0,0 +1,205 @@
+"""Render a LiteLLM proxy config + Claude Code launch env from models.yaml.
+
+Claude Code exposes at most three subagent alias slots (``opus``,
+``sonnet``, ``haiku``) plus the interactive main-loop model. The seven
+Model Fabric roles therefore collapse onto those slots by tier:
+
+    quality tier (design/review/architecture/quality_gate)  -> opus slot
+    execution                                                -> haiku slot
+    mechanical                                               -> sonnet slot
+    strategy / orchestrator                                  -> main model
+
+Each slot maps to a LiteLLM route (``arka-<slot>``) that fans out to the
+role's real upstream — Anthropic-direct or local Ollama. The launch env
+points ``ANTHROPIC_DEFAULT_<TIER>_MODEL`` at those routes, so a subagent
+dispatched with ``model: haiku`` reaches Ollama while ``model: opus``
+reaches Anthropic — in the same session. The Anthropic API key never
+enters the client env; it stays server-side in the proxy's environment.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from core.runtime.model_router import ModelsConfig, load_config, resolve
+
+# The three Claude Code subagent alias slots we can address, plus a
+# sentinel for the interactive main-loop model (not an alias).
+_SLOTS = ("opus", "sonnet", "haiku")
+_MAIN = "main"
+
+# Which alias slot each work-role dispatches through. The orchestrator
+# uses this to choose the Task `model` param per role; the launch env
+# points each slot's default model at the matching gateway route.
+ROLE_ALIAS: dict[str, str] = {
+    "design": "opus",
+    "review": "opus",
+    "architecture": "opus",
+    "quality_gate": "opus",
+    "strategy": _MAIN,
+    "execution": "haiku",
+    "mechanical": "sonnet",
+}
+
+# Representative role whose configured upstream defines each slot's route.
+# All quality roles share the opus slot, so one of them stands in.
+_SLOT_ROLE: dict[str, str] = {
+    "opus": "quality_gate",
+    "sonnet": "mechanical",
+    "haiku": "execution",
+}
+
+# runtime-tier tokens -> real Anthropic model ids the proxy calls upstream.
+# Real ids (claude-fable-5, claude-*) pass straight through.
+_RUNTIME_TO_ANTHROPIC: dict[str, str] = {
+    "opus": "claude-opus-4-8",
+    "best": "claude-opus-4-8",
+    "sonnet": "claude-sonnet-5",
+    "default": "claude-sonnet-5",
+    "haiku": "claude-haiku-4-5-20251001",
+    "fast": "claude-haiku-4-5-20251001",
+}
+
+_DEFAULT_OLLAMA_BASE = "http://localhost:11434"
+_DEFAULT_PORT = 4000
+_ANTHROPIC_KEY_REF = "os.environ/ANTHROPIC_API_KEY"
+
+
+def role_alias(role: str) -> str:
+    """Which Claude Code alias slot a role dispatches through.
+
+    Unknown roles fall back to the opus slot — never the cheap tier —
+    consistent with the model-router's quality-first posture.
+    """
+    return ROLE_ALIAS.get(role, "opus")
+
+
+class Upstream(BaseModel):
+    """A concrete backend a slot routes to."""
+
+    kind: str  # "anthropic" | "ollama"
+    model_id: str
+    api_base: str | None = None
+
+
+class GatewayPlan(BaseModel):
+    """Resolved routing: one upstream per subagent alias slot.
+
+    The strategy role rides the interactive main-loop model (set by
+    ``--model`` / the operator's ``/model``), which reaches Anthropic via
+    the wildcard passthrough route — it is not a gateway-controlled slot.
+    """
+
+    slots: dict[str, Upstream]  # keyed by "opus"/"sonnet"/"haiku"
+    source: str
+
+
+def _upstream_for(provider: str, model: str, ollama_base: str) -> Upstream:
+    if provider == "ollama":
+        return Upstream(kind="ollama", model_id=model, api_base=ollama_base)
+    # runtime + anthropic both terminate at Anthropic-direct.
+    return Upstream(kind="anthropic", model_id=_RUNTIME_TO_ANTHROPIC.get(model, model))
+
+
+def _ollama_base(config: ModelsConfig) -> str:
+    return (config.providers.get("ollama", {}) or {}).get("base_url") or _DEFAULT_OLLAMA_BASE
+
+
+def build_gateway_plan(user_path=None, local_only: bool = False) -> GatewayPlan:
+    """Resolve every alias slot to its upstream from the operator's config.
+
+    ``local_only`` (for subscription users with no ANTHROPIC_API_KEY):
+    every slot that would hit Anthropic is redirected to the local Ollama
+    model instead, so the whole session runs keyless on local models. Raises
+    if the config has no Ollama route to fall back to.
+    """
+    config, source = load_config(user_path)
+    ollama_base = _ollama_base(config)
+    slots: dict[str, Upstream] = {}
+    for slot, role in _SLOT_ROLE.items():
+        r = resolve(role, user_path)
+        slots[slot] = _upstream_for(r.provider, r.model, ollama_base)
+    if local_only:
+        fallback = _local_fallback(slots)
+        if fallback is None:
+            raise ValueError(
+                "local-only gateway requested but models.yaml has no Ollama "
+                "route to fall back to — point at least one role at ollama/<model>"
+            )
+        slots = {
+            slot: (up if up.kind == "ollama" else fallback)
+            for slot, up in slots.items()
+        }
+    return GatewayPlan(slots=slots, source=source)
+
+
+def _local_fallback(slots: dict[str, Upstream]) -> Upstream | None:
+    """The local Ollama upstream to redirect Anthropic routes to (prefer
+    execution/haiku), or None when no slot is local."""
+    if slots.get("haiku", Upstream(kind="anthropic", model_id="")).kind == "ollama":
+        return slots["haiku"]
+    for up in slots.values():
+        if up.kind == "ollama":
+            return up
+    return None
+
+
+def _litellm_params(up: Upstream) -> dict:
+    if up.kind == "ollama":
+        # ollama_chat/ enables tool-use translation; api_base points at the
+        # local daemon (which forwards :cloud models to Ollama Cloud).
+        return {"model": f"ollama_chat/{up.model_id}", "api_base": up.api_base}
+    return {"model": up.model_id, "api_key": _ANTHROPIC_KEY_REF}
+
+
+def build_litellm_config(user_path=None, local_only: bool = False) -> dict:
+    """The LiteLLM proxy config.yaml structure (regenerated per launch).
+
+    One ``arka-<slot>`` route per alias slot, plus a wildcard route for the
+    interactive main-loop model and any raw model id. In the default mixed
+    mode the wildcard forwards to Anthropic (key via ``os.environ``, never
+    inlined); in ``local_only`` mode it forwards to the local Ollama model
+    so the whole session is keyless. The client authenticates with the
+    gateway master key either way.
+    """
+    plan = build_gateway_plan(user_path, local_only=local_only)
+    model_list = [
+        {"model_name": f"arka-{slot}", "litellm_params": _litellm_params(plan.slots[slot])}
+        for slot in _SLOTS
+    ]
+    if local_only:
+        wildcard = _litellm_params(_local_fallback(plan.slots))
+    else:
+        # LiteLLM matches explicit names first; this catches the main-loop
+        # model and any raw claude-* id and forwards it to Anthropic.
+        wildcard = {"model": "anthropic/*", "api_key": _ANTHROPIC_KEY_REF}
+    model_list.append({"model_name": "*", "litellm_params": wildcard})
+    return {
+        "model_list": model_list,
+        "litellm_settings": {"drop_params": True},
+        "general_settings": {"master_key": "os.environ/ARKA_GATEWAY_KEY"},
+    }
+
+
+def build_launch_env(master_key: str, port: int = _DEFAULT_PORT, user_path=None) -> dict[str, str]:
+    """Env vars Claude Code launches with so subagent aliases hit the gateway.
+
+    ``ANTHROPIC_API_KEY`` is deliberately absent — it belongs to the proxy,
+    not the client. The client presents only the gateway master key.
+    """
+    return {
+        "ANTHROPIC_BASE_URL": f"http://127.0.0.1:{port}",
+        "ANTHROPIC_AUTH_TOKEN": master_key,
+        "ANTHROPIC_DEFAULT_OPUS_MODEL": "arka-opus",
+        "ANTHROPIC_DEFAULT_SONNET_MODEL": "arka-sonnet",
+        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "arka-haiku",
+    }
+
+
+def render_config_yaml(user_path=None, local_only: bool = False) -> str:
+    """The LiteLLM config as a YAML string (what arka-claude writes to disk)."""
+    import yaml
+
+    return yaml.safe_dump(
+        build_litellm_config(user_path, local_only=local_only), sort_keys=False
+    )

package/core/runtime/model_routing_check.py

@@ -0,0 +1,71 @@
+"""Model-routing telemetry — answer "is the Model Fabric actually used?".
+
+The gateway makes per-role routing real; this module makes it *observable*.
+It reports the resolved route table, whether the LiteLLM proxy is live, and
+a best-effort count of which ``arka-<slot>`` routes actually served traffic
+(parsed from the proxy log). Everything degrades to a plain summary when the
+gateway is off, so ``/arka status`` always has a truthful line to show.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from core.runtime.gateway.litellm_config import build_gateway_plan
+
+_GATEWAY_LOG = Path.home() / ".arkaos" / "gateway" / "litellm.log"
+_DEFAULT_PORT = 4000
+_ROUTE_RE = re.compile(r"\barka-(opus|sonnet|haiku)\b")
+
+
+def resolved_routes(user_path=None) -> dict[str, str]:
+    """Alias slot -> human 'kind:model' the gateway would route it to."""
+    plan = build_gateway_plan(user_path)
+    return {
+        slot: f"{up.kind}:{up.model_id}" for slot, up in plan.slots.items()
+    }
+
+
+def gateway_healthy(port: int = _DEFAULT_PORT, timeout: float = 1.0) -> bool:
+    """True when the LiteLLM proxy answers its liveness probe."""
+    import urllib.error
+    import urllib.request
+
+    try:
+        with urllib.request.urlopen(
+            f"http://127.0.0.1:{port}/health/liveliness", timeout=timeout
+        ) as resp:
+            return resp.status == 200
+    except (urllib.error.URLError, OSError, ValueError):
+        return False
+
+
+def served_counts(log_path: Path | None = None) -> dict[str, int]:
+    """Best-effort count of arka-<slot> routes seen in the proxy log."""
+    path = log_path or _GATEWAY_LOG
+    counts: dict[str, int] = {}
+    try:
+        text = path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return counts
+    for match in _ROUTE_RE.finditer(text):
+        slot = match.group(1)
+        counts[slot] = counts.get(slot, 0) + 1
+    return counts
+
+
+def status_summary(port: int = _DEFAULT_PORT, user_path=None, log_path=None) -> str:
+    """One compact block for /arka status — reality, not intent."""
+    live = gateway_healthy(port)
+    routes = resolved_routes(user_path)
+    header = (
+        f"Gateway: {'LIVE' if live else 'off'} (:{port}) — per-role model routing "
+        f"{'active' if live else 'not active; honour-system context injection only'}"
+    )
+    lines = [f"  {slot} → {target}" for slot, target in sorted(routes.items())]
+    counts = served_counts(log_path)
+    if counts:
+        served = " ".join(f"{slot}={n}" for slot, n in sorted(counts.items()))
+        lines.append(f"  served: {served}")
+    return header + "\n" + "\n".join(lines)

package/core/runtime/model_routing_context.py

@@ -57,7 +57,7 @@ def routing_summary() -> str:
 
 
 def routing_directive() -> str:
-    """Full SessionStart block: the config plus how to honor it.
+    """Full SessionStart block: the config plus how to honour it.
 
     Returns '' when the config cannot be read, so the hook can skip the
     block entirely rather than inject an empty directive.
@@ -65,6 +65,26 @@ def routing_directive() -> str:
     summary = routing_summary()
     if not summary:
         return ""
+
+    # When the LiteLLM gateway is live, the alias a subagent is dispatched
+    # with is what physically selects the upstream (opus→Anthropic,
+    # haiku→Ollama for execution), so the directive names the concrete
+    # alias per role. Off, it stays advisory context injection.
+    gateway_line = ""
+    try:
+        from core.runtime.model_routing_check import gateway_healthy
+
+        if gateway_healthy():
+            gateway_line = (
+                "\nGateway LIVE: the Task model param physically routes the "
+                "upstream. Dispatch execution with model=haiku (→ Ollama), "
+                "mechanical with model=sonnet, and design/review/architecture/"
+                "quality_gate with model=opus (→ Anthropic). strategy is the "
+                "main loop model."
+            )
+    except Exception:
+        gateway_line = ""
+
     # 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.
@@ -79,4 +99,5 @@ def routing_directive() -> str:
         "the agent YAML default. Quality roles never downgrade below the "
         "configured model (excellence-mandate). Genuinely mechanical "
         "dispatches (commit messages, formatting) use the mechanical role."
+        f"{gateway_line}"
     )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.3.5",
+  "version": "4.3.6",
   "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.5"
+version = "4.3.6"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}
@@ -45,6 +45,12 @@ ingest = [
     "beautifulsoup4>=4.12.0",
     "requests>=2.31.0",
 ]
+gateway = [
+    # LiteLLM proxy: the Anthropic-compatible fan-out endpoint that makes
+    # per-role mixed-provider routing (execution→Ollama, quality→Anthropic)
+    # take effect. Only needed when launching with ARKA_GATEWAY=1.
+    "litellm[proxy]>=1.50.0",
+]
 dev = [
     "pytest>=8.0",
     "pytest-cov>=5.0",

package/scripts/gateway-ensure.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ArkaOS — Model-routing gateway ensure
+#
+# Renders the LiteLLM proxy config from ~/.arkaos/models.yaml, ensures the
+# proxy is running, and writes the Claude Code launch env to a file the
+# caller sources. Best-effort: any failure returns non-zero so arka-claude
+# degrades to a plain `claude` launch — a broken gateway never blocks work.
+#
+# Contract:
+#   in : $ARKA_PY (interpreter), $ARKAOS_ROOT (repo), env ARKA_GATEWAY_PORT
+#   out: writes $ARKAOS_HOME/gateway/launch.env on success; exit 0
+#        exit non-zero on any failure (caller must degrade)
+# ============================================================================
+set -uo pipefail
+
+ARKAOS_HOME="${ARKAOS_HOME:-$HOME/.arkaos}"
+PORT="${ARKA_GATEWAY_PORT:-4000}"
+GW_DIR="$ARKAOS_HOME/gateway"
+CONFIG="$GW_DIR/config.yaml"
+ENV_FILE="$GW_DIR/launch.env"
+LOG="$GW_DIR/litellm.log"
+LITELLM="$ARKAOS_HOME/venv/bin/litellm"
+
+warn() { printf '  \033[1;33m⚠  gateway: %s\033[0m\n' "$1" >&2; }
+
+# ─── Preconditions ────────────────────────────────────────────────────────
+[ -n "${ARKA_PY:-}" ] || { warn "ARKA_PY unset"; exit 1; }
+[ -n "${ARKAOS_ROOT:-}" ] || { warn "ARKAOS_ROOT unset"; exit 1; }
+if [ ! -x "$LITELLM" ]; then
+  warn "LiteLLM not installed in the ArkaOS venv — run: ~/.arkaos/venv/bin/pip install 'litellm[proxy]'"
+  exit 1
+fi
+
+# Mode: with an API key -> mixed (quality→Anthropic, execution→Ollama).
+# Without one (subscription users) -> local-only: every route runs on the
+# local Ollama model, keyless. The main arka-claude keeps the subscription.
+LOCAL_FLAG=""
+if [ -z "${ANTHROPIC_API_KEY:-}" ]; then
+  LOCAL_FLAG="--local"
+  warn "no ANTHROPIC_API_KEY — local-only mode: the whole session runs on the local Ollama model (use plain arka-claude for subscription/quality work)"
+fi
+
+mkdir -p "$GW_DIR"
+health() { curl -fsS -m 2 "http://127.0.0.1:$PORT/health/liveliness" >/dev/null 2>&1; }
+
+# ─── Reuse a healthy proxy WITHOUT rotating its key ───────────────────────
+# The running proxy validates the ARKA_GATEWAY_KEY it started with; the
+# client reads that same value from the existing launch.env. Minting a new
+# key on reuse would 401 every request, so the reuse path touches neither
+# the key nor launch.env. Changing models.yaml needs ARKA_GATEWAY_RESTART=1.
+if [ "${ARKA_GATEWAY_RESTART:-0}" != "1" ] && health && [ -f "$ENV_FILE" ]; then
+  exit 0
+fi
+if health; then                      # RESTART path — old proxy must go
+  pkill -f "litellm .*--port $PORT" 2>/dev/null || true
+  sleep 1
+fi
+
+# ─── Render config from models.yaml ───────────────────────────────────────
+# shellcheck disable=SC2086  # LOCAL_FLAG is a single controlled token
+if ! PYTHONPATH="$ARKAOS_ROOT" "$ARKA_PY" -m core.runtime.gateway $LOCAL_FLAG > "$CONFIG" 2>/dev/null; then
+  if [ -n "$LOCAL_FLAG" ]; then
+    warn "could not render gateway config — local-only needs at least one ollama route in models.yaml"
+  else
+    warn "could not render gateway config from models.yaml"
+  fi
+  exit 1
+fi
+
+# ─── Fresh master key + client launch env (created for THIS proxy) ────────
+MASTER_KEY="$("$ARKA_PY" -c 'import secrets; print("sk-arka-" + secrets.token_hex(16))')"
+export ARKA_GATEWAY_KEY="$MASTER_KEY"
+
+if ! PYTHONPATH="$ARKAOS_ROOT" "$ARKA_PY" -m core.runtime.gateway --env "$MASTER_KEY" > "$ENV_FILE" 2>/dev/null; then
+  warn "could not render launch env"
+  exit 1
+fi
+# The proxy reads ANTHROPIC_API_KEY + ARKA_GATEWAY_KEY from its own env.
+printf 'ARKA_GATEWAY_KEY=%s\n' "$MASTER_KEY" >> "$ENV_FILE"
+chmod 600 "$ENV_FILE" 2>/dev/null || true   # bearer token — owner-only
+
+# Start in the background; ARKA_GATEWAY_KEY + ANTHROPIC_API_KEY inherited.
+( ARKA_GATEWAY_KEY="$MASTER_KEY" nohup "$LITELLM" --config "$CONFIG" --port "$PORT" \
+    >> "$LOG" 2>&1 & disown 2>/dev/null || true )
+
+# ─── Health-wait (bounded) ────────────────────────────────────────────────
+for _ in $(seq 1 30); do
+  if health; then exit 0; fi
+  sleep 1
+done
+warn "gateway did not become healthy within 30s (see $LOG)"
+exit 1