dh-cli 0.12.4__tar.gz → 0.12.6__tar.gz

{dh_cli-0.12.4 → dh_cli-0.12.6}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: dh-cli
-Version: 0.12.4
+Version: 0.12.6
 Summary: Dayhoff Labs developer CLI
 Author-email: Dayhoff Labs <dev@dayhofflabs.com>
 License: # PolyForm Noncommercial License 1.0.0

{dh_cli-0.12.4 → dh_cli-0.12.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dh-cli"
-version = "0.12.4"
+version = "0.12.6"
 description = "Dayhoff Labs developer CLI"
 requires-python = ">=3.11"
 readme = "README.md"

{dh_cli-0.12.4 → dh_cli-0.12.6}/src/dh_cli/batch/aws_batch.py

@@ -2,6 +2,7 @@
 
 import logging
 import re
+import socket
 import time
 from dataclasses import dataclass
 from typing import Any
@@ -9,6 +10,7 @@ from typing import Any
 import boto3
 from botocore.exceptions import ClientError
 
+from dh_cli.batch.job_id import get_aws_username
 from dh_cli.batch.manifest import (
     BATCH_JOBS_BASE,
     JobStatus,
@@ -29,6 +31,36 @@ class BatchError(Exception):
     pass
 
 
+def _pipeline_from_definition(job_definition: str) -> str:
+    """Derive the pipeline name from a job definition name or ARN.
+
+    'dayhoff-embed-t5', 'dayhoff-embed-t5:3' and the full ARN all yield
+    'embed-t5'. Falls back to the bare definition name if the 'dayhoff-'
+    prefix is absent.
+    """
+    name = job_definition.rsplit("/", 1)[-1].split(":")[0]
+    return name.removeprefix("dayhoff-")
+
+
+def _tag_user() -> str:
+    """Username for the User cost tag.
+
+    'root' means get_aws_username() hit its getpass fallback in a container —
+    tagging it would collapse many people into one bucket, invisibly. Tag
+    unknown-<hostname> instead and say how to fix it.
+    """
+    username = get_aws_username()
+    if username == "root":
+        hostname = socket.gethostname()
+        logger.warning(
+            "Could not resolve your AWS username (got system user 'root'); "
+            f"tagging this job User=unknown-{hostname}. "
+            "Set AWS_SSO_USER or run 'dh aws login' to fix cost attribution."
+        )
+        return f"unknown-{hostname}"
+    return username
+
+
 @dataclass
 class ArrayJobStatus:
     """Aggregated status for an array job."""
@@ -90,6 +122,7 @@ class BatchClient:
         gpus: int | None = None,
         image_override: str | None = None,
         command: list[str] | None = None,
+        project: str | None = None,
     ) -> str:
         """Submit a job to AWS Batch.
 
@@ -103,6 +136,7 @@ class BatchClient:
             timeout_seconds: Job timeout in seconds
             retry_attempts: Number of retry attempts
             depends_on: Job dependencies
+            project: Value for the Project cost tag (defaults to "unspecified")
 
         Returns:
             AWS Batch job ID
@@ -119,6 +153,16 @@ class BatchClient:
                 "jobDefinition": job_definition,
                 "jobQueue": job_queue,
                 "retryStrategy": {"attempts": retry_attempts},
+                # Cost attribution: propagated to the ECS task, split per task
+                # by SCAD. JobId is the dh job ID (the job name), not the AWS
+                # UUID, so humans can correlate with `dh batch status`.
+                "tags": {
+                    "User": _tag_user(),
+                    "Pipeline": _pipeline_from_definition(job_definition),
+                    "Project": project or "unspecified",
+                    "JobId": job_name,
+                },
+                "propagateTags": True,
             }
 
             if array_size and array_size > 1:

{dh_cli-0.12.4 → dh_cli-0.12.6}/src/dh_cli/batch/commands/submit.py

@@ -33,6 +33,7 @@ DEFAULT_QUEUE = "t4-1x-spot"
 @click.option("--retry", default=3, type=int, help="Retry attempts")
 @click.option("--timeout", default="6h", help="Job timeout (e.g., 6h, 1d)")
 @click.option("--image", help="Pre-built image URI")
+@click.option("--project", help="Project cost tag (defaults to 'unspecified')")
 @click.option("--env", multiple=True, help="Environment variables (KEY=VALUE)")
 @click.option("--dry-run", is_flag=True, help="Show plan without submitting")
 @click.option("--base-path", default=BATCH_JOBS_BASE, help="Base path for job data")
@@ -50,6 +51,7 @@ def submit(
     retry,
     timeout,
     image,
+    project,
     env,
     dry_run,
     base_path,
@@ -84,6 +86,7 @@ def submit(
       retry: 3
       timeout: 6h
       image: custom-image:tag
+      project: my-campaign   # Project cost tag (optional)
       env:
         MY_VAR: value
     """
@@ -116,6 +119,7 @@ def submit(
     job_retry = _pick("retry", retry)
     job_timeout = _pick("timeout", timeout)
     job_image = image or config.get("image")
+    job_project = project or config.get("project")
     if job_image and not _ECR_IMAGE_RE.match(job_image):
         raise click.BadParameter(
             f"--image must be a fully-qualified ECR URL "
@@ -214,6 +218,7 @@ def submit(
             depends_on=depends_on,
             share_identifier=get_aws_username(),
             image_override=job_image,
+            project=job_project,
         )
 
         # Update manifest with Batch job ID

{dh_cli-0.12.4 → dh_cli-0.12.6}/src/dh_cli/cloud_commands.py

@@ -19,6 +19,7 @@ import re
 import shutil
 import subprocess
 import sys
+import time
 from pathlib import Path
 from typing import List, Optional, Tuple
 
@@ -29,6 +30,8 @@ import typer
 GCP_PROJECT_ID = "enzyme-discovery"
 AWS_DEFAULT_PROFILE = "dev-devaccess"
 AWS_CONFIG_FILE = Path.home() / ".aws" / "config"
+AWS_SSO_CACHE_DIR = Path.home() / ".aws" / "sso" / "cache"
+NETRC_FILE = Path.home() / ".netrc"
 SHELL_RC_FILES = [
     Path.home() / ".bashrc",
     Path.home() / ".bash_profile",
@@ -398,6 +401,55 @@ def _is_aws_profile_authenticated(profile: str) -> bool:
     return returncode == 0
 
 
+def _print_sso_session_status() -> None:
+    """Print the cached SSO access token's expiry, and note what it isn't.
+
+    A cache dir holds both the client-registration file and the access-token
+    file, and both carry `expiresAt` - the registration one is weeks out, the
+    token's is hours out. They're told apart by content shape (presence of
+    `accessToken`), never by glob order, mtime, or filename, since either of
+    those picked the registration file on the box this was written for and
+    reported six weeks of headroom that didn't exist.
+    """
+    access_token_expiry = None
+    if AWS_SSO_CACHE_DIR.is_dir():
+        for cache_file in AWS_SSO_CACHE_DIR.glob("*.json"):
+            try:
+                data = json.loads(cache_file.read_text())
+            except (OSError, ValueError):
+                continue
+            if isinstance(data, dict) and "accessToken" in data:
+                access_token_expiry = data.get("expiresAt")
+                break
+
+    # The token is refreshed silently on ~1h cycles; the 8h portal session it
+    # rides on is not visible from inside the container at all, so the note
+    # below must stand on its own when no expiry was printed above.
+    if access_token_expiry:
+        print(f"{BLUE}SSO access token expires:{NC} {access_token_expiry}")
+        print(
+            f"{YELLOW}Note: the AWS SSO portal session's lifetime is not locally "
+            f"observable from here; the access token expiry above is not that window.{NC}"
+        )
+    else:
+        print(f"{YELLOW}Note: the AWS SSO portal session's lifetime is not locally observable from here.{NC}")
+
+
+def _print_netrc_age() -> None:
+    """Print the age of ~/.netrc.
+
+    The CodeArtifact token it holds carries no expiry, so age is the only
+    signal available, and it gates `pixi install` (and therefore `dh` itself).
+    """
+    if not NETRC_FILE.exists():
+        return
+    try:
+        age_hours = (time.time() - NETRC_FILE.stat().st_mtime) / 3600
+    except OSError:
+        return
+    print(f"{BLUE}~/.netrc age:{NC} {age_hours:.1f} hours")
+
+
 def _run_aws_sso_login(profile: str) -> None:
     """Run the AWS SSO login command for a specific profile."""
     aws_path = _find_executable("aws")
@@ -590,13 +642,19 @@ def aws_status(
     profile: Optional[str] = typer.Option(None, "--profile", "-p", help="Check specific profile instead of current."),
 ):
     """Show current AWS authentication status."""
-    target_profile = profile or _get_current_aws_profile()
+    try:
+        target_profile = profile or _get_current_aws_profile()
+        authenticated = _is_aws_profile_authenticated(target_profile)
+        aws_path = _find_executable("aws")
+    except FileNotFoundError as e:
+        print(f"{RED}Could not determine AWS status: {e}{NC}", file=sys.stderr)
+        raise typer.Exit(6)
+
     print(f"{BLUE}AWS profile:{NC} {GREEN}{target_profile}{NC}")
 
-    if _is_aws_profile_authenticated(target_profile):
+    if authenticated:
         print(f"Credential status: {GREEN}valid{NC}")
         # Get detailed identity information
-        aws_path = _find_executable("aws")
         _run_command(
             [
                 aws_path,
@@ -612,6 +670,12 @@ def aws_status(
         print("\nTo authenticate, run:")
         print(f"  {YELLOW}dh aws login{NC}")
 
+    _print_sso_session_status()
+    _print_netrc_age()
+
+    if not authenticated:
+        raise typer.Exit(5)
+
 
 @aws_app.command("login")
 def aws_login(

{dh_cli-0.12.4 → dh_cli-0.12.6}/src/dh_cli/engines_studios/engine_commands.py

@@ -147,9 +147,7 @@ def launch_engine(
         # Launch the engine, retrying transient AWS capacity errors by default.
         retry = _make_capacity_retry(engine_type, no_retry, retry_timeout, retry_interval)
         engine = retry(
-            lambda: client.launch_engine(
-                name=name, user=user, engine_type=engine_type, boot_disk_size=boot_disk_size
-            )
+            lambda: client.launch_engine(name=name, user=user, engine_type=engine_type, boot_disk_size=boot_disk_size)
         )
 
         engine_id = engine["instance_id"]

dh_cli-0.12.6/tests/batch/test_submit_job_tags.py

@@ -0,0 +1,157 @@
+"""Tests for cost-attribution tags on BatchClient.submit_job.
+
+Tags are defaulted inside submit_job — no call site passes them. They pin:
+- the four keys User/Pipeline/Project/JobId and propagateTags=True (AC-1)
+- User from get_aws_username(), JobId = the dh job name (AC-2)
+- Pipeline derived from the job definition name (AC-5)
+- Project defaults to "unspecified", overridable per submission (AC-5)
+- the root-fallback guard tagging User=unknown-<hostname> (AC-6)
+- both submit_array_retry re-entry paths produce tagged jobs (AC-4)
+"""
+
+from unittest.mock import MagicMock, patch
+
+
+def _make_client():
+    """Construct a BatchClient with mocked boto3 batch/logs clients."""
+    with patch("dh_cli.batch.aws_batch.boto3") as mock_boto3:
+        mock_batch = MagicMock()
+        mock_logs = MagicMock()
+        mock_boto3.client.side_effect = [mock_batch, mock_logs]
+        mock_batch.submit_job.return_value = {"jobId": "aws-uuid"}
+
+        from dh_cli.batch.aws_batch import BatchClient
+
+        client = BatchClient()
+        return client, mock_batch
+
+
+def _submit(client, **overrides):
+    kwargs = dict(
+        job_name="dma-boltz-20260810-a3f2c9e1",
+        job_definition="dayhoff-boltz",
+        job_queue="a10g-1x-spot",
+    )
+    kwargs.update(overrides)
+    return client.submit_job(**kwargs)
+
+
+@patch("dh_cli.batch.aws_batch.get_aws_username", return_value="dma")
+class TestSubmitJobTags:
+    def test_no_tag_parameters_in_signature(self, _mock_user):
+        """AC-3: tags are defaulted inside submit_job — call sites have no
+        tag argument to pass (or forget)."""
+        import inspect
+
+        from dh_cli.batch.aws_batch import BatchClient
+
+        params = inspect.signature(BatchClient.submit_job).parameters
+        assert "tags" not in params
+        assert "propagate_tags" not in params
+
+    def test_sends_exactly_four_tag_keys_and_propagate(self, _mock_user):
+        client, mock_batch = _make_client()
+        _submit(client)
+        submit_args = mock_batch.submit_job.call_args[1]
+        assert submit_args["propagateTags"] is True
+        assert set(submit_args["tags"]) == {"User", "Pipeline", "Project", "JobId"}
+
+    def test_user_is_aws_username_and_jobid_is_dh_job_name(self, _mock_user):
+        client, mock_batch = _make_client()
+        _submit(client)
+        tags = mock_batch.submit_job.call_args[1]["tags"]
+        assert tags["User"] == "dma"
+        assert tags["JobId"] == "dma-boltz-20260810-a3f2c9e1"
+
+    def test_pipeline_derived_from_job_definition(self, _mock_user):
+        client, mock_batch = _make_client()
+        for definition, expected in [
+            ("dayhoff-embed-t5", "embed-t5"),
+            ("dayhoff-boltz", "boltz"),
+            ("dayhoff-generic", "generic"),
+            # ARN form, as produced by _register_image_override
+            (
+                "arn:aws:batch:us-east-1:074735440724:job-definition/dayhoff-rfd3:7",
+                "rfd3",
+            ),
+            # Name:revision form
+            ("dayhoff-esmfold2:3", "esmfold2"),
+        ]:
+            _submit(client, job_definition=definition)
+            tags = mock_batch.submit_job.call_args[1]["tags"]
+            assert tags["Pipeline"] == expected, definition
+
+    def test_project_defaults_to_unspecified(self, _mock_user):
+        client, mock_batch = _make_client()
+        _submit(client)
+        tags = mock_batch.submit_job.call_args[1]["tags"]
+        assert tags["Project"] == "unspecified"
+
+    def test_project_overridable_per_submission(self, _mock_user):
+        client, mock_batch = _make_client()
+        _submit(client, project="cost-attribution")
+        tags = mock_batch.submit_job.call_args[1]["tags"]
+        assert tags["Project"] == "cost-attribution"
+
+    def test_share_identifier_behaviour_unchanged(self, _mock_user):
+        client, mock_batch = _make_client()
+        _submit(client, share_identifier="dma")
+        submit_args = mock_batch.submit_job.call_args[1]
+        assert submit_args["shareIdentifier"] == "dma"
+        assert submit_args["schedulingPriorityOverride"] == 0
+
+
+class TestRootFallbackGuard:
+    """AC-6: getpass-fallback 'root' must not become the User tag."""
+
+    @patch("dh_cli.batch.aws_batch.socket.gethostname", return_value="devbox9")
+    @patch("dh_cli.batch.aws_batch.get_aws_username", return_value="root")
+    def test_root_user_tagged_unknown_hostname_with_warning(self, _mock_user, _mock_host, caplog):
+        client, mock_batch = _make_client()
+        import logging
+
+        with caplog.at_level(logging.WARNING):
+            _submit(client)
+        tags = mock_batch.submit_job.call_args[1]["tags"]
+        assert tags["User"] == "unknown-devbox9"
+        assert any("AWS_SSO_USER" in r.message for r in caplog.records)
+
+    @patch("dh_cli.batch.aws_batch.get_aws_username", return_value="dma")
+    def test_non_root_user_emits_no_warning(self, _mock_user, caplog):
+        client, mock_batch = _make_client()
+        import logging
+
+        with caplog.at_level(logging.WARNING):
+            _submit(client)
+        assert not any("AWS_SSO_USER" in r.message for r in caplog.records)
+
+
+@patch("dh_cli.batch.aws_batch.get_aws_username", return_value="dma")
+class TestArrayRetryReentriesTagged:
+    """AC-4: both submit_array_retry re-entry paths produce tagged jobs."""
+
+    def test_single_index_reentry_tagged(self, _mock_user):
+        client, mock_batch = _make_client()
+        client.submit_array_job_with_indices(
+            job_name="dma-embed-20260810-a3f2c9e1-r1",
+            job_definition="dayhoff-embed-t5",
+            job_queue="t4-1x-spot",
+            indices=[7],
+        )
+        submit_args = mock_batch.submit_job.call_args[1]
+        assert submit_args["propagateTags"] is True
+        assert submit_args["tags"]["Pipeline"] == "embed-t5"
+        assert submit_args["tags"]["JobId"] == "dma-embed-20260810-a3f2c9e1-r1"
+
+    def test_multi_index_reentry_tagged(self, _mock_user):
+        client, mock_batch = _make_client()
+        client.submit_array_job_with_indices(
+            job_name="dma-embed-20260810-a3f2c9e1-r1",
+            job_definition="dayhoff-embed-t5",
+            job_queue="t4-1x-spot",
+            indices=[3, 5, 9],
+        )
+        submit_args = mock_batch.submit_job.call_args[1]
+        assert submit_args["propagateTags"] is True
+        assert submit_args["tags"]["Pipeline"] == "embed-t5"
+        assert submit_args["tags"]["User"] == "dma"

{dh_cli-0.12.4 → dh_cli-0.12.6}/tests/batch/test_submit_merge.py

@@ -203,6 +203,44 @@ class TestArrayAndRetryMerge:
         assert mock_client.submit_job.call_args[1]["retry_attempts"] == 5
 
 
+class TestProjectOption:
+    """--project / YAML `project` forwards to submit_job's project kwarg
+    (the Project cost tag); absent everywhere, None is forwarded and
+    submit_job defaults the tag to "unspecified"."""
+
+    def test_cli_project_forwarded(self, cli_runner, tmp_path):
+        result, mock_client = _invoke(
+            cli_runner,
+            ["--command", "echo hi", "--project", "cost-attribution"],
+            tmp_path,
+        )
+        assert result.exit_code == 0, result.output
+        assert mock_client.submit_job.call_args[1]["project"] == "cost-attribution"
+
+    def test_yaml_project_wins_when_cli_omitted(self, cli_runner, tmp_path):
+        config_path = tmp_path / "job.yaml"
+        config_path.write_text(yaml.dump({"command": "echo hi", "project": "gauntlet"}))
+        result, mock_client = _invoke(cli_runner, ["-f", str(config_path)], tmp_path)
+        assert result.exit_code == 0, result.output
+        assert mock_client.submit_job.call_args[1]["project"] == "gauntlet"
+
+    def test_cli_project_beats_yaml(self, cli_runner, tmp_path):
+        config_path = tmp_path / "job.yaml"
+        config_path.write_text(yaml.dump({"command": "echo hi", "project": "gauntlet"}))
+        result, mock_client = _invoke(
+            cli_runner,
+            ["-f", str(config_path), "--project", "poise"],
+            tmp_path,
+        )
+        assert result.exit_code == 0, result.output
+        assert mock_client.submit_job.call_args[1]["project"] == "poise"
+
+    def test_absent_everywhere_forwards_none(self, cli_runner, tmp_path):
+        result, mock_client = _invoke(cli_runner, ["--command", "echo hi"], tmp_path)
+        assert result.exit_code == 0, result.output
+        assert mock_client.submit_job.call_args[1]["project"] is None
+
+
 class TestGpuRegressionFromReport:
     """The specific surprising case called out in the plan: a caller
     who does `--gpus 1 -f yaml-with-gpus-zero.yaml` expects a GPU job,

{dh_cli-0.12.4 → dh_cli-0.12.6}/tests/engines_studios/test_retry.py

@@ -36,9 +36,7 @@ def test_returns_immediately_on_success():
         calls.append(1)
         return "ok"
 
-    result = retry_on_capacity(
-        action, timeout=600, interval=30, monotonic=clock.monotonic, sleep=clock.sleep
-    )
+    result = retry_on_capacity(action, timeout=600, interval=30, monotonic=clock.monotonic, sleep=clock.sleep)
 
     assert result == "ok"
     assert len(calls) == 1
@@ -53,14 +51,11 @@ def test_retries_capacity_error_then_succeeds():
         attempts["n"] += 1
         if attempts["n"] < 3:
             raise RuntimeError(
-                "Failed to launch instance: An error occurred "
-                "(InsufficientInstanceCapacity) when calling RunInstances"
+                "Failed to launch instance: An error occurred (InsufficientInstanceCapacity) when calling RunInstances"
             )
         return "launched"
 
-    result = retry_on_capacity(
-        action, timeout=600, interval=30, monotonic=clock.monotonic, sleep=clock.sleep
-    )
+    result = retry_on_capacity(action, timeout=600, interval=30, monotonic=clock.monotonic, sleep=clock.sleep)
 
     assert result == "launched"
     assert attempts["n"] == 3
@@ -77,9 +72,7 @@ def test_non_capacity_error_propagates_without_retry():
         raise RuntimeError("VcpuLimitExceeded: vCPU quota exceeded")
 
     with pytest.raises(RuntimeError, match="VcpuLimitExceeded"):
-        retry_on_capacity(
-            action, timeout=600, interval=30, monotonic=clock.monotonic, sleep=clock.sleep
-        )
+        retry_on_capacity(action, timeout=600, interval=30, monotonic=clock.monotonic, sleep=clock.sleep)
 
     assert attempts["n"] == 1
     assert clock.slept == []
@@ -94,9 +87,7 @@ def test_reraises_last_capacity_error_after_budget_exhausted():
         raise RuntimeError("InsufficientInstanceCapacity: no capacity")
 
     with pytest.raises(RuntimeError, match="InsufficientInstanceCapacity"):
-        retry_on_capacity(
-            action, timeout=60, interval=30, monotonic=clock.monotonic, sleep=clock.sleep
-        )
+        retry_on_capacity(action, timeout=60, interval=30, monotonic=clock.monotonic, sleep=clock.sleep)
 
     # attempt@t=0 fails; next attempt (t=30) fits in the 60s budget -> sleep 30.
     # attempt@t=30 fails; next attempt (t=60) would NOT be < 60 -> stop, no sleep.
@@ -113,9 +104,7 @@ def test_timeout_zero_means_single_attempt():
         raise RuntimeError("InsufficientInstanceCapacity")
 
     with pytest.raises(RuntimeError, match="InsufficientInstanceCapacity"):
-        retry_on_capacity(
-            action, timeout=0, interval=30, monotonic=clock.monotonic, sleep=clock.sleep
-        )
+        retry_on_capacity(action, timeout=0, interval=30, monotonic=clock.monotonic, sleep=clock.sleep)
 
     assert attempts["n"] == 1
     assert clock.slept == []
@@ -162,9 +151,7 @@ def test_keyboard_interrupt_during_sleep_propagates():
         raise RuntimeError("InsufficientInstanceCapacity")
 
     with pytest.raises(KeyboardInterrupt):
-        retry_on_capacity(
-            action, timeout=600, interval=30, monotonic=clock.monotonic, sleep=clock.sleep
-        )
+        retry_on_capacity(action, timeout=600, interval=30, monotonic=clock.monotonic, sleep=clock.sleep)
 
 
 @pytest.mark.parametrize(

dh_cli-0.12.6/tests/test_aws_status.py

@@ -0,0 +1,184 @@
+"""Exit-code and reporting contract for `dh aws status`.
+
+`dh aws status` is the one honest answer an unattended agent has about its own
+AWS credentials, so it must fail closed and must never overstate the window it
+can see:
+
+  0 — authenticated
+  5 — unauthenticated
+  6 — could not tell (e.g. no `aws` binary)
+
+`2` stays reserved for typer's UsageError. 5 and 6 are distinct on purpose: a
+caller must never confuse "credentials are gone" with "I could not determine
+it", because the safe response differs.
+
+All AWS interaction is mocked at `_run_command`; no credentials required. No
+test asserts on a token value, and every fixture token is a placeholder.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from pathlib import Path
+from unittest.mock import patch
+
+from click.testing import CliRunner
+from typer.main import get_command
+
+PLACEHOLDER_TOKEN = "PLACEHOLDER-NOT-A-REAL-TOKEN"
+
+REGISTRATION_FILE = {
+    "clientId": "placeholder-client-id",
+    "clientSecret": "PLACEHOLDER-CLIENT-SECRET",
+    "expiresAt": "2026-09-14T13:59:33Z",
+    "grantTypes": ["refresh_token", "urn:ietf:params:oauth:grant-type:device_code"],
+    "scopes": ["sso:account:access"],
+}
+
+ACCESS_TOKEN_FILE = {
+    "accessToken": PLACEHOLDER_TOKEN,
+    "clientId": "placeholder-client-id",
+    "clientSecret": "PLACEHOLDER-CLIENT-SECRET",
+    "expiresAt": "2026-08-13T04:00:00Z",
+    "refreshToken": PLACEHOLDER_TOKEN,
+    "region": "us-east-1",
+    "registrationExpiresAt": "2026-09-14T13:59:33Z",
+    "startUrl": "https://placeholder.awsapps.com/start",
+}
+
+
+def _invoke(
+    cache_dir: Path,
+    netrc_file: Path,
+    *,
+    authenticated: bool = True,
+    which_returns_path: bool = True,
+):
+    """Run `aws status` with the AWS CLI boundary and both files stubbed."""
+    from dh_cli import cloud_commands
+    from dh_cli.cloud_commands import aws_app
+
+    result_tuple = (0, '{"Arn": "arn:aws:sts::000000000000:assumed-role/placeholder/x"}', "")
+    if not authenticated:
+        result_tuple = (255, "", "Error loading SSO Token: Token has expired and refresh failed")
+
+    stack = [
+        patch.object(cloud_commands, "AWS_SSO_CACHE_DIR", cache_dir),
+        patch.object(cloud_commands, "NETRC_FILE", netrc_file),
+        patch.object(cloud_commands, "_run_command", return_value=result_tuple),
+        patch.dict(os.environ, {"AWS_PROFILE": "dev-devaccess"}, clear=False),
+    ]
+    if which_returns_path:
+        stack.append(patch.object(cloud_commands.shutil, "which", return_value="/usr/bin/aws"))
+    else:
+        stack.append(patch.object(cloud_commands.shutil, "which", return_value=None))
+
+    runner = CliRunner()
+    for ctx in stack:
+        ctx.start()
+    try:
+        return runner.invoke(get_command(aws_app), ["status"])
+    finally:
+        for ctx in reversed(stack):
+            ctx.stop()
+
+
+def _write_cache(tmp_path: Path) -> Path:
+    """Write both SSO cache shapes, with the registration file NEWER on disk."""
+    cache_dir = tmp_path / "sso" / "cache"
+    cache_dir.mkdir(parents=True)
+    token_path = cache_dir / "aaa11111.json"
+    token_path.write_text(json.dumps(ACCESS_TOKEN_FILE))
+    reg_path = cache_dir / "bbb22222.json"
+    reg_path.write_text(json.dumps(REGISTRATION_FILE))
+    # Registration file is both newer and alphabetically later: a glob taking
+    # the newest or the first hit must not be able to pass by accident.
+    old = time.time() - 86400
+    os.utime(token_path, (old, old))
+    return cache_dir
+
+
+def _netrc(tmp_path: Path, age_hours: float = 5.0) -> Path:
+    netrc_file = tmp_path / ".netrc"
+    netrc_file.write_text("machine placeholder.d.codeartifact.us-east-1.amazonaws.com\n")
+    stamp = time.time() - age_hours * 3600
+    os.utime(netrc_file, (stamp, stamp))
+    return netrc_file
+
+
+def test_authenticated_exits_0(tmp_path):
+    result = _invoke(_write_cache(tmp_path), _netrc(tmp_path), authenticated=True)
+    assert result.exit_code == 0, result.output
+
+
+def test_unauthenticated_exits_5(tmp_path):
+    """The whole point: `dh aws status && long_job` must not run the job."""
+    result = _invoke(_write_cache(tmp_path), _netrc(tmp_path), authenticated=False)
+    assert result.exit_code == 5, result.output
+    assert "not authenticated" in result.output.lower(), result.output
+
+
+def test_missing_aws_binary_exits_6_without_traceback(tmp_path):
+    """`_find_executable` raises FileNotFoundError today; a diagnostic must not
+    traceback when the thing it diagnoses is missing."""
+    result = _invoke(
+        _write_cache(tmp_path),
+        _netrc(tmp_path),
+        which_returns_path=False,
+    )
+    assert result.exit_code == 6, result.output
+    assert not isinstance(result.exception, FileNotFoundError), result.exception
+
+
+def test_reports_access_token_expiry_not_registration_expiry(tmp_path):
+    """The regression test for the trap.
+
+    Both cache files carry `expiresAt`. On a real box the registration file
+    read 2026-09-14 beside an access token expiring the same afternoon, so a
+    glob taking the newest or first hit reports six weeks of headroom that does
+    not exist. Selection must be by content shape: the file with `accessToken`.
+    """
+    result = _invoke(_write_cache(tmp_path), _netrc(tmp_path), authenticated=True)
+    assert result.exit_code == 0, result.output
+    assert "2026-08-13" in result.output, result.output
+    assert "2026-09-14" not in result.output, result.output
+
+
+def test_missing_cache_directory_claims_no_window(tmp_path):
+    """No cache is a reason to say nothing, not to guess."""
+    result = _invoke(tmp_path / "absent", tmp_path / "no-netrc", authenticated=True)
+    assert result.exit_code == 0, result.output
+    assert result.exception is None, result.exception
+    assert not re.search(r"\d{4}-\d{2}-\d{2}", result.output), result.output
+
+
+def test_reports_netrc_age(tmp_path):
+    """The CodeArtifact token records no expiry, so age is the only signal —
+    and it gates `pixi install`, and therefore `dh` itself."""
+    result = _invoke(_write_cache(tmp_path), _netrc(tmp_path, age_hours=5.0))
+    netrc_lines = [ln for ln in result.output.splitlines() if "netrc" in ln.lower()]
+    assert netrc_lines, result.output
+    assert "5" in netrc_lines[0], netrc_lines[0]
+
+
+def test_states_portal_session_is_not_locally_observable(tmp_path):
+    """The access-token expiry is not the window. Nothing inside a devcon can
+    see the portal session's lifetime, and the output must say so rather than
+    let the token clock be read as the deadline."""
+    result = _invoke(_write_cache(tmp_path), _netrc(tmp_path))
+    lowered = result.output.lower()
+    assert "portal" in lowered, result.output
+    assert "not locally observable" in lowered, result.output
+
+
+def test_no_boto3_import():
+    """`dh` installs through CodeArtifact, which needs working AWS auth, so a
+    diagnostic that cannot run when auth is broken is useless exactly when it
+    is needed."""
+    from dh_cli import cloud_commands
+
+    source = Path(cloud_commands.__file__).read_text()
+    assert "boto3" not in source, "cloud_commands.py must stay standard-library-only"