From 0734e06ca5923bec78fc148ea45be44fd8de5360 Mon Sep 17 00:00:00 2001
From: Krzysztof kuhy Rudnicki <krzysztofrudnicki0@gmail.com>
Date: Sun, 16 Aug 2026 22:51:20 +0200
Subject: [PATCH] Let trace_shell_split.sh stub extra binaries per run

fresh-install/main.sh calls git clone against live AUR URLs, makepkg, and
curl -- none of which belong in the default stub set, since plenty of
scripts read git state harmlessly and a blanket git stub would change what
they see rather than protect anything.

--stub git,curl,makepkg shadows them for one run. Verified: both calls are
captured in the trace with no repo cloned and no network hit, and the two
regression fixtures still behave (exit 1 for the set -e tail, four
circular-name-reference warnings for the nameref).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
---
 .../trace-harness-extra-stubs-2026-08-16.json | 41 +++++++++++++++++++
 meta/scripts/trace_shell_split.sh             | 19 +++++++--
 2 files changed, 57 insertions(+), 3 deletions(-)
 create mode 100644 docs/superpowers/evidence/trace-harness-extra-stubs-2026-08-16.json

diff --git a/docs/superpowers/evidence/trace-harness-extra-stubs-2026-08-16.json b/docs/superpowers/evidence/trace-harness-extra-stubs-2026-08-16.json
new file mode 100644
index 00000000..5180d203
--- /dev/null
+++ b/docs/superpowers/evidence/trace-harness-extra-stubs-2026-08-16.json
@@ -0,0 +1,41 @@
+{
+  "intent": "Let trace_shell_split.sh shadow additional binaries per run, so scripts that clone from AUR or build packages can be traced without touching the network or the package set.",
+  "scope": [
+    "meta/scripts/trace_shell_split.sh",
+    "Non-goal: git/curl/wget/makepkg are deliberately not added to the default set"
+  ],
+  "changes": [
+    "Rename STUBBED_COMMANDS to DEFAULT_STUBBED_COMMANDS and add a --stub a,b,c flag whose names are shadowed for that run only.",
+    "Document why git and friends stay out of the default set: many scripts read git state harmlessly, so a blanket stub would change what they observe rather than protect anything."
+  ],
+  "verification": [
+    {
+      "command": "trace_shell_split.sh on a fixture calling `git clone` and `curl`, with --stub git,curl,makepkg",
+      "result": "pass",
+      "evidence": "Trace captured 'git clone https://example.com/repo.git' and 'curl -sL https://example.com/x'; stdout reached 'reached the end'. No repository was cloned and no request left the machine."
+    },
+    {
+      "command": "Regression: the `set -e` function-tail fixture",
+      "result": "pass",
+      "evidence": "Still exit status 1 with an empty trace and no stdout -- the --stub change did not weaken detection."
+    },
+    {
+      "command": "Regression: the self-referencing nameref fixture",
+      "result": "pass",
+      "evidence": "Still four 'circular name reference' warnings captured in stderr."
+    },
+    {
+      "command": "shellcheck meta/scripts/trace_shell_split.sh; shfmt -d meta/scripts/trace_shell_split.sh",
+      "result": "pass",
+      "evidence": "Both exit 0 with no output."
+    }
+  ],
+  "risks": [
+    "A caller who forgets --stub for a script that shells out to git or curl gets a real clone or a real request. The header comment tells the reader to grep for network and build verbs first; that remains a human step.",
+    "IFS-splitting the --stub value means a binary name containing a comma cannot be passed, which no real binary does."
+  ],
+  "rollback": [
+    "Revert the commit; the harness returns to a fixed default stub list.",
+    "Re-run the three fixtures and confirm the same exit statuses."
+  ]
+}
diff --git a/meta/scripts/trace_shell_split.sh b/meta/scripts/trace_shell_split.sh
index 66ad491c..0287f6bc 100755
--- a/meta/scripts/trace_shell_split.sh
+++ b/meta/scripts/trace_shell_split.sh
@@ -22,6 +22,7 @@
 # Usage:
 #   trace_shell_split.sh <script> [-- <script args>]
 #   trace_shell_split.sh <script> --out <file> [-- <script args>]
+#   trace_shell_split.sh <script> --stub git,curl,makepkg --out <file>
 # ============================================================================
 
 set -euo pipefail
@@ -32,7 +33,12 @@ readonly SCRIPT_NAME
 # Commands that change the system, the phone, or the package set. Each becomes
 # a stub that records its invocation and exits 0. Extend deliberately: a
 # missing name here means the real binary runs.
-readonly STUBBED_COMMANDS=(
+#
+# Deliberately NOT here: `git`, `curl`, `wget`, `makepkg`. Those are stubbed
+# per-run via --stub, because plenty of scripts read git state harmlessly and a
+# blanket git stub would change what they see rather than protect anything.
+# Grep the target for network and build verbs before tracing it.
+readonly DEFAULT_STUBBED_COMMANDS=(
 	sudo pacman yay paru systemctl systemd-run
 	adb fastboot
 	nft iptables ip6tables firewall-cmd
@@ -47,6 +53,7 @@ TARGET=""
 OUT=""
 TEMP_DIR=""
 declare -a SCRIPT_ARGS=()
+declare -a EXTRA_STUBS=()
 
 cleanup() {
 	if [[ -n "${TEMP_DIR:-}" && -d "$TEMP_DIR" ]]; then
@@ -57,9 +64,10 @@ cleanup() {
 trap cleanup EXIT
 
 usage() {
-	echo "Usage: $SCRIPT_NAME <script> [--out <file>] [-- <script args>]"
+	echo "Usage: $SCRIPT_NAME <script> [--out <file>] [--stub a,b] [-- <script args>]"
 	echo "  <script>      script to trace (not modified)"
 	echo "  --out <file>  write the trace here (default: stdout)"
+	echo "  --stub a,b    also shadow these binaries (e.g. git,curl,makepkg)"
 	echo "  --            everything after this is passed to the script"
 	exit 0
 }
@@ -82,7 +90,7 @@ validate_requirements() {
 write_stubs() {
 	local bin_dir="$1" name
 	mkdir -p "$bin_dir"
-	for name in "${STUBBED_COMMANDS[@]}"; do
+	for name in "${DEFAULT_STUBBED_COMMANDS[@]}" ${EXTRA_STUBS[@]+"${EXTRA_STUBS[@]}"}; do
 		cat >"$bin_dir/$name" <<STUB
 #!/usr/bin/env bash
 printf '%s %s\n' "$name" "\$*" >>"\$TRACE_FILE"
@@ -140,6 +148,11 @@ while [[ $# -gt 0 ]]; do
 		OUT="$2"
 		shift 2
 		;;
+	--stub)
+		# Comma-separated extra binaries to shadow for this run only.
+		IFS=',' read -r -a EXTRA_STUBS <<<"$2"
+		shift 2
+		;;
 	-h | --help)
 		usage
 		;;