fix(lib): default 'agentex agents build' to --no-cache so stale layers can't ship stale source (#476)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: deepthi-rao-scale

src/agentex/lib/cli/commands/agents.py

@@ -127,6 +127,13 @@ def build(
         None,
         help="Docker build argument in the format 'KEY=VALUE' (can be used multiple times)",
     ),
+    cache: bool = typer.Option(
+        False,
+        "--cache/--no-cache",
+        help="Whether to use the build cache. Defaults to off so a stale cached layer "
+        "can't silently ship source that no longer matches the checkout (notably when "
+        "republishing a moving tag like ':latest'). Pass --cache to opt back in.",
+    ),
 ):
     """
     Build an agent image locally from the given manifest.
@@ -155,6 +162,7 @@ def build(
             secret=secret or "",  # Provide default empty string
             tag=tag or "latest",  # Provide default
             build_args=build_arg or [],  # Provide default empty list
+            cache=cache,
         )
         if image_url:
             typer.echo(f"Successfully built image: {image_url}")

src/agentex/lib/cli/handlers/agent_handlers.py

@@ -39,6 +39,7 @@ def build_agent(
     secret: str | None = None,
     tag: str | None = None,
     build_args: list[str] | None = None,
+    cache: bool = False,
 ) -> str:
     """Build the agent locally and optionally push to registry
 
@@ -49,6 +50,10 @@ def build_agent(
         secret: Docker build secret in format 'id=secret-id,src=path-to-secret-file'
         tag: Image tag to use (defaults to 'latest')
         build_args: List of Docker build arguments in format 'KEY=VALUE'
+        cache: Whether to use the build cache. Defaults to False (passes --no-cache to
+            buildx) so a stale cached layer can't silently ship source that no longer
+            matches the checkout, notably when republishing a moving tag like ':latest'.
+            Pass True to opt back in for faster local rebuilds.
 
     Returns:
         The image URL
@@ -85,7 +90,10 @@ def build_agent(
                 "file": str(build_context.path / build_context.dockerfile_path),  # type: ignore[operator]
                 "tags": [image_name],
                 "platforms": platforms,
+                "cache": cache,  # cache=False -> `docker buildx build --no-cache`
             }
+            if not cache:
+                logger.info("Build cache disabled (--no-cache)")
 
             # Add Docker build args if provided
             if build_args: