testsAndMisc/NEXT_SESSION_PROMPT.md

Next session: split install_leechblock.sh

Paste this whole file into a fresh Claude session opened in ~/testsAndMisc. It is self-contained. Do not go looking for the previous session's context.

The one job

Split linux_configuration/scripts/periodic_background/digital_wellbeing/install_leechblock.sh (485 lines, over the 250-line cap by 235) into files that are each under the cap, and prove by execution that it still does exactly the same thing.

This is the best-conditioned target left: it is the only remaining one that traces to completion with exit 0, and its 93 written-file hashes are identical across runs. Read the safety note below before you run it, though — it kills browsers.

What landed in the last session (do not redo)

Two splits, both committed and pushed, both proven by an empty before/after trace diff:

• install_usage_monitoring.sh 290 → 53-line entry + 5 libs (26965ba)
• install_pacman_wrapper.sh 316 → 128-line entry + 4 libs (4eedc17)

Read the 4eedc17 diff first — it is the closest worked example, and three of its lessons apply directly here:

• Keep path/variable definitions in the ENTRY script, not a lib/paths.sh. A definitions-only lib assigns without referencing, which is SC2034 on every variable, and suppressions are forbidden. Libs that only reference globals are fine. export silences it but leaks the variables into every child process — a behaviour change the trace cannot see. Don't.
• The pre-commit hook runs shfmt -w on staged shell files and re-stages them, rewriting cat > "x" << 'EOF' into cat >"x" <<'EOF'. Run shfmt -w yourself first, then verify, so the tested state is the committed state.
• Enumerate every test that greps the target's source text before designing the seams. The pacman split had eight such assertions across two test libs; one (chattr +i) was missed on the first pass and failed loudly. Run:

  grep -rn 'install_leechblock' linux_configuration/tests/ meta/ .github/
  

Repo-wide jscpd reports 2.51% from the working tree but 1.47% at HEAD in a clean worktree — the excess is entirely vendored .venv/.ci-mirror-venv site-packages. Don't chase it; measure in a worktree if you need a real number.

SAFETY: this script kills browsers and deletes directories

Two hazards, both measured:

1. Line ~217 runs pkill -f 'google-chrome|chromium|brave-browser|vivaldi|thorium'. pkill is NOT in the harness stub set, and --prefix cannot contain it — signals are not filesystem writes. Tracing this script closes every open browser. Check nothing is running (pgrep -af 'chrome|chromium|thorium') and pass --stub pkill before any run.
2. It runs rsync -a --delete at $XDG_DATA_HOME/leechblockng. This is safe under --prefix — the harness exports XDG_DATA_HOME into the prefix explicitly because of this script — but never run it outside the harness.

Verified after the probe runs: ~/.local/share/leechblockng/ untouched (still dated Aug 9), no Chrome profile file modified, /usr/local/bin/browser-preexec-wrapper untouched. The node seeder resolves profiles via os.homedir(), which the prefix redirects, so it found no profiles and wrote nothing ("Seeding" appears zero times in the trace).

The baseline

F=linux_configuration/scripts/periodic_background/digital_wellbeing/install_leechblock.sh

rm -rf /tmp/pfx-before        # fresh, NOT emptied — the harness refuses a non-empty prefix
meta/scripts/trace_shell_split.sh "$F" --prefix /tmp/pfx-before \
  --stub pkill --out /tmp/before.txt

Expect exit 0 and 93 files written. Note the probe baseline was captured without --stub pkill; adding the stub is correct and may add one line to the stubbed-call list, so capture your own baseline with the same flags you will use afterwards.

Two things vary between runs and are NOT split defects — normalize them before diffing:

• The prefix path is echoed inside the six sudo sed -i …--load-extension=… stubbed calls.
• curl's progress meter (download speeds/times) in stderr.

Everything else is stable: all 93 content hashes were byte-identical across two consecutive HEAD runs. The manifest section alone is the real assertion:

sed -n '/=== files written/,/=== stdout/p' /tmp/before.txt > /tmp/before.man
sed -n '/=== files written/,/=== stdout/p' /tmp/after.txt  > /tmp/after.man
diff /tmp/before.man /tmp/after.man     # must be empty

Also diff the full traces with the two varying patterns normalized, so a change in stdout ordering or a dropped step still shows.

Hazards specific to THIS file

1. SCRIPT_DIR at line ~205 finds sibling data files

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
DEFAULTS_SRC="$SCRIPT_DIR/leechblock_defaults.json"

It also locates seed_leechblock_storage.js and node_modules/. In a sourced lib ${BASH_SOURCE[0]} resolves to lib/, so these would silently point at lib/leechblock_defaults.json and the defaults would be skipped with only a warning — exit status unchanged. Compute it once in the entry and let libs read it, exactly as REPO_DIR was handled in 26965ba.

2. Network downloads make timing non-deterministic

curl fetches the LeechBlockNG tarball and jQuery UI. Content is stable (same hashes across runs) but progress output is not. Do not --stub curl — that would skip the download and empty out most of the 93 files.

3. A trap 'rm -rf "$tmpdir"' EXIT is set mid-script

Set inside the download branch (~line 143). If you move that branch into a lib, the trap still registers globally, but check it is not overwritten by another trap … EXIT you introduce.

Rules that will bite you

• SCRIPT_DIR must resolve symlinks in the entry: SCRIPT_DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")".
• Wrapping top-level code in a function changes what set -e sees. A bare [[ -n $x ]] && arr+=("$x") as a function's last statement becomes its return value; append || true if so.
• No suppressions. No # shellcheck disable, no per-file ignores.
• New .sh libs need the executable bit, a #!/bin/bash shebang, and no set -euo pipefail (a sourced lib inherits the caller's strict mode).
• Verify with pre-commit run shellcheck --files …, not a bare shellcheck -x. The latter follows source= directives and hides SC2034 in a standalone lib; the former is the real gate and does not.
• Every commit touching code needs an evidence JSON in docs/superpowers/evidence/; ≥4 staged code files additionally needs a fresh docs/superpowers/contracts/*.json. Validate both with python3 meta/scripts/validate_contract.py / meta/scripts/validate_evidence.py.
• Markdown needs npx prettier --write — prettier is pre-push only.
• Work directly on main; commit and push. git stash and branch creation are blocked by hooks.
• git push runs ci-mirror and takes minutes. Never edit files while a push is running.
• Do not wire the file-length pre-commit hook. It must land last, only once bash ~/utils/scripts/check_file_length.sh --all exits 0.

Read these first

1. docs/shell-split-verification.md — how a green split is still broken. Now covers the /usr/bin bind limit, the unstubbed pkill, and how to compare when the target embeds a timestamp.
2. docs/shell-split-recipes.md — how to actually make a split.
3. The 4eedc17 and 26965ba diffs — two worked examples of the entry+lib shape.

Definition of done

• install_leechblock.sh and every file split out of it are under 250 lines.
• The trace manifest (93 files, all hashes) is identical before and after, and the normalized full traces are identical, both at exit 0.
• Any test that greps the installer's source text still passes, with no assertion weakened.
• pre-commit run shellcheck clean, shfmt clean, zero suppressions.
• ~/.local/share/leechblockng/ and all Chrome profile dirs unmodified by the verification runs — check mtimes before and after.
• Committed and pushed, with evidence (and a contract if ≥4 code files).

Ruled out — do not attempt these

• nvidia_troubleshoot.sh (336). Measured this session: its trace dies at step 3 because backup_file writes /etc/profile.backup.<stamp>, a new sibling in unbound /etc (a file bind cannot cover siblings, and bare /etc is refused). 239 of its 336 lines never execute. Keeping the unproven ones in the entry — the rule the pacman split established — leaves the entry at ~265, still over the cap. It cannot satisfy both the rule and the goal.
• block_compulsive_opening.sh (705) — install_all copies the running script into /usr/local/bin; an entry+lib shape ships an entry whose SCRIPT_DIR has no lib/, breaking three daily-use apps plus the pacman rewrap hook.
• Blocked on NAMED blockers, not line count: check_and_enable_services.sh (1337), steam_compatibility.sh (663), libre_translate.sh (488), enforce_vbox_hosts.sh (443). See refactor_claude_todo_resume.md.

setup_thorium_startup.sh (443) is unprobed — trace it at HEAD before committing to it, the same way this one was probed.

Known pre-existing failure (not yours)

bash linux_configuration/tests/test_security_hardening.sh exits 1 at HEAD with exactly one failure, ❌ FAIL: Compulsive block wrappers installed. It belongs to block_compulsive_opening.sh. Capture it before and after your change and confirm it is unchanged; do not try to fix it.