arkaos 4.1.1 → 4.3.0

package/dashboard/app/pages/models.vue

@@ -0,0 +1,404 @@
+<script setup lang="ts">
+// Model Fabric (PR-C) — who runs what, what this machine offers, where
+// tokens flow. Backed by /api/models, /api/models/role, /api/models/usage.
+
+interface ResolvedRole {
+  role: string
+  provider: string
+  model: string
+  effort: string
+  source: string
+}
+
+interface OllamaModel {
+  name: string
+  size_gb: number
+  family: string
+  parameter_size: string
+}
+
+interface ModelsOverview {
+  source: string
+  config_path: string
+  roles: ResolvedRole[]
+  providers: Record<string, { type: string }>
+  aliases: Record<string, Record<string, string>>
+  fusion: { judge: Record<string, string>, panel: Array<Record<string, string>> }
+  ollama: { installed: boolean, running: boolean, host: string, models: OllamaModel[] }
+  keys: { openrouter: boolean, anthropic: boolean }
+}
+
+interface BreakdownRow {
+  total_cost_usd: number | null
+  total_tokens_in: number
+  total_tokens_out: number
+  call_count: number
+}
+
+interface UsageSummary {
+  period: string
+  call_count: number
+  total_cost_usd: number | null
+  total_tokens_in: number
+  total_tokens_out: number
+  total_cached_tokens: number
+  by_model: Record<string, BreakdownRow>
+  by_provider: Record<string, BreakdownRow>
+}
+
+type Period = 'today' | 'week' | 'month' | 'all'
+
+const { fetchApi, apiBase } = useApi()
+const toast = useToast()
+
+const {
+  data: overview,
+  status,
+  error,
+  refresh,
+} = fetchApi<ModelsOverview>('/api/models')
+
+const period = ref<Period>('week')
+const periodOptions: { label: string, value: Period }[] = [
+  { label: 'Today', value: 'today' },
+  { label: '7 days', value: 'week' },
+  { label: '30 days', value: 'month' },
+  { label: 'All time', value: 'all' },
+]
+const { data: usage, refresh: refreshUsage } = fetchApi<UsageSummary>(
+  '/api/models/usage',
+  { query: computed(() => ({ period: period.value })) },
+)
+watch(period, () => refreshUsage())
+
+// ─── Provider lanes (signature element: live availability strip) ────────
+
+const QUALITY_ROLES = new Set(['design', 'review', 'architecture', 'strategy', 'quality_gate'])
+
+const laneStyles: Record<string, { badge: string, dot: string }> = {
+  runtime: { badge: 'text-primary bg-primary/10', dot: 'bg-primary' },
+  ollama: { badge: 'text-amber-600 dark:text-amber-400 bg-amber-500/10', dot: 'bg-amber-500' },
+  openrouter: { badge: 'text-violet-600 dark:text-violet-400 bg-violet-500/10', dot: 'bg-violet-500' },
+  anthropic: { badge: 'text-sky-600 dark:text-sky-400 bg-sky-500/10', dot: 'bg-sky-500' },
+}
+
+function laneStyle(provider: string) {
+  return laneStyles[provider] ?? { badge: 'text-muted bg-muted/10', dot: 'bg-muted' }
+}
+
+interface Lane {
+  id: string
+  label: string
+  live: boolean
+  detail: string
+}
+
+const lanes = computed<Lane[]>(() => {
+  const o = overview.value
+  if (!o) return []
+  const ollama = o.ollama ?? { installed: false, running: false, models: [] }
+  const keys = o.keys ?? { openrouter: false, anthropic: false }
+  const ollamaDetail = ollama.running
+    ? `${(ollama.models ?? []).length} local models`
+    : ollama.installed ? 'installed, not running' : 'not installed'
+  return [
+    { id: 'runtime', label: 'Runtime', live: true, detail: 'active CLI session' },
+    { id: 'ollama', label: 'Ollama', live: ollama.running, detail: ollamaDetail },
+    { id: 'openrouter', label: 'OpenRouter', live: keys.openrouter, detail: keys.openrouter ? 'key configured' : 'no key' },
+    { id: 'anthropic', label: 'Anthropic', live: keys.anthropic, detail: keys.anthropic ? 'key configured' : 'no key' },
+  ]
+})
+
+// ─── Inline role re-routing ──────────────────────────────────────────────
+
+const editingRole = ref<string | null>(null)
+const editTarget = ref('')
+const saving = ref(false)
+
+const targetOptions = computed(() => {
+  const o = overview.value
+  if (!o) return []
+  const options: { label: string, value: string }[] = []
+  for (const alias of ['best', 'default', 'fast']) {
+    options.push({ label: `runtime / ${alias}`, value: `runtime/${alias}` })
+  }
+  for (const m of o.ollama?.models ?? []) {
+    options.push({ label: `ollama / ${m.name}`, value: `ollama/${m.name}` })
+  }
+  if (o.keys?.anthropic) {
+    for (const alias of ['best', 'default', 'fast']) {
+      options.push({ label: `anthropic / ${alias}`, value: `anthropic/${alias}` })
+    }
+  }
+  if (o.keys?.openrouter) {
+    options.push({ label: 'openrouter / (type model id)', value: 'openrouter/' })
+  }
+  return options
+})
+
+function startEdit(row: ResolvedRole) {
+  editingRole.value = row.role
+  editTarget.value = `${row.provider}/${row.model}`
+}
+
+async function saveEdit(role: string) {
+  if (!editTarget.value.includes('/')) {
+    toast.add({ title: 'Target must be provider/model', color: 'error' })
+    return
+  }
+  saving.value = true
+  try {
+    await $fetch(`${apiBase.value}/api/models/role`, {
+      method: 'POST',
+      body: { role, target: editTarget.value },
+    })
+    toast.add({ title: `${role} re-routed`, description: editTarget.value, color: 'success', icon: 'i-lucide-route' })
+    editingRole.value = null
+    await refresh()
+  } catch (err) {
+    toast.add({
+      title: 'Re-route failed',
+      description: err instanceof Error ? err.message : 'unknown error',
+      color: 'error',
+    })
+  } finally {
+    saving.value = false
+  }
+}
+
+async function useForMechanical(model: OllamaModel) {
+  editTarget.value = `ollama/${model.name}`
+  await saveEdit('mechanical')
+}
+
+// ─── Usage bars ──────────────────────────────────────────────────────────
+
+const usageRows = computed<Array<[string, BreakdownRow]>>(() =>
+  Object.entries(usage.value?.by_model ?? {}).sort(
+    (a, b) => (b[1].total_tokens_in + b[1].total_tokens_out) - (a[1].total_tokens_in + a[1].total_tokens_out),
+  ).slice(0, 10),
+)
+
+const maxUsageTokens = computed(() => {
+  const max = usageRows.value.reduce(
+    (acc, [, r]) => Math.max(acc, r.total_tokens_in + r.total_tokens_out), 0,
+  )
+  return max > 0 ? max : 1
+})
+
+function formatTokens(value: number): string {
+  if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`
+  if (value >= 1_000) return `${(value / 1_000).toFixed(1)}K`
+  return value.toString()
+}
+
+function formatCost(value: number | null): string {
+  if (value === null || value === undefined) return 'n/a'
+  if (value === 0) return '$0'
+  if (value < 0.01) return `$${value.toFixed(4)}`
+  return `$${value.toFixed(2)}`
+}
+</script>
+
+<template>
+  <UDashboardPanel id="models">
+    <template #header>
+      <UDashboardNavbar title="Models">
+        <template #right>
+          <UButton
+            label="Refresh"
+            variant="ghost"
+            icon="i-lucide-refresh-cw"
+            size="sm"
+            @click="() => { refresh(); refreshUsage() }"
+          />
+        </template>
+      </UDashboardNavbar>
+    </template>
+
+    <template #body>
+      <DashboardState
+        :status="status"
+        :error="error"
+        loading-label="Loading model fabric"
+        :on-retry="() => refresh()"
+      >
+        <div class="space-y-6">
+          <!-- Provider lanes: live availability strip -->
+          <UCard>
+            <div class="grid grid-cols-2 md:grid-cols-4 gap-4">
+              <div
+                v-for="lane in lanes"
+                :key="lane.id"
+                class="flex items-start gap-3"
+              >
+                <span class="relative flex h-2.5 w-2.5 mt-1.5">
+                  <span
+                    v-if="lane.live"
+                    class="animate-ping absolute inline-flex h-full w-full rounded-full opacity-60 motion-reduce:hidden"
+                    :class="laneStyle(lane.id).dot"
+                  />
+                  <span
+                    class="relative inline-flex rounded-full h-2.5 w-2.5"
+                    :class="lane.live ? laneStyle(lane.id).dot : 'bg-muted/40'"
+                  />
+                </span>
+                <div>
+                  <p class="text-sm font-semibold">{{ lane.label }}</p>
+                  <p class="text-xs text-muted">{{ lane.detail }}</p>
+                </div>
+              </div>
+            </div>
+          </UCard>
+
+          <!-- Role routing -->
+          <UCard>
+            <template #header>
+              <div class="flex items-center justify-between">
+                <p class="text-xs font-semibold text-muted uppercase tracking-wider">
+                  Role routing
+                </p>
+                <p class="text-xs text-muted font-mono hidden md:block">{{ overview?.config_path }}</p>
+              </div>
+            </template>
+            <div class="divide-y divide-default">
+              <div
+                v-for="row in overview?.roles ?? []"
+                :key="row.role"
+                class="flex items-center gap-3 py-2.5"
+              >
+                <UIcon
+                  :name="QUALITY_ROLES.has(row.role) ? 'i-lucide-gem' : 'i-lucide-cog'"
+                  class="size-4 shrink-0"
+                  :class="QUALITY_ROLES.has(row.role) ? 'text-primary' : 'text-muted'"
+                />
+                <span class="w-32 shrink-0 text-sm font-medium">{{ row.role }}</span>
+                <template v-if="editingRole === row.role">
+                  <UInputMenu
+                    v-model="editTarget"
+                    :items="targetOptions"
+                    value-key="value"
+                    create-item
+                    size="sm"
+                    class="flex-1 max-w-xs"
+                    placeholder="provider/model"
+                    @create="(item: string) => { editTarget = item }"
+                  />
+                  <UButton size="xs" label="Save" :loading="saving" @click="saveEdit(row.role)" />
+                  <UButton size="xs" variant="ghost" label="Cancel" @click="editingRole = null" />
+                </template>
+                <template v-else>
+                  <span
+                    class="inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium"
+                    :class="laneStyle(row.provider).badge"
+                  >
+                    {{ row.provider }}
+                  </span>
+                  <span class="text-sm font-mono truncate">
+                    {{ row.model || '(unset)' }}
+                  </span>
+                  <UBadge variant="subtle" size="sm" color="neutral">{{ row.effort }}</UBadge>
+                  <UButton
+                    icon="i-lucide-pencil"
+                    variant="ghost"
+                    size="xs"
+                    class="ml-auto"
+                    :aria-label="`Edit ${row.role} routing`"
+                    @click="startEdit(row)"
+                  />
+                </template>
+              </div>
+            </div>
+          </UCard>
+
+          <div class="grid grid-cols-1 lg:grid-cols-2 gap-6">
+            <!-- Local Ollama models -->
+            <UCard>
+              <template #header>
+                <p class="text-xs font-semibold text-muted uppercase tracking-wider">
+                  Local models (Ollama)
+                </p>
+              </template>
+              <div v-if="overview?.ollama?.running && (overview.ollama?.models ?? []).length" class="divide-y divide-default">
+                <div
+                  v-for="m in (overview.ollama?.models ?? [])"
+                  :key="m.name"
+                  class="flex items-center gap-3 py-2"
+                >
+                  <UIcon name="i-lucide-hard-drive" class="size-4 text-amber-500 shrink-0" />
+                  <div class="min-w-0 flex-1">
+                    <p class="text-sm font-mono truncate">{{ m.name }}</p>
+                    <p class="text-xs text-muted">
+                      {{ m.family || 'unknown family' }}
+                      <template v-if="m.parameter_size"> · {{ m.parameter_size }}</template>
+                      <template v-if="m.size_gb"> · {{ m.size_gb }} GB</template>
+                      <template v-if="!m.size_gb"> · cloud-proxied</template>
+                    </p>
+                  </div>
+                  <UButton
+                    size="xs"
+                    variant="soft"
+                    label="Use for mechanical"
+                    :loading="saving"
+                    @click="useForMechanical(m)"
+                  />
+                </div>
+              </div>
+              <div v-else-if="overview?.ollama?.installed" class="py-6 text-center">
+                <p class="text-sm text-muted">Ollama is installed but not running.</p>
+                <p class="text-xs text-muted mt-1 font-mono">ollama serve</p>
+              </div>
+              <div v-else class="py-6 text-center">
+                <p class="text-sm text-muted">No local models yet.</p>
+                <p class="text-xs text-muted mt-1">
+                  Install Ollama to run free local models for mechanical work and fusion panels.
+                </p>
+              </div>
+            </UCard>
+
+            <!-- Usage by model -->
+            <UCard>
+              <template #header>
+                <div class="flex items-center justify-between">
+                  <p class="text-xs font-semibold text-muted uppercase tracking-wider">
+                    Usage by model
+                  </p>
+                  <USelect v-model="period" :items="periodOptions" size="xs" class="min-w-24" aria-label="Usage period" />
+                </div>
+              </template>
+              <div v-if="usageRows.length" class="space-y-3">
+                <div class="flex items-baseline justify-between">
+                  <p class="text-sm">
+                    <span class="font-semibold">{{ usage?.call_count ?? 0 }}</span>
+                    <span class="text-muted"> calls · </span>
+                    <span class="font-semibold">{{ formatTokens((usage?.total_tokens_in ?? 0) + (usage?.total_tokens_out ?? 0)) }}</span>
+                    <span class="text-muted"> tokens</span>
+                  </p>
+                  <p class="text-sm font-semibold">{{ formatCost(usage?.total_cost_usd ?? null) }}</p>
+                </div>
+                <div v-for="[name, row] in usageRows" :key="name" class="space-y-1">
+                  <div class="flex items-center justify-between text-xs">
+                    <span class="font-mono truncate">{{ name || '(unattributed)' }}</span>
+                    <span class="text-muted shrink-0 ml-2">
+                      {{ formatTokens(row.total_tokens_in + row.total_tokens_out) }} · {{ row.call_count }} calls
+                    </span>
+                  </div>
+                  <div class="h-1.5 rounded-full bg-muted/20 overflow-hidden">
+                    <div
+                      class="h-full rounded-full bg-primary"
+                      :style="{ width: `${Math.max(2, ((row.total_tokens_in + row.total_tokens_out) / maxUsageTokens) * 100)}%` }"
+                    />
+                  </div>
+                </div>
+              </div>
+              <div v-else class="py-6 text-center">
+                <p class="text-sm text-muted">No usage recorded for this period.</p>
+                <p class="text-xs text-muted mt-1">Calls made through the Model Fabric land here automatically.</p>
+              </div>
+            </UCard>
+          </div>
+        </div>
+      </DashboardState>
+    </template>
+  </UDashboardPanel>
+</template>

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.3.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.3.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/dashboard-api.py

@@ -864,6 +864,85 @@ def commands(dept: Optional[str] = Query(None), q: Optional[str] = Query(None)):
     return {"commands": data, "total": len(data)}
 
 
+@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.ollama_discovery import discover
+
+    config, source = load_config()
+    keys_path = Path.home() / ".arkaos" / "keys.json"
+    try:
+        keys = json.loads(keys_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        keys = {}
+    return {
+        "source": source,
+        "config_path": str(USER_CONFIG_PATH),
+        "roles": [item.model_dump() 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(),
+        "ollama": discover().to_dict(),
+        "keys": {
+            "openrouter": bool(
+                os.environ.get("OPENROUTER_API_KEY")
+                or keys.get("OPENROUTER_API_KEY")
+            ),
+            "anthropic": bool(os.environ.get("ANTHROPIC_API_KEY")),
+        },
+    }
+
+
+@app.post("/api/models/role")
+async def models_set_role(request: Request):
+    """Re-route a role: {role, target: 'provider/model', effort?}."""
+    from core.runtime.model_router import set_role
+
+    body = await request.json()
+    role = str(body.get("role", "")).strip()
+    target = str(body.get("target", "")).strip()
+    effort = body.get("effort") or None
+    if not role or not target:
+        return JSONResponse(
+            {"error": "role and target (provider/model) are required"},
+            status_code=422,
+        )
+    try:
+        item = set_role(role, target, effort=effort)
+    except ValueError as exc:
+        return JSONResponse({"error": str(exc)}, status_code=422)
+    return item.model_dump()
+
+
+@app.get("/api/models/usage")
+def models_usage(period: str = "today"):
+    """Per-model/provider/category token + cost aggregation."""
+    from core.runtime.llm_cost_telemetry import VALID_PERIODS, summarise
+
+    if period not in VALID_PERIODS:
+        return JSONResponse(
+            {"error": f"period must be one of {list(VALID_PERIODS)}"},
+            status_code=422,
+        )
+    summary = summarise(period=period)
+    return {
+        "period": summary.period,
+        "call_count": summary.call_count,
+        "total_cost_usd": summary.total_cost_usd,
+        "total_tokens_in": summary.total_tokens_in,
+        "total_tokens_out": summary.total_tokens_out,
+        "total_cached_tokens": summary.total_cached_tokens,
+        "cache_hit_rate": summary.cache_hit_rate,
+        "by_model": summary.by_model,
+        "by_provider": summary.by_provider,
+        "by_category": summary.by_category,
+    }
+
+
 @app.get("/api/budget")
 def budget_all():
     mgr = _get_budget_manager()

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