synth-ai 0.2.14__py3-none-any.whl → 0.2.16__py3-none-any.whl

synth_ai/_utils/__init__.py

@@ -0,0 +1,47 @@
+"""
+Compatibility shims for legacy `synth_ai._utils.*` imports.
+
+The modern codebase exposes these helpers under ``synth_ai.utils``.  These
+modules re-export the public symbols so existing downstream code (and our own
+older examples/tests) continue to work without modification.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from types import ModuleType
+
+_MAPPING = {
+    "base_url": "synth_ai.utils.base_url",
+    "http": "synth_ai.utils.http",
+    "prompts": "synth_ai.utils.prompts",
+    "task_app_state": "synth_ai.utils.task_app_state",
+    "user_config": "synth_ai.utils.user_config",
+}
+
+__all__ = sorted(_MAPPING.keys())
+
+
+def __getattr__(name: str) -> ModuleType:
+    target = _MAPPING.get(name)
+    if not target:
+        raise AttributeError(f"module 'synth_ai._utils' has no attribute '{name}'")
+    module = import_module(target)
+    globals()[name] = module
+    return module
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))
+
+
+def _export(module_name: str) -> None:
+    module = import_module(_MAPPING[module_name])
+    globals().setdefault(module_name, module)
+    if hasattr(module, "__all__"):
+        for attr in module.__all__:  # type: ignore[attr-defined]
+            globals().setdefault(attr, getattr(module, attr))
+
+
+for _name in __all__:
+    _export(_name)

synth_ai/_utils/base_url.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from synth_ai.utils.base_url import *  # noqa: F401,F403
+
+try:
+    from synth_ai.utils.base_url import __all__ as __wrapped_all__  # type: ignore[attr-defined]
+except ImportError:  # pragma: no cover - defensive
+    __wrapped_all__ = []
+
+__all__ = list(__wrapped_all__)

synth_ai/_utils/http.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from synth_ai.utils.http import *  # noqa: F401,F403
+
+try:
+    from synth_ai.utils.http import __all__ as __wrapped_all__  # type: ignore[attr-defined]
+except ImportError:  # pragma: no cover - defensive
+    __wrapped_all__ = []
+
+__all__ = list(__wrapped_all__)

synth_ai/_utils/prompts.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from synth_ai.utils.prompts import *  # noqa: F401,F403
+
+try:
+    from synth_ai.utils.prompts import __all__ as __wrapped_all__  # type: ignore[attr-defined]
+except ImportError:  # pragma: no cover - defensive
+    __wrapped_all__ = []
+
+__all__ = list(__wrapped_all__)

synth_ai/_utils/task_app_state.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from synth_ai.utils.task_app_state import *  # noqa: F401,F403
+
+try:
+    from synth_ai.utils.task_app_state import (
+        __all__ as __wrapped_all__,  # type: ignore[attr-defined]
+    )
+except ImportError:  # pragma: no cover - defensive
+    __wrapped_all__ = []
+
+__all__ = list(__wrapped_all__)

synth_ai/_utils/user_config.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from synth_ai.utils.user_config import *  # noqa: F401,F403
+
+try:
+    from synth_ai.utils.user_config import __all__ as __wrapped_all__  # type: ignore[attr-defined]
+except ImportError:  # pragma: no cover - defensive
+    __wrapped_all__ = []
+
+__all__ = list(__wrapped_all__)

synth_ai/api/models/supported.py

@@ -20,35 +20,106 @@ QWEN3_MODELS: list[str] = [
     "Qwen/Qwen3-14B",
     "Qwen/Qwen3-30B-A3B",
     "Qwen/Qwen3-32B",
-    # Include 4B-2507 and Thinking variants used in RL
+    # 2507 baseline models
+    "Qwen/Qwen3-4B-2507",
+    # Instruct variants (no <think> tags)
+    "Qwen/Qwen3-4B-Instruct-2507",
+    "Qwen/Qwen3-4B-Instruct-2507-FP8",
+    "Qwen/Qwen3-30B-A3B-Instruct-2507",
+    "Qwen/Qwen3-30B-A3B-Instruct-2507-FP8",
+    "Qwen/Qwen3-235B-A22B-Instruct-2507",
+    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
+    # Thinking variants (with <think> tags)
     "Qwen/Qwen3-4B-Thinking-2507",
+    "Qwen/Qwen3-4B-Thinking-2507-FP8",
     "Qwen/Qwen3-30B-A3B-Thinking-2507",
+    "Qwen/Qwen3-30B-A3B-Thinking-2507-FP8",
     "Qwen/Qwen3-235B-A22B-Thinking-2507",
+    "Qwen/Qwen3-235B-A22B-Thinking-2507-FP8",
 ]
 
 # Qwen3 Coder family (backend-supported); text-only, SFT/inference
 QWEN3_CODER_MODELS: list[str] = [
-    # Instruct variants used for coding tasks
+    # Instruct variants used for coding tasks (no <think> tags)
     "Qwen/Qwen3-Coder-30B-A3B-Instruct",
+    "Qwen/Qwen3-Coder-30B-A3B-Instruct-FP8",
     "Qwen/Qwen3-Coder-480B-A35B-Instruct",
+    "Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8",
+]
+
+# Qwen3-VL family (vision-language models); multimodal, SFT/inference
+QWEN3_VL_MODELS: list[str] = [
+    # Vision-Language Models (Qwen3-VL)
+    "Qwen/Qwen3-VL-2B-Instruct",
+    "Qwen/Qwen3-VL-2B-Thinking",
+    "Qwen/Qwen3-VL-4B-Instruct",
+    "Qwen/Qwen3-VL-4B-Thinking",
+    "Qwen/Qwen3-VL-8B-Instruct",
+    "Qwen/Qwen3-VL-8B-Thinking",
+    "Qwen/Qwen3-VL-30B-A3B-Instruct",
+    "Qwen/Qwen3-VL-30B-A3B-Thinking",
+    "Qwen/Qwen3-VL-32B-Instruct",
+    "Qwen/Qwen3-VL-32B-Thinking",
+    "Qwen/Qwen3-VL-235B-A22B-Instruct",
+    "Qwen/Qwen3-VL-235B-A22B-Thinking",
 ]
 
 # Training support sets
 RL_SUPPORTED_MODELS: frozenset[str] = frozenset(
     {
+        # Legacy base models
         "Qwen/Qwen3-0.6B",
         "Qwen/Qwen3-1.7B",
         "Qwen/Qwen3-4B",
-        "Qwen/Qwen3-4B-Thinking-2507",
         "Qwen/Qwen3-8B",
         "Qwen/Qwen3-14B",
         "Qwen/Qwen3-30B-A3B",
+        # 2507 models - base
+        "Qwen/Qwen3-4B-2507",
+        # 2507 models - instruct (no <think> tags)
+        "Qwen/Qwen3-4B-Instruct-2507",
+        "Qwen/Qwen3-4B-Instruct-2507-FP8",
+        "Qwen/Qwen3-30B-A3B-Instruct-2507",
+        "Qwen/Qwen3-30B-A3B-Instruct-2507-FP8",
+        # 2507 models - thinking (with <think> tags)
+        "Qwen/Qwen3-4B-Thinking-2507",
+        "Qwen/Qwen3-4B-Thinking-2507-FP8",
         "Qwen/Qwen3-30B-A3B-Thinking-2507",
+        "Qwen/Qwen3-30B-A3B-Thinking-2507-FP8",
+        # Coder instruct models
+        "Qwen/Qwen3-Coder-30B-A3B-Instruct",
+        "Qwen/Qwen3-Coder-30B-A3B-Instruct-FP8",
+        # Vision-Language models (Qwen3-VL)
+        "Qwen/Qwen3-VL-2B-Instruct",
+        "Qwen/Qwen3-VL-2B-Thinking",
+        "Qwen/Qwen3-VL-4B-Instruct",
+        "Qwen/Qwen3-VL-4B-Thinking",
+        "Qwen/Qwen3-VL-8B-Instruct",
+        "Qwen/Qwen3-VL-8B-Thinking",
     }
 )
 
-# SFT allowlist includes core Qwen3 plus Coder family
-SFT_SUPPORTED_MODELS: frozenset[str] = frozenset([*QWEN3_MODELS, *QWEN3_CODER_MODELS])
+# SFT allowlist includes core Qwen3 plus Coder and VL families
+SFT_SUPPORTED_MODELS: frozenset[str] = frozenset([*QWEN3_MODELS, *QWEN3_CODER_MODELS, *QWEN3_VL_MODELS])
+
+# Models that support <think> reasoning tags
+THINKING_MODELS: frozenset[str] = frozenset(
+    {
+        "Qwen/Qwen3-4B-Thinking-2507",
+        "Qwen/Qwen3-4B-Thinking-2507-FP8",
+        "Qwen/Qwen3-30B-A3B-Thinking-2507",
+        "Qwen/Qwen3-30B-A3B-Thinking-2507-FP8",
+        "Qwen/Qwen3-235B-A22B-Thinking-2507",
+        "Qwen/Qwen3-235B-A22B-Thinking-2507-FP8",
+        # Vision-Language Thinking models
+        "Qwen/Qwen3-VL-2B-Thinking",
+        "Qwen/Qwen3-VL-4B-Thinking",
+        "Qwen/Qwen3-VL-8B-Thinking",
+        "Qwen/Qwen3-VL-30B-A3B-Thinking",
+        "Qwen/Qwen3-VL-32B-Thinking",
+        "Qwen/Qwen3-VL-235B-A22B-Thinking",
+    }
+)
 
 # ------------------------------------------------------------------------------
 # Lifecycle classification (core vs experimental)
@@ -58,11 +129,17 @@ SFT_SUPPORTED_MODELS: frozenset[str] = frozenset([*QWEN3_MODELS, *QWEN3_CODER_MO
 _EXPERIMENTAL_DEFAULTS: frozenset[str] = frozenset(
     {
         # Larger (>= 64B) or bleeding-edge variants are experimental by default.
+        "Qwen/Qwen3-235B-A22B-Instruct-2507",
+        "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
         "Qwen/Qwen3-235B-A22B-Thinking-2507",
+        "Qwen/Qwen3-235B-A22B-Thinking-2507-FP8",
         "Qwen/Qwen3-Coder-480B-A35B-Instruct",
+        "Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8",
         # Thinking variants can fluctuate more rapidly.
         "Qwen/Qwen3-30B-A3B-Thinking-2507",
+        "Qwen/Qwen3-30B-A3B-Thinking-2507-FP8",
         "Qwen/Qwen3-4B-Thinking-2507",
+        "Qwen/Qwen3-4B-Thinking-2507-FP8",
     }
 )
 
@@ -77,8 +154,8 @@ def _parse_experimental_env() -> frozenset[str]:
 # Final experimental set (defaults ∪ optional env override)
 EXPERIMENTAL_MODELS: frozenset[str] = frozenset(_EXPERIMENTAL_DEFAULTS | _parse_experimental_env())
 
-# Build catalog entries for both core and coder families under unified "Qwen3"
-_ALL_QWEN3_IDS: list[str] = [*QWEN3_MODELS, *QWEN3_CODER_MODELS]
+# Build catalog entries for core, coder, and VL families under unified "Qwen3"
+_ALL_QWEN3_IDS: list[str] = [*QWEN3_MODELS, *QWEN3_CODER_MODELS, *QWEN3_VL_MODELS]
 
 CORE_MODELS: frozenset[str] = frozenset(m for m in _ALL_QWEN3_IDS if m not in EXPERIMENTAL_MODELS)
 
@@ -120,6 +197,7 @@ class SupportedModel:
     modalities: tuple[str, ...] = ()
     training_modes: tuple[str, ...] = ()
     lifecycle: str = "core"  # "core" | "experimental"
+    supports_thinking: bool = False  # Whether model supports <think> reasoning tags
 
     def as_dict(self) -> dict[str, object]:
         data: dict[str, object] = {
@@ -127,6 +205,7 @@ class SupportedModel:
             "family": self.family,
             "provider": self.provider,
             "lifecycle": self.lifecycle,
+            "supports_thinking": self.supports_thinking,
         }
         if self.modalities:
             data["modalities"] = list(self.modalities)
@@ -150,6 +229,7 @@ SUPPORTED_MODELS: tuple[SupportedModel, ...] = tuple(
             )
         ),
         lifecycle=("experimental" if model in EXPERIMENTAL_MODELS else "core"),
+        supports_thinking=(model in THINKING_MODELS),
     )
     for model in _ALL_QWEN3_IDS
 )
@@ -347,11 +427,66 @@ def training_modes_for_model(model_id: str) -> tuple[str, ...]:
     return model.training_modes
 
 
+def supports_thinking(model_id: str) -> bool:
+    """Return True if the model supports <think> reasoning tags.
+    
+    Thinking models use structured <think>...</think> tags for reasoning.
+    Instruct models do not have these tags and should not use thinking-specific logic.
+    
+    Args:
+        model_id: Model identifier (can include prefixes like 'rl:', 'fft:', etc.)
+        
+    Returns:
+        True if the model supports thinking tags, False otherwise.
+        Returns False for unsupported models.
+        
+    Example:
+        >>> supports_thinking("Qwen/Qwen3-4B-Thinking-2507")
+        True
+        >>> supports_thinking("Qwen/Qwen3-4B-Instruct-2507")
+        False
+        >>> supports_thinking("rl:Qwen/Qwen3-4B-Thinking-2507")
+        True
+    """
+    try:
+        canonical = ensure_supported_model(model_id, allow_finetuned_prefixes=True)
+    except UnsupportedModelError:
+        return False
+    model = _MODEL_BY_ID.get(canonical)
+    if not model:
+        return False
+    return model.supports_thinking
+
+
+def get_model_metadata(model_id: str) -> SupportedModel | None:
+    """Return the full metadata for a supported model, or None if not supported.
+    
+    Args:
+        model_id: Model identifier (can include prefixes like 'rl:', 'fft:', etc.)
+        
+    Returns:
+        SupportedModel instance with full metadata, or None if model is not supported.
+        
+    Example:
+        >>> meta = get_model_metadata("Qwen/Qwen3-4B-Instruct-2507")
+        >>> meta.supports_thinking
+        False
+        >>> meta.training_modes
+        ('rl', 'sft')
+    """
+    try:
+        canonical = ensure_supported_model(model_id, allow_finetuned_prefixes=True)
+    except UnsupportedModelError:
+        return None
+    return _MODEL_BY_ID.get(canonical)
+
+
 __all__ = [
     "QWEN3_MODELS",
     "QWEN3_CODER_MODELS",
     "RL_SUPPORTED_MODELS",
     "SFT_SUPPORTED_MODELS",
+    "THINKING_MODELS",
     "EXPERIMENTAL_MODELS",
     "CORE_MODELS",
     "ExperimentalWarning",
@@ -373,5 +508,7 @@ __all__ = [
     "core_model_ids",
     "format_supported_models",
     "training_modes_for_model",
+    "supports_thinking",
+    "get_model_metadata",
 ]
 

synth_ai/api/train/__init__.py

@@ -1,5 +1,17 @@
 from __future__ import annotations
 
-from .cli import register, train_command
+from typing import Any
 
 __all__ = ["register", "train_command"]
+
+
+def register(cli: Any) -> None:
+    from synth_ai.cli.train import register as _register  # local import avoids circular dependency
+
+    _register(cli)
+
+
+def train_command(*args: Any, **kwargs: Any) -> Any:
+    from synth_ai.cli.train import train_command as _train_command  # local import avoids cycle
+
+    return _train_command(*args, **kwargs)

synth_ai/api/train/cli.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import importlib
 import os
+import time
 from collections.abc import Callable, Mapping
 from pathlib import Path
 from typing import Any, cast
@@ -36,20 +37,41 @@ from .utils import (
 )
 
 
-def _discover_dataset_candidates(config_path: Path, limit: int = 50) -> list[Path]:
+def _discover_dataset_candidates(
+    config_path: Path, limit: int = 50, timeout: float = 10.0
+) -> list[Path]:
+    root = config_path.parent
+    parent = root.parent
+    cwd = Path.cwd()
+
     search_dirs: list[Path] = [
-        config_path.parent,
-        config_path.parent / "datasets",
-        REPO_ROOT / "traces",
+        root,
+        root / "datasets",
+        parent,
+        parent / "datasets",
+        parent / "ft_data",
+        cwd,
+        cwd / "datasets",
+        cwd / "ft_data",
         REPO_ROOT / "datasets",
+        REPO_ROOT / "ft_data",
+        REPO_ROOT / "traces",
     ]
 
     candidates: list[Path] = []
     seen: set[Path] = set()
+    start = time.monotonic()
+    timed_out = False
     for directory in search_dirs:
+        if timed_out or time.monotonic() - start > timeout:
+            timed_out = True
+            break
         if not directory.exists() or not directory.is_dir():
             continue
         for path in directory.rglob("*.jsonl"):
+            if time.monotonic() - start > timeout:
+                timed_out = True
+                break
             try:
                 resolved = path.resolve()
             except OSError:
@@ -300,7 +322,7 @@ def train_command(
 def _wait_for_training_file(
     backend_base: str, api_key: str, file_id: str, *, timeout: float = 120.0
 ) -> None:
-    url = f"{backend_base}/learning/files/{file_id}"
+    url = f"{backend_base.rstrip('/')}/files/{file_id}"
     headers = {"Authorization": f"Bearer {api_key}"}
     elapsed = 0.0
     interval = 2.0
@@ -524,7 +546,7 @@ def handle_sft(
             click.echo("Validating validation dataset…")
             validate_sft_jsonl(build.validation_file)
 
-        upload_url = f"{backend_base}/learning/files"
+        upload_url = f"{backend_base.rstrip('/')}/files"
         click.echo("\n=== Uploading Training Data ===")
         click.echo(f"Dataset: {build.train_file}")
         click.echo(f"Destination: {upload_url}")
@@ -579,7 +601,8 @@ def handle_sft(
         try:
             _wait_for_training_file(backend_base, synth_key, train_file_id)
         except click.ClickException as exc:
-            raise click.ClickException(f"Training file {train_file_id} not ready: {exc}") from exc
+            click.echo(f"[WARN] File readiness check failed: {exc}")
+            click.echo("Proceeding anyway - backend will validate file during job creation...")
 
         click.echo("\n=== Creating Training Job ===")
         click.echo("Job payload preview:")

synth_ai/api/train/config_finder.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import json
-import os
 from collections.abc import Iterable
 from dataclasses import dataclass
 from pathlib import Path
@@ -11,7 +10,9 @@ import click
 from .utils import REPO_ROOT, load_toml, preview_json
 
 _SKIP_DIRS = {".git", "__pycache__", ".venv", "node_modules", "dist", "build"}
-_STATE_FILE = os.path.expanduser("~/.synth-ai/demo.json")
+
+_STATE_DIR = Path.home() / ".synth-ai"
+_STATE_FILE = _STATE_DIR / "train_cli.json"
 
 
 @dataclass(slots=True)
@@ -23,8 +24,8 @@ class ConfigCandidate:
 def _load_last_config() -> Path | None:
     """Load the last used training config path from state file."""
     try:
-        if os.path.isfile(_STATE_FILE):
-            with open(_STATE_FILE) as fh:
+        if _STATE_FILE.is_file():
+            with _STATE_FILE.open() as fh:
                 data = json.load(fh)
                 if isinstance(data, dict):
                     last_config = data.get("LAST_CONFIG")
@@ -41,14 +42,14 @@ def _save_last_config(config_path: Path) -> None:
     """Save the last used training config path to state file."""
     try:
         data = {}
-        if os.path.isfile(_STATE_FILE):
-            with open(_STATE_FILE) as fh:
+        if _STATE_FILE.is_file():
+            with _STATE_FILE.open() as fh:
                 data = json.load(fh) or {}
         if not isinstance(data, dict):
             data = {}
         data["LAST_CONFIG"] = str(config_path.resolve())
-        os.makedirs(os.path.dirname(_STATE_FILE), exist_ok=True)
-        with open(_STATE_FILE, "w") as fh:
+        _STATE_DIR.mkdir(parents=True, exist_ok=True)
+        with _STATE_FILE.open("w") as fh:
             json.dump(data, fh)
     except Exception:
         pass
@@ -77,6 +78,7 @@ def _iter_candidate_paths() -> Iterable[Path]:
         REPO_ROOT / "configs",
         REPO_ROOT / "examples",
         REPO_ROOT / "training",
+        REPO_ROOT / "synth_ai" / "demos",
     ]
     for base in preferred:
         if not base.exists():
@@ -148,6 +150,10 @@ def discover_configs(explicit: list[str], *, requested_type: str | None) -> list
             raise click.ClickException(f"Config not found: {path}")
         data = load_toml(path)
         cfg_type = _infer_config_type(data)
+        if cfg_type == "unknown":
+            raise click.ClickException(
+                f"Config {path} is missing algorithm.type/method metadata. Add type = 'rl' or 'sft'."
+            )
         candidates.append(ConfigCandidate(path=path, train_type=cfg_type))
         seen.add(path)
 
@@ -162,10 +168,12 @@ def discover_configs(explicit: list[str], *, requested_type: str | None) -> list
         except Exception:
             continue
         cfg_type = _infer_config_type(data)
+        if cfg_type == "unknown":
+            continue
         candidates.append(ConfigCandidate(path=path, train_type=cfg_type))
 
     if requested_type and requested_type != "auto":
-        candidates = [c for c in candidates if c.train_type in {requested_type, "unknown"}]
+        candidates = [c for c in candidates if c.train_type == requested_type]
 
     # De-dupe by path and keep deterministic ordering by directory depth then name
     candidates.sort(key=lambda c: (len(c.path.parts), str(c.path)))
@@ -196,9 +204,8 @@ def prompt_for_config(
 
     click.echo("Select a training config:")
     for idx, cand in enumerate(candidates, start=1):
-        label = cand.train_type if cand.train_type != "unknown" else "?"
         last_marker = " (last used)" if last_config and cand.path.resolve() == last_config else ""
-        click.echo(f"  {idx}) [{label}] {cand.path}{last_marker}")
+        click.echo(f"  {idx}) {cand.path}{last_marker}")
     click.echo("  0) Abort")
 
     choice = click.prompt("Enter choice", type=int, default=default_idx)

synth_ai/api/train/env_resolver.py

@@ -8,6 +8,7 @@ from pathlib import Path
 from typing import Any, cast
 
 import click
+from synth_ai.utils.env import resolve_env_var
 
 from . import task_app
 from .utils import REPO_ROOT, mask_value, read_env_file, write_env_value
@@ -232,18 +233,16 @@ def _resolve_key(resolver: EnvResolver, spec: KeySpec) -> str:
             _maybe_persist(resolver, spec, env_val)
             os.environ[spec.name] = env_val
             return env_val
-        options: list[tuple[str, Callable[[], str | None]]] = []
 
-        def _enter_manual() -> str:
-            prompt = f"Enter {spec.description}" if spec.description else f"Enter {spec.name}"
-            value = click.prompt(prompt, hide_input=spec.secret).strip()
-            if not value:
-                raise click.ClickException(f"{spec.name} cannot be empty")
-            _maybe_persist(resolver, spec, value)
-            os.environ[spec.name] = value
-            return value
+        resolve_env_var(spec.name)
+        resolved_value = os.environ.get(spec.name)
+        if resolved_value:
+            click.echo(f"Found {spec.name} via secrets helper: {mask_value(resolved_value)}")
+            _maybe_persist(resolver, spec, resolved_value)
+            os.environ[spec.name] = resolved_value
+            return resolved_value
 
-        options.append(("Enter manually", _enter_manual))
+        options: list[tuple[str, Callable[[], str | None]]] = []
 
         def _pick_env() -> str | None:
             resolver.select_new_env()
@@ -276,6 +275,10 @@ def _resolve_key(resolver: EnvResolver, spec: KeySpec) -> str:
 
 def _maybe_persist(resolver: EnvResolver, spec: KeySpec, value: str) -> None:
     # Automatically save (no prompt)
+    # Skip auto-persisting TASK_APP_URL to prevent overwriting CLI overrides
+    if spec.name == "TASK_APP_URL":
+        click.echo(f"Skipping auto-persist for {spec.name} (use CLI flags to override)")
+        return
     resolver.set_value(spec.name, value)
     click.echo(f"Saved {spec.name} to {resolver.current_path}")