From 8e4f0163f4fad68fe7a5fe0d3904f956c0d2db71 Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <codeforester@gmail.com>
Date: Tue, 21 Jul 2026 06:43:24 -0700
Subject: [PATCH] Complete temporary run retention coverage

---
 .../basectl/tests/runtime-dispatch.bats       | 58 +++++++++++++++++++
 docs/observability.md                         |  5 ++
 2 files changed, 63 insertions(+)

diff --git a/cli/bash/commands/basectl/tests/runtime-dispatch.bats b/cli/bash/commands/basectl/tests/runtime-dispatch.bats
index 615f5af2..75724bf5 100644
--- a/cli/bash/commands/basectl/tests/runtime-dispatch.bats
+++ b/cli/bash/commands/basectl/tests/runtime-dispatch.bats
@@ -69,6 +69,64 @@ load ./basectl_helpers.bash
 }
 
 
+@test "basectl removes temp data after a recognized command failure by default" {
+    local cache_root="$TEST_TMPDIR/cache"
+    local run_root
+
+    run env \
+        HOME="$TEST_HOME" \
+        BASE_HOME="$BASE_REPO_ROOT" \
+        BASE_CACHE_DIR="$cache_root" \
+        bash -c '
+            source "$BASE_HOME/cli/bash/commands/basectl/basectl.sh"
+            log_debug() { :; }
+            basectl_do_setup() {
+                mkdir -p "$BASE_CLI_RUN_ROOT/tmp/base_setup"
+                printf "temporary\\n" >"$BASE_CLI_RUN_ROOT/tmp/base_setup/file.txt"
+                return 7
+            }
+            basectl_history_record() { :; }
+            basectl_main setup
+        '
+
+    [ "$status" -eq 7 ]
+    run_root="$(find "$cache_root/base/runs" -mindepth 1 -maxdepth 1 -type d -print -quit)"
+    [ -n "$run_root" ]
+    [ ! -e "$run_root/tmp" ]
+    [ -f "$run_root/run.json" ]
+    [ -f "$run_root/logs/primary.log" ]
+}
+
+
+@test "basectl preserves temp data after a recognized command failure when requested" {
+    local cache_root="$TEST_TMPDIR/cache"
+    local run_root
+
+    run env \
+        HOME="$TEST_HOME" \
+        BASE_HOME="$BASE_REPO_ROOT" \
+        BASE_CACHE_DIR="$cache_root" \
+        bash -c '
+            source "$BASE_HOME/cli/bash/commands/basectl/basectl.sh"
+            log_debug() { :; }
+            basectl_do_setup() {
+                mkdir -p "$BASE_CLI_RUN_ROOT/tmp/base_setup"
+                printf "temporary\\n" >"$BASE_CLI_RUN_ROOT/tmp/base_setup/file.txt"
+                return 7
+            }
+            basectl_history_record() { :; }
+            basectl_main --keep-temp setup
+        '
+
+    [ "$status" -eq 7 ]
+    run_root="$(find "$cache_root/base/runs" -mindepth 1 -maxdepth 1 -type d -print -quit)"
+    [ -n "$run_root" ]
+    [ -f "$run_root/tmp/base_setup/file.txt" ]
+    [ -f "$run_root/run.json" ]
+    [ -f "$run_root/logs/primary.log" ]
+}
+
+
 @test "basectl labels run bundle directories without changing the run ID" {
     run env \
         BASE_HOME="$BASE_REPO_ROOT" \
diff --git a/docs/observability.md b/docs/observability.md
index bf8d69da..7ee27bb8 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -166,6 +166,11 @@ The retention contract should be:
   caches older than the age.
 - `basectl clean --keep-last <count>` retains the newest completed bundles per
   owner namespace.
+- Per-run temporary data is diagnostic-only: `basectl` removes the complete
+  `tmp/` tree after every recognized command, regardless of success or failure,
+  unless `basectl --keep-temp <command>` (or the documented Python retention
+  setting) is used. Run metadata, history, and `logs/primary.log` remain
+  available either way.
 - History records remain even when cleanup removes their referenced bundle, and
   `basectl history` can mark those logs as missing.
 - Durable user state under `~/.base.d` is never cleaned by history retention.