fix: auto-load ~/.praisonai/.env on aiui run so env: tokens resolve (fixes #286)

Channels configured with env:VAR token references silently resolved to
empty strings when the dashboard was started without the shell exporting
the tokens, so bots showed 'Connected' but never replied. aiui run now
loads the standard PraisonAI .env files (~/.praisonai/.env, then ./.env)
into the process environment at startup, matching the PraisonAI CLI
convention. Existing process vars are never overridden and parsing is
dependency-free (no python-dotenv).

Co-Authored-By: Claude Opus 4.8 <[email protected]>

.github/automation.meta.json

@@ -3,7 +3,7 @@
   "stack": "claude",
   "profile": "sdk",
   "mode": "hub",
-  "hubRef": "v1.1.6",
-  "templateVersion": "1.1.6",
+  "hubRef": "v1.1.8",
+  "templateVersion": "1.1.7",
   "installedAt": "2026-09-07T10:02:11Z"
 }

.github/scripts/gate-config.js

@@ -4,6 +4,10 @@
 
 module.exports = {
   repoFullName: 'MervinPraison/PraisonAIUI',
+  gitUser: 'MervinPraison',
+  gitEmail: '[email protected]',
+  triggerLogins: ['MervinPraison', 'github-actions[bot]'],
+  allowedTriageBots: ['praisonai-triage-agent[bot]'],
   productPathPrefixes: ['src/praisonaiui/', 'src/frontend/', 'tests/'],
   sensitivePathPatterns: [
     /^\.github\/workflows\//,

.github/workflows/auto-pr-comment.yml

@@ -27,7 +27,7 @@ jobs:
     permissions:
       issues: write
       pull-requests: write
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].6
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].8
     secrets: inherit
     with:
-      hub_ref: v1.1.6
+      hub_ref: v1.1.8

.github/workflows/bot-pr-recovery.yml

@@ -16,8 +16,8 @@ permissions:
 
 jobs:
   recover:
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].6
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].8
     secrets: inherit
     with:
-      hub_ref: v1.1.6
+      hub_ref: v1.1.8
       pr_number: ${{ github.event.inputs.pr_number || '' }}

.github/workflows/ci-failure-claude.yml

@@ -25,8 +25,8 @@ permissions:
 
 jobs:
   detect-and-trigger:
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].6
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].8
     secrets: inherit
     with:
-      hub_ref: v1.1.6
+      hub_ref: v1.1.8
       pr_number: ${{ github.event.inputs.pr_number || '' }}

.github/workflows/claude-merge-gate.yml

@@ -43,9 +43,9 @@ jobs:
       id-token: write
     steps:
       - uses: actions/checkout@v4
-      - uses: MervinPraison/github-automation-template/.github/actions/[email protected].6
+      - uses: MervinPraison/github-automation-template/.github/actions/[email protected].8
         with:
-          hub_ref: v1.1.6
+          hub_ref: v1.1.8
       - name: Generate GitHub App token
         id: app-token
         uses: actions/create-github-app-token@v1
@@ -87,9 +87,9 @@ jobs:
       issues: write
       actions: read
       id-token: write
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].6
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].8
     secrets: inherit
     with:
-      hub_ref: v1.1.6
+      hub_ref: v1.1.8
       pr_number: ${{ github.event.inputs.pr_number || github.event.client_payload.pr_number || '' }}
       merge_method: ${{ github.event.inputs.merge_method || 'merge' }}

.github/workflows/claude.yml

@@ -18,7 +18,7 @@ jobs:
       issues: write
       actions: read
       id-token: write
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].6
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].8
     secrets: inherit
     with:
-      hub_ref: v1.1.6
+      hub_ref: v1.1.8

.github/workflows/merge-conflict-claude.yml

@@ -25,9 +25,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: MervinPraison/github-automation-template/.github/actions/[email protected].6
+      - uses: MervinPraison/github-automation-template/.github/actions/[email protected].8
         with:
-          hub_ref: v1.1.6
+          hub_ref: v1.1.8
       - name: Detect conflicting PRs and trigger Claude
         uses: actions/github-script@v7
         with:

