Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
refactor(paths): unify DATA_DIR resolution; dev vs daemon state split
trohitgfc9bcd24d488
diff --git a/.env b/.envnew file mode 100644index 00000000..ebfd5047--- /dev/null+++ b/.env@@ -0,0 +1,167 @@+# Service Ports (used by start.js, vite, and docker-compose)+VITE_CLIENT_PORT=3000+PYTHON_BACKEND_PORT=3010+NODEJS_EXECUTOR_PORT=3020+WHATSAPP_RPC_PORT=9400+REDIS_PORT=6379++# Server Configuration+HOST=127.0.0.1+PORT=3010+DEBUG=false+WORKERS=1++# Security (Development keys - MUST CHANGE FOR PRODUCTION)+SECRET_KEY=dev-secret-key-12345678901234567890123456789012+API_KEY_ENCRYPTION_KEY=dev-encryption-key-12345678901234567890123456++# Authentication+# VITE_AUTH_ENABLED: "true" (require login) or "false" (bypass authentication)+VITE_AUTH_ENABLED=false+# AUTH_MODE: "single" (local deploy - first user is owner) or "multi" (cloud - open registration)+AUTH_MODE=single+JWT_SECRET_KEY=dev-jwt-secret-key-12345678901234567890+JWT_EXPIRE_MINUTES=10080+JWT_COOKIE_NAME=machina_token+JWT_COOKIE_SECURE=false+JWT_COOKIE_SAMESITE=lax++# CORS Configuration - Allow all common dev ports+CORS_ORIGINS=["http://localhost:3000","http://localhost:3001","http://localhost:3002","http://localhost:3003","http://localhost:3004","http://localhost:3005","http://localhost:3006","http://127.0.0.1:3000","http://127.0.0.1:3001","http://127.0.0.1:3002","http://127.0.0.1:3003","http://127.0.0.1:3004","http://127.0.0.1:3005","http://127.0.0.1:3006","http://localhost:5173"]++# Database Configuration+# SQLite DB filename. Resolved under DATA_DIR by+# ``Settings._resolve_under_data`` — same pattern as ``temporal.db``+# and ``credentials.db`` so dev mode's DATA_DIR=.machina moves all+# three together. The SQLAlchemy URL is composed at runtime by+# ``Settings.database_url`` (sqlite+aiosqlite:///<abspath>).+WORKFLOW_DB_FILENAME=workflow.db+DATABASE_ECHO=false+DATABASE_POOL_SIZE=5+DATABASE_MAX_OVERFLOW=10++# Cache Configuration (Disabled for development)+REDIS_ENABLED=false+CACHE_TTL=300++# Temporal Configuration+# Enable for durable workflow execution with automatic retries.+# Backed by ``temporal server start-dev`` against a SQLite db at+# ``TEMPORAL_SQLITE_PATH``. The official ``temporal`` CLI is downloaded+# by pooch from https://temporal.download/cli/archive/latest on+# ``machina build`` (or first ``machina start`` if build was skipped).+TEMPORAL_ENABLED=true+TEMPORAL_SERVER_ADDRESS=localhost:7233+TEMPORAL_NAMESPACE=default+TEMPORAL_TASK_QUEUE=machina-tasks+TEMPORAL_PER_TYPE_DISPATCH=true+TEMPORAL_AGENT_WORKFLOW_ENABLED=true+# gRPC frontend port the CLI dev server binds (``--port``). Default per+# https://docs.temporal.io/references/configuration.+TEMPORAL_FRONTEND_GRPC_PORT=7233+# Web UI port (``--ui-port``). ``temporal server start-dev`` defaults+# this to ``--port + 1000``; we override to 8080 to match the+# historical MachinaOS port (kept for muscle memory + bookmarks).+# Browse to http://<host>:<TEMPORAL_UI_PORT>/.+TEMPORAL_UI_PORT=8080+# SQLite db file ``temporal server start-dev --db-filename`` opens.+# Relative to DATA_DIR (= ~/.machina/) unless absolute. Flat under+# DATA_DIR like ``credentials.db`` / ``workflow.db``. History is+# always preserved across restarts (Temporal UI keeps showing every+# workflow that ever ran); see ``TEMPORAL_TERMINATE_RUNNING_ON_STARTUP``+# below for the resumption knob.+TEMPORAL_SQLITE_PATH=temporal.db+# On server boot, terminate every workflow still in ``Running`` state.+# History is preserved (workflows show as ``Terminated`` in the UI,+# NOT deleted) but resumption is disabled, because MachinaOS's+# ``DeploymentManager`` has no boot-time reconcile against Temporal+# Visibility yet — resumed workflows would otherwise keep executing+# but be invisible to the MachinaOS UI. Flip to ``false`` once the+# reconcile lands to re-enable durable resumption.+TEMPORAL_TERMINATE_RUNNING_ON_STARTUP=true+# Graceful shutdown window for the Temporal child process.+TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS=30+# Supervisor readiness-probe window. The CLI binary may need to+# download (~114 MB zip) on first ``machina start`` if ``machina build``+# didn't pre-cache it.+TEMPORAL_SERVER_READY_TIMEOUT_SECONDS=120++# Wave 12 event framework. ``true`` (default) routes trigger events+# through TriggerListenerWorkflow + Temporal Signal fan-out for the+# 8 canary-registered trigger types (webhook, chat, task, telegram,+# whatsapp, gmail, cron, email). Flip to ``false`` to roll back to+# the legacy event_waiter path -- see docs-internal/event_framework.md.+EVENT_FRAMEWORK_ENABLED=true++# Memory compaction. ``true`` (default) auto-compacts agent+# conversation memory when cumulative tokens exceed the model's+# context-window threshold. Per-session overrides via the UI.+COMPACTION_ENABLED=true++# Dead-letter queue for failed workflow executions. Off by default.+DLQ_ENABLED=false++# Data directory (base for all persistent storage: DBs, workspaces,+# workflows, claude state). User-home rooted by default — same+# convention claude code itself uses (`~/.claude/`), Stripe+# (`~/.config/stripe/`), ngrok (`~/.ngrok2/`). Survives `rm -rf` of+# the repo and lets multiple checkouts share state.+#+# Resolution rules (`server/core/paths.py::machina_root`):+# - `~/...` → user home (cross-platform via Path.expanduser)+# - absolute → used verbatim+# - relative → resolved under repo root (back-compat)+#+# Set to `.machina` (or `data`) if you want repo-local behaviour+# instead. Pre-cutover layouts (`<repo>/data/`, `<repo>/workflows/`)+# do NOT auto-migrate — see `server/core/paths.py` for the manual+# `mv` checklist if you're upgrading from an older release.+DATA_DIR=~/.machina++# Per-workflow workspace (nodes save files here, resolved under DATA_DIR)+WORKSPACE_BASE_DIR=workspaces++# Logging+LOG_LEVEL=INFO+LOG_FORMAT=text++# Rate Limiting (Relaxed for development)+RATE_LIMIT_ENABLED=false+RATE_LIMIT_REQUESTS=1000+RATE_LIMIT_WINDOW=60++# Service Timeouts (Extended for debugging)+AI_TIMEOUT=60+AI_MAX_RETRIES=1+AI_RETRY_DELAY=0.5++MAPS_TIMEOUT=30++# Health Check+HEALTH_CHECK_INTERVAL=60++# Cleanup Configuration (for long-running daemon)+CLEANUP_ENABLED=true+CLEANUP_INTERVAL=3600+CLEANUP_LOGS_MAX_COUNT=1000+CLEANUP_CACHE_MAX_AGE_HOURS=24++# Feature Toggles+WS_LOGGING_ENABLED=true++# Gunicorn Configuration (for production deployment)+# GUNICORN_TIMEOUT=120+# GUNICORN_GRACEFUL_TIMEOUT=30+# GUNICORN_KEEPALIVE=5+# GUNICORN_MAX_REQUESTS=10000+# GUNICORN_MAX_REQUESTS_JITTER=1000++# WebSocket Configuration (For remote Android device connections)+WEBSOCKET_URL=wss://relay.zeenie.xyz/ws+WEBSOCKET_API_KEY=++# AI Proxy Configuration (Ollama-style proxy for Claude Code CLI)+# Default port for AI proxy servers (e.g., Ollama, Claude Code CLI proxy)+AI_PROXY_DEFAULT_PORT=11434++diff --git a/.env.dev b/.env.devnew file mode 100644index 00000000..5c63eabb--- /dev/null+++ b/.env.dev@@ -0,0 +1,16 @@+# Dev-mode env overrides — layered on top of ``.env.template`` and+# ``.env`` by ``machina dev`` (only). The ``machina start`` /+# ``machina daemon`` paths never load this file, so production-style+# runs keep the ``.env.template`` defaults (DATA_DIR=~/.machina).+#+# Loaded by ``cli.config.load_dev_overrides`` via ``os.environ.setdefault``+# so an explicit shell override (``DATA_DIR=/foo machina dev``) still+# wins. Committed to git as the canonical dev convention — every+# checkout's ``machina dev`` lands state in the same place.++# Per-checkout state under <repo>/.machina/ (resolved as a relative+# path under ``project_root()`` by ``core.paths.machina_root``).+# Multiple worktrees on the same machine each get their own clean+# DB / workspaces / temporal history; ``rm -rf`` of the worktree+# wipes the runtime state alongside the source.+DATA_DIR=.machinadiff --git a/.env.template b/.env.templateindex 615410e8..ebfd5047 100644--- a/.env.template+++ b/.env.template@@ -30,11 +30,12 @@ JWT_COOKIE_SAMESITE=laxCORS_ORIGINS=["http://localhost:3000","http://localhost:3001","http://localhost:3002","http://localhost:3003","http://localhost:3004","http://localhost:3005","http://localhost:3006","http://127.0.0.1:3000","http://127.0.0.1:3001","http://127.0.0.1:3002","http://127.0.0.1:3003","http://127.0.0.1:3004","http://127.0.0.1:3005","http://127.0.0.1:3006","http://localhost:5173"]# Database Configuration-# SQLite DB file. ``~`` expands cross-platform at Settings load time-# (Path.expanduser → ``$HOME`` on POSIX, ``%USERPROFILE%`` on Windows).-# Keep this in sync with DATA_DIR below — both should live under the-# same root.-DATABASE_URL=sqlite+aiosqlite:///~/.machina/workflow.db+# SQLite DB filename. Resolved under DATA_DIR by+# ``Settings._resolve_under_data`` — same pattern as ``temporal.db``+# and ``credentials.db`` so dev mode's DATA_DIR=.machina moves all+# three together. The SQLAlchemy URL is composed at runtime by+# ``Settings.database_url`` (sqlite+aiosqlite:///<abspath>).+WORKFLOW_DB_FILENAME=workflow.dbDATABASE_ECHO=falseDATABASE_POOL_SIZE=5DATABASE_MAX_OVERFLOW=10diff --git a/.gitignore b/.gitignoreindex 66abbfcb..25056bc9 100644--- a/.gitignore+++ b/.gitignore@@ -21,15 +21,10 @@ package-lock.json# =============================================================================# SECURITY - Credentials and Secrets (NEVER COMMIT)# =============================================================================-# Environment variables (contain API keys, secrets)-.env-.env.*-!.env.template-!.env.example-server/.env-server/.env.*-!server/.env.template-!server/.env.example+# Env files are committed — they hold only ports, paths, feature flags,+# and other non-sensitive config. Credentials live in the encrypted+# ``credentials.db`` (Fernet + PBKDF2 via ``server/core/encryption.py``),+# never in env files.# API Keys and Credentials**/credentials.jsondiff --git a/.npmignore b/.npmignoreindex eb9193e3..4b1e85cc 100644--- a/.npmignore+++ b/.npmignore@@ -7,10 +7,10 @@.gitignore.github/-# Environment & secrets-.env-.env.*-!.env.template+# Env files ship with the package — they hold only non-sensitive config+# (ports, paths, feature flags). Credentials live in the encrypted+# ``credentials.db`` (Fernet + PBKDF2 via server/core/encryption.py),+# never in env files. Matches the .gitignore policy.# Database files*.dbdiff --git a/cli/commands/dev.py b/cli/commands/dev.pyindex 24d64152..b55f2071 100644--- a/cli/commands/dev.py+++ b/cli/commands/dev.py@@ -21,6 +21,7 @@ import typerfrom cli._common import build_backend_spec, free_all_ports, preflightfrom cli.colors import console+from cli.config import load_dev_overridesfrom cli.platform_ import (node_modules_dir,platform_name,@@ -32,10 +33,9 @@ from cli.commands._temporal_specs import temporal_specsdef _has_vite(root: Path) -> bool:- return (- (node_modules_dir(root) / "vite").exists()- or (root / "client" / "node_modules" / "vite").exists()- )+ return (node_modules_dir(root) / "vite").exists() or (+ root / "client" / "node_modules" / "vite"+ ).exists()def _clear_vite_cache(root: Path) -> None:@@ -73,9 +73,18 @@ def _build_specs(root: Path, cfg, *, daemon: bool, use_vite: bool) -> list[Servidef dev_command(daemon: bool = typer.Option(- False, "--daemon", help="Bind backend to 0.0.0.0 instead of 127.0.0.1.",+ False,+ "--daemon",+ help="Bind backend to 0.0.0.0 instead of 127.0.0.1.",),) -> None:+ # Layer ``.env.dev`` (committed) on top of ``.env.template`` + ``.env``+ # so dev state lands at ``<repo>/.machina/`` (per-checkout) instead+ # of ``~/.machina/`` (user home). Called BEFORE ``preflight()`` so+ # ``load_config``'s ``setdefault`` pass sees the dev values already+ # in ``os.environ``. ``machina start`` / ``machina daemon`` skip+ # this hook, falling through to the ``.env.template`` defaults.+ load_dev_overrides()cfg, root = preflight()os.environ.setdefault("PYTHONUTF8", "1")@@ -83,7 +92,9 @@ def dev_command(console.print("\n[bold]=== MachinaOS Starting ===[/]\n")console.print(f"Platform: {platform_name()}")- console.print(f"Mode: {'Daemon (uvicorn)' if daemon else 'Development (uvicorn)'}")+ console.print(+ f"Mode: {'Daemon (uvicorn)' if daemon else 'Development (uvicorn)'}"+ )console.print(f"Ports: {', '.join(str(p) for p in cfg.all_ports)}")console.log("Freeing ports...")diff --git a/cli/config.py b/cli/config.pyindex cccc26b8..a928da4c 100644--- a/cli/config.py+++ b/cli/config.py@@ -1,16 +1,25 @@-"""Project configuration -- typed view over ``.env`` / ``.env.template``.--Stdlib-only env-var loader. ``.env.template`` ships with every install-and is the canonical source of defaults; ``.env`` (created by-``scripts/postinstall.js`` on ``npm install -g machinaos``) layers user-overrides on top; ``os.environ`` wins over both at the call site.--Merged values are pushed into ``os.environ`` so downstream consumers-that read ``os.environ`` directly see the same view as this module.--No Python-side hardcoded defaults: ``.env.template`` is the single-source of truth. If the template is missing (broken install), we error-out loudly with a remediation hint rather than silently substituting+"""Project configuration -- typed view over ``.env.dev`` / ``.env`` / ``.env.template``.++Stdlib-only env-var loader. Three env files, lowest precedence first:++ 1. ``.env.template`` — canonical production defaults. Ships with every+ install. ``DATA_DIR=~/.machina`` (user home) is the daemon+ behaviour: ``machina start`` / ``machina daemon`` use these.+ 2. ``.env`` — user overrides (created by ``scripts/postinstall.js`` on+ ``npm install -g machinaos``). Gitignored.+ 3. ``.env.dev`` — dev-mode overrides. Loaded ONLY by ``machina dev``+ via :func:`load_dev_overrides`. Pins ``DATA_DIR=.machina`` so+ per-checkout dev state lives at ``<repo>/.machina/`` instead of+ ``~/.machina/``. Committed to git.++Process env (``os.environ``) wins over all three. Merged file values+are pushed into ``os.environ`` via ``setdefault`` so downstream+consumers that read ``os.environ`` directly see the same view as this+module.++No Python-side hardcoded defaults: env files are the single source of+truth. If ``.env.template`` is missing (broken install), we error out+loudly with a remediation hint rather than silently substitutingduplicate hardcoded values that drift from the shipped template."""@@ -94,6 +103,27 @@ class Config:]+def load_dev_overrides(root: Path | None = None) -> None:+ """Layer ``.env.dev`` on top of ``.env.template`` + ``.env``.++ Called by ``machina dev`` BEFORE :func:`load_config` so dev-only env+ vars (notably ``DATA_DIR=.machina``, the per-checkout dev state+ root) land in ``os.environ`` first. ``load_config`` then sees them+ via its own ``setdefault`` pass and skips its template fallbacks.++ Uses ``setdefault`` so an explicit shell override+ (``DATA_DIR=/foo machina dev``) still wins. Missing ``.env.dev``+ file is a no-op — production-style invocations never trigger this.++ The daemon path (``machina start`` / ``machina daemon``) does not+ call this, so daemon installs keep the ``.env.template`` default+ of ``DATA_DIR=~/.machina``.+ """+ root = root or project_root()+ for key, value in _load_env_file(root / ".env.dev").items():+ os.environ.setdefault(key, value)++@lru_cache(maxsize=1)def load_config(root: Path | None = None) -> Config:"""Load + merge ``.env.template`` (baseline) and ``.env`` (overrides).diff --git a/server/core/config.py b/server/core/config.pyindex 59983527..5728e321 100644--- a/server/core/config.py+++ b/server/core/config.py@@ -33,8 +33,11 @@ class Settings(BaseSettings):secret_key: str = Field(env="SECRET_KEY", min_length=32)cors_origins: List[str] = Field(env="CORS_ORIGINS")- # Database Configuration- database_url: str = Field(env="DATABASE_URL")+ # Database Configuration. ``database_url`` is a computed property+ # (see below) — the SQLite file name lives in ``WORKFLOW_DB_FILENAME``+ # and resolves under ``DATA_DIR`` like every other state path,+ # rather than being hardcoded inside a SQLAlchemy URL string.+ workflow_db_filename: str = Field(env="WORKFLOW_DB_FILENAME")database_echo: bool = Field(default=False, env="DATABASE_ECHO")database_pool_size: int = Field(default=20, env="DATABASE_POOL_SIZE", ge=5, le=100)database_max_overflow: int = Field(default=30, env="DATABASE_MAX_OVERFLOW", ge=10, le=100)@@ -76,7 +79,8 @@ class Settings(BaseSettings):# heartbeat interval — a worker drain completes within one polling# cycle. Tune via env when SIGTERM-to-restart latency matters.temporal_graceful_shutdown_seconds: int = Field(- env="TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS", ge=1,+ env="TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS",+ ge=1,)# Wave 12 canary-flag default flipped to True (2026-05-15).# The Temporal-native event dispatch path@@ -89,7 +93,8 @@ class Settings(BaseSettings):# working unchanged for non-canary triggers. See# docs-internal/event_framework.md § Rollback procedure.event_framework_enabled: bool = Field(- default=True, env="EVENT_FRAMEWORK_ENABLED",+ default=True,+ env="EVENT_FRAMEWORK_ENABLED",)# gRPC frontend port — the port ``temporal server start-dev``@@ -97,14 +102,18 @@ class Settings(BaseSettings):# ``.env.template`` (canonical default lives there). Reference:# https://docs.temporal.io/references/configurationtemporal_frontend_grpc_port: int = Field(- env="TEMPORAL_FRONTEND_GRPC_PORT", ge=1024, le=65535,+ env="TEMPORAL_FRONTEND_GRPC_PORT",+ ge=1024,+ le=65535,)# Web UI port. ``temporal server start-dev`` defaults this to# ``--port + 1000`` (i.e. 8233 alongside the default 7233 gRPC# port); declared explicitly via ``--ui-port`` so the binding is# intentional and surfaces in status snapshots.temporal_ui_port: int = Field(- env="TEMPORAL_UI_PORT", ge=1024, le=65535,+ env="TEMPORAL_UI_PORT",+ ge=1024,+ le=65535,)# SQLite db path passed to ``temporal server start-dev# --db-filename ...``. Resolved relative to ``DATA_DIR``@@ -183,10 +192,14 @@ class Settings(BaseSettings):# File-rotation knobs — only consulted when LOG_FILE is set.# Default ceiling = 10 MiB × 5 backups = ~50 MiB on disk.log_file_max_bytes: int = Field(- default=10 * 1024 * 1024, env="LOG_FILE_MAX_BYTES", ge=1024,+ default=10 * 1024 * 1024,+ env="LOG_FILE_MAX_BYTES",+ ge=1024,)log_file_backup_count: int = Field(- default=5, env="LOG_FILE_BACKUP_COUNT", ge=0,+ default=5,+ env="LOG_FILE_BACKUP_COUNT",+ ge=0,)# Rate Limiting@@ -251,25 +264,20 @@ class Settings(BaseSettings):def _expanduser_path(cls, v: Optional[str]) -> Optional[str]:return str(Path(v).expanduser()) if v else v- @field_validator("database_url", mode="after")- @classmethod- def validate_database_url(cls, v: str) -> str:- """Expand ``~`` in sqlite paths + ensure parent dir exists.-- Parses the URL via SQLAlchemy's canonical parser instead of- string surgery on ``:///``.+ @property+ def database_url(self) -> str:+ """Compose the SQLAlchemy URL from ``DATA_DIR`` + ``WORKFLOW_DB_FILENAME``.++ Always ``sqlite+aiosqlite:///<abspath>`` — the only DB engine+ MachinaOS uses. Parent dir is mkdir'd here so the DB file can+ be opened on first access without a separate bootstrap step.+ Reads :meth:`_resolve_under_data` so the same DEV / daemon+ toggle (``.env.dev`` swapping ``DATA_DIR=.machina``) that moves+ every other state path moves ``workflow.db`` too."""- if not v:- return v- from sqlalchemy.engine.url import make_url- url = make_url(v)- if url.drivername.startswith("sqlite") and url.database:- db_path = Path(url.database).expanduser()- db_path.parent.mkdir(parents=True, exist_ok=True)- if str(db_path) != url.database:- v = url.set(database=str(db_path)).render_as_string(hide_password=False)- return v-+ db_path = Path(self._resolve_under_data(self.workflow_db_filename))+ db_path.parent.mkdir(parents=True, exist_ok=True)+ return f"sqlite+aiosqlite:///{db_path}"@propertydef is_development(self) -> bool:@@ -282,11 +290,17 @@ class Settings(BaseSettings):return not self.debugdef _resolve_under_data(self, path: str) -> str:- """Resolve a path relative to data_dir, unless already absolute."""- p = Path(path)- if p.is_absolute():- return str(p)- return str(Path(self.data_dir) / p)+ """Resolve ``path`` under ``data_dir``, returning an absolute path.++ Thin delegate to :func:`core.paths._resolve_data_path` so the+ single resolution algorithm lives in one place. Used by the+ ``credentials_db_resolved`` / ``workspace_base_resolved``+ properties and any plugin that needs a DATA_DIR-relative path+ without importing ``core.paths`` directly.+ """+ from core.paths import _resolve_data_path++ return str(_resolve_data_path(self.data_dir, path))@propertydef credentials_db_resolved(self) -> str:@@ -310,4 +324,4 @@ class Settings(BaseSettings):"extra": "ignore","env_parse_none_str": "none","env_nested_delimiter": "__",- }\ No newline at end of file+ }diff --git a/server/core/paths.py b/server/core/paths.pyindex 2d5a831b..c417f9ff 100644--- a/server/core/paths.py+++ b/server/core/paths.py@@ -93,18 +93,53 @@ def project_root() -> Path:return _REPO_ROOT-def machina_root() -> Path:- """Absolute path of ``~/.machina/`` (or the configured DATA_DIR).-- ``Path.expanduser()`` is a no-op when there's no ``~`` to expand,- so we can always call it unconditionally. After expansion: if- absolute, use verbatim; if relative, resolve under repo root- (back-compat with ``DATA_DIR=data`` etc.). Settings is- instantiated lazily — Pydantic caches the result.+def _resolve_data_path(base: str, subpath: str = "") -> Path:+ """Canonical state-path resolution primitive. Always returns absolute.++ Shared by :func:`data_path` (public entry point) and+ ``Settings._resolve_under_data`` (the Pydantic-side mirror used by+ state-path properties like ``credentials_db_resolved``). One+ implementation so the two never drift.++ Rules:+ - ``Path.expanduser()`` on ``base`` — no-op when no ``~`` present.+ - Absolute resolved ``base`` → used verbatim.+ - Relative ``base`` → resolved under :func:`project_root` (so+ dev mode's ``DATA_DIR=.machina`` lands at ``<repo>/.machina/``+ regardless of the subprocess's cwd).+ - Empty ``subpath`` → returns the resolved base.+ - Absolute ``subpath`` → returned verbatim.+ - Relative ``subpath`` → joined onto the resolved base.+ """+ b = Path(base).expanduser()+ if not b.is_absolute():+ b = project_root() / b+ if not subpath:+ return b.resolve()+ p = Path(subpath)+ return p.resolve() if p.is_absolute() else (b / p).resolve()+++def data_path(subpath: str | Path = "") -> Path:+ """Absolute path of ``<DATA_DIR>/<subpath>``.++ Single entry point for every state location MachinaOS reads or+ writes. Reads ``Settings.data_dir`` (env var ``DATA_DIR``) — so+ the dev / daemon split (``.env.dev`` vs ``.env.template``) moves+ every state path together. Pass an empty ``subpath`` to get the+ DATA_DIR root.++ Settings is instantiated lazily — Pydantic caches the result.+ Resolution rules: see :func:`_resolve_data_path`."""from core.config import Settings- p = Path(Settings().data_dir).expanduser()- return p.resolve() if p.is_absolute() else (project_root() / p).resolve()++ return _resolve_data_path(Settings().data_dir, str(subpath))+++def machina_root() -> Path:+ """Absolute path of the configured DATA_DIR (= ``data_path()``)."""+ return data_path()def packages_dir() -> Path:@@ -152,13 +187,13 @@ def package_dir(name: str) -> Path:def claude_config_dir() -> Path:"""``CLAUDE_CONFIG_DIR`` for spawned claude subprocesses.- Resolves to ``<machina_root>/claude/``. Single source of truth for+ Resolves to ``<DATA_DIR>/claude/``. Single source of truth forthe plugin's ``MACHINA_CLAUDE_DIR`` constant (re-exported from``nodes/agent/claude_code_agent/_oauth.py`` for back-compat).Stores OAuth tokens + session state — distinct from:func:`claude_npm_dir`, which holds the downloaded CLI binary."""- return machina_root() / "claude"+ return data_path("claude")def claude_npm_dir() -> Path:@@ -173,8 +208,16 @@ def claude_npm_dir() -> Path:def workspaces_dir() -> Path:- """Root for per-workflow workspaces."""- return machina_root() / "workspaces"+ """Root for per-workflow workspaces.++ Routes through ``data_path(Settings().workspace_base_dir)`` (env+ var ``WORKSPACE_BASE_DIR``) so the path stays in lockstep with+ every other state location — no hardcoded ``"workspaces"`` literal+ that drifts when the env var changes.+ """+ from core.config import Settings++ return data_path(Settings().workspace_base_dir)def workspace_dir(workflow_id: str) -> Path:@@ -204,18 +247,32 @@ def example_workflows_dir() -> Path:def whatsapp_dir() -> Path:- """Persistent WhatsApp session DB / state dir."""- return machina_root() / "whatsapp"+ """Persistent WhatsApp session DB / state dir.++ Routes through ``data_path(Settings().whatsapp_data_subdir)``+ (env var ``WHATSAPP_DATA_SUBDIR``) so the WhatsApp tree moves+ with ``DATA_DIR``.+ """+ from core.config import Settings++ return data_path(Settings().whatsapp_data_subdir)def credentials_db_path() -> Path:- """Encrypted credentials store (Fernet + PBKDF2)."""- return machina_root() / "credentials.db"+ """Encrypted credentials store (Fernet + PBKDF2).++ Routes through ``data_path(Settings().credentials_db_path)`` (env+ var ``CREDENTIALS_DB_PATH``) so the DB moves with ``DATA_DIR``.+ """+ from core.config import Settings++ return data_path(Settings().credentials_db_path)__all__ = ["project_root","machina_root",+ "data_path","packages_dir","package_dir","claude_config_dir",diff --git a/server/nodes/whatsapp/_runtime.py b/server/nodes/whatsapp/_runtime.pyindex bb7c96e6..12169963 100644--- a/server/nodes/whatsapp/_runtime.py+++ b/server/nodes/whatsapp/_runtime.py@@ -36,6 +36,7 @@ class WhatsAppRuntime(BaseProcessSupervisor):super().__init__()if settings is None:from core.config import Settings+settings = Settings()self.settings = settings@@ -43,11 +44,14 @@ class WhatsAppRuntime(BaseProcessSupervisor):@propertydef data_root(self) -> Path:- sub = getattr(self.settings, "whatsapp_data_subdir", "whatsapp")- base = Path(self.settings.data_dir)- if not base.is_absolute():- base = _PROJECT_ROOT / "server" / base- return (base / sub).resolve()+ # Routes through ``Settings._resolve_under_data`` so dev mode's+ # ``DATA_DIR=.machina`` lands the WhatsApp tree at+ # ``<repo>/.machina/whatsapp/`` (not ``<repo>/server/.machina/...``,+ # which the old ad-hoc ``_PROJECT_ROOT / "server" / data_dir``+ # logic produced when ``DATA_DIR`` was relative).+ return Path(+ self.settings._resolve_under_data(self.settings.whatsapp_data_subdir)+ )@propertydef port(self) -> int:@@ -107,7 +111,8 @@ class WhatsAppRuntime(BaseProcessSupervisor):config["server"]["port"] = self.portconfig["server"]["host"] = self.bind_host(self.data_root / "configs" / "config.yaml").write_text(- yaml.safe_dump(config, sort_keys=False), encoding="utf-8",+ yaml.safe_dump(config, sort_keys=False),+ encoding="utf-8",)