setup_hosts_guard.sh was NEXT_SESSION_PROMPT.md's next split target, but
live-machine inspection showed it (and 16 supporting files - enforce-*.sh,
6 systemd units, install_pacman_hooks.sh, pacman-hooks/, psychological/,
both READMEs) is fully retired in favor of guard-lib, migrated 2026-07-04.
User confirmed archive over split, then confirmed the larger 17-file scope
once the directory was surveyed. Full history preserved via git filter-repo,
live at github.com/kuhyx/testsAndMisc-archive/tree/main/linux_configuration/scripts/periodic_background/hosts/guard.
plugins/{nsswitch,resolved}-plugin.sh stay - they're guard-lib's live
plugins, referenced by absolute path from /etc/guard-lib/targets/*.conf.
check_and_enable_services.sh's check_hosts() rewritten to check guard-lib
state (guardctl file-guard status) instead of the retired units/scripts it
used to check and self-repair - verified live, now reports the hosts
service ok against the actual migrated machine instead of a false error.
copilot-instructions.md and one install.sh comment updated to match.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
12 KiB
Next session: pick the next §3/§4 target — no split candidate is currently in scope
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.
Over-cap: 11 (10 shell, 2 kotlin, 1 dart — focus_owner's two Kotlin files
count once regardless of listing style). Working tree clean, main in sync
as of the setup_hosts_guard.sh archive commit (see §0).
Two standing decisions from the user, already made — do not re-litigate:
- 100% line coverage on what you extract — same bar every session so far has applied. Does not apply to archived/deleted code (no split happened).
- Split blind where there is no device. Do not deploy to the phone, do not ask to. Prove splits with tests, hashes and real runs instead.
0. What just happened (read this, don't repeat it)
setup_hosts_guard.sh (576 lines) was this session's assigned split target.
The dead-code check-in (per the §0 lesson from two sessions before this one)
turned up evidence the file might be fully superseded — confirmed by
inspecting live machine state: the legacy pacman hooks it installs were
absent from /etc/pacman.d/hooks/, its systemd units were all disabled,
and guard-lib's /etc/guard-lib/targets/{hosts,nsswitch,resolved}.conf were
all already populated. The user confirmed: archive, don't split.
Scope grew past the one named file once the directory was surveyed: the
whole legacy hosts-guard subsystem (17 files — setup_hosts_guard.sh,
enforce-hosts.sh, enforce-nsswitch.sh, enforce-resolved.sh, 6 systemd
units, install_pacman_hooks.sh, pacman-hooks/*, psychological/*, both
READMEs) only existed to support the retired system, so it went to
testsAndMisc-archive together via git filter-repo (same procedure as the
plagiarism-tools and libre_translate archives). plugins/nsswitch-plugin.sh
and plugins/resolved-plugin.sh were kept — they're guard-lib's live
plugins, registered by absolute path in /etc/guard-lib/targets/*.conf.
check_and_enable_services.sh's check_hosts() function was rewritten in
the same commit (user confirmed this too) to check guard-lib state
(guardctl file-guard status <name>) instead of the legacy systemd
units/enforce-scripts it used to check and self-repair. Verified live:
sudo bash check_and_enable_services.sh --status now reports the hosts
service ok against the actual migrated machine, where the old code would
have reported error (three units it expected enabled were disabled by
design). linux_configuration/.github/copilot-instructions.md (always-loaded)
and one comment in hosts/install.sh were also updated to stop naming the
archived files.
Lesson (now 3 for 4): the check-in keeps changing scope, and this time it
changed scope twice — first archive-vs-split, then "just this file" vs
"the whole dead subsystem." Keep surveying the directory (grep -rl, not
just the named file) before proposing an archive's file list, and keep
confirming scope growth with the user before executing it.
0.1 Known defect found but NOT fixed this session — flag again if touching guard-lib
/etc/guard-lib/targets/nsswitch.conf and .../resolved.conf both have
PLUGIN= pointing at the repo checkout
(/home/kuhy/testsAndMisc/linux_configuration/scripts/periodic_background/hosts/guard/plugins/*.sh)
instead of /usr/local/share/guard-lib-plugins/, which
migrate_hosts_guard_to_guard_lib.sh's own header warns against by name
("pointing it at a repo checkout... silently breaks enforcement the day that
directory moves"). /usr/local/share/guard-lib-plugins/ does not exist on
this machine at all — the migration's plugin-install step appears to have
never run. Not fixed this session: it needs a sudo mutation of a live
security-enforcement system plus guardctl re-registration, which the user
was not asked to approve. If a future session touches guard-lib, nsswitch,
resolved, or moves/renames this checkout, raise this first.
1. This session's task: none pre-selected — ask the user
Every file currently over the 250-line cap is already on an explicit out-of-scope list from a prior session (§3 below, or the equivalent of the old §4). There is no unclaimed split candidate right now. Options, in roughly ascending order of friction:
- Re-run
bash meta/scripts/check_file_length.sh --allfresh (files may have grown/shrunk since this doc was written) and see if a genuinely new candidate appeared. - Ask the user whether any §3/§4 file should be taken out of its hold (e.g.
"is
install_leechblock.sh/block_compulsive_opening.shstill deployed at/usr/local/…? still preferred bypacman_wrapper.sh:831?" — re-verify, don't assume the old note is still true). - Ask the user for a completely different task.
Ask before picking — do not silently start splitting a file that a prior session explicitly parked, and do not assume "no candidate" means "nothing to do here" without checking with the user first.
2. §3 — do not touch this session (unless the user lifts it)
install_leechblock.sh (485) and block_compulsive_opening.sh (705) are
copied to /usr/local/…, and pacman_wrapper.sh:831 prefers the deployed
copy on every pacman invocation. Splitting them naively breaks every
pacman -S on this machine. Re-verify this is still true (grep
pacman_wrapper.sh for the deployed-copy preference) before assuming the old
note still holds — a lot has changed guard-lib-side this session, worth the
30-second re-check.
You cannot run sudo pacman -S from the Bash tool — it deadlocks on
db.lck. Hand the user a ! sudo pacman -S <pkg> line plus the expected
output if pacman_wrapper.sh ever needs live verification.
3. Out of scope until the user says otherwise
setup_midnight_shutdown.sh (1734), check_and_enable_services.sh (1225,
edited this session but not split — same out-of-scope reasoning as before),
generate_study_materials.sh (1017), pacman_wrapper.sh (929),
setup_night_lockdown.sh (918), hosts/install.sh (913, one comment edited
this session), EnforcementRunner.kt (564), DevicePolicyBridge.kt (415),
status_page_state.dart (307) — check check_file_length.sh --all for the
current exact list before assuming this is still accurate, since files
change size between sessions.
pacman_wrapper.sh carries the same live-deployment trap as §2. The Kotlin
and Dart files need a different verification stack — focus_owner gradle
needs JAVA_HOME=/usr/lib/jvm/java-21-openjdk and --rerun-tasks; a plain
gradlew test reports UP-TO-DATE and proves nothing.
4. Rules that will bite you (carried forward, still true)
- Ask before large scope changes. Three of the last four sessions have changed scope mid-session because the user volunteered new information, or a check-in (dead-code, or in this session's case a directory survey) surfaced something bigger than the named file. That is fine and expected — just don't assume silence means "keep going as originally scoped."
- Survey the whole directory before scoping an archive, not just the named
file.
grep -rl <filename-stem>across the repo, thenlsthe file's own directory — this session's file list grew from 1 to 17 files this way. - No suppressions, ever. No
# noqa, no per-file-ignore added without asking every time, no shellcheck disable beyond what's already justified inline. - A file must not assign a global it never reads (SC2034). The hook runs
shellcheckwith no-x, but.shellcheckrc'sexternal-sources=true+source-path=SCRIPTDIRmeans asource=annotation on the sourcing file still resolves correctly. - New sourced libs need a shebang AND the executable bit, staged with
git add --chmod=+x— a plaingit addafterwards resets it. pre-commit run --files <changed>before committing, but run it aftergit add.prettierandci-mirrorrun on pre-push.npx prettier --writeany.md/.jsonyou touch (evidence/contract files included).- Every commit touching code needs evidence in
docs/superpowers/evidence/<slug>-<date>.json. Staging ≥4 code files also needs a freshdocs/superpowers/contracts/*.json. Put the measured number in it, not a rounded-up one. This session's pair (archive-setup-hosts-guard-2026-08-18.jsonin bothevidence/andcontracts/) documents an archive-plus-live-script-fix, not a pure split — read it if the next task is another archive-vs-split judgment call. - An archive does not need new tests. The 100%-coverage standing decision binds code that gets split, not code that gets deleted. Neither this session's archive nor the two before it added tests for the archived code.
- Work directly on
main.git stashand branch creation are blocked; usegit worktree add --detachfor a clean baseline (but NEVERgit filter-repoinside a worktree — it shares the object store with the main repo and will corrupt it; always a throwawaygit clonefor that). - Do not wire the file-length hook into pre-commit. It lands last, once
check_file_length.sh --allexits 0. - Watch
jscpd(fails above 2%). Measure in a clean HEAD worktree. - Cap pytest memory:
systemd-run --user --scope -p MemorySwapMax=0 -p MemoryMax=2G. - Never let a test allocate unbounded real memory.
5. Tooling reference
meta/scripts/check_file_length.sh --all — the 250-line gate. Run
before every commit. Applies to test files too, not just the file you're
splitting.
meta/scripts/shell_coverage.sh <test> <subject> [min] — kcov wrapper,
100% minimum. Hand it the test script directly; bash script.sh
instruments the bash binary and silently reports 0/0.
meta/scripts/extract_shell_functions.py — moves functions
brace-by-brace. Never slice by line range. Verify placement with grep -c
on the anchor.
meta/scripts/verify_shell_split.sh <pre-split-rev> <old> <new>... —
proves a split moved every function verbatim. For a partial split list
the old path among the new paths too.
meta/scripts/mutate_shell.py <spec> — mutation testing; optional, not
required.
Archiving a dead file/subsystem (no dedicated script — hand-run each
time): clone to a scratch dir, git filter-repo --force --path <each current path> --path <each historical path from git log --all --follow
--name-only>, clone testsAndMisc-archive separately, add the filtered
clone as a remote, git merge --allow-unrelated-histories, remove stray
remote-tracking branches and the remote, push, verify with gh api repos/kuhyx/testsAndMisc-archive/contents/<dir>, then git rm from
testsAndMisc. Read docs/superpowers/evidence/archive-setup-hosts-guard-2026-08-18.json
or archive-plagiarism-tools-2026-08-18.json for the full worked example.
6. Testing pattern to follow (for an actual split, if one gets picked)
The established pattern for single_use/-adjacent shell scripts with no
prior test coverage (used across three prior splits):
- A
lib/tests/directory sibling to the split libs. - A
*_harness.shfile (sourced, not executed) with_t_pass/_t_fail/_t_eqhelpers,mktemp -d+trap cleanup EXIT, and PATH-shim fakes for any external tool the code shells out to. - One
test_<lib>.shper lib, sourcing the harness, asserting against real function calls (not mocks at the call-site level). - A
test_<entry-script>.shthat runs the actual entry script as a subprocess against the same fakes. If this test file threatens to grow past 250 lines, split the fixture setup into its own*_entry_harness.shearly. - Sharp edges hit and fixed across sessions, watch for all of them again:
local a="$1" b="${a}"fails underset -u— split into separatelocalstatements.- A function that calls
exit(notreturn) on a fatal condition will kill the whole test script if called directly inside anifcondition. Run it in a subshell:if (fn args); then .... - A backgrounded process needs
disownbeforekill/waitreliably affects only it. - SIGINT delivery to a backgrounded job was unreliable in this environment; SIGTERM was not.
- If a script under test computes a real resource allocation (memory, disk) from live system state, make the relevant constants env-overridable and pin them to something tiny in every test.
Check the target file for anything that shells out before assuming a prior session's fakes apply — each file is a different domain.