feat: add Helm lifecycle reporting and integration coverage

.github/workflows/test.yml

@@ -568,7 +568,10 @@ jobs:
           - demo-helmfile
           - helm
 
-    timeout-minutes: 60
+    # The macOS matrix may spend up to 45 minutes starting Colima, followed by
+    # two bounded 45-minute test attempts. Keep the job ceiling above those
+    # nested budgets so the second retry can finish and emit diagnostics.
+    timeout-minutes: 180
     steps:
       - name: Check out code into the Go module directory
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -644,23 +647,36 @@ jobs:
           }
 
           cleanup_k3s() {
-            atmos emulator down kubernetes -s dev || true
-            docker rm -f atmos-dev-emulator-kubernetes >/dev/null 2>&1 || true
+            run_with_timeout 60 atmos emulator down kubernetes -s dev || true
+            run_with_timeout 30 docker rm -f atmos-dev-emulator-kubernetes >/dev/null 2>&1 || true
+          }
+
+          diagnose_k3s() {
+            if ! run_with_timeout 15 docker inspect atmos-dev-emulator-kubernetes >/dev/null 2>&1; then
+              return
+            fi
+
+            echo "::group::k3s workload diagnostics"
+            run_with_timeout 30 docker exec atmos-dev-emulator-kubernetes kubectl get pods,jobs,deployments -A -o wide || true
+            run_with_timeout 30 docker exec atmos-dev-emulator-kubernetes kubectl get events -A --sort-by=.lastTimestamp || true
+            run_with_timeout 30 docker exec atmos-dev-emulator-kubernetes ctr --namespace k8s.io images list || true
+            echo "::endgroup::"
           }
 
           # macOS k3s jobs can occasionally hang in the Docker/Colima stack.
           # Bound each attempt so the matrix can retry instead of consuming the
           # whole job timeout and cancelling the required aggregate check.
           attempt_timeout=1500
           if [ "${{ matrix.flavor.target }}" = "macos" ]; then
-            attempt_timeout=900
+            attempt_timeout=2700
           fi
 
           trap cleanup_k3s EXIT
           for attempt in 1 2; do
             run_with_timeout "${attempt_timeout}" atmos test && exit 0
             status=$?
             echo "atmos test failed (attempt ${attempt}/2, status ${status})" >&2
+            diagnose_k3s
             cleanup_k3s
             [ "${attempt}" -lt 2 ] && sleep 15
           done

.pre-commit-config.yaml

@@ -90,7 +90,7 @@ repos:
         stages: [pre-commit]
         exclude: ^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|.*\.svg|website/src/components/Screengrabs/)
       - id: check-yaml
-        exclude: ^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|tests/fixtures/)
+        exclude: ^(vendor/|tests/test-cases/|tests/testdata/|tests/snapshots/|tests/fixtures/|examples/helm/components/helm/demo/templates/)
         args: [--allow-multiple-documents, --unsafe]
       - id: check-added-large-files
         stages: [pre-commit]

docs/fixes/2026-07-31-native-helm-release-lifecycle.md

@@ -0,0 +1,36 @@
+# Native Helm release lifecycle
+
+**Date:** 2026-07-31
+
+Native Helm cluster operations now expose Helm 4 wait, timeout, recovery,
+history, hook, and CRD controls through stack configuration and explicit command
+flags. Apply and delete dry runs now reach the Helm SDK without persisting release
+state. Caller cancellation propagates through direct and dependency-ordered
+execution into install and upgrade actions and into delete wait and hook phases;
+Helm 4 does not expose a context-aware uninstall request.
+
+Atmos reports the selected action and effective release policy before the Helm
+action begins, including any `hookOnly` to `watcher` promotion required by
+failure recovery. Bulk delete uses reverse dependency order so dependents are
+removed before the releases they consume.
+
+## Migration notes
+
+- An omitted `release.timeout` remains `0s` (unbounded) for one minor release and emits a
+  warning. The omitted default becomes `5m` in the following minor. Configure
+  `release.timeout: 0s` explicitly to keep unbounded behavior without the warning.
+- An omitted `release.history.max` retains ten upgrade revisions, matching the
+  Helm CLI. Configure `release.history.max: 0` to retain unlimited history.
+- Failure recovery is operation-specific: use `release.install.on_failure: uninstall`
+  for failed first installs and `release.upgrade.on_failure: rollback` for failed
+  upgrades. Upgrade cleanup is controlled independently by
+  `release.upgrade.cleanup_on_failure`.
+- Boolean `--wait=true` and `--wait=false` remain accepted temporarily; use
+  `--wait=watcher` and `--wait=hookOnly`.
+- Explicit lifecycle flags cannot be combined with a non-Kubernetes provision
+  target. Stored lifecycle configuration is intentionally bypassed for external
+  delivery and is identified as such in the execution summary.
+- Chart-loading commands do not fetch missing dependencies unless
+  `--dependency-update` is explicitly supplied. The opt-in follows Helm's
+  dependency-update behavior and may access repositories and mutate the chart's
+  `charts/` directory and lock file.

docs/prd/native-helm-release-lifecycle.md

@@ -53,7 +53,6 @@ These gaps force users migrating from Helm or Helmfile to choose between depende
 - Fix apply dry-run propagation as a release-blocking safety prerequisite, then correctly propagate delete dry-run, cancellation, and deadlines through cluster operations.
 - Validate configuration before chart download or cluster mutation.
 - Keep template and diff complete by including Helm chart hook resources alongside the ordinary release manifest.
-- Allow callers to opt into fetching missing chart dependencies with Helm-compatible `--dependency-update` semantics.
 - Keep the design compatible with future pre-rollback diagnostics without requiring another public configuration rename.
 - Follow Atmos schema, stack-processing, command parsing, provider, error, logging, and testing conventions.
 
@@ -240,8 +239,6 @@ atmos helm delete demo-api -s example-prod \
 
 `template`, `diff`, and `plan` do not register release-lifecycle flags because they do not perform a release operation.
 
-All chart-loading operations (`template`, `diff`, `plan`, `apply`, and `deploy`) accept `--dependency-update`. Atmos invokes Helm's dependency manager only when a declared dependency is missing. The flag is intentionally invocation-scoped: without it, Atmos does not access dependency repositories or mutate the chart directory and instead reports both the equivalent `helm dependency build <chart>` command and the opt-in flag.
-
 ## Configuration Contract
 
 ### Release-Wide Defaults
@@ -372,6 +369,7 @@ The following rules apply:
 - A release that fails and is successfully rolled back still returns failure to the scheduler.
 - A rollback or uninstall failure preserves the original release failure and adds the recovery failure.
 - Dependents never run after timeout, failed readiness, failed hooks, failed rollback, or cancellation.
+- Bulk delete traverses the selected graph in reverse topological order so dependents are removed before their dependencies.
 - A future mixed-kind scheduler consumes the same provider result; it must not reinterpret Helm readiness.
 
 ## Timeout Semantics

errors/errors.go

@@ -1539,6 +1539,7 @@ var (
 	ErrHelmReleaseHistory            = errors.New("failed to inspect helm release history")
 	ErrHelmReleaseUpgrade            = errors.New("failed to upgrade helm release")
 	ErrHelmReleaseUninstall          = errors.New("failed to uninstall helm release")
+	ErrHelmReleaseOperation          = errors.New("helm release operation failed")
 )
 
 // Stack dependency (`depends_on`) resolution errors.

examples/helm/README.md

@@ -17,12 +17,14 @@ Run the local chart workflow end to end:
 
 ```shell
 atmos validate stacks
-atmos helm template demo -s dev
+atmos helm template demo -s dev --dependency-update
 atmos emulator up kubernetes -s dev
 atmos helm diff demo -s dev --identity local-k3s
-atmos helm apply demo -s dev --identity local-k3s
+atmos helm apply demo -s dev --identity local-k3s --dry-run
+atmos helm apply demo -s dev --identity local-k3s --on-failure=uninstall --wait=watcher --timeout=2m
 atmos emulator exec kubernetes -s dev -- kubectl -n demo get deployment demo
 atmos emulator exec kubernetes -s dev -- kubectl -n demo get service demo
+atmos helm delete demo -s dev --identity local-k3s --dry-run --wait=watcher --timeout=2m
 atmos helm delete demo -s dev --identity local-k3s
 atmos emulator down kubernetes -s dev
 ```
@@ -33,7 +35,7 @@ this same lifecycle.
 ## Render (no cluster, no credentials)
 
 ```shell
-atmos helm template demo -s dev
+atmos helm template demo -s dev --dependency-update
 
 # Render the same chart through a declarative Helm repository.
 HELM_DEMO_REPO_URL=http://127.0.0.1:8080 atmos helm template demo-repo -s dev
@@ -69,6 +71,20 @@ atmos emulator up kubernetes -s dev
 atmos helm apply demo -s dev --identity local-k3s
 ```
 
+The stack sets `release.wait.strategy: watcher`, `release.timeout: 4m`,
+`release.history.max: 10`, and `release.install.crds: skip` as native Helm type
+defaults. The `demo` component overrides the wait strategy to `legacy`, uses
+install uninstall-on-failure, and enables upgrade rollback with independent
+failed-upgrade cleanup. The `atmos test` workflow
+covers non-mutating apply and delete dry runs, ordinary Job waiting, chart-hook
+suppression, CRD skipping, weighted hook ordering, retained hook resources,
+install and upgrade rollback, failed-upgrade cleanup, timeout handling, and
+dependency-gated Helm releases. Rendering also verifies opt-in acquisition of a
+missing `file://` library dependency, hook manifests, and a Helm `tpl` expression
+preserved in stack values.
+The intentionally slow resources are observed
+with bounded Kubernetes readiness checks rather than fixed-delay assertions.
+
 ## Helm Repositories
 
 The `demo-repo` component shows the declarative Helm repository path: