fix: define host runtime environment ownership

.github/workflows/ci.yml

@@ -82,6 +82,18 @@ jobs:
           uv run python -c
           "from pathlib import Path; import subprocess; out = Path('.tmp/agentseek.Dockerfile'); out.parent.mkdir(exist_ok=True); subprocess.run(['uv', 'run', 'agentseek-api', 'dockerfile', '--config', 'examples/external_graph/manifest.json', str(out)], check=True); text = out.read_text(encoding='utf-8'); assert 'ENV PYTHONPATH=/deps/agent' in text; assert 'ENV AGENTSEEK_GRAPHS=/deps/agent/examples/external_graph/manifest.json' in text"
 
+      - name: CLI config, host environment, and process tests
+        run: >-
+          uv run pytest
+          tests/unit/test_cli.py
+          tests/unit/test_graph_manifest.py
+          tests/unit/test_dotenv_adapter.py
+          tests/unit/test_runtime_environment.py
+          tests/unit/test_runtime_entrypoint.py
+          tests/unit/test_process_supervisor.py
+          tests/integration/test_cli_runtime_processes.py
+          -q
+
       - name: Sync embedded SeekDB extra for serve smoke
         if: runner.os == 'Linux' || (runner.os == 'macOS' && runner.arch == 'ARM64')
         run: uv sync --dev --extra embedded
@@ -90,8 +102,9 @@ jobs:
         if: runner.os == 'Linux' || (runner.os == 'macOS' && runner.arch == 'ARM64')
         run: uv run python scripts/test_cli_serve_smoke.py
 
-      - name: CLI config and Docker planning tests
-        run: uv run pytest tests/unit/test_cli.py tests/unit/test_graph_manifest.py -q
+      - name: Minimum direct dependency compatibility
+        if: runner.os == 'Linux'
+        run: uv run python scripts/test_minimum_cli_dependencies.py
 
   embedded-seekdb-smoke:
     name: Embedded SeekDB Smoke

CHANGELOG.md

@@ -2,6 +2,27 @@
 
 Notable changes to AgentSeek API are documented in this file.
 
+## Unreleased
+
+### Fixed
+
+- Made inherited host environment keys, including explicit empty strings,
+  authoritative over config and CLI dotenv sources.
+- Parse each dotenv source independently with strict malformed-file handling,
+  and distinguish valueless `KEY` from explicit empty `KEY=`.
+- Start worker and scheduler roles in fresh child processes so their settings
+  are constructed after the resolved environment is installed.
+- Kept version, help, and Dockerfile rendering independent of runtime settings
+  validation.
+
+### Upgrade notes
+
+- Dotenv values no longer interpolate from config mappings or other dotenv
+  files. Put dependent bindings in one physical file or pass the final literal
+  value.
+- Malformed dotenv syntax now exits with status 2 instead of warning and
+  continuing with a partial runtime configuration.
+
 ## 0.2.1 - 2026-07-14
 
 ### Fixed

README.md

@@ -260,7 +260,35 @@ When running from this repository, use `uv run agentseek-api ...`.
 
 - `-c, --config PATH`: explicit `agentseek.json`, `langgraph.json`, or manifest
   path
-- `--env-file PATH`: dotenv-style file loaded into the runtime environment
+- `--env-file PATH`: host-runtime dotenv source
+
+### Host runtime environment
+
+For `dev`, `serve`, `worker`, and `scheduler`, direct assignments are applied in
+this order:
+
+1. the dotenv path named by config `env`;
+2. the literal config `env` mapping and `auth.path`;
+3. the CLI `--env-file`;
+4. the environment inherited by `agentseek-api`.
+
+The inherited environment is authoritative by key presence. This includes an
+explicit empty value. A lower source can fill an absent key, but cannot replace
+an inherited `KEY=`.
+
+Each dotenv file is evaluated independently. It can reference the inherited
+environment and earlier bindings in the same physical file; it cannot reference
+a config mapping or another dotenv file. Later assignment does not recompute an
+earlier interpolated value.
+
+In dotenv syntax, a bare `KEY` is valid but contributes no assignment, while
+`KEY=` contributes an explicit empty string. Missing files, invalid UTF-8, and
+malformed syntax stop the command before a runtime child starts.
+
+The CLI applies command-owned values after this merge: the selected config path
+becomes `AGENTSEEK_GRAPHS`, and `dev` forces `STUDIO_AUTH_LOCAL_DEV=true`.
+Host and port options are passed as child argv and do not rewrite environment
+keys with similar names.
 
 ### Common usage
 

pyproject.toml

@@ -9,22 +9,23 @@ dependencies = [
     "uvicorn>=0.30.0",
     "pydantic>=2.8.0",
     "pydantic-settings>=2.4.0",
-    "sqlalchemy>=2.0.0",
+    "sqlalchemy>=2.0.12",
     "greenlet>=3.1.0",
     "asyncpg>=0.29.0",
     "aiomysql>=0.2.0",
     "aiosqlite>=0.20.0",
     "redis>=5.0.0",
-    "langgraph>=1.0.3",
+    "langgraph>=1.0.6",
     "langgraph-sdk>=0.3.5",
-    "langchain-core>=1.0.0",
+    "langchain-core>=1.2.5",
     "langchain-openai>=1.0.0",
     "langchain-anthropic>=1.0.0",
     "langchain-oceanbase==0.6.0",
     "cryptography>=45.0.0",
     "pymysql>=1.1.0",
     "langchain>=0.3.9",
     "mcp>=1.27.1,<2",
+    "python-dotenv>=1.0,<1.3",
     "scalar-fastapi>=1.0.3",
 ]
 
@@ -39,7 +40,7 @@ agentseek-api = "agentseek_api.cli:main"
 [dependency-groups]
 dev = [
     "pytest>=8.0.0",
-    "pytest-asyncio>=0.23.0",
+    "pytest-asyncio>=0.23.5",
     "pytest-cov>=5.0.0",
     "httpx>=0.27.0",
     "ruff>=0.6.0",

scripts/test_minimum_cli_dependencies.py

@@ -0,0 +1,109 @@
+"""Verify host environment resolution with all direct dependency floors."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+import tomllib
+from pathlib import Path
+
+
+def main() -> None:
+    repository = Path(__file__).resolve().parents[1]
+    project = tomllib.loads((repository / "pyproject.toml").read_text(encoding="utf-8"))
+    requirements = list(project["project"]["dependencies"])
+    requirements.append("pytest>=8.0.0")
+    requirements.append("pytest-asyncio>=0.23.5")
+
+    with tempfile.TemporaryDirectory(prefix="agentseek-minimum-") as directory:
+        environment = Path(directory) / ".venv"
+        subprocess.run(
+            [
+                "uv",
+                "venv",
+                "--python",
+                "3.12",
+                str(environment),
+            ],
+            check=True,
+        )
+        python = environment / (
+            "Scripts/python.exe" if sys.platform == "win32" else "bin/python"
+        )
+        subprocess.run(
+            [
+                "uv",
+                "pip",
+                "install",
+                "--python",
+                str(python),
+                "--resolution",
+                "lowest-direct",
+                *requirements,
+            ],
+            check=True,
+        )
+        subprocess.run(
+            [
+                "uv",
+                "pip",
+                "install",
+                "--python",
+                str(python),
+                "--no-deps",
+                "-e",
+                str(repository),
+            ],
+            check=True,
+        )
+
+        version = subprocess.run(
+            [
+                str(python),
+                "-c",
+                (
+                    "import importlib.metadata; "
+                    "print(importlib.metadata.version('python-dotenv'))"
+                ),
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        assert version.stdout.strip() == "1.0.0"
+
+        cli_env = dict(os.environ)
+        cli_env.pop("PYTHONPATH", None)
+        cli_env["PORT"] = "not-an-integer"
+        version_result = subprocess.run(
+            [str(python), "-m", "agentseek_api.cli", "version"],
+            cwd=repository,
+            env=cli_env,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        expected_version = project["project"]["version"]
+        assert version_result.stdout.strip() == f"agentseek-api {expected_version}"
+
+        test_env = dict(os.environ)
+        test_env.pop("PYTHONPATH", None)
+        subprocess.run(
+            [
+                str(python),
+                "-m",
+                "pytest",
+                "tests/unit/test_dotenv_adapter.py",
+                "tests/unit/test_runtime_environment.py",
+                "-q",
+            ],
+            cwd=repository,
+            env=test_env,
+            check=True,
+        )
+
+
+if __name__ == "__main__":
+    main()