From 724f46f145426364d741015fcbbed9878af5fede Mon Sep 17 00:00:00 2001
From: Ryan Hughes <ryan@heyoodle.com>
Date: Sat, 23 May 2026 12:45:12 -0400
Subject: [PATCH] installer: trace finalizer in debug builds

---
 finalize.sh                              | 16 ++++++++-
 install/helpers/logging.sh               |  7 +++-
 test/offline-finalizer-bootstrap-test.sh | 41 ++++++++++++++++++++++++
 3 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/finalize.sh b/finalize.sh
index 83eefc3d..01c9f371 100644
--- a/finalize.sh
+++ b/finalize.sh
@@ -5,12 +5,26 @@
 # target-side setup scripts. The ISO parent owns UI/error handling, while the
 # online path re-establishes its tty-backed traps below.
 
+export OMARCHY_INSTALL_LOG_FILE="${OMARCHY_INSTALL_LOG_FILE:-/var/log/omarchy-install.log}"
+
+if [[ ${OMARCHY_INSTALL_DEBUG:-} == "1" ]]; then
+  if [[ -n ${OMARCHY_CHROOT_FINALIZER:-} || ${OMARCHY_INSTALL_MODE:-} == "offline" ]]; then
+    if { mkdir -p "$(dirname "$OMARCHY_INSTALL_LOG_FILE")" && touch "$OMARCHY_INSTALL_LOG_FILE"; } 2>/dev/null; then
+      exec >>"$OMARCHY_INSTALL_LOG_FILE" 2>&1
+    else
+      echo "[finalize-debug] WARNING: cannot write $OMARCHY_INSTALL_LOG_FILE; tracing to inherited stderr" >&2
+    fi
+  fi
+  export PS4='+ ${BASH_SOURCE[0]##*/}:${LINENO}:${FUNCNAME[0]:-main}: '
+  echo "[finalize-debug] tracing enabled for $$ at $(date -Is)"
+  set -x
+fi
+
 set -eEo pipefail
 
 _OMARCHY_INSTALLER_DIR=$(dirname "$(realpath "${BASH_SOURCE[0]}")")
 export OMARCHY_PATH="${OMARCHY_PATH:-$_OMARCHY_INSTALLER_DIR}"
 export OMARCHY_INSTALL="${OMARCHY_INSTALL:-$_OMARCHY_INSTALLER_DIR/install}"
-export OMARCHY_INSTALL_LOG_FILE="${OMARCHY_INSTALL_LOG_FILE:-/var/log/omarchy-install.log}"
 export PATH="$_OMARCHY_INSTALLER_DIR/bin:$OMARCHY_PATH/bin:$PATH"
 
 # Do not source helpers/all.sh here. That bundle unconditionally pulls in
diff --git a/install/helpers/logging.sh b/install/helpers/logging.sh
index d74e17dc..a27b506b 100644
--- a/install/helpers/logging.sh
+++ b/install/helpers/logging.sh
@@ -134,7 +134,12 @@ run_logged() {
 
   # Use a clean subshell, but keep errexit so failures inside sourced scripts
   # cannot be hidden by a later successful command in the same script.
-  bash -eE -c 'source "$1"' bash "$script" </dev/null >>"$OMARCHY_INSTALL_LOG_FILE" 2>&1
+  if [[ ${OMARCHY_INSTALL_DEBUG:-} == "1" ]]; then
+    PS4='+ ${BASH_SOURCE[0]##*/}:${LINENO}:${FUNCNAME[0]:-main}: ' \
+      bash -x -eE -c 'source "$1"' bash "$script" </dev/null >>"$OMARCHY_INSTALL_LOG_FILE" 2>&1
+  else
+    bash -eE -c 'source "$1"' bash "$script" </dev/null >>"$OMARCHY_INSTALL_LOG_FILE" 2>&1
+  fi
 
   local exit_code=$?
 
diff --git a/test/offline-finalizer-bootstrap-test.sh b/test/offline-finalizer-bootstrap-test.sh
index 4b684b1c..76cbf031 100755
--- a/test/offline-finalizer-bootstrap-test.sh
+++ b/test/offline-finalizer-bootstrap-test.sh
@@ -88,4 +88,45 @@ if [[ $output == *'Inappropriate ioctl'* || $output == *'/dev/tty'* ]]; then
   exit 1
 fi
 
+rm -f "$TMP/home/finalizer-completed" "$TMP/omarchy-install.log"
+debug_output="$({
+  setsid -w env \
+    OMARCHY_INSTALL_DEBUG=1 \
+    OMARCHY_INSTALL="$TMP/install" \
+    OMARCHY_PATH="$TMP/omarchy" \
+    OMARCHY_INSTALL_MODE=offline \
+    OMARCHY_CHROOT_FINALIZER=1 \
+    OMARCHY_INSTALL_LOG_FILE="$TMP/omarchy-install.log" \
+    HOME="$TMP/home" \
+    USER=ryan \
+    bash "$ROOT/finalize.sh" </dev/null
+} 2>&1)"
+
+printf '%s\n' "$debug_output"
+
+if [[ ! -f "$TMP/home/finalizer-completed" ]]; then
+  echo "expected debug finalizer completion marker" >&2
+  exit 1
+fi
+
+if ! grep -q '\[finalize-debug\] tracing enabled' "$TMP/omarchy-install.log"; then
+  echo "expected finalize debug trace marker in install log" >&2
+  exit 1
+fi
+
+if ! grep -q 'source .*/helpers/mode.sh' "$TMP/omarchy-install.log"; then
+  echo "expected helper source trace in debug install log" >&2
+  exit 1
+fi
+
+if ! grep -q 'packaging-marker' "$TMP/omarchy-install.log"; then
+  echo "expected debug run_logged script output in install log" >&2
+  exit 1
+fi
+
+if [[ $debug_output == *'Inappropriate ioctl'* || $debug_output == *'/dev/tty'* ]]; then
+  echo "debug offline finalizer attempted tty access" >&2
+  exit 1
+fi
+
 echo "offline finalizer bootstrap test passed"