.github/workflows/pipeline-status-sync.yml

@@ -13,7 +13,7 @@ permissions:
 
 jobs:
   sync:
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].6
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].8
     secrets: inherit
     with:
-      hub_ref: v1.1.6
+      hub_ref: v1.1.8

examples/python/voice-agent/integrations/voice/doctor.py

@@ -17,6 +17,25 @@ def _tcp_open(host: str, port: int, timeout: float = 2.0) -> bool:
         return False
 
 
+_MCP_PROBE_TIMEOUT_SEC = 2.0
+
+
+def _is_slow_mcp_probe(detail: str) -> bool:
+    lowered = detail.lower()
+    return any(token in lowered for token in ("timed out", "timeout", "temporarily unavailable"))
+
+
+def _mcp_servers_probe(app_port: int) -> tuple[str, str]:
+    """Probe MCP list endpoint; slow stdio connect must not fail the whole doctor run."""
+    status, detail = _http_status(
+        f"http://127.0.0.1:{app_port}/api/mcp/servers",
+        timeout=_MCP_PROBE_TIMEOUT_SEC,
+    )
+    if status == "fail" and _is_slow_mcp_probe(detail):
+        return "warn", detail
+    return status, detail
+
+
 def _http_status(url: str, timeout: float = 5.0) -> tuple[str, str]:
     try:
         req = Request(url, headers={"User-Agent": "praisonai-voice-doctor"})
@@ -64,7 +83,7 @@ def run_voice_doctor(*, app_port: int = 8001, sidecar_port: int = 8002) -> dict[
         checks.append({"name": "Speech Engine config", "status": status, "detail": detail})
         status, detail = _http_status(f"http://127.0.0.1:{app_port}/api/voice/realtime/config")
         checks.append({"name": "GPT Realtime config", "status": status, "detail": detail})
-        status, detail = _http_status(f"http://127.0.0.1:{app_port}/api/mcp/servers")
+        status, detail = _mcp_servers_probe(app_port)
         checks.append({"name": "MCP servers API", "status": status, "detail": detail})
     else:
         checks.append(

src/praisonaiui/cli.py

@@ -44,6 +44,43 @@ def _icon(symbol: str, fallback: str) -> str:
     return symbol if _supports_unicode() else fallback
 
 
+def _load_env_files() -> int:
+    """Load environment variables from the standard PraisonAI ``.env`` files.
+
+    Mirrors the PraisonAI CLI convention so ``env:VAR`` references (e.g. in
+    Channels config) resolve when the server was started without the shell
+    exporting the tokens. Reads ``~/.praisonai/.env`` first, then a ``.env`` in
+    the current working directory. Existing process env vars are never
+    overridden, and parsing is intentionally dependency-free (no python-dotenv).
+
+    Returns the number of variables newly set into ``os.environ``.
+    """
+    import os
+
+    loaded = 0
+    for env_path in (Path.home() / ".praisonai" / ".env", Path.cwd() / ".env"):
+        try:
+            if not env_path.is_file():
+                continue
+            for line in env_path.read_text(encoding="utf-8").splitlines():
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                if line.startswith("export "):
+                    line = line[len("export "):]
+                key, value = line.split("=", 1)
+                key = key.strip()
+                value = value.strip().strip('"').strip("'")
+                if key and key not in os.environ:
+                    os.environ[key] = value
+                    loaded += 1
+        except Exception:
+            # Never let env loading break startup — resolution falls back to
+            # the existing process environment.
+            continue
+    return loaded
+
+
 app = typer.Typer(
     name="aiui",
     help="PraisonAIUI - YAML-driven website generator",
@@ -1380,6 +1417,17 @@ def run(
         console.print(f"[red]Error:[/red] App file not found: {app_file}")
         raise typer.Exit(code=1)
 
+    # Auto-load standard PraisonAI env files so `env:VAR` references (e.g. in
+    # Channels config) resolve even when the shell did not export the tokens.
+    # This matches the PraisonAI CLI convention and fixes the "Connected but
+    # bot never replies" class of issues caused by empty env-resolved tokens.
+    _loaded = _load_env_files()
+    if _loaded:
+        console.print(
+            f"[green]{_icon('✓', 'OK')}[/green] Loaded {_loaded} environment "
+            f"variable(s) from PraisonAI config"
+        )
+
     is_yaml = app_file.suffix in (".yaml", ".yml")
 
     if is_yaml:

tests/unit/test_env_loader.py

@@ -0,0 +1,68 @@
+"""Unit tests for `_load_env_files` — auto-loading PraisonAI `.env` files.
+
+Regression coverage for issue #286: `env:VAR` channel token references
+resolved to empty strings because `aiui run` never loaded the standard
+`~/.praisonai/.env` file, so bots showed "Connected" but never replied.
+"""
+
+import os
+
+from praisonaiui.cli import _load_env_files
+
+
+def _write_env(path, body):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(body, encoding="utf-8")
+
+
+def test_loads_home_praisonai_env(tmp_path, monkeypatch):
+    """Variables in ~/.praisonai/.env are loaded into the process env."""
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("TELEGRAM_BOT_TOKEN", raising=False)
+
+    _write_env(tmp_path / ".praisonai" / ".env", 'TELEGRAM_BOT_TOKEN="123:AAtoken"\n')
+
+    loaded = _load_env_files()
+
+    assert loaded >= 1
+    assert os.environ["TELEGRAM_BOT_TOKEN"] == "123:AAtoken"
+
+
+def test_does_not_override_existing_env(tmp_path, monkeypatch):
+    """An already-set process variable is never clobbered by the file."""
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("SLACK_BOT_TOKEN", "xoxb-from-shell")
+
+    _write_env(tmp_path / ".praisonai" / ".env", "SLACK_BOT_TOKEN=xoxb-from-file\n")
+
+    _load_env_files()
+
+    assert os.environ["SLACK_BOT_TOKEN"] == "xoxb-from-shell"
+
+
+def test_ignores_comments_blanks_and_export_prefix(tmp_path, monkeypatch):
+    """Comments/blank lines are skipped and `export ` prefixes are stripped."""
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("FOO", raising=False)
+    monkeypatch.delenv("BAR", raising=False)
+
+    _write_env(
+        tmp_path / ".praisonai" / ".env",
+        "# a comment\n\nexport FOO=foo\nBAR='bar'\n",
+    )
+
+    _load_env_files()
+
+    assert os.environ["FOO"] == "foo"
+    assert os.environ["BAR"] == "bar"
+
+
+def test_missing_files_are_harmless(tmp_path, monkeypatch):
+    """No env files present → returns 0 and does not raise."""
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    monkeypatch.chdir(tmp_path)
+
+    assert _load_env_files() == 0

tests/unit/test_voice_agent.py

@@ -478,6 +478,26 @@ def test_voice_doctor_report(monkeypatch):
     assert report["summary"]["failed"] >= 1
 
 
+def test_voice_doctor_mcp_probe_timeout_is_warn(monkeypatch):
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-test-key-12345678")
+
+    def fake_http_status(url: str, timeout: float = 5.0):
+        if "/api/mcp/servers" in url:
+            assert timeout == 2.0
+            return "fail", "timed out"
+        return "pass", "HTTP 200"
+
+    with _voice_modules() as imp:
+        doctor = imp("integrations.voice.doctor")
+        monkeypatch.setattr(doctor, "_tcp_open", lambda *args, **kwargs: True)
+        monkeypatch.setattr(doctor, "_http_status", fake_http_status)
+        report = doctor.run_voice_doctor(app_port=8001, sidecar_port=59998)
+
+    mcp = next(c for c in report["checks"] if c["name"] == "MCP servers API")
+    assert mcp["status"] == "warn"
+    assert mcp["detail"] == "timed out"
+
+
 def test_call_detail_ui_includes_analytics():
     with _voice_modules() as imp:
         ui = imp("integrations.voice.call_detail_ui